---
tags: [nanochat, repro, troubleshooting]
阶段: 10-复现与实验
难度: ★★★
created: 2026-10-22
related: "[[本地环境搭建]], [[跑通speedrun脚本]], [[用--depth调参]], [[检查点与恢复]]"
---

# 常见问题踩坑

## 定义

**故障树**（fault tree）是按症状组织的排查结构：顶层是可直接观察到的现象（报错文本、日志缺失、指标异常），中间层是可能的原因，底层是能区分这些原因的最小验证命令与对应修复。

本篇使用的术语：

| 术语 | 含义 |
|---|---|
| 症状（symptom） | 用户能直接观察到的现象，如一行报错或一个异常指标 |
| 根因（root cause） | 导致症状的最小机制，通常对应一处代码或一个环境变量 |
| 验证命令 | 能区分两个候选根因的单条命令，输出应当二值化 |
| 修复 | 改变配置或代码使症状消失的最小动作 |
| 静默回退（silent fallback） | 代码检测到能力缺失后改用较慢路径，只打印警告不中断 |
| 词表错配 | 分词器与检查点的 `vocab_size` 不一致，或数值相同而内容不同 |
| 显存碎片 | 分配器保留的空闲块尺寸不匹配请求，导致总量足够但无法分配 |
| rendezvous | `torchrun` 各进程互相发现并建立进程组的阶段 |

**分诊**（triage）指在动手修之前先用少量命令把症状收敛到一条分支的过程；本篇的每一条都给出「现象、原因、验证、修复」四段，其中验证段是可复制执行的命令。

## 为什么重要

nanochat 的多数故障不报错。FA3 不可用时只打印四行警告后回退 SDPA，训练继续但慢一倍；数据未下齐时 dataloader 在已有分片上循环，损失曲线正常但能力偏低；fp16 下 FA3 关闭且没有 GradScaler 的路径会静默产生 NaN。这些都属于静默失败，唯一可靠的发现方式是按症状逐项验证。

故障的代价与阶段相关。同一处显存问题，在启动时表现为立即 OOM，在训练两小时后表现为中断并浪费一次 8 卡运行；同一处词表问题，在加载时表现为断言失败，在训练后表现为 CORE 异常低而找不到原因。把故障拦在更早的阶段，等价于节省整段算力。

它是「懂工程」这条主线的主要载体。懂原理能解释为什么会有这个约束，能复现能跑通一次，只有懂工程能在报错信息不充分时定位到具体代码位置。本篇的 11 条症状覆盖了 05 阶段的训练、06 阶段的 SFT、08 阶段的评测与 09 阶段的推理中出现的绝大多数失败。

在全书中的位置：前置为 [[本地环境搭建]]（环境类故障）、[[跑通speedrun脚本]]（产物与命令）、[[用--depth调参]]（显存与批大小）；后续为 [[实验日志]]（把每次故障记成可复用条目）。相关机制在 [[检查点与恢复]]、[[FlashAttention与高效注意力]]、[[FP8混合精度训练]] 中展开。

## 原理与推导

### 0 故障树总览

下表把 11 条症状与最可能根因、一条验证命令对应起来。先用它收敛分支，再进入对应小节。

| # | 症状 | 最可能根因 | 一条验证命令 |
|---|---|---|---|
| 1 | 启动即 OOM，或显存有余量却 OOM | 单卡批过大或分配器碎片 | 降低 `--device-batch-size` 重试 |
| 2 | 训练中后期 OOM | 评测与采样阶段的峰值 | `nvidia-smi` 对比 `Peak memory usage` |
| 3 | 吞吐只有一半 | FA3 回退 SDPA | 打印 `HAS_FA3` 与 `USE_FA3` |
| 4 | 出现 DATASET UPGRADE 警告 | 数据未下载或旧目录 | 数 `base_data_climbmix` 的分片 |
| 5 | 加载时词表断言失败 | 分词器与检查点不匹配 | 比较两处 `vocab_size` |
| 6 | 恢复后损失跳变 | 优化器状态与当前配置不一致 | 打印参数组的 `initial_lr` |
| 7 | 损失 NaN 或 inf | fp16 未配 GradScaler | 检查 `COMPUTE_DTYPE` 与 scaler 日志 |
| 8 | CPU 上每秒几 token | 无 GPU 且未降级配置 | 打印设备类型与精度 |
| 9 | encode/decode 不往返 | 特殊 token 走错 API | 往返测试 |
| 10 | 找不到检查点 | 基准目录或 tag 不一致 | 列 `base_checkpoints/*/model_*.pt` |
| 11 | torchrun 启动失败 | 端口冲突或环境变量残留 | `env` 过滤 `RANK` |

