提交 4ab993d9 authored 作者: zhangqianwei's avatar zhangqianwei

@张钱炜 @新增平台需求以及架构设计

上级 2d23fc4d
...@@ -27,4 +27,6 @@ logs/ ...@@ -27,4 +27,6 @@ logs/
*.zip *.zip
*.tar.gz *.tar.gz
*.pdf *.pdf
EOF # 文档网站
\ No newline at end of file /docs-site
EOF
# 蔡馥名(CFM)工作任务表
> **文档说明**:本文档基于《实习生培训教程编写任务》(V1.0) 提炼蔡馥名(CFM)的所有交付任务,作为个人执行清单与周进度跟踪表使用。
> **生成时间**:2026-07-07
> **总工期**:2 天(2026-07-07 ~ 2026-07-08)
> **最终交付截止**:7 月 8 日下班前(提交最终合并请求)
---
## 一、CFM 任务总览
### 1.1 负责模块
| 模块编号 | 模块名称 | 章节数 | 负责状态 |
| ----- | --------- | --- | ---- |
| 模块一 | Python 工程化 | 5 | 全部负责 |
| 模块六 | RAG 基础 | 5 | 全部负责 |
| 模块七 | 工程实操 | 5 | 全部负责 |
| **合计** | — | **15** | **100% 负责** |
### 1.2 交付物(必须按时产出的 3 个文档)
```
提交路径:docs/理论学习/教程/
├─ 模块一-Python工程化.md (5 个章节)
├─ 模块六-RAG基础.md (5 个章节)
└─ 模块七-工程实操.md (5 个章节)
```
### 1.3 CFM 专属核心要求(文档原文约束)
```
├─ Git 使用必须有详细的命令示例
├─ RAG 流程必须有流程图
├─ Docker 必须有完整的 Dockerfile 示例
└─ 每个工具都必须有快速上手指南
```
---
## 二、CFM 章节级任务清单(15 个章节)
### 模块一:Python 工程化(5 个章节)
#### 1.1 Git 使用(★★★★★ 必会 / 最高优先级)
| 子知识点编号 | 知识点名称 | 子知识点内容 | 状态 |
| -------- | ------------ | ------------ | -- |
| 1.1.1 | 首次配置 | user.name / user.email 配置 | 待开始 |
| 1.1.2 | 克隆项目 | git clone 命令用法 | 待开始 |
| 1.1.3 | 分支操作 | branch / switch / checkout | 待开始 |
| 1.1.4 | 同步代码 | fetch / pull / rebase | 待开始 |
| 1.1.5 | 提交代码 | add / commit / amend | 待开始 |
| 1.1.6 | 推送代码 | push / -u | 待开始 |
| 1.1.7 | 合并与冲突处理 | merge 冲突识别与解决 | 待开始 |
| 1.1.8 | 查看历史与差异 | log / diff / blame | 待开始 |
| 1.1.9 | 版本回退 | reset / revert / reflog | 待开始 |
| 1.1.10 | 暂存工作 | stash | 待开始 |
| 1.1.11 | Commit 规范与分支命名 | 提交信息规范 + 分支命名约定 | 待开始 |
**如何完成**:
```
1. 按 "什么是 Git → 举个例子 → 正解 vs 错误 → 实战代码 → 常见问题 → 验收标准 → 官方来源" 结构撰写
2. 每个子知识点必须给出可直接运行的命令示例(带输入输出)
3. 重点突出冲突处理与版本回退(这是新手最容易卡住的环节)
4. 必须包含 ASCII 示意图(如分支演进图、rebase vs merge 对比图)
```
**验收标注**:
```
□ 能独立完成 clone → branch → commit → push 完整流程
□ 能看懂并解决 merge 冲突
□ 能用 reset / revert / reflog 完成版本回退
□ 能用 stash 临时保存未完成工作
□ commit 规范符合 type(module): description 格式
```
#### 1.2 面向对象(★★★☆☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | ------------ | -- |
| 1.2.1 | 类定义与实例化 | 待开始 |
| 1.2.2 | 继承与多态 | 待开始 |
| 1.2.3 | 特殊方法 | `__init__` / `__str__` / `__len__` | 待开始 |
| 1.2.4 | 访问控制 | 公有 / 私有 / 保护 | 待开始 |
| 1.2.5 | 上下文管理器 | with 语句 | 待开始 |
| 1.2.6 | 迭代器与生成器 | iter / yield | 待开始 |
| 1.2.7 | 枚举类 | enum.Enum | 待开始 |
**如何完成**:
```
1. 每个子知识点必须给出最小可运行类示例
2. 继承与多态必须用对比示例(动物类 Dog/Cat 示例)
3. 上下文管理器推荐使用 @contextmanager 装饰器
4. 迭代器与生成器要手写一个 MyRange 例子
```
**验收标注**:
```
□ 能定义类并实例化
□ 能用继承实现多态
□ 能重写 __str__ / __len__ 等特殊方法
□ 能用 with 语句管理资源
□ 能区分迭代器和生成器的使用场景
□ 能使用 enum 定义枚举类
```
#### 1.3 装饰器(★★★☆☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | --------------- | -- |
| 1.3.1 | 装饰器基础 | @decorator 语法 | 待开始 |
| 1.3.2 | 带参数的装饰器 | 装饰器工厂 |
| 1.3.3 | functools.wraps | 保留原函数元信息 |
| 1.3.4 | 常用内置装饰器 | @property / @staticmethod |
| 1.3.5 | 装饰器执行顺序 | 多层装饰器栈 |
**如何完成**:
```
1. 从最简单的计时装饰器讲起
2. 必须展示 @wraps 的必要性(用 vs 不用对比)
3. 类装饰器(@property、@staticmethod)必须有对比示例
4. 必须画出多层装饰器包裹时函数调用顺序图
```
**验收标注**:
```
□ 能写出无参数装饰器
□ 能写出带参数装饰器
□ 能解释 @wraps 的作用
□ 能使用 @property / @staticmethod
□ 能分析多层装饰器的执行顺序
```
#### 1.4 异步编程(★★★☆☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | ------- | -- |
| 1.4.1 | async / await 语法 | 待开始 |
| 1.4.2 | asyncio 基本使用 | 待开始 |
| 1.4.3 | 常见错误 | 忘记 await 时的报错现象 | 待开始 |
| 1.4.4 | 异步 vs 同步对比 | 时长对比示例 | 待开始 |
**如何完成**:
```
1. 必须有可对比运行的同步 vs 异步代码
2. 必须展示 "忘记 await" 的 RuntimeWarning 报错截图或粘贴错误信息
3. asyncio.sleep vs time.sleep 必须做对比
```
**验收标注**:
```
□ 能写出 async def 函数
□ 能用 asyncio.run 执行协程
□ 能识别忘记 await 的报错
□ 能用 asyncio.gather 并发执行任务
```
#### 1.5 Python 代码规范(★★★☆☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | -------- | -- |
| 1.5.1 | PEP8 规范要点 | 待开始 |
| 1.5.2 | 类型注解 | type hints | 待开始 |
| 1.5.3 | 虚拟环境 | venv / conda | 待开始 |
| 1.5.4 | 包结构规范 | 模块组织 | 待开始 |
**如何完成**:
```
1. PEP8 必须列出最常用的 10 条规则(命名、缩进、行长、import 顺序等)
2. 类型注解必须给出 List/Dict/Optional/Union 等常用示例
3. 虚拟环境必须给出 venv 和 conda 两套命令对比
4. 包结构展示标准项目布局(src/、tests/、pyproject.toml)
```
**验收标注**:
```
□ 能用 black/flake8 格式化代码
□ 能为函数添加完整类型注解
□ 能创建并激活 venv
□ 能搭建符合规范的项目结构
```
---
### 模块六:RAG 基础(5 个章节)
#### 6.1 RAG 原理(★★★★☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | ------- | -- |
| 6.1.1 | 为什么需要 RAG | 待开始 |
| 6.1.2 | RAG 完整流程 | 待开始 |
| 6.1.3 | RAG vs Fine-tuning | 待开始 |
| 6.1.4 | RAG 应用场景 | 待开始 |
**如何完成**:
```
1. 必须画出 RAG 完整流程图(文档加载 → 分块 → Embedding → 向量库 → 检索 → 生成)
2. 用 "闭卷考试 vs 开卷考试" 类比 LLM 单独回答 vs RAG
3. RAG vs Fine-tuning 必须用对比表展示(成本、时效、可解释性等维度)
```
**验收标注**:
```
□ 能画出 RAG 完整流程图
□ 能解释每一步的作用
□ 能说出 RAG 与微调的适用场景差异
```
#### 6.2 文档处理(★★★★☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | ---------- | -- |
| 6.2.1 | PDF 解析 | pdfplumber | 待开始 |
| 6.2.2 | Word 解析 | python-docx | 待开始 |
| 6.2.3 | 文本清洗 | 去噪 / 标准化 | 待开始 |
| 6.2.4 | 表格提取 | 跨页表格合并 | 待开始 |
| 6.2.5 | 元数据管理 | filename / page / source | 待开始 |
**如何完成**:
```
1. 必须有完整可运行的 PDF 解析示例(含中文 PDF)
2. 必须给出 OCR 场景的处理方案(当 pdfplumber 抽不出文字时)
3. 文本清洗要有规则示例(去除页眉页脚、合并换行等)
```
**验收标注**:
```
□ 能用 pdfplumber 提取 PDF 文本(含表格)
□ 能用 python-docx 提取 Word 内容
□ 能清洗文本中的页眉页脚噪声
□ 能为分块后的文本附加完整元数据
```
#### 6.3 文本分块(★★★★☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | --------- | -- |
| 6.3.1 | 固定长度分块 | 待开始 |
| 6.3.2 | 递归字符分块 | 待开始 |
| 6.3.3 | 语义分块 | 待开始 |
| 6.3.4 | 分块大小配置 | 待开始 |
**如何完成**:
```
1. 必须对比 3 种分块方式的优缺点(表格展示)
2. 必须给出 LangChain 的 RecursiveCharacterTextSplitter 使用示例
3. 必须包含 chunk_size / chunk_overlap 调参建议
```
**验收标注**:
```
□ 能写出 3 种分块方法的可运行代码
□ 能解释为什么通常选择递归字符分块作为默认方案
□ 能合理设置 chunk_size 和 overlap
```
#### 6.4 Embedding(★★★★☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | ----- | -- |
| 6.4.1 | Embedding 原理 | 待开始 |
| 6.4.2 | 常用模型 | BGE / M3E | 待开始 |
| 6.4.3 | API 调用 | 待开始 |
| 6.4.4 | 批量向量化 | 待开始 |
**如何完成**:
```
1. 必须用 "把句子变成坐标点" 类比 Embedding
2. 必须展示 cosine similarity 计算代码
3. API 调用必须对比 OpenAI text-embedding 与开源 BGE 两套方案
```
**验收标注**:
```
□ 能解释 Embedding 的含义
□ 能调用 BGE/M3E 模型得到向量
□ 能计算两个句子的相似度
□ 能用批量接口处理 1000+ 文本
```
#### 6.5 向量数据库(★★★★☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | ------ | -- |
| 6.5.1 | Chroma 快速上手 | 待开始 |
| 6.5.2 | Collection 管理 | 待开始 |
| 6.5.3 | CRUD 操作 | 待开始 |
| 6.5.4 | 检索原理 | 待开始 |
**如何完成**:
```
1. 必须给出从安装到查询的最小完整示例(约 15 行代码)
2. CRUD 必须覆盖 add / get / update / delete
3. 必须对比相似度检索(similarity_search)和 MMR 检索
```
**验收标注**:
```
□ 能本地启动 Chroma 并完成增删改查
□ 能用 similarity_search 完成检索
□ 能设置 metadata 过滤条件
□ 能解释 HNSW 等近似最近邻算法原理
```
---
### 模块七:工程实操(5 个章节)
#### 7.1 FastAPI(★★★★☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | ---------- | -- |
| 7.1.1 | FastAPI vs Flask | 待开始 |
| 7.1.2 | 路由定义 | @app.get / @app.post | 待开始 |
| 7.1.3 | 请求体 | Pydantic 模型 | 待开始 |
| 7.1.4 | 响应模型 | response_model | 待开始 |
| 7.1.5 | 依赖注入 | Depends | 待开始 |
| 7.1.6 | 中间件 | 自定义中间件 | 待开始 |
| 7.1.7 | 异步路由 | async def | 待开始 |
| 7.1.8 | 自动文档 | /docs / Swagger | 待开始 |
**如何完成**:
```
1. 必须有完整的最小可运行 API(包含启动、访问、关闭)
2. 必须展示 Swagger 文档自动生成效果
3. Pydantic 模型必须展示字段验证失败的 422 错误
4. 异步路由必须与同步路由做性能对比
```
**验收标注**:
```
□ 能用 FastAPI 启动一个完整服务
□ 能定义 Pydantic 请求体并验证
□ 能用 Depends 实现依赖注入
□ 能自定义中间件处理跨域/日志
□ 能访问 /docs 查看自动生成的 API 文档
```
#### 7.2 PostgreSQL(★★★★☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | -------------- | -- |
| 7.2.1 | 基本命令 | psql 登录 | 待开始 |
| 7.2.2 | 表创建与数据类型 | SERIAL / VARCHAR / JSONB | 待开始 |
| 7.2.3 | 增删改查 | INSERT / SELECT / UPDATE / DELETE | 待开始 |
| 7.2.4 | 索引与优化 | B-Tree / 复合索引 / EXPLAIN | 待开始 |
| 7.2.5 | Python 连接 | psycopg2 | 待开始 |
| 7.2.6 | SQLAlchemy ORM | 关系映射 / 查询 | 待开始 |
**如何完成**:
```
1. 必须从 psql 命令行开始,再切到 SQLAlchemy ORM
2. 索引部分必须给出 EXPLAIN ANALYZE 前后对比
3. SQLAlchemy 必须展示一对一、一对多、多对多三种关系
```
**验收标注**:
```
□ 能在 psql 中完成 CRUD
□ 能用 psycopg2 在 Python 中执行 SQL
□ 能用 SQLAlchemy ORM 定义模型
□ 能为高频查询字段建立索引
□ 能用 EXPLAIN 分析慢查询
```
#### 7.3 Redis(★★★☆☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | --------- | -- |
| 7.3.1 | 基本数据类型 | String / Hash / List / Set / ZSet | 待开始 |
| 7.3.2 | 常用命令 | GET / SET / HGETALL / LPUSH 等 | 待开始 |
| 7.3.3 | 缓存策略 | Cache-Aside / Write-Through | 待开始 |
| 7.3.4 | Python 客户端 | redis-py | 待开始 |
| 7.3.5 | 分布式锁 | SETNX / Redlock | 待开始 |
**如何完成**:
```
1. 必须给出每种数据类型的最小示例(1 行命令)
2. 缓存策略用 "字典 vs 图书馆" 类比 Cache-Aside
3. 分布式锁必须给出 SETNX + EXPIRE 双命令的坑(需用 Lua)
```
**验收标注**:
```
□ 能区分 5 种数据类型的适用场景
□ 能用 redis-py 完成基本操作
□ 能用 Cache-Aside 模式优化读多写少业务
□ 能正确实现基于 Redis 的分布式锁
```
#### 7.4 Docker(★★★★☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | -------- | -- |
| 7.4.1 | Docker 概念 | 镜像 / 容器 / 仓库 | 待开始 |
| 7.4.2 | Dockerfile 编写 | FROM / RUN / COPY / CMD | 待开始 |
| 7.4.3 | 常用指令 | build / run / exec / logs | 待开始 |
| 7.4.4 | Docker Compose | docker-compose.yml | 待开始 |
| 7.4.5 | 容器操作 | 启停 / 进入 / 文件拷贝 | 待开始 |
| 7.4.6 | GPU 支持 | nvidia-container-toolkit | 待开始 |
**如何完成**:
```
1. 必须有完整可运行的 Dockerfile 示例(Python Web 服务打包)
2. docker-compose 必须给出 3 个服务编排(web + db + redis)
3. GPU 支持部分必须给出 nvidia-smi 在容器内的验证命令
4. 必须有镜像分层优化的多阶段构建示例
```
**验收标注**:
```
□ 能编写多阶段构建的 Dockerfile
□ 能用 docker-compose 启动多容器
□ 能进入容器调试(docker exec -it)
□ 能让容器访问宿主 GPU
```
#### 7.5 pytest(★★★☆☆)
| 子知识点编号 | 知识点名称 | 状态 |
| ------- | ------- | -- |
| 7.5.1 | pytest 基础 | 待开始 |
| 7.5.2 | 断言 | assert | 待开始 |
| 7.5.3 | Fixture | 待开始 |
| 7.5.4 | 参数化测试 | @pytest.mark.parametrize | 待开始 |
| 7.5.5 | Mock | unittest.mock | 待开始 |
**如何完成**:
```
1. 必须从最简单的 test_*.py 命名讲起
2. Fixture 必须展示 scope="function/module/session" 三种作用域
3. Mock 必须给出 "模拟外部 API" 的实战场景
```
**验收标注**:
```
□ 能用 pytest 编写基本测试用例
□ 能用 Fixture 复用测试资源
□ 能用 parametrize 减少重复代码
□ 能用 Mock 模拟外部依赖
```
---
## 三、CFM 全局要求(写作质量标准)
### 3.1 每个知识点的标准结构(强制)
```
### X.X 知识点名称
> 用 1-2 句话说清:这个知识点解决什么问题。
---
## 什么是这个知识点?
(含:1. 一句话定义 2. 为什么重要 3. 生活类比)
## 举个例子
(含:1. 输入是什么 2. 输出是什么 3. 代码演示)
## 正解 vs 错误
(含:1. 正确做法 2. 常见错误 3. 错误表现)
## 原理深入(可选)
(含:1. 核心逻辑 2. 数学推导 3. 流程图/ASCII 图)
## 实战代码
(可直接运行的最小示例)
## 常见问题
Q&A 形式
## 验收标准
checklist 形式
## 官方来源
- 链接
## 参考文献
[1] xxx
```
### 3.2 生动性 10 技巧(建议贯穿全文)
| 编号 | 技巧 | 在 CFM 章节中的重点应用 |
| -- | ------------- | --------------------------------------------- |
| 1 | 对比展示 | Git 命令正反对比、FastAPI vs Flask、Redis 数据类型对比 |
| 2 | 生活类比 | RAG ↔ 开卷考试、Embedding ↔ 坐标点 |
| 3 | 具体输入输出 | 每段 Git 命令必须给输入输出 |
| 4 | 代码可直接运行 | 所有 Python 代码、Dockerfile、SQL 必须可运行 |
| 5 | 错误案例分析 | "忘记 await"、merge 冲突、约束冲突 |
| 6 | 竖线分隔展示 | 正解 vs 错误表格 |
| 7 | 流程图/步骤分解 | RAG 流程、Docker 构建步骤 |
| 8 | ASCII 示意图 | Git 分支演进图、RAG pipeline |
| 9 | 时间/字数预估 | ⏱️ 5 分钟 / 📖 1500 字 |
| 10 | 参考文献引用 | 官方文档链接 + 经典博客 |
### 3.3 合格标准(最低线)
```
□ 有通俗易懂的概念解释(不是照抄官方文档)
□ 有具体可运行的代码示例
□ 有正确 vs 错误的对比
□ 有常见问题 Q&A
□ 有可验收的标准
□ 有官方来源链接
```
---
## 四、CFM 每日执行计划
### 第一天(2026-07-07,周二)
#### 上午优先级(最高)
| 优先级 | 章节 | 难度 | 预计耗时 |
| ------ | -------------------- | ----- | ---- |
| ⭐⭐⭐⭐⭐ | 【1.1】Git 使用 | ★★★★★ | 3h |
| ⭐⭐⭐⭐ | 【6.1】RAG 原理 | ★★★★☆ | 1.5h |
#### 下午
| 优先级 | 章节 | 难度 | 预计耗时 |
| ------ | -------------- | ----- | ---- |
| ⭐⭐⭐⭐ | 【6.2】文档处理 | ★★★★☆ | 1.5h |
| ⭐⭐⭐⭐ | 【6.3】文本分块 | ★★★★☆ | 1h |
| ⭐⭐⭐⭐ | 【6.4】Embedding | ★★★★☆ | 1h |
**当天交付物检查**:
```
□ 1.1 Git 使用(11 个子知识点全部完成)
□ 6.1 RAG 原理(含流程图)
□ 6.2 文档处理(含 pdfplumber/python-docx 可运行示例)
□ 6.3 文本分块(3 种分块方法对比表)
□ 6.4 Embedding(API + BGE 双方案)
```
### 第二天(2026-07-08,周三)
#### 上午
| 优先级 | 章节 | 难度 | 预计耗时 |
| ----- | --------------- | ----- | ---- |
| ⭐⭐⭐⭐ | 【6.5】向量数据库 | ★★★★☆ | 1.5h |
| ⭐⭐⭐⭐ | 【7.1】FastAPI | ★★★★☆ | 2h |
| ⭐⭐⭐⭐ | 【7.2】PostgreSQL | ★★★★☆ | 2h |
#### 下午
| 优先级 | 章节 | 难度 | 预计耗时 |
| ----- | --------------- | ----- | ---- |
| ⭐⭐⭐⭐ | 【7.4】Docker | ★★★★☆ | 2h |
| ⭐⭐ | 【1.2】面向对象 | ★★★☆☆ | 1h |
| ⭐⭐ | 【1.3】装饰器 | ★★★☆☆ | 1h |
| ⭐⭐ | 【1.4】异步编程 | ★★★☆☆ | 0.5h |
| ⭐⭐ | 【1.5】Python 代码规范 | ★★★☆☆ | 0.5h |
| ⭐⭐ | 【7.3】Redis | ★★★☆☆ | 1h |
| ⭐⭐ | 【7.5】pytest | ★★★☆☆ | 1h |
**当天交付物检查**:
```
□ 完成模块六全部 5 章 + 模块七全部 5 章 + 模块一剩余 4 章
□ 格式统一(标题层级、代码块语言标注、表格 Markdown 化、链接可访问)
□ 最终合并请求提交
```
---
## 五、Git 提交规范(CFM 专属示例)
> ⚠️ **每个小节完成后立即提交,不要等全部完成再提交!**
### 提交格式
```
type(module): description
```
### CFM 应使用的示例
```
feat(module1): 完成 1.1 Git 使用 11 个子知识点
feat(module6): 完成 RAG 完整流程图与原理章节
feat(module6): 完成 6.2 PDF/Word 文档处理示例
feat(module6): 完成 6.3 三种文本分块对比
feat(module6): 完成 6.4 Embedding 双方案(BGE + OpenAI)
feat(module6): 完成 6.5 Chroma 向量库 CRUD
feat(module7): 完成 7.1 FastAPI 完整示例
feat(module7): 完成 7.2 PostgreSQL 与 SQLAlchemy ORM
feat(module7): 完成 7.4 Docker 多阶段构建示例
feat(module1): 完成面向对象章节 1.2
feat(module1): 完成装饰器章节 1.3(含 @wraps 对比)
feat(module1): 完成异步编程章节 1.4
feat(module1): 完成 Python 代码规范章节 1.5
feat(module7): 完成 Redis 章节 7.3
feat(module7): 完成 pytest 章节 7.5
docs(module1): 统一 Python 工程化章节格式
docs(module6): 完善 RAG 基础章节 Q&A
docs(module7): 补充工程实操常见问题
fix(module7): 修复 Dockerfile 多阶段构建示例错误
style(module6): 统一 Embedding 示例代码格式
```
### 提交要求
```
├─ 每次完成一个小节提交一次(不要等到最后一次性提交)
├─ 提交信息要清晰描述改动
└─ 单次提交尽量保持原子性(一个章节 = 一次提交)
```
---
## 六、CFM 验收检查清单(合并请求前自查)
### 6.1 内容完整性(必须全部 ☐ → ☑)
**模块一:Python 工程化(5/5)**
```
☐ 1.1 Git 使用(11 子知识点全部完成)
☐ 1.2 面向对象(7 子知识点全部完成)
☐ 1.3 装饰器(5 子知识点全部完成)
☐ 1.4 异步编程(4 子知识点全部完成)
☐ 1.5 Python 代码规范(4 子知识点全部完成)
```
**模块六:RAG 基础(5/5)**
```
☐ 6.1 RAG 原理(含完整流程图)
☐ 6.2 文档处理(pdfplumber + python-docx 双示例)
☐ 6.3 文本分块(3 种方法对比)
☐ 6.4 Embedding(BGE + OpenAI 双方案)
☐ 6.5 向量数据库(Chroma CRUD + 检索)
```
**模块七:工程实操(5/5)**
```
☐ 7.1 FastAPI(含 Pydantic、Depends、中间件、自动文档)
☐ 7.2 PostgreSQL(psql + SQLAlchemy 双示例)
☐ 7.3 Redis(5 种数据类型 + 分布式锁)
☐ 7.4 Docker(Dockerfile + docker-compose + GPU)
☐ 7.5 pytest(Fixture + parametrize + Mock)
```
### 6.2 格式统一(强制)
```
☐ 使用统一的标题层级(# / ## / ###)
☐ 代码块必须有语言标注(```python / ```bash / ```yaml)
☐ 表格必须使用 Markdown 格式
☐ 所有链接可访问(无 404)
☐ 标题无错别字
```
### 6.3 内容质量(每章必须包含)
```
☐ 什么是这个知识点(通俗解释)
☐ 举个例子(具体示例)
☐ 正解 vs 错误(对比展示)
☐ 实战代码(可运行)
☐ 常见问题 Q&A
☐ 验收标准
☐ 官方来源
```
### 6.4 CFM 专属硬性要求
```
☐ Git 使用:包含详细命令示例(每个子知识点 ≥ 3 个命令)
☐ RAG 流程:必须包含 ASCII 流程图
☐ Docker:包含完整可运行 Dockerfile 示例
☐ 每个工具(FastAPI/PostgreSQL/Redis/Docker/pytest):都有"5 分钟快速上手"小节
```
### 6.5 代码质量
```
☐ 所有 Python 代码片段在本地测试通过
☐ 所有 Dockerfile 可成功 build 出镜像
☐ 所有 docker-compose 可成功 up
☐ 所有 SQL 可在 PostgreSQL 中执行成功
☐ 所有 Git 命令在实际仓库中测试通过
```
---
## 七、风险与应对
### 7.1 时间紧张(2 天完成 15 章)
**应对**:
```
1. 严格按子知识点并行/串行处理,每完成一个子知识点就勾选
2. 优先完成优先级最高(★5)的章节:1.1 Git、1.1 子知识点(11 个)
3. ★3 的章节(1.2-1.5、7.3、7.5)可以写得相对精简,但结构必须完整
4. 遇到难点卡壳超过 30 分钟 → 先标记 TODO,跳过继续推进
```
### 7.2 代码测试耗时
**应对**:
```
1. 代码片段尽量采用最小可运行原则(不超过 30 行)
2. 复用现有可运行环境(已部署的 multimodal_service 项目仓库)
3. 实在跑不通的代码在文末注明 "本节代码需 PyTorch X.X / Python X.X 环境"
```
### 7.3 Git 提交规范漏掉
**应对**:
```
1. 第一次提交前先确认远程仓库的 main 分支保护规则
2. 每完成 1 个子知识点立刻 stage + commit
3. 每天下班前 review 一次 git log
```
---
## 八、CFM 协作约定
### 8.1 与其他成员的边界
```
├─ 不修改模块二(李佳洋负责:PyTorch 基础)
├─ 不修改模块三(张钱炜负责:深度学习基础)
├─ 不修改模块四(张钱炜负责:Transformer 原理)
├─ 不修改模块五(李佳洋负责:LLM + API 调用)
└─ 严格负责 模块一 / 模块六 / 模块七 全部内容
```
### 8.2 文件命名(提交前再次确认)
```
docs/理论学习/教程/
├─ 模块一-Python工程化.md ← CFM 负责
├─ 模块二-PyTorch基础.md ← 李佳洋负责(不要碰)
├─ 模块三-深度学习基础.md ← 张钱炜负责(不要碰)
├─ 模块四-Transformer原理.md ← 张钱炜负责(不要碰)
├─ 模块五-LLM-API调用.md ← 李佳洋负责(不要碰)
├─ 模块六-RAG基础.md ← CFM 负责
└─ 模块七-工程实操.md ← CFM 负责
```
### 8.3 统一术语参考
```
├─ LLM(大语言模型)
├─ RAG(检索增强生成)
├─ Embedding(向量化)
├─ Fine-tuning(微调)
├─ ORM(对象关系映射)
├─ CRUD(增删改查)
└─ 所有英文术语首次出现时必须括号标注中文
```
---
## 九、附录:CFM 文档写作模板(直接复制使用)
### 9.1 单个知识点模板
```markdown
### X.X 知识点名称
> 用 1-2 句话说清:这个知识点解决什么问题。
---
## 什么是这个知识点?
(用通俗语言解释)
- **一句话定义**:xxxx
- **为什么重要**:xxxx
- **生活类比**:xxxx
## 举个例子
**输入**:xxx
**输出**:xxx
**代码**:
```python
# 最小可运行示例
```
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| -- | ----- | ----- |
| 写法 | xxx | xxx |
| 表现 | xxx | xxx |
**错误报错**:
```
RuntimeError: ...
```
**解决方法**:xxx
## 原理深入(可选)
(底层原理 / 流程图 / 数学推导)
```
[输入] → [处理] → [输出]
```
## 实战代码
完整可运行的代码块(带注释、输入输出示例)。
## 常见问题
**Q: 常见问题 1?**
A: 回答
**Q: 常见问题 2?**
A: 回答
## 验收标准
```
☐ 能独立写出 xxx 代码
☐ 能解释 xxx 原理
☐ 能处理 xxx 错误
```
## 官方来源
- https://xxx
## 参考文献
[1] xxx
```
---
## 十、签收与状态跟踪
| 项目 | 状态 | 备注 |
| -------- | ---------- | ------------- |
| 文档接收 | ✅ 2026-07-07 | 阅读完成 |
| 模块一启动 | ☐ 待开始 | 第一天上午 |
| 模块六启动 | ☐ 待开始 | 第一天上午 |
| 模块七启动 | ☐ 待开始 | 第二天上午 |
| 中期检查点 | ☐ 待到 | 第一天下班前完成自检 |
| 最终交付 | ☐ 待到 | 7/8 下班前提交合并请求 |
---
> **最后提醒**:所有 15 个章节 + 3 个交付文档,必须在 **2026-07-08 17:00 前** 完成并提交最终合并请求。
> 文档完成度 = (已勾选验收标注的章节数) / 15,越多越好。
# 今日任务规划 (2026-07-13 周一)
> **规划说明**:本文档为今日工作任务分解与执行指南,所有 AI 相关服务代码统一存放于 `ai-service/` 目录。
---
## 一、任务总览
| 序号 | 任务名称 | 优先级 | 预计耗时 | 产出物位置 |
| --- | ------- | ------ | -------- | --------- |
| 1 | RBAC / 项目 / 状态机接口契约评审 | ⭐⭐⭐⭐⭐ | 2h | `cfm_docs/接口契约评审/` |
| 2 | Milvus 单机环境 + 接入测试 | ⭐⭐⭐⭐⭐ | 2.5h | `ai-service/milvus/` |
| 3 | LLM 统一 Client | ⭐⭐⭐⭐ | 2h | `ai-service/llm-client/` |
| 4 | GitHub Token 池化协助 | ⭐⭐⭐ | 1.5h | `ai-service/github-pool/` |
| 5 | Docker / GPU 调度 PoC | ⭐⭐⭐⭐ | 2.5h | `ai-service/gpu-scheduler/` |
**总耗时**:约 10.5 小时,建议分上午/下午两个阶段完成
---
## 二、任务详细分解
### 任务 1:RBAC / 项目 / 状态机接口契约评审
**任务目标**:评审现有系统的权限控制、项目管理和状态流转接口设计
#### 1.1 评审范围
```
评审内容:
├─ RBAC 权限模型
│ ├─ 用户-角色-权限 三角关系
│ ├─ 角色继承与互斥
│ ├─ 权限粒度控制
│ └─ 接口鉴权流程
│
├─ 项目管理接口
│ ├─ 项目 CRUD 接口设计
│ ├─ 项目成员管理
│ └─ 项目资源配置
│
└─ 状态机接口
├─ 状态定义与转换规则
├─ 事件触发机制
├─ 状态持久化策略
└─ 并发状态修改处理
```
#### 1.2 评审检查清单
```markdown
□ 接口是否符合 RESTful 规范
□ 请求/响应数据结构是否完整
□ 错误码定义是否统一
□ 鉴权与授权流程是否清晰
□ 状态转换是否有前置条件校验
□ 并发控制是否有死锁风险
□ 日志记录是否完整
□ 接口文档是否与实现一致
```
#### 1.3 产出物
- 路径:`cfm_docs/接口契约评审/`
- 文件:
- `RBAC接口评审报告.md`
- `项目接口评审报告.md`
- `状态机接口评审报告.md`
- `评审问题汇总.md`
#### 1.4 时间安排
- 时段:上午 09:00 - 11:00
- 建议:先快速过一遍现有接口文档,标记问题点,再深入评审
---
### 任务 2:Milvus 单机环境 + 接入测试
**任务目标**:搭建 Milvus 向量数据库单机环境并完成 Python SDK 接入测试
#### 2.1 环境准备
```bash
# 1. 创建项目目录
mkdir -p ai-service/milvus
# 2. Milvus 单机部署(Docker Compose)
cat > ai-service/milvus/docker-compose.yml << 'EOF'
version: '3.8'
services:
etcd:
container_name: milvus-etcd
image: quay.io/coreos/etcd:v3.5.5
environment:
- ETCD_AUTO_COMPACTION_MODE=revision
- ETCD_AUTO_COMPACTION_RETENTION=1000
- ETCD_QUOTA_BACKEND_BYTES=4294967296
- ETCD_SNAPSHOT_COUNT=50000
volumes:
- etcd_data:/etcd
command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
minio:
container_name: milvus-minio
image: minio/minio:RELEASE.2023-03-20T20-16-18Z
environment:
MINIO_ACCESS_KEY: minioadmin
MINIO_SECRET_KEY: minioadmin
volumes:
- minio_data:/minio_data
command: minio server /minio_data
milvus:
container_name: milvus-standalone
image: milvusdb/milvus:v2.3.3
command: ["milvus", "run", "standalone"]
environment:
ETCD_ENDPOINTS: etcd:2379
MINIO_ADDRESS: minio:9000
volumes:
- milvus_data:/var/lib/milvus
ports:
- "19530:19530"
- "9091:9091"
volumes:
etcd_data:
minio_data:
milvus_data:
EOF
```
#### 2.2 Python SDK 接入代码
```python
# ai-service/milvus/client.py
from pymilvus import connections, Collection, FieldSchema, CollectionSchema, DataType, utility
class MilvusClient:
def __init__(self, host="localhost", port="19530"):
connections.connect(alias="default", host=host, port=port)
def create_collection(self, name, dim=768):
fields = [
FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=True),
FieldSchema(name="embedding", dtype=DataType.FLOAT_VECTOR, dim=dim),
FieldSchema(name="text", dtype=DataType.VARCHAR, max_length=65535),
]
schema = CollectionSchema(fields, description="Vector collection")
Collection(name, schema)
def insert(self, collection_name, embeddings, texts):
collection = Collection(collection_name)
data = [embeddings, texts]
result = collection.insert(data)
collection.flush()
return result
def search(self, collection_name, query_embedding, top_k=10):
collection = Collection(collection_name)
collection.load()
search_params = {"metric_type": "L2", "params": {"nprobe": 10}}
results = collection.search(
data=[query_embedding],
anns_field="embedding",
param=search_params,
limit=top_k
)
return results
def close(self):
connections.disconnect("default")
```
#### 2.3 测试用例
```python
# ai-service/milvus/test_client.py
import pytest
from client import MilvusClient
import numpy as np
def test_connection():
client = MilvusClient()
assert client is not None
client.close()
def test_create_and_insert():
client = MilvusClient()
client.create_collection("test_collection", dim=128)
embeddings = np.random.rand(10, 128).astype(np.float32).tolist()
texts = [f"text_{i}" for i in range(10)]
result = client.insert("test_collection", embeddings, texts)
assert result.insert_count == 10
client.close()
def test_search():
client = MilvusClient()
query = np.random.rand(128).astype(np.float32).tolist()
results = client.search("test_collection", query, top_k=3)
assert len(results[0]) <= 3
client.close()
```
#### 2.4 产出物
- 路径:`ai-service/milvus/`
- 文件:
- `docker-compose.yml` - Milvus 部署配置
- `client.py` - Python SDK 封装
- `test_client.py` - 单元测试
- `README.md` - 快速上手指南
- `测试报告.md` - 接入测试结果
#### 2.5 时间安排
- 时段:上午 11:00 - 13:00(含午休调整)
- 建议:docker-compose up 后台运行,同步编写 Python SDK 代码
---
### 任务 3:LLM 统一 Client
**任务目标**:封装统一的 LLM 调用客户端,支持多后端(OpenAI / Claude / 本地模型)
#### 3.1 架构设计
```
ai-service/llm-client/
├─ base.py # 基类定义
├─ openai_client.py # OpenAI 适配器
├─ anthropic_client.py # Claude 适配器
├─ local_client.py # 本地模型适配器(vLLM/Ollama)
├─ unified.py # 统一入口
├─ config.py # 配置管理
├─ exceptions.py # 自定义异常
└─ __init__.py
```
#### 3.2 核心代码
```python
# ai-service/llm-client/base.py
from abc import ABC, abstractmethod
from typing import List, Dict, Optional, Generator
class BaseLLMClient(ABC):
@abstractmethod
def chat(self, messages: List[Dict], **kwargs) -> str:
"""同步对话"""
pass
@abstractmethod
def stream_chat(self, messages: List[Dict], **kwargs) -> Generator[str, None, None]:
"""流式对话"""
pass
@abstractmethod
def embeddings(self, texts: List[str]) -> List[List[float]]:
"""文本向量化"""
pass
```
```python
# ai-service/llm-client/unified.py
from enum import Enum
from typing import List, Dict, Optional
from .openai_client import OpenAIClient
from .anthropic_client import AnthropicClient
from .local_client import LocalClient
class LLMProvider(Enum):
OPENAI = "openai"
ANTHROPIC = "anthropic"
LOCAL = "local"
class UnifiedLLMClient:
def __init__(self, provider: LLMProvider, **config):
self.provider = provider
self.client = self._create_client(provider, **config)
def _create_client(self, provider, **config):
clients = {
LLMProvider.OPENAI: OpenAIClient,
LLMProvider.ANTHROPIC: AnthropicClient,
LLMProvider.LOCAL: LocalClient,
}
return clients[provider](**config)
def chat(self, messages: List[Dict], **kwargs) -> str:
return self.client.chat(messages, **kwargs)
def stream_chat(self, messages: List[Dict], **kwargs):
return self.client.stream_chat(messages, **kwargs)
def embeddings(self, texts: List[str]) -> List[List[float]]:
return self.client.embeddings(texts)
@staticmethod
def from_config(config: Dict):
provider = LLMProvider(config.get("provider", "openai"))
return UnifiedLLMClient(provider, **config.get("config", {}))
```
#### 3.3 配置文件示例
```yaml
# ai-service/llm-client/config.yaml
providers:
openai:
provider: openai
config:
api_key: ${OPENAI_API_KEY}
model: gpt-4-turbo
base_url: https://api.openai.com/v1
timeout: 60
anthropic:
provider: anthropic
config:
api_key: ${ANTHROPIC_API_KEY}
model: claude-3-opus-20240229
max_tokens: 4096
local:
provider: local
config:
base_url: http://localhost:8000/v1
model: qwen2-7b
api_key: dummy
```
#### 3.4 使用示例
```python
from unified import UnifiedLLMClient, LLMProvider
# 方式一:直接指定 provider
client = UnifiedLLMClient(LLMProvider.OPENAI, api_key="sk-xxx")
messages = [
{"role": "system", "content": "你是专业助手"},
{"role": "user", "content": "你好,介绍一下自己"}
]
# 同步调用
response = client.chat(messages)
print(response)
# 流式调用
for chunk in client.stream_chat(messages):
print(chunk, end="", flush=True)
# 方式二:从配置文件加载
client = UnifiedLLMClient.from_config(yaml.safe_load(open("config.yaml"))["providers"]["openai"])
```
#### 3.5 产出物
- 路径:`ai-service/llm-client/`
- 文件:
- `base.py` - 抽象基类
- `openai_client.py` - OpenAI 实现
- `anthropic_client.py` - Claude 实现
- `local_client.py` - 本地模型实现
- `unified.py` - 统一入口
- `config.py` / `config.yaml` - 配置管理
- `exceptions.py` - 异常定义
- `README.md` - 使用文档
- `requirements.txt` - 依赖
#### 3.6 时间安排
- 时段:下午 14:00 - 16:00
- 建议:先实现 OpenAI 适配器作为参考,其他适配器可复用结构
---
### 任务 4:GitHub Token 池化协助
**任务目标**:设计并实现 GitHub Token 池化系统,提高 API 调用并发能力
#### 4.1 架构设计
```
ai-service/github-pool/
├─ pool.py # Token 池核心
├─ rate_limiter.py # 限流控制
├─ strategies.py # 调度策略
├─ monitor.py # 健康监控
├─ exceptions.py # 异常定义
├─ config.py # 配置
└─ __init__.py
```
#### 4.2 核心代码
```python
# ai-service/github-pool/pool.py
import asyncio
import time
from typing import List, Optional, Callable
from dataclasses import dataclass
from .rate_limiter import RateLimiter
from .strategies import RoundRobinStrategy
@dataclass
class Token:
key: str
remaining: int
reset_at: float
is_active: bool = True
class GitHubTokenPool:
def __init__(self, tokens: List[str], strategy: str = "round_robin"):
self.tokens = [Token(key=t, remaining=5000, reset_at=0) for t in tokens]
self.rate_limiter = RateLimiter(5000, 3600) # 5000 req/hour
self.strategy = RoundRobinStrategy() if strategy == "round_robin" else None
self._lock = asyncio.Lock()
async def get_token(self) -> Optional[Token]:
async with self._lock:
available = [t for t in self.tokens if t.is_active and t.remaining > 0]
if not available:
return None
return self.strategy.select(available)
async def release_token(self, token: Token, used: int = 1):
token.remaining = max(0, token.remaining - used)
if token.remaining <= 0:
token.is_active = False
asyncio.create_task(self._refresh_token(token))
async def _refresh_token(self, token: Token):
await asyncio.sleep(3600) # 等到 rate limit 重置
token.remaining = 5000
token.is_active = True
async def execute(self, func: Callable, *args, **kwargs):
token = await self.get_token()
if not token:
raise Exception("No available tokens")
try:
result = await func(*args, **kwargs, token=token.key)
await self.release_token(token)
return result
except Exception as e:
await self.release_token(token, used=0)
raise
```
#### 4.3 调度策略
```python
# ai-service/github-pool/strategies.py
from abc import ABC, abstractmethod
from typing import List
import random
class SelectionStrategy(ABC):
@abstractmethod
def select(self, tokens: List) -> any:
pass
class RoundRobinStrategy(SelectionStrategy):
def __init__(self):
self._index = 0
def select(self, tokens: List) -> any:
token = tokens[self._index % len(tokens)]
self._index += 1
return token
class RandomStrategy(SelectionStrategy):
def select(self, tokens: List) -> any:
return random.choice(tokens)
class LeastUsedStrategy(SelectionStrategy):
def select(self, tokens: List) -> any:
return min(tokens, key=lambda t: t.remaining)
```
#### 4.4 产出物
- 路径:`ai-service/github-pool/`
- 文件:
- `pool.py` - Token 池核心实现
- `rate_limiter.py` - 限流控制
- `strategies.py` - 调度策略(轮询/随机/最小使用)
- `monitor.py` - 健康监控
- `config.py` - 配置管理
- `README.md` - 使用文档
- `requirements.txt` - 依赖
#### 4.5 时间安排
- 时段:下午 16:00 - 17:30
- 建议:先完成核心 Token 池,策略模式预留扩展接口
---
### 任务 5:Docker / GPU 调度 PoC
**任务目标**:验证 Docker GPU 调度能力,实现简单的任务分发与 GPU 资源管理
#### 5.1 架构设计
```
ai-service/gpu-scheduler/
├─ docker-compose.yml # 基础服务编排
├─ scheduler/
│ ├─ __init__.py
│ ├─ gpu_manager.py # GPU 资源管理
│ ├─ task_queue.py # 任务队列
│ ├─ worker.py # 工作节点
│ ├─ api.py # REST API
│ └─ config.py # 配置
├─ examples/
│ ├─ inference.py # 推理任务示例
│ └─ embedding.py # 向量化任务示例
└─ README.md
```
#### 5.2 GPU 资源管理
```python
# ai-service/gpu-scheduler/scheduler/gpu_manager.py
import subprocess
import json
from typing import List, Dict
from dataclasses import dataclass
@dataclass
class GPUInfo:
id: int
name: str
memory_total: int
memory_used: int
memory_free: int
utilization: float
class GPUMonitor:
@staticmethod
def get_gpu_info() -> List[GPUInfo]:
try:
result = subprocess.run(
["nvidia-smi", "--query-gpu=index,name,memory.total,memory.used,memory.free,utilization.gpu",
"--format=csv,noheader,nounits"],
capture_output=True, text=True
)
gpus = []
for line in result.stdout.strip().split('\n'):
if line:
idx, name, mem_total, mem_used, mem_free, util = line.split(', ')
gpus.append(GPUInfo(
id=int(idx),
name=name.strip(),
memory_total=int(mem_total),
memory_used=int(mem_used),
memory_free=int(mem_free),
utilization=float(util)
))
return gpus
except Exception as e:
print(f"Failed to get GPU info: {e}")
return []
class GPUManager:
def __init__(self, max_memory_percent=90):
self.max_memory_percent = max_memory_percent
self.monitor = GPUMonitor()
def get_available_gpus(self, required_memory_mb: int) -> List[int]:
available = []
for gpu in self.monitor.get_gpu_info():
free_percent = (gpu.memory_free / gpu.memory_total) * 100
if free_percent >= (100 - self.max_memory_percent):
required_memory_mb / 1024 # 转换为 MB
if gpu.memory_free >= required_memory_mb:
available.append(gpu.id)
return available
def allocate_gpu(self, required_memory_mb: int) -> int:
available = self.get_available_gpus(required_memory_mb)
if not available:
raise Exception("No available GPU with sufficient memory")
return available[0]
```
#### 5.3 任务队列
```python
# ai-service/gpu-scheduler/scheduler/task_queue.py
import asyncio
from typing import Dict, Optional, Callable
from dataclasses import dataclass, field
from enum import Enum
import uuid
class TaskStatus(Enum):
PENDING = "pending"
RUNNING = "running"
COMPLETED = "completed"
FAILED = "failed"
@dataclass
class Task:
id: str
type: str
params: Dict
status: TaskStatus = TaskStatus.PENDING
gpu_id: Optional[int] = None
result: Optional[any] = None
error: Optional[str] = None
created_at: float = field(default_factory=lambda: asyncio.get_event_loop().time())
class TaskQueue:
def __init__(self):
self._queue = asyncio.Queue()
self._tasks: Dict[str, Task] = {}
async def submit(self, task_type: str, params: Dict) -> str:
task_id = str(uuid.uuid4())[:8]
task = Task(id=task_id, type=task_type, params=params)
self._tasks[task_id] = task
await self._queue.put(task)
return task_id
async def get_task(self) -> Optional[Task]:
try:
return self._queue.get_nowait()
except asyncio.QueueEmpty:
return None
def get_task_status(self, task_id: str) -> Optional[TaskStatus]:
task = self._tasks.get(task_id)
return task.status if task else None
def update_status(self, task_id: str, status: TaskStatus, **kwargs):
if task_id in self._tasks:
self._tasks[task_id].status = status
for key, value in kwargs.items():
setattr(self._tasks[task_id], key, value)
```
#### 5.4 Worker 实现
```python
# ai-service/gpu-scheduler/scheduler/worker.py
import asyncio
import docker
from typing import Dict
from .gpu_manager import GPUManager
from .task_queue import TaskQueue, TaskStatus
class GPUWorker:
def __init__(self, task_queue: TaskQueue, gpu_manager: GPUManager):
self.queue = task_queue
self.gpu_manager = gpu_manager
self.docker_client = docker.from_env()
self._running = False
async def start(self):
self._running = True
while self._running:
task = await self.queue.get_task()
if task:
await self._process_task(task)
else:
await asyncio.sleep(1)
async def _process_task(self, task):
try:
gpu_id = self.gpu_manager.allocate_gpu(task.params.get("memory_mb", 4096))
self.queue.update_status(task.id, TaskStatus.RUNNING, gpu_id=gpu_id)
# 使用 Docker 运行任务
container = self.docker_client.containers.run(
task.params.get("image", "pytorch/pytorch:latest"),
f"python {task.params.get('script', 'run.py')}",
volumes=task.params.get("volumes", {}),
environment={"CUDA_VISIBLE_DEVICES": str(gpu_id)},
detach=True
)
result = container.wait()
logs = container.logs().decode('utf-8')
if result["StatusCode"] == 0:
self.queue.update_status(task.id, TaskStatus.COMPLETED, result=logs)
else:
self.queue.update_status(task.id, TaskStatus.FAILED, error=logs)
container.remove()
except Exception as e:
self.queue.update_status(task.id, TaskStatus.FAILED, error=str(e))
def stop(self):
self._running = False
```
#### 5.5 Docker Compose 配置
```yaml
# ai-service/gpu-scheduler/docker-compose.yml
version: '3.8'
services:
scheduler-api:
build: ./scheduler
ports:
- "8000:8000"
environment:
- GPU_ENABLED=true
- WORKER_COUNT=2
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./data:/app/data
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
redis:
image: redis:7-alpine
ports:
- "6379:6379"
networks:
default:
name: gpu-scheduler-network
```
#### 5.6 产出物
- 路径:`ai-service/gpu-scheduler/`
- 文件:
- `docker-compose.yml` - 服务编排
- `scheduler/` - 调度器核心代码
- `examples/` - 任务示例
- `README.md` - 使用文档
- `POC测试报告.md` - PoC 验证结果
#### 5.7 时间安排
- 时段:下午 17:30 - 20:00
- 建议:先验证 Docker GPU 挂载,再实现任务调度核心逻辑
---
## 三、时间安排总览
```
┌─────────────────────────────────────────────────────────────────┐
│ 今日时间线 (2026-07-13) │
├─────────────────────────────────────────────────────────────────┤
│ 09:00 - 11:00 │ 任务1:RBAC/项目/状态机接口契约评审 │
│ │ - 快速过一遍现有接口 │
│ │ - 标记问题点 │
│ │ - 编写评审报告 │
├────────────────┼────────────────────────────────────────────────┤
│ 11:00 - 13:00 │ 任务2:Milvus 单机环境 + 接入测试 │
│ │ - docker-compose 启动 Milvus │
│ │ - Python SDK 封装 │
│ │ - 接入测试验证 │
├────────────────┼────────────────────────────────────────────────┤
│ 13:00 - 14:00 │ 午休 │
├────────────────┼────────────────────────────────────────────────┤
│ 14:00 - 16:00 │ 任务3:LLM 统一 Client │
│ │ - 抽象基类设计 │
│ │ - OpenAI/Claude/本地模型适配器 │
│ │ - 统一入口封装 │
├────────────────┼────────────────────────────────────────────────┤
│ 16:00 - 17:30 │ 任务4:GitHub Token 池化 │
│ │ - Token 池核心实现 │
│ │ - 调度策略 │
│ │ - 健康监控 │
├────────────────┼────────────────────────────────────────────────┤
│ 17:30 - 20:00 │ 任务5:Docker / GPU 调度 PoC │
│ │ - GPU 资源管理 │
│ │ - 任务队列设计 │
│ │ - Worker 实现 │
│ │ - PoC 验证 │
└─────────────────────────────────────────────────────────────────┘
```
---
## 四、目录结构汇总
```
/home/admin2/studyweb/
├── cfm_docs/
│ └── 接口契约评审/
│ ├── RBAC接口评审报告.md
│ ├── 项目接口评审报告.md
│ ├── 状态机接口评审报告.md
│ └── 评审问题汇总.md
│
└── ai-service/
├── milvus/
│ ├── docker-compose.yml
│ ├── client.py
│ ├── test_client.py
│ ├── README.md
│ └── 测试报告.md
│
├── llm-client/
│ ├── base.py
│ ├── openai_client.py
│ ├── anthropic_client.py
│ ├── local_client.py
│ ├── unified.py
│ ├── config.py
│ ├── config.yaml
│ ├── exceptions.py
│ ├── README.md
│ └── requirements.txt
│
├── github-pool/
│ ├── pool.py
│ ├── rate_limiter.py
│ ├── strategies.py
│ ├── monitor.py
│ ├── config.py
│ ├── README.md
│ └── requirements.txt
│
└── gpu-scheduler/
├── docker-compose.yml
├── scheduler/
│ ├── __init__.py
│ ├── gpu_manager.py
│ ├── task_queue.py
│ ├── worker.py
│ ├── api.py
│ └── config.py
├── examples/
│ ├── inference.py
│ └── embedding.py
├── README.md
└── POC测试报告.md
```
---
## 五、执行检查清单
### 任务 1:RBAC / 项目 / 状态机接口契约评审
```
☐ 阅读现有接口文档
☐ RBAC 接口评审完成
☐ 项目接口评审完成
☐ 状态机接口评审完成
☐ 评审问题汇总完成
```
### 任务 2:Milvus 单机环境 + 接入测试
```
☐ docker-compose.yml 创建
☐ Milvus 服务启动成功
☐ Python SDK 封装完成
☐ 连接测试通过
☐ CRUD 测试通过
☐ 向量检索测试通过
☐ README.md 编写完成
```
### 任务 3:LLM 统一 Client
```
☐ 抽象基类定义
☐ OpenAI 适配器实现
☐ Claude 适配器实现
☐ 本地模型适配器实现
☐ 统一入口封装
☐ 配置文件支持
☐ 单元测试通过
☐ README.md 编写完成
```
### 任务 4:GitHub Token 池化协助
```
☐ Token 池核心实现
☐ 限流控制实现
☐ 调度策略实现
☐ 健康监控实现
☐ 单元测试通过
☐ README.md 编写完成
```
### 任务 5:Docker / GPU 调度 PoC
```
☐ GPU 资源管理实现
☐ 任务队列实现
☐ Worker 实现
☐ Docker Compose 配置
☐ GPU 挂载验证通过
☐ 任务分发测试通过
☐ README.md 编写完成
☐ PoC 测试报告完成
```
---
## 六、风险与应对
| 风险 | 可能性 | 影响 | 应对措施 |
| --- | ------ | --- | -------- |
| Milvus 启动失败 | 中 | 中 | 检查 Docker 版本,确认 port 19530 未被占用 |
| GPU 不可用 | 低 | 高 | 使用 CPU 模式降级验证 PoC |
| Token 池并发问题 | 中 | 中 | 使用 asyncio.Lock 保证线程安全 |
| LLM API 限流 | 高 | 中 | 添加指数退避重试机制 |
---
> **最后更新**:2026-07-13 09:00
> **执行人**:待填写
> **状态**:待开始
# 实习生培训教程编写任务说明
> **版本**:V1.0
> **日期**:2026-07-06
> **定位**:为实习生编写生动易懂的培训教程
> **风格参考**:DataWhale Happy-LLM / PyTorch Tutorials
---
## 一、任务目标
将实习生培训内容整理成**可直接教学的教程文档**,风格参考 DataWhale:[https://datawhalechina.github.io/happy-llm/#/./README](https://datawhalechina.github.io/happy-llm/#/./README)
```
目标效果:
├─ 像 DataWhale 那样:概念清晰 + 例子丰富 + 对比展示
├─ 像 PyTorch 官方教程:权威权威 + 可运行示例
└─ 像实训手册:看完就会,做完验收
```
---
## 二、教程风格指南
### 2.1 每个知识点的标准结构
```
### X.X 知识点名称
> 用 1-2 句话说清:这个知识点解决什么问题。
---
## 什么是这个知识点?
(用通俗语言解释,包含:
1. 一句话定义
2. 为什么重要
3. 生活类比(可选))
## 举个例子
(具体示例,包含:
1. 输入是什么
2. 输出是什么
3. 代码演示)
## 正解 vs 错误
(对比展示,包含:
1. 正确做法
2. 常见错误
3. 错误表现)
## 原理深入(可选)
(底层原理,包含:
1. 核心逻辑
2. 数学推导(可选)
3. 流程图/ASCII 图)
## 实战代码
(可直接运行的最小示例)
## 常见问题
Q: 常见问题 1
A: 回答
Q: 常见问题 2
A: 回答
## 验收标准
```
□ 能独立写出 xxx 代码
□ 能解释 xxx 原理
□ 能处理 xxx 错误
```
## 官方来源
- https://xxx
## 参考文献
[1] xxx
```
---
### 2.2 生动性的 10 个技巧
| 技巧 | 示例 | 效果 |
| ---------------- | -------------------------- | ------ |
| **1. 对比展示** | 正解 vs 错误 / before vs after | 一眼看出区别 |
| **2. 生活类比** | "把张量想象成 Excel 表格" | 快速理解 |
| **3. 具体输入输出** | 输入:`xxx` → 输出:`xxx` | 看得见摸得着 |
| **4. 代码可直接运行** | 最小可运行代码块 | 动手实践 |
| **5. 错误案例分析** | 错误表现 + 解决方法 | 少走弯路 |
| **6. 竖线分隔展示** | 正确:`A | B |
| **7. 流程图/步骤分解** | 1. 先做... 2. 再做... 3. 最后... | 清晰脉络 |
| **8. ASCII 示意图** | `输入 → 处理 → 输出` | 轻量化图示 |
| **9. 时间/字数预估** | ⏱️ 5 分钟 / 📖 1000 字 | 建立预期 |
| **10. 参考文献引用** | 标注论文/官方文档 | 权威可信 |
---
### 2.3 写作质量标准
```
合格:
├─ 有通俗易懂的概念解释(不是照抄官方文档)
├─ 有具体可运行的代码示例
├─ 有正确 vs 错误的对比
├─ 有常见问题 Q&A
├─ 有可验收的标准
└─ 有官方来源链接
```
---
## 三、教程内容大纲
### 模块一:Python 工程化(Week 1 前半)
#### 1.1 Git 使用(必须掌握)
```
子知识点:
├─ 1.1.1 首次配置(user.name / user.email)
├─ 1.1.2 克隆项目(git clone)
├─ 1.1.3 分支操作(branch / switch / checkout)
├─ 1.1.4 同步代码(fetch / pull / rebase)
├─ 1.1.5 提交代码(add / commit / amend)
├─ 1.1.6 推送代码(push / -u)
├─ 1.1.7 合并与冲突处理
├─ 1.1.8 查看历史与差异
├─ 1.1.9 版本回退(reset / revert / reflog)
├─ 1.1.10 暂存工作(stash)
└─ 1.1.11 Commit 规范与分支命名
```
#### 1.2 面向对象
```
子知识点:
├─ 1.2.1 类定义与实例化
├─ 1.2.2 继承与多态
├─ 1.2.3 特殊方法(__init__ / __str__ / __len__)
├─ 1.2.4 访问控制(公有 / 私有 / 保护)
├─ 1.2.5 上下文管理器(with 语句)
├─ 1.2.6 迭代器与生成器
└─ 1.2.7 枚举类(enum)
```
#### 1.3 装饰器
```
子知识点:
├─ 1.3.1 装饰器基础(@decorator 语法)
├─ 1.3.2 带参数的装饰器
├─ 1.3.3 functools.wraps
├─ 1.3.4 常用内置装饰器(@property / @staticmethod)
└─ 1.3.5 装饰器执行顺序
```
#### 1.4 异步编程
```
子知识点:
├─ 1.4.1 async / await 语法
├─ 1.4.2 asyncio 基本使用
├─ 1.4.3 常见错误(忘记 await)
└─ 1.4.4 异步 vs 同步对比
```
#### 1.5 Python 代码规范
```
子知识点:
├─ 1.5.1 PEP8 规范要点
├─ 1.5.2 类型注解(type hints)
├─ 1.5.3 虚拟环境(venv / conda)
└─ 1.5.4 包结构规范
```
---
### 模块二:PyTorch 基础(Week 1 后半)
#### 2.1 Tensor 操作
```
子知识点:
├─ 2.1.1 张量创建(tensor / zeros / ones / randn)
├─ 2.1.2 张量属性(shape / dtype / device)
├─ 2.1.3 张量运算(加减乘除 / 矩阵乘法)
├─ 2.1.4 索引与切片
├─ 2.1.5 形状变换(reshape / view / transpose)
├─ 2.1.6 张量与 NumPy 互转
├─ 2.1.7 GPU 迁移(.to('cuda'))
└─ 2.1.8 广播机制
```
#### 2.2 自动求导
```
子知识点:
├─ 2.2.1 requires_grad 设置
├─ 2.2.2 backward() 反向传播
├─ 2.2.3 grad 属性读取
├─ 2.2.4 no_grad() 上下文
└─ 2.2.5 detach() 断开计算图
```
#### 2.3 nn.Module
```
子知识点:
├─ 2.3.1 自定义模型(继承 nn.Module)
├─ 2.3.2 __init__ 与 forward
├─ 2.3.3 模型参数(parameters())
├─ 2.3.4 模型保存与加载
└─ 2.3.5 .train() / .eval() 模式
```
#### 2.4 训练循环
```
子知识点:
├─ 2.4.1 数据加载(Dataset / DataLoader)
├─ 2.4.2 前向传播
├─ 2.4.3 损失计算
├─ 2.4.4 反向传播与参数更新
├─ 2.4.5 完整训练循环
└─ 2.4.6 常见错误(梯度清零 / NaN)
```
---
### 模块三:深度学习基础(Week 2)
#### 3.1 激活函数
```
子知识点:
├─ 3.1.1 Sigmoid(公式 / 梯度消失)
├─ 3.1.2 Tanh
├─ 3.1.3 ReLU(死亡 ReLU 问题)
├─ 3.1.4 Leaky ReLU / GELU
└─ 3.1.5 Softmax(多分类)
```
#### 3.2 损失函数
```
子知识点:
├─ 3.2.1 交叉熵损失(CrossEntropyLoss)
├─ 3.2.2 二分类交叉熵(BCEWithLogitsLoss)
├─ 3.2.3 均方误差(MSE / MSELoss)
└─ 3.2.4 损失选择原则
```
#### 3.3 优化器
```
子知识点:
├─ 3.3.1 SGD(随机梯度下降)
├─ 3.3.2 Adam(自适应学习率)
├─ 3.3.3 AdamW(权重衰减)
├─ 3.3.4 学习率设置
└─ 3.3.5 梯度裁剪
```
#### 3.4 前向传播 / 反向传播
```
子知识点:
├─ 3.4.1 计算图概念
├─ 3.4.2 前向传播过程
├─ 3.4.3 梯度计算(链式法则)
├─ 3.4.4 反向传播过程
└─ 3.4.5 梯度消失与爆炸
```
---
### 模块四:Transformer 原理(Week 2 后半)
#### 4.1 Self-Attention
```
子知识点:
├─ 4.1.1 Attention 机制背景
├─ 4.1.2 Query / Key / Value 概念
├─ 4.1.3 注意力分数计算(Scaled Dot-Product)
├─ 4.1.4 Softmax 归一化
├─ 4.1.5 加权求和
└─ 4.1.6 手写 Self-Attention 代码
```
#### 4.2 Multi-Head Attention
```
子知识点:
├─ 4.2.1 为什么要多头
├─ 4.2.2 多头计算过程
├─ 4.2.3 PyTorch 实现(nn.MultiheadAttention)
└─ 4.2.4 与 Self-Attention 的关系
```
#### 4.3 位置编码
```
子知识点:
├─ 4.3.1 为什么需要位置编码
├─ 4.3.2 绝对位置编码(Sinusoidal)
├─ 4.3.3 相对位置编码(RoPE)
└─ 4.3.4 位置编码实现
```
#### 4.4 Layer Norm / Feed Forward
```
子知识点:
├─ 4.4.1 Batch Norm vs Layer Norm
├─ 4.4.2 Layer Norm 计算过程
├─ 4.4.3 Feed Forward Network
├─ 4.4.4 残差连接
└─ 4.4.5 完整 Encoder Block
```
---
### 模块五:LLM + API 调用(Week 3)
#### 5.1 Prompt Engineering
```
子知识点:
├─ 5.1.1 零样本提示(Zero-shot)
├─ 5.1.2 少样本提示(Few-shot)
├─ 5.1.3 Chain-of-Thought(CoT)
├─ 5.1.4 角色提示
├─ 5.1.5 结构化输出
├─ 5.1.6 温度与 Top-p
└─ 5.1.7 Prompt 迭代优化
```
#### 5.2 OpenAI API 调用
```
子知识点:
├─ 5.2.1 API Key 配置
├─ 5.2.2 基本调用(ChatCompletion)
├─ 5.2.3 messages 格式
├─ 5.2.4 Token 计算
├─ 5.2.5 错误处理
├─ 5.2.6 多轮对话
└─ 5.2.7 成本优化
```
#### 5.3 流式输出
```
子知识点:
├─ 5.3.1 Streaming 原理(SSE)
├─ 5.3.2 流式调用
├─ 5.3.3 chunk 拼接
└─ 5.3.4 前端展示
```
#### 5.4 Function Calling
```
子知识点:
├─ 5.4.1 Function Calling 概念
├─ 5.4.2 函数定义(JSON Schema)
├─ 5.4.3 调用流程
├─ 5.4.4 多轮 Function Calling
└─ 5.4.5 实际应用场景
```
---
### 模块六:RAG 基础(Week 4)
#### 6.1 RAG 原理
```
子知识点:
├─ 6.1.1 为什么需要 RAG
├─ 6.1.2 RAG 完整流程
├─ 6.1.3 RAG vs Fine-tuning
└─ 6.1.4 RAG 应用场景
```
#### 6.2 文档处理
```
子知识点:
├─ 6.2.1 PDF 解析(pdfplumber)
├─ 6.2.2 Word 解析(python-docx)
├─ 6.2.3 文本清洗
├─ 6.2.4 表格提取
└─ 6.2.5 元数据管理
```
#### 6.3 文本分块
```
子知识点:
├─ 6.3.1 固定长度分块
├─ 6.3.2 递归字符分块
├─ 6.3.3 语义分块
└─ 6.3.4 分块大小配置
```
#### 6.4 Embedding
```
子知识点:
├─ 6.4.1 Embedding 原理
├─ 6.4.2 常用模型(BGE / M3E)
├─ 6.4.3 API 调用
└─ 6.4.4 批量向量化
```
#### 6.5 向量数据库
```
子知识点:
├─ 6.5.1 Chroma 快速上手
├─ 6.5.2 Collection 管理
├─ 6.5.3 CRUD 操作
└─ 6.5.4 检索原理
```
---
### 模块七:工程实操(Week 5-12)
#### 7.1 FastAPI
```
子知识点:
├─ 7.1.1 FastAPI vs Flask
├─ 7.1.2 路由定义(@app.get / @app.post)
├─ 7.1.3 请求体(Pydantic 模型)
├─ 7.1.4 响应模型
├─ 7.1.5 依赖注入
├─ 7.1.6 中间件
├─ 7.1.7 异步路由
└─ 7.1.8 自动文档
```
#### 7.2 PostgreSQL
```
子知识点:
├─ 7.2.1 基本命令
├─ 7.2.2 表创建与数据类型
├─ 7.2.3 增删改查
├─ 7.2.4 索引与优化
├─ 7.2.5 Python 连接(psycopg2)
└─ 7.2.6 SQLAlchemy ORM
```
#### 7.3 Redis
```
子知识点:
├─ 7.3.1 基本数据类型
├─ 7.3.2 常用命令
├─ 7.3.3 缓存策略
├─ 7.3.4 Python 客户端
└─ 7.3.5 分布式锁
```
#### 7.4 Docker
```
子知识点:
├─ 7.4.1 Docker 概念
├─ 7.4.2 Dockerfile 编写
├─ 7.4.3 常用指令
├─ 7.4.4 Docker Compose
├─ 7.4.5 容器操作
└─ 7.4.6 GPU 支持
```
#### 7.5 pytest
```
子知识点:
├─ 7.5.1 pytest 基础
├─ 7.5.2 断言
├─ 7.5.3 Fixture
├─ 7.5.4 参数化测试
└─ 7.5.5 Mock
```
---
---
## 四、参考资料
### 官方文档
| 主题 | 链接 |
| ------- | -------------------------------------------------------------------------------------- |
| Git | [https://git-scm.com/book/zh/v2](https://git-scm.com/book/zh/v2) |
| PyTorch | [https://pytorch.org/docs/](https://pytorch.org/docs/) |
| FastAPI | [https://fastapi.tiangolo.com/zh/tutorial/](https://fastapi.tiangolo.com/zh/tutorial/) |
| Docker | [https://docs.docker.com/get-started/](https://docs.docker.com/get-started/) |
| pytest | [https://docs.pytest.org/](https://docs.pytest.org/) |
| Redis | [https://redis.io/docs/getting-started/](https://redis.io/docs/getting-started/) |
### 参考教程
| 教程 | 链接 |
| ------------------- | ------------------------------------------------------------------------------------------ |
| DataWhale Happy-LLM | [https://datawhalechina.github.io/happy-llm/](https://datawhalechina.github.io/happy-llm/) |
| PyTorch Tutorials | [https://pytorch.org/tutorials/](https://pytorch.org/tutorials/) |
| FastAPI Tutorial | [https://fastapi.tiangolo.com/tutorial/](https://fastapi.tiangolo.com/tutorial/) |
---
## 五、任务分配表
### 5.1 分工方案
> **总工期**:2 天(2026-07-07 ~ 2026-07-08)
### 5.2 详细任务分配
---
#### 张钱炜(算法/原理模块)
```
负责模块:模块三(深度学习基础)+ 模块四(Transformer原理)
核心要求:
├─ 必须画出 Attention 计算流程图
├─ 必须手写 Self-Attention 代码
├─ 必须解释清楚 Q/K/V 的作用
└─ 必须对比 Batch Norm 和 Layer Norm
负责章节:
├─ 【3.1】激活函数(★★★★☆)
├─ 【3.2】损失函数(★★★★☆)
├─ 【3.3】优化器(★★★★☆)
├─ 【3.4】前向传播/反向传播(★★★★★)← 重点
├─ 【4.1】Self-Attention(★★★★★)← 重点
├─ 【4.2】Multi-Head Attention(★★★★★)← 重点
├─ 【4.3】位置编码(★★★★★)← 重点
└─ 【4.4】Layer Norm / Feed Forward(★★★★☆)
```
---
#### 李佳洋(工程实践模块)
```
负责模块:模块二(PyTorch基础)+ 模块五(LLM+API调用)
核心要求:
├─ 代码必须可运行(必须实际测试)
├─ 必须有完整的 API 调用示例
├─ 必须演示多轮对话和 Function Calling
└─ 必须解释训练循环每个步骤
负责章节:
├─ 【2.1】Tensor 操作(★★★★☆)
├─ 【2.2】自动求导(★★★★☆)
├─ 【2.3】nn.Module(★★★★☆)
├─ 【2.4】训练循环(★★★★★)← 重点
├─ 【5.1】Prompt Engineering(★★★★☆)
├─ 【5.2】OpenAI API 调用(★★★★★)← 重点
├─ 【5.3】流式输出(★★★★☆)
└─ 【5.4】Function Calling(★★★★★)← 重点
```
---
#### 蔡馥名(基础/工具模块)
```
负责模块:模块一(Python工程化)+ 模块六(RAG基础)+ 模块七(工程实操)
核心要求:
├─ Git 使用必须有详细的命令示例
├─ RAG 流程必须有流程图
├─ Docker 必须有完整的 Dockerfile 示例
└─ 每个工具都必须有快速上手指南
负责章节:
├─ 【1.1】Git 使用(★★★★★)← 必会
├─ 【1.2】面向对象(★★★☆☆)
├─ 【1.3】装饰器(★★★☆☆)
├─ 【1.4】异步编程(★★★☆☆)
├─ 【1.5】Python 代码规范(★★★☆☆)
├─ 【6.1】RAG 原理(★★★★☆)
├─ 【6.2】文档处理(★★★★☆)
├─ 【6.3】文本分块(★★★★☆)
├─ 【6.4】Embedding(★★★★☆)
├─ 【6.5】向量数据库(★★★★☆)
├─ 【7.1】FastAPI(★★★★☆)
├─ 【7.2】PostgreSQL(★★★★☆)
├─ 【7.3】Redis(★★★☆☆)
├─ 【7.4】Docker(★★★★☆)
└─ 【7.5】pytest(★★★☆☆)
```
---
### 5.4 每日任务分解
#### 第一天(7月7日)
```
上午
张钱炜:
├─ 完成 3.4 前向传播/反向传播(★★★★★)
└─ 完成 4.1 Self-Attention(★★★★★)
李佳洋:
├─ 完成 2.4 训练循环(★★★★★)
└─ 完成 5.2 OpenAI API 调用(★★★★★)
蔡馥名:
├─ 完成 1.1 Git 使用(★★★★★)
└─ 完成 6.1 RAG 原理(★★★★☆)
下午
张钱炜:
├─ 完成 3.1 激活函数
├─ 完成 3.2 损失函数
└─ 完成 3.3 优化器
李佳洋:
├─ 完成 2.1 Tensor 操作
├─ 完成 2.2 自动求导
└─ 完成 2.3 nn.Module
蔡馥名:
├─ 完成 6.2 文档处理
├─ 完成 6.3 文本分块
└─ 完成 6.4 Embedding
```
---
### 5.5 任务分配总表
| 模块 | 章节 | 负责人 | 难度 | 状态 |
| ------------------------ | ------------ | --- | ----- | --- |
| **模块一:Python工程化** | | | | |
| 1.1 Git 使用 | 1.1.1-1.1.11 | 蔡馥名 | ★★★★★ | 待开始 |
| 1.2 面向对象 | 1.2.1-1.2.7 | 蔡馥名 | ★★★☆☆ | 待开始 |
| 1.3 装饰器 | 1.3.1-1.3.5 | 蔡馥名 | ★★★☆☆ | 待开始 |
| 1.4 异步编程 | 1.4.1-1.4.4 | 蔡馥名 | ★★★☆☆ | 待开始 |
| 1.5 Python代码规范 | 1.5.1-1.5.4 | 蔡馥名 | ★★★☆☆ | 待开始 |
| **模块二:PyTorch基础** | | | | |
| 2.1 Tensor操作 | 2.1.1-2.1.8 | 李佳洋 | ★★★★☆ | 待开始 |
| 2.2 自动求导 | 2.2.1-2.2.5 | 李佳洋 | ★★★★☆ | 待开始 |
| 2.3 nn.Module | 2.3.1-2.3.5 | 李佳洋 | ★★★★☆ | 待开始 |
| 2.4 训练循环 | 2.4.1-2.4.6 | 李佳洋 | ★★★★★ | 待开始 |
| **模块三:深度学习基础** | | | | |
| 3.1 激活函数 | 3.1.1-3.1.5 | 张钱炜 | ★★★★☆ | 待开始 |
| 3.2 损失函数 | 3.2.1-3.2.4 | 张钱炜 | ★★★★☆ | 待开始 |
| 3.3 优化器 | 3.3.1-3.3.5 | 张钱炜 | ★★★★☆ | 待开始 |
| 3.4 前向传播/反向传播 | 3.4.1-3.4.5 | 张钱炜 | ★★★★★ | 待开始 |
| **模块四:Transformer原理** | | | | |
| 4.1 Self-Attention | 4.1.1-4.1.6 | 张钱炜 | ★★★★★ | 待开始 |
| 4.2 Multi-Head Attention | 4.2.1-4.2.4 | 张钱炜 | ★★★★★ | 待开始 |
| 4.3 位置编码 | 4.3.1-4.3.4 | 张钱炜 | ★★★★★ | 待开始 |
| 4.4 Layer Norm/FFN | 4.4.1-4.4.5 | 张钱炜 | ★★★★☆ | 待开始 |
| **模块五:LLM+API** | | | | |
| 5.1 Prompt Engineering | 5.1.1-5.1.7 | 李佳洋 | ★★★★☆ | 待开始 |
| 5.2 OpenAI API调用 | 5.2.1-5.2.7 | 李佳洋 | ★★★★★ | 待开始 |
| 5.3 流式输出 | 5.3.1-5.3.4 | 李佳洋 | ★★★★☆ | 待开始 |
| 5.4 Function Calling | 5.4.1-5.4.5 | 李佳洋 | ★★★★★ | 待开始 |
| **模块六:RAG基础** | | | | |
| 6.1 RAG原理 | 6.1.1-6.1.4 | 蔡馥名 | ★★★★☆ | 待开始 |
| 6.2 文档处理 | 6.2.1-6.2.5 | 蔡馥名 | ★★★★☆ | 待开始 |
| 6.3 文本分块 | 6.3.1-6.3.4 | 蔡馥名 | ★★★★☆ | 待开始 |
| 6.4 Embedding | 6.4.1-6.4.4 | 蔡馥名 | ★★★★☆ | 待开始 |
| 6.5 向量数据库 | 6.5.1-6.5.4 | 蔡馥名 | ★★★★☆ | 待开始 |
| **模块七:工程实操** | | | | |
| 7.1 FastAPI | 7.1.1-7.1.8 | 蔡馥名 | ★★★★☆ | 待开始 |
| 7.2 PostgreSQL | 7.2.1-7.2.6 | 蔡馥名 | ★★★★☆ | 待开始 |
| 7.3 Redis | 7.3.1-7.3.5 | 蔡馥名 | ★★★☆☆ | 待开始 |
| 7.4 Docker | 7.4.1-7.4.6 | 蔡馥名 | ★★★★☆ | 待开始 |
| 7.5 pytest | 7.5.1-7.5.5 | 蔡馥名 | ★★★☆☆ | 待开始 |
---
## 六、交付物要求
### 6.1 张钱炜交付物
```
提交路径:docs/理论学习/教程/
文件:
├─ 模块三-深度学习基础.md
└─ 模块四-Transformer原理.md
必须包含:
├─ 8 个完整章节
├─ 每个章节必须有 ASCII 流程图或结构图
├─ Self-Attention 必须有手写代码
├─ 必须有 PyTorch 实现代码
└─ 必须对比 Batch Norm 和 Layer Norm
质量标准:
├─ 原理讲解通俗易懂
├─ 代码可直接运行
└─ 图表清晰准确
```
### 6.2 李佳洋交付物
```
提交路径:docs/理论学习/教程/
文件:
├─ 模块二-PyTorch基础.md
└─ 模块五-LLM-API调用.md
必须包含:
├─ 8 个完整章节
├─ 每个知识点必须有可运行代码
├─ API 调用必须有完整示例
├─ 训练循环必须有完整代码
└─ Function Calling 必须有实战案例
质量标准:
├─ 代码必须实际测试通过
├─ 示例必须可以直接运行
└─ 错误处理必须完整
```
### 6.3 蔡馥名交付物
```
提交路径:docs/理论学习/教程/
文件:
├─ 模块一-Python工程化.md
├─ 模块六-RAG基础.md
└─ 模块七-工程实操.md
必须包含:
├─ 15 个完整章节
├─ Git 使用必须有详细命令示例
├─ Docker 必须有完整 Dockerfile
├─ RAG 流程必须有流程图
└─ 每个工具都必须有快速上手
质量标准:
├─ 命令示例必须准确
├─ 代码块可直接复制使用
└─ 步骤清晰易follow
```
---
## 七、验收标准
### 7.1 格式统一标准
```
所有文档必须遵循:
├─ 使用统一的标题层级(# / ## / ###)
├─ 代码块必须有语言标注(```python)
├─ 表格必须使用 Markdown 格式
├─ 链接必须可访问
└─ 标题不能有错别字
```
### 7.2 内容质量标准
```
每个章节必须包含:
├─ 什么是这个知识点(通俗解释)
├─ 举个例子(具体示例)
├─ 正解 vs 错误(对比展示)
├─ 实战代码(可运行)
├─ 常见问题 Q&A
├─ 验收标准
└─ 官方来源
```
### 7.3 提交标准
```
7月8号下班前:
├─ 完成所有章节定稿
├─ 格式完全统一
├─ 图表完整
└─ 提交最终合并请求
```
---
## 八、注意事项
### Git 提交
```
提交格式:type(module): description
示例:
├─ feat(module4): 完成 Self-Attention 章节
├─ fix(module2): 修复 Tensor 操作代码错误
├─ docs(module1): 完善 Git 使用教程
└─ style(module5): 统一 API 调用示例格式
要求:
├─ 每次完成一个小节提交一次
├─ 不要等到最后一次性提交
└─ 提交信息要清晰描述改动
```
This source diff could not be displayed because it is too large. You can view the blob instead.
...@@ -898,7 +898,7 @@ vectors = embed_openai(texts) ...@@ -898,7 +898,7 @@ vectors = embed_openai(texts)
print(f"维度:{len(vectors[0])}") # 1536 print(f"维度:{len(vectors[0])}") # 1536
``` ```
#### BGE vs OpenAI 对比 ##### BGE vs OpenAI 对比
| 维度 | BGE(本地) ⭐ | OpenAI(云端) | | 维度 | BGE(本地) ⭐ | OpenAI(云端) |
| ---------------------- | -------------- | ------------------ | | ---------------------- | -------------- | ------------------ |
......
# 模块四:Transformer 原理
> 本模块是理解现代大语言模型(LLM)的核心基础。Transformer 彻底改变了 NLP 领域,让"理解上下文"变得前所未有的高效。学完本章,你将能读懂 BERT、GPT、LLaMA 等主流模型的架构设计。
---
## Transformer 架构总览
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Transformer 完整架构 │
├─────────────────────────────────┬───────────────────────────────────────┤
│ Encoder (编码器) │ Decoder (解码器) │
├─────────────────────────────────┼───────────────────────────────────────┤
│ │ │
│ 输入序列 ──→ Embedding ──→ │ 输出序列 ──→ Embedding ──→ │
│ + Positional │ + Positional │
│ Encoding │ Encoding │
│ │ │ │ │
│ ┌───────────────┴───────────┐ │ ┌───────────────┴───────────┐ │
│ │ Encoder Layer × N │ │ │ Decoder Layer × N │ │
│ │ ┌─────────────────────┐ │ │ │ ┌─────────────────────┐│ │
│ │ │ Multi-Head │ │ │ │ │ Masked Multi-Head ││ │
│ │ │ Self-Attention │ │ │ │ │ Self-Attention ││ │
│ │ └──────────┬──────────┘ │ │ │ └──────────┬──────────┘│ │
│ │ │ Add & Norm │ │ │ │ Add & Norm │ │
│ │ ▼ │ │ │ ▼ │ │
│ │ ┌─────────────────────┐ │ │ │ ┌─────────────────────┐│ │
│ │ │ Feed Forward │ │ │ │ │ Cross Attention ││ │
│ │ │ Network │ │ │ │ │ (使用Encoder的K,V) ││ │
│ │ └──────────┬──────────┘ │ │ │ └──────────┬──────────┘│ │
│ │ │ Add & Norm │ │ │ │ Add & Norm │ │
│ └─────────────┼───────────────┘ │ │ ▼ │ │
│ │ │ │ ┌─────────────────────┐│ │
│ ▼ │ │ │ Feed Forward ││ │
│ Encoder Output │ │ │ Network ││ │
│ (K, V) │ │ └──────────┬──────────┘│ │
│ │ │ │ Add & Norm │ │
│ │ └─────────────┼─────────────┘ │
│ │ │ │
│ │ ▼ │
│ │ Linear + Softmax │
│ │ 输出 Token │
└─────────────────────────────────┴───────────────────────────────────────┘
模型配置:
原版: N=6, d=512, d_ff=2048, h=8
BERT: N=12, d=768, d_ff=3072, h=12
GPT-3: N=96, d=12288
LLaMA: N=32, d=4096, 使用 RoPE
```
---
## 4.1 Self-Attention
> 如果让你做阅读理解题,你会先看问题,然后回到原文中找答案。Self-Attention 就是让模型学会"带着问题找答案"的能力——每个词都可以"看"到句子中的所有其他词,判断谁跟谁更相关。
---
### 什么是 Self-Attention?
**一句话定义**:Self-Attention(自注意力)让序列中的**每个位置**都能同时**关注**序列中的**所有其他位置**,计算它们之间的相关性强度。
**为什么重要?**
- 解决了 RNN 难以捕捉长距离依赖的问题("我"和十段前的"他"有关联吗?能有!)
- 打破了序列必须按顺序处理的限制,可以完全并行计算
- 让模型能够"看到"全局信息,理解上下文
**生活类比**:想象你在聚会中听一个人说话
```
场景:你在一场嘈杂的聚会中听张三说话
你的大脑会:
1. 注意张三的嘴型(主要信息)
2. 同时观察周围人的表情(判断他说的话是否可信)
3. 偶尔瞥一眼手机屏幕(任务相关)
4. 忽略远处的背景噪音(过滤干扰)
Self-Attention 的工作方式完全一样:
- 每个词都会"问"其他所有词:"你和我有多相关?"
- 然后根据相关性强度,加权整合所有信息
```
---
### Query / Key / Value:三个角色的故事
**为什么要分成 Q、K、V 三个向量?**
让我用一个图书馆的故事来解释:
```
图书馆的故事
Query(查询):就像你拿着借书证去图书馆
你说:"我想找机器学习相关的书"
你在表达"我需要什么"
Key(钥匙):每本书的分类标签
书A标签:"机器学习、深度学习、Python"
书B标签:"历史、小说、文学"
书C标签:"数据分析、机器学习"
每本书在说明"我是什么内容"
Value(内容):书的实际内容
找到匹配的书后,你要阅读的真正内容
匹配过程:
1. 用 Query 去匹配 Key(找哪本书和"机器学习"相关)
2. 匹配度越高的书,Value(内容)权重越大
3. 最终输出:加权后的书籍内容
```
**对应到 Self-Attention**:
```
Q: "我现在这个词,需要找什么信息?"
K: "我这个词,包含什么信息?"
V: "我这个词,实际提供什么内容?"
Attention Score = Query 和 Key 的匹配程度
Output = 用 Attention Score 对 Value 加权求和
```
---
### 具体计算流程
```
输入句子:"The cat sat on the mat"
Step 1: 每个词变成一个向量(Embedding)
[The, cat, sat, on, the, mat]
↓
[v₁, v₂, v₃, v₄, v₅, v₆] ← 每个 v 是一个 d_model 维向量
Step 2: 生成 Q, K, V(通过可学习的矩阵变换)
Q = V × W_Q ← "我在找什么"
K = V × W_K ← "我有什么"
V = V × W_V ← "我提供什么"
Step 3: 计算注意力分数(点积 + 缩放)
对于位置 i 的 Query qᵢ:
score(qᵢ, kⱼ) = (qᵢ · kⱼ) / √d_k
Step 4: Softmax 得到概率分布
attention_weights = softmax(scores)
Step 5: 加权求和
outputᵢ = Σⱼ(attention_weightᵢⱼ × vⱼ)
```
### Attention 权重矩阵示例
```
以 "The cat sat on the mat" 为例的注意力权重热力图:
The cat sat on the mat
┌─────┬─────┬─────┬─────┬─────┬─────┐
The │ 0.30│ 0.45│ 0.10│ 0.05│ 0.05│ 0.05│
├─────┼─────┼─────┼─────┼─────┼─────┤
cat │ 0.42│ 0.30│ 0.15│ 0.05│ 0.03│ 0.05│
├─────┼─────┼─────┼─────┼─────┼─────┤
sat │ 0.10│ 0.35│ 0.30│ 0.15│ 0.05│ 0.05│
├─────┼─────┼─────┼─────┼─────┼─────┤
on │ 0.05│ 0.05│ 0.15│ 0.30│ 0.35│ 0.10│
├─────┼─────┼─────┼─────┼─────┼─────┤
the │ 0.05│ 0.05│ 0.05│ 0.15│ 0.30│ 0.40│
├─────┼─────┼─────┼─────┼─────┼─────┤
mat │ 0.05│ 0.05│ 0.10│ 0.30│ 0.35│ 0.15│
└─────┴─────┴─────┴─────┴─────┴─────┘
观察:
- "The" 最关注 "cat"(0.45)- 主谓关系
- "cat" 最关注 "The"(0.42)- 语义相关
- "sat" 关注 "cat" 和 "on" - 主谓和介宾关系
- "mat" 关注 "on" 和 "the" - 介宾关系
```
**关键观察**:
- 对角线上不一定都是最高的值(词不一定最关注自己)
- 语义相关的词之间往往有更强的注意力
---
### ✅ 正确做法
```python
import torch
import torch.nn.functional as F
import math
def scaled_dot_product_attention(Q, K, V, mask=None):
"""
缩放点积注意力(Self-Attention 的标准实现)
参数:
Q: [batch, seq_len, d_k] - 查询
K: [batch, seq_len, d_k] - 键
V: [batch, seq_len, d_v] - 值
mask: [batch, seq_len, seq_len] - 掩码,0表示遮蔽
返回:
output: [batch, seq_len, d_v] - 注意力输出
attention_weights: [batch, seq_len, seq_len] - 注意力权重
"""
d_k = Q.size(-1)
# 1️⃣ 计算点积注意力分数
# Q @ K.T: [B, L, D] @ [B, D, L] = [B, L, L]
scores = torch.matmul(Q, K.transpose(-2, -1))
# 2️⃣ 缩放(防止 d_k 太大时梯度消失)
scores = scores / math.sqrt(d_k)
# 3️⃣ 应用掩码(如 padding 或未来位置)
if mask is not None:
scores = scores.masked_fill(mask == 0, -1e9)
# 4️⃣ Softmax 得到概率分布
attention_weights = F.softmax(scores, dim=-1)
# 5️⃣ 加权求和
output = torch.matmul(attention_weights, V)
return output, attention_weights
```
### ❌ 常见错误
| 错误写法 | 为什么错 | 正确写法 |
|---------|---------|---------|
| `scores = Q @ K` | 维度不对,K 需要转置 | `Q @ K.transpose(-2, -1)` |
| 不除以 `√d_k` | d_k 大时梯度消失 | `scores / math.sqrt(d_k)` |
| mask 值设为 -1 | 可能被 softmax 变成 0 | 用 `-1e9`(足够小的负数)|
| 对错误的维度做 mask | 没效果 | 确保 mask shape 是 `[B, L, L]` |
| 忘记 `batch_first=True` | PyTorch 默认是 `[L, B, D]` | 检查 MultiheadAttention 参数 |
---
### 原理深入
#### 为什么用点积来计算相似度?
**点积的本质是投影**:
```
向量 a = [1, 2]
向量 b = [2, 1]
a · b = 1×2 + 2×1 = 4
几何意义:
- 如果 a 和 b 方向相同,a·b > 0,相关
- 如果 a 和 b 方向相反,a·b < 0,不相关
- 如果 a 和 b 垂直,a·b = 0,无关
```
**为什么点积比余弦相似度更好?**
- 余弦相似度只看方向,不看 magnitude
- 点积既看方向,也看 magnitude
- 在注意力中,Query 和 Key 的 magnitude 也有意义
#### 为什么要除以 √d_k?
**数学推导**:
```
假设 Q 和 K 的每个分量都是独立随机变量
均值 = 0,方差 = 1
则 q·k = Σᵢ qᵢkᵢ 的方差 = d_k(d_k 个独立随机变量相加)
当 d_k 很大时(如 512),点积的值可能达到 ±√d_k ≈ ±22
Softmax 输入范围过大,会导致:
softmax([22, 21, -21, -22]) ≈ [0.88, 0.12, 0, 0]
梯度接近 0,训练困难!
除以 √d_k 后:
方差归一化为 1
数值稳定,Softmax 梯度正常
```
---
## 4.2 Multi-Head Attention
> 你有没有想过,为什么我们需要"多头"注意力?一个 Attention 头不够吗?想象你读一篇文章时,你会同时关注语法结构、指代关系、语义相似等多个维度——多头注意力就是让模型也能同时从多个角度理解文本。
### 为什么要用多头?
**单一注意力的局限**:
```
假设只有一个 Attention 头:
句子:"The cat sat on the mat because it was tired"
问题:"it" 指代什么?
回答:只能学习到一种"相关性"
结果:模型可能困惑于"it"指的是"cat"还是"mat"
```
**多头注意力的优势**:
```
多个 Attention 头同时工作:
Head 1(语法头):
"cat" ←→ "sat" (主谓关系,强关注)
"it" ←→ "cat" (指代关系,强关注)
Head 2(语义头):
"cat" ←→ "tired" (猫很累,语义相关)
"mat" ←→ "sat" (在垫子上,语义相关)
Head 3(位置头):
关注相邻词之间的关系
"on" ←→ "the" (介词+冠词,模式)
每个头学到不同的东西,最后拼接起来!
```
**我的理解**:多头注意力就像一个"团队"
- 每个头是一个"专家",专注一个方面
- 不同的头看不同的"角度"
- 最后汇总所有专家的意见,做出综合判断
---
### 多头计算过程
#### 数学公式
```
MultiHead(Q, K, V) = Concat(head₁, head₂, ..., headₕ) × W_O
其中:
headᵢ = Attention(QWᵢ^Q, KWᵢ^K, VWᵢ^V)
```
#### 计算流程图
```
输入 X: [batch, seq_len, d_model]
│
├──→ W_Q₁ ──→ Q₁ ──┐
│ │
├──→ W_Q₂ ──→ Q₂ ──┼── Concat ──→ W_O ──→ 输出
│ ... │ ↑
├──→ W_Qₕ ──→ Qₕ ──┤ │
│ │ │
├──→ W_K₁ ──→ K₁ ──┤ │
│ │ │
├──→ W_K₂ ──→ K₂ ──┼────┘
│ ... │
├──→ W_Kₕ ──→ Kₕ ──┤
│ │
├──→ W_V₁ ──→ V₁ ──┤
├──→ W_V₂ ──→ V₂ ──┤
│ ... │
└──→ W_Vₕ ──→ Vₕ ──┘
每条线代表一个"头"的操作
```
#### 维度变化详解
```
输入: X [batch, seq_len, d_model]
│
├─→ d_model 维向量
│
▼
分 h=8 个头,每个头维度 d_k = d_model/h = 768/8 = 64
每个头的操作:
X [B, L, D] → W_Q [D, d_k] → Q [B, L, d_k]
X [B, L, D] → W_K [D, d_k] → K [B, L, d_k]
X [B, L, D] → W_V [D, d_v] → V [B, L, d_v]
Attention 计算 → 得到 [B, L, d_v]
拼接 h 个头:
[B, L, d_v] × 8 → Concat → [B, L, h×d_v] = [B, L, d_model]
最终投影:
[B, L, d_model] × W_O [d_model, d_model] → [B, L, d_model]
```
---
### ✅ 正确做法
```python
import torch
import torch.nn as nn
import torch.nn.functional as F
import math
class MultiHeadAttention(nn.Module):
"""
多头注意力实现
"""
def __init__(self, d_model, num_heads, dropout=0.1):
super().__init__()
assert d_model % num_heads == 0, "d_model 必须能被 num_heads 整除"
self.d_model = d_model
self.num_heads = num_heads
self.d_k = d_model // num_heads # 每个头的维度
# Q, K, V 投影
self.W_Q = nn.Linear(d_model, d_model)
self.W_K = nn.Linear(d_model, d_model)
self.W_V = nn.Linear(d_model, d_model)
# 输出投影
self.W_O = nn.Linear(d_model, d_model)
self.dropout = nn.Dropout(dropout)
def split_heads(self, x):
"""
将 embedding 分成多个头
[B, L, D] → [B, H, L, D/H]
"""
batch_size, seq_len, _ = x.shape
x = x.view(batch_size, seq_len, self.num_heads, self.d_k)
return x.transpose(1, 2) # [B, H, L, D/H]
def forward(self, Q, K, V, mask=None):
batch_size = Q.size(0)
# 1️⃣ 线性投影
Q = self.W_Q(Q)
K = self.W_K(K)
V = self.W_V(V)
# 2️⃣ 分成多个头
Q = self.split_heads(Q) # [B, H, L, d_k]
K = self.split_heads(K)
V = self.split_heads(V)
# 3️⃣ 计算注意力
scores = torch.matmul(Q, K.transpose(-2, -1)) / math.sqrt(self.d_k)
if mask is not None:
scores = scores.masked_fill(mask == 0, -1e9)
attention_weights = F.softmax(scores, dim=-1)
attention_weights = self.dropout(attention_weights)
# 4️⃣ 加权求和
context = torch.matmul(attention_weights, V) # [B, H, L, d_v]
# 5️⃣ 合并多头
context = context.transpose(1, 2).contiguous() # [B, L, H, d_v]
context = context.view(batch_size, -1, self.d_model) # [B, L, D]
# 6️⃣ 输出投影
output = self.W_O(context)
return output, attention_weights
# ============ 使用 PyTorch 内置实现 ============
def use_pytorch_mha():
"""使用 PyTorch 内置的 MultiheadAttention"""
d_model = 768
num_heads = 12
mha = nn.MultiheadAttention(
embed_dim=d_model,
num_heads=num_heads,
dropout=0.1,
batch_first=True # 重要:True 表示输入是 [B, L, D]
)
# 输入 [B, L, D]
query = torch.randn(2, 10, 768)
key = torch.randn(2, 10, 768)
value = torch.randn(2, 10, 768)
output, weights = mha(query, key, value)
print(f"输入: {query.shape}")
print(f"输出: {output.shape}")
print(f"注意力权重: {weights.shape}")
```
### ❌ 常见错误
| 错误写法 | 为什么错 | 正确写法 |
|---------|---------|---------|
| `d_model % num_heads != 0` | 无法均分维度 | 确保整除,如 768/12=64 |
| `num_heads` 设成 100 | 头太多,每个头维度太小 | 一般 4-16 头 |
| 混淆 `transpose(1, 2)` 和 `transpose(2, 3)` | 维度乱了 | 先确认当前维度顺序 |
| 不使用 `contiguous()` | view 需要连续内存 | reshape 前加 `.contiguous()` |
---
### 我的理解:多头注意力的直观解释
> **理解 1:多个"视角"看同一个问题**
>
> 想象你让 8 个不同背景的人看一幅画:
> - 画家看笔触技法
> - 历史学家看时代背景
> - 普通观众看情感表达
> - 收藏家看价值
>
> 多头注意力就是这个道理——每个头从不同角度理解文本。
> **理解 2:参数效率**
>
> 有趣的是,多头注意力和单头注意力的参数量几乎相同!
>
> ```
> 单头 d_model=256: W_Q, W_K, W_V 都是 [256, 256]
> 多头 8 头 d_k=32: W_Q, W_K, W_V 都是 [256, 32*8] = [256, 256]
> ```
>
> 维度切分后,总参数量相同,但表达能力更强。
> **理解 3:头数的选择**
>
> 常见设置:
> - BERT-base: 12 头,d_model=768,d_k=64
> - GPT-2: 12 头,d_model=768,d_k=64
> - LLaMA: 32 头,d_model=4096,d_k=128
>
> 头数不是越多越好,需要和模型大小匹配。
---
### 常见问题
**Q1: 多个头之间是独立的吗?**
> A: 是的,在数学上它们是独立的。但它们共享同一个输入 X,共享参数空间 W_Q, W_K, W_V,只是切片不同。
**Q2: 每个头学到的内容一样吗?**
> A: 不一样!通过可视化可以发现,不同的头确实关注不同的方面(如语法、语义、位置等)。这是 Multi-Head Attention 的核心价值。
**Q3: 如何决定用多少个头?**
> A: 经典设置是 d_model/64。例如 d_model=768 时,用 12 头(768/64=12)。BERT 和 GPT 都遵循这个原则。
**Q4: 多头注意力和卷积神经网络 (CNN) 有什么相似之处?**
> A: 都有"并行处理局部特征"的特性。但 CNN 用固定的卷积核,而 Attention 是动态的、由数据驱动的。
---
## 4.3 位置编码
> 如果把 "I love you" 变成 "you love I",Self-Attention 算出来的结果是一样的——因为它根本不知道词语的顺序!位置编码就是给 Transformer 装上"顺序感"的秘密武器。
---
### 为什么需要位置编码?
**Self-Attention 是位置无关的**:
```
同一个句子,不同顺序:
"I love you" → 编码器编码
"you love I" → 编码器编码
结果:完全相同!
因为 Self-Attention 只看内容相似度,不看位置
```
**这对 NLP 来说是致命的**:
```
"狗咬人" vs "人咬狗"
"我爱你" vs "你爱我"
"小王欠小李500元" vs "小李欠小王500元"
位置完全不同,意思可能完全相反!
```
---
### 正弦/余弦位置编码
**公式**:
$$PE_{(pos, 2i)} = \sin\left(\frac{pos}{10000^{2i/d_{model}}}\right)$$
$$PE_{(pos, 2i+1)} = \cos\left(\frac{pos}{10000^{2i/d_{model}}}\right)$$
**可视化表示**:
```
位置编码矩阵 PE [max_len, d_model]:
维度 0 维度 1 维度 2 维度 3 ... 维度 d
位置 0 ┌────────┬────────┬────────┬────────┬───────┐
│ sin(0) │ cos(0) │ sin(0) │ cos(0) │ ... │
├────────┼────────┼────────┼────────┼───────┤
位置 1 │ sin(1) │ cos(1) │ sin(1) │ cos(1) │ ... │
├────────┼────────┼────────┼────────┼───────┤
位置 2 │ sin(2) │ cos(2) │ sin(2) │ cos(2) │ ... │
├────────┼────────┼────────┼────────┼───────┤
│ ... │ ... │ ... │ ... │ ... │
└────────┴────────┴────────┴────────┴───────┘
规律:
- 偶数维度(2i):使用 sin
- 奇数维度(2i+1):使用 cos
- 频率从高频到低频:10000^(0/d), 10000^(2/d), ...
```
**为什么选择 sin 和 cos?**
```
独特性质:相对位置可以通过线性变换获取
PE(pos + k) 可以用 PE(pos) 的线性组合表示!
这意味着模型可以通过简单的线性变换,
直接学习到相对位置关系!
```
**直观理解**:
```
类比:就像时钟的指针
- 短针(高频):快速变化,记录精确位置
- 长针(低频):缓慢变化,记录大概范围
```
---
### 旋转位置编码 (RoPE)
**什么是 RoPE?**
RoPE(Rotary Position Embedding)是一种新型的位置编码,被 LLaMA、GLM 等模型广泛使用。
**核心思想**:不直接把位置编码加到 embedding 上,而是通过**旋转操作**融入位置信息。
**2维旋转示意图**:
```
原始向量 q₀ = (x, y)
位置 m 的旋转:
y
↑
│ · q_m (旋转后)
│ /│
│ / │ 角度 = mθ
│ / │
│/ θ │
───────┼────┼────────────────→ x
/│ │
/ │ │
/ │ │ θ = 基础频率
· │ │ m = 位置
q₀ │ │
│ │
旋转后坐标:
x' = x·cos(mθ) - y·sin(mθ)
y' = x·sin(mθ) + y·cos(mθ)
```
**Attention 计算时**:
```
两个旋转后的 Query 和 Key 做点积:
<RoPE(q_m), RoPE(k_n)> = <q_m, k_n> (只与 m-n 有关!)
这意味着:RoPE 的注意力只依赖相对位置!
```
**RoPE vs Sinusoidal 对比**:
```
┌────────────────┬──────────────────────────────────────────────┐
│ 方法 │ 特点 │
├────────────────┼──────────────────────────────────────────────┤
│ Sinusoidal │ 绝对位置编码,需要模型学习相对位置 │
│ (原始Transformer)│ 外推性有限 │
├────────────────┼──────────────────────────────────────────────┤
│ RoPE │ 通过旋转隐式编码相对位置 │
│ (LLaMA, GLM) │ 数学上保证相对位置关系,更好支持长序列 │
└────────────────┴──────────────────────────────────────────────┘
```
---
## 4.4 Layer Norm / Feed Forward / 残差连接
> 如果说 Self-Attention 是 Transformer 的"大脑",那么 Layer Norm、Feed Forward 和残差连接就是它的"骨骼"——它们支撑着 Attention 正常工作,让深层网络能够高效训练。
---
### Layer Norm vs Batch Norm
**先理解归一化的作用**:
```
数据分布问题:
- 输入数据尺度不一致(有的很大,有的很小)
- 梯度消失/爆炸
- 训练不稳定
归一化解决:
- 把数据转换成稳定的分布
- 加速训练
- 提高泛化能力
```
### 两种归一化的核心区别
```
Batch Norm:对 batch 维度统计(跨样本)
Layer Norm:对单个样本内部统计(样本内)
假设输入 [batch=4, seq_len=5, d_model=8]
Layer Norm(对最后 d_model 维):
对每个样本的每个位置,分别归一化
统计范围:5 × 8 = 40 个值
独立处理 4 × 5 = 20 个位置
Batch Norm(对 batch 维度):
对每个特征维度,跨 batch 统计
统计范围:4 个样本的同一特征
需要 batch 有一定大小
```
### 可视化对比
```
Batch Norm Layer Norm
输入形状: [batch, seq_len, d_model] [batch, seq_len, d_model]
│ │
▼ ▼
统计维度: ┌─────────────────────┐ ┌─────────────────────┐
│ 对 batch 维度统计 │ │ 对 d_model 维度统计 │
│ (跨样本) │ │ (样本内) │
└─────────────────────┘ └─────────────────────┘
│ │
▼ ▼
结果: 每个特征维度独立归一化 每个位置的 d_model 维归一化
```
### 为什么 NLP 用 Layer Norm?
```
NLP 任务的特点:
1. 序列长度变化大
- 句子1: "Hello"
- 句子2: "Hello, how are you today?"
2. Batch 大小可能很小
- 在线推理: batch=1
- 预训练大模型: batch 受限于显存
3. 每个位置需要独立归一化
- "Hello" 的统计量 ≠ "Hello, how..." 的统计量
Layer Norm 完美适配这些特点!
```
---
### Feed Forward Network
#### 结构
```
输入: [batch, seq_len, d_model] = [B, L, 768]
│
▼
线性变换: [B, L, 768] × [768, 3072] = [B, L, 3072]
│
▼
激活函数: GELU(x)
│
▼
Dropout: 随机置零一些神经元
│
▼
线性变换: [B, L, 3072] × [3072, 768] = [B, L, 768]
│
▼
Dropout: 随机置零
│
▼
输出: [batch, seq_len, d_model] = [B, L, 768]
```
#### 为什么需要 FFN?
```
Attention 的能力:
- 捕捉 token 之间的关联
- 动态计算权重
- 但它是线性变换的组合
FFN 的能力:
- 引入非线性
- 逐位置变换(Position-wise)
- 增加模型容量
一个比喻:
Attention = 交流信息
FFN = 消化信息
没有 FFN 的 Transformer ≈ 没有激活函数的神经网络
```
#### FFN 参数占比
```
Transformer 参数分布:
Multi-Head Attention: ~1/3
- W_Q, W_K, W_V: d_model × d_model × 3
- W_O: d_model × d_model
Feed Forward: ~2/3
- W_1: d_model × d_ff (通常 d_ff = 4 × d_model)
- W_2: d_ff × d_model
所以 FFN 占据了 Transformer 大部分参数!
```
---
### 残差连接
#### 什么是残差?
```
普通网络:
输出 = f(输入)
残差网络:
输出 = 输入 + f(输入)
其中 f(输入) 是"残差",输入是"恒等映射"
```
#### 为什么残差有效?
```
问题:深层网络的梯度消失
输入 ──→ [Layer 1] ──→ [Layer 2] ──→ ... ──→ [Layer N] ──→ 输出
梯度传播路径很长,每个 Layer 都会"衰减"一些梯度
深层网络的前面层几乎收不到梯度
残差连接:
输入 ──┐
│
├──→ [Layer 1] ──→ [Layer 2] ──→ ... ──→ [Layer N] ──┐
│ │
└───────────────────────────────────────────────────────┘
+
输出
梯度可以直接从输出传回输入:
∂输出/∂输入 = 1 + ∂(所有层)/∂输入
1 确保梯度至少是 1,不会完全消失!
```
---
### 完整 Encoder Block
#### 结构图
```
┌──────────────────────────────────────────────────────────────┐
│ Encoder Block │
├──────────────────────────────────────────────────────────────┤
│ │
│ 输入 x ─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ Multi-Head Self-Attention │ │ │
│ │ │ │ │ │
│ │ │ x ─→ W_Q,W_K,W_V ─→ Q,K,V │ │ │
│ │ │ ↓ │ │ │
│ │ │ 分成 h=8 个头并行计算 │ │ │
│ │ │ ↓ │ │ │
│ │ │ Scaled Dot-Product Attention │ │ │
│ │ │ ↓ │ │ │
│ │ │ Concat → W_O → 输出 │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Add & LayerNorm ────────────┐ │ │
│ │ │ │ │ │
│ └────────────────────────┼──────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────┐ │ │
│ │ │ Feed Forward │ │ │
│ │ │ │ │ │
│ │ │ Linear(d→4d) │ │ │
│ │ │ ↓ │ │ │
│ │ │ GELU │ │ │
│ │ │ ↓ │ │ │
│ │ │ Linear(4d→d) │ │ │
│ │ └──────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Add & LayerNorm ────┼───┼──→ 输出
│ │ │ │ │
│ └────────────┴─────────────┘ │
└──────────────────────────────────────────────────────────────┘
```
#### PyTorch 实现
```python
import torch
import torch.nn as nn
import torch.nn.functional as F
import math
class TransformerEncoderBlock(nn.Module):
"""
完整的 Transformer Encoder Block
"""
def __init__(self, d_model, num_heads, d_ff, dropout=0.1):
super().__init__()
# Multi-Head Self-Attention
self.self_attn = nn.MultiheadAttention(
embed_dim=d_model,
num_heads=num_heads,
dropout=dropout,
batch_first=True
)
# Layer Normalization
self.norm1 = nn.LayerNorm(d_model)
self.norm2 = nn.LayerNorm(d_model)
# Feed Forward Network
self.ffn = nn.Sequential(
nn.Linear(d_model, d_ff),
nn.GELU(), # 常用 GELU 而不是 ReLU
nn.Dropout(dropout),
nn.Linear(d_ff, d_model),
nn.Dropout(dropout)
)
def forward(self, x, mask=None):
"""
参数:
x: [batch, seq_len, d_model]
mask: attention mask
返回:
x: [batch, seq_len, d_model]
"""
# ====== Self-Attention + 残差连接 ======
# 计算注意力
attn_out, _ = self.self_attn(x, x, x, attn_mask=mask)
# 残差连接 + Layer Norm
x = self.norm1(x + attn_out)
# ====== FFN + 残差连接 ======
# FFN
ffn_out = self.ffn(x)
# 残差连接 + Layer Norm
x = self.norm2(x + ffn_out)
return x
# ============ 完整 Transformer Encoder ============
class TransformerEncoder(nn.Module):
"""
多层 Transformer Encoder
"""
def __init__(self, num_layers, d_model, num_heads, d_ff, dropout=0.1):
super().__init__()
self.layers = nn.ModuleList([
TransformerEncoderBlock(d_model, num_heads, d_ff, dropout)
for _ in range(num_layers)
])
# 可选:最终 Layer Norm
self.final_norm = nn.LayerNorm(d_model)
def forward(self, x, mask=None):
for layer in self.layers:
x = layer(x, mask)
return self.final_norm(x)
# ============ 测试 ============
if __name__ == "__main__":
# 参数设置(类似 BERT-base)
batch, seq_len = 2, 32
d_model = 768
num_heads = 12
d_ff = d_model * 4 # 3072
num_layers = 6
# 输入
x = torch.randn(batch, seq_len, d_model)
# 创建模型
encoder = TransformerEncoder(num_layers, d_model, num_heads, d_ff)
# 前向传播
output = encoder(x)
print(f"📥 输入: {x.shape}")
print(f"📤 输出: {output.shape}")
print(f"🏗️ 参数量: {sum(p.numel() for p in encoder.parameters()):,}")
```
---
## 常见问题
**Q1: Layer Norm 的 normalized_shape 应该怎么设?**
> A: 如果输入是 `[B, L, D]`,设 `normalized_shape=D`。如果输入是 `[B, D]`,设 `normalized_shape=D`。
**Q2: FFN 为什么要用 GELU 而不是 ReLU?**
> A: GELU 是 ReLU 的平滑版本,负数也有小的梯度。在 Transformer 中效果更好(BERT、GPT 都用 GELU)。
**Q3: 为什么残差连接后面要 Layer Norm?**
> A: 这被称为 "Post-LN"。还有一种 "Pre-LN" 是在残差之前做 Layer Norm。两种方式各有优劣,Post-LN 更常用但训练不稳定,Pre-LN 更稳定但效果略差。
**Q4: FFN 的中间维度为什么是 4 倍?**
> A: 这是 Transformer 论文中的经验设置。实验表明 4 倍扩展在大多数任务中效果最好。太小容量不够,太大参数量爆炸。
**Q5: Transformer 有多少参数?**
> A:
> ```
> BERT-base: 110M 参数
> - 12 层 Encoder
> - d_model=768, num_heads=12, d_ff=3072
>
> BERT-large: 340M 参数
> - 24 层 Encoder
> - d_model=1024, num_heads=16, d_ff=4096
> ```
---
## 验收标准
```
□ 能用通俗语言解释什么是 Self-Attention
□ 能画出 Q/K/V 的计算流程图
□ 能写出缩放点积注意力的数学公式
□ 能手写 Self-Attention 的 PyTorch 代码
□ 知道为什么要除以 √d_k
□ 理解 Mask 的作用(Padding Mask vs Future Mask)
□ 能画出注意力权重矩阵
□ 能解释 Self-Attention 的时间复杂度
□ 能解释为什么要用多头注意力
□ 能写出 Multi-Head Attention 的数学公式
□ 能画出多头注意力的计算流程图
□ 能在 PyTorch 中实现多头注意力
□ 能对比单头和多头的参数量和表达能力
□ 知道常见的头数设置(BERT: 12头, LLaMA: 32头)
□ 能解释为什么 Self-Attention 需要位置编码
□ 能写出 Sinusoidal 位置编码的公式
□ 能在 PyTorch 中实现位置编码
□ 能对比 Sinusoidal 和 Learned 位置编码
□ 能理解 RoPE 的核心思想
□ 能对比 Batch Norm 和 Layer Norm 的区别
□ 能解释为什么 NLP 任务用 Layer Norm
□ 能写出 Layer Norm 的公式
□ 能画出 FFN 的结构图
□ 能解释残差连接的作用
□ 能画出完整的 Transformer Encoder Block 结构图
□ 能在 PyTorch 中实现完整的 Encoder Block
□ 能估算 Transformer 的参数量
```
---
## 官方来源
- **原始论文**: [Attention Is All You Need](https://arxiv.org/abs/1706.03762)
- **PyTorch 官方实现**: [torch.nn.MultiheadAttention](https://pytorch.org/docs/stable/generated/torch.nn.MultiheadAttention.html)
- **Layer Norm 论文**: [Layer Normalization](https://arxiv.org/abs/1607.06450)
- **RoPE 论文**: [RoFormer: Enhanced Transformer with Rotary Position Embedding](https://arxiv.org/abs/2104.09864)
- **DataWhale Happy-LLM**: [第二章 Transformer 架构](https://datawhalechina.github.io/happy-llm/#/./chapter2)
---
## 参考文献
[1] Vaswani et al., "Attention Is All You Need", NeurIPS 2017
[2] Jay Alammar, "The Illustrated Transformer": http://jalammar.github.io/illustrated-transformer/
[3] Lilian Weng, "Attention? Attention!": https://lilianweng.github.io/posts/2018-06-24-attention/
[4] Ba et al., "Layer Normalization", 2016
[5] Su et al., "RoFormer: Enhanced Transformer with Rotary Position Embedding", 2022
...@@ -145,7 +145,7 @@ def validate_item(f): ...@@ -145,7 +145,7 @@ def validate_item(f):
@app.route("/items/", methods=["POST"]) @app.route("/items/", methods=["POST"])
@validate_item @validate_item
def create_item(data): def create_item(data):
return jsonify({"item_id": 42, **data}) return jsonify({"item_id": 42, "data": data})
@app.route("/items/<int:item_id>", methods=["GET"]) @app.route("/items/<int:item_id>", methods=["GET"])
...@@ -839,7 +839,7 @@ session.add_all([s1, s2, c1]) ...@@ -839,7 +839,7 @@ session.add_all([s1, s2, c1])
session.commit() session.commit()
# 查询 # 查询
alice_posts = session.query(Post).filter_by(author_id=user.id).all() alice_posts = session.query(Post).filter(Post.author_id == user.id).all()
python_students = session.query(Student).filter(Student.courses.any(name="Python 入门")).all() python_students = session.query(Student).filter(Student.courses.any(name="Python 入门")).all()
``` ```
......
# 模块三:深度学习基础
> 本模块涵盖深度学习中最重要的基础概念:激活函数、损失函数、优化器,以及神经网络的核心工作机制——前向传播与反向传播。掌握这些内容,是理解一切深度学习模型的根基。
---
## 3.1 激活函数
> 激活函数决定了神经元是否应该被"激活",就像生活中的"开关"——只有达到一定条件,才会让信号通过。
---
### 什么是激活函数?
**一句话定义**:激活函数是非线性函数,它给神经网络提供"非线性能力",让网络能学习复杂的模式。
**为什么重要?**
- 如果没有激活函数,多层神经网络 = 线性变换 = 等于一层
- 激活函数让网络能拟合任意复杂的非线性关系
- 不同的激活函数适用于不同的场景
**生活类比**:就像水龙头的阀门
- 水压(输入)太小,阀门不开,水流(输出)为零
- 水压超过阈值,阀门打开,水流开始通过
- 这就是 ReLU 的工作原理!
---
### 举个例子
### 输入输出
```
输入:张量 [x1, x2, x3, ...]
↓
激活函数:f(x)
↓
输出:变换后的值 [y1, y2, y3, ...]
```
### 不同激活函数的对比
| 激活函数 | 公式 | 输出范围 | 适用场景 |
|---------|------|---------|---------|
| Sigmoid | σ(x) = 1/(1+e⁻ˣ) | (0, 1) | 二分类输出层 |
| Tanh | tanh(x) | (-1, 1) | 隐藏层(已较少使用)|
| ReLU | f(x) = max(0, x) | [0, +∞) | 隐藏层(默认选择)|
| Leaky ReLU | f(x) = max(0.01x, x) | (-∞, +∞) | 隐藏层(ReLU替代)|
| GELU | f(x) = x·Φ(x) | (-∞, +∞) | Transformer(如BERT)|
| ELU | f(x) = x (x>0);α(eˣ−1) (x≤0) | (-α, +∞) | 隐藏层(负值更平滑)|
| Softmax | σ(zᵢ) = e^(zᵢ)/Σe^(zⱼ) | (0, 1),和为1 | 多分类输出层 |
---
### 正解 vs 错误
### ✅ 正确做法
```
# 1. 隐藏层用 ReLU(最常用)
import torch.nn as nn
layer = nn.ReLU()
# 2. 二分类输出层用 Sigmoid
layer = nn.Sigmoid()
# 3. 多分类输出层用 Softmax
layer = nn.Softmax(dim=1)
```
### ❌ 常见错误
| 错误做法 | 问题 | 正确做法 |
|---------|------|---------|
| 隐藏层用 Sigmoid | 梯度消失严重 | 改用 ReLU |
| 输出层用 ReLU | 输出无负值 | 改用 Sigmoid/Softmax |
| 学习率太大 + ReLU | 神经元"死亡" | 降低学习率或用 Leaky ReLU |
| 不加激活函数 | 网络退化为线性 | 隐藏层必须加激活函数 |
---
## 原理深入
### 3.1.1 Sigmoid(公式 / 梯度消失)
**数学公式**:
$$\sigma(x) = \frac{1}{1 + e^{-x}}$$
**图像**:
![Sigmoid 函数图像](images/sigmoid.png)
*图:Sigmoid 函数及其导数 σ'(x)=σ(x)(1−σ(x))*
**特点**:
- 输出平滑,介于 (0, 1) 之间
- 可以概率解释
**致命问题——梯度消失**:
- 当 x 很大或很小时,梯度 ≈ 0
- 反向传播时,前面层的梯度几乎传不下去
- 深层网络训练困难
### 3.1.2 Tanh
**数学公式**:
$$\tanh(x) = \frac{e^x - e^{-x}}{e^x + e^{-x}}$$
**图像**:
![Tanh 函数图像](images/tanh.png)
*图:Tanh 函数及其导数 1−tanh²(x),均值接近 0 收敛更快*
**特点**:
- 输出在 (-1, 1) 之间
- 均值接近 0,收敛更快
- 同样存在梯度消失问题
### 3.1.3 ReLU(死亡 ReLU 问题)
**数学公式**:
$$f(x) = \max(0, x)$$
**图像**:
![ReLU 函数图像](images/relu.png)
*图:ReLU 函数及其导数,x>0 梯度恒为 1 是其核心优势*
**优点**:
- 计算极快(就是一个 max 操作)
- 缓解梯度消失问题
- 收敛速度快
**致命问题——死亡 ReLU(Dying ReLU)**:
```
现象:某神经元输出永远为 0,再也不更新
原因:梯度为 0 时,权重无法更新
  初始权重过大或偏置不当 → 输出全落负半轴
  → ReLU 输出全 0 → 梯度全 0 → 参数永远停在初始值
过程示意:
初始化权重过大
↓
某神经元加权求和 w·x + b 全为负
↓
ReLU(负数) = 0
↓
反向传播梯度 = 0
↓
该神经元永远"死亡",不再参与学习
```
**解决方案**:
1. **Leaky ReLU**:f(x) = max(0.01x, x),负区保留小梯度
2. **PReLU**:f(x) = max(αx, x),α 可学习
3. **ELU**:f(x) = x, (x>0);α(eˣ−1), (x≤0),负区更平滑
4. 降低学习率,避免参数大幅跳入负区
5. **He 初始化**(配合 ReLU 专门设计)
> ⚠️ **`inplace=True` 的额外风险**:`nn.ReLU(inplace=True)` 会直接修改输入 tensor。如果后续代码依赖该输入的值(如 Skip Connection 中的残差),inplace 操作会无声地破坏残差分支的梯度,导致训练困难。**训练阶段建议使用默认的 `inplace=False`,推理阶段再改为 `True` 节省显存。**
### 3.1.4 Leaky ReLU / GELU
**Leaky ReLU**:
$$f(x) = \max(0.01x, x)$$
**图像**:
![Leaky ReLU 函数图像](images/leaky_relu.png)
*图:Leaky ReLU x<0 时仍保留 0.01 的小梯度,避免死亡神经元*
- x < 0 时有一个很小但不为零的梯度
**GELU(Gaussian Error Linear Unit)**:
$$f(x) = x \cdot \Phi(x)$$
其中 Φ(x) 是标准正态分布的累积分布函数。
**图像**:
![GELU 函数图像](images/gelu.png)
*图:GELU 及其导数 Φ(x)+xφ(x),比 ReLU 在 0 附近更平滑*
- Transformer 标配(如 BERT、GPT)
- 比 ReLU 更平滑,效果更好
- 计算稍复杂
### 3.1.5 Softmax(多分类)
**数学公式**:
$$\text{Softmax}(z_i) = \frac{e^{z_i}}{\sum_{j=1}^{K} e^{z_j}}$$
**作用**:将一组实数转换为概率分布,所有输出和为 1
**示例**:
```
输入:z = [2.0, 1.0, 0.1]
输出:σ(z) = [0.7, 0.2, 0.1]
(和为 1,可以解释为概率)
```
---
### 3.1.6 权重初始化(衔接梯度消失与激活函数的关键)
**为什么初始化很重要?**
权重初始值决定了网络训练的起点。初始化太大会导致梯度爆炸,太小会导致梯度消失。初始化方法必须与激活函数匹配。
**三种主流初始化方法**:
| 方法 | 适用激活函数 | 公式 | PyTorch |
|------|------------|------|---------|
| **Xavier (Glorot)** | Sigmoid / Tanh | W ~ N(0, 2/(n_in + n_out)) | `nn.init.xavier_uniform_` |
| **Kaiming (He)** | ReLU / Leaky ReLU / GELU | W ~ N(0, 2/n_in) | `nn.init.kaiming_normal_` |
| **正交初始化** | RNN / LSTM | W · Wᵀ = I | `nn.init.orthogonal_` |
> **经验法则**:ReLU 家族用 Kaiming,Tanh/Sigmoid 用 Xavier。PyTorch 中 `nn.Linear` 默认已使用 Kaiming uniform(对 ReLU 友好),但自定义层或特殊结构时需要手动初始化。
**为什么 Kaiming 适合 ReLU?**
```
ReLU 会把负值置零,相当于每次把一半的信号"杀掉"。
如果不补偿,输出方差会逐层减半:
Var(y) = Var(x) / 2 (每经过一层 ReLU)
→ 深层网络信号趋近 0 → 梯度消失
Kaiming 初始化把权重方差加大:
Var(W) = 2 / n_in
→ 补偿 ReLU 的"信号损失",保持各层方差稳定
```
**PyTorch 代码示例**:
```python
import torch
import torch.nn as nn
class CustomNet(nn.Module):
def __init__(self):
super().__init__()
self.fc1 = nn.Linear(784, 256)
self.fc2 = nn.Linear(256, 10)
# 手动权重初始化(配合 ReLU)
nn.init.kaiming_normal_(self.fc1.weight, mode='fan_out', nonlinearity='relu')
nn.init.kaiming_normal_(self.fc2.weight, mode='fan_out', nonlinearity='relu')
nn.init.zeros_(self.fc1.bias)
nn.init.zeros_(self.fc2.bias)
def forward(self, x):
x = torch.relu(self.fc1(x))
return self.fc2(x)
# 验证初始化效果
model = CustomNet()
print("fc1 weight mean:", model.fc1.weight.mean().item())
print("fc1 weight std:", model.fc1.weight.std().item())
```
**常见错误**:
| 错误做法 | 问题 | 正确做法 |
|---------|------|---------|
| 全部用 `torch.randn()` 默认初始化 | 方差不确定,训练不稳定 | 用 `nn.init` 方法匹配激活函数 |
| 初始化偏置全为 0(对于 BatchNorm 层) | 第一个 epoch 输出全为 0 | BatchNorm 偏置可初始化为 0,但权重需正确初始化 |
| 对所有层用相同的 Xavier | ReLU 层梯度可能消失 | ReLU 层用 Kaiming |
---
### 实战代码
```python
import torch
import torch.nn as nn
# 3.1.1 Sigmoid
sigmoid = nn.Sigmoid()
x = torch.tensor([0.0, 2.0, -2.0])
print(f"Sigmoid: {sigmoid(x)}")
# 输出: tensor([0.5000, 0.8808, 0.1192])
# 3.1.2 Tanh
tanh = nn.Tanh()
print(f"Tanh: {tanh(x)}")
# 输出: tensor([ 0.0000, 0.9640, -0.9640])
# 3.1.3 ReLU
relu = nn.ReLU()
print(f"ReLU: {relu(x)}")
# 输出: tensor([0., 2., 0.])
# 3.1.4 Leaky ReLU
leaky_relu = nn.LeakyReLU(negative_slope=0.01)
print(f"LeakyReLU: {leaky_relu(x)}")
# 输出: tensor([-0.0200, 2.0000, -0.0200])
# 3.1.5 Softmax
softmax = nn.Softmax(dim=0)
z = torch.tensor([2.0, 1.0, 0.1])
print(f"Softmax: {softmax(z)}")
# 输出: tensor([0.6590, 0.2424, 0.0986])
print(f"Sum: {softmax(z).sum()}") # 验证和为1
```
---
### 常见问题
**Q1: 隐藏层应该用哪个激活函数?**
> A: 默认选择 **ReLU**。如果遇到死亡神经元问题,换成 **Leaky ReLU** 或 **GELU**。
**Q2: 为什么 ReLU 可以缓解梯度消失?**
> A: 对于 x > 0,ReLU 的梯度恒为 1,不会像 Sigmoid/Tanh 那样在两端趋近于 0。
**Q3: 输出层用哪个激活函数?**
> A: 根据任务决定:
> - 二分类:Sigmoid(输出 0~1 表示概率)
> - 多分类:Softmax(输出各类别的概率)
> - 回归任务:通常不加激活函数(或者根据输出范围选择)
**Q4: 多个激活函数可以叠加吗?**
> A: 可以在不同层使用不同的激活函数,但通常隐藏层统一用一种效率高的(如 ReLU)。
**Q5: 什么时候用 `inplace=True`?**
> A: 仅在**推理阶段**或确认后续不再需要原输入值时使用(如推理时的推理模型)。训练时用默认值 `inplace=False`,否则可能破坏 Skip Connection 等依赖原输入的梯度计算。
**Q6: Softmax 的数值稳定性问题?**
> A: 当输入值很大时,e^x 可能溢出。正确做法是减去最大值:
```python
def stable_softmax(z):
z_max = z.max()
exp_z = torch.exp(z - z_max)
return exp_z / exp_z.sum()
```
> 注:`nn.CrossEntropyLoss` 内部已做稳定化处理,不需要手动写。
---
### 验收标准
```
□ 能解释为什么需要激活函数(非线性能力)
□ 能对比 Sigmoid、ReLU、Softmax 的适用场景
□ 能说明梯度消失问题及 ReLU 的优势
□ 能在 PyTorch 中正确使用各种激活函数
□ 能处理 Softmax 的数值稳定性问题
□ 能根据任务选择合适的输出层激活函数
```
---
### 官方来源
- PyTorch 激活函数文档:https://pytorch.org/docs/stable/nn.html#non-linear-activations-weighted-lookup-non-linear
- ReLU 论文:Nair & Hinton, "Rectified Linear Units Improve Restricted Boltzmann Machines", 2010
- GELU 论文:Hendrycks & Gimpel, "Gaussian Error Linear Units (GELUs)", 2016
---
### 参考文献
[1] Goodfellow et al., *Deep Learning*, Chapter 6
[2] https://nn.readthedocs.io/en/rtd/activation/
---
## 3.2 损失函数
> 损失函数是训练的"指南针"——它告诉我们当前模型的预测有多差,指引优化器找到正确的方向。
---
### 什么是损失函数?
**一句话定义**:损失函数衡量模型预测值与真实值之间的差距,损失越小,模型越好。
**为什么重要?**
- 损失函数定义了优化目标
- 不同的任务需要不同的损失函数
- 损失函数的选择直接影响模型效果
**生活类比**:就像考试得分
- 损失函数 = 扣掉的分数
- 我们的目标是让扣分最少(损失最小)
- 优化器 = 学习方法,帮我们提高成绩
---
### 举个例子
### 分类任务的损失
```
真实标签:[猫, 狗, 鸟]
预测概率:[0.7, 0.2, 0.1]
损失 = -log(0.7) = 0.357 (猫的概率越高,损失越小)
```
### 回归任务的损失
```
真实值:[3.0, 2.5, 4.0]
预测值:[2.8, 2.7, 3.9]
MSE = [(3-2.8)² + (2.5-2.7)² + (4-3.9)²] / 3 = 0.07
```
**损失函数的几何意义**:
![损失函数的几何意义](images/loss_geometry.png)
*图:左轴蓝色抛物线是 MSE=(y−ŷ)²,红框示意某点预测误差的"平方面积";右轴橙色/绿色是 BCE 的 −log(ŷ) 和 −log(1−ŷ) 曲线,可见当预测概率接近 0(但真实为 1)时,BCE 损失会急剧飙升,这就是为什么分类模型错得越离谱、惩罚越大*
---
### 正解 vs 错误
### ✅ 正确做法
```python
import torch
import torch.nn as nn
# 分类任务:多分类
criterion = nn.CrossEntropyLoss()
# 分类任务:二分类
criterion = nn.BCEWithLogitsLoss()
# 回归任务
criterion = nn.MSELoss()
```
### ❌ 常见错误
| 错误做法 | 问题 | 正确做法 |
|---------|------|---------|
| 多分类用 MSE | 梯度不稳定,效果差 | 用 CrossEntropyLoss |
| 二分类用 CrossEntropyLoss + Sigmoid | 冗余 | 直接用 BCEWithLogitsLoss |
| 回归任务用交叉熵 | 梯度可能为 0 | 用 MSELoss 或 SmoothL1Loss |
| 不做损失归一化 | 不同任务损失量级不同 | 必要时做归一化 |
---
## 原理深入
### 3.2.1 交叉熵损失(CrossEntropyLoss)
**数学公式**:
$$L = -\sum_{i} y_i \log(\hat{y}_i)$$
其中 y_i 是真实标签(one-hot),ŷ_i 是预测概率。
**为什么分类用它?**
- 概率解释:最小化交叉熵 = 最大化似然 = 让正确类别的概率最大
- 梯度特性:当预测错误时,梯度大,学习快;当预测正确时,梯度小,趋于稳定
**PyTorch 实现**:
```python
# nn.CrossEntropyLoss = LogSoftmax + NLLLoss
# 输入:raw logits(未经 softmax)
# 目标:class indices(不是 one-hot)
```
**示例**:
```python
import torch
import torch.nn as nn
criterion = nn.CrossEntropyLoss()
# 4个样本,3个类别
logits = torch.tensor([[2.0, 1.0, 0.1], # 样本1预测:类别0最可能
[0.5, 2.0, 0.3], # 样本2预测:类别1最可能
[1.0, 0.5, 1.5], # 样本3预测:类别2最可能
[0.5, 0.5, 1.0]]) # 样本4预测:类别2最可能
targets = torch.tensor([0, 1, 2, 2]) # 真实标签
loss = criterion(logits, targets)
print(f"CrossEntropyLoss: {loss.item():.4f}")
```
**三种损失函数曲线对比**:
![损失函数对比](images/loss_comparison.png)
*图:(a) 回归损失 MSE(L2) vs MAE(L1) 对比——MSE 对大误差更敏感(平方放大),MAE 对小误差更敏感(绝对值放大);(b) 二分类 BCE:ŷ→0 但 y=1 时损失暴涨,ŷ=0.5(最不确定)时损失=0.69;(c) 多分类 CE:预测正确类别概率越接近 1,损失越接近 0*
### 3.2.2 二分类交叉熵(BCEWithLogitsLoss)
**数学公式**:
$$L = -[y \cdot \log(\hat{y}) + (1-y) \cdot \log(1-\hat{y})]$$
**为什么用 Logits?**
- BCEWithLogitsLoss 内部做了 sigmoid
- 比先 sigmoid 再 BCE 更数值稳定
- 避免了 log(0) 的数值问题
**示例**:
```python
import torch
import torch.nn as nn
criterion = nn.BCEWithLogitsLoss()
# 4个二分类样本
logits = torch.tensor([2.0, -1.0, 0.5, -2.0]) # raw logits
targets = torch.tensor([1.0, 0.0, 1.0, 0.0]) # 真实标签
loss = criterion(logits, targets)
print(f"BCEWithLogitsLoss: {loss.item():.4f}")
# 也可以手动sigmoid看概率
probs = torch.sigmoid(logits)
print(f"Probabilities: {probs}") # [0.88, 0.27, 0.62, 0.12]
```
### 3.2.3 均方误差(MSE / MSELoss)
**数学公式**:
$$MSE = \frac{1}{n} \sum_{i=1}^{n}(y_i - \hat{y}_i)^2$$
**适用场景**:
- 回归任务
- 目标值连续变化
- 对离群值不敏感(相对地)
**示例**:
```python
import torch
import torch.nn as nn
criterion = nn.MSELoss()
predictions = torch.tensor([2.8, 2.7, 3.9])
targets = torch.tensor([3.0, 2.5, 4.0])
loss = criterion(predictions, targets)
print(f"MSELoss: {loss.item():.4f}")
# 手动验证
manual_mse = ((predictions - targets) ** 2).mean()
print(f"Manual MSE: {manual_mse.item():.4f}")
```
**SmoothL1Loss(Huber Loss)**:
```python
# 对离群值更鲁棒
criterion = nn.SmoothL1Loss()
loss = criterion(predictions, targets)
```
### 3.2.4 损失选择原则
```
任务类型 推荐损失函数
─────────────────────────────────
二分类 BCEWithLogitsLoss
多分类 CrossEntropyLoss
多标签分类 BCEWithLogitsLoss(每个标签独立)
回归(连续) MSELoss / SmoothL1Loss
回归(有离群值) SmoothL1Loss / HuberLoss
排序/推荐 MarginRankingLoss / ContrastiveLoss
```
---
### 3.2.5 正则化(防止过拟合的核心手段)
**为什么需要正则化?**
模型参数过多时,网络会"记住"训练数据的噪声,而不是学习真正的规律——这叫**过拟合(Overfitting)**。正则化通过给模型的复杂度施加惩罚,让模型学到的规律更通用。
**五种常见正则化方法**:
#### 1. L2 正则化(权重衰减)
$$L_{\text{total}} = L_{\text{original}} + \frac{\lambda}{2} \|\mathbf{w}\|_2^2$$
在优化器中通过 `weight_decay` 参数实现(相当于在梯度上加一项 `λw`)。SGD 中 `weight_decay` = L2;Adam 中 `weight_decay` ≠ 真正 L2,推荐用 AdamW。
```python
# AdamW(推荐):weight_decay 是真正的权重衰减
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-3, weight_decay=0.01)
# 普通 Adam:weight_decay 不是真正的 L2,不推荐混用
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3, weight_decay=0.01)
```
#### 2. L1 正则化(稀疏化)
$$L_{\text{total}} = L_{\text{original}} + \lambda \|\mathbf{w}\|_1$$
鼓励权重变成 0,可用于特征选择。PyTorch 没有内置 L1 正则化,需要手动在 loss 中加项:
```python
l1_loss = sum(p.abs().sum() for p in model.parameters())
total_loss = original_loss + lambda_ * l1_loss
```
#### 3. Dropout(训练时随机丢弃神经元)
训练时以概率 `p` 随机将神经元的输出置零;推理时所有神经元都参与但输出乘以 `(1-p)`。
```python
class Net(nn.Module):
def __init__(self):
super().__init__()
self.fc1 = nn.Linear(256, 128)
self.dropout = nn.Dropout(p=0.5) # 丢弃率 50%
self.fc2 = nn.Linear(128, 10)
def forward(self, x):
x = torch.relu(self.fc1(x))
x = self.dropout(x) # 训练时生效,推理时自动关闭
x = self.fc2(x)
return x
```
> **为什么 Dropout 有效?** 让网络不能依赖任何一个神经元,从而被迫学习更鲁棒的特征——相当于每次训练一个"不同的子网络",推理时取平均。
#### 4. 批量归一化(BatchNorm)
在每个 mini-batch 上对激活值做标准化(均值=0,方差=1),再学一个线性变换。既有正则化效果,又能加速收敛。
```python
class Net(nn.Module):
def __init__(self):
super().__init__()
self.fc1 = nn.Linear(784, 256)
self.bn1 = nn.BatchNorm1d(256) # 放在 Linear 之后、激活之前
self.fc2 = nn.Linear(256, 10)
def forward(self, x):
x = torch.relu(self.bn1(self.fc1(x))) # BN → Linear → 激活
return self.fc2(x)
```
> **注意**:BatchNorm 在训练时用 batch 统计量,在推理时用滑动平均的统计量。推理时若 batch_size=1(逐样本推理),BatchNorm 效果会退化,此时应改用 **LayerNorm** 或 **InstanceNorm**。
#### 5. Early Stopping(早停)
当验证集 loss 不再下降时,提前停止训练,避免在训练集上继续过拟合。
```python
best_val_loss = float('inf')
patience = 5 # 连续 5 个 epoch 验证集 loss 不下降就停止
counter = 0
for epoch in range(epochs):
train_loss = train_one_epoch(model, train_loader)
val_loss = evaluate(model, val_loader)
if val_loss < best_val_loss:
best_val_loss = val_loss
counter = 0
torch.save(model.state_dict(), 'best_model.pt') # 保存最优模型
else:
counter += 1
if counter >= patience:
print(f"早停:验证集 loss 连续 {patience} 个 epoch 未改善")
break
```
**正则化方法对比**:
| 方法 | 原理 | 适用场景 | 副作用 |
|------|------|---------|-------|
| L2 (AdamW) | 惩罚大权重 | 几乎所有任务 | 可能影响大权重有用的情况 |
| L1 | 稀疏化权重 | 特征选择、模型压缩 | 梯度不稳定 |
| Dropout | 随机丢弃神经元 | CNN / 全连接层 | 训练慢(两倍迭代)|
| BatchNorm | 标准化 + 仿射变换 | CV、CNN | 不适合 RNN / 小 batch |
| Early Stopping | 监控验证集 loss | 几乎所有任务 | 需要划分验证集 |
> **实战经验**:对于大多数任务,**AdamW + Dropout + 适量数据增强**是泛化性能最强的组合。BatchNorm 更多是加速收敛的技巧,而非专门的正则化手段。
---
### 实战代码
```python
import torch
import torch.nn as nn
def demo_all_losses():
print("=" * 50)
print("3.2 损失函数演示")
print("=" * 50)
# 1. CrossEntropyLoss(多分类)
print("\n1. CrossEntropyLoss(多分类):")
criterion = nn.CrossEntropyLoss()
logits = torch.tensor([[2.0, 1.0, 0.1],
[0.5, 2.0, 0.3]])
targets = torch.tensor([0, 1]) # 类别索引
loss = criterion(logits, targets)
print(f" 损失值: {loss.item():.4f}")
# 2. BCEWithLogitsLoss(二分类)
print("\n2. BCEWithLogitsLoss(二分类):")
criterion = nn.BCEWithLogitsLoss()
logits = torch.tensor([2.0, -1.0, 0.5])
targets = torch.tensor([1.0, 0.0, 1.0])
loss = criterion(logits, targets)
print(f" 损失值: {loss.item():.4f}")
# 3. MSELoss(回归)
print("\n3. MSELoss(回归):")
criterion = nn.MSELoss()
pred = torch.tensor([2.8, 2.7, 3.9])
target = torch.tensor([3.0, 2.5, 4.0])
loss = criterion(pred, target)
print(f" 损失值: {loss.item():.4f}")
# 4. 自定义权重
print("\n4. 带权重的 CrossEntropyLoss:")
criterion = nn.CrossEntropyLoss(weight=torch.tensor([1.0, 2.0, 0.5])) # 类别权重
logits = torch.tensor([[2.0, 1.0, 0.1],
[0.5, 2.0, 0.3]])
targets = torch.tensor([0, 1])
loss = criterion(logits, targets)
print(f" 损失值: {loss.item():.4f}")
if __name__ == "__main__":
demo_all_losses()
```
---
### 常见问题
**Q1: CrossEntropyLoss 和 NLLLoss 有什么区别?**
> A: CrossEntropyLoss = LogSoftmax + NLLLoss。你只需要用 CrossEntropyLoss,不需要手动做 softmax。
**Q2: 损失值多大算"好"?**
> A: 这取决于任务:
> - 二分类 BCE:理想趋近于 0
> - 多分类 CE:类别数为 N 时,随机预测约 log(N)
> - MSE:取决于目标值的量级
**Q3: 多标签分类用什么损失函数?**
> A: 用 BCEWithLogitsLoss,每个标签独立计算二分类损失。
**Q4: 损失不下降怎么办?**
> A: 检查:学习率是否合适、模型是否正确、损失函数是否匹配任务、数据是否有问题。
---
### 验收标准
```
□ 能解释损失函数在训练中的作用
□ 能对比 CrossEntropyLoss 和 MSELoss 的适用场景
□ 能在 PyTorch 中正确使用各种损失函数
□ 能根据任务类型选择合适的损失函数
□ 理解 BCEWithLogitsLoss 比手动 Sigmoid + BCE 更稳定
□ 知道如何给损失函数添加权重
```
---
### 官方来源
- PyTorch 损失函数文档:https://pytorch.org/docs/stable/nn.html#loss-functions
- Cross Entropy 解释:https://pytorch.org/docs/stable/generated/torch.nn.CrossEntropyLoss.html
---
### 参考文献
[1] Goodfellow et al., *Deep Learning*, Chapter 5
[2] https://ml-cheatsheet.readthedocs.io/en/latest/loss_functions.html
---
## 3.3 优化器
> 优化器是训练的"发动机"——它根据梯度方向,决定如何调整参数,让损失函数最小化。
---
### 什么是优化器?
**一句话定义**:优化器根据损失函数的梯度,决定如何更新模型参数。
**为什么重要?**
- 不同的优化器收敛速度差异很大
- 学习率等超参数直接影响训练效果
- 理解优化器才能调好模型
**生活类比**:就像下山找最低点
- 当前位置 = 当前模型参数
- 山的坡度 = 梯度
- 下山的步子 = 学习率
- 优化器 = 下山策略(走一步看一步 / 惯性冲 / 自适应步长)
---
### 举个例子
```
# 训练循环中的优化器使用
optimizer = torch.optim.Adam(model.parameters(), lr=0.001)
for epoch in range(epochs):
for batch in dataloader:
optimizer.zero_grad() # 1. 清零梯度
output = model(batch) # 2. 前向传播
loss = criterion(output) # 3. 计算损失
loss.backward() # 4. 反向传播
optimizer.step() # 5. 更新参数
```
---
### 正解 vs 错误
### ✅ 正确做法
```python
# 1. 常用优化器选择
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-3, weight_decay=0.01)
# 2. 学习率调度
scheduler = torch.optim.lr_scheduler.StepLR(optimizer, step_size=10, gamma=0.1)
# 3. 梯度裁剪
torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
```
### ❌ 常见错误
| 错误做法 | 问题 | 正确做法 |
|---------|------|---------|
| 忘记 zero_grad() | 梯度累加,训练异常 | 每次迭代前清零 |
| 学习率太大 | 不收敛 / NaN | 调小学习率 |
| 所有参数同一学习率 | 微调效果差 | 分层学习率 |
| 不做梯度裁剪 | 梯度爆炸 | 训练不稳定时加裁剪 |
| 不使用学习率衰减 | 收敛慢 | 添加 scheduler |
---
## 原理深入
### 3.3.1 SGD(随机梯度下降)
**数学公式**:
$$\theta_{t+1} = \theta_t - \eta \cdot \nabla_\theta L(\theta)$$
**特点**:
- 简单直接
- 收敛较慢,容易陷入局部最优
- 需要手动调学习率
**PyTorch 实现**:
```python
# 基础 SGD(PyTorch 2.0+ 推荐 foreach=True,性能更好)
optimizer = torch.optim.SGD(model.parameters(), lr=0.01, foreach=True)
# 带动量(最常用)
optimizer = torch.optim.SGD(model.parameters(), lr=0.01, momentum=0.9, foreach=True)
```
**Momentum(动量)**:
$$v_t = \beta v_{t-1} + (1-\beta) \nabla_\theta L(\theta)$$
$$\theta_{t+1} = \theta_t - \eta v_t$$
- 相当于给参数更新加了"惯性"
- 加速收敛,减少震荡
### 3.3.2 Adam(自适应学习率)
**Adam = Adaptive Moment Estimation**
**核心思想**:
- 对每个参数自适应调整学习率
- 一阶矩估计(动量)处理稀疏梯度
- 二阶矩估计处理梯度幅度差异
**数学公式**:
```
m_t = β₁ m_{t-1} + (1-β₁) g_t # 梯度的一阶矩估计(类似动量)
v_t = β₂ v_{t-1} + (1-β₂) g_t² # 梯度的二阶矩估计
m̂_t = m_t / (1-β₁^t) # 偏差校正
v̂_t = v_t / (1-β₂^t) # 偏差校正
θ_{t+1} = θ_t - η * m̂_t / (√v̂_t + ε) # 参数更新
```
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `lr` | 1e-3 | 学习率 |
| `betas` | (0.9, 0.999) | 一阶/二阶矩估计的指数衰减率 |
| `eps` | 1e-8 | 数值稳定性项 |
| `weight_decay` | 0 | 权重衰减系数(见 3.2.5 节正则化) |
**PyTorch 实现**:
```python
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
```
### 3.3.3 AdamW(权重衰减)
**为什么 Adam 的 weight_decay 不是真正的 L2?**
在标准 SGD 中,L2 正则化 = 在梯度上加一项 `λw` = 直接让权重衰减,两者等价。但在 Adam 中,自适应学习率 `m̂/√v̂` 会缩放梯度,此时再在缩放后的梯度上直接加 `λw` 不等于真正的 L2 正则化,效果不可预测。
**AdamW 的改进**:
$$\theta_{t+1} = \theta_t - \eta \cdot ( \frac{m_t}{\sqrt{v_t} + \epsilon} + \lambda \theta_t )$$
其中 λ 是权重衰减系数。
**PyTorch 实现**:
```python
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-3, weight_decay=0.01)
```
**推荐使用场景**:
- Transformer 模型(BERT、GPT 等)
- 预训练模型微调
### 3.3.4 学习率设置
**学习率的作用**:
![学习率对训练的影响](images/lr_curves.png)
*图:左=学习率过小(100 步仍未降到最优);中=学习率过大(Loss 震荡、爆炸出 NaN);右=合适的学习率(平稳快速收敛到较低 loss)*
**常见设置策略**:
```python
# 1. 固定学习率
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
# 2. 学习率衰减
scheduler = torch.optim.lr_scheduler.StepLR(optimizer, step_size=10, gamma=0.1)
# 3. Warmup + Cosine Annealing
scheduler = torch.optim.lr_scheduler.CosineAnnealingWarmRestarts(optimizer, T_0=10, T_mult=2)
# 4. OneCycleLR(推荐用于收敛)
scheduler = torch.optim.lr_scheduler.OneCycleLR(
optimizer, max_lr=1e-3, epochs=epochs, steps_per_epoch=len(dataloader)
)
```
### 3.3.5 梯度裁剪
**作用**:防止梯度爆炸
**PyTorch 实现**:
```python
# 方法1:按值裁剪
torch.nn.utils.clip_grad_value_(model.parameters(), clip_value=1.0)
# 方法2:按范数裁剪(推荐)
torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
```
**使用示例**:
```python
for epoch in range(epochs):
for batch in dataloader:
optimizer.zero_grad()
output = model(batch)
loss = criterion(output, target)
loss.backward()
# 梯度裁剪
torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
optimizer.step()
```
**SGD vs Adam 的优化轨迹对比**:
![SGD vs Adam 优化轨迹](images/optimizer_trajectory.png)
*图:在 Rosenbrock 损失面上(等高线表示 loss,越深越大),蓝色★为起点 (–1.2, 0.8),金色★为最优点 (1, 1)。SGD 沿窄谷反复震荡,迭代缓慢;Adam 通过自适应缩放梯度,沿平滑路径快速逼近最优点*
---
### 实战代码
```python
import torch
import torch.nn as nn
import torch.optim as optim
# 定义一个简单的模型
class SimpleNet(nn.Module):
def __init__(self):
super().__init__()
self.fc = nn.Linear(10, 1)
def forward(self, x):
return self.fc(x)
# 创建模型和数据
model = SimpleNet()
x = torch.randn(32, 10)
y = torch.randn(32, 1)
# 定义损失函数
criterion = nn.MSELoss()
# 定义优化器配置(每次循环都重新创建,保证状态干净)
optimizer_configs = [
('SGD', lambda p: optim.SGD(p, lr=0.01, momentum=0.9, foreach=True)),
('Adam', lambda p: optim.Adam(p, lr=0.01)),
('AdamW', lambda p: optim.AdamW(p, lr=0.01, weight_decay=0.01)),
]
for name, opt_fn in optimizer_configs:
model.reset_parameters() # 重置模型权重
optimizer = opt_fn(model.parameters()) # 每次新建优化器,清除上一轮的动量状态
print(f"\n{name}:")
for step in range(5):
optimizer.zero_grad()
output = model(x)
loss = criterion(output, y)
loss.backward()
optimizer.step()
print(f" Step {step}: loss = {loss.item():.4f}")
```
---
### 常见问题
**Q1: 应该用 SGD 还是 Adam?**
> A:
> - 一般任务:先用 Adam(收敛快,调参简单)
> - 大模型预训练:常用 AdamW
> - 追求最优性能:可以尝试 SGD + Momentum + 学习率调度
**Q2: 学习率如何设置?**
> A:
> - Adam 常用 1e-3
> - SGD 常用 0.01-0.1
> - 预训练模型微调常用 1e-5 到 5e-5
**Q3: 什么时候需要梯度裁剪?**
> A: 训练不稳定(loss 出现 NaN 或剧烈震荡)时使用。RNN、Transformer 训练时常需要。
**Q4: 多个学习率怎么办?**
> A: 使用参数分组:
```python
optimizer = torch.optim.Adam([
{'params': model.backbone.parameters(), 'lr': 1e-5},
{'params': model.head.parameters(), 'lr': 1e-3}
])
```
**Q5: weight_decay 和 L2 正则化是什么关系?**
> A: 在标准 SGD 中,weight_decay = L2 正则化。但在 Adam 中,两者不等价。推荐使用 AdamW 的 weight_decay。
---
### 验收标准
```
□ 能解释 SGD、Adam、AdamW 的区别和适用场景
□ 能在 PyTorch 中正确使用各种优化器
□ 能设置合适的学习率和学习率调度
□ 知道什么时候需要梯度裁剪
□ 理解动量(Momentum)的作用
□ 能使用参数分组设置不同学习率
□ 理解 weight_decay 和 L2 正则化的关系
```
---
### 官方来源
- PyTorch 优化器文档:https://pytorch.org/docs/stable/optim.html
- Adam 论文:Kingma & Ba, "Adam: A Method for Stochastic Optimization", 2014
- AdamW 论文:Loshchilov & Hutter, "Decoupled Weight Decay Regularization", 2019
---
### 参考文献
[1] https://ruder.io/optimizing-gradient-descent/
[2] Goodfellow et al., *Deep Learning*, Chapter 8
---
## 3.4 前向传播 / 反向传播
> 前向传播是"预测",反向传播是"学习"。这两者共同构成了神经网络训练的核心循环。
---
### 什么是前向传播和反向传播?
**一句话定义**:
- **前向传播**:输入数据从输入层到输出层流动,得到预测结果
- **反向传播**:根据预测误差,从输出层反向计算梯度,更新参数
**为什么重要?**
- 前向传播是模型做预测的过程
- 反向传播是模型学习的过程
- 理解这两个过程,才能理解深度学习的本质
**生活类比**:就像考试
- **前向传播** = 答题(根据已学的知识给出答案)
- **反向传播** = 批改 + 学习(看看哪里错了,下次改正)
---
### 计算图概念
**计算图**:用节点和边表示计算过程的图
```
示例:计算 L = (w * x + b)²
计算图:
x ──┐
├──> * ──┐
w ──┘ ├──> + ──┐
b ──────┘ ├──> ² ──> L
↑
(w*x + b)
前向传播(计算输出):
L = (w*x + b)² = (2*3 + 1)² = 49
反向传播(计算梯度):
dL/d(w*x+b) = 2 * (w*x+b) = 14
d(w*x+b)/dw = x = 3
d(w*x+b)/db = 1
=> dL/dw = dL/d(w*x+b) * d(w*x+b)/dw = 14 * 3 = 42
=> dL/db = dL/d(w*x+b) * d(w*x+b)/db = 14 * 1 = 14
```
---
### 正解 vs 错误
### ✅ 正确做法
```python
import torch
# 1. 前向传播
x = torch.tensor([1.0, 2.0], requires_grad=True)
y = x ** 2 + 2 * x + 1
# 2. 反向传播
y.sum().backward() # 标量才能backward
# 3. 查看梯度
print(x.grad) # tensor([4., 6.])
```
### ❌ 常见错误
| 错误做法 | 问题 | 正确做法 |
|---------|------|---------|
| 非标量 loss 调用 backward() | 报错 | 先 .sum() 或 .mean() |
| 多次 backward() 不清梯度 | 梯度累加 | 调用 zero_grad() |
| 对不需要梯度的tensor求导 | 结果为None | 设置 requires_grad=True |
| 修改叶子节点的值 | 破坏计算图 | 用 .data 或 detach() |
| 忘记 no_grad 推理 | 浪费内存 | 推理时用 torch.no_grad() |
---
## 原理深入
### 3.4.1 计算图概念
**计算图的直观展示**:计算图是一种可视化工具,用于展示神经网络的计算流程。每个节点表示一个变量或操作,边表示数据流动和梯度传递。
*说明:左图为简单表达式 L=(w·x+b)² 的计算图,蓝色箭头是前向计算,红色标注是反向梯度;右图为神经网络分层计算图,每一层的梯度 = 上游梯度 × 本地导数(链式法则)*
**计算图的构建**:
```python
import torch
# PyTorch 自动构建计算图
a = torch.tensor([1.0], requires_grad=True)
b = torch.tensor([2.0], requires_grad=True)
c = a + b # c = a + b
d = c * a # d = c * a = a * (a + b)
L = d.sum() # L = d_1 + d_2 + ...
print(f"a 是叶子节点: {a.is_leaf}")
print(f"c 不是叶子节点: {c.is_leaf}")
```
**叶子节点**:用户创建的 tensor,不是由运算产生的
### 3.4.2 前向传播过程
**前向传播全流程总览**:前向传播是数据从输入层经过隐藏层流向输出层的过程,最终得到预测结果。
*说明:蓝色箭头表示前向传播(输入→隐藏→输出→损失),红色箭头表示反向传播(梯度从损失反向流回每一层),最后由 Optimizer 更新参数*
**前向传播流程**:
```
输入层 ──> 隐藏层1 ──> 隐藏层2 ──> ... ──> 输出层
│ │ │ │
│ │ │ │
x Linear+ReLU Linear+ReLU Linear
│ │ │ │
└──────────┴───────────┴────────────────────┘
输出 ŷ
```
**代码示例**:
```python
import torch
import torch.nn as nn
class SimpleNet(nn.Module):
def __init__(self):
super().__init__()
self.layer1 = nn.Linear(10, 5)
self.relu = nn.ReLU()
self.layer2 = nn.Linear(5, 1)
def forward(self, x):
x = self.layer1(x)
x = self.relu(x)
x = self.layer2(x)
return x
# 前向传播
model = SimpleNet()
x = torch.randn(1, 10)
output = model(x) # 前向传播
print(f"输出形状: {output.shape}") # torch.Size([1, 1])
```
### 3.4.3 梯度计算(链式法则)
**链式法则**:
$$\frac{dL}{d\theta} = \frac{dL}{d\text{out}} \cdot \frac{d\text{out}}{d\theta}$$
**计算图反向传播示例**:
```
x ──┐
├──> * ──> a ──┐
w ──┘ ├──> + ──> b ──┐
b ────────────┼──> * ──> L
∂L/∂b ──────────────────────┘
↑
│
∂L/∂a = ∂L/∂b * ∂b/∂a = ∂L/∂b * b
```
```python
import torch
# 手动计算:L = w * x * x + b * x
w = torch.tensor([2.0], requires_grad=True)
x = torch.tensor([3.0], requires_grad=True)
L = w * x * x + x * x # = w*x² + x²
L.backward()
print(f"dL/dw = {w.grad}") # x² = 9
print(f"dL/dx = {x.grad}") # 2wx + 2x = 12 + 6 = 18
```
### 3.4.4 反向传播过程
**完整训练循环中的反向传播**:
```python
import torch
import torch.nn as nn
model = SimpleNet()
criterion = nn.MSELoss()
optimizer = torch.optim.Adam(model.parameters(), lr=0.01)
x = torch.randn(32, 10)
y = torch.randn(32, 1)
# 1. 前向传播
output = model(x) # 计算预测值
loss = criterion(output, y) # 计算损失
# 2. 反向传播
optimizer.zero_grad() # 清零梯度
loss.backward() # 反向传播,计算梯度
# 3. 更新参数
optimizer.step() # 根据梯度更新参数
print(f"Loss: {loss.item():.4f}")
```
### 3.4.5 梯度消失与梯度爆炸
**梯度消失(Vanishing Gradient)**:
```
问题:梯度在传播过程中越来越小,前层参数几乎不更新
原因:
- Sigmoid/Tanh 在两端梯度接近0
- 网络太深时,链式法则使梯度指数衰减
解决方案:
- 用 ReLU 替代 Sigmoid/Tanh
- **Kaiming 初始化**(详见 3.1.6 节,专为 ReLU 设计)
- 残差连接(ResNet)
- 批量归一化(BatchNorm,见 3.2.5 节正则化)
- LSTM/GRU 的门控机制
```
**梯度爆炸(Exploding Gradient)**:
```
问题:梯度在传播过程中越来越大,参数更新剧烈
表现:
- loss 变成 NaN
- loss 剧烈震荡
解决方案:
- 梯度裁剪(`clip_grad_norm_`,详见 3.3.5 节)
- **合适的权重初始化**(详见 3.1.6 节,避免方差过大)
- 降低学习率
- 批量归一化(见 3.2.5 节)
```
**诊断方法**:
```python
# 查看梯度
for name, param in model.named_parameters():
if param.grad is not None:
print(f"{name}: grad_norm = {param.grad.norm().item():.6f}")
# 检测梯度爆炸
def check_grad_explosion(optimizer):
total_norm = 0.0
for p in model.parameters():
if p.grad is not None:
total_norm += p.grad.data.norm(2).item() ** 2
total_norm = total_norm ** 0.5
print(f"Gradient norm: {total_norm:.4f}")
```
**梯度消失 vs 爆炸的可视化**:
![梯度消失与梯度爆炸](images/gradient_problem.png)
*图:左图 Sigmoid 网络每层梯度乘以约 0.25,10 层后梯度小到 1e-6,前层参数几乎不更新;右图不稳定的深层网络每层梯度放大 1.5 倍,10 层后梯度爆炸到 1e4 量级,导致 Loss=NaN*
---
### 实战代码
```python
import torch
import torch.nn as nn
print("=" * 50)
print("3.4 前向传播与反向传播演示")
print("=" * 50)
# 1. 自动求导基础
print("\n1. 自动求导基础:")
x = torch.tensor([1.0, 2.0, 3.0], requires_grad=True)
y = x ** 2 + 2 * x + 1
y_sum = y.sum()
print(f" x = {x}")
print(f" y = x² + 2x + 1 = {y}")
y_sum.backward()
print(f" dy/dx = {x.grad}") # 2x + 2 = [4, 6, 8]
# 2. 完整训练循环
print("\n2. 完整训练循环:")
class DemoNet(nn.Module):
def __init__(self):
super().__init__()
self.fc1 = nn.Linear(4, 3)
self.fc2 = nn.Linear(3, 1)
def forward(self, x):
x = torch.relu(self.fc1(x))
x = self.fc2(x)
return x
model = DemoNet()
criterion = nn.MSELoss()
optimizer = torch.optim.Adam(model.parameters(), lr=0.01)
# 模拟数据
x = torch.randn(8, 4)
y = torch.randn(8, 1)
print(" 训练过程:")
for epoch in range(5):
# 前向传播
output = model(x)
loss = criterion(output, y)
# 反向传播
optimizer.zero_grad()
loss.backward()
# 更新参数
optimizer.step()
print(f" Epoch {epoch+1}: loss = {loss.item():.4f}")
# 3. 梯度检查
print("\n3. 梯度检查:")
model.zero_grad()
output = model(x)
loss = criterion(output, y)
loss.backward()
for name, param in model.named_parameters():
if param.grad is not None:
print(f" {name}: mean_grad = {param.grad.mean().item():.6f}")
```
---
### 常见问题
**Q1: 为什么 loss.backward() 前要 optimizer.zero_grad()?**
> A: PyTorch 默认会累加梯度。如果不清零,梯度会叠加,导致参数更新错误。
**Q2: 什么时候用 torch.no_grad()?**
> A: 推理/评估时使用。不需要计算梯度,节省内存和计算。
**Q3: 为什么损失出现 NaN?**
> A: 常见原因:学习率太大、梯度爆炸(用梯度裁剪)、输入数据有 NaN、数值溢出。
**Q4: 如何调试梯度计算?**
> A:
> ```python
> # 打印梯度
> loss.backward()
> print(model.weight.grad)
>
> # 数值梯度检验
> from torch.autograd import gradcheck
> print(gradcheck(model, x))
> ```
**Q5: requires_grad 是什么?**
> A: 表示这个 tensor 是否需要计算梯度。只有 requires_grad=True 的 tensor 才会被纳入计算图。
**Q6: 叶子节点和非叶子节点有什么区别?**
> A:
> - 叶子节点:用户直接创建的 tensor
> - 非叶子节点:由运算产生的 tensor
> - 梯度只能从叶子节点获取
---
### 验收标准
```
□ 能解释前向传播和反向传播的过程
□ 能画出一个简单神经网络的计算图
□ 能在 PyTorch 中正确实现训练循环
□ 能解释梯度清零(zero_grad)的重要性
□ 知道什么时候使用 torch.no_grad()
□ 能诊断和解决梯度消失/梯度爆炸问题
□ 理解链式法则在反向传播中的应用
□ 能用手算简单计算图的梯度
```
---
### 官方来源
- PyTorch autograd 文档:https://pytorch.org/docs/stable/autograd.html
- CS231n 反向传播:https://cs231n.github.io/optimization-1/
---
### 参考文献
[1] Goodfellow et al., *Deep Learning*, Chapter 6
[2] http://colah.github.io/posts/2015-08-Backprop/
[3] https://pytorch.org/tutorials/beginner/blitz/neural_networks_tutorial.html
# 李佳洋(LJY)教程编写执行表
> **用途**:把《实习生培训教程编写任务》里分配给李佳洋的内容,整理成一份可直接执行、可跟进、可自检的个人工作表。
> **生成日期**:2026-07-07
> **周期**:2026-07-07 至 2026-07-08
> **目标节点**:2026-07-08 下班前完成初版整理、统一格式并提交最终合并请求
---
## 一、我的交付边界
### 1.1 我负责的模块
| 模块 | 名称 | 章节数 | 说明 |
| --- | --- | --- | --- |
| 模块二 | PyTorch 基础 | 4 | 偏基础能力,要求代码讲解清楚、示例可运行 |
| 模块五 | LLM + API 调用 | 4 | 偏实战能力,要求调用链路完整、错误处理完整 |
### 1.2 我要交付的文档
```text
提交路径:docs/理论学习/教程/
├─ 模块二-PyTorch基础.md
└─ 模块五-LLM-API调用.md
```
### 1.3 这条线的硬要求
```text
├─ 共完成 8 个完整章节
├─ 每个知识点都要配可运行代码
├─ API 调用必须给出完整示例
├─ 必须演示多轮对话和 Function Calling
├─ 训练循环必须有完整代码并解释每一步
└─ 错误处理不能省略
```
---
## 二、整体任务盘点
### 2.1 模块二:PyTorch 基础
| 章节 | 子知识点范围 | 难度 | 当前状态 | 备注 |
| --- | --- | --- | --- | --- |
| 2.1 Tensor 操作 | 2.1.1 - 2.1.8 | ★★★★☆ | 待开始 | 下午优先 |
| 2.2 自动求导 | 2.2.1 - 2.2.5 | ★★★★☆ | 待开始 | 下午优先 |
| 2.3 nn.Module | 2.3.1 - 2.3.5 | ★★★★☆ | 待开始 | 下午优先 |
| 2.4 训练循环 | 2.4.1 - 2.4.6 | ★★★★★ | 待开始 | 上午重点 |
### 2.2 模块五:LLM + API 调用
| 章节 | 子知识点范围 | 难度 | 当前状态 | 备注 |
| --- | --- | --- | --- | --- |
| 5.1 Prompt Engineering | 5.1.1 - 5.1.7 | ★★★★☆ | 待开始 | 明日重点 |
| 5.2 OpenAI API 调用 | 5.2.1 - 5.2.7 | ★★★★★ | 待开始 | 上午重点 |
| 5.3 流式输出 | 5.3.1 - 5.3.4 | ★★★★☆ | 待开始 | 明日重点 |
| 5.4 Function Calling | 5.4.1 - 5.4.5 | ★★★★★ | 待开始 | 明日重点 |
---
## 三、优先级排序
### 3.1 今天最先解决的两章
```text
1. 2.4 训练循环
2. 5.2 OpenAI API 调用
```
原因:
1. 两章都被标记为五星重点。
2. 两章都直接决定后续章节的示例质量和技术深度。
3. 上午先打通训练流程和 API 调用,后面的 Tensor、自动求导、多轮对话、流式输出会更好展开。
### 3.2 今天第二梯队
```text
1. 2.1 Tensor 操作
2. 2.2 自动求导
3. 2.3 nn.Module
```
### 3.3 明天必须收口的内容
```text
1. 5.1 Prompt Engineering
2. 5.3 流式输出
3. 5.4 Function Calling
4. 两份文档统一风格、补 FAQ、补验收标准、补官方来源
```
---
## 四、今天上午执行清单
### 4.1 上午目标 A:完成 2.4 训练循环
#### 必写内容
```text
├─ 2.4.1 Dataset / DataLoader
├─ 2.4.2 前向传播
├─ 2.4.3 损失计算
├─ 2.4.4 反向传播与参数更新
├─ 2.4.5 完整训练循环
└─ 2.4.6 常见错误(梯度清零 / NaN)
```
#### 写作要求
1. 必须给出一段最小可运行训练代码,不能只放零散片段。
2. 必须逐步讲清 `zero_grad -> forward -> loss -> backward -> step`。
3. 必须补上两个新手高频错误:忘记清零梯度、loss 变成 `NaN`。
4. 必须让读者看完后能自己写出一个最小训练循环。
#### 这一章完成后的自查
```text
□ 代码能直接运行
□ loss 会正常输出
□ 每一步作用都解释到了
□ 有“正确写法 vs 常见错误”对比
□ 有章节级验收标准
```
### 4.2 上午目标 B:完成 5.2 OpenAI API 调用
#### 必写内容
```text
├─ 5.2.1 API Key 配置
├─ 5.2.2 基本调用
├─ 5.2.3 messages 格式
├─ 5.2.4 Token 计算
├─ 5.2.5 错误处理
├─ 5.2.6 多轮对话
└─ 5.2.7 成本优化
```
#### 写作要求
1. 必须提供完整调用示例,包含环境变量配置、初始化客户端、发起请求、读取返回结果。
2. 必须讲清 `messages` 是怎么组织上下文的。
3. 必须补充错误处理,至少覆盖密钥缺失、请求失败、参数错误这几类。
4. 必须展示一个多轮对话示例,而不是只写单轮问答。
5. 必须明确说明 token 与成本之间的关系。
#### 这一章完成后的自查
```text
□ 示例代码结构完整
□ 单轮调用可讲明白
□ 多轮对话示例清晰
□ 有错误处理部分
□ 有成本优化建议
```
---
## 五、每章统一写法约束
不管写哪一章,都必须套用下面这套结构:
```text
1. 知识点标题
2. 用 1-2 句话说明它解决什么问题
3. 什么是这个知识点
4. 举个例子
5. 正解 vs 错误
6. 实战代码
7. 常见问题
8. 验收标准
9. 官方来源
10. 参考文献(如有)
```
额外提醒:
1. 不能直接照搬官方文档定义,必须自己讲清楚。
2. 每章都尽量给出具体输入和具体输出。
3. 能对比的地方尽量做对比,尤其是“正确写法 vs 错误写法”。
4. 代码块必须标注语言类型。
---
## 六、建议写作顺序
### 6.1 模块二建议顺序
```text
2.4 训练循环
-> 2.1 Tensor 操作
-> 2.2 自动求导
-> 2.3 nn.Module
```
说明:
1. 先写训练循环,可以反过来带动 Tensor、梯度、模型这三章。
2. 这样后面补例子时,四章之间能共享同一套演示代码背景。
### 6.2 模块五建议顺序
```text
5.2 OpenAI API 调用
-> 5.1 Prompt Engineering
-> 5.3 流式输出
-> 5.4 Function Calling
```
说明:
1. 先把基础调用写稳,后面流式输出和 Function Calling 才不会飘。
2. Prompt Engineering 放在基础调用之后更容易写出“提示词如何影响结果”的演示。
---
## 七、风险点提醒
### 7.1 最容易拖慢进度的地方
```text
├─ 训练循环只讲概念,不给完整代码
├─ API 调用只写伪代码,不写可运行示例
├─ 多轮对话没有展示 messages 累积方式
├─ Function Calling 只有概念,没有完整执行链路
└─ 各章节结构不统一,最后返工整理
```
### 7.2 为了避免返工,写的时候就要带着做的事
```text
├─ 每章边写边补“正解 vs 错误”
├─ 每章边写边补 FAQ
├─ 每章边写边放官方来源
└─ 代码写完就做最小验证,不要堆到最后一起检查
```
---
## 八、个人收口清单
在提交前,至少确认下面这些都完成:
```text
□ 两份文档都已创建
□ 8 个章节全部覆盖
□ 每章都有可运行代码
□ 上午两章已达到“可直接给实习生看”的程度
□ 多轮对话已展示
□ Function Calling 已有实战案例
□ 错误处理已补齐
□ 标题层级、代码块语言、链接格式统一
```
---
## 九、给自己的结果标准
如果这份任务完成得好,最终应该达到下面这个效果:
1. 新人读完 `2.4` 后,能把训练循环写出来并知道为什么这样写。
2. 新人读完 `5.2` 后,能自己完成一次基础 API 调用并理解多轮对话组织方式。
3. 新人读完模块二和模块五后,不只是“看懂”,而是能直接照着跑、照着改、照着排错。
# 实习生与产教融合平台 - 架构大纲(v2 · 完善版)
> **更新说明**:本版本在 v1 基础上保留原有 8 个章节结构,新增以下关键内容:
> - 微服务拆分与依赖关系
> - AI 能力中心详细架构(RAG、Embedding、Prompt 管理)
> - 实训闭环引擎的状态机建模
> - 容器沙箱的安全隔离方案
> - 安全合规(密码策略、审计追踪、数据加密)
> - 非功能性需求(SLA、性能、容量)
> - 监控告警与容灾
> - 风险与应对策略
---
## 一、系统分层架构
| 层级 | 说明 |
| --- | --- |
| **接入层** | Web 前端(管理后台 / 学员端 / 学校端)+ 移动端 H5(可选) |
| **网关层** | API 网关(Kong / Nginx)、统一认证、限流熔断、CORS、请求日志 |
| **业务应用层** | 实训闭环引擎、AI 能力中心、权限管理、培养体系生成 |
| **服务层** | 微服务(用户 / 项目 / 实训 / 答辩 / 审核 / 培养体系 / 通知) |
| **AI 能力层** | LLM 统一调用服务、向量数据库、RAG 检索增强、知识图谱 |
| **数据层** | MySQL(业务数据)、Redis(缓存/会话)、MinIO(文件/代码仓库)、Milvus(向量) |
| **基础设施层** | Docker / K8s、容器沙箱、code-server、GPU 节点、Prometheus / Grafana |
---
## 二、核心模块设计
### 1. 通用底座(两模块共用)
**1.1 内部项目库**
- 项目管理(CRUD、标签、难度等级 L1-L5)
- 项目分类索引(技术栈 / 标注类型 / 业务领域)
- 关联资料存储(代码、文档、验收报告、版本管理)
**1.2 实训闭环引擎**
```
预习 → 实操 → 答辩 → 进阶匹配 → 主管审核 → 入项
```
- 流程状态机引擎(Spring State Machine / 自研)
- 阶段校验与门控逻辑(前置条件 / 缺失项提示)
- 循环次数与退出条件配置
- 阶段流转日志(审计追溯)
**1.3 AI 能力中心**(详见第五章)
| 能力 | 说明 | 依赖 |
| --- | --- | --- |
| 项目推荐 | 基于相似度匹配推荐源项目 | Embedding + 向量检索 |
| 知识点提取 | 结构化知识点有向图 | LLM + 知识图谱 |
| 缺陷分析 | 错误日志 → 薄弱知识点映射 | LLM + 学员画像 |
| 项目分类 | 标注项目多维度分类 | LLM + 分类器 |
| 体系生成 | 培养方案自动编排 | LLM + 模板库 |
**1.4 成长档案与能力画像**
- 全流程数据沉淀(预习 / 实操 / 答辩 / 审核)
- 能力短板画像(基于知识点依赖图)
- 可视化成长轨迹(雷达图 / 进度条)
---
### 2. 模块一:技术部
- **推荐源**:GitHub 项目(GitHub API / 镜像索引)
- **实训闭环**:与通用底座一致
- **实操环境**:Docker 容器 + code-server
- **特色**:实操产物自动归档至 MinIO,提交即触发答辩流程
---
### 3. 模块二:标注部
- **推荐源**:公司往届内部标注项目
- **实训闭环**:与模块一一致
- **人才培训体系生成**(对外服务)
- 甲方资料上传与管理
- AI 项目分类(行业 / 类型 / 难度)
- 体系四板块生成:
- 晋升路径
- 实习实训内容
- 配套课程
- 就业方向
- 人工复核与编辑
- 对外交付与协作
---
## 三、微服务拆分与依赖关系
> 原 v1 未拆分服务粒度,本节明确微服务边界与依赖。
```
┌──────────────────────────────────────────────────────────────┐
│ API Gateway │
│ (认证 / 限流 / 路由) │
└──────────┬───────────┬───────────┬───────────┬───────────────┘
▼ ▼ ▼ ▼
┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
│ 用户服务 │ │ 项目服务 │ │ 实训服务 │ │ AI 服务 │
│ user │ │ project │ │training│ │ ai │
└───────┘ └───────┘ └───────┘ └───────┘
│ │ │ │
▼ ▼ ▼ ▼
┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
│ 答辩服务 │ │ 审核服务 │ │ 通知服务 │ │体系生成 │
│defense │ │ audit │ │ notify │ │ system│
└───────┘ └───────┘ └───────┘ └───────┘
```
### 服务职责
| 服务 | 职责 | 数据所有权 |
| --- | --- | --- |
| **user-service** | 用户、角色、权限、登录 | users / roles / permissions |
| **project-service** | 项目库、标签、分类、难度 | projects / tags / categories |
| **training-service** | 实训流程状态机、阶段流转 | training_tasks / training_flow_log |
| **defense-service** | 答辩申请、评审、评分 | defense_records |
| **audit-service** | 主管审核、入项登记 | audit_records / entry_records |
| **ai-service** | LLM 调用、向量化、RAG 检索 | ai_logs / vector_index |
| **system-gen-service** | 培养体系生成(模块二专属) | training_systems |
| **notify-service** | 站内信、邮件、Webhook | notifications |
### 服务依赖规则
1. **单向依赖**:上游服务不依赖下游服务(如 user-service 不调用 training-service)
2. **数据隔离**:每个服务独占数据库表,通过 API 通信
3. **事件驱动**:阶段流转通过 RabbitMQ 事件总线通知(如 `training.advanced` 事件)
4. **熔断降级**:AI 服务不可用时,自动降级为人工推荐
---
## 四、数据架构
### 1. 核心数据模型
```
├── 用户/角色 (User, Role, Permission)
├── 项目 (Project) - 含难度等级、标签
├── 实训任务 (TrainingTask) - 关联项目、学员、状态
├── 知识点 (KnowledgePoint) - 依赖关系图
├── 预习记录 (PreviewRecord)
├── 实操产物 (PracticeArtifact)
├── 实操报告 (PracticeReport)
├── 答辩记录 (DefenseRecord) - 含评分、意见
├── 能力画像 (CapabilityProfile)
├── 进阶记录 (AdvancementRecord)
├── 入项记录 (EntryRecord)
└── 培训体系 (TrainingSystem) - 模块二专属
```
### 2. AI 相关数据
```
├── 项目推荐日志 (recommendation_log)
├── 知识点提取结果 (knowledge_extract_result)
├── 缺陷分析报告 (defect_analysis_report)
├── 项目分类结果 (project_classification)
├── 向量索引 (vector_index) - Milvus
├── Prompt 模板版本 (prompt_template)
└── 生成的培养体系 (training_system)
```
### 3. 数据分区与归档
| 数据类型 | 存储 | 保留策略 |
| --- | --- | --- |
| 业务核心数据 | MySQL | 永久 |
| 操作审计日志 | MySQL 分区表(按月) | 5 年 |
| AI 调用日志 | MySQL + ES | 1 年 |
| 实操产物文件 | MinIO | 永久(学员归档后可下载) |
| 向量数据 | Milvus | 与项目生命周期一致 |
| 临时缓存 | Redis | TTL 1h |
---
## 五、AI 能力中心详细架构
> 原 v1 仅列出能力清单,本节补充架构与流程。
### 1. 整体架构
```
┌─────────────────────────────────────────────────────────┐
│ AI 能力中心 │
├─────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 项目推荐 │ │知识点提取│ │ 缺陷分析 │ │ 项目分类 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ └──────────┬──┴──────────────┴────────────┘ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ LLM 统一调用服务 │ │
│ │ (OpenAI/文心/通义) │ │
│ └──────────┬───────────┘ │
│ ▼ │
│ ┌──────────┬──────────┬──────────┐ │
│ │ Embedding│ 向量检索 │ RAG 检索 │ │
│ └──────────┴──────────┴──────────┘ │
└─────────────────────────────────────────────────────────┘
```
### 2. 项目推荐流程
```
学员画像 + 历史项目
│
▼
┌──────────────┐ ┌──────────────┐
│ Embedding 编码│ → │ Milvus 向量检索│
└──────────────┘ └──────────────┘
│
▼
┌──────────────┐
│ Top-K 项目 │
└──────┬───────┘
│
▼
┌──────────────┐
│ LLM 重排序 │
│ (含理由生成) │
└──────────────┘
```
### 3. 知识点提取流程
```
GitHub README + 目录结构
│
▼
┌──────────────┐
│ 文本预处理 │ (分块 / 去噪)
└──────┬───────┘
│
▼
┌──────────────┐
│ LLM 提取 │ ← Prompt 模板
│ (JSON 输出) │
└──────┬───────┘
│
▼
┌──────────────┐
│ 知识点依赖图 │ (拓扑排序 / 环检测)
│ 持久化 │
└──────────────┘
```
### 4. Prompt 管理
- **版本管理**:每个 Prompt 模板独立版本号,支持回滚
- **A/B 测试**:同一任务可挂多个 Prompt,对比效果
- **变量注入**:支持动态变量(如 `{user_level}` `{project_type}`)
- **效果评测**:用评测集(`eval_set_v1.json`)自动评分
### 5. AI 服务可用性保障
| 风险 | 应对策略 |
| --- | --- |
| LLM 服务商故障 | 切换备用模型(OpenAI ↔ 文心 ↔ 通义) |
| 调用超时 | 超时重试 + 降级为人工 |
| Token 限额 | Token 池 + 多账号轮询 |
| 幻觉输出 | JSON Schema 严格校验 + 人工复核兜底 |
---
## 六、关键接口设计
### 1. 项目管理
- `POST /api/v1/projects` - 创建项目
- `GET /api/v1/projects` - 项目列表(筛选 / 搜索)
- `GET /api/v1/projects/{id}` - 项目详情
- `PUT /api/v1/projects/{id}` - 更新项目
- `POST /api/v1/projects/{id}/difficulty` - 难度校准
### 2. 实训流程
- `POST /api/v1/training/recommend` - AI 推荐项目
- `POST /api/v1/training/preview` - 知识点提取
- `POST /api/v1/training/practice/submit` - 实操产物提交
- `POST /api/v1/training/report/submit` - 报告提交
- `POST /api/v1/training/defense/apply` - 申请答辩
- `POST /api/v1/training/defense/review` - 答辩评审
- `POST /api/v1/training/advance` - 进阶匹配
- `POST /api/v1/training/audit` - 主管审核
- `POST /api/v1/training/entry` - 入项登记
### 3. 人才培训体系(模块二)
- `POST /api/v1/training-system/classify` - 项目分类
- `POST /api/v1/training-system/generate` - 体系生成
- `PUT /api/v1/training-system/{id}` - 人工编辑
- `POST /api/v1/training-system/deliver` - 对外交付
### 4. 认证与权限
- `POST /api/v1/auth/login` - 登录
- `POST /api/v1/auth/register` - 注册
- `POST /api/v1/auth/refresh` - Token 刷新
- `GET /api/v1/users` - 用户列表
- `POST /api/v1/users/batch-import` - 批量导入
- `GET /api/v1/audit/logs` - 审计日志
### 5. GitHub 仓库匹配(v1.5)
- `GET /api/v1/github/search` - 仓库搜索
- `POST /api/v1/github/repos/{id}/mark` - 标记采用 / 排除
- `GET /api/v1/github/repos/filter` - 仓库筛选
---
## 七、安全与权限
### 1. RBAC 角色权限矩阵
| 角色 | 权限范围 |
| --- | --- |
| 管理员 | 全系统配置、用户管理 |
| 主管 | 审核学员、内容终审、体系审批 |
| 导师 | 答辩评审、学员指导 |
| 学员 | 参与实训、提交产物、查看成长档案 |
| 学校(模块二) | 查看 / 编辑培养体系、提交反馈 |
### 2. 鉴权流程
```
客户端 → API Gateway → JWT 校验 → 权限拦截 → 业务服务
(401 过期) (403 越权)
```
### 3. 密码与登录安全
- **密码加密**:bcrypt(cost=12) / Argon2id
- **登录保护**:连续 5 次失败锁定 30 分钟(按 IP + 账号双重维度)
- **Token 策略**:JWT(access 2h + refresh 7d)
- **会话管理**:单点登出 + 异地登录提醒
### 4. 数据安全
| 数据类型 | 加密策略 |
| --- | --- |
| 用户密码 | bcrypt 不可逆加密 |
| 敏感字段(手机号 / 邮箱) | AES-256 对称加密 |
| 传输层 | HTTPS / TLS 1.3 |
| 数据库 | 字段级加密(身份证 / 银行卡等) |
| 文件存储 | MinIO 私有读写 + 签名 URL |
### 5. 操作审计
- 所有写操作(增 / 删 / 改)写入 `audit_logs` 表
- 记录项:操作人、操作类型、资源、IP、User-Agent、时间戳
- 审计日志不可删除(仅可归档)
- 关键操作触发实时告警(如批量删除用户)
### 6. 合规要求
- **数据隐私**:学员数据脱敏展示(如手机号 138****8000)
- **数据导出**:管理员导出需二次确认 + 审批流
- **GDPR / 个人信息保护法**:用户可申请导出 / 删除个人数据
- **代码仓库合规**:对接 GitHub 时遵守其 API ToS
---
## 八、非功能性需求
### 1. 性能指标
| 指标 | 目标 |
| --- | --- |
| 接口 P99 响应时间 | < 500ms(不含 AI 调用) |
| AI 调用 P95 响应时间 | < 5s |
| 页面首屏加载 | < 2s |
| 并发用户数 | ≥ 500(学员端) |
| 数据库 QPS | ≥ 3000 |
### 2. 可用性
| 指标 | 目标 |
| --- | --- |
| 服务可用性 SLA | ≥ 99.5%(工作时段) |
| 故障恢复时间 RTO | < 30 分钟 |
| 数据恢复点 RPO | < 1 小时 |
### 3. 容量规划(首年预估)
| 资源 | 规模 |
| --- | --- |
| 学员数 | 1000 人 |
| 项目数 | 5000 个 |
| 实操产物 | 10 万份 |
| 总存储 | 5 TB(含代码仓库) |
| 日均 AI 调用 | 1 万次 |
### 4. 扩展性
- **水平扩展**:所有服务无状态化,支持 K8s 自动扩缩容
- **存储扩展**:MinIO 集群模式(EC 纠删码)
- **向量扩展**:Milvus 集群模式(支持 1 亿向量)
---
## 九、监控告警与容灾
### 1. 监控体系
```
┌────────────────────────────────────────────┐
│ Prometheus + Grafana │
├────────────────────────────────────────────┤
│ JVM / GC / QPS / RT / 错误率 / 慢 SQL │
│ AI 调用成功率 / Token 消耗 / 响应时间 │
│ Milvus 检索 QPS / 向量召回率 │
│ 容器 CPU / 内存 / GPU 利用率 │
└────────────────────────────────────────────┘
```
### 2. 告警分级
| 级别 | 触发条件 | 通知方式 |
| --- | --- | --- |
| **P0** | 服务不可用 / 数据丢失 | 电话 + 短信 + 钉钉 |
| **P1** | 错误率 > 5% / RT > 1s | 钉钉 + 邮件 |
| **P2** | 资源使用率 > 80% | 钉钉群机器人 |
### 3. 容灾方案
| 场景 | 方案 |
| --- | --- |
| 数据库故障 | 主从切换(< 1 分钟自动切换) |
| AI 服务不可用 | 降级为人工推荐 / 排队重试 |
| 文件存储故障 | MinIO 多副本 + 跨可用区 |
| 单服务故障 | K8s 自动重启 + 熔断降级 |
| 区域性故障 | 异地冷备(数据 RPO < 1h) |
### 4. 备份策略
- **MySQL**:每日全量 + 每 6h 增量备份,保留 30 天
- **MinIO**:EC 纠删码(4+2),实时多副本
- **配置中心**:Git 仓库版本管理,支持一键回滚
- **Prompt 模板**:版本化存储,可追溯可回滚
---
## 十、部署架构
```
┌─────────────┐
│ 负载均衡 │ (Nginx / SLB)
└──────┬──────┘
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Web服务 │ │ API服务 │ │ AI服务 │
│ (N个实例)│ │ (N个实例)│ │ (GPU节点)│
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
┌────┴───────────────┴───────────────┴────┐
│ MySQL主从 + Redis Cluster + Milvus │
└────────────────────────────────────────┘
│
┌──────┴──────┐
│ Docker主机 │ (K8s 集群)
│ ┌─────────┐ │
│ │ 沙箱容器 │ │ ← 每学员独立容器(资源隔离)
│ └─────────┘ │
│ ┌─────────┐ │
│ │code-srv │ │ ← code-server (网页版 VSCode)
│ └─────────┘ │
└────────────┘
```
### 容器沙箱安全隔离
| 维度 | 措施 |
| --- | --- |
| **资源隔离** | cgroup 限制 CPU / 内存 / 磁盘 |
| **网络隔离** | 学员容器仅开放 80/443 出站,禁止内网访问 |
| **文件系统** | 容器内只读系统盘 + 可写工作目录 |
| **运行时长** | 超时自动销毁(默认 8h) |
| **操作审计** | 所有 shell 命令记录至 ES |
| **危险命令** | 拦截 `rm -rf /`、`dd`、`mkfs` 等 |
---
## 十一、迭代规划
| 阶段 | 范围 |
| --- | --- |
| **MVP v1.0** | 项目管理 + 基础实训闭环(不含 AI) |
| **v1.5** | + AI 推荐 + 知识点提取 |
| **v2.0** | + 容器沙箱实操 + 答辩评审 |
| **v2.5** | + 进阶匹配 + 主管审核 + 入项 |
| **v3.0** | 模块二上线 + 人才培训体系生成 |
---
## 十二、风险与应对策略
| 风险 | 影响 | 等级 | 应对策略 |
| --- | --- | --- | --- |
| **GitHub API 限流** | FR-003 无法规模化 | 高 | Token 池 + 镜像索引 + 缓存 |
| **AI 幻觉输出** | 知识点提取 / 体系生成质量差 | 高 | JSON Schema 严格校验 + 人工复核 |
| **容器沙箱逃逸** | 安全风险 | 高 | 网络隔离 + 操作审计 + 危险命令拦截 |
| **状态机复杂度膨胀** | 难以维护 | 中 | 配置化(JSON / YAML)+ 可视化编辑器 |
| **LLM 服务商涨价 / 停服** | 成本 / 可用性 | 中 | 多模型抽象 + 国内模型备份 |
| **学员数据泄露** | 合规风险 | 高 | 加密存储 + 脱敏展示 + 审计追踪 |
| **大规模并发答辩评审** | 性能瓶颈 | 中 | 异步队列 + 评审员分片 |
| **GitHub 仓库许可证问题** | 商用风险 | 中 | 许可证扫描 + 黑名单过滤 |
---
## 十三、附录
### 1. 名词解释
| 术语 | 解释 |
| --- | --- |
| RBAC | Role-Based Access Control,基于角色的访问控制 |
| RAG | Retrieval-Augmented Generation,检索增强生成 |
| RTO | Recovery Time Objective,恢复时间目标 |
| RPO | Recovery Point Objective,恢复点目标 |
| Embedding | 将文本转换为向量的过程 |
| Token | LLM 的计费单位,≈ 0.75 个英文单词 |
### 2. 参考资料
- 《PRD 文档》
- 《任务安排.md》
- 《本周任务安排-7.13-7.17.md》
### 3. 版本历史
| 版本 | 日期 | 变更 |
| --- | --- | --- |
| v1 | 2026-07-12 | 初版(8 个章节) |
| **v2** | **2026-07-13** | **新增:微服务拆分、AI 架构、监控容灾、非功能需求、风险应对、合规要求** |
\ No newline at end of file
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑!
请 注册 或者 后发表评论