附录 C 踩坑与 FAQ

第 2 章可选使用 torchtext 官方 GPT2BPEEncoder，其正则引擎依赖 RE2：

安装失败或平台不提供该包时，改用教程自带的 bpe_tokenizer.h：纯 C++ 实现，无外部依赖，数值与官方一致。全部章节默认使用它。

第 2 章的双实现交叉验证保证了这个替身可用：官方版缺席时，自研版结果可以直接对账。

所有下载脚本统一用 HF_MIRROR 开关选择源：

默认源 hf-mirror.com 国内无代理可达，速度约 10 MB/s；下载失败时自动回退 huggingface.co。GitHub raw 数据（nl2bash 等）国内可直连但较慢，超时再用 ALL_PROXY 指定代理。

程序内 query_ollama 请求 http://localhost:11434/api/chat。Ollama 不可达时，第 7 章会打印跳过提示后继续，不会崩溃。评分是可选环节，跳过不影响其余章节。

medium（355M）全参微调加 AdamW，显存大头是优化器状态。动量与二阶矩约 2×355M×4B ≈ 2.8 GB（账目见第 9 章），此外还有梯度与激活。16 GiB 显卡实测安全配置：

batch 提到 8 及以上会 OOM；small（124M）用 batch=8 没有问题。显存不足时按此顺序缩减：减 batch → 减 max_length → 改用第 9 章的 LoRA（可训练参数降到约 2%）。换更大的卡放在最后。

开跑前先核对下表，预估等待时间：

Ampere 及之后的 GPU 默认用 TF32 做 matmul，速度约快 8 倍，尾数只有 10 位。本项目所有 main.cpp 开头都有关闭代码：

不关闭时，GPU 结果与 CPU 数值会在 1e-2 量级上漂移。要复现书中数值，保持默认（关闭 TF32）；要追求吞吐量，可以打开 TF32 并接受数值偏差。

权重初始化必须先在 CPU 上用 torch::manual_seed(123) 完成，之后再 .to(device)。先迁设备再初始化时，CUDA 的 RNG 序列与 CPU 不同，同样的 seed 会得到不同的初始权重，loss 曲线从第一步就分叉。教程代码的固定写法：

这类问题的症状是：程序正常运行，数值与书对不上。遇到时先检查上面两行的顺序。

C++ 的 std::mt19937 与 Python 的 random 不是同一个 RNG，DataLoader 批次顺序必然不同，loss 曲线细节也就必然不同。这不是 bug，是两套随机数系统的正常差异。

判断复现是否成功，看三点：起点（地板 loss ≈ \(\ln V\)）、终点量级、train/val 分叉形态，而不是逐 step 对齐。逐位对齐只在同一台机器、同一份代码、同一套 RNG 下才成立。

torch::load 载入与 --size 不匹配的权重，会抛形状不匹配异常。这是有意设计：第 5 章 assign 的「失败要响」原则在框架层生效。看到 Shape mismatch 时，先核对 --size 与权重文件的对应关系，不要怀疑实现。

convert_data.py 要求 all.nl 与 all.cm 行数严格对齐，不一致直接报错退出，防止错位训练。手动下载语料后，先统计两个文件的行数：行错开一位，问答对全部错位，训练照常跑完，结果全部无效，且不会报错。