### 症状 1 启动即 OOM 或碎片导致的 OOM

**现象**：进程启动数秒内抛出 `torch.OutOfMemoryError`，栈顶通常在第一次前向或反向后；或者 `nvidia-smi` 显示还有数 GB 空闲却仍然 OOM，且 `reserved` 远大于 `allocated`。

**原因**：两类。第一类是容量不足：单卡批过大，d24 在 $B_{\text{dev}}=16$ 时估计峰值约 42 GB，$B_{\text{dev}}=32$ 时约 76 GB，后者在 80 GB 卡上也会失败；峰值的主要项是激活与 logits，都与 $B_{\text{dev}}$ 成正比。第二类是碎片：缓存分配器按块管理显存，反复申请不同尺寸的临时张量会留下无法复用的小块，评测与采样改变输入形状时尤其明显。

**验证**：

```bash
# 1) 卡的总显存与当前占用
nvidia-smi --query-gpu=name,memory.total,memory.used --format=csv
# 2) 只跑一步，把单卡批降到 1，确认是容量问题而不是代码问题
python -m scripts.base_train -- --depth=24 --device-batch-size=1 \
    --num-iterations=1 --eval-every=-1 --core-metric-every=-1 --sample-every=-1
# 3) 区分碎片：allocated 远小于 reserved 即指向碎片
python -c "import torch; print(torch.cuda.memory_allocated() / 2**30, torch.cuda.memory_reserved() / 2**30)"
```

第二条命令若能跑完一步，就说明是容量问题；若仍 OOM，问题在别处（残留进程占卡、`CUDA_VISIBLE_DEVICES` 指向错误设备）。

**修复**：按 `--device-batch-size` 16 → 8 → 4 → 2 → 1 逐级下降，梯度累积步数会自动增大以保持总批不变。碎片侧确保 `expandable_segments:True` 生效（`PYTORCH_ALLOC_CONF` 与旧名 `PYTORCH_CUDA_ALLOC_CONF` 都试），并在阶段切换时调用 `torch.cuda.empty_cache()`。仍不够时开 `--fp8`（需要 sm89 以上），或把 `--max-seq-len` 从 2048 降到 1024（改变上下文设定，需在记录中标注）。

### 症状 2 训练中后期 OOM

**现象**：训练数百到数千步后 OOM，或只在评测、采样、保存检查点时 OOM。

**原因**：两类。第一类是显存碎片：长跑过程中不同尺寸的临时块被反复申请与释放，缓存分配器保留的空闲块尺寸不匹配新请求。第二类是阶段峰值：`base_eval` 的 CORE 评测会加载 `eval_bundle` 与逐任务数据，`chat_eval` 的生成式评测会为每个样本分配 KV 缓存，这些峰值可能高于训练稳态。

**验证**：

```bash
# 训练脚本在结束时打印分配器峰值；与 nvidia-smi 的总占用对比
grep "Peak memory usage" runs/*/train.log
# 打开分配器统计，看 reserved 与 allocated 的差距
python -c "
import torch
print(torch.cuda.memory_allocated() / 2**30, torch.cuda.memory_reserved() / 2**30)
"
```

`reserved` 显著大于 `allocated` 且 OOM 发生在总量仍有余量时，指向碎片。

