w wyl123ly 的博客
MD

检查点与恢复

25 KB 2026.10.22 原文件

检查点与恢复

定义

检查点(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 byteSFT 继承与报告;断点时不重算
model_configasdict(GPTConfig),含 n_layer、n_head、n_kv_head、n_embd、sequence_len、vocab_size、window_pattern重建模型结构,无需再传 --depth
user_configvars(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实战入门:meta device、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.md 2026-02-16 条目 —— 对应 SFT 优化器热启动与 load_optimizer_state 的动机。