Skip to content

分布式 checkpoint 实战:DCP 的分片布局、异步保存与重分片 ​

摘要:torch.distributed.checkpoint(DCP)解决的问题不是"保存得更快一点",而是两个结构性缺陷:torch.save 要求把分片参数汇成一份完整 state_dict,内存放大到单卡放不下;以及保存下来的东西和"当时的并行拓扑"绑死,换机器就加载不了。DCP 的官方定义就两句话——每个 rank 只写自己的分片、支持加载时重分片。本文把这两句话拆成可操作的契约、目录布局、参数账和验证流程。

1. 先看清 torch.save 失效的两个点 ​

很多团队把 checkpoint 慢归因于"存储带宽不够",于是换 NVMe、加条带,结果没变化。真正的原因是 torch.save 的调用形态:它拿到的是一个已经聚合好的完整 state_dict。在 FSDP/张量并行下,这份完整 state_dict 要么需要 all-gather(显存翻倍并产生一次全集群通信),要么只在 rank0 聚合(单点内存与单点带宽)。前者在 70B 级别直接 OOM,后者把整集群的写带宽压到一个进程。

DCP 的官方说明把差异写得很直接:

  • 它产生多个文件,至少每个 rank 一个("It produces multiple files per checkpoint, with at least one per rank");
  • 它是原地操作,模型必须先分配好自己的数据,DCP 直接使用这块存储("It operates in place, meaning that the model should allocate its data first and DCP uses that storage instead")。

第二条是理解后面所有坑的钥匙:DCP 从不替你搬数据,它只往你已有的 tensor 里写。这也解释了为什么加载时必须"先按新拓扑建好模型、分配到设备"再调用 load。

2. 三条核心契约 ​

契约官方依据违反后的现象
原地语义"operates in place… model should allocate its data first"加载后参数没变,或加载报错
键一致"Each rank must have the same keys in their state_dict… Mismatched keys may result in hangs or errors"卡住不返回(hang),比报错更难查
Stateful 协议对象若有 state_dict/load_state_dict,save 前调用前者、load 后调用后者自定义模块状态丢失

加载侧还有三条官方警告,必须逐条落实:

  1. 所有 tensor 必须在调用前就分配到目标设备("All tensors in state_dict must be allocated on their destination device prior to calling this function");
  2. 非 tensor 数据用 torch.load() 加载并原地修改 state_dict——所以非张量字段(如 epoch、数据加载器状态)也要放进 state_dict,而不是另存一个 json;
  3. 必须在根模块上再调一次 load_state_dict,否则 load 的后处理与非张量数据不会向下传播。

第 3 条是最常见的"加载成功但结果不对"的原因:dcp.load 把数据写进了 state_dict,但模块需要 load_state_dict 才真正接管。

3. 一次保存到底发生了什么 ​

一次保存的六步序列、目录里为什么会出现 .metadata,以及 async_save 的边界

DCP 把保存拆成 planner 与 storage 两层,官方给出的调用序列是固定的六步:

  1. 所有 rank:设置 checkpoint_id;
  2. 所有 rank:set_up_storage_writer();
  3. 所有 rank:prepare_local_plan()——每个 rank 算出"我要写哪些切片";
  4. 仅协调者:prepare_global_plan()——汇总,决定归属与去重;
  5. 所有 rank:write_data();
  6. 仅协调者:finish()——写元数据,并把这次 checkpoint 标记为成功。

第 6 步是"为什么目录里有个 .metadata 文件"的答案。对 FileSystemWriter,官方描述的形态是:

  • 每个写请求一个文件(one file per write request);
  • 启用 rank 协调时,加一个全局 .metadata;不启用(use_collectives=False)时,每个 rank 写一个 __{rank}.metadata;
  • 它的假设是 checkpoint 路径是空目录或不存在,且文件创建是原子的。

"每个写请求一个文件"是 DCP checkpoint 动辄上万个小文件的根源。这直接接上 05 章的运营问题:一次大模型 checkpoint 就是一次小文件风暴,会同时压 MDC/元数据服务和容量配额——本仓库 容量与配额运营 里讲的 inode 曲线,最容易在这里被顶穿。

4. 为什么必须用 get_state_dict ​

如果直接把 model.state_dict() 交给 DCP,在 FSDP 与 DDP 混合、或用了张量并行/流水并行时,会出现两件坏事:模型键的 FQN 不一致;优化器 state_dict 用的是参数 ID 而不是名字。官方对这套 API 的说明正好覆盖这两点:get_state_dict 返回的键是canonical FQN(即"未被任何并行切分时 named_parameters() 给的名字"),并把优化器的参数 ID 转换成同一套 FQN,因此结果可以直接喂给 dcp.save() / dcp.load(),且"可以用不同的 trainer 数量与不同并行组合重新分片"。