**修复**：`base_train.py` 与 `chat_sft.py` 在文件顶部设置 `os.environ["PYTORCH_ALLOC_CONF"] = "expandable_segments:True"`。若运行的 PyTorch 版本只识别旧变量名，在启动前额外导出 `PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True`。评测阶段单独降 `--device-batch-size`，例如 `base_eval --device-batch-size=8`。

### 症状 3 FA3 不可用或静默回退

**现象**：日志中出现 80 个感叹号包围的 `WARNING: Flash Attention 3 not available, using PyTorch SDPA fallback`，随后可能出现 `WARNING: SDPA has no support for sliding window attention`。吞吐明显低于预期，MFU 偏低。

**原因**：`nanochat/flash_attention.py` 的 `_load_flash_attention_3()` 返回 `None`。触发条件有五种：非 CUDA 设备；`kernels` 包无法从 Hugging Face Hub 取到内核（离线或网络受限）；计算能力为 10.0 的 Blackwell（注释说明需要等 FA3 重新编译）；`COMPUTE_DTYPE` 不是 bf16（FA3 的 Hopper 内核只支持 bf16 与 fp8）；内核与当前 torch 版本不兼容。

**验证**：

```bash
python -c "
from nanochat.flash_attention import HAS_FA3, USE_FA3
from nanochat.common import COMPUTE_DTYPE
print('HAS_FA3:', HAS_FA3, '| USE_FA3:', USE_FA3, '| dtype:', COMPUTE_DTYPE)
"
```

`HAS_FA3=False` 说明内核未加载；`HAS_FA3=True` 而 `USE_FA3=False` 说明是精度不匹配。

**修复**：确保联网并允许访问 Hugging Face Hub；用 `NANOCHAT_DTYPE=bfloat16` 或默认的 bf16；Blackwell 上只能接受 SDPA。回退后应把 `--window-pattern` 改为 `L`，因为 SDPA 的滑动窗口需要显式掩码，窗口模式在回退路径上反而更慢。吞吐损失是真实的：FA3 在 batch 32、seq 2048 下约为 FA2 的两倍，回退后整个训练的墙钟时间显著上升。

### 症状 4 数据未下载或回退到 legacy 目录

**现象**：日志打印 `WARNING: DATASET UPGRADE REQUIRED` 与 `Could not find: .../base_data_climbmix`，随后回退到 `base_data`；若两个目录都不存在，则 `os.listdir` 抛 `FileNotFoundError`。

**原因**：`list_parquet_files` 在 `base_data_climbmix` 不存在时尝试旧目录 `base_data`。这个回退是为从 FineWeb-EDU 升级的用户准备的，若从未下载过数据，两个目录都不存在。

**验证**：

```bash
ls "$NANOCHAT_BASE_DIR/base_data_climbmix"/*.parquet 2>/dev/null | wc -l
python -c "
from nanochat.dataset import list_parquet_files
files = list_parquet_files()
print('files:', len(files))
print('val shard:', files[-1])
"
```

分片数应为训练分片数加 1，且最后一个必须是 `shard_06542.parquet`。

**修复**：`python -m nanochat.dataset -n 170` 补齐训练分片（验证分片总是自动下载）；换数据集后必须重训分词器，因为词表的内容依赖训练语料；确认 `NANOCHAT_BASE_DIR` 与训练时一致。

### 症状 5 词表与模型不匹配

**现象**：加载检查点时报 `AssertionError: Tokenizer vocab size 32768 does not match model config vocab size ...`；或者断言通过但模型输出乱码、bpb 异常高。

**原因**：`checkpoint_manager.build_model` 只比较 `vocab_size` 数值，不比较词表内容。因此「用 32768 的词表 A 训练，再用 32768 的词表 B 加载」不会触发断言，但 token id 到字节的映射已经改变，模型的输入语义整体错位。

**验证**：

