附录 C 常见报错与排查

报错不可怕，可怕的是不知道为什么。本章把项目可能遇到的报错分类整理。

C.1 安装与环境报错

❌ error: Microsoft Visual C++ 14.0 or greater is required

原因：Windows 上 tiktoken 编译需要 C++ build tools。

解决：

1. 装 [Visual Studio Build Tools](微软 Visual Studio 下载站)，勾选「C++ 桌面开发」。
2. 或用预编译 wheel：pip install tiktoken --prefer-binary。

❌ torch.cuda.is_available() 返回 False（但有 NVIDIA 卡）

原因：pip install torch 默认装 CPU 版。

解决：卸载重装 CUDA 版：

pip uninstall torch
# 去 PyTorch 官网 拿对应命令，例如：
pip install torch --index-url PyTorch 官方 CUDA 轮子仓库（whl/cu121）
​

验证：

import torch
print(torch.cuda.is_available())   # 应该 True
print(torch.cuda.get_device_name(0))
​

❌ ImportError: cannot import name 'GPT2LMHeadModel'

原因：transformers 版本太老。

解决：

pip install --upgrade "transformers>=4.36.0"
​

❌ ModuleNotFoundError: No module named 'tqdm' / gradio / 等

原因：依赖没装全。

解决：

pip install -r requirements.txt
​

C.2 数据加载报错

❌ urllib.error.URLError: <urlopen error ...>

原因：GitHub 在国内访问不稳定，tiny_shakespeare 下载失败。

解决：手动下载并缓存：

1. 浏览器打开：
   karpathy/char-rnn 仓库的 data/tinyshakespeare/input.txt（GitHub raw 文件）
2. 另存为 data/tiny_shakespeare.txt（UTF-8 编码）
3. 再跑 python train.py，会命中本地缓存。

❌ [dataset] HuggingFace 下载失败

原因：tiny_shakespeare 数据集从 HF Hub 下线，或网络问题。

解决：本项目会自动回退到 GitHub 直链下载。如果 GitHub 也失败，见上一条手动方案。

❌ DataLoader 为空 / n_samples = 0

原因：数据集 token 数 < block_size + 1。

解决：

# 减小 block_size
python train.py --block-size 32

# 或检查数据是否下载成功
ls -lh data/tiny_shakespeare.txt   # 应该约 1MB
​

C.3 模型构建报错

❌ n_embd must be divisible by n_head

原因：注意力头维度非整数（如 n_embd=100, n_head=3，100/3 不是整数）。

解决：调整 n_embd 使其能被 n_head 整除：

# 错误
python train.py --n-embd 100 --n-head 3   # 100/3 = 33.33

# 正确
python train.py --n-embd 96 --n-head 3    # 96/3 = 32 ✓
python train.py --n-embd 384 --n-head 6   # 384/6 = 64 ✓（默认）
​

❌ size mismatch for wte.weight

原因：checkpoint 的 vocab_size 与当前配置不一致。

解决：

1. 别动 vocab_size（保持 50257）。
2. 如果是改了 block_size 又用旧 checkpoint 续训：新 checkpoint 的 wpe 尺寸会变，要么重训要么用 strict=False 加载（会丢失位置嵌入）。

❌ RuntimeError: CUDA out of memory

原因：显存不足。

解决：按优先级试：

# 1. 减小 batch_size
python train.py --batch-size 8

# 2. 减小 block_size
python train.py --block-size 64

# 3. 减小模型规模
python train.py --n-layer 4 --n-embd 256

# 4. 终极：CPU 训练（慢但不会 OOM）
python train.py --device cpu
​

C.4 训练报错

❌ Loss 变成 nan

原因：学习率过大、数值溢出、梯度爆炸。

排查顺序：

1. 学习率是否过大？

   # 减小学习率 + 增加预热
   python train.py --learning-rate 1e-4 --warmup-iters 200
   ​

2. 数据是否异常？检查 data/tiny_shakespeare.txt 是否包含奇怪字符。

3. 加异常检测定位：

   torch.autograd.set_detect_anomaly(True)
   # 然后训练，会打印是哪个算子产生 NaN
   ​

4. 检查梯度裁剪是否生效：确认 grad_clip=1.0。

❌ 训练时 Windows 卡死 / 递归启动

原因：num_workers > 0 但训练入口未在 if __name__ == "__main__": 保护下。

解决：

• 本项目已正确处理（train.py 末尾有保护）。

• 如果你自己改了脚本，确保：

  if __name__ == "__main__":
      train()
  ​

• 或保持 --num-workers 0（默认值，安全）。

❌ 训练速度越来越慢

原因：可能是显存碎片化、或某处不小心累积了计算图。

排查：

1. 监控显存：

   nvidia-smi -l 1
   ​

   如果显存持续增长，说明有计算图泄漏。

2. 检查是否漏了 optimizer.zero_grad() 或 @torch.no_grad()（推理时）。

3. 重启训练：用 --resume 续训。

❌ tqdm 进度条不刷新

原因：Windows 终端有时不显示 \r。

解决：

• 用 Windows Terminal（推荐）。
• 或忽略进度条，看每 log_iter 步的 [train] step XXX 日志。

C.5 加载 checkpoint 报错

❌ KeyError: "model_state_dict"

原因：传的 checkpoint 不是本项目格式（可能是 HF 目录或纯 state_dict）。

解决：

• 确认传的是 train.py 产出的 .pt 文件。

• 如果是 HF 目录（含 config.json），直接传目录路径：

  python inference.py --checkpoint path/to/hf_dir
  ​

