Accelerate Checkpointing 指南:用 save_state / load_state 实现模型训练状态的完整保存与恢复

原创2026-09-23 16:14:131,746 阅读
文章标签:人工智能深度学习分布式训练机器学习

Accelerate Checkpointing 指南:用 save_state / load_state 实现模型训练状态的完整保存与恢复

在使用 Accelerate 训练 PyTorch 模型时,断点续训(Checkpointing)是工程落地的必备能力:训练中断后能精确恢复到之前的训练进度,而不是从头重来。本篇指南以 Accelerate 官方文档(docs/source/usage_guides/checkpoint.md)为核心骨架,结合当前仓库中 src/accelerate/checkpointing.py 与 src/accelerate/accelerator.py 的源码实现,讲解如何用 Accelerator.save_state 一键保存模型、优化器、RNG 随机数生成器、GradScaler 等全部训练状态,如何在断点后通过 load_state 与 skip_first_batches 无缝恢复训练,以及如何通过 ProjectConfiguration 和 register_for_checkpointing 定制保存策略。读完本篇,你将掌握一套可直接复制到训练脚本中的完整断点续训方案。

为什么要用 Accelerate 做 Checkpointing

在分布式训练中,直接调用 torch.save(model.state_dict()) 会遇到一系列问题:

  • 模型经过 accelerator.prepare() 后可能被 DistributedDataParallel、FSDP、DeepSpeed 等包装,直接保存的是包装层而非原始模型;
  • 训练状态远不止模型权重,还包括优化器动量、学习率调度器进度、随机数生成器状态、混合精度下的 GradScaler 缩放因子;
  • 分布式环境下,每个进程都要保存状态,何时同步、由谁落盘、如何避免进程间互相覆盖,都需要约定。

Accelerate 提供两个便捷函数一次性解决上述问题:

  • Accelerator.save_state:把模型、优化器、RNG 生成器、GradScaler(如启用混合精度)以及注册过的自定义对象保存到指定文件夹;
  • Accelerator.load_state:从 save_state 生成的文件夹中恢复全部状态。

这两者的实现位于 src/accelerate/checkpointing.py 的 save_accelerator_state 与 load_accelerator_state,而 Accelerator 上的公开 API 定义在 src/accelerate/accelerator.py(save_state)与 src/accelerate/accelerator.py(load_state)。

最小可用示例:保存与恢复一个完整训练状态

官方文档给出的最小示例完整呈现了"注册调度器 → 保存初始状态 → 训练 → 恢复状态"的全流程,以下是继承原文并补充注释的版本:

from accelerate import Accelerator
import torch

accelerator = Accelerator(project_dir="my/save/path")

my_scheduler = torch.optim.lr_scheduler.StepLR(my_optimizer, step_size=1, gamma=0.99)
my_model, my_optimizer, my_training_dataloader = accelerator.prepare(
    my_model, my_optimizer, my_training_dataloader
)

# 注册 LR scheduler:它不具备模型/优化器/采样器那样的"默认待遇",需要显式注册
accelerator.register_for_checkpointing(my_scheduler)

# 保存初始状态
accelerator.save_state()

device = accelerator.device
my_model.to(device)

# 执行训练
for epoch in range(num_epochs):
    for batch in my_training_dataloader:
        my_optimizer.zero_grad()
        inputs, targets = batch
        inputs = inputs.to(device)
        targets = targets.to(device)
        outputs = my_model(inputs)
        loss = my_loss_function(outputs, targets)
        accelerator.backward(loss)
        my_optimizer.step()
    my_scheduler.step()

# 从之前的保存点恢复状态
accelerator.load_state("my/save/path/checkpointing/checkpoint_0")

使用这个 API 时有两条重要约束,源码注释中反复强调:

  1. 保存与加载必须出自同一训练脚本。save_state / load_state 是为"训练中途断电续跑"设计的,其内部对模型、优化器的保存方式与 prepare 后的包装状态强相关,并不保证跨脚本通用(详见 src/accelerate/accelerator.py 中的 Tip 说明)。如果目标是"训练完成后导出模型权重供推理使用",应使用 accelerator.save_model(src/accelerate/accelerator.py,支持 max_shard_size 分片与 safetensors 序列化)。
  2. 不注册的对象不会被保存。如果某个文件没有通过 register_for_checkpointing 注册,即使它存在于保存目录中,load_state 也不会加载它。