实操要点:

python
from torch.distributed.checkpoint.state_dict import get_state_dict, set_state_dict
import torch.distributed.checkpoint as dcp

model_sd, optim_sd = get_state_dict(model, optimizers=[optim])
sd = {"model": model_sd, "optim": optim_sd}
dcp.save(sd, checkpoint_id=f"/ckpt/step-{step}")

加载侧有一条时机约束容易被忽略:set_state_dict(以及 set_optimizer_state_dict)只能在 backward() 之前或优化器 step() 之后调用,否则优化器状态不会正确初始化。还原断点续训时,"先 load 再 backward"的顺序不是风格问题,是硬要求。

模块化写法(把模型和优化器包成 Stateful 对象)在 DCP 示例里更常见,好处是 dcp.load 结束时 load_state_dict 会被自动调用,省掉第 2 节提到的那次"忘了在根模块调 load_state_dict"。

5. FileSystemWriter 六个参数的真实含义 ​

官方签名与默认值:

python
FileSystemWriter(path, single_file_per_rank=True, sync_files=True,
                 thread_count=1, per_thread_copy_ahead=10000000,
                 cache_staged_state_dict=False, overwrite=True,
                 serialization_format=SerializationFormat.TORCH_SAVE)
参数默认影响实践建议
single_file_per_rankTrue每个 rank 一个文件 vs 每个写请求一个文件保持 True:文件数从"上万"降到"每 rank 数千",元数据压力显著下降
sync_filesTrue写完后是否 fsync生产保持 True;只在压测吞吐时临时关掉,并明确"掉电即丢"的风险
thread_count1每个 rank 的写入线程数单文件顺序写够快时不要加;小文件多、单文件不足带宽时加到 2~4 与 per_thread_copy_ahead 一起调
per_thread_copy_ahead10000000(约 9.5 MiB)预读/预拷贝窗口(字节)与线程数同向调大能压住尾延迟,但吃 host 内存
cache_staged_state_dictFalse是否缓存 staged 副本,便于后续复用只在"同一步多次保存"的场景开,否则白占一份内存
overwriteTrue目标已存在时是否覆盖生产建议改 False:配合"按 step 分目录",让重复写同一路径直接失败而不是静默覆盖好 checkpoint

overwrite=False 这条不是洁癖。DCP 的假设是"路径为空或不存在",一旦允许覆盖,一个写了一半的失败 checkpoint 会和上一份好 checkpoint 落进同一目录,元数据与分片互相踩踏,恢复时才发现读不出来。

6. async_save 到底异步了什么 ​

官方对 async_save 的描述是两步:先把 state_dict 反暂存(de-stage)到 staging 存储(默认 CPU 内存),再在独立线程里调用 save。注意顺序——异步的部分是"写盘",不是"拷贝"。GPU→CPU 的这一次拷贝发生在调用 async_save 的当下(除非你显式用异步 staging)。

返回对象是 AsyncSaveResponse,它带两个 future,这两个必须分清,否则会算错"checkpoint 到底成功了没有":

  • staging_completion:本地副本已拷完——到这一步为止,训练可以安全地继续改参数;
  • upload_completion:checkpoint 真正写完——只有它完成,这次保存才算成功。

官方还给了两条硬约束:这个特性是 experimental;"MUST CALL CLOSE AFTER LAST CHECKPOINT IS SAVED"——不调 close 会泄漏(默认 stager 里有线程池与缓存的存储块)。

python
resp = dcp.async_save(sd, checkpoint_id=f"/ckpt/step-{step}")
resp.staging_completion.result()      # 副本就绪,可继续训练
# ... 训练若干步后,在健康检查点或退出前:
resp.upload_completion.result()       # 真正写完;失败要在这里暴露
stager.close()

async_checkpointer_type 可选 THREAD(默认)与 PROCESS。THREAD 省内存、共享页表,但 GIL 与 GDS/host 拷贝会互相影响;PROCESS 隔离更彻底,代价是一次跨进程传输与额外内存。

7. 异步保存的内存账 ​

这是最容易被低估的一段。官方对 staging 的定义是:给 AsyncStager 一次机会,创建一个"training-safe"的 state_dict 表示——staging 完成之后对模块数据的任何更新都不应反映到这份 state_dict 上;默认实现就是在 CPU 内存上做一份完整拷贝。