```bash
python -c "
import json, os
from nanochat.common import get_base_dir
from nanochat.tokenizer import get_tokenizer
base = get_base_dir()
tok = get_tokenizer()
print('tokenizer vocab:', tok.get_vocab_size())
meta_path = os.path.join(base, 'base_checkpoints', 'd24', 'meta_005568.json')
meta = json.load(open(meta_path, encoding='utf-8'))
print('model vocab:', meta['model_config']['vocab_size'])
print('tokenizer mtime:', os.path.getmtime(os.path.join(base, 'tokenizer', 'tokenizer.pkl')))
print('checkpoint mtime:', os.path.getmtime(meta_path))
"
```

最后一对时间戳若显示分词器比检查点新，基本可以确定词表被替换过。

**修复**：训练与推理必须使用同一份 `tokenizer.pkl` 与 `token_bytes.pt`，建议在训练完成后随检查点一起备份。改变 `--vocab-size` 后必须从头训练，因为 `wte`、`lm_head`、value embeddings 的形状都依赖词表大小。

### 症状 6 resume 后学习率或优化器异常

**现象**：从 `--resume-from-step` 恢复后损失出现跳变、学习率曲线与预期不符，或直接报优化器状态形状不匹配。

**原因**：`torch.optim.Optimizer.load_state_dict` 会恢复参数组的全部超参数键（含 `initial_lr`、`lr`、`betas`、`weight_decay`）。`base_train.py` 在恢复后执行 `group["lr"] = group["initial_lr"] * lrm`，因此 `initial_lr` 取自检查点而不是当前命令行的推导结果。三个具体后果：用不同的 `--target-param-data-ratio` 或 `--total-batch-size` 恢复时，学习率仍按旧配置；改变 `--nproc_per_node` 时，优化器状态的分片形状与新 world size 不匹配；改变 `num_iterations` 时，warmdown 的起点与 `lrm` 曲线整体偏移。

**验证**：

```bash
# 恢复日志中应出现这一行，step 与 meta 一致
grep -E "Resuming optimization|Inherited|Scaling LRs" runs/*/train.log
python -c "
import json, os
from nanochat.common import get_base_dir
meta = json.load(open(os.path.join(get_base_dir(), 'base_checkpoints', 'd24', 'meta_005568.json'), encoding='utf-8'))
print('user_config:', {k: meta['user_config'][k] for k in ('depth','target_param_data_ratio','device_batch_size','total_batch_size')})
"
```

**修复**：恢复时保持 `--nproc_per_node`、`--total-batch-size`、`--target-param-data-ratio` 与原始运行一致；只改评测频率与保存频率是安全的。若确实需要换配置，当前脚本没有「只加载权重」的入口（`load_optimizer=True` 写死在恢复分支），需要改代码把该参数改为 `False`，代价是动量与二阶矩从零重建，前若干步会有损失尖峰。

### 症状 7 bf16 与 fp16 精度问题

**现象**：损失变成 `NaN` 或 `inf`；fp16 训练时梯度下溢；日志显示 `WARNING: Flash Attention 3 only supports bf16, but COMPUTE_DTYPE=torch.float16`。

**原因**：三种精度路径的行为不同。bf16 的指数范围与 fp32 相同，不需要梯度缩放；fp16 的指数范围小，需要 `GradScaler`，而 `base_train.py` 与 `chat_sft.py` 实现了它、`chat_rl.py` 没有；fp32 在 Ampere 上通过 `torch.set_float32_matmul_precision("high")` 使用 tf32。若在 RL 阶段强制 `NANOCHAT_DTYPE=float16`，会得到无缩放的反向传播。

**验证**：

```bash
# 日志开头的两行足以定位
grep -E "COMPUTE_DTYPE|GradScaler" runs/*/train.log
python -c "import torch; print(torch.cuda.get_device_capability())"
```

计算能力低于 8.0 时 bf16 不被支持，代码会自动退回 fp32。

**修复**：SM80 以上一律用 bf16；需要 fp16 时只在 base 与 SFT 阶段使用，并确认日志出现 `GradScaler enabled for fp16 training`；出现 NaN 时先降学习率或检查数据（空文档、异常长的行），不要先怀疑精度。

### 症状 8 CPU 或 MPS 上太慢

**现象**：`tok/sec` 只有几十到几百，`bf16_mfu: 0.00`，训练一步需要数秒。