一次 save_state 到底写入了哪些文件

save_accelerator_state(src/accelerate/checkpointing.py)会把状态组织成一组命名文件,文件名的常量定义在 src/accelerate/utils/constants.py:

文件 常量 内容
model.safetensors(默认)或 pytorch_model.bin(safe_serialization=False 时) SAFE_MODEL_NAME / MODEL_NAME 模型权重,默认使用 safetensors 序列化
optimizer.bin OPTIMIZER_NAME 优化器 state_dict()
scheduler.bin SCHEDULER_NAME 已注册调度器的 state_dict()
sampler.bin SAMPLER_NAME DataLoader 采样器状态(仅当使用 Accelerate 的 SeedableRandomSampler 等自定义采样器时)
dl_state_dict.bin — 使用 StatefulDataLoader 时的完整 DataLoader 状态
scaler.pt SCALER_NAME GradScaler 状态(仅混合精度训练时存在)
random_states_{process_index}.pkl RNG_STATE_NAME 当前进程的 Python random、NumPy、torch(含 CUDA/XPU/MLU/HPU 等各后端)RNG 状态,以及内部 step 计数
custom_checkpoint_{index}.pkl — 通过 register_for_checkpointing 注册的自定义对象

其中值得注意的实现细节:

  • 多对象场景下(多个模型/优化器/调度器),文件名会追加序号,如 pytorch_model_1.bin、optimizer_1.bin;
  • 加载时(src/accelerate/checkpointing.py)会优先寻找 model.safetensors,不存在则回退到 pytorch_model.bin,因此两种序列化格式的检查点可以混用;
  • RNG 状态文件按 process_index 命名,保证每个分布式进程恢复各自的随机状态,从而让数据采样、dropout 等行为与中断前完全一致;
  • 加载 RNG 时若发现文件中带有 step 字段,会把该值写入 override_attributes,最终由 Accelerator.load_state 恢复内部 self.step 计数(src/accelerate/accelerator.py)。

用 ProjectConfiguration 定制保存位置与自动命名

默认情况下,save_state(output_dir) 要求你手动传入目录。若希望训练过程中自动迭代命名检查点,可通过 ProjectConfiguration 定制(对应文档原句:if automatic_checkpoint_naming 启用后,每个检查点保存在 Accelerator.project_dir/checkpoints/checkpoint_{checkpoint_number})。该配置类定义在 src/accelerate/utils/dataclasses.py,支持以下字段:

字段 默认值 说明
project_dir None 项目根目录,保存的数据存放于此
logging_dir None 本地日志目录,缺省时与 project_dir 相同
automatic_checkpoint_naming False 是否启用检查点自动命名
total_limit None 最多保留的检查点数量,超出时删除最旧者
iteration 0 当前保存迭代计数(对应检查点编号)
save_on_each_node False 多节点训练时,是否在每个节点都保存(否则仅主节点保存)

启用方式:

from accelerate import Accelerator
from accelerate.utils import ProjectConfiguration

project_config = ProjectConfiguration(
    project_dir="my/save/path",
    automatic_checkpoint_naming=True,
    total_limit=3,          # 只保留最近 3 个检查点
)
accelerator = Accelerator(project_configuration=project_config)

# 无需传目录,自动保存到 my/save/path/checkpoints/checkpoint_0、checkpoint_1、...
accelerator.save_state()

源码层面的行为(src/accelerate/accelerator.py):

  • save_state 内部检查 project_configuration.automatic_checkpoint_naming,为真时把 output_dir 强制指向 project_dir/checkpoints;
  • 当 total_limit 有值且当前检查点数量超限时,由主进程按编号排序后删除最旧的检查点,日志会提示删除了多少个以腾出空间;
  • 每次保存后 project_configuration.iteration += 1,检查点目录以 checkpoint_{iteration} 命名;
  • 若目标目录已存在同名检查点会抛出 ValueError,提示手动调整 save_iteration 以跳过已存在的编号;
  • 启用自动命名后,load_state() 可以不传 input_dir,它会自动挑选编号最大的(即最新的)检查点加载(src/accelerate/accelerator.py)。

register_for_checkpointing:让调度器等自定义对象一并保存

模型、优化器、DataLoader 采样器会被 Accelerate 自动纳入检查点,但学习率调度器等对象不会。官方文档给出的解法是 Accelerator.register_for_checkpointing:只要对象同时具备 state_dict 和 load_state_dict 方法,就能注册并随 save_state / load_state 自动存取。

