PPT 课件：用 Transformers 部署 Gemma 小模型
版本: v0.0.1
用途: 视频录制
时长: 约 30 分钟
难度: 小白友好
幻灯片 1：封面
标题：手把手教程：用 Transformers 部署 Gemma 小模型
副标题：从本地到云端，打造你的 AI 函数调用服务
内容：
- 讲师：[你的名字]
- 日期：2026-01-01
- 版本：v0.0.1
视觉建议：
- 背景：简洁的技术风
- 配图：Gemma 模型图标 + FastAPI logo
- 配色：蓝色系（科技感）
幻灯片 2：课程目标（1分钟）
学习目标：
- ✅ 理解 Transformers 部署原理
- ✅ 掌握 FastAPI 项目结构
- ✅ 学会 Prompt 调试技巧
- ✅ 完成从 0 到部署的全流程
学完能做什么：
- 部署自己的 AI 模型服务
- 测试 HuggingFace 海量模型
- 快速验证 AI 想法
视觉建议：
- 3 个图标：代码、部署、测试
- 每个目标配一个小图标
幻灯片 3：为什么选择这个方案？（2分钟）
问题场景：
想用 AI 做函数调用，但：
- Ollama 模型太少 ❌
- 付费 API 太贵 ❌
- 部署太复杂 ❌
我们的方案：
Transformers + FastAPI + HuggingFace Space
✅ 支持海量模型
✅ 本地免费测试
✅ 云端免费部署
✅ OpenAI 兼容
视觉建议：
- 左边：问题（红色 ❌）
- 右边：解决方案（绿色 ✅）
- 中间：箭头连接
幻灯片 4：技术栈介绍（2分钟）
核心组件：
- Transformers - 模型加载和推理
- FastAPI - Web 服务框架
- Gemma-270M - 轻量级函数调用模型
- HuggingFace Space - 免费云部署
为什么选 Gemma-270M？
- 够小：1GB，免费资源跑得动
- 够用：专门训练做函数调用
- 够快：响应时间可接受
视觉建议：
- 4 个卡片，每个组件一个
- 配对应 logo
幻灯片 5：项目结构概览（1分钟）
my_gemma_service/
├── .env # 配置文件
├── app.py # 主程序（50行）
├── utils/
│ ├── chat_request.py # 请求验证（10行）
│ ├── chat_response.py # 响应生成（50行）
│ └── model.py # 模型管理（60行）
├── requirements.txt # 依赖
├── Dockerfile # 部署用
└── my_model_cache/ # 模型缓存
总代码量：约 170 行
视觉建议：
- 树状结构图
- 用不同颜色区分文件类型
幻灯片 6：环境准备（2分钟）
安装命令：
# 1. 检查 Python
python --version # 需要 3.9+
# 2. 安装依赖
pip install fastapi uvicorn[standard] \
transformers torch accelerate \
python-dotenv python-multipart \
huggingface_hub
创建项目：
mkdir my_gemma_service
cd my_gemma_service
mkdir utils
touch .env app.py utils/__init__.py
视觉建议：
- 分步演示终端操作
- 每步配截图
幻灯片 7：配置文件（1分钟）
.env 文件：
# 模型名称，可以修改为其他模型
DEFAULT_MODEL_NAME="unsloth/functiongemma-270m-it"
为什么用 .env？
- 集中管理配置
- 方便切换模型
- 避免硬编码
视觉建议：
- 代码高亮显示
- 旁边配解释
幻灯片 8：模型管理模块（3分钟）
功能：
- 检查模型是否存在
- 下载模型
- 初始化 pipeline
代码演示：
# utils/model.py
from pathlib import Path
from transformers import pipeline, AutoTokenizer
def check_model(model_name):
cache_dir = "./my_model_cache"
model_path = Path(cache_dir) / f"models--{model_name.replace('/', '--')}"
snapshot_path = model_path / "snapshots"
if snapshot_path.exists() and any(snapshot_path.iterdir()):
return model_name, cache_dir, True
return model_name, cache_dir, False
视觉建议：
- 代码分块显示
- 用箭头标注数据流
幻灯片 9：Prompt 调试技巧（3分钟）
我的 Prompt：
写一个 Python 模块，检查 HuggingFace 模型是否已下载。
如果不存在，提示用户下载。
使用 transformers 库。
AI 第一次回复的问题：
- ❌ 没有错误处理
- ❌ 没有详细日志
- ❌ 返回值太简单
优化后的 Prompt：
改进 check_model 函数：
1. 返回 (model_name, cache_dir, success) 三元组
2. 打印详细的检查过程
3. 如果模型不存在，提示用户如何下载
4. 添加 try-catch 处理异常
视觉建议：
- 左右对比：Prompt 优化前后
- 用红色标注问题，绿色标注改进
幻灯片 10：真实调试过程（4分钟）
测试命令：
python -c "from utils.model import check_model; print(check_model('unsloth/functiongemma-270m-it'))"
第一次报错：
ImportError: No module named 'transformers'
解决：
pip install transformers
第二次报错：
FileNotFoundError: 模型不存在
解决：
# 先下载模型
curl -X POST "http://localhost:7860/download" \
-d '{"model": "unsloth/functiongemma-270m-it"}'
视觉建议：
- 终端截图展示报错
- 用红色标注错误信息
- 用绿色标注解决方案
幻灯片 11：聊天请求模块（2分钟）
功能：验证和解析请求参数
代码：
# utils/chat_request.py
from pydantic import BaseModel
from typing import List, Optional, Dict, Any
class ChatRequest(BaseModel):
model: Optional[str] = "unsloth/functiongemma-270m-it"
messages: List[Dict[str, Any]]
max_tokens: Optional[int] = None
temperature: Optional[float] = 1.0
为什么用 Pydantic？
- 自动验证参数
- 类型安全
- 自动生成文档
视觉建议：
- 代码 + 解释
- 配 Pydantic logo
幻灯片 12：聊天响应模块（4分钟）
核心挑战：处理 Gemma 的特殊返回格式
Gemma 返回格式：
{
"generated_text": [
{"role": "user", "content": "你好"},
{"role": "assistant", "content": "你好！我是助手"}
]
}
我们需要提取：
"你好！我是助手"
调试过程：
# 问题：如何提取 assistant 的内容？
# 方案1：字符串分割
content = text.split("assistant:")[-1]
# 方案2：正则表达式（更精确）
import re
content = re.search(r'assistant:\s*(.*)', text, re.DOTALL).group(1)
视觉建议：
- 数据流图：输入 → 处理 → 输出
- 用动画展示提取过程
幻灯片 13：主程序 app.py（3分钟）
三大核心：
- 全局变量：存储模型状态
- Startup 事件：自动加载模型
- 三个路由：状态、下载、聊天
代码结构：
# 全局状态
model_name = None
pipe = None
tokenizer = None
# 启动事件
@app.on_event("startup")
async def startup_event():
# 加载模型...
# 路由
@app.get("/")
@app.post("/download")
@app.post("/v1/chat/completions")
视觉建议：
- 架构图：展示组件关系
- 用虚线框标注全局变量
幻灯片 14：完整代码演示（5分钟）
分文件手写：
- .env（30秒）
- utils/model.py（1.5分钟）
- utils/chat_request.py（30秒）
- utils/chat_response.py（1.5分钟）
- app.py（1分钟）
手写原则：
- 一行一行敲
- 边敲边解释
- 遇到问题现场调试
视觉建议：
- 录屏演示：真实手写过程
- 每行代码配解释
幻灯片 15：本地测试（3分钟）
启动服务：
uvicorn app:app --host 0.0.0.0 --port 7860 --reload
测试 1：状态检查：
curl http://localhost:7860/
测试 2：函数调用：
curl -X POST "http://localhost:7860/v1/chat/completions" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "北京天气如何？"},
{"role": "system", "content": "使用 get_weather(city) 函数"}
],
"max_tokens": 100
}'
预期结果：
{
"choices": [{
"message": {
"content": "根据您的请求，我需要调用 get_weather(city='北京')"
}
}]
}
视觉建议：
- 三栏布局：命令、输出、解释
- 用箭头连接
幻灯片 16：部署到云端（2分钟）
步骤 1：准备文件：
# Dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 7860
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
步骤 2：上传代码：
git init
git add .
git commit -m "v0.0.1"
git remote add origin https://huggingface.co/spaces/你的用户名/你的Space名称
git push -u origin main
步骤 3：等待构建（5-10分钟）
视觉建议：
- 流程图：3 步走
- 配 HuggingFace Space 截图
幻灯片 17：免费资源说明（1分钟）
HuggingFace Space 免费版：
- CPU: 2核
- 内存: 16GB
- 存储: 10GB
- 休眠: 48小时无访问后休眠
Gemma-270M 需求：
- 模型大小: ~1GB
- 运行内存: ~3-4GB
- ✅ 完全够用！
视觉建议：
- 对比表格
- 用绿色 ✅ 标注够用
幻灯片 18：常见问题解答（2分钟）
Q1: 下载很慢？
export HF_ENDPOINT=https://hf-mirror.com
Q2: 内存不够？
- 换更小的模型
- 使用量化版本
- 增加 Swap
Q3: 为什么不用 Ollama？
- 模型库有限
- Transformers 支持所有模型
- 部署更灵活
Q4: 如何换模型？
# 修改 .env
DEFAULT_MODEL_NAME="其他模型名称"
# 重启服务
视觉建议：
- 问答卡片形式
- 每个问题配图标
幻灯片 19：Prompt 技巧总结（2分钟）
好的 Prompt：
✅ 具体明确
✅ 分步迭代
✅ 提供上下文
✅ 要求示例
调试技巧：
- 打印中间结果：
print()大法 - 缩小范围：单独测试函数
- 对比测试：已知正确代码
- 分步验证：改一步测一步
我的 Prompt 模板：
任务：[具体要做什么]
背景：[为什么要做]
要求：
1. [具体要求1]
2. [具体要求2]
输出格式：[代码/解释/示例]
已知问题：[如果有]
视觉建议：
- 清单形式
- 用 ✅ 标注要点
幻灯片 20：项目总结（1分钟）
我们完成了：
- ✅ 170 行代码的完整项目
- ✅ 从 0 到部署的全流程
- ✅ AI 编码的真实过程
- ✅ 调试和优化技巧
学到了什么：
- Transformers 部署原理
- FastAPI 项目结构
- Prompt 调试方法
- 云端部署流程
下一步可以：
- 测试更多模型
- 添加更多函数
- 集成到实际应用
视觉建议：
- 3 个要点，配图标
- 鼓励性结束语
幻灯片 21：Q&A（不限时）
欢迎提问：
- 代码问题
- 部署问题
- 模型选择
- 优化建议
联系方式：
- GitHub: [你的链接]
- 邮箱: [你的邮箱]
- 社区: [社区链接]
视觉建议：
- 简洁背景
- 联系方式清晰
幻灯片 22：参考资料
官方文档：
- Transformers: https://huggingface.co/docs/transformers
- FastAPI: https://fastapi.tiangolo.com
- HuggingFace Spaces: https://huggingface.co/spaces
相关资源：
- Gemma 模型: https://huggingface.co/unsloth/functiongemma-270m-it
- 本教程代码: [你的 GitHub]
视觉建议：
- 链接可点击（如果是 PDF）
- 清晰的列表
视频录制建议
时间分配（30分钟）
- 0-2分：介绍和目标
- 2-8分：环境准备和项目结构
- 8-15分：代码手写（重点）
- 15-20分：测试演示
- 20-25分：部署到云端
- 25-30分：总结和 Q&A
录制技巧
- 分段录制：每 5 分钟一段，方便剪辑
- 代码放大：确保观众能看清代码
- 语速适中：重要步骤放慢
- 互动提问：在关键点停顿，引导思考
后期剪辑
- 添加字幕
- 突出关键代码
- 添加动画效果
- 背景音乐（轻柔）
版本记录
v0.0.1 - 2026-01-01
- 初始版本
- 22 页幻灯片
- 适合 30 分钟视频
- 包含完整代码演示
下一步计划：
- v0.0.2：添加更多案例
- v0.0.3：性能优化专题
- v0.0.4：生产部署最佳实践
祝你录制顺利！🚀