Chapter 11
调试与常见错误
📌 commit af33f76跟 PyTorch 主分支跑的代价
TorchTitan 跟着 PyTorch 主分支走，常碰到 nightly 引入的 regression。本章列高频问题。
11.1启动 / 环境
| 现象 | 处理 |
|---|
| "DTensor not found" | torch < 2.4；升 nightly |
| "AttributeError: no attribute 'pipelining'" | torch 2.5+ 才有 stable PP |
| "context_parallel not found" | torch 2.6+ 才有 CP |
| "torchao import 错" | 装 nightly torchao |
| tokenizer.model 找不到 | 下载 Llama-3 tokenizer 放 ./tokenizer/ |
11.2OOM
| 位置 | 处理 |
|---|
| 第 0 step OOM | 开 ac=full；增 tp_degree；减 seq_len / batch_size |
| 第 N step OOM | 显存碎片化；PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True |
| compile 后 OOM | compile 增加一些 staging tensor；关 compile 验证 |
| float8 OOM | fp8 buffer 有额外开销；改 rowwise（更省） |
11.3NaN / loss spike
| 现象 | 处理 |
|---|
| 0 step NaN | 用 bf16 而非 fp16；init_method_std 默认 0.02 |
| compile 后 NaN | 关 compile 看是否消失；可能 inductor 算子有 bug |
| float8 训练 NaN | rowwise 比 tensorwise 稳；降 lr 0.5× |
| async TP 时 NaN | async TP 通信切块会引入数值差异；关掉验证 |
11.4NCCL / 多机
| 现象 | 处理 |
|---|
| NCCL hang | 查 NCCL_SOCKET_IFNAME；多机要 IB |
| PP send/recv hang | schedule 配错，某个 stage 没正确收发；检查 microbatch 数 |
| NCCL allreduce hang | 不同 rank 走了不同分支（if rank==0 ...） |
| HSDP 不工作 | dp_replicate × dp_shard ≠ dp 总 GPU 数 |
11.5性能
| 现象 | 处理 |
|---|
| MFU 低于 40% | 没开 bf16 / compile / float8；先开这三个 |
| compile 第一步慢 10× | 正常，编译期 |
| seq_len 改了 compile 重新跑 | 关 compile.dynamic_shapes 或固定 seq_len |
| 多机比单机慢得多 | 查 IB；开 HSDP；调小 dp_shard |
11.6compile 兼容性
TorchTitan 是 PyTorch compile 测试场。常见问题：
- 动态 shape 触发重编译 → 用
dynamic=False；
- FSDP2 + compile 兼容（PT 2.4+），FSDP1 不兼容；
- PP + compile 部分兼容（schedule 内部要单独 compile）；
- CP + compile 兼容性新（torch 2.6+）。
11.7调试技巧
# nightly torch 引入 regression 时
pip install --pre torch==2.7.0.devXXXXXXX --index-url ...
# 锁版本验证
# 看 verbose
TORCH_LOGS=+dynamo,recompiles torchrun ... # compile debug
NCCL_DEBUG=INFO
# memory snapshot
[memory_estimation]
enabled = true
disable_fake_mode = true
11.8这章你需要带走的
- TorchTitan 跟 PyTorch nightly 走，遇到 regression 锁版本；
- OOM 优先开 ac=full + 加 TP；
- NaN 优先用 bf16；compile 引入的问题先关 compile 排查；
- compile + FSDP2 / CP 兼容性新，不稳时先关掉。