w wyl123ly 的博客
MD

常见问题踩坑

27 KB 2026.10.22 原文件

常见问题踩坑

定义

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

本篇使用的术语:

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

分诊(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 或 inffp16 未配 GradScaler检查 COMPUTE_DTYPE 与 scaler 日志
8CPU 上每秒几 token无 GPU 且未降级配置打印设备类型与精度
9encode/decode 不往返特殊 token 走错 API往返测试
10找不到检查点基准目录或 tag 不一致列 base_checkpoints//model_.pt
11torchrun 启动失败端口冲突或环境变量残留env 过滤 RANK

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

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

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

验证:

# 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 缓存,这些峰值可能高于训练稳态。

验证:

# 训练脚本在结束时打印分配器峰值;与 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 版本不兼容。

验证:

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 升级的用户准备的,若从未下载过数据,两个目录都不存在。

验证:

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 到字节的映射已经改变,模型的输入语义整体错位。

验证:

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 曲线整体偏移。

验证:

# 恢复日志中应出现这一行,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,会得到无缩放的反向传播。

验证:

# 日志开头的两行足以定位
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 以上的深度,单步时间会达到分钟量级。

验证:

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 会被系统性低估。

验证:

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。

验证:

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,同机多个未清理的进程会冲突。

验证:

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 显存来源

关键直觉

先区分「报错」与「回退」,再定位

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

例子与代码

例 1:一键分诊

# 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:校验恢复点与当前配置

# 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 不同则不安全。

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 阶梯的显存预算

# 用 [[用--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:

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 的依据。

易错点

以下六条都是排查过程中真实会犯的判断错误

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 的硬件门槛。