8. 开发者参考：自动化测试与代码地图¶
只做练习、不改代码的读者可以跳过本章。想改数据处理、训练代码或教程本身时，先读这里：本项目用自动化测试把“文档里写的”和“代码实际做的”绑在一起。
8.1 自动化测试¶
修改数据处理或训练代码后，用 CPU 环境运行回归测试。这个环境包含 PyTorch、TRL 和 PEFT，供随机初始化的微型模型验证训练机制；第 2 章的数据练习可以先跳过它。
python3.11 -m venv .venv-cpu
source .venv-cpu/bin/activate
python -m pip install -r requirements-cpu.txt
python -m pytest -q
测试需要包含 tests/ 的完整项目源码；第 3 章的精简 GPU 上传包不包含开发者测试。在完整项目中也可使用 .venv-train 执行测试。微型模型测试无需下载权重。
| 层级 | 测试/命令 | 能证明什么 |
|---|---|---|
| 数据 | test_data.py、test_prepare.py、test_bundle.py、test_notebook.py |
单文件读取、草稿门槛、分组与未来轮次隔离、非空目标、快照兼容 |
| 模板 | test_render.py、lab.audit |
目标范围、Token 边界、EOS、溢出、真实 collator padding |
| 微型训练 | test_training.py、test_notebook.py |
CLI 训练组件和 Notebook 实际代码能更新、保存、重载及合并 LoRA |
| 评估 | test_eval.py |
配对、缺失评分、平局、对话聚类统计 |
| 文档与代码 | test_tutorial.py、test_book.py |
教程命令被实际 CLI 接受；部署示例、附录与源码一致；页面与下载包可用 |
| API 示例 | test_tutorial.py |
直接运行书中调用示例，检查模型名、地址、参数和多轮历史传递 |
| 下载 | test_download.py |
各下载源沿用同一版本、缺失/损坏权重被拒绝 |
| GPU 模型 | 第 4、5 章命令 | 真实 QLoRA 训练/恢复、adapter 与合并输出 |
| vLLM 集成 | /health、/v1/models、第 5 章 Python 示例、vllm bench serve |
真实服务可调用，完成单轮/多轮/流式调用和并发压测 |
API 示例测试使用临时本地 HTTP 服务，不能作为 vLLM 推理证据。GPU 与服务检查在相应环境执行；未执行项在 todo 保持未勾选。
保留以下验收证据：原始/展开数据和审核记录；token 报告与测试输出；模型 SHA、依赖、驱动与训练配置；检查点、adapter 和恢复步数；A/B/C 原始输出与评分；合并清单、推理环境版本、API 响应。
8.2 代码阅读地图与依据¶
主线先阅读 Notebook，辅助模块按职责查阅：
| 教材位置 | 对应代码 | 用途 |
|---|---|---|
| 第 2.8 节、第 3 章 | download.py、download-lock.json | 下载固定版本并检查完整性 |
| 第 2 章 | dataset.json、data.py、prepare.py、common.py | 校验事实与对话、构造提示词、生成分词样本 |
| 第 2、6 章 | audit.py | 核对真实 collator 的监督范围和 padding |
| 第 4 章 | 01_gpu_train.ipynb | 1 Epoch 训练、loss 曲线、产物检查、重载回答与合并 |
| 第 4.6 节、第 6 章、附录 | train.py、training.py | 命令行训练、正式参数对照及断点恢复 |
| 第 6 章 | infer.py、evaluate.py | A/B/C 推理、盲评统计与候选冻结 |
| 第 5 章 | merge.py、Notebook 最后两节 | 独立导出、vLLM 部署与挂载 adapter、API 调用、压测 |
Notebook 展示训练细节；CLI 保留用于重复实验和恢复，两种入口各有对应章节。API 示例直接调用 HTTP 或 OpenAI SDK，压测使用 vLLM 自带的 vllm bench serve，不另外维护客户端。
| 决策 | 理由与依据 |
|---|---|
| 固定文本 4B | 沿用同一基座比较实验；Qwen 模型卡 |
| 显式 completion mask | 监督范围可检查；TRL 0.24 |
| NF4+LoRA | 单卡训练少量参数；PEFT 量化 |
| 独立推理环境 | 避免依赖覆盖；vLLM GPU 安装 |
| 事实与表达训练分开 | 本项目实验设计，收益由对照验证 |
事实卡记录科学资料链接。审核时逐条核对断言、适用条件及比喻边界，尤其注意尚标 pending 的来源；网页可访问不等于支持全部生成对话。