**原因**：三处叠加。第一，`base_train.py` 在非 CUDA 设备上把 `gpu_peak_flops` 设为 `inf`，因此 MFU 恒为 0，这是指标问题不是性能问题；第二，没有 FA3，注意力走 SDPA；第三，CPU 与 MPS 的默认精度是 fp32，矩阵乘吞吐比 bf16 低。若再沿用 d12 以上的深度，单步时间会达到分钟量级。

**验证**：

```bash
python -c "
from nanochat.common import autodetect_device_type, COMPUTE_DTYPE, COMPUTE_DTYPE_REASON
print('device:', autodetect_device_type())
print('dtype:', COMPUTE_DTYPE, COMPUTE_DTYPE_REASON)
"
```

**修复**：使用 `runs/runcpu.sh` 的配置：深度 6、`--head-dim=64`、`--max-seq-len=512`、`--window-pattern=L`、`--total-batch-size=16384`、`--num-iterations=5000`。Apple Silicon 可加 `NANOCHAT_DTYPE=bfloat16` 换取约四分之一的显存下降。CPU 只用于验证代码路径，不用于产生能力指标。

### 症状 9 tokenizer 编码异常

**现象**：`tok_eval` 的往返断言失败；`token_bytes` 的和异常；bpb 异常低或异常高；特殊 token 出现在普通编码结果中。

**原因**：编码 API 的分工。`encode` 使用 `encode_ordinary`，它不会识别特殊 token；特殊 token 必须通过 `encode_special` 或 `prepend`/`append` 参数传入。`decode` 对非 UTF-8 字节的 token 会产生替换字符，因此计算字节数必须用 `decode_single_token_bytes`。此外，`token_bytes` 把特殊 token 记为 0，若把它改成实际字节长度，bpb 会被系统性低估。

**验证**：

```bash
python -c "
from nanochat.tokenizer import get_tokenizer, get_token_bytes
tok = get_tokenizer()
text = 'Hello 世界 123\n<|bos|> 不是特殊 token 的字面量'
ids = tok.encode(text)
print('round-trip:', tok.decode(ids) == text)
print('special id:', tok.encode_special('<|bos|>'))
print('token_bytes sum:', int(get_token_bytes().sum()))
"
```

第一项应为 `True`；文本中的 `<|bos|>` 是普通字符序列，只在作为 `prepend` 参数时才会被当作特殊 token。

**修复**：使用 `RustBPETokenizer` 的封装方法而不是直接调用 tiktoken；需要插入特殊 token 时用 `prepend`/`append`；重训分词器后重建 `token_bytes.pt`，二者必须同批生成。

### 症状 10 找不到检查点

**现象**：`FileNotFoundError: No checkpoints found in ...`、`No checkpoints found in <dir>`，或加载到了非预期的模型。

**原因**：四类。`NANOCHAT_BASE_DIR` 与训练时不同；`--model-tag` 与目录名不一致（训练时用了 `d24`，评测时用了实验名）；`--step` 指向不存在的文件；未给 `--model-tag` 时 `find_largest_model` 按目录名中的 `d<数字>` 取最大，目录里同时有 d12 与 d24 时选 d24。

**验证**：

```bash
ls -d "$NANOCHAT_BASE_DIR"/base_checkpoints/*/
ls "$NANOCHAT_BASE_DIR"/base_checkpoints/*/model_*.pt | tail -3
python -c "
from nanochat.checkpoint_manager import find_largest_model, find_last_step
import os
from nanochat.common import get_base_dir
d = os.path.join(get_base_dir(), 'base_checkpoints')
tag = find_largest_model(d)
print('guessed tag:', tag, '| last step:', find_last_step(os.path.join(d, tag)))
"
```

**修复**：评测与 SFT 时显式传 `--model-tag` 与 `--step`，不依赖猜测。文件名中的六位数字是 `find_last_step` 的解析依据，不要手工重命名。

### 症状 11 torchrun 启动失败或环境变量异常

