附录 C 常见问题排查
文档摘要
附录 C 常见问题排查 按报错现象分类的排查指南。先定位现象，再看原因与解决方案。 C.1 环境与安装类 C.1.1 原因：tiktoken 未安装。 解决： C.1.2 原因：transformers 未安装或版本过低。 解决： C.1.3 安装 torch 后 返回 False 原因：安装的是 CPU 版 torch，未装 CUDA 版。 解决：到 PyTorch 官网按你的 CUDA 版本获取安装命令，重装。常见如： C.1.4 Windows 下 训练报错或卡住 原因：Windows 多进程要求训练入口在 内，且有时仍不稳定。 解决：加 强制单进程加载。 C.2 教师模型下载类 C.2.1 （下载教师时） 原因：磁盘空间不足。
附录 C 常见问题排查
按报错现象分类的排查指南。先定位现象，再看原因与解决方案。
C.1 环境与安装类
C.1.1 ModuleNotFoundError: No module named 'tiktoken'
原因：tiktoken 未安装。
解决：
pip install tiktoken
C.1.2 ModuleNotFoundError: No module named 'transformers'
原因：transformers 未安装或版本过低。
解决：
pip install "transformers>=4.36.0"
C.1.3 安装 torch 后 torch.cuda.is_available() 返回 False
原因：安装的是 CPU 版 torch，未装 CUDA 版。
解决：到 PyTorch 官网按你的 CUDA 版本获取安装命令，重装。常见如：
pip install torch --index-url https://download.pytorch.org/whl/cu121
C.1.4 Windows 下 num_workers > 0 训练报错或卡住
原因：Windows 多进程要求训练入口在 if __name__ == "__main__": 内，且有时仍不稳定。
解决：加 --num-workers 0 强制单进程加载。
C.2 教师模型下载类
C.2.1 OSError: No space left on device（下载教师时）
原因：磁盘空间不足。教师 GPT2 权重约 548MB，加上缓存目录冗余需预留约 1GB。
解决：
- 清理磁盘空间，至少预留 1GB。
- 或把 HuggingFace 缓存目录指向其他盘：设置环境变量
HF_HOME到空间充足的盘。
C.2.2 教师下载超时或连接失败
原因：网络访问 HuggingFace Hub 不畅。
解决：
- 设置镜像端点环境变量后再重试：
# 设置镜像（示例，按可用镜像调整） set HF_ENDPOINT=https://hf-mirror.com
- 或在能联网的机器上预下载，再把
~/.cache/huggingface/整个目录拷贝到目标机器。
C.2.3 ConnectionError / ProxyError 下载失败
原因：代理配置问题。
解决：检查代理环境变量 HTTP_PROXY / HTTPS_PROXY 是否正确设置，或临时关闭代理重试。
C.3 训练类
C.3.1 训练 loss 不下降
可能原因与排查：
| 排查点 | 检查方法 |
|---|---|
| 学习率太小 | 看 lr 是否接近 0，尝试调大 --learning-rate |
| 学习率太大（震荡） | 看 loss 是否剧烈跳动，尝试调小 |
| 数据问题 | 打印一个 batch 的 x、y，确认 y 是 x 左移一位 |
| 损失实现 bug | 用随机数据跑第 6 章的健康性检查 |
| 教师未正确加载 | 确认日志打印了「教师参数量 124M」 |
C.3.2 训练 loss 下降但效果差（学生 PPL 远高于教师）
可能原因：
- 学生太小：增大
--student-n-embd和--student-n-layer。 - 训练步数不足：增加
--max-iters。 - 蒸馏参数不佳：参考第 10 章，尝试不同 T 和 α 组合。
- 数据太少：tiny_shakespeare 只有 1MB，可换更大语料。
C.3.3 kd 损失为 0 或不下降
可能原因：
- α=1：此时软标签项被完全忽略，kd 不参与优化，这是预期行为（不是 bug）。改为
--alpha 0.5即可。 - 温度过高：T 极大时分布接近均匀，KL 信号弱。降低
--temperature。 - 学生已完全学会教师：极少见，此时 kd 趋近 0 是好事。
C.3.4 RuntimeError: CUDA out of memory
原因：显存不足。
解决（按优先级）：
- 减小
--batch-size（如 32 → 8）。 - 减小
--block-size（如 128 → 64）。 - 减小学生规模
--student-n-embd。 - 换更大显存的 GPU。
C.3.5 训练速度很慢
排查：
| 现象 | 可能原因 | 解决 |
|---|---|---|
| 用 CPU 训练 | 未用 GPU | 确认 CUDA 可用，用 --device cuda |
| 教师反复前向慢 | 未开缓存 | 加 --cache-teacher |
| 数据加载慢 | num_workers=0 | 适当增大（Windows 谨慎） |
C.3.6 NaN loss（损失变成 NaN）
可能原因：学习率过大导致数值爆炸。
解决：
- 降低
--learning-rate。 - 确认
--grad-clip生效（默认 1.0）。 - 检查温度是否过小（如 T=0.01 会导致 softmax 数值问题），T 至少保持 ≥ 1。
C.4 评估类
C.4.1 加载学生时 size mismatch 报错
原因：checkpoint 内的学生架构与当前配置不一致。
解决：本项目会自动从 checkpoint 恢复学生架构配置。若仍报错，手动确认训练时和评估时的 --student-n-layer/n-head/n-embd 一致。
C.4.2 学生 PPL 高得离谱（如 > 1000）
可能原因：
- 训练步数太少，学生还没学到东西。
- 加载了错误的 checkpoint（如 step 很早的那个）。
- 评估时 block_size 与训练时不一致。
解决：用最终 checkpoint student_final.pt 评估，确认 block_size 一致。
C.4.3 评估时 alignment_kl 很大
含义：学生分布偏离教师很多，蒸馏对齐不好。
解决：
- 延长训练。
- 调整温度（通常 T=2~4 对齐效果较好）。
- 检查是否 α 过高（如 α=0.9）导致软标签被忽视。
C.5 推理类
C.5.1 生成文本重复或卡循环
原因：采样温度过低，退化为贪心。
解决：
- 提高
--temperature（如 0.8）。 - 或调整
--top-k（如 40）增加多样性。
C.5.2 生成文本不连贯
原因：温度过高或学生训练不足。
解决：
- 降低
--temperature（如 0.7）。 - 减小
--top-k（如 20）。 - 确认学生训练充分（PPL 不太高）。
C.5.3 中文提示生成乱码
原因：本项目主要在英文莎士比亚语料上蒸馏，且 GPT-2 分词器对中文支持有限。
解决：本项目定位为英文模型，建议用英文提示。若需中文能力，需换中文语料与支持中文的分词器重新蒸馏。
C.5.4 交互模式输入后无响应
原因：生成中（模型逐 token 生成，可能较慢）。
解决：等待，或减小 --max-new-tokens。CPU 推理较慢，建议用 GPU。
C.6 缓存类
C.6.1 --cache-teacher 后磁盘暴涨
原因：教师缓存占用空间大（每样本约 block_size × vocab × 4 字节）。
解决：
- 评估是否真需要缓存（短训练不必）。
- 用完后手动删除缓存目录释放空间。
- 减小 block_size 降低单样本占用。
C.6.2 缓存构建中途失败
原因：通常是内存不足或磁盘满。
解决：
- 减小
teacher_cache_shard（在配置中），让分片更小、更早落盘。 - 确认磁盘空间充足。
- 构建失败后删除不完整的缓存目录，重新构建。
C.7 通用排查思路
遇到未知问题时，按这个顺序排查：
排查清单
遇到问题时，依次确认：
- 依赖是否都装好（
import测试） - GPU 是否可用（
torch.cuda.is_available()） - 教师是否成功加载（日志有「教师参数量」）
- 数据形状是否正确（打印一个 batch）
- 损失函数是否健康（第 6 章健康性检查）
- 配置是否一致（训练/评估的 block_size、学生规模）
- 磁盘/显存是否充足
若本附录未覆盖你的问题，建议带上完整的报错信息与复现命令寻求帮助。排查时务必提供：① 完整报错栈，② 你执行的命令，③ 相关的环境信息（OS、GPU、依赖版本）。