附录 C 常见报错与排查

文档摘要

附录 C 常见报错与排查报错不可怕，可怕的是不知道为什么。本章把项目可能遇到的报错分类整理。 C.1 安装与环境报错 ❌ 原因：Windows 上 tiktoken 编译需要 C++ build tools。解决：装 Visual Studio Build Tools（去微软 Visual Studio 官方下载站获取），勾选「C++ 桌面开发」。或用预编译 wheel：。 ❌ 返回（但有 NVIDIA 卡）原因：默认装 CPU 版。解决：卸载重装 CUDA 版。去 PyTorch 官网拿对应 CUDA 版本的安装命令（形如），复制执行。验证： ❌ 原因：transformers 版本太老。解决： ❌ / / 等原因：依赖没装全。解决： C.

附录 C 常见报错与排查

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

C.1 安装与环境报错

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

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

解决：

装 Visual Studio Build Tools（去微软 Visual Studio 官方下载站获取），勾选「C++ 桌面开发」。
或用预编译 wheel：pip install tiktoken --prefer-binary。

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

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

解决：卸载重装 CUDA 版。去 PyTorch 官网拿对应 CUDA 版本的安装命令（形如 pip install torch --index-url ...），复制执行。

验证：


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 下载失败。

解决：手动下载并缓存——通过任意可用方式获取原始文本（karpathy/char-rnn 仓库的 data/tinyshakespeare/input.txt），另存为 data/tiny_shakespeare.txt（UTF-8 编码），再跑训练时会命中本地缓存。

❌ `[dataset] 数据集下载失败`

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

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

❌ `DataLoader 为空` / `n_samples = 0`

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

解决：减小 --block-size 32，或检查数据是否下载成功（缓存文件应该约 1MB）。

C.3 模型构建报错

❌ `n_embd must be divisible by n_head`

原因：注意力头维度非整数。

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


# 错误：100/3 = 33.33
python train.py --n-embd 100 --n-head 3
# 正确
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 与当前配置不一致。

解决：

别动 vocab_size（保持 50257）。
如果是改了 block_size 又用旧 checkpoint 续训：位置嵌入尺寸会变，要么重训要么用 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`

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

排查顺序：

学习率是否过大？减小 + 增加预热：python train.py --learning-rate 1e-4 --warmup-iters 200
数据是否异常？检查缓存文本是否包含奇怪字符。
加异常检测定位：torch.autograd.set_detect_anomaly(True)，然后训练会打印是哪个算子产生 NaN。
检查梯度裁剪是否生效：确认 grad_clip=1.0。

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

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

解决：保持 --num-workers 0（默认值，安全）；或确保入口在保护块内。详见《第 1 章环境准备与首次运行》。

❌ 训练速度越来越慢

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

排查：

监控显存：nvidia-smi -l 1，如果显存持续增长说明有计算图泄漏。
检查是否漏了 optimizer.zero_grad() 或推理时漏了 @torch.no_grad()。
重启训练：用 --resume 续训。

C.5 加载 checkpoint 报错

❌ `KeyError: "model_state_dict"`

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

解决：确认传的是训练产出的 .pt 文件。如果是框架目录（含配置文件），直接传目录路径。

❌ `加载权重：缺失键 XXX 个，多余键 YYY 个`

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

判断：缺失=0, 多余=0 完美加载；缺失=几百, 多余=0 部分层是新的；缺失=几百, 多余=几百 架构完全不匹配，别用了。

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

❌ `FileNotFoundError: checkpoints/gpt_final.pt`

原因：没训练就推理。

解决：先 python train.py，训完后再推理。

C.6 推理报错

❌ 推理输出每次都不同

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

解决：想要确定性用贪心 --temperature 0；或固定随机种子 torch.manual_seed(42)。

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

原因：训练步数太少。

解决：默认 5000 步；还是乱码就加大 --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 报错

❌ `[生成失败] ...`

原因：回调函数捕获了异常，错误信息显示在输出框。

常见子类：FileNotFoundError → checkpoint 路径不对；RuntimeError: CUDA OOM → 显存不足；ValueError → 输入异常。

❌ 页面打不开 `localhost:7860`

排查：

端口被占用？换一个：python app.py --port 8080。
防火墙拦截？关闭防火墙试一下。
进程没起来？看终端有没有 Running on local URL 字样。

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

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

解决：重启重新生成链接；或用内网穿透工具（frp、ngrok）替代。

C.8 性能问题

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

排查：GPU 利用率低（< 50%）→ 数据加载是瓶颈，增大 --num-workers（Linux）；或减小 --log-iter 避免频繁 .item() 同步。block_size 太大也试减小。CPU 训练 25M 模型本来就很慢，几小时正常。

❌ 推理速度慢

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

解决：用框架的 model.generate(use_cache=True)，速度提升 5-10 倍。

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 调试技巧

打印 tensor shape：print(x.shape) / x.dtype / x.device，很多 bug 是 shape 对不上。
打印 loss 和 lr：print(f"step={step} loss={loss.item():.4f}")，观察训练是否正常。
小规模复现：--max-iters 5 几秒就完，适合验证修改是否有效。
binary search 找 bug：某个修改导致崩溃就回退一半，再回退一半，快速定位。
用 pdb 调试：代码里加 import pdb; pdb.set_trace()，常用命令 n（下一步）、s（进入函数）、p var（打印）、c（继续）。

C.11 报错对照速查

报错	原因	解决
`CUDA out of memory`	显存不足	减小 batch_size / block_size / n_embd；或 CPU
`n_embd must be divisible by n_head`	注意力头维度非整数	调整 n_embd 整除 n_head
`DataLoader 为空`	数据集 token 数 < block_size+1	减小 block_size；检查数据下载
`KeyError: "model_state_dict"`	checkpoint 格式不对	确认是本项目训练产出
训练时 Windows 卡死	num_workers>0 且入口未保护	用 num_workers=0；或保证 `if __name__`
推理输出每次不同	采样有随机性	用 `--temperature 0` 走贪心
推理输出乱码	训练步数太少	默认 5000 步；加大 max-iters
loss 变 NaN	学习率过大 / 数值溢出	减小 lr；加梯度裁剪；anomaly 检测
`urllib.error.URLError`	GitHub 访问受限	手动下载放到数据缓存目录
Gradio 启动后无法访问	防火墙/端口占用	换 --port；或 --share
输出重复循环	贪心解码陷阱	提高温度，开 top-k
中文输出乱码	英文模型不认识中文	换中文数据训练

祝调试顺利！🐛➡️🚀

附录 C 常见报错与排查

文档摘要