**现象**：单进程 `python -m scripts.base_train` 正常，`torchrun` 启动即失败；报 `Address already in use`；或日志显示 `Distributed world size: 1` 但预期是 8。

**原因**：`is_ddp_requested()` 只检查 `RANK`、`LOCAL_RANK`、`WORLD_SIZE` 三个环境变量是否同时存在。直接在 shell 里 `export RANK=0` 而缺少另两个，会得到半初始化状态；反之，残留的 `WORLD_SIZE` 会让单进程运行误以为需要初始化进程组。`--standalone` 会在本机随机端口建立 rendezvous，同机多个未清理的进程会冲突。

**验证**：

```bash
env | grep -E "^(RANK|LOCAL_RANK|WORLD_SIZE|MASTER_ADDR|MASTER_PORT)=" || echo "no ddp env"
nvidia-smi --query-compute-apps=pid,used_memory --format=csv
ps aux | grep -c "[t]orchrun"
```

**修复**：统一用 `torchrun --standalone --nproc_per_node=8` 启动；手工测试单进程前先清除 DDP 环境变量；端口冲突时用 `--rdzv-endpoint=localhost:29501` 指定端口；`--nproc_per_node` 不得超过可见 GPU 数。

### 在 nanochat 中的落地

| 位置 | 与故障的关系 |
|---|---|
| `base_train.py` 顶部的 `PYTORCH_ALLOC_CONF` | 缓解症状 1 的碎片 |
| `base_train.py` 的 FA3 状态打印 | 症状 3 的第一现场，四行警告由这里产生 |
| `nanochat/flash_attention.py:_load_flash_attention_3` | 症状 3 的根因，五种失败条件都收敛到返回 `None` |
| `nanochat/dataset.py:list_parquet_files` | 症状 4 的 legacy 回退与提示文本 |
| `checkpoint_manager.build_model` 的词表断言 | 症状 5 的拦截点，只比较数值不比较内容 |
| `base_train.py` 的 `initial_lr` 使用 | 症状 6 的根因，恢复后仍按检查点的初始学习率 |
| `common.py:_detect_compute_dtype` | 症状 7 与 8 的分支来源 |
| `tokenizer.py` 的 `encode`、`encode_special`、`decode_single_token_bytes` | 症状 9 的 API 分工 |
| `checkpoint_manager.find_largest_model` 与 `find_last_step` | 症状 10 的目录猜测逻辑 |
| `common.py:is_ddp_requested` | 症状 11 的三变量判据 |
| `gpt.py:kv_bytes_per_token` | 症状 2 中评测与对话阶段的 KV 显存来源 |

## 关键直觉

> [!tip] 先区分「报错」与「回退」，再定位
> 报错把根因写在栈里，回退把根因藏在警告里。nanochat 中影响最大的三处都是回退：FA3 缺失回退 SDPA、数据缺失回退旧目录、精度缺失回退 fp32，三者都不会中断训练，只会让结果变慢或变差。因此排查的第一步不是读栈，而是检查日志开头的三行状态：`COMPUTE_DTYPE`、FA3 是否启用、分片数。这三行与第 0 节的总览表、第 3、4、7 节一一对应，它们通过后，剩下的才是真正的报错。

## 例子与代码

### 例 1：一键分诊

```bash
# triage.sh —— 只读检查，不修改任何文件；按故障树顺序打印状态
set -u
BASE="${NANOCHAT_BASE_DIR:-$HOME/.cache/nanochat}"
echo "base dir: $BASE"
python -V 2>&1
python -c "import torch; print('torch:', torch.__version__, torch.version.cuda, torch.cuda.is_available())" 2>/dev/null || echo "torch: 未安装"
python -c "
from nanochat.common import COMPUTE_DTYPE, COMPUTE_DTYPE_REASON
from nanochat.flash_attention import HAS_FA3, USE_FA3
print('dtype:', COMPUTE_DTYPE, COMPUTE_DTYPE_REASON)
print('HAS_FA3:', HAS_FA3, '| USE_FA3:', USE_FA3)
" 2>/dev/null || echo "nanochat 无法导入"
nvidia-smi --query-gpu=name,memory.total,memory.used --format=csv,noheader 2>/dev/null || echo "无 NVIDIA 设备"
echo "shards: $(ls "$BASE"/base_data_climbmix/*.parquet 2>/dev/null | wc -l)"
echo "legacy: $(ls "$BASE"/base_data/*.parquet 2>/dev/null | wc -l)"
ls -l "$BASE"/tokenizer/tokenizer.pkl "$BASE"/tokenizer/token_bytes.pt 2>/dev/null || echo "分词器产物缺失"
ls -d "$BASE"/base_checkpoints/*/ "$BASE"/chatsft_checkpoints/*/ 2>/dev/null || echo "无检查点"
```

