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

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

上级 2d23fc4d
......@@ -27,4 +27,6 @@ logs/
*.zip
*.tar.gz
*.pdf
# 文档网站
/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 调用示例格式
要求:
├─ 每次完成一个小节提交一次
├─ 不要等到最后一次性提交
└─ 提交信息要清晰描述改动
```
......@@ -97,43 +97,43 @@ v1.docx → v2.docx → v3-改哭了版.docx → v3-真的改哭了.docx →
---
## 什么是首次配置?
#### 什么是首次配置?
Git 是一个**分布式**版本控制系统,每个提交都会记录作者信息(姓名 + 邮箱)。**首次配置 = 给 Git 装上"身份证"**。
### 一句话定义
##### 一句话定义
通过 `git config` 命令设置全局或仓库级的用户名、邮箱、编辑器等偏好。
### 为什么重要
##### 为什么重要
每次 `git commit` 都会带上你的名字和邮箱,团队成员看 `git log` 时能看到谁提交了什么。**配置错了,所有提交都会带错信息**,事后改起来很麻烦。
### 生活类比
##### 生活类比
Git 就像一个**班级签到表**——每次提交都相当于签到,签到必须写上"姓名 + 学号"。第一次用 Git 必须先"登记"自己的信息,不然签到表上全是"匿名"。
---
## 举个例子
#### 举个例子
### 输入
##### 输入
#### 全局配置(张三在个人电脑上配置)
##### 全局配置(张三在个人电脑上配置)
```bash
# 1. 设置全局用户名和邮箱(只需要做一次)
###### 1. 设置全局用户名和邮箱(只需要做一次)
git config --global user.name "张三"
git config --global user.email "zhangsan@example.com"
# 2. 设置默认编辑器为 VS Code(推荐)
###### 2. 设置默认编辑器为 VS Code(推荐)
git config --global core.editor "code --wait"
# 3. 设置默认分支名为 main(GitHub 默认也是 main)
###### 3. 设置默认分支名为 main(GitHub 默认也是 main)
git config --global init.defaultBranch main
```
#### 局部配置(张三在某个项目仓库中配置)
##### 局部配置(张三在某个项目仓库中配置)
```bash
# 进入某个项目目录
......@@ -150,9 +150,9 @@ git config core.editor "code --wait"
git config --list --local
```
### 输出
##### 输出
#### 全局配置输出
###### 全局配置输出
```bash
# 查看刚刚的配置
......@@ -163,7 +163,7 @@ git config --list | grep -E "user|editor|defaultBranch"
# init.defaultBranch=main
```
#### 局部配置输出
##### 局部配置输出
```bash
# 查看当前仓库的配置
......@@ -178,7 +178,7 @@ git config --list --local
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| ---------------- | -------------------------------------------------------------------------- | ------------------------------------- |
......@@ -193,7 +193,6 @@ git config --list --local
# 没配置就提交
$ git commit -m "first commit"
# 输出(看起来一切正常)
$ git log --format="%an <%ae>"
# 作者显示为:
# Your Name <you@example.com>
......@@ -202,9 +201,9 @@ $ git log --format="%an <%ae>"
---
## 实战代码
#### 实战代码
### 全套配置(建议入职第一天就执行)
##### 全套配置(建议入职第一天就执行)
```bash
# === 身份信息 ===
......@@ -231,7 +230,7 @@ git config --global color.ui auto
git config --list
```
### 全局 vs 仓库级 vs 单次命令
##### 全局 vs 仓库级 vs 单次命令
| 范围 | 命令示例 | 作用范围 |
| ---------------- | ------------------------------------------ | -------------------------- |
......@@ -241,7 +240,7 @@ git config --list
---
## 常见问题
#### 常见问题
**Q:配置错了,已经提交了几十个 commit,能批量改作者信息吗?**
......@@ -265,7 +264,7 @@ A:GitHub 提供了 noreply 邮箱(`username@users.noreply.github.com`),
---
## 验收标准
#### 验收标准
```
☐ 能用 git config --global 设置 user.name 和 user.email
......@@ -275,12 +274,12 @@ A:GitHub 提供了 noreply 邮箱(`username@users.noreply.github.com`),
☐ 知道为什么要用真实邮箱而不是随便填
```
## 官方来源
##### 官方来源
- Git 官方文档 - 初次配置 Git:[https://git-scm.com/book/zh/v2/起步-初次运行-Git-前的配置](https://git-scm.com/book/zh/v2/%E8%B5%B7%E6%AD%A5-%E5%88%9D%E6%AC%A1%E8%BF%90%E8%A1%8C-Git-%E5%89%8D%E7%9A%84%E9%85%8D%E7%BD%AE)
- `git-config` 手册页:[https://git-scm.com/docs/git-config](https://git-scm.com/docs/git-config)
## 参考文献
##### 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 1.5 节.
[2] Git 官方文档. *Git Config*. [https://git-scm.com/docs/git-config](https://git-scm.com/docs/git-config)
......@@ -293,17 +292,17 @@ A:GitHub 提供了 noreply 邮箱(`username@users.noreply.github.com`),
## 1.1.2 克隆项目
### 什么是克隆(clone)?
#### 什么是克隆(clone)?
#### 一句话定义
##### 一句话定义
`git clone <仓库地址>` 把远程仓库的**完整历史**复制到本地,生成一个全新的工作目录。
### 为什么重要
##### 为什么重要
进入一个新团队,第一件事就是 `git clone`,把项目代码拉下来。**克隆得到的本地仓库和远程仓库完全独立**——你在本地怎么改都不会影响远程,直到你 `git push`。
### 生活类比
##### 生活类比
- `git clone` = 把一个**连锁店的整套账本**复印一份放到你的工位上
- 你改自己的账本,原店不受影响
......@@ -311,9 +310,9 @@ A:GitHub 提供了 noreply 邮箱(`username@users.noreply.github.com`),
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```bash
# 假设公司仓库地址是:git@github.com:cfm-team/smartqa.git
......@@ -322,7 +321,7 @@ git clone git@github.com:cfm-team/smartqa.git
# 默认克隆到 ./smartqa 目录
```
### 输出
##### 输出
```bash
Cloning into 'smartqa'...
......@@ -336,7 +335,7 @@ Resolving deltas: 100% (856/856), done.
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| -------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------- |
......@@ -347,9 +346,9 @@ Resolving deltas: 100% (856/856), done.
---
## 实战代码
#### 实战代码
### HTTPS vs SSH 两种方式对比
#### HTTPS vs SSH 两种方式对比
| 维度 | HTTPS 协议 | SSH 协议 |
| ------------------ | ----------------------------------------- | ------------------------------------ |
......@@ -358,28 +357,24 @@ Resolving deltas: 100% (856/856), done.
| 是否每次都要输密码 | 是(除非配 PAT 或 credential helper) | 否,只需配一次 SSH key |
| 适合谁 | 临时克隆开源项目、CI/CD | 日常开发、需要频繁 push/pull |
### 配置 SSH Key(推荐日常使用)
#### 配置 SSH Key(推荐日常使用)
```bash
# 1. 生成 SSH 密钥对(一路回车即可)
ssh-keygen -t ed25519 -C "your.email@example.com"
# 输出:
# Generating public/private ed25519 key pair.
###### 1. 生成 SSH 密钥对(一路回车即可)ssh-keygen -t ed25519 -C "your.email@example.com"
##### 输出:# Generating public/private ed25519 key pair.
# Enter file in which to save the key (/home/you/.ssh/id_ed25519): [回车]
# Enter passphrase (empty for no passphrase): [回车]
# Your identification has been saved in /home/you/.ssh/id_ed25519
# Your public key has been saved in /home/you/.ssh/id_ed25519.pub
# 2. 复制公钥内容到剪贴板
cat ~/.ssh/id_ed25519.pub
###### 2. 复制公钥内容到剪贴板cat ~/.ssh/id_ed25519.pub
# 把输出粘贴到 GitHub → Settings → SSH and GPG keys → New SSH key
# 3. 测试连接
ssh -T git@github.com
###### 3. 测试连接ssh -T git@github.com
# Hi <your-username>! You've successfully authenticated...
```
### 克隆到指定目录
#### 克隆到指定目录
```bash
# 克隆并改名(自动进入新目录)
......@@ -389,7 +384,7 @@ git clone git@github.com:user/repo.git my-project
git clone git@github.com:user/repo.git .
```
### 只克隆最新一次提交(浅克隆)
#### 只克隆最新一次提交(浅克隆)
```bash
# 适合只想看最新代码、节省时间的场景
......@@ -399,7 +394,7 @@ git clone --depth 1 git@github.com:user/repo.git
git fetch --unshallow
```
### 克隆指定分支
#### 克隆指定分支
```bash
# 方法 1:克隆后切换到指定分支
......@@ -410,32 +405,28 @@ git switch develop # 克隆默认是 main,改切到 develop
git clone --branch develop git@github.com:user/repo.git
```
### 克隆后的标准流程
#### 克隆后的标准流程
```bash
# 1. 进入仓库目录
cd my-project
###### 1. 进入仓库目录cd my-project
# 2. 查看克隆后的状态(自动配置好了 origin 远程)
git remote -v
###### 2. 查看克隆后的状态(自动配置好了 origin 远程)git remote -v
# origin git@github.com:user/repo.git (fetch)
# origin git@github.com:user/repo.git (push)
# 3. 查看当前分支
git branch -a
###### 3. 查看当前分支git branch -a
# * main
# remotes/origin/HEAD -> origin/main ← 默认分支
# remotes/origin/develop
# remotes/origin/feature/xxx
# 4. 克隆后第一件事:配置你的身份(见 1.1.1)
git config user.name "张三"
###### 4. 克隆后第一件事:配置你的身份(见 1.1.1)git config user.name "张三"
git config user.email "zhangsan@company.com"
```
---
## 常见问题
#### 常见问题
**Q:克隆时报错 `Permission denied (publickey)`?**
......@@ -484,7 +475,7 @@ git fetch --unshallow
---
## 验收标准
#### 验收标准
```
☐ 能用 git clone <ssh-url> 把项目拉下来
......@@ -496,12 +487,12 @@ git fetch --unshallow
☐ 知道克隆后要配置 git 身份信息
```
## 官方来源
##### 官方来源
- `git-clone` 手册页:[https://git-scm.com/docs/git-clone](https://git-scm.com/docs/git-clone)
- GitHub - About SSH:[https://docs.github.com/en/authentication/connecting-to-github-with-ssh](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
## 参考文献
##### 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 2.1 节 "Git 基础 - 获取 Git 仓库".
[2] GitHub Docs. *Cloning a repository*. [https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
......@@ -510,21 +501,21 @@ git fetch --unshallow
## 1.1.3 分支操作
### 什么是分支?
#### 什么是分支?
> 用 1-2 句话说清:**分支 = 你的"平行宇宙"**,在分支上随便改不会影响主线,合并时再合到一起。
---
### 一句话定义
##### 一句话定义
分支(branch)是指向某个 commit 的**可移动指针**。新分支让你在不影响主线的情况下自由开发。
### 为什么重要
##### 为什么重要
团队协作的核心机制:**每个人在自己的分支开发,互不干扰**,开发完再合并。多分支让你可以**同时推进多个任务**(修 bug、做新功能、发版本)。
### 生活类比
##### 生活类比
想象你在写一本书:
......@@ -536,7 +527,7 @@ git fetch --unshallow
---
## ASCII 分支示意图
##### ASCII 分支示意图
```
main 分支(稳定版)
......@@ -552,16 +543,15 @@ git fetch --unshallow
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```bash
# 查看所有分支
git branch -a
# 输出:
# * main
##### 输出:# * main
# remotes/origin/main
# remotes/origin/feature/login
# (* 表示当前所在分支)
......@@ -578,7 +568,7 @@ git switch main
git branch -d feature/login
```
### 输出
##### 输出
```bash
$ git switch -c feature/login
......@@ -588,7 +578,7 @@ Switched to a new branch 'feature/login'
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| ------------------ | -------------------------------------------------------------- | -------------------------------------------------------- |
......@@ -616,9 +606,9 @@ $ git branch -d feature/login
---
## 原理深入
#### 原理深入
### 分支的本质
#### 分支的本质
Git 的分支**只是一个指向 commit 对象的可变指针**:
......@@ -631,37 +621,32 @@ Git 的分支**只是一个指向 commit 对象的可变指针**:
创建分支 = 写入 41 字节(一个 SHA-1)的文件,**几乎是瞬间完成的**。
### HEAD 的含义
#### HEAD 的含义
`HEAD` 是一个**特殊指针**,指向"当前所在分支"。`git switch` 实际是把 HEAD 指向另一个分支(如 `refs/heads/feature/login`)。
---
## 实战代码
#### 实战代码
### 一套完整的分支操作流程
```bash
# 1. 从 main 切出 feature 分支
git switch main # 先回到 main
###### 1. 从 main 切出 feature 分支git switch main # 先回到 main
git pull # 确保 main 是最新的
git switch -c feature/add-login # 创建并切到新分支
# 2. 在新分支上开发
echo "登录功能代码" > login.py
###### 2. 在新分支上开发echo "登录功能代码" > login.py
git add login.py
git commit -m "feat(login): 新增登录接口"
# 3. 推送到远程
git push -u origin feature/add-login
###### 3. 推送到远程git push -u origin feature/add-login
# 4. 在 main 上合并这个 feature
git switch main
###### 4. 在 main 上合并这个 featuregit switch main
git merge feature/add-login
git push
# 5. 清理已合并的本地分支
git branch -d feature/add-login
###### 5. 清理已合并的本地分支git branch -d feature/add-login
```
### 分支命名约定(见 1.1.11 详述)
......@@ -711,7 +696,7 @@ git stash pop
---
## 常见问题
#### 常见问题
**Q:`switch` 和 `checkout` 到底用哪个?**
......@@ -782,7 +767,7 @@ git branch -vv
---
## 验收标准
#### 验收标准
```
☐ 能用 git switch -c 创建并切换分支
......@@ -795,39 +780,39 @@ git branch -vv
☐ 能在合并后清理已合并的 feature 分支
```
## 官方来源
##### 官方来源
- `git-branch` 手册页:[https://git-scm.com/docs/git-branch](https://git-scm.com/docs/git-branch)
- `git-switch` 手册页:[https://git-scm.com/docs/git-switch](https://git-scm.com/docs/git-switch)
- Git Book - 分支简介:[https://git-scm.com/book/zh/v2/Git-分支-分支简介](https://git-scm.com/book/zh/v2/Git-%E5%88%86%E6%94%AF-%E5%88%86%E6%94%AF%E7%AE%80%E4%BB%8B)
## 参考文献
##### 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 3 章 "Git 分支".
[2] Git Book. *Git Branching - Rebasing*. [https://git-scm.com/book/zh/v2/Git-分支-分支变基](https://git-scm.com/book/zh/v2/Git-%E5%88%86%E6%94%AF-%E5%88%86%E6%94%AF%E5%8F%98%E5%9F%BA)
---
### 1.1.4 同步代码
## 1.1.4 同步代码
> 用 1-2 句话说清:从远程把队友的改动拿过来——这一步有 3 种方式,**用错方式会让你后悔**。
---
## 什么是同步代码?
#### 什么是同步代码?
### 一句话定义
##### 一句话定义
"同步"包含**两个动作**:
- **下载**(fetch):把远程的新 commit 拉到本地,但**不修改**你的工作区
- **合并 / 变基**(merge / rebase):把下载下来的 commit 整合到你当前分支
### 为什么重要
##### 为什么重要
多人协作时,大家都在自己的分支上开发。**你需要定期把队友的代码同步到自己本地**,否则你的本地版本会越来越落后,最终合并时产生大量冲突。
### 生活类比
##### 生活类比
想象你在改论文,老师时不时在共享文档里加批注:
......@@ -837,9 +822,9 @@ git branch -vv
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```bash
# 方式 1:纯下载,不合并
......@@ -852,7 +837,7 @@ git pull origin main
git pull --rebase origin main
```
### 输出
##### 输出
```bash
$ git fetch origin
......@@ -868,7 +853,7 @@ Your branch is behind 'origin/main' by 3 commits, and can be fast-forwarded.
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| ------------ | ------------------------------------------------------- | ------------------------------------------------- |
......@@ -879,7 +864,7 @@ Your branch is behind 'origin/main' by 3 commits, and can be fast-forwarded.
---
## 原理深入:fetch vs pull vs pull --rebase ASCII 时间线对比
#### 原理深入:fetch vs pull vs pull --rebase ASCII 时间线对比
**场景**:你和队友从同一个 commit `A` 出发,各自开发后你提交了 `B`,队友提交了 `C`。
......@@ -896,7 +881,7 @@ A
你本地 .git 里没有 C
```
### 步骤 1:fetch(下载但不合并)
###### 步骤 1:fetch(下载但不合并)
```
$ git fetch
......@@ -917,7 +902,7 @@ A ─── C ←─────────────────────
B ←────── main (你当前分支)
```
### 步骤 2a:merge(pull 默认行为)
###### 步骤 2a:merge(pull 默认行为)
```
$ git pull # = fetch + merge
......@@ -931,7 +916,7 @@ A ──┬── B (你)
历史变成"分叉→合并"的菱形,对人类阅读不友好。
### 步骤 2b:rebase(pull --rebase 行为)
###### 步骤 2b:rebase(pull --rebase 行为)
```
$ git pull --rebase # = fetch + rebase
......@@ -954,26 +939,24 @@ A ── C ── B'(你的 commit 改了个"新爸爸")
---
## 实战代码
#### 实战代码
### 推荐的标准流程(个人 feature 分支)
#### 推荐的标准流程(个人 feature 分支)
```bash
# 1. 早上开工,先 sync 一次
git switch feature/login
###### 1. 早上开工,先 sync 一次git switch feature/login
git fetch origin
git pull --rebase origin main # 把 main 的改动"挪到"我前面
# 现在我的 feature/login 始终建立在最新 main 之上
# 2. 推上去前再 sync 一次(防止 PR 合并冲突)
git fetch origin
###### 2. 推上去前再 sync 一次(防止 PR 合并冲突)git fetch origin
git pull --rebase origin main
git push -f # 因为 rebase 改写了 history,需要 -f
# ⚠️ 注意:-f 仅在你**自己的 feature 分支**上用,main 上永远不要 -f!
```
### 多人共用分支的正确流程
#### 多人共用分支的正确流程
```bash
# 假设 dev 分支是你和同事都在用的
......@@ -985,7 +968,7 @@ git pull # 用 merge,不要 rebase 别人写过的 commit
---
## 常见问题
#### 常见问题
**Q:我 `git pull` 后报了一堆冲突,怎么办?**
......@@ -995,17 +978,11 @@ A:根据用的是 merge 还是 rebase,处理方式略有不同:
# ===== merge 冲突处理 =====
git pull origin main
# 出现冲突后:
# 1. 编辑冲突文件,去掉 <<<<<<< ======= >>>>>>> 标记
# 2. git add <冲突文件>
# 3. git commit -m "解决冲突:xxx"
###### 1. 编辑冲突文件,去掉 <<<<<<< ======= >>>>>>> 标记###### 2. git add <冲突文件>###### 3. git commit -m "解决冲突:xxx"
# ===== rebase 冲突处理 =====
git pull --rebase origin main
# 出现冲突后:
# 1. 编辑冲突文件,去掉 <<<<<<< ======= >>>>>>> 标记
# 2. git add <冲突文件>
# 3. git rebase --continue # 继续处理下一个 commit
# 或者如果不想继续:
###### 1. 编辑冲突文件,去掉 <<<<<<< ======= >>>>>>> 标记###### 2. git add <冲突文件>###### 3. git rebase --continue # 继续处理下一个 commit# 或者如果不想继续:
git rebase --abort # 放弃这次 rebase,回到之前的状态
```
......@@ -1027,7 +1004,7 @@ git pull origin main --allow-unrelated-histories
A:看场景:
| 场景 | 推荐 | 原因 |
|------|------|------|
| ---------------- | ------------------------------------- | ---------------------------- |
| 日常同步个人分支 | `git fetch` + 检查后再 merge/rebase | 更安全,可以先看远程改了什么 |
| 急着看最新代码 | `git pull` | 一步到位 |
| 提交前同步 | `git pull --rebase` | 保持线性历史 |
......@@ -1052,7 +1029,7 @@ A:在**个人 feature 分支上没问题**:
---
## 验收标准
#### 验收标准
```
☐ 能区分 fetch / pull / pull --rebase 三者差别
......@@ -1066,36 +1043,36 @@ A:在**个人 feature 分支上没问题**:
☐ 能处理 "refusing to merge unrelated histories" 错误
```
## 官方来源
##### 官方来源
- `git-fetch` 手册页:[https://git-scm.com/docs/git-fetch](https://git-scm.com/docs/git-fetch)
- `git-pull` 手册页:[https://git-scm.com/docs/git-pull](https://git-scm.com/docs/git-pull)
- Git Book - 变基:[https://git-scm.com/book/zh/v2/Git-分支-变基](https://git-scm.com/book/zh/v2/Git-%E5%88%86%E6%94%AF-%E5%8F%98%E5%9F%BA)
## 参考文献
##### 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 3.6 节 "变基".
[2] Git Book. *Git Branching - Rebasing*. [https://git-scm.com/book/zh/v2/Git-分支-分支变基](https://git-scm.com/book/zh/v2/Git-%E5%88%86%E6%94%AF-%E5%88%86%E6%94%AF%E5%8F%98%E5%9F%BA)
---
### 1.1.5 提交代码
## 1.1.5 提交代码
> 用 1-2 句话说清:**把改动"打个存档点"**——存什么、写什么说明、能不能撤回。
---
## 什么是提交(commit)?
#### 什么是提交(commit)?
### 一句话定义
##### 一句话定义
`git commit` 把**暂存区里的所有改动**打包成一个"存档点"(commit 对象),永久存进 `.git` 数据库。
### 为什么重要
##### 为什么重要
commit 是 Git 最小的"撤销单位"。一个 commit 就是一个完整的快照(不是 diff),所以你可以随时回到任意一个 commit。
### 生活类比
##### 生活类比
commit = 游戏的**存档点**:
......@@ -1105,9 +1082,9 @@ commit = 游戏的**存档点**:
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```bash
# 完整的提交流程
......@@ -1117,7 +1094,7 @@ git add README.md # 选一个文件放进暂
git commit -m "docs: 新增 README"
```
### 输出
##### 输出
```bash
$ git status
......@@ -1138,7 +1115,7 @@ $ git commit -m "docs: 新增 README"
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| ------------------ | ---------------------------------------------------------- | ------------------------------------------- |
......@@ -1172,7 +1149,7 @@ b3e1d24 update
---
## 实战代码
#### 实战代码
### `git add` 三种模式对比
......@@ -1185,19 +1162,16 @@ b3e1d24 update
### `git commit` 三种写法
```bash
# 1. 单行 message
git commit -m "docs: 新增 README"
###### 1. 单行 messagegit commit -m "docs: 新增 README"
# 2. 多行 message(推荐用于重要 commit)
git commit
###### 2. 多行 message(推荐用于重要 commit)git commit
# 弹出编辑器,写:
# docs: 新增项目说明文档
#
# - 增加安装步骤
# - 增加使用示例
# 3. 修改上一次 commit(追加 / 修改信息)
git commit --amend -m "新的 message"
###### 3. 修改上一次 commit(追加 / 修改信息)git commit --amend -m "新的 message"
# ⚠️ 别在已 push 的 commit 上用 --amend,会导致历史分歧
```
......@@ -1210,7 +1184,7 @@ git commit --amend -m "新的 message"
| 撤回工作区改动 | `git restore <file>` | 不可恢复! |
| 撤销旧写法 | `git checkout -- <file>` | |
### amend 的应用场景
#### amend 的应用场景
```bash
# 场景:刚 commit 完,发现忘 add 了一个文件
......@@ -1223,8 +1197,7 @@ $ git status
# 改写上一次 commit
$ git add tests/test_login.py
$ git commit --amend --no-edit
# 输出:
# [main 8e4d2c3] feat: 新增登录接口
##### 输出:# [main 8e4d2c3] feat: 新增登录接口
# Date: Thu Jul 7 10:30:00 2026 +0800
# 2 files changed, 45 insertions(+)
# commit ID 变了,但 message 不变;之前的提交并入了这次
......@@ -1232,7 +1205,7 @@ $ git commit --amend --no-edit
---
## 常见问题
#### 常见问题
**Q:commit 后才发现漏了文件,能补进去吗?**
......@@ -1255,7 +1228,7 @@ A:
---
## 验收标准
#### 验收标准
```
☐ 能用 git add / git commit 完成一次提交
......@@ -1265,35 +1238,35 @@ A:
☐ 能写出格式良好的 commit message(见 1.1.11)
```
## 官方来源
##### 官方来源
- `git-commit` 手册页:[https://git-scm.com/docs/git-commit](https://git-scm.com/docs/git-commit)
- `git-add` 手册页:[https://git-scm.com/docs/git-add](https://git-scm.com/docs/git-add)
- `git-restore` 手册页:[https://git-scm.com/docs/git-restore](https://git-scm.com/docs/git-restore)
## 参考文献
##### 参考文献
[1] *Pro Git* 第 2.2 节 "记录每次更新到仓库"。
---
### 1.1.6 推送代码
## 1.1.6 推送代码
> 用 1-2 句话说清:**把本地存档同步给队友**——但要小心"覆盖别人"和"-f 的危险"。
---
## 什么是推送(push)?
#### 什么是推送(push)?
### 一句话定义
##### 一句话定义
`git push` 把本地分支的 commit **同步到远程仓库**。
### 为什么重要
##### 为什么重要
你 commit 到本地只是给自己存档,**push 才能让队友看到你的改动**。团队协作的"信息源"是远程仓库,所有人通过 push/pull 同步。
### 生活类比
##### 生活类比
- commit = 在自己的笔记本上做笔记
- push = 把笔记内容拍成照片发给团队群
......@@ -1301,9 +1274,9 @@ A:
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```bash
# 第一次推送当前分支 + 设置 upstream(跟踪关系)
......@@ -1313,7 +1286,7 @@ git push -u origin feature/login
git push
```
### 输出
##### 输出
```bash
$ git push -u origin feature/login
......@@ -1329,7 +1302,7 @@ Branch 'feature/login' set up to track remote branch 'feature/login' from 'origi
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| -------- | ------------------------------------------- | -------------------------------------------------------- |
......@@ -1354,7 +1327,7 @@ hint: 'git pull ...') before pushing again.
---
## 原理深入:`-u` 的含义
#### 原理深入:`-u` 的含义
`-u` = `--set-upstream`,建立**本地分支与远程分支的跟踪关系**。
......@@ -1376,26 +1349,21 @@ Git 想避免你"误推到错分支"。第一次推送时,本地分支和远
---
## 实战代码
#### 实战代码
### 首次推送个人分支
#### 首次推送个人分支
```bash
# 1. 创建本地分支(详见 1.1.3)
git switch -c feature/add-logout
###### 1. 创建本地分支(详见 1.1.3)git switch -c feature/add-logout
# 2. 开发 + 提交(详见 1.1.5)
echo "logout func" > logout.py
###### 2. 开发 + 提交(详见 1.1.5)echo "logout func" > logout.py
git add logout.py
git commit -m "feat(auth): 新增退出登录接口"
# 3. 首次推送
git push -u origin feature/add-logout
# 输出含 "Branch 'feature/add-logout' set up to track..."
```
### 之后的所有 push
###### 3. 首次推送git push -u origin feature/add-logout
##### 输出含 "Branch 'feature/add-logout' set up to track..."```
#### 之后的所有 push
```bash
# 已建立跟踪,直接 push
git commit -am "fix: 修复退出按钮失效"
......@@ -1421,7 +1389,7 @@ git push --force-with-lease origin feature/my-branch
---
## 常见问题
#### 常见问题
**Q:push 时报错 `non-fast-forward`,怎么办?**
......@@ -1446,7 +1414,7 @@ A:见 1.1.9 版本回退。一般做法:
---
## 验收标准
#### 验收标准
```
☐ 能用 git push -u origin <branch> 首次推送个人分支
......@@ -1456,34 +1424,34 @@ A:见 1.1.9 版本回退。一般做法:
☐ 能处理 push 被拒绝(rejected)的场景
```
## 官方来源
##### 官方来源
- `git-push` 手册页:[https://git-scm.com/docs/git-push](https://git-scm.com/docs/git-push)
- GitHub - About protected branches:[https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)
## 参考文献
##### 参考文献
[1] *Pro Git* 第 2.5 节 "远程仓库的使用"。
---
### 1.1.7 合并与冲突处理
## 1.1.7 合并与冲突处理
> 用 1-2 句话说清:**把两个分支的改动合二为一**——但当 Git 不知道怎么合并时,就需要你亲自下场。
---
## 什么是合并与冲突?
#### 什么是合并与冲突?
### 一句话定义
##### 一句话定义
`git merge` 把一个分支的改动**合并到当前分支**;当同一文件的同一位置被不同分支修改时,Git 无法自动合并,这就是**冲突(conflict)**。
### 为什么重要
##### 为什么重要
团队协作的核心流程:**在 feature 分支开发 → 合并到 main**。合并时遇到冲突是家常便饭,能否正确解决冲突直接决定你的代码能否上线。
### 生活类比
##### 生活类比
你和队友同时在修改同一份文档:
......@@ -1493,35 +1461,30 @@ A:见 1.1.9 版本回退。一般做法:
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```bash
# 场景:feature/login 开发完成,合并到 main
# 1. 切到 main
git switch main
###### 1. 切到 maingit switch main
# 2. 拉取最新代码
git pull origin main
###### 2. 拉取最新代码git pull origin main
# 3. 合并 feature/login
git merge feature/login
###### 3. 合并 feature/logingit merge feature/login
```
### 输出(无冲突时)
##### 输出(无冲突时)```bash
```bash
$ git merge feature/login
Merge made by the 'ort' strategy.
README.md | 2 ++
1 file changed, 2 insertions(+)
```
### 输出(有冲突时)
```
```bash
##### 输出(有冲突时)```bash
$ git merge feature/login
Auto-merging README.md
CONFLICT (content): Merge conflict in README.md
......@@ -1530,14 +1493,14 @@ Automatic merge failed; fix conflicts and then commit the result.
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| -------- | ------------------------------------------- | ---------------------------- |
| 合并前 | 先切到目标分支并 pull 最新 | 直接在 feature 分支上合并 |
| 解决冲突 | 编辑文件 → 保留需要的部分 → add → commit | 直接 push 或删掉冲突标记就跑 |
| 放弃合并 | `git merge --abort` | 关掉编辑器假装没事发生 |
| 删除分支 | 合并完成后用 `-d` 删除 | 合并完还在原地留着 |
| 删除分支 | 合并完成后用`-d` 删除 | 合并完还在原地留着 |
**冲突标记长这样**:
......@@ -1551,9 +1514,9 @@ Automatic merge failed; fix conflicts and then commit the result.
---
## 原理深入:Fast-forward vs 三方合并
#### 原理深入:Fast-forward vs 三方合并
### Fast-forward(快进合并)
#### Fast-forward(快进合并)
当 main 没有新提交时,Git 直接"指针移动",不产生新 commit:
......@@ -1567,7 +1530,7 @@ main: A ── B ── C ── D
└── feature (已合并)
```
### 三方合并(Recursive)
#### 三方合并(Recursive)
当 main 有新提交时,Git 需要"三方比较":
......@@ -1583,29 +1546,24 @@ Git 比较:A(共同祖先) vs B(main改动) vs C(feature改动)
---
## 实战代码
#### 实战代码
### 1. 标准合并流程
###### 1. 标准合并流程
```bash
# 1. 确保在 main 分支
git switch main
###### 1. 确保在 main 分支git switch main
# 2. 确保 main 是最新的
git pull origin main
###### 2. 确保 main 是最新的git pull origin main
# 3. 执行合并
git merge feature/login
###### 3. 执行合并git merge feature/login
# 4. 如果有冲突,解决后:
git add <冲突文件>
###### 4. 如果有冲突,解决后:git add <冲突文件>
git commit -m "Merge branch 'feature/login' into main"
# 5. 合并完成后删除 feature 分支
git branch -d feature/login
###### 5. 合并完成后删除 feature 分支git branch -d feature/login
```
### 2. 解决冲突的完整步骤
###### 2. 解决冲突的完整步骤
```bash
# 冲突时 Git 会列出冲突文件
......@@ -1631,14 +1589,14 @@ git add README.md
git commit -m "Merge branch 'feature/login' into main"
```
### 3. Abort 放弃合并
###### 3. Abort 放弃合并
```bash
# 冲突太复杂,想放弃重来
git merge --abort
```
### 4. Squash Merge(压缩合并)
###### 4. Squash Merge(压缩合并)
把 feature 分支的多个 commit 合并成一个:
......@@ -1650,7 +1608,7 @@ git commit -m "feat: 完成登录功能"
---
## 常见问题
#### 常见问题
**Q:合并时提示 `fatal: refusing to merge unrelated histories`?**
......@@ -1687,7 +1645,7 @@ git revert HEAD # 创建一个新 commit 撤销之前的合并
---
## 验收标准
#### 验收标准
```
☐ 能用 git merge 合并分支
......@@ -1699,36 +1657,36 @@ git revert HEAD # 创建一个新 commit 撤销之前的合并
☐ 知道合并冲突后必须 add + commit 才能完成
```
## 官方来源
##### 官方来源
- `git-merge` 手册页:[https://git-scm.com/docs/git-merge](https://git-scm.com/docs/git-merge)
- Git Book - 合并:[https://git-scm.com/book/zh/v2/Git-分支-分支的衍合](https://git-scm.com/book/zh/v2/Git-%E5%88%86%E6%94%AF-%E5%88%86%E6%94%AF%E7%9A%84%E8%A1%8D%E5%90%88)
## 参考文献
##### 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 3.2 节 "分支的合并"。
---
### 1.1.8 查看历史与差异
## 1.1.8 查看历史与差异
> 用 1-2 句话说清:**翻 Git 的"账本"**——看看过去改了什么、谁改的、每次改动的差异。
---
## 什么是查看历史与差异?
#### 什么是查看历史与差异?
### 一句话定义
##### 一句话定义
- `git log` = 查看提交历史
- `git diff` = 查看两个版本之间的差异
- `git blame` = 查看某行代码是谁写的、什么时候改的
### 为什么重要
##### 为什么重要
当代码出问题、想知道某行代码是谁写的、或要对比两个版本的差异时,这些命令就是你的"侦探工具"。
### 生活类比
##### 生活类比
- `git log` = 翻阅**微信聊天记录**,看谁发了什么消息
- `git diff` = 看**修改前后的对比截图**,哪些地方变了
......@@ -1736,9 +1694,9 @@ git revert HEAD # 创建一个新 commit 撤销之前的合并
---
## 举个例子
#### 举个例子
### git log 查看历史
##### git log 查看历史
```bash
# 基本日志
......@@ -1757,7 +1715,7 @@ git log -5
git log -- README.md
```
### git diff 查看差异
##### git diff 查看差异
```bash
# 查看工作区 vs 暂存区
......@@ -1776,7 +1734,7 @@ git diff abc123..def456
git diff -- README.md
```
### git blame 追溯代码
##### git blame 追溯代码
```bash
# 查看某文件每行的最后修改者
......@@ -1788,10 +1746,10 @@ git blame -L 10,20 README.md
---
## 正解 vs 错误
##### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| ---------- | ----------------------------------- | -------------------------- |
| 看全部历史 | `git log --oneline -20` | `git log` 刷屏找不到重点 |
| 看分支图 | `git log --graph --oneline --all` | 不知道有哪些分支 |
| 看单次改动 | `git show <commit-id>` | `git log` 一路翻 |
......@@ -1812,30 +1770,30 @@ git log -p -- README.md # 看某个文件的详细变更
---
## 原理深入:diff 的三种视角
#### 原理深入:diff 的三种视角
### 1. 工作区 vs 暂存区(`git diff`)
###### 1. 工作区 vs 暂存区(`git diff`)
```
工作区:你正在改的
暂存区:git add 过的
```
### 2. 暂存区 vs HEAD(`git diff --cached`)
###### 2. 暂存区 vs HEAD(`git diff --cached`)
```
暂存区:即将提交的内容
HEAD:最后一次提交
```
### 3. 工作区 vs HEAD(`git diff HEAD`)
###### 3. 工作区 vs HEAD(`git diff HEAD`)
```
工作区:所有未提交的改动
HEAD:最后一次提交
```
### diff 输出解读
##### diff 输出解读
```bash
$ git diff
......@@ -1852,25 +1810,25 @@ index 1234567..89abcdef 100644
---
## 实战代码
#### 实战代码
### 1. 完整历史查询
###### 1. 完整历史查询```bash
##### 按时间排序
```bash
# 按时间排序
git log --oneline --date=relative --pretty=format:"%h %s %ad %an"
# 输出:
# a1b2c3d feat: 新增登录功能 2 days ago Zhang San
# e4f5g6h fix: 修复注册 bug 5 days ago Li Si
##### 输出:# a1b2c3d feat: 新增登录功能 2 days ago Zhang San
##### e4f5g6h fix: 修复注册 bug 5 days ago Li Si
#### 查看某个 commit 的完整信息
# 查看某个 commit 的完整信息
git show a1b2c3d
```
### 2. 差异对比
```
```bash
###### 2. 差异对比```bash
# 比较两次提交
git diff abc123..def456
......@@ -1884,24 +1842,24 @@ git diff --name-only
git diff > changes.patch
```
### 3. blame 追溯
###### 3. blame 追溯```bash
#### 查看某文件的每行代码来源
```bash
# 查看某文件的每行代码来源
git blame README.md
# 输出示例:
^1234567 (Zhang San 2024-01-01 1) # 项目说明
##### 输出示例:^1234567 (Zhang San 2024-01-01 1) # 项目说明
ab8c9d2e (Li Si 2024-01-15 2) 新增使用方法
3f4g5h6i (Zhang San 2024-02-01 3) 修复错别字
# 只看特定行
##### 只看特定行
git blame -L 10,20 README.md
```
### 4. 搜索历史
```
```bash
###### 4. 搜索历史```bash
# 搜索 commit 消息
git log --grep="登录"
......@@ -1914,7 +1872,7 @@ git log --follow -p path/to/file.py
---
## 常见问题
##### 常见问题
**Q:`git diff` 输出太多,看不过来?**
......@@ -1951,7 +1909,7 @@ git config --global i18n.logOutputEncoding utf-8
---
## 验收标准
#### 验收标准
```
☐ 能用 git log --oneline 查看精简历史
......@@ -1963,35 +1921,35 @@ git config --global i18n.logOutputEncoding utf-8
☐ 能用 git log -p 查看某个文件的历史变更
```
## 官方来源
##### 官方来源
- `git-log` 手册页:[https://git-scm.com/docs/git-log](https://git-scm.com/docs/git-log)
- `git-diff` 手册页:[https://git-scm.com/docs/git-diff](https://git-scm.com/docs/git-diff)
- `git-blame` 手册页:[https://git-scm.com/docs/git-blame](https://git-scm.com/docs/git-blame)
## 参考文献
##### 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 2.3 节 "查看提交历史"。
---
### 1.1.9 版本回退
## 1.1.9 版本回退
> 用 1-2 句话说清:**后悔药**——写错了、删错了、push 错了,都能找回来。
---
## 什么是版本回退?
#### 什么是版本回退?
### 一句话定义
##### 一句话定义
当代码出问题或需要回到历史版本时,使用 `git reset` / `git revert` / `git reflog` 三种方式回退。
### 为什么重要
##### 为什么重要
Git 是"防删神器"——只要 commit 过,几乎没有真正丢失的数据。学会回退,你就拥有了"后悔药"。
### 生活类比
##### 生活类比
- **游戏存档**:打 boss 死了,读档重来
- **Ctrl+Z**:写错了,撤回
......@@ -1999,19 +1957,19 @@ Git 是"防删神器"——只要 commit 过,几乎没有真正丢失的数据
---
## 三种回退方式对比
#### 三种回退方式对比
| 命令 | 作用 | 是否改写历史 | 适用场景 |
| --- | --- | --- | --- |
| -------------- | --------------------------- | ------------ | ----------------------------- |
| `git reset` | 移动 HEAD 指针 | ✅ 改写 | 撤销本地未 push 的 commit |
| `git revert` | 创建新 commit 撤销旧 commit | ❌ 不改写 | 撤销已 push 的 commit(安全) |
| `git reflog` | 恢复误删的 commit | ✅ 改写 | 恢复彻底消失的 commit |
---
## 举个例子
#### 举个例子
### 场景 1:撤销本地最后一个 commit(还没 push)
##### 场景 1:撤销本地最后一个 commit(还没 push)
```bash
# 查看最近 3 个 commit
......@@ -2027,7 +1985,7 @@ git reset --mixed HEAD~1 # 默认
git reset --hard HEAD~1
```
### 场景 2:撤销已 push 的 commit
##### 场景 2:撤销已 push 的 commit
```bash
# 创建新 commit 撤销指定 commit
......@@ -2037,14 +1995,13 @@ git revert HEAD
git push origin main
```
### 场景 3:恢复误删的 commit
##### 场景 3:恢复误删的 commit
```bash
# 查看所有操作记录(包含被 reset 的)
git reflog
# 输出:
# a1b2c3d HEAD@{0}: reset: moving to HEAD~1
##### 输出:# a1b2c3d HEAD@{0}: reset: moving to HEAD~1
# e4f5g6h HEAD@{1}: commit: 新增功能
# 恢复到 e4f5g6h
......@@ -2053,10 +2010,10 @@ git reset --hard e4f5g6h
---
## 正解 vs 错误
##### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| ----------------- | ------------------------------------------- | ------------------------------------- |
| 撤销本地 commit | `git reset HEAD~1` | 删掉 .git 重来 |
| 撤销已 push 的 | `git revert HEAD` | `git reset --hard` 然后 `-f` 强推 |
| 想撤销多次 commit | `git revert HEAD~3..HEAD` | 多次 revert |
......@@ -2077,9 +2034,9 @@ git push -f origin main
---
## 原理深入:三种 reset 模式
#### 原理深入:三种 reset 模式
### --soft(软重置)
##### --soft(软重置)
```
HEAD 移动,但:
......@@ -2089,7 +2046,7 @@ HEAD 移动,但:
效果:撤销 commit,但代码还在暂存区
```
### --mixed(混合重置,默认)
##### --mixed(混合重置,默认)
```
HEAD 移动,但:
......@@ -2099,7 +2056,7 @@ HEAD 移动,但:
效果:撤销 commit 和 add,但代码还在工作区
```
### --hard(硬重置)
##### --hard(硬重置)
```
HEAD 移动,但:
......@@ -2109,7 +2066,7 @@ HEAD 移动,但:
效果:彻底回到那个版本 ⚠️
```
### revert vs reset 对比图
##### revert vs reset 对比图
```
reset(改写历史):
......@@ -2125,25 +2082,29 @@ A -> B -> C -> D -> E (HEAD)
---
## 实战代码
#### 实战代码
### 1. 完整回退场景
##### 1. 完整回退场景```bash
##### 2.场景:想回到 3 天前的版本
```bash
# 场景:想回到 3 天前的版本
git log --oneline -10
# 找到目标 commit:abc1234
# 方法 1:reset(本地用)
找到目标 commit:abc1234
方法 1:reset(本地用)
git reset --hard abc1234
# 方法 2:revert(已 push 用)
方法 2:revert(已 push 用)
git revert abc1234
# 会生成一个新 commit,撤销 abc1234 的改动
```
### 2. 只撤销某个文件的改动
会生成一个新 commit,撤销 abc1234 的改动
```
###### 2. 只撤销某个文件的改动
```bash
# 回到该文件的上一个版本
git checkout HEAD -- path/to/file.py
......@@ -2152,14 +2113,13 @@ git checkout HEAD -- path/to/file.py
git restore path/to/file.py
```
### 3. 用 reflog 恢复误操作
##### 3. 用 reflog 恢复误操作
```bash
# 查看完整操作历史
git reflog
# 输出:
# abc1234 HEAD@{0}: commit: 新增功能
##### 输出:# abc1234 HEAD@{0}: commit: 新增功能
# def5678 HEAD@{1}: reset: moving to HEAD~1
# ghi9012 HEAD@{2}: commit: 修复 bug
......@@ -2167,7 +2127,7 @@ git reflog
git reset --hard ghi9012
```
### 4. 撤销 merge
##### 4. 撤销 merge
```bash
# 撤销合并
......@@ -2180,17 +2140,14 @@ git push origin main
---
## 常见问题
#### 常见问题
**Q:已经 `git push -f` 强推了,能恢复吗?**
A:可以,但需要团队配合:
```bash
# 1. 找同事让他们把正确的分支 push 上来
# 2. 或者用 git reflog 找到被删的 commit,然后重新强推
# 3. 联系管理员从 GitHub 恢复
```
###### 1. 找同事让他们把正确的分支 push 上来###### 2. 或者用 git reflog 找到被删的 commit,然后重新强推###### 3. 联系管理员从 GitHub 恢复```
**Q:reset 后还能看到原来的 commit 吗?**
......@@ -2213,7 +2170,7 @@ git push --force # ⚠️ 危险
---
## 验收标准
#### 验收标准
```
☐ 能区分 git reset --soft/--mixed/--hard 三种模式
......@@ -2225,35 +2182,35 @@ git push --force # ⚠️ 危险
☐ 理解 revert 不改写历史,适合公共分支
```
## 官方来源
##### 官方来源
- `git-reset` 手册页:[https://git-scm.com/docs/git-reset](https://git-scm.com/docs/git-reset)
- `git-revert` 手册页:[https://git-scm.com/docs/git-revert](https://git-scm.com/docs/git-revert)
- `git-reflog` 手册页:[https://git-scm.com/docs/git-reflog](https://git-scm.com/docs/git-reflog)
## 参考文献
##### 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 4.4 节 "重写历史"。
---
### 1.1.10 暂存工作
## 1.1.10 暂存工作
> 用 1-2 句话说清:**"我现在手头的工作还没写完,但又得切换分支去处理别的事"**——stash 就是把你的改动"锁进柜子"。
---
## 什么是暂存工作(stash)?
#### 什么是暂存工作(stash)?
### 一句话定义
##### 一句话定义
`git stash` 把工作区的**未提交改动**临时保存起来,之后可以恢复继续工作。
### 为什么重要
##### 为什么重要
当你正在开发一半,突然要切到其他分支处理紧急 bug 时,stash 让你不用 commit 半成品就能切换分支。
### 生活类比
##### 生活类比
你在写报告,写到一半领导让你去开会:
......@@ -2262,9 +2219,9 @@ git push --force # ⚠️ 危险
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```bash
# 正在改代码,但还没写完
......@@ -2284,7 +2241,7 @@ git switch main
git stash pop
```
### 输出
##### 输出
```bash
$ git stash
......@@ -2301,10 +2258,10 @@ Changes not staged for commit:
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| -------------- | ---------------------------------------- | ---------------------- |
| 暂存前 | `git stash` 或 `git stash push` | 随便 commit 一个 "WIP" |
| 暂存时加说明 | `git stash push -m "未完成的登录功能"` | 没有任何描述 |
| 查看暂存列表 | `git stash list` | 忘了存了哪几个 |
......@@ -2314,7 +2271,7 @@ Changes not staged for commit:
---
## 原理深入:stash 的存储结构
#### 原理深入:stash 的存储结构
```
stash 实际创建了两个 commit:
......@@ -2326,9 +2283,9 @@ stash 实际创建了两个 commit:
---
## 实战代码
#### 实战代码
### 1. 基本操作
###### 1. 基本操作
```bash
# 暂存当前改动(简写)
......@@ -2343,8 +2300,7 @@ git stash push -m "wip" path/to/file.py
# 查看暂存列表
git stash list
# 输出:
# stash@{0}: On main: 未完成的登录功能
##### 输出:# stash@{0}: On main: 未完成的登录功能
# stash@{1}: WIP on main: a1b2c3d 初始版本
# 恢复最新 stash 并删除
......@@ -2363,7 +2319,7 @@ git stash drop
git stash clear
```
### 2. 暂存包括未跟踪的文件
###### 2. 暂存包括未跟踪的文件
```bash
# 默认 stash 只会暂存已跟踪的文件
......@@ -2371,50 +2327,47 @@ git stash -u # 包含未跟踪的新文件
git stash --include-untracked
```
### 3. 暂存指定路径
###### 3. 暂存指定路径
```bash
# 只暂存某个目录
git stash push -m "wip" src/components/
```
### 4. 从 stash 创建分支
###### 4. 从 stash 创建分支
```bash
# 从 stash 创建新分支继续工作(stash 内容和当前分支冲突时有用)
git stash branch new-branch stash@{0}
```
### 5. 常用工作流
###### 5. 常用工作流
```bash
# 场景:正在 feature/login 开发,main 出了 bug 要修
# 1. 暂存当前改动
git stash push -m "wip: feature/login"
###### 1. 暂存当前改动git stash push -m "wip: feature/login"
# 2. 切到 main 修 bug
git switch main
###### 2. 切到 main 修 buggit switch main
git pull origin main
# ... 修复 bug ...
git commit -m "fix: 修复登录页崩溃"
git push origin main
# 3. 切回 feature 分支继续开发
git switch feature/login
###### 3. 切回 feature 分支继续开发git switch feature/login
git stash pop
```
---
## 常见问题
#### 常见问题
**Q:stash 和 commit 有什么区别?**
A:
| | stash | commit |
| --- | --- | --- |
| ----------------- | ------------------ | --------------- |
| 目的 | 临时保存工作进度 | 永久存档 |
| 是否生成 commit | 生成特殊 commit | 生成普通 commit |
| 是否在 log 中可见 | `git stash list` | `git log` |
......@@ -2443,7 +2396,7 @@ git stash list
---
## 验收标准
#### 验收标准
```
☐ 能用 git stash 暂存未提交的改动
......@@ -2456,35 +2409,35 @@ git stash list
☐ 能在紧急 bug 修复场景下使用 stash
```
## 官方来源
##### 官方来源
- `git-stash` 手册页:[https://git-scm.com/docs/git-stash](https://git-scm.com/docs/git-stash)
## 参考文献
##### 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 7.3 节 "暂存工作"。
---
### 1.1.11 Commit 规范与分支命名
## 1.1.11 Commit 规范与分支命名
> 用 1-2 句话说清:**让团队 review 不抓狂**——统一的 commit 规范和分支命名让代码历史可读、可追溯。
---
## 什么是 Commit 规范与分支命名?
#### 什么是 Commit 规范与分支命名?
### 一句话定义
##### 一句话定义
规定 commit message 的格式(type: description)和分支的命名规则(如 feature/login)。
### 为什么重要
##### 为什么重要
- 好的 commit 历史让 code review 和 bug 追踪事半功倍
- 混乱的 commit 信息("fix bug"、"update")让团队成员互相折磨
- 规范的分支命名让你一眼看出这个分支是干什么的
### 生活类比
##### 生活类比
学校成绩单的格式:`2024-01-15 数学 95 优`
vs
......@@ -2492,10 +2445,10 @@ vs
---
## 常用 Commit 类型(type)
##### 常用 Commit 类型(type)
| type | 含义 | 示例 |
| --- | --- | --- |
| ------------ | -------------------------- | ------------------------------- |
| `feat` | 新功能 | `feat(login): 新增第三方登录` |
| `fix` | 修复 bug | `fix(cart): 修复结算金额错误` |
| `docs` | 文档 | `docs: 更新 README` |
......@@ -2508,9 +2461,9 @@ vs
---
## 举个例子
#### 举个例子
### Commit Message 格式
##### Commit Message 格式
```bash
# 格式
......@@ -2523,7 +2476,7 @@ docs(api): 更新接口文档
refactor(user): 重构用户模块代码结构
```
### Branch 命名格式
##### Branch 命名格式
```bash
# 常用分支类型
......@@ -2543,10 +2496,10 @@ release/v1.2.0 # 发布版本
---
## 正解 vs 错误
##### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| ----------- | ---------------------------- | -------------------------------- |
| Commit 消息 | `feat(auth): 新增登录功能` | `update`、`fix bug`、`wip` |
| 消息语言 | 统一用英文(或统一用中文) | 混用中英文 |
| 消息长度 | subject ≤ 50 字 | 长篇大论写一坨 |
......@@ -2555,7 +2508,7 @@ release/v1.2.0 # 发布版本
---
## 原理深入:Angular 规范
#### 原理深入:Angular 规范
目前最流行的 Commit 规范来自 Angular 团队:
......@@ -2567,28 +2520,28 @@ release/v1.2.0 # 发布版本
<footer>
```
### Subject 规则
##### Subject 规则
1. 以动词开头
2. 第一字母小写
3. 结尾不加句号
4. 不超过 50 字符
### Body 规则(可选)
##### Body 规则(可选)
- 解释 **what** 和 **why**,不解释 **how**
- 每行不超过 72 字符
### Footer 规则(可选)
##### Footer 规则(可选)
- Breaking changes:`BREAKING CHANGE: xxx`
- 关联 issue:`Closes #123`
---
## 实战代码
#### 实战代码
### 1. 配置 commit 模板
##### 1. 配置 commit 模板
```bash
# 创建 commit 模板
......@@ -2610,7 +2563,7 @@ EOF
git config --global commit.template ~/.gitmessage
```
### 2. commit-msg 钩子检查
##### 2. commit-msg 钩子检查
```bash
# 项目根目录创建 .git/hooks/commit-msg
......@@ -2627,13 +2580,14 @@ EOF
chmod +x .git/hooks/commit-msg
```
### 3. 强制分支命名策略(GitHub)
##### 3. 强制分支命名策略(GitHub)
在仓库 Settings → Branches → Branch protection rules 中:
- Require branches to be named before merge
- Pattern: `(feature|bugfix|hotfix|release)/.+`
### 4. Commitizen 工具
##### 4. Commitizen 工具
```bash
# 安装
......@@ -2642,18 +2596,24 @@ npm install -g commitizen
# 使用交互式 commit
git cz
# 输出:
# ? Select the type of change that you're committing: feat
# ? What is the scope of this change? auth
# ? Write a short description: 新增手机号登录
# ? Provide additional context?
# ? Is this a BREAKING CHANGE? No
##### 输出:
```
---
? Select the type of change that you're committing: feat
? What is the scope of this change? auth
? Write a short description: 新增手机号登录
? Provide additional context?
## 常见问题
? Is this a BREAKING CHANGE? No
```
---
#### 常见问题
**Q:已经 push 了才发现 commit 消息写错了?**
A:用 `git rebase` 交互式修改:
......@@ -2685,7 +2645,7 @@ feature/login/lisi # 李四的登录功能分支
---
## 验收标准
#### 验收标准
```
☐ 能写出符合规范的 commit message:type(scope): description
......@@ -2697,12 +2657,12 @@ feature/login/lisi # 李四的登录功能分支
☐ 能用 commit template 规范团队 commit
```
## 官方来源
##### 官方来源
- Conventional Commits 规范:[https://www.conventionalcommits.org/](https://www.conventionalcommits.org/)
- Git Book - 自定义 Git:[https://git-scm.com/book/zh/v2/Git-基础-自定义-Git](https://git-scm.com/book/zh/v2/Git-%E5%88%86%E5%88%86%E5%9C%B0%E5%8C%96-Git#_git_hooks)
## 参考文献
##### 参考文献
[1] Conventional Commits. *Conventional Commits Specification v1.0.0*. [https://www.conventionalcommits.org/](https://www.conventionalcommits.org/)
[2] Angular Team. *Angular Contributing Guide - Commit Message Format*. [https://github.com/angular/angular/blob/main/CONTRIBUTING.md](https://github.com/angular/angular/blob/main/CONTRIBUTING.md)
......@@ -2721,26 +2681,26 @@ feature/login/lisi # 李四的登录功能分支
---
## 什么是类?
#### 什么是类?
### 一句话定义
##### 一句话定义
类(Class)是创建对象的模板,定义了对象的属性(数据)和方法(行为)。
### 为什么重要
##### 为什么重要
OOP 让代码更接近现实世界的事物,使大型项目的代码结构清晰、易于维护。
### 生活类比
##### 生活类比
- **类** = 汽车的图纸(定义所有汽车有什么:4个轮子、方向盘、发动机)
- **实例** = 根据图纸造出来的具体汽车(张三的红色轿车、李四的蓝色SUV)
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
class Dog:
......@@ -2765,7 +2725,7 @@ print(dog1.bark()) # 旺财 汪汪叫!
print(dog2) # Dog(name=小白, age=5)
```
### 输出
##### 输出
```
旺财 汪汪叫!
......@@ -2774,22 +2734,21 @@ Dog(name=小白, age=5)
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| ------------------ | ------------------------- | -------------------------- |
| __init__ | 定义初始化逻辑 | 把所有属性都设默认值 |
| self | 第一个参数必须是 self | 忘记写 self 或写成其他名字 |
| 类属性 vs 实例属性 | 实例属性在 __init__ 中定义 | 把所有属性都定义为类属性 |
| 类属性 vs 实例属性 | 实例属性在__init__ 中定义 | 把所有属性都定义为类属性 |
| 类型注解 | 给属性和方法加类型注解 | 完全没有类型 |
---
## 实战代码
#### 实战代码
### 1. 完整的类定义
###### 1. 完整的类定义```python
```python
from dataclasses import dataclass
from typing import Optional
......@@ -2799,7 +2758,7 @@ class User:
# 类属性(所有实例共享)
total_users = 0
def __init__(self, username: str, email: str, age: Optional[int] = None):
def__init__(self, username: str, email: str, age: Optional[int] = None):
self.username = username # 实例属性
self.email = email
self.age = age
......@@ -2809,20 +2768,21 @@ class User:
age_info = f",今年 {self.age} 岁" if self.age else ""
return f"我叫 {self.username}{age_info}"
def __repr__(self) -> str:
def__repr__(self) -> str:
return f"User(username={self.username!r}, email={self.email!r})"
# 使用
user1 = User("张三", "zhangsan@example.com", 25)
user2 = User("李四", "lisi@example.com")
print(user1.introduce()) # 我叫 张三,今年 25 岁
print(user2.introduce()) # 我叫 李四
print(User.total_users) # 2
```
### 2. 数据类(简化版)
```
###### 2. 数据类(简化版)
```python
from dataclasses import dataclass
......@@ -2842,7 +2802,7 @@ print(p1.distance_to(p2)) # 5.0
---
## 常见问题
#### 常见问题
**Q:类属性和实例属性有什么区别?**
......@@ -2862,7 +2822,7 @@ A:Python 中 `__init__` 不是构造函数,是**初始化方法**。真正
---
## 验收标准
#### 验收标准
```
☐ 能定义类并创建实例
......@@ -2872,12 +2832,12 @@ A:Python 中 `__init__` 不是构造函数,是**初始化方法**。真正
☐ 能使用类型注解定义属性和方法参数
```
## 官方来源
##### 官方来源
- Python 官方文档 - 类:[https://docs.python.org/zh-cn/3/tutorial/classes.html](https://docs.python.org/zh-cn/3/tutorial/classes.html)
- dataclasses:[https://docs.python.org/zh-cn/3/library/dataclasses.html](https://docs.python.org/zh-cn/3/library/dataclasses.html)
## 参考文献
##### 参考文献
[1] Mark Lutz. *Learning Python (5th Edition)*. O'Reilly, 2013. Chapter 26-28.
......@@ -2889,17 +2849,17 @@ A:Python 中 `__init__` 不是构造函数,是**初始化方法**。真正
---
## 什么是继承?
#### 什么是继承?
### 一句话定义
##### 一句话定义
继承(Inheritance)允许一个新类复用另一个类的属性和方法,同时可以扩展或修改。
### 为什么重要
##### 为什么重要
继承实现代码复用,避免重复定义相似的类。
### 生活类比
##### 生活类比
```
动物(父类)
......@@ -2911,9 +2871,9 @@ A:Python 中 `__init__` 不是构造函数,是**初始化方法**。真正
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
class Animal:
......@@ -2941,7 +2901,7 @@ for animal in animals:
print(animal.speak())
```
### 输出
##### 输出
```
旺财 汪汪!
......@@ -2950,10 +2910,10 @@ for animal in animals:
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| -------- | -------------------------- | ------------------------------------------- |
| 继承写法 | `class Child(Parent):` | `class Child extends Parent`(Java 写法) |
| 调用父类 | `super().__init__(name)` | 不调用,丢失父类初始化 |
| 方法覆盖 | 子类重写方法 | 完全重写不调用 super |
......@@ -2961,9 +2921,9 @@ for animal in animals:
---
## 实战代码
#### 实战代码
### 1. 单继承
###### 1. 单继承
```python
class Animal:
......@@ -2987,7 +2947,7 @@ print(dog.bark()) # 旺财 汪汪叫!
print(dog.breed) # 哈士奇
```
### 2. 多继承与 MRO
###### 2. 多继承与 MRO
```python
class Flyable:
......@@ -3010,7 +2970,7 @@ print(Duck.__mro__)
# (<class 'Duck'>, <class 'Animal'>, <class 'Flyable'>, <class 'Swimmable'>, <class 'object'>)
```
### 3. 抽象基类
###### 3. 抽象基类
```python
from abc import ABC, abstractmethod
......@@ -3044,7 +3004,7 @@ print(rect.area()) # 12.0
---
## 常见问题
#### 常见问题
**Q:Python 支持多重继承吗?**
......@@ -3071,6 +3031,7 @@ D().test() # C(MRO: D -> B -> C -> A)
**Q:什么时候用继承?什么时候用组合?**
A:
- **继承**:是的关系("狗是动物")
- **组合**:有的关系("车有引擎")
......@@ -3086,7 +3047,7 @@ class Car:
---
## 验收标准
#### 验收标准
```
☐ 能用 class Child(Parent) 实现继承
......@@ -3097,12 +3058,12 @@ class Car:
☐ 能区分继承和组合的使用场景
```
## 官方来源
##### 官方来源
- Python 官方文档 - 继承:[https://docs.python.org/zh-cn/3/tutorial/classes.html#inheritance](https://docs.python.org/zh-cn/3/tutorial/classes.html#inheritance)
- abc 模块:[https://docs.python.org/zh-cn/3/library/abc.html](https://docs.python.org/zh-cn/3/library/abc.html)
## 参考文献
##### 参考文献
[1] David Goodger. *Python Patterns: Inheritance vs Composition*. [https://python-patterns.guide/](https://python-patterns.guide/)
......@@ -3114,17 +3075,17 @@ class Car:
---
## 什么是特殊方法?
#### 什么是特殊方法?
### 一句话定义
##### 一句话定义
特殊方法(Magic Methods / Dunder Methods)是 Python 类预留的钩子,让对象支持 `len()`、`str()`、`+` 等内置操作。
### 为什么重要
##### 为什么重要
让自定义对象"像原生类型一样"工作,代码更 Pythonic。
### 生活类比
##### 生活类比
"特殊方法"就像给对象装了"开关",打开后就能用 Python 的内置功能。
......@@ -3133,7 +3094,7 @@ class Car:
## 常用特殊方法速查
| 方法 | 作用 | 调用场景 |
| --- | --- | --- |
| ------------ | ---------------- | ------------------- |
| `__init__` | 初始化 | `obj = Class()` |
| `__str__` | 人类可读字符串 | `print(obj)` |
| `__repr__` | 开发者可读字符串 | `repr(obj)`、调试 |
......@@ -3145,9 +3106,9 @@ class Car:
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
class Vector:
......@@ -3186,7 +3147,7 @@ print(v1 + v2) # Vector(4, 6)
print(abs(v1)) # 5.0
```
### 输出
##### 输出
```
Vector(3, 4)
......@@ -3199,10 +3160,10 @@ Vector(4, 6)
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| ------------------------------- | ----------------------------------------------- | --------------------- |
| __str__ vs __repr__ | __str__ 给用户看,__repr__ 给开发者 | 只写一个 |
| 返回类型 | __str__ 返回 str,__len__ 返回 int | 返回值类型搞错 |
| 比较操作 | 用 NotImplemented 而不是 return False | 简单粗暴 return False |
......@@ -3210,7 +3171,7 @@ Vector(4, 6)
---
## 实战代码
#### 实战代码
### 完整示例:实现一个类似 list 的容器
......@@ -3259,11 +3220,12 @@ for item in stack: # 迭代
---
## 常见问题
#### 常见问题
**Q:__str__ 和 __repr__ 有什么区别?**
A:
- `__repr__`:给开发者调试用,尽量包含所有信息
- `__str__`:给用户看,可读性好
......@@ -3282,12 +3244,13 @@ class Person:
**Q:NotImplemented 和 NotImplementedError 有什么区别?**
A:
- `NotImplemented`:特殊值,告诉 Python "这个操作不支持此类型,试试其他的"
- `NotImplementedError`:异常,抛出表示"子类必须实现这个方法"
---
## 验收标准
#### 验收标准
```
☐ 能实现 __str__ 和 __repr__ 方法
......@@ -3298,11 +3261,11 @@ A:
☐ 知道 NotImplemented 和 NotImplementedError 的区别
```
## 官方来源
##### 官方来源
- Python 数据模型:[https://docs.python.org/zh-cn/3/reference/datamodel.html](https://docs.python.org/zh-cn/3/reference/datamodel.html)
## 参考文献
##### 参考文献
[1] Doug Hellmann. *Python Magic Methods*. [https://rszalski.github.io/magicmethods/](https://rszalski.github.io/magicmethods/)
......@@ -3314,13 +3277,13 @@ A:
---
## 什么是访问控制?
#### 什么是访问控制?
### 一句话定义
##### 一句话定义
通过命名约定(单下划线、双下划线)控制属性和方法的访问权限。
### 为什么重要
##### 为什么重要
封装(Encapsulation)是 OOP 的三大特性之一,保护数据不被随意修改。
......@@ -3329,16 +3292,16 @@ A:
Python 没有真正的 private,用约定来模拟:
| 前缀 | 含义 | 说明 |
| --- | --- | --- |
| ---------- | ------ | ----------------------------- |
| `name` | 公开 | 随意访问 |
| `_name` | 受保护 | 约定"请勿外部访问" |
| `__name` | 私有 | 名字被 mangling,不易直接访问 |
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
class BankAccount:
......@@ -3376,7 +3339,7 @@ print(account.balance) # 1300
account._BankAccount__balance # 能访问但不推荐
```
### 输出
##### 输出
```
1000
......@@ -3386,20 +3349,20 @@ account._BankAccount__balance # 能访问但不推荐
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| 命名 | 私有用 `__name`,受保护用 `_name` | 全部公开 |
| 访问私有属性 | 通过公开方法(getter/setter)或 property | 直接访问 `__name` |
| property | 用 `@property` 装饰器 | 写 `get_name()` 方法 |
| setter | 用 `@name.setter` | 不提供 setter(单向 property) |
| ------------ | ---------------------------------------- | ------------------------------ |
| 命名 | 私有用`__name`,受保护用 `_name` | 全部公开 |
| 访问私有属性 | 通过公开方法(getter/setter)或 property | 直接访问`__name` |
| property | 用`@property` 装饰器 | 写`get_name()` 方法 |
| setter | 用`@name.setter` | 不提供 setter(单向 property) |
---
## 实战代码
#### 实战代码
### 完整的 property 使用
#### 完整的 property 使用
```python
class User:
......@@ -3438,7 +3401,7 @@ user.age = -1 # ValueError: 年龄不能为负
---
## 常见问题
#### 常见问题
**Q:Python 真的有 private 吗?**
......@@ -3460,7 +3423,7 @@ A:当需要在访问/修改属性时做额外处理(验证、计算等)。
---
## 验收标准
#### 验收标准
```
☐ 能区分 _name(受保护)和 __name(私有)的使用场景
......@@ -3470,11 +3433,11 @@ A:当需要在访问/修改属性时做额外处理(验证、计算等)。
☐ 理解 Python 的封装是约定而非强制
```
## 官方来源
##### 官方来源
- Python 官方文档 - 标识符:[https://docs.python.org/zh-cn/3/reference/lexical_analysis.html#identifiers](https://docs.python.org/zh-cn/3/reference/lexical_analysis.html#identifiers)
## 参考文献
##### 参考文献
[1] Mark Lutz. *Learning Python (5th Edition)*. O'Reilly, 2013. Chapter 27.
......@@ -3486,28 +3449,29 @@ A:当需要在访问/修改属性时做额外处理(验证、计算等)。
---
## 什么是上下文管理器?
#### 什么是上下文管理器?
### 一句话定义
##### 一句话定义
实现 `__enter__` 和 `__exit__` 方法的对象,支持 `with` 语句,自动处理资源清理。
### 为什么重要
##### 为什么重要
确保资源在使用后正确释放,即使发生异常也不会泄露。
### 生活类比
##### 生活类比
餐厅的"代客泊车":
- `__enter__` = 服务员把车开走
- `__exit__` = 用完餐后服务员把车开回来
- `with` = 整个停车过程
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
# 文件操作 - 上下文管理器
......@@ -3530,19 +3494,19 @@ finally:
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| -------- | ---------------------------- | ---------------------- |
| 使用 | `with obj as f:` | 先 open 再手动 close |
| 自定义 | 用 `@contextmanager` 装饰器 | 每次都写完整类 |
| 自定义 | 用`@contextmanager` 装饰器 | 每次都写完整类 |
| 异常处理 | contextmanager 会捕获异常 | 不处理异常导致资源泄露 |
---
## 实战代码
#### 实战代码
### 1. 类实现上下文管理器
###### 1. 类实现上下文管理器
```python
class DatabaseConnection:
......@@ -3569,13 +3533,12 @@ class DatabaseConnection:
with DatabaseConnection("users.db") as db:
result = db.query("SELECT * FROM users")
print(result)
# 输出:
# 连接数据库: users.db
##### 输出:# 连接数据库: users.db
# 执行: SELECT * FROM users
# 关闭数据库: users.db
```
### 2. 装饰器实现(推荐)
###### 2. 装饰器实现(推荐)
```python
from contextlib import contextmanager
......@@ -3598,13 +3561,12 @@ with timer("数据处理"):
time.sleep(1)
print("处理中...")
# 输出:
# [数据处理] 开始
##### 输出:# [数据处理] 开始
# 处理中...
# [数据处理] 结束,耗时 1.00s
```
### 3. 嵌套上下文管理器
###### 3. 嵌套上下文管理器
```python
from contextlib import ExitStack
......@@ -3617,7 +3579,7 @@ with ExitStack() as stack:
---
## 常见问题
#### 常见问题
**Q:__exit__ 返回 True 会怎样?**
......@@ -3643,7 +3605,7 @@ def my_context():
---
## 验收标准
#### 验收标准
```
☐ 能使用 with 语句操作文件、数据库等资源
......@@ -3653,11 +3615,11 @@ def my_context():
☐ 知道 ExitStack 的使用场景
```
## 官方来源
##### 官方来源
- contextlib 模块:[https://docs.python.org/zh-cn/3/library/contextlib.html](https://docs.python.org/zh-cn/3/library/contextlib.html)
## 参考文献
##### 参考文献
[1] Python Packaging. *Context Managers and Python's with Statement*. [https://book.pythontips.com/en/latest/context_managers.html](https://book.pythontips.com/en/latest/context_managers.html)
......@@ -3669,32 +3631,32 @@ def my_context():
---
## 什么是迭代器?
#### 什么是迭代器?
### 一句话定义
##### 一句话定义
迭代器是实现 `__iter__` 和 `__next__` 的对象,能逐个返回数据。
### 什么是生成器?
#### 什么是生成器?
### 一句话定义
##### 一句话定义
生成器是使用 `yield` 的特殊函数,按需产生数据,节省内存。
### 为什么重要
##### 为什么重要
处理大数据或无限序列时,生成器只在需要时才计算,内存效率高。
### 生活类比
##### 生活类比
- **列表**:一次打印出所有菜名(占满桌子)
- **生成器**:服务员端一道吃一道(按需上菜)
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
# 列表:一次性生成所有数据
......@@ -3744,19 +3706,19 @@ for num in fibonacci(10):
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| ---------- | ---------------- | ----------------------- |
| 大数据处理 | 用生成器 | 用列表一次性加载 |
| yield 位置 | 在函数中用 yield | 把 yield 和 return 混用 |
| 迭代器复用 | 每次创建新实例 | 一个迭代器用完再遍历 |
---
## 实战代码
#### 实战代码
### 1. MyRange 实现
###### 1. MyRange 实现
```python
def my_range(start: int, stop: int = None, step: int = 1):
......@@ -3775,7 +3737,7 @@ for i in my_range(1, 10, 2):
print(i, end=" ") # 1 3 5 7 9
```
### 2. 读取大文件
###### 2. 读取大文件
```python
def read_large_file(filepath: str, chunk_size: int = 1024):
......@@ -3792,7 +3754,7 @@ for chunk in read_large_file("big_file.txt"):
print(chunk)
```
### 3. 无限序列
###### 3. 无限序列
```python
def infinite_count(start: int = 0):
......@@ -3809,11 +3771,12 @@ for _ in range(10):
---
## 常见问题
#### 常见问题
**Q:迭代器和生成器有什么区别?**
A:
- **迭代器**:实现 `__iter__` 和 `__next__` 的对象
- **生成器**:使用 `yield` 的函数,自动实现迭代器协议
......@@ -3840,7 +3803,7 @@ print(list(gen)) # [] 空了!
---
## 验收标准
#### 验收标准
```
☐ 能理解迭代器的 __iter__ 和 __next__ 协议
......@@ -3851,12 +3814,12 @@ print(list(gen)) # [] 空了!
☐ 理解生成器省内存的场景
```
## 官方来源
##### 官方来源
- Python 官方文档 - 迭代器:[https://docs.python.org/zh-cn/3/library/stdtypes.html#iterator-types](https://docs.python.org/zh-cn/3/library/stdtypes.html#iterator-types)
- Python 官方文档 - 生成器:[https://docs.python.org/zh-cn/3/tutorial/classes.html#generators](https://docs.python.org/zh-cn/3/tutorial/classes.html#generators)
## 参考文献
##### 参考文献
[1] David Beazley & Brian K. Jones. *Python Cookbook (3rd Edition)*. O'Reilly, 2013. Chapter 4.
......@@ -3868,26 +3831,26 @@ print(list(gen)) # [] 空了!
---
## 什么是枚举类?
#### 什么是枚举类?
### 一句话定义
##### 一句话定义
枚举(Enum)是一组命名的常量值,提高代码可读性和类型安全。
### 为什么重要
##### 为什么重要
用 `Status.SUCCESS` 代替 `1`,用 `Color.RED` 代替 `"red"`,避免魔法值。
### 生活类比
##### 生活类比
- 不用枚举:`return 200`(200 是什么鬼?)
- 用枚举:`return HTTPStatus.OK`(一目了然)
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
from enum import Enum
......@@ -3905,7 +3868,7 @@ print(c.value) # 1
print(c == Color.RED) # True
```
### 输出
##### 输出
```
Color.RED
......@@ -3916,19 +3879,19 @@ True
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| ---- | ----------------------- | ------------------------------------- |
| 命名 | `class Status(Enum):` | 用字典或常量 |
| 访问 | `Status.SUCCESS` | `Status["SUCCESS"]`(需要异常处理) |
| 比较 | 用 `==` 或 `is` | 用 `>` `<`(除非继承 IntEnum) |
| 比较 | 用`==` 或 `is` | 用`>` `<`(除非继承 IntEnum) |
---
## 实战代码
#### 实战代码
### 1. 基本枚举
###### 1. 基本枚举
```python
from enum import Enum, auto
......@@ -3953,7 +3916,7 @@ print(Weekday.MONDAY.value) # 1
print(Direction.NORTH.value) # 1
```
### 2. IntEnum(可当整数用)
###### 2. IntEnum(可当整数用)
```python
from enum import IntEnum
......@@ -3968,7 +3931,7 @@ print(HTTPStatus.OK + 1) # 201
print(HTTPStatus.OK == 200) # True
```
### 3. Flag(位枚举)
###### 3. Flag(位枚举)
```python
from enum import Flag, auto
......@@ -3987,7 +3950,7 @@ if Permission.READ in read_write:
print("有读权限")
```
### 4. 枚举遍历和成员检查
###### 4. 枚举遍历和成员检查
```python
class Status(Enum):
......@@ -4016,11 +3979,12 @@ print(Status(2)) # Status.RUNNING
---
## 常见问题
#### 常见问题
**Q:Enum 和 IntEnum 有什么区别?**
A:
- `Enum`:值可以是任意类型,比较用 `==`
- `IntEnum`:值是整数,可以用 `<` `>` 比较
......@@ -4058,7 +4022,7 @@ print(Operation.ADD.apply(2, 3)) # 5
---
## 验收标准
#### 验收标准
```
☐ 能定义 enum.Enum 的枚举类
......@@ -4069,11 +4033,11 @@ print(Operation.ADD.apply(2, 3)) # 5
☐ 能用 Flag 定义位枚举
```
## 官方来源
##### 官方来源
- enum 模块:[https://docs.python.org/zh-cn/3/library/enum.html](https://docs.python.org/zh-cn/3/library/enum.html)
## 参考文献
##### 参考文献
[1] Python Official Documentation. *Enum HOW TO*. [https://docs.python.org/zh-cn/3/howto/enum.html](https://docs.python.org/zh-cn/3/howto/enum.html)
......@@ -4091,27 +4055,28 @@ print(Operation.ADD.apply(2, 3)) # 5
---
## 什么是装饰器?
#### 什么是装饰器?
### 一句话定义
##### 一句话定义
装饰器是一个接收函数作为参数、返回新函数的函数。
### 为什么重要
##### 为什么重要
装饰器实现"横切关注点"(日志、缓存、权限检查),避免代码重复。
### 生活类比
##### 生活类比
手机壳:
- 原函数 = 手机
- 装饰器 = 手机壳(套上去,不改变手机功能,但增加了保护)
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
def timer(func):
......@@ -4135,7 +4100,7 @@ def slow_function():
slow_function()
```
### 输出
##### 输出
```
slow_function 执行耗时: 1.00s
......@@ -4143,19 +4108,19 @@ slow_function 执行耗时: 1.00s
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| -------- | ------------------------------------ | --------------- |
| 语法 | `@decorator_name` | 不加 @ 手动赋值 |
| 包装函数 | `wrapper` 接收 `*args, **kwargs` | 不接受参数 |
| 返回值 | 返回 `result` | 忘记 return |
| 返回值 | 返回`result` | 忘记 return |
---
## 实战代码
#### 实战代码
### 1. 日志装饰器
###### 1. 日志装饰器
```python
import functools
......@@ -4179,7 +4144,7 @@ def divide(a, b):
return a / b
```
### 2. 类型检查装饰器
###### 2. 类型检查装饰器
```python
def type_check(func):
......@@ -4208,7 +4173,7 @@ print(add(1, 2)) # 3
---
## 验收标准
#### 验收标准
```
☐ 能理解装饰器是"接收函数、返回函数"的函数
......@@ -4218,11 +4183,11 @@ print(add(1, 2)) # 3
☐ 理解装饰器不修改原函数,只是包装它
```
## 官方来源
##### 官方来源
- Python 官方文档 - 装饰器:[https://docs.python.org/zh-cn/3/tutorial/controlflow.html#decorators](https://docs.python.org/zh-cn/3/tutorial/controlflow.html#decorators)
## 参考文献
##### 参考文献
[1] Bruce Eckel. *Python 3 Patterns, Recipes and Idioms*. [https://python-3-patterns-idioms-test.readthedocs.io/](https://python-3-patterns-idioms-test.readthedocs.io/)
......@@ -4234,9 +4199,9 @@ print(add(1, 2)) # 3
---
## 什么是带参数的装饰器?
#### 什么是带参数的装饰器?
### 一句话定义
##### 一句话定义
装饰器工厂:外层函数接收参数,返回真正的装饰器。
......@@ -4254,9 +4219,9 @@ def decorator_factory(arg1, arg2): # 接收装饰器参数
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
def repeat(times: int):
......@@ -4279,7 +4244,7 @@ def greet(name: str):
print(greet("World"))
```
### 输出
##### 输出
```
['Hello, World!', 'Hello, World!', 'Hello, World!']
......@@ -4287,16 +4252,16 @@ print(greet("World"))
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| -------- | ----------------------------------------- | ---------------- |
| 结构 | `outer(params) -> decorator -> wrapper` | 直接装饰器带参数 |
| 参数传递 | 每层正确传递 | 参数丢失 |
---
## 实战代码
#### 实战代码
### 带日志级别的装饰器
......@@ -4332,7 +4297,7 @@ def debug_process():
---
## 验收标准
#### 验收标准
```
☐ 能理解装饰器工厂的三层结构
......@@ -4340,7 +4305,7 @@ def debug_process():
☐ 能在装饰器参数中使用闭包变量
```
## 官方来源
##### 官方来源
- Python functools 模块:[https://docs.python.org/zh-cn/3/library/functools.html](https://docs.python.org/zh-cn/3/library/functools.html)
......@@ -4352,21 +4317,21 @@ def debug_process():
---
## 什么是 functools.wraps?
#### 什么是 functools.wraps?
### 一句话定义
##### 一句话定义
`@functools.wraps(func)` 把被装饰函数的 `__name__`、`__doc__` 等元信息复制到 wrapper 函数。
### 为什么重要
##### 为什么重要
没有 @wraps,`func.__name__` 会变成 `wrapper`,文档和类型检查会出错。
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
def my_decorator(func):
......@@ -4405,16 +4370,16 @@ print(hello.__doc__) # "打招呼函数"
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| ---- | -------------------------------------------- | -------- |
| 位置 | `@functools.wraps(func)` 在 wrapper 定义内 | 放在外层 |
| 参数 | `@functools.wraps(func)` 传入被装饰函数 | 忘记传参 |
---
## 实战代码
#### 实战代码
### 需要 @wraps 的场景
......@@ -4447,7 +4412,7 @@ print(inspect.signature(add)) # (a: int, b: int) -> int
---
## 常见问题
#### 常见问题
**Q:不用 @wraps 会怎样?**
......@@ -4460,20 +4425,18 @@ add.__doc__ # None
add.__annotations__ # {}(可能)
# 问题:
# 1. help(add) 显示的是 wrapper 的文档
# 2. 依赖 __name__ 的工具(如 Flask 路由)可能出错
# 3. 类型检查器会困惑
```
###### 1. help(add) 显示的是 wrapper 的文档###### 2. 依赖 __name__ 的工具(如 Flask 路由)可能出错###### 3. 类型检查器会困惑```
---
## 验收标准
#### 验收标准
```
☐ 知道 @functools.wraps 的作用
☐ 能在自定义装饰器中使用 @wraps
☐ 能解释 @wraps 保留哪些元信息
☐ 理解 @wraps 对调试和文档的重要性
```
---
......@@ -4494,10 +4457,8 @@ add.__annotations__ # {}(可能)
---
## 举个例子
### 输入
#### 举个例子
##### 输入
```python
class Circle:
def __init__(self, radius: float):
......@@ -4530,7 +4491,7 @@ print(Circle.pi()) # 3.14(不需要实例)
c2 = Circle.from_diameter(20) # 从直径创建
```
### 输出
##### 输出
```
5
......@@ -4540,17 +4501,17 @@ c2 = Circle.from_diameter(20) # 从直径创建
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| ------------- | ---------------------- | ------------------------ |
| @staticmethod | 不需要访问类或实例属性 | 用 self.xxx |
| @classmethod | 第一个参数是 cls | 第一个参数是 self |
| @property | 定义只读或计算属性 | 在 setter 外修改其他属性 |
---
## 实战代码
#### 实战代码
### @property 实现 getter/setter
......@@ -4585,7 +4546,7 @@ print(t.celsius) # 0.0
---
## 验收标准
#### 验收标准
```
☐ 能区分 @staticmethod、@classmethod、@property 的使用场景
......@@ -4634,9 +4595,9 @@ wrapper_a(wrapper_b(func))
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
import functools
......@@ -4669,7 +4630,7 @@ def hello():
hello()
```
### 输出
##### 输出
```
装饰器 B ← 装饰器从下到上初始化
......@@ -4684,16 +4645,16 @@ A 结束
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| ---- | ------------------------------------------ | -------------- |
| 顺序 | 装饰器初始化:下→上,wrapper 执行:内→外 | 混淆两个方向 |
| 调试 | 给每个 wrapper 打印日志 | 乱写顺序不验证 |
---
## 实战代码
#### 实战代码
### 典型场景:多个装饰器
......@@ -4740,7 +4701,7 @@ fetch_data()
---
## 验收标准
#### 验收标准
```
☐ 能画出多层装饰器的执行顺序图
......@@ -4749,7 +4710,7 @@ fetch_data()
☐ 理解顺序对调试和错误处理的影响
```
## 官方来源
##### 官方来源
- Python 官方文档 - 装饰器定义:[https://docs.python.org/zh-cn/3/reference/compound_stmts.html#function](https://docs.python.org/zh-cn/3/reference/compound_stmts.html#function)
......@@ -4767,28 +4728,29 @@ fetch_data()
---
## 什么是 async/await?
#### 什么是 async/await?
### 一句话定义
##### 一句话定义
- `async def`:定义一个可以"暂停"的函数(协程)
- `await`:暂停当前协程,等待另一个协程完成
### 为什么重要
##### 为什么重要
异步 I/O 比同步 I/O 高效 10-100 倍,尤其适合网络请求、文件操作。
### 生活类比
##### 生活类比
餐厅点菜:
- **同步**:等第一道菜上完才点第二道
- **异步**:把菜单给服务员,去做别的事,等叫号再去取
---
## 举个例子
#### 举个例子
### 输入
##### 输入
```python
import asyncio
......@@ -4811,7 +4773,7 @@ async def main():
asyncio.run(main())
```
### 输出
##### 输出
```
[{'id': 1, 'name': '用户1'}, {'id': 2, 'name': '用户2'}]
......@@ -4820,19 +4782,19 @@ asyncio.run(main())
---
## 正解 vs 错误
#### 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --- | --- | --- |
| -------- | ------------------------------------- | -------------------------- |
| 定义函数 | `async def func():` | `def func():` 然后 await |
| 调用协程 | `await func()` 或 `asyncio.run()` | 直接 `func()` |
| 调用协程 | `await func()` 或 `asyncio.run()` | 直接`func()` |
| 返回值 | 普通 return | 不需要 await return |
---
## 实战代码
#### 实战代码
### 1. 基础语法
###### 1. 基础语法
```python
import asyncio
......@@ -4850,7 +4812,7 @@ asyncio.run(say_hello())
print(say_hello()) # <coroutine object say_hello at 0x...>
```
### 2. await 等待多个任务
###### 2. await 等待多个任务
```python
async def task(id: int):
......@@ -4878,7 +4840,7 @@ asyncio.run(main())
---
## 验收标准
#### 验收标准
```
☐ 能用 async def 定义异步函数
......@@ -4888,11 +4850,11 @@ asyncio.run(main())
☐ 能用 asyncio.gather 并发执行多个任务
```
## 官方来源
##### 官方来源
- asyncio 模块:[https://docs.python.org/zh-cn/3/library/asyncio.html](https://docs.python.org/zh-cn/3/library/asyncio.html)
## 参考文献
##### 参考文献
[1] Yifei Ding. *Python Asyncio Tutorial*. [https://docs.python.org/zh-cn/3/library/asyncioyncio.html](https://docs.python.org/zh-cn/3/library/asyncioyncio.html)
......@@ -4907,7 +4869,7 @@ asyncio.run(main())
## asyncio 核心组件
| 组件 | 作用 |
| --- | --- |
| ------------------------- | -------------------------- |
| `asyncio.run()` | 运行顶层协程,创建事件循环 |
| `asyncio.create_task()` | 创建后台任务 |
| `asyncio.gather()` | 并发执行多个协程 |
......@@ -4916,11 +4878,10 @@ asyncio.run(main())
---
## 实战代码
#### 实战代码
### 1. 完整示例
###### 1. 完整示例```python
```python
import asyncio
import time
......@@ -4946,10 +4907,10 @@ async def main():
print(f"结果: {results}")
asyncio.run(main())
```
### 2. Task 的取消
```
###### 2. Task 的取消
```python
async def long_task():
try:
......@@ -4974,7 +4935,7 @@ async def main():
asyncio.run(main())
```
### 3. 超时控制
###### 3. 超时控制
```python
async def slow_task():
......@@ -4993,7 +4954,7 @@ asyncio.run(main())
---
## 验收标准
#### 验收标准
```
☐ 能用 asyncio.run() 运行协程
......@@ -5076,7 +5037,7 @@ async def main():
---
## 验收标准
#### 验收标准
```
☐ 能识别"忘记 await"导致的协程对象
......@@ -5143,19 +5104,19 @@ async def fetch_all_async(urls: list[str]):
### 性能对比
| 方式 | 10 个 0.5s 请求 | 100 个请求 |
| --- | --- | --- |
| ---- | --------------- | ---------- |
| 同步 | 5 秒 | 50 秒 |
| 异步 | 0.5 秒 | 0.5 秒 |
| 提升 | 10 倍 | 100 倍 |
---
## 实战代码
#### 实战代码
### 选择异步还是同步?
| 场景 | 推荐 |
| --- | --- |
| -------------------------------- | -------------------------------- |
| CPU 密集型(计算、加密) | 同步 + 多进程 |
| I/O 密集型(网络请求、文件读写) | 异步 |
| 简单的单次请求 | 同步(代码简单) |
......@@ -5164,7 +5125,7 @@ async def fetch_all_async(urls: list[str]):
---
## 验收标准
#### 验收标准
```
☐ 能用 time.time() 对比同步和异步的执行时间
......@@ -5173,11 +5134,11 @@ async def fetch_all_async(urls: list[str]):
☐ 能说出异步的主要优势
```
## 官方来源
##### 官方来源
- aiohttp 文档:[https://docs.aiohttp.org/](https://docs.aiohttp.org/)
## 参考文献
##### 参考文献
[1] Yifei Ding. *Speed Up Your Python With Asyncio*. Real Python. [https://realpython.com/async-io-python/](https://realpython.com/async-io-python/)
......@@ -5197,7 +5158,7 @@ async def fetch_all_async(urls: list[str]):
## 核心规则
### 1. 缩进
###### 1. 缩进
```python
# ✅ 正确:4 个空格
......@@ -5209,7 +5170,7 @@ if True:
→ do_something()
```
### 2. 行长度
###### 2. 行长度
```python
# ✅ 每行不超过 79 字符(编辑器推荐 100-120)
......@@ -5225,7 +5186,7 @@ text = (
)
```
### 3. 空行
###### 3. 空行
```python
# 模块顶层函数之间:2 个空行
......@@ -5245,7 +5206,7 @@ class MyClass:
pass
```
### 4. Import
###### 4. Import
```python
# ✅ 标准库 → 第三方库 → 本地库的顺序
......@@ -5260,7 +5221,7 @@ import mymodule
# ✅ 避免 from xxx import *(除非明确知道导出了什么)
```
### 5. 空格
###### 5. 空格
```python
# ✅ 正确
......@@ -5280,7 +5241,7 @@ c = (a+b) * (a-b) # 同上
### 6. 命名
| 类型 | 命名规则 | 示例 |
| --- | --- | --- |
| --------- | ----------------- | -------------------------------- |
| 变量/函数 | 小写下划线 | `my_variable`, `my_function` |
| 类 | 大写开头驼峰 | `MyClass` |
| 常量 | 全大写下划线 | `MAX_SIZE`, `PI` |
......@@ -5316,7 +5277,7 @@ autopep8 --in-place --aggressive myfile.py
---
## 验收标准
#### 验收标准
```
☐ 能说出 PEP8 的核心规则(缩进、空格、命名、空行)
......@@ -5325,7 +5286,7 @@ autopep8 --in-place --aggressive myfile.py
☐ 能区分变量、函数、类、常量的命名规则
```
## 官方来源
##### 官方来源
- PEP 8 官方文档:[https://peps.python.org/pep-0008/](https://peps.python.org/pep-0008/)
- PEP 8 中文翻译:[https://pep8.org/](https://pep8.org/)
......@@ -5365,7 +5326,7 @@ def add(a: int, b: int) -> int:
## 常用类型
| 类型 | 说明 | 示例 |
| --- | --- | --- |
| --------------------------------------- | --------------------- | --------------------------------- |
| `int`, `str`, `bool`, `float` | 基础类型 | `x: int = 1` |
| `list[T]`, `dict[K, V]`, `set[T]` | 泛型容器 | `list[int]`, `dict[str, int]` |
| `tuple[T, ...]` | 元组(固定/可变长度) | `tuple[int, str]` |
......@@ -5376,9 +5337,9 @@ def add(a: int, b: int) -> int:
---
## 实战代码
#### 实战代码
### 1. 基础注解
###### 1. 基础注解
```python
from typing import List, Dict, Optional, Union, Callable
......@@ -5404,7 +5365,7 @@ def process_user(
}
```
### 2. 复杂类型
###### 2. 复杂类型
```python
from typing import TypeVar, Generic, Protocol
......@@ -5434,7 +5395,7 @@ stack.push(2)
print(stack.pop()) # 2
```
### 3. Python 3.10+ 新语法
###### 3. Python 3.10+ 新语法
```python
# 使用 | 代替 Optional 和 Union
......@@ -5453,7 +5414,7 @@ match x:
---
## 常见问题
#### 常见问题
**Q:加了类型注解会影响性能吗?**
......@@ -5470,7 +5431,7 @@ mypy myfile.py
---
## 验收标准
#### 验收标准
```
☐ 能为函数参数和返回值添加类型注解
......@@ -5480,7 +5441,7 @@ mypy myfile.py
☐ 能用 mypy 进行静态类型检查
```
## 官方来源
##### 官方来源
- typing 模块:[https://docs.python.org/zh-cn/3/library/typing.html](https://docs.python.org/zh-cn/3/library/typing.html)
- mypy 文档:[https://mypy.readthedocs.io/](https://mypy.readthedocs.io/)
......@@ -5565,33 +5526,28 @@ conda env create -f environment.yml
### conda vs venv
| 维度 | venv | conda |
| --- | --- | --- |
| -------- | -------------- | -------------------------------- |
| 适用场景 | 纯 Python 项目 | Python + 非 Python 依赖(C/C++) |
| 包管理 | pip | conda + pip |
| 体积 | 轻量 | 较大(含科学计算预装) |
---
## 实战代码
#### 实战代码
### 完整项目初始化流程
```bash
# 1. 创建项目目录
mkdir myproject && cd myproject
###### 1. 创建项目目录mkdir myproject && cd myproject
# 2. 创建虚拟环境
python -m venv .venv
###### 2. 创建虚拟环境python -m venv .venv
# 3. 激活环境
source .venv/bin/activate # Linux/Mac
###### 3. 激活环境source .venv/bin/activate # Linux/Mac
# 或 .venv\Scripts\activate # Windows
# 4. 升级 pip
pip install --upgrade pip
###### 4. 升级 pippip install --upgrade pip
# 5. 安装依赖
pip install flask pytest black mypy
###### 5. 安装依赖pip install flask pytest black mypy
# 6. 生成 requirements.txt
pip freeze > requirements.txt
......@@ -5630,7 +5586,7 @@ htmlcov/
---
## 验收标准
#### 验收标准
```
☐ 能用 python -m venv 创建虚拟环境
......@@ -5641,7 +5597,7 @@ htmlcov/
☐ 能区分 venv 和 conda 的适用场景
```
## 官方来源
##### 官方来源
- venv 模块:[https://docs.python.org/zh-cn/3/library/venv.html](https://docs.python.org/zh-cn/3/library/venv.html)
- conda 文档:[https://docs.conda.io/](https://docs.conda.io/)
......@@ -5721,9 +5677,9 @@ warn_return_any = true
---
## 实战代码
#### 实战代码
### 1. src layout(推荐)
###### 1. src layout(推荐)
```bash
# 创建项目结构
......@@ -5744,7 +5700,7 @@ def test_hello():
assert hello() == "Hello, World!"
```
### 2. 安装为可编辑模式
###### 2. 安装为可编辑模式
```bash
# 安装项目(开发模式)
......@@ -5756,11 +5712,12 @@ python -c "from mypackage import hello; print(hello())"
---
## 常见问题
#### 常见问题
**Q:为什么推荐 src layout?**
A:
1. 避免导入时意外 import 项目的测试文件
2. 模拟真实用户安装后的环境
3. 更容易做可编辑安装(`pip install -e .`)
......@@ -5771,7 +5728,7 @@ A:用 **pyproject.toml**(现代推荐)。setup.py 是旧方式,pyproject
---
## 验收标准
#### 验收标准
```
☐ 能搭建标准的项目结构
......@@ -5782,12 +5739,12 @@ A:用 **pyproject.toml**(现代推荐)。setup.py 是旧方式,pyproject
☐ 能写好 README.md(安装、使用、许可证)
```
## 官方来源
##### 官方来源
- Python 打包指南:[https://packaging.python.org/](https://packaging.python.org/)
- pyproject.toml 规范:[https://packaging.python.org/en/latest/specifications/pyproject-toml/](https://packaging.python.org/en/latest/specifications/pyproject-toml/)
## 参考文献
##### 参考文献
[1] Hynek Schlawack. *Testing & Packaging*. [https://hynek.me/articles/testing-packaging/](https://hynek.me/articles/testing-packaging/)
......
......@@ -898,7 +898,7 @@ vectors = embed_openai(texts)
print(f"维度:{len(vectors[0])}") # 1536
```
#### BGE vs OpenAI 对比
##### BGE vs 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):
@app.route("/items/", methods=["POST"])
@validate_item
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"])
......@@ -839,7 +839,7 @@ session.add_all([s1, s2, c1])
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()
```
......
# 模块三:深度学习基础
> 本模块涵盖深度学习中最重要的基础概念:激活函数、损失函数、优化器,以及神经网络的核心工作机制——前向传播与反向传播。掌握这些内容,是理解一切深度学习模型的根基。
---
## 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 人 到此讨论。请谨慎行事。
请先完成此评论的编辑!
请 注册 或者 后发表评论