其实现(src/accelerate/accelerator.py)会逐一校验传入对象是否同时具备两个方法,否则抛出 ValueError 并列出非法对象;通过校验后对象被追加到 self._custom_objects。保存时调用 save_custom_state 写入 custom_checkpoint_{index}.pkl,加载时调用 load_custom_state 读取,详见 src/accelerate/checkpointing.py。

accelerator.register_for_checkpointing(my_scheduler, my_custom_tracker)

# 之后 save_state / load_state 会自动带上这两个对象

需要留意的是,load_state 会严格校验目录中 custom_checkpoint_*.pkl 的数量是否与当前注册对象数量一致,不一致会抛出 RuntimeError(src/accelerate/accelerator.py),提示检查点必须由"同一组注册对象"产生,或在目录中避免使用 custom_checkpoint 命名冲突文件。

分布式后端下的保存差异:FSDP / DeepSpeed / Megatron-LM

save_state 内部会根据 self.distributed_type 分派不同的保存策略(src/accelerate/accelerator.py):

  • FSDP:调用 save_fsdp_model / save_fsdp_optimizer(src/accelerate/utils/fsdp_utils.py),按 FSDP 分片规则保存模型与优化器;
  • DeepSpeed:调用 DeepSpeed 引擎的 save_checkpoint(output_dir, ckpt_id),模型与优化器状态由 DeepSpeed 统一管理,ckpt_id 为 pytorch_model 或 pytorch_model_{i};加载时对应调用 load_checkpoint;
  • Megatron-LM:委托模型的 save_checkpoint / load_checkpoint 处理;
  • 其他场景(DDP / 单卡等):走通用路径,用 get_state_dict 取出权重后交给 save_accelerator_state。

get_state_dict(src/accelerate/accelerator.py)同样按后端区分:DeepSpeed ZeRO-3 场景要求配置 stage3_gather_16bit_weights_on_model_save=True(否则抛错并提示改用 zero_to_fp32.py 恢复权重);FSDP 通过 FULL_STATE_DICT + offload_to_cpu=True、rank0_only=True 只在 rank 0 汇总完整状态;FSDP2 则基于 torch.distributed.checkpoint 的 get_model_state_dict 实现;存在 offload 参数时走 get_state_dict_offloaded_model。

此外 load_state 对 map_location 有默认行为(src/accelerate/accelerator.py):多进程多设备且非 MULTI_XPU 时默认 "on_device"(状态加载到各自设备),否则默认 "cpu";你也可以通过 load_model_func_kwargs 里的 map_location 显式覆盖。load_accelerator_state 会对非法值抛出 TypeError,只接受 None、"cpu"、"on_device" 三者。

恢复 DataLoader 进度:skip_first_batches

save_state 保存了采样器状态,但如果你是在一个 epoch 的中间保存检查点,恢复后 DataLoader 会从头开始取数,导致同一批数据被重复训练。官方文档给出的解法是 Accelerator.skip_first_batches,它返回一个高效跳过前 num_batches 个 batch 的新 DataLoader:

from accelerate import Accelerator

accelerator = Accelerator(project_dir="my/save/path")

train_dataloader = accelerator.prepare(train_dataloader)
accelerator.load_state("my_state")

# 假设检查点保存在第 100 个 step 处
skipped_dataloader = accelerator.skip_first_batches(train_dataloader, 100)

# 恢复后的第一个 epoch 使用跳过版
for batch in skipped_dataloader:
    # 完成当前 epoch 的剩余部分
    pass

# 后续 epoch 回到原始 dataloader
for batch in train_dataloader:
    pass

其底层实现在 src/accelerate/data_loader.py:非 IterableDataset 场景下,通过 SkipBatchSampler 包装原 batch_sampler 实现"从第 N 个 batch 开始取";对于 DataLoaderShard / DataLoaderDispatcher 会保留 device、rng_types、iteration 等属性重建一个新 DataLoader。官方文档特别提示,若原 DataLoader 是 StatefulDataLoader(其自身支持完整状态存取),则不应使用 skip_first_batches,恢复后直接沿用原 DataLoader 即可。

端到端实战:把断点续训接进真实训练脚本

仓库中的 examples/by_feature/checkpointing.py 是一个可直接运行的完整示例(GLUE MRPC 文本分类 + 断点续训),它演示了比官方文档示例更完整的工程化模式,包括两种检查点频率和目录解析逻辑:

