检查点与恢复
定义
检查点(checkpoint)是训练过程中写入磁盘的一组文件,其并集足以让训练从写入那一刻继续:模型参数、优化器状态、以及描述「训练到哪一步、看过哪些数据、损失与统计量是多少」的元数据。
其中出现的术语与符号定义如下。
- step:全局优化器步数,从 0 开始计数;每步包含 次梯度累积(
grad_accum_steps)与一次参数更新。文件名中的六位数字即 step,例如model_000500.pt。 - rank:分布式进程编号 , 为 world size。nanochat 的模型参数在所有 rank 上完全相同(不使用 DDP 的参数分片),优化器状态则按 rank 分片。
- 分片(shard):把一份张量按第 0 维切成 份,第 个 rank 只持有第 份。
optim_{step:06d}_rank{r}.pt中的rank{r}表明该文件只对该 rank 有效。 - state_dict:PyTorch 的参数字典,键为参数名、值为张量。nanochat 保存的是未编译模型的
state_dict(),因此键名不带_orig_mod.前缀。 - meta device:PyTorch 的虚拟设备,张量只有形状与 dtype、不占用存储。用于在不知道真实显存的情况下构造模型骨架。
to_empty(device=...):把 meta 张量替换为目标设备上的真实张量,内容为未初始化的垃圾值;它只分配存储,不做初始化。assign=True:load_state_dict的选项,表示用检查点中的张量对象直接替换模型中的张量,而不是复制数值。dtype 与 device 由检查点张量决定。_orig_mod.前缀:torch.compile包装模型时给所有参数名加的前缀。由编译后模型保存的检查点带有该前缀,加载时必须剥掉。- pq_idx / rg_idx / epoch:数据加载器的游标。
pq_idx是 parquet 分片序号,rg_idx是分片内的 row group 序号,epoch是遍历整个分片列表的轮次,从 1 开始计数。
为什么重要
它解决的是「长跑训练的失败代价」这一具体问题。预训练是 nanochat 中最长的一段计算:当前 speedrun 用 d24、--target-param-data-ratio=8、总批 token,共 5568 步,reference speedrun 约 2.02 小时(README leaderboard 第 4 行),autoresearch 第 2 轮为 1.65 小时(第 6 行)。没有检查点,任何一次掉电、驱动崩溃或误杀进程都意味着这约 2 小时归零;有检查点但没有优化器状态,恢复后的前若干步会因动量与二阶矩从零重建而出现损失尖峰;有模型与优化器但没有数据游标,恢复后会从数据集开头重读,等于用重复数据继续训练。
它同时是整条流水线的接口:SFT 与 RL 都从 base 检查点热启动,评测脚本 scripts/base_eval.py 用 load_model("base", ...) 取模型与 meta,推理 Engine 也从同一目录加载。检查点文件的命名与 meta 字段一旦改变,下游四个阶段全部失效。
在「懂原理 / 能复现 / 懂工程」三个维度中,本篇属于工程维度:原理只有一条(状态要完整),工程细节却决定了恢复是否真的等价于没有中断。
原理与推导
1. 为什么是三类文件而不是一个
训练状态可以按「谁拥有它」分成三类,这个划分直接决定了保存位置。
第一类是模型参数。nanochat 不在模型层面做参数分片,所有 rank 持有完全相同的参数副本,因此只需要 rank 0 写一份 model_{step:06d}.pt。
第二类是优化器状态。MuonAdamW 在分布式下按 ZeRO-2 方式分片:AdamW 的大参数只保留本 rank 对应切片的 exp_avg、exp_avg_sq;Muon 只保留本 rank 拥有的 chunk 的 momentum_buffer、second_momentum_buffer。这些张量在各 rank 上形状不同、内容不同,无法由一个 rank 代写,因此每个 rank 写自己的 optim_{step:06d}_rank{r}.pt。
第三类是元数据。step、验证损失、模型配置、用户配置、数据游标、循环统计量都是小规模标量或字典,写成 JSON 便于人工检查与跨语言读取,由 rank 0 写 meta_{step:06d}.json。
三类文件合起来才构成「可继续的训练状态」。只有第一类是可推理的模型,只有前两类是可继续优化的训练,三者齐全才是可复现的训练。
2. 保存路径与命名
保存函数的实际代码如下(nanochat/checkpoint_manager.py,save_checkpoint)。
def save_checkpoint(checkpoint_dir, step, model_data, optimizer_data, meta_data, rank=0):
if rank == 0:
os.makedirs(checkpoint_dir, exist_ok=True)
# 模型参数:所有 rank 相同,只需 rank 0 保存
model_path = os.path.join(checkpoint_dir, f"model_{step:06d}.pt")
torch.save(model_data, model_path)
logger.info(f"Saved model parameters to: {model_path}")
# 元数据写成 JSON,便于人工检查
meta_path = os.path.join(checkpoint_dir, f"meta_{step:06d}.json")
with open(meta_path, "w", encoding="utf-8") as f:
json.dump(meta_data, f, indent=2)
logger.info(f"Saved metadata to: {meta_path}")
# 优化器状态按 rank 分片,每个 rank 必须保存自己的一份
if optimizer_data is not None:
os.makedirs(checkpoint_dir, exist_ok=True)
optimizer_path = os.path.join(checkpoint_dir, f"optim_{step:06d}_rank{rank:d}.pt")
torch.save(optimizer_data, optimizer_path)
logger.info(f"Saved optimizer state to: {optimizer_path}")
三个细节值得注意。step:06d 是零填充六位,使文件在字典序下等于数值序,find_last_step 因此可以直接取最大整数。optimizer_data is not None 允许「只存模型不存优化器」;加载端 load_checkpoint(..., load_optimizer=False) 在评测与推理时用它省一次磁盘读取。os.makedirs 在优化器分支里对所有 rank 都执行,因为 rank 0 建目录与其它 rank 写优化器分片之间没有同步屏障,每个 rank 都必须保证目录存在。
3. meta 的字段与用途
scripts/base_train.py 在保存时构造的元数据字典如下。
| 字段 | 内容 | 用途 |
|---|---|---|
step | 当前步数 | 恢复循环起点;find_last_step 的冗余副本 |
val_bpb | 最近一次验证的 bits per byte | SFT 继承与报告;断点时不重算 |
model_config | asdict(GPTConfig),含 n_layer、n_head、n_kv_head、n_embd、sequence_len、vocab_size、window_pattern | 重建模型结构,无需再传 --depth |
user_config | vars(args),训练脚本的全部命令行参数 | 复现实验、审计超参数来源 |
device_batch_size | 单卡批大小 | SFT 继承 batch 设置 |
max_seq_len | 上下文长度 | 与 model_config.sequence_len 互为校验 |
total_batch_size | 全局批大小(token) | SFT 继承;复算梯度累积步数 |
dataloader_state_dict | {"pq_idx", "rg_idx", "epoch"} | 恢复数据游标 |
loop_state | {"min_val_bpb", "smooth_train_loss", "total_training_time"} | 恢复日志统计与最优记录 |
loop_state 是最容易被忽略的一项。smooth_train_loss 是训练损失的指数滑动平均,total_training_time 是累计墙钟时间(只统计第 10 步之后),min_val_bpb 是最优验证损失。它们不影响梯度,但影响日志的可比性与「最优检查点」的判断,因此与参数一起持久化。
4. 加载:从 meta 到可训练模型
build_model 是加载流程的唯一入口(nanochat/checkpoint_manager.py),它构造出的模型是未编译、未包装的原始模型。
def build_model(checkpoint_dir, step, device, phase):
assert phase in ["train", "eval"], f"Invalid phase: {phase}"
model_data, optimizer_data, meta_data = load_checkpoint(checkpoint_dir, step, device, load_optimizer=False)
if device.type in {"cpu", "mps"}:
# CPU/MPS 没有 bf16 的完整算子支持,转成 fp32 做推理
model_data = {k: v.float() if v.dtype == torch.bfloat16 else v for k, v in model_data.items()}
# torch.compile 会给所有键加前缀,旧检查点需要剥掉
model_data = {k.removeprefix("_orig_mod."): v for k, v in model_data.items()}
model_config_kwargs = meta_data["model_config"]
_patch_missing_config_keys(model_config_kwargs)
model_config = GPTConfig(**model_config_kwargs)
_patch_missing_keys(model_data, model_config)
with torch.device("meta"):
model = GPT(model_config)
model.to_empty(device=device)
model.init_weights() # 需要它初始化 rotary 的 cos/sin 缓冲
model.load_state_dict(model_data, strict=True, assign=True)
if phase == "eval":
model.eval()
else:
model.train()
tokenizer = get_tokenizer()
assert tokenizer.get_vocab_size() == model_config_kwargs["vocab_size"]
return model, tokenizer, meta_data
流程可以拆成六个必要步骤。
第一步,meta device 构造。with torch.device("meta"): model = GPT(model_config) 只计算形状与 dtype,不分配显存。这样即使目标设备装不下两份模型,也能先建骨架再换存储。
第二步,to_empty(device=device) 把每个 meta 张量替换为目标设备上的空张量。此时参数内容是垃圾值,但形状正确。
第三步,init_weights()。这一步不可省略:cos、sin 两个旋转位置编码缓冲以 persistent=False 注册,不在 state_dict 中,只能由 init_weights 重新计算。源码在该行留了注释说明这是权宜之计。
第四步,load_state_dict(strict=True, assign=True)。strict=True 要求键集合完全一致,任何缺失或多余都会报错,这是防止「加载了半个模型」的最后一道检查。assign=True 让模型直接接管检查点张量,而不是逐元素复制,省一次内存往返,并保持检查点中的 dtype(例如 embedding 为 bf16、矩阵参数为 fp32)。
第五步,切换 train() 或 eval() 模式。它只影响 dropout 与归一化行为;nanochat 没有 dropout,但评测时仍应显式设置。
第六步,加载 tokenizer 并断言词表大小一致。词表不匹配的模型会产生无意义的 logits,这个断言把错误提前到加载阶段。
5. 向后兼容:补键而不是报错
旧检查点缺少后来新增的键,build_model 用两个补丁函数处理。
_patch_missing_config_keys 只处理一项:缺少 window_pattern 时补 "L"。原因是早期模型全部使用全上下文注意力,不存在滑动窗口模式。
_patch_missing_keys 处理两个参数:resid_lambdas 补 1.0(恒等缩放),x0_lambdas 补 0.0(关闭输入混入)。这两个值对应「该机制不生效」的中性取值,使旧检查点在结构上可加载。
需要明确代价:当前 init_weights 把 resid_lambdas 初始化在 1.15 到 1.05 之间、x0_lambdas 在 0.20 到 0.05 之间。补丁给的是 1.0 与 0.0,与「用当前代码从头训练」得到的函数不同。因此旧检查点可加载、可评测,但它的等效函数与同 step 的新训练并不完全一致。
6. 目录结构与查找约定
基础目录由 get_base_dir() 决定:优先读环境变量 NANOCHAT_BASE_DIR,否则用 ~/.cache/nanochat。在其下按来源分三个目录,由 load_model(source, ...) 的映射表给出:base 对应 base_checkpoints,sft 对应 chatsft_checkpoints,rl 对应 chatrl_checkpoints。
模型标签(model tag)默认是 d{depth},可用 --model-tag 覆盖。查找规则有两个函数。
find_largest_model(checkpoints_dir) 先在子目录名上匹配正则 d(\d+),取数值最大者;若一个都不匹配,退回按目录修改时间取最新。find_last_step(checkpoint_dir) 在目录内匹配 model_(\d+)\.pt,取最大整数。
这一对规则解释了「不传 --model-tag 与 --step 时会发生什么」:load_model_from_dir 会取最大的深度、再取该深度下的最后一步。对评测脚本这是便利,对复现实验是风险,因为目录里多一个更大的实验模型就会改变默认加载目标。
7. 断点续训恢复了什么
scripts/base_train.py 的恢复分支只做四件事:加载模型参数、加载优化器分片、恢复循环变量、恢复数据游标。
数据游标的恢复逻辑在 nanochat/dataloader.py 的 _document_batches 中。给定 (pq_idx, rg_idx, epoch),它定位到同一个 parquet 分片;由于每个 rank 负责 row group 的一个子序列(步长等于 world size),恢复时先算 base_idx = resume_rg_idx // ddp_world_size,随后执行 base_idx += 1,再以 rg_idx = base_idx * ddp_world_size + ddp_rank 对齐到本 rank 的相位。+= 1 意味着恢复点不是被保存的那个 row group,而是前进一整轮,最多跳过 world size 个 row group;若越过文件末尾则进入下一个分片。恢复只发生在第一次遍历,之后游标按 row group 正常推进。
loop_state 恢复三个统计量;val_bpb 用于让恢复后的第一次日志不显示空值。
有一项约束不在代码里,而在调度器里:num_iterations 决定 warmup、warmdown 与权重衰减余弦曲线的形状,恢复时必须与中断前一致。若用 --target-param-data-ratio 自动计算,则要求 --depth 与数据参数比都不变;若用 --num-iterations,则数字必须相同。否则即使参数与优化器都正确,学习率曲线也会错位。
还有一处细节:保存条件里包含 step != args.resume_from_step,即恢复的那一步不会被立即重存,避免用同一 step 覆盖文件。
8. 恢复是否等价的四个判据
「恢复成功」不等于「恢复等价」。可以按四个判据逐项检查,每项都对应一个具体的失败模式。
判据一,文件层面:optim_{step}_rank{r}.pt 对每个 都存在,且大小相近。缺一个文件时 load_optimizer=True 会直接抛异常;大小差异过大说明某个 rank 的保存被截断。
判据二,游标层面:恢复后第一条训练日志的 pq 与 rg 不为零(除非训练确实只走了几十步)。全为零说明 dataloader_state_dict 没有从 meta 传入,训练从头开始。
判据三,损失层面:恢复后的训练损失应与中断前的平滑损失接近。smooth_train_loss 是 EMA,恢复后从保存值继续,因此前几步的损失不会重置为初始值;若看到损失突然回到训练早期的量级,说明 loop_state 没有恢复。
判据四,调度层面:lrm(学习率乘数)在恢复的那一步应等于中断前同一步的值。由于 get_lr_multiplier 以 num_iterations 为自变量,这一项能同时暴露「num_iterations 不一致」的问题。
四项都通过,才能说恢复后走的是同一条轨迹;只通过第一项,通常只是「能加载」而非「能继续」。
在 nanochat 中的落地
第一处是 nanochat/checkpoint_manager.py 的 save_checkpoint 与 load_checkpoint。它们只负责字节搬运,不做任何结构转换;结构转换全部在 build_model 中完成。这样拆分的理由是:保存路径被训练脚本调用(需要快),加载路径被评测与推理调用(需要稳),两者对失败容忍度的要求不同。
第二处是 scripts/base_train.py 的保存调用点。它传入的是 orig_model.state_dict()(未编译模型),而不是 model。原因是 torch.compile 会给参数名加 _orig_mod. 前缀,且编译包装可能在后续版本改变键名;保存未编译模型使检查点与编译器版本解耦。同时它传入 optimizer.state_dict(),其中包含按 rank 分片后的状态。
第三处是 load_optimizer_state(source, device, rank, ...),它只加载某个 rank 的优化器分片而不重建模型,供 SFT 热启动使用。dev/LOG.md 的 SFT 记录指出,加载预训练动量比从零初始化略好,因此 SFT 默认开启该选项。
关键直觉
检查点是「参数 + 优化器矩 + 数据游标」的三元组,meta 是这三者的索引
模型参数决定「当前函数是什么」,优化器矩决定「下一步以多大步长、朝哪个方向走」,数据游标决定「下一步看到哪条数据」。三者的可分辨状态都由 step 标识,因此文件名用 step 对齐;meta 把「step 对应哪些配置与统计量」固定下来,使恢复不需要重放命令行。与严格定义的关系:定义给出三类文件,直觉说明它们分别对应训练的哪一个自由度;少任何一维,恢复后的轨迹都会偏离原轨迹,而不仅仅是「模型差一点」。
例子与代码
1. 保存、中断、恢复的完整流程
以下命令以 d12 为例,因为它在 8 卡上只需约 2520 步、成本低,适合验证恢复流程。--save-every=1000 是关键:默认值 -1 表示只在最后一步保存,训练中途被打断就没有可恢复的检查点。
# 训练 d12:自动批大小 2^19,共 2520 步;每 1000 步存一次
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
--depth=12 \
--device-batch-size=32 \
--save-every=1000 \
--run=d12-resume-demo \
--model-tag=d12_resume_demo
在日志出现 step 01000/02520 之后用 Ctrl-C 打断(不要在写文件时打断,torch.save 不是原子操作)。此时磁盘上应有:
~/.cache/nanochat/base_checkpoints/d12_resume_demo/
├── model_001000.pt # rank 0 写,约 0.79 GB(d12:矩阵 fp32 + 嵌入 bf16)
├── meta_001000.json # rank 0 写,几 KB
├── optim_001000_rank0.pt # 每个 rank 各写一份,每份约 0.15 GB
├── optim_001000_rank1.pt
├── ...
└── optim_001000_rank7.pt
恢复命令与训练命令只差一个参数:
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
--depth=12 \
--device-batch-size=32 \
--save-every=1000 \
--resume-from-step=1000 \
--run=d12-resume-demo \
--model-tag=d12_resume_demo
预期输出依次包含:Resuming optimization from step 1000、Scaling the LR for the AdamW parameters ∝1/√(768/768) = 1.000000、Calculated number of iterations from target data:param ratio: 2,520,随后第一条训练日志的 epoch: 1 之后 pq 与 rg 均为非零值,表明数据没有从头开始。
上面两个体积是估算值,按 d12 的参数构成计算:矩阵参数 个以 fp32 存(约 0.34 GB),wte、lm_head 各 个,wte 为 bf16(约 0.05 GB)、lm_head 为 fp32(约 0.10 GB),12 层中的 6 层各有一个 的 value embedding,共 个 bf16 元素(约 0.30 GB),合计约 0.79 GB。若按 d24 计算同一公式,模型文件约 4.23 GB,单 rank 优化器分片约 0.72 GB。
2. 直接用加载器读检查点
import os
import torch
from nanochat.checkpoint_manager import load_model, find_last_step
device = torch.device("cuda", 0)
# model_tag 与 step 都省略时:取最大深度的目录、该目录下的最大 step
model, tokenizer, meta = load_model("base", device, phase="eval")
print(meta["step"], meta["val_bpb"], meta["model_config"]["n_layer"])
# 例如:5568 0.71800 24
# 也可以显式定位:先查最后一步,再加载该步
# 注意 find_last_step 不展开 ~,必须自己 expanduser
ckpt_dir = os.path.expanduser("~/.cache/nanochat/base_checkpoints/d24")
last = find_last_step(ckpt_dir)
print(last)
load_model 的第二个位置参数是 device,第三个是 phase;model_tag、step 必须用关键字传,因为 load_model 把 *args 原样转给 load_model_from_dir。
3. 一次加载的时间与空间代价
build_model 的峰值显存约为参数量的两倍:to_empty 先按 meta 形状分配一份空张量,load_state_dict(assign=True) 再把每个参数对象替换为检查点张量,被替换的空张量随即释放。assign=True 本身不复制数值,所以替换完成后不会长期保留两份;scripts/base_train.py 在恢复分支里仍写了 del model_data,作用是尽早释放字典对象与其中已不再被模型引用的张量。若要进一步压低峰值,只能改成先在 CPU 上加载、再逐张量搬到设备。
4. 核对 meta 与文件是否自洽
import json, os
d = os.path.expanduser("~/.cache/nanochat/base_checkpoints/d12_resume_demo")
with open(os.path.join(d, "meta_001000.json"), encoding="utf-8") as f:
meta = json.load(f)
print(sorted(meta.keys()))
# 预期:['dataloader_state_dict', 'device_batch_size', 'loop_state', 'max_seq_len',
# 'model_config', 'step', 'total_batch_size', 'user_config', 'val_bpb']
print(meta["step"] == 1000, meta["dataloader_state_dict"]["epoch"] == 1)
# 预期:True True
print(meta["model_config"]["n_layer"], meta["model_config"]["n_embd"])
# 预期:12 768
print(os.path.getsize(os.path.join(d, "model_001000.pt")) // 2**20, "MiB")
# 预期:约 756(0.79 GB)
最后一行把第 2 节的手算体积与真实文件对上:若差异很大,通常是因为检查点由 fp32 参数保存(未走 bf16 的 wte/value embedding 路径),或保存了编译后模型的额外缓冲。
易错点
六个可检验的错误
1. 认为优化器状态只由 rank 0 保存。实际是每个 rank 各写一份
optim_{step}_rank{r}.pt;只保留 rank0 的文件会导致恢复时报错或状态错误。2. 把检查点直接
load_state_dict到torch.compile之后的模型。若检查点由编译模型保存,键名带_orig_mod.,必须先用removeprefix剥离;反过来,把已剥前缀的字典加载进编译模型会报 missing keys。3. 跳过
init_weights()。cos、sin是persistent=False的缓冲,不在state_dict中,跳过这一步会让 RoPE 变成垃圾值,损失在第一步就异常,而参数加载本身不会报错。4. 恢复时改变
--depth或--target-param-data-ratio。num_iterations随之变化,warmup/warmdown 与权重衰减余弦的位置全部错位;参数能加载,训练语义已经不同。5. 用
--save-every=-1启动长跑。默认只在最后一步保存,中途中断没有可恢复点;speedrun 脚本即采用该默认,因此它不可恢复。6. 在 CPU/MPS 上直接加载 bf16 检查点做推理。
build_model只在device.type in {"cpu","mps"}时把 bf16 转 fp32;若自己写加载逻辑,需复制这段转换,否则部分算子在 CPU 上不支持 bf16。
关联笔记
- 前置 训练脚本与speedrun:checkpoint 的调用点、保存频率与
num_iterations的来源都在训练循环里。 - 对照 分布式训练与优化器分片:解释
optim_{step}_rank{r}.pt为什么必须按 rank 分开,以及分片边界如何由参数分组决定。 - 后续 跑通speedrun脚本:整条 speedrun 的产物目录与恢复命令。
- 跨库 分布式训练与部署:通用原理见该篇,本篇只讲 nanochat 的三类文件约定与 ZeRO-2 分片的落盘形式。
- 跨库 PyTorch实战入门:
metadevice、to_empty、assign=True的通用语义。
达标检测
- [ ] 能不看源码写出三类检查点文件名格式,并说明每一类由哪个 rank 写、为什么。
- [ ] 能列出
meta的九个字段,并指出哪两个字段决定「恢复后看到哪条数据」。 - [ ] 能解释
build_model中init_weights()为何不能省略,以及省略后在哪一步暴露。 - [ ] 能写出
_patch_missing_config_keys与_patch_missing_keys分别补了哪些键、补的值是多少,并说明补丁值与新训练初值不同的后果。 - [ ] 能计算 d24 模型文件与单 rank 优化器分片的近似大小(给出参数分组与 dtype 依据)。
- [ ] 能设计一组命令,使 d12 训练在第 1000 步后可恢复,并指出必须显式设置哪个参数。
- [ ] 能说明恢复时若
num_iterations变化,学习率曲线在哪些区间错位。
参考来源
- Karpathy, nanochat(commit 92d63d4),
nanochat/checkpoint_manager.py—— 对应本篇第 2、4、5、6 节的全部函数与行为。 - Karpathy, nanochat(commit 92d63d4),
scripts/base_train.py与nanochat/dataloader.py—— 对应 meta 字段、恢复分支与数据游标逻辑。 - Rajbhandari et al., ZeRO: Memory Optimizations Toward Training Trillion Parameter Models(1910.02054)—— 对应优化器状态分片(ZeRO-2)的解释。
- PyTorch 文档,
torch.device("meta")、Module.to_empty、load_state_dict(assign=...)—— 对应第 4 节的三个 API 语义。 - Karpathy, nanochat(commit 92d63d4),
dev/LOG.md2026-02-16 条目 —— 对应 SFT 优化器热启动与load_optimizer_state的动机。