❌ [model] 加载权重：缺失键 XXX 个，多余键 YYY 个

原因：模型架构与 checkpoint 不匹配（改了 n_layer/n_embd 等）。

判断：

• 缺失=0, 多余=0：完美加载 ✓
• 缺失=几百, 多余=0：模型比 checkpoint 大，部分层是新的（随机初始化）。
• 缺失=几百, 多余=几百：架构完全不匹配，别用了。

解决：

• 续训必须用相同架构：别改 --n-layer 等参数。
• 推理时让 load_for_inference 自动从 checkpoint 读配置（默认行为）。

❌ FileNotFoundError: checkpoints/gpt_final.pt

原因：没训练就推理。

解决：先训练：

python train.py
# 训完后再 inference.py
​

C.6 推理报错

❌ 推理输出每次都不同

原因：采样有随机性（temperature > 0）。

解决：

• 想要确定性，用贪心：

  python inference.py --prompt "..." --temperature 0
  ​

• 或固定随机种子：

  import torch
  torch.manual_seed(42)
  ​

❌ 推理输出乱码 / 不像莎士比亚

原因：训练步数太少。

解决：

• 默认 5000 步。如果还是乱码，加大：

  python train.py --max-iters 20000
  ​

• 25M 模型在 tiny_shakespeare 上的合理 loss 约 1.5-2.0。

❌ 输出全是同一个词重复

原因：贪心解码陷入循环。

解决：

• 提高温度：--temperature 0.8
• 开 Top-K：--top-k 40

❌ 中文 prompt 输出乱码

原因：模型在英文（莎士比亚）上训练，不认识中文。

解决：

• 换中文数据训练。
• 或只给英文 prompt。

C.7 Web UI 报错

❌ [生成失败] ...

原因：app.py 的 predict 函数捕获了异常，错误信息显示在输出框。

常见子类：

• FileNotFoundError → checkpoint 路径不对。
• RuntimeError: CUDA OOM → 显存不足，重启或换 CPU。
• ValueError → 输入异常。

❌ 页面打不开 localhost:7860

排查：

1. 端口被占用？换一个：

   python app.py --port 8080
   ​

2. 防火墙拦截？Windows 关闭防火墙试一下。

3. 进程没起来？看终端有没有 Running on local URL: 本地地址。

❌ --share 公网链接访问不了

原因：Gradio tunnel 服务偶尔抽风，或网络问题。

解决：

• 重启 app.py 重新生成链接。
• 或用内网穿透工具（frp、ngrok）替代。

C.8 性能问题

❌ 训练速度慢（< 5 step/s on GPU）

排查：

1. GPU 利用率低（nvidia-smi 显示 < 50%）？

   • 数据加载是瓶颈。增大 --num-workers（Linux）。
   • 或减小 --log-iter，避免频繁 .item() 同步。

2. block_size 太大？减小试试。

3. CPU 训练？CPU 训 25M 模型本来就很慢，几个小时正常。

❌ 推理速度慢

原因：本项目手写循环没用 KV Cache，每步重算。

解决：

• 用 HF 的 model.generate(use_cache=True)，速度提升 5-10 倍：

  model = ...  # GPT2LMHeadModel
  out = model.generate(
      input_ids=input_ids,
      max_new_tokens=100,
      do_sample=True,
      temperature=0.8,
      top_k=40,
      use_cache=True,
  )
  ​

C.9 报错排查通用流程

报错
  │
  ▼
1. 读完整报错信息（不要只看最后一行）
  │
  ▼
2. 复制报错信息搜索
  │
  ▼
3. 判断报错类型：
   ├─ ImportError → 装包
   ├─ FileNotFoundError → 路径/数据问题
   ├─ RuntimeError → 模型/设备问题
   ├─ CUDA OOM → 减小 batch/模型
   └─ ValueError → 参数不对
  │
  ▼
4. 最小复现：用超小配置试
   python train.py --max-iters 5 --n-layer 2 --n-embd 64 --n-head 2 --block-size 32
  │
  ▼
5. 还不行 → 查 issue 区 / 问 AI
​

C.10 调试技巧

技巧 1：打印 tensor shape

print(x.shape)        # torch.Size([32, 128])
print(x.dtype)        # torch.int64
print(x.device)       # cuda:0
​

很多 bug 是 shape 对不上。

技巧 2：打印 loss 和 lr

print(f"step={step} loss={loss.item():.4f} lr={scheduler.get_last_lr()[0]:.2e}")
​

观察训练是否在正常进行。

技巧 3：小规模复现

# 用玩具配置快速试
python train.py --max-iters 5 --n-layer 2 --n-embd 64 --n-head 2 --block-size 32
​

5 步训练几秒就完，适合验证修改是否有效。

技巧 4：binary search 找 bug

如果某个修改导致崩溃，回退一半，再回退一半，快速定位是哪一行的问题。

技巧 5：用 pdb 调试

# 在代码里加
import pdb; pdb.set_trace()

# 或运行时
python -m pdb train.py
​

常用命令：n（下一步）、s（进入函数）、p var（打印变量）、c（继续）、q（退出）。

C.11 求助前自查清单

求助前确认：

• 报错完整信息复制了（不只是最后一行）？
• 用的 Python / torch / transformers 版本？
• 操作系统（Windows/Linux/macOS）？
• 有没有 GPU？显存多大？
• 跑的什么命令？传了什么参数？
• 用最小配置（--max-iters 5 --n-layer 2 ...）能复现吗？

把这些信息一起贴出来，别人能更快帮你。

C.12 报错对照速查

祝调试顺利！🐛➡️🚀