每一行对应故障树中的一条：`dtype` 与 `HAS_FA3` 对应症状 3 与 7，`shards` 与 `legacy` 对应症状 4，分词器一行对应症状 9，检查点一行对应症状 10。该脚本不写任何文件，可以在生产节点上随时执行。

### 例 2：校验恢复点与当前配置

```python
# resume_check.py —— 有真实 meta 时校验，无文件时用内嵌样例演示判定逻辑
import json
import os

base = os.environ.get("NANOCHAT_BASE_DIR", os.path.expanduser("~/.cache/nanochat"))
path = os.path.join(base, "base_checkpoints", "d24", "meta_005568.json")

if os.path.exists(path):
    meta = json.load(open(path, encoding="utf-8"))
    source = "real"
else:
    meta = {
        "step": 5568,
        "user_config": {"depth": 24, "target_param_data_ratio": 8,
                        "device_batch_size": 16, "total_batch_size": 1048576},
        "loop_state": {"total_training_time": 7281.4},
    }
    source = "demo"

cfg = meta["user_config"]
current = {"depth": 24, "target_param_data_ratio": 8,
           "device_batch_size": 8, "total_batch_size": 1048576}

print("source:", source, "| checkpoint step:", meta["step"])
for k in ("depth", "target_param_data_ratio", "device_batch_size", "total_batch_size"):
    same = cfg.get(k) == current.get(k)
    print(f"  {k}: ckpt={cfg.get(k)} now={current.get(k)} same={same}")
print("safe_to_resume:", cfg["depth"] == current["depth"] and
      cfg["total_batch_size"] == current["total_batch_size"])
```

示例模式下输出如下。`device_batch_size` 不同是允许的，只要 `total_batch_size` 相同，梯度累积会自动补偿；`depth` 与 `total_batch_size` 不同则不安全。

```text
source: demo | checkpoint step: 5568
  depth: ckpt=24 now=24 same=True
  target_param_data_ratio: ckpt=8 now=8 same=True
  device_batch_size: ckpt=16 now=8 same=False
  total_batch_size: ckpt=1048576 now=1048576 same=True
safe_to_resume: True
```

### 例 3：OOM 阶梯的显存预算

```bash
# 用 [[用--depth调参]] 第 5 节的公式估算 d24 在不同单卡批下的峰值，决定从哪里开始试
V=32768; T=2048; L=24; D=1536; STATIC=9170000000   # 8 卡时分片后的静态项
for dev in 32 16 8 4 2 1; do
    logits=$((2 * dev * T * V * 2))
    act=$((24 * L * dev * T * D))
    total=$(((STATIC + logits + act) / 1000000000))
    echo "dev=$dev  logits=$((logits / 1000000))MB  act=$((act / 1000000))MB  估计峰值=${total}GB"
done
```

预期输出说明为什么 d24 应从 16 开始试，而不是默认的 32：

```text
dev=32  logits=8589MB  act=57982MB  估计峰值=75GB
dev=16  logits=4294MB  act=28991MB  估计峰值=42GB
dev=8  logits=2147MB  act=14495MB  估计峰值=25GB
dev=4  logits=1073MB  act=7247MB  估计峰值=17GB
dev=2  logits=536MB  act=3623MB  估计峰值=13GB
dev=1  logits=268MB  act=1811MB  估计峰值=11GB
```

