FSDP2 实战:fully_shard 契约、显存账与 torch.compile 组合
摘要:FSDP2 不是"FSDP1 换了个名字"。它把 FlatParameter 换成了逐参数的 dim-0 DTensor 分片,这个改动带来一串连锁后果:state_dict 不再需要 all-gather、冻结参数的限制放松、内存管理不再需要
record_stream与limit_all_gathers。与此同时,fully_shard有六条必须遵守的使用契约,任何一条破了都不会报错,只会让吞吐悄悄掉下去。本文把这些契约、显存账与torch.compile的组合方式一次讲清,并给出可以照着跑的验收口径。
1. FSDP1 的经验为什么在 FSDP2 上失灵
官方文档对 FSDP2 的定义很直接:使用**逐参数分片(per-parameter sharding)**的 DTensor 表示,在 eager 模式下追求性能,同时改善可用性。它和 FSDP1 的差异集中在三处:
- 分片表示:FSDP2 把每个参数沿 dim-0 切开(
torch.chunk(dim=0)),而 FSDP1 是把一组张量拼平、拼接、再切分(FlatParameter)。后果是"哪张卡上有什么数据"变得可推理,切到别的并行方式也简单; - state_dict:FSDP2 不做全量 state dict,分片 state dict 本身就是 DTensor,免通信;FSDP1 要拿全量就必须 all-gather。要用全量就自己
DTensor.full_tensor(),或者走分布式 checkpoint 的 state dict API; - 内存管理:FSDP2 用不同的多流内存管理方式,不需要
torch.Tensor.record_stream,也不需要像 FSDP1 那样用limit_all_gathers=True去阻塞 CPU 来换取确定性。
另外两条实际影响:冻结参数的约束放松了(逐参数分片不必为"冻结参数如何塞进 FlatParameter"发愁);fully_shard 暴露了手动控制预取与集合通信调度的 API,给愿意调的人留了空间。
所以从 FSDP1 迁移过来时,第一条要放弃的旧习惯就是"用 limit_all_gathers 压显存抖动"——在 FSDP2 上它是无效的,显存要按下面的 reshard_after_forward 与预取深度来算。
2. fully_shard 的六条契约
签名(官方原文):
torch.distributed.fsdp.fully_shard(
*module*, *,
mesh=None,
reshard_after_forward=None,
shard_placement_fn=None,
mp_policy=MixedPrecisionPolicy(param_dtype=None, reduce_dtype=None,
output_dtype=None, cast_forward_inputs=True),
offload_policy=OffloadPolicy(),
ignored_params=None,
)六条契约,每条都是"不遵守不报错、只掉性能"的类型:
- 参数被原地改成 DTensor。初始化时
model.parameters()从普通torch.Tensor原地变成 DTensor,并按 device mesh 搬到对应设备。所以优化器必须用 DTensor 参数初始化,step 也在 DTensor 上做;如果你先建优化器再fully_shard,优化器里握着的还是旧张量。 - 前向/反向靠 hook 做 all-gather 与释放。pre-forward hook 把参数 all-gather 成普通张量,post-forward hook 释放(无需通信),post-backward hook 释放参数并 reduce-scatter 梯度。
- 必须
model(input)而不是model.forward(input)。只有走__call__才会触发 pre-forward hook。确实要直接调forward,就得显式model.unshard(),或者用register_fsdp_forward_method(model, "forward")把该方法注册成被 hook 的前向。 - 必须自底向上调用。
fully_shard把module.parameters()里"尚未被更早调用分到组"的参数收进一个组;对根模块调用时,它会把各层的参数排除掉,只把剩下的(embedding、输出投影)收成一组。只对根模块调用等于放弃逐层重叠。 - 类型被原地"并集"成 FSDPModule。
nn.Linear会变成FSDPLinear,既是nn.Linear也是FSDPModule,因此能拿到reshard()、unshard()这些方法——注意这两个方法都不递归。 - FQN 不变。
fully_shard不包一层新模块,只挂 hook,所以model.state_dict()的 key 前后一致。这条是 checkpoint 能无缝对接的前提。
3. 分组粒度决定通信能否重叠
一个组对应一次 all-gather、一次 reduce-scatter。官方明确说:把模型分成多个组("逐层")才能拿到峰值显存收益与通信/计算重叠,一般不应该只对最顶层根模块调用。
工程含义是:层数就是重叠的机会数,也是预取调度的粒度。太粗(比如按 4 层一组)单次 all-gather 更大、更难和计算重叠;太细(每层都拆成多个组)集合通信次数变多、每次消息更小,容易被启动开销吃掉。Transformer 上"一个 block 一组"是起点,然后按实测调。
4. reshard_after_forward 的三档
| 取值 | 前向之后 | 反向 | 适用 |
|---|---|---|---|
True | 释放未分片参数 | 重新 all-gather | 非根模块的默认 |
False | 保留未分片参数 | 省掉一次 all-gather | 根模块的默认(反向紧接着就要用) |
None(默认) | 非根 True、根 False | 同上 | 不动它就行 |
int | reshard 到更小的 world size | 在更小 world size 上 all-gather | 想用显存换通信 |
几个容易踩的点:
int必须是 mesh 分片维度的非平凡因数(不含 1 和维度本身);常见选择是节点内规模(比如单机卡数)。它让反向 all-gather 只用节点内通信,代价是显存占用高于True;- 前向与反向之间如果要改参数,注册到模块上的必须是分片参数。取
False或int时,得手动调reshard(); - 训练/评估切换可以运行时改:
set_reshard_after_forward(False)跑评估、再set_reshard_after_forward(True)回训练,比重建模型省事。
5. 混合精度:三个 dtype 各管一段
MixedPrecisionPolicy(param_dtype, reduce_dtype, output_dtype, cast_forward_inputs) 是模块级(不是算子级)的混合精度,官方给了明确的分工:
param_dtype:未分片参数的 dtype,也就是前向/反向计算与 all-gather 的 dtype。为None时用原始 dtype;优化器 step 始终用原始 dtype 的分片参数;reduce_dtype:梯度归约(reduce-scatter 或 all-reduce)的 dtype。为None但param_dtype非None时,归约跟随计算 dtype。这正是"低精度算、全精度归约"的入口:param_dtype=bf16, reduce_dtype=fp32;output_dtype:前向浮点输出的 cast 目标,用于不同模块用不同精度策略的拼接;cast_forward_inputs:是否把前向的浮点输入 cast 到param_dtype。
官方还点明一个省显存的理由:FSDP 本来就把高精度分片参数留在内存里,所以模块级混合精度不需要额外的高精度参数副本给优化器用。这和"用 autocast 再加一份 fp32 主权重"是两条不同的路。
有个细节别忽略:reduce_dtype 在关掉梯度同步时会影响累积语义——官方原文是"如果同时通过 set_requires_gradient_sync() 关掉梯度归约,FSDP 会用 reduce_dtype 累积梯度"。做梯度累积又做低精度归约时,这里要想清楚数值链路。
6. 梯度累积与反向的两把旋钮
FSDP1 的 no_sync() 在 FSDP2 上对应 set_requires_gradient_sync(False)(官方明确写了"等价于 FSDP1 的 no_sync"),它是抑制通信做梯度累积的标准手段:微批内不归约,最后一个微批再同步。
配套的两个:
set_reshard_after_backward(False):反向之后不 reshard,用显存换"下一次前向不必重新 all-gather"。梯度累积窗口里特别有用,但窗口越长显存越紧;set_is_last_backward(True):告诉 FSDP 下一次反传是最后一次,它会等待未完成的梯度归约并清理反向预取的数据结构。做微批(microbatch)切分时必须用,否则预取状态会跨微批残留。
7. 通信优化:预取、共享流与零拷贝
- 预取深度:
set_modules_to_forward_prefetch(list)/set_modules_to_backward_prefetch(list)。传单元素列表(相邻那个模块)等价于默认重叠行为;长度 ≥2 才更激进,代价是预留更多显存。这是"想再压一点通信停顿"时第一个该试的旋钮。 - 共享通信流:
share_comm_ctx([...])让多个 FSDPModule 共用 CUDA 流。官方给的场景是流水并行——每个 model chunk 都是 FSDP 根,共享流能避免跨流内存碎片。 - 零拷贝集合通信:
set_allocate_memory_from_process_group_for_comm(True)让通信的临时缓冲用 ProcessGroup 自带分配器,NCCL 下可借 SHARP 走 NVLink/IB 零拷贝。两个硬约束:不能与set_custom_all_gather()/set_custom_reduce_scatter()同时用(这两者允许更细粒度控制,该方法无法判断它们的缓冲策略);且它依赖"只用 sum 型归约",所以需要配合set_force_sum_reduction_for_comms(True)——官方说明是 NCCL 目前只对这种集合通信支持零拷贝。 set_unshard_in_backward(False):用于明确知道该组参数反向不需要的场景(例如 embedding),省掉一次反向 all-gather。
8. CPU offload 的真实代价
CPUOffloadPolicy(pin_memory=True) 会把参数、梯度、优化器状态都卸载到 CPU:分片参数在 all-gather 前 H2D 拷贝,未分片参数按 reshard_after_forward 释放,分片梯度在反向 D2H,优化器 step 在 CPU 上跑。
代价写清楚:pin memory 能提高拷贝效率并与计算重叠,但被 pin 住的内存不能被其他进程使用;CPU 内存不够时把 pin_memory=False,代价是拷贝变慢、重叠变差。另有一层现实约束:优化器在 CPU 上跑,step 时间会明显变长,端到端收益要在"省下的显存"和"多出来的 step 时间"之间算,而不是只看峰值显存。
9. 与 torch.compile 组合
torch.compile 的官方签名与默认值:fullgraph=False、dynamic=None、backend='inductor'、mode 默认 "default"。几个直接影响 FSDP2 组合的点:
fullgraph=False(默认):会在函数内寻找可编译区域,允许 graph break;设True则要求整个函数进单图,有 break 直接报错。FSDP2 的 hook、集合通信、DTensor 重分发都容易产生 break,所以起步一律用默认的False,先看它编译出了什么,再考虑收紧。- 重编译上限:同一个 frame 最多关联
torch._dynamo.config.recompile_limit个编译结果,默认 8,到顶就回落 eager。guard 失配时会有多次编译,用TORCH_LOGS=guards查。FSDP2 的参数在 DTensor 与普通张量之间来回切换,是 guard 失配的常见来源,所以"编译了但没变快"要先看重编译次数,而不是先怀疑 kernel。 dynamic=None(默认):先特化,检测到动态性后在重编译时生成更动态的 kernel。变长序列的 batch 会让它反复重编译,用TORCH_LOGS=dynamic查过度特化。要稳定就显式dynamic=True(官方提示:某些算子/优化仍会强制特化)。mode="reduce-overhead":用 CUDA graphs 压 Python 开销,但会缓存调用所需的工作区内存,显存占用更高,且只对"不修改输入"的 CUDA 图生效。FSDP2 本身已经在吃显存,这个 mode 要单独做显存核算;max-autotune在 GPU 上默认也开 CUDA graphs,同样要算。torch.nn.Module.compile():可以原地编译模块、不改变结构——这对"已经fully_shard过的模块"是有意义的入口。
落地顺序建议(每步都可回退):
- 先跑通不编译的基线:
fully_shard逐层分组,记录 step time 与峰值显存; - 按块编译,不整模型编译:以 Transformer block 为单位编译,编译区域小、编译时间短、图更容易纯;整模型编译的编译时长与重编译风险都更高;
- 从默认参数开始:
fullgraph=False、mode="default",先拿到TORCH_LOGS=guards与TORCH_LOGS=dynamic的输出,确认重编译次数是否收敛; - 再试
reduce-overhead:只有在前一步显存还有余量时才试,并单独记录峰值显存变化; - 验收三个数:step time(中位数而非均值)、峰值显存、单位时间重编译次数。三者只要有一个退化,就说明这次编译的位置或参数选错了。
诚实提示:torch.compile 与 FSDP2 的交互细节随版本变化很快(hook 捕获范围、DTensor 分解、CUDA graphs 支持面都会变)。所以结论必须来自你自己版本上的 TORCH_LOGS 输出与实测,不要照抄任何一篇博客的参数组合。
10. 一页检查表与五个坑
上线前检查表
- [ ] 优化器在
fully_shard之后建,参数确实是 DTensor - [ ] 前向走
model(x),没有直接model.forward(x) - [ ]
fully_shard是自底向上逐层调用,不是只调根模块 - [ ] 梯度累积用
set_requires_gradient_sync(False),最后一个微批恢复True - [ ] 有微批切分时调用了
set_is_last_backward(True) - [ ]
reshard_after_forward的int取值是 mesh 分片维度的非平凡因数 - [ ] 混合精度用
MixedPrecisionPolicy,没有同时叠一层 autocast 造成双重 cast - [ ] checkpoint 用分片 state dict(DTensor)保存,需要全量时才
full_tensor() - [ ] 开编译后记录了重编译次数与峰值显存
五个坑
- 只对根模块
fully_shard:能跑,但失去逐层重叠,峰值显存也下不来。 - 先建优化器再
fully_shard:优化器握着被替换掉的旧张量,更新不生效且不报错。 - 用
model.forward(x)图省事:hook 不触发,参数没被 all-gather,前向直接算错。 - 拿 FSDP1 的
limit_all_gathers经验调 FSDP2:FSDP2 的内存管理路径不同,这个旋钮不存在对应收益。 - 编译后只看吞吐不看重编译:
recompile_limit到 8 就回落 eager,看着"编译成功",实际大半在跑 eager。
一句话收束:FSDP2 的正确性靠契约(谁先建、怎么调、什么顺序),性能靠三个可测量的旋钮(分组粒度、reshard 档位、预取深度),torch.compile 只能在契约正确的前提下加乘,不能救契约错误。