# 训练开始时加载检查点(--resume_from_checkpoint 传入检查点目录)
if args.resume_from_checkpoint:
    accelerator.load_state(args.resume_from_checkpoint)
    path = os.path.basename(args.resume_from_checkpoint)
    training_difference = os.path.splitext(path)[0]
    if "epoch" in training_difference:
        starting_epoch = int(training_difference.replace("epoch_", "")) + 1
        resume_step = None
    else:
        resume_step = int(training_difference.replace("step_", ""))
        starting_epoch = resume_step // len(train_dataloader)
        resume_step -= starting_epoch * len(train_dataloader)

for epoch in range(starting_epoch, num_epochs):
    # 恢复后的第一个 epoch 跳过已训练过的 step
    if args.resume_from_checkpoint and epoch == starting_epoch and resume_step is not None:
        if not args.use_stateful_dataloader:
            active_dataloader = accelerator.skip_first_batches(train_dataloader, resume_step)
        else:
            active_dataloader = train_dataloader
        overall_step += resume_step
    else:
        active_dataloader = train_dataloader
    ...
    # 按 step 或 epoch 频率保存
    accelerator.save_state(output_dir)  # 例如 "step_100" / "epoch_1"

这段代码展示了三个关键工程细节,可以平滑移植到任何训练脚本:

  1. 目录即元数据:用 epoch_{i} / step_{i} 命名检查点目录,恢复时从路径字符串解析出应从第几个 epoch、第几个 step 继续,无需额外维护状态文件;
  2. 频率可控:--checkpointing_steps 可设为整数(每 N 步存一次)或 "epoch"(每个 epoch 存一次);
  3. 状态校验:恢复后可立即评估模型性能并与断点前记录的值比对,确认恢复无误。

如何验证断点续训的正确性

仓库提供了配套测试来保证该功能的可靠性:src/accelerate/test_utils/scripts/external_deps/test_checkpointing.py 是一个带 --resume_from_checkpoint 参数的端到端脚本,训练流程为:

  1. 每训练完一个 epoch 调用 accelerator.save_state(output_dir)(目录名为 epoch_{epoch}),同时把该 epoch 的准确率、调度器学习率、优化器学习率、epoch 号、总 step 数写入 state_{epoch}.json;
  2. 断点续训时,先从检查点目录解析出 starting_epoch,调用 accelerator.load_state 恢复;
  3. 恢复后立即跑一次评估,然后断言"恢复后评估的准确率 == 断点前记录的准确率、调度器/优化器学习率一致、epoch 号一致",全部断言通过才认为加载成功(src/accelerate/test_utils/scripts/external_deps/test_checkpointing.py)。

这套"保存 → 重新启动 → 恢复 → 数值比对"的验证思路同样适用于你自己的训练脚本:恢复点上的任何数值(loss、准确率、学习率、优化器状态)都应该与中断前完全一致,这是判断检查点系统是否正确的黄金标准。

小结与最佳实践

  • 训练中断续跑:用 save_state / load_state,并配合 register_for_checkpointing 注册调度器等对象;二者只应在同一训练脚本内配对使用;
  • 自动管理检查点:通过 ProjectConfiguration(automatic_checkpoint_naming=True, total_limit=N) 自动命名并淘汰旧检查点,load_state() 不传参即可加载最新断点;
  • 恢复 DataLoader 进度:普通 DataLoader 用 skip_first_batches,StatefulDataLoader 直接加载状态;
  • 权重导出:训练完成后请使用 save_model(支持 safetensors 与分片),不要复用 save_state 的产物做推理加载;
  • 分布式后端(FSDP / DeepSpeed / Megatron-LM)的检查点由 Accelerate 自动分派底层实现,但要注意 DeepSpeed ZeRO-3 需要开启 stage3_gather_16bit_weights_on_model_save 才能通过 get_state_dict 拿到 16bit 权重;
  • 每次恢复后做一次数值比对,让断点续训的正确性始终有据可查。

相关参考材料:官方文档原文 docs/source/usage_guides/checkpoint.md、API 参考 docs/source/package_reference/accelerator.md、核心实现 src/accelerate/checkpointing.py、配置类 src/accelerate/utils/dataclasses.py、实战示例 examples/by_feature/checkpointing.py。

登录后查看全文
accelerate