于是开销是明确的:

  • host 内存要预留至少一份完整 checkpoint 的大小(模型 + 优化器状态,按保存精度算);
  • 开了 use_pinned_memory=True(默认)更快但吃更多内存,官方在 StagingOptions 里写得很清楚;
  • use_shared_memory=True 默认开启,供多进程共享同一份 staged 数据(PROCESS 模式才真正用得上);
  • DefaultStager 不是线程安全的——每线程一个实例,或外部加锁。

StagingOptions 四个开关的默认值可直接查:use_pinned_memory=True、use_shared_memory=True、use_async_staging=True、use_non_blocking_copy=True;官方同时注明,CUDA 相关特性在没有 CUDA 时会抛异常——所以在纯 CPU 调试环境里,要么关掉这些开关,要么准备好接异常。

算一笔账:70B 模型(bf16 权重约 140 GB)+ Adam 两阶状态(按 fp32 约 560 GB)的完整 checkpoint 是数百 GB 级,单机 host 内存根本放不下这份拷贝。这就是为什么大模型上 async_save 要么配 PROCESS + 共享内存 + 分块策略,要么干脆退回同步保存但把保存时间挤进 checkpoint 间隔——先算 host 内存,再决定异步,顺序不能反。

8. 重分片:能力边界与三条实操 ​

官方的能力声明只有一句:DCP 处理加载时的重分片,使得"在一个集群拓扑下保存、在另一个拓扑下加载"成为可能。这句话成立的前提是第 4 节的 canonical FQN——保存下来的元数据记录的是"逻辑张量的全局形状与切片",而不是"rank 3 的第 2 个文件"。恢复时每个 rank 只读自己需要的切片(官方:"each rank will try to read the least amount of data necessary")。

三条实操:

  1. 保存端一律用 get_state_dict,不要手写 model.state_dict()——拓扑无关性的来源就在这里;
  2. 加载端先按新拓扑建模型、to(device),再 dcp.load——因为原地语义,顺序反了就是往一张空表里写;
  3. allow_partial_load 默认 False,官方语义是"state_dict 里有、checkpoint 里没有的键 → 直接报运行时错误"。做 LoRA 与全参互转、或新增了 head 时,显式打开它并同时打印缺失键清单,否则你会得到一个"能跑但某些层是随机初始化"的模型——这是最贵的一类静默失败。

另外两个格式互转工具值得记住:dcp_to_torch_save 与 torch_save_to_dcp,官方都带同一条警告——为避免 OOM,建议只在单个 rank 上运行。以及从 torch.save 直接在线加载并重分片的能力:BroadcastingTorchSaveReader + DynamicMetaLoadPlanner,做法是协调者读全量、再广播并切分,官方明确说明这样"避免每个 rank 都加载整份 checkpoint,从而降低 OOM 风险",代价是一次广播通信。

9. 生产落地的四条硬规矩 ​

  1. 按 step 分目录,绝不复用路径:/ckpt/step-1000/、/ckpt/step-2000/,配合 overwrite=False。这样"半成品"永远进不了好 checkpoint 的目录。
  2. 保存成功的判据是 .metadata 存在 + upload_completion 返回,不是"目录里有文件"。文件目录可以先建出来再慢慢写,这是 DCP 的写入序列决定的。
  3. 保存后抽样验证:起一个小规模进程组(比如 1/8 规模),用同一套 get_state_dict + dcp.load 加 allow_partial_load=False 走一遍。键缺失会在这里立刻暴露,而不是在三天后的续训里。
  4. 与存储侧对齐两件事:一次 checkpoint 的文件数与总字节数。前者决定元数据服务压力(见 容量与配额运营 的 inode 双水位),后者决定条带与带宽(见 Lustre 客户端调优)。single_file_per_rank=True 是让这两个数字都变好看的第一选择。

10. 五个坑 ​

  1. 以为 async_save 连拷贝也异步:它先做 staging(GPU→CPU 全量拷贝)再异步写盘;显存/内存峰值发生在调用当下,不是后台。
  2. 把 staging_completion 当保存成功:那只是"副本就绪",upload_completion 才是写完;只等前者会在掉电/盘满时丢掉整次保存。
  3. 忘了在根模块调 load_state_dict:dcp.load 只往 state_dict 里写,非张量与后处理不会自动传播。
  4. 手写 model.state_dict() 而不是 get_state_dict:优化器的参数 ID 与并行后的 FQN 会让重分片直接失效,换拓扑就加载不了。
  5. 不调 close():官方明确要求"最后一份 checkpoint 保存后必须 close",否则线程池与缓存存储块泄漏,长跑作业会慢慢吃掉 host 内存。

相关文章 ​

AI-HPC 智算超算专家 · Contact: openaihpc@gmail.com