75 GB 在 80 GB 卡上留不出碎片余量，因此默认 32 对 d24 不可用；42 GB 是 speedrun 选 16 的依据。

## 易错点

> [!warning] 以下六条都是排查过程中真实会犯的判断错误
> 1. 把 `bf16_mfu: 0.00` 当成性能故障。非 CUDA 设备上 `gpu_peak_flops` 为 `inf`，MFU 恒为 0；应看 `tok/sec`。检验：日志中是否打印了 GPU 名称。
> 2. 用 `nvidia-smi` 的空闲显存判断能否启动。它包含缓存分配器保留的块，与 `torch.cuda.memory_allocated` 相差数 GB。检验：同时打印两个数。
> 3. 认为词表断言通过就说明分词器正确。断言只比较 `vocab_size` 数值。检验：比较 `tokenizer.pkl` 与 `meta` 的时间戳。
> 4. 用不同卡数恢复训练。优化器状态按 rank 分片，形状随 world size 变化。检验：`ls optim_*_rank*.pt | wc -l` 是否等于当前进程数。
> 5. 在 FA3 回退后仍用 `SSSL`。SDPA 的滑动窗口要构造显式掩码，比全上下文更慢。检验：日志是否出现 `SDPA has no support for sliding window`。
> 6. 用 `--device-batch-size=1` 长时间训练来「省显存」。累积步数会变成数十，Python 开销与数据加载成为瓶颈，墙钟时间远超预期。检验：日志中的 `dt` 与 `tok/sec` 是否明显恶化。

## 关联笔记

- 前置 [[本地环境搭建]]：环境类故障（症状 3、7、8、11）的安装前提。
- 前置 [[跑通speedrun脚本]]：症状 4、10 涉及的数据与检查点路径在该篇给出。
- 对照 [[用--depth调参]]：症状 1、2 的显存分解与调整顺序在该篇推导。
- 后续 [[实验日志]]：把每次故障的现象、验证命令与修复记成可复用条目。
- 跨库 [[分布式训练与部署]]：通用原理见该篇，本篇只写 nanochat 中 `torchrun` 与进程组的具体表现。

## 达标检测

- [ ] 能按「现象、原因、验证、修复」四段复述任意三条症状，并给出可复制的验证命令。
- [ ] 能解释为什么 FA3 回退属于静默失败，并指出日志中三行状态的位置。
- [ ] 能说明数据回退到 `base_data` 的触发条件，以及为什么换数据集后必须重训分词器。
- [ ] 能解释词表断言为何挡不住「数值相同、内容不同」的错配。
- [ ] 能说明恢复训练时哪些参数必须保持一致，哪些可以改变。
- [ ] 能区分 `allocated` 与 `reserved`，并解释 `expandable_segments` 的作用。
- [ ] 能用例 3 的脚本算出 d24 在 `dev=8` 时的估计峰值，并说明与实测的偏差来源。

## 参考来源

- Karpathy, *nanochat*（commit `92d63d4`），`nanochat/flash_attention.py`、`nanochat/dataset.py`、`nanochat/checkpoint_manager.py`、`nanochat/tokenizer.py`、`nanochat/common.py` —— 对应症状 3 到 11 的根因代码位置。
- Karpathy, *nanochat*（commit `92d63d4`），`scripts/base_train.py` 与 `scripts/base_eval.py` —— 对应 OOM、恢复、精度与评测阶段的实践细节。
- Karpathy, *nanochat* `dev/LOG.md`（2026-01-16 FA3 回退、2026-03-04 数据集升级与 dtype 管理） —— 对应回退的实现动机与 legacy 警告文本。
- PyTorch documentation, *CUDA memory management*、*torchrun*、*Reproducibility* —— 对应碎片、分布式环境变量与确定性三节。
- Hugging Face `kernels` 文档 —— 对应 FA3 内核的下载与缓存机制。
- NVIDIA, *CUDA C++ Programming Guide*（compute capability 与 FP8 支持） —— 对应精度与 FP8 的硬件门槛。
