AI-Research-SKILLs 实战指南:PyTorch FSDP2 `fully_shard` API 完整解读与分布式训练落地
AI-Research-SKILLs 实战指南:PyTorch FSDP2 fully_shard API 完整解读与分布式训练落地
导读
本文以 AI-Research-SKILLs 仓库中 08-distributed-training/pytorch-fsdp2 技能包的核心参考文档(pytorch_fully_shard_api.md)为骨架,系统解读 PyTorch FSDP2 的统一入口 torch.distributed.fsdp.fully_shard:从函数签名、核心参数语义,到 DTensor 参数契约、自底向上的切分顺序、混合精度与 CPU offload 策略,再到与 DeviceMesh、分布式检查点(DCP)的组合方式。读完本文,你将掌握为任意单卡训练脚本接入 FSDP2 的正确姿势——包括初始化流程、钩子触发条件、优化器构建时机等最容易踩坑的关键点,并能直接在多卡环境下落地一套可运行的分布式训练与检查点方案。
一、fully_shard 是什么:FSDP2 的统一入口
FSDP2(Fully Sharded Data Parallel 第二代)在 PyTorch 中的主要暴露方式是 torch.distributed.fsdp.fully_shard。与 FSDP1 的 FullyShardedDataParallel 包装器风格不同,FSDP2 提供的是一个以模块为单位的原地(in-place)切分 API,并配套引入 FSDPModule 与 DTensor 体系。
从 pytorch_fully_shard_api.md 整理的 API 文档要点来看,fully_shard 的核心行为包括:
- 在初始化阶段将
model.parameters()转换为 DTensor(分布式张量); - 在 forward/backward 之前自动挂接 all-gather 钩子,将切分参数聚合回完整形态用于计算;
- 在 forward/backward 之后自动执行 free/reshard,释放临时聚合出的完整参数,从而让"参数 + 梯度 + 优化器状态"都以分片形态驻留显存。
这正是 FSDP 系列区别于 DDP 的本质:pytorch_fsdp2_tutorial.md 中明确对比了三种并行方案的差异——DDP 只复制梯度并做 all-reduce,而 FSDP 连参数、梯度和优化器状态一并切分;FSDP2 相比 FSDP1 的改进在于采用 DTensor 按参数切分(per-parameter sharding),参数状态字典更直接、内存行为更确定,并且为自定义 all-gather(如 float8/NF4 场景)预留了扩展点。
在仓库的技能定义(SKILL.md)中,这一技能的使用场景被明确为:模型(参数 + 梯度 + 优化器状态)无法放入单张 GPU、希望使用基于 DTensor 的急切模式切分、以及未来需要与 Tensor Parallel 通过 DeviceMesh 组合训练时。
1.1 函数签名与核心参数
fully_shard(module, *,
mesh=None,
reshard_after_forward=None,
shard_placement_fn=None,
mp_policy=MixedPrecisionPolicy(...),
offload_policy=OffloadPolicy(),
ignored_params=None)
各参数语义(继承自 API 参考文档):
| 参数 | 类型 | 语义与取值 |
|---|---|---|
mesh |
DeviceMesh |
描述切分拓扑。1D mesh 对应"经典"FSDP 切分,placement 为 (Shard(0),);2D mesh 对应混合切分(HSDP),在一个维度上切分、另一个维度上复制,placement 为 (Replicate(), Shard(0)) |
reshard_after_forward |
bool / int / None |
控制 forward 之后是否释放非切分参数。True 表示 forward 后释放、backward 时重新 all-gather;False 表示 forward 后保留(省去 backward 的 all-gather);None 为默认策略:非根模块为 True、根模块为 False;传入 int 则允许 forward 后重切分到更小的 world size(要求该值能整除切分维大小) |
shard_placement_fn |
callable | 按参数覆盖默认的切分维度;若非 0 维切分,需要保证均匀切分 |
mp_policy |
MixedPrecisionPolicy |
混合精度策略,见第三节 |
offload_policy |
OffloadPolicy |
卸载策略,见第三节 |
ignored_params |
参数集合 | 这些参数不切分、不迁移、不参与梯度归约 |
关于 mesh 的深入背景:DeviceMesh 是管理 ProcessGroup 的高层抽象,pytorch_device_mesh_tutorial.md 指出,没有 DeviceMesh 时用户需要手工计算各 rank 的复制/切分分组并创建多个进程组;而 FSDP2 直接接受 DeviceMesh 作为 mesh 参数,使 1D 全切分与 2D 混合切分只需改变 mesh 形状即可表达。官方推荐在 init_process_group 与设置 CUDA 设备之后尽早创建 DeviceMesh,以便与 TP 等其他并行维度组合。
二、必须遵守的"用户契约":五个关键约束
API 文档原文特别强调了一组用户契约(user contract),它们直接决定了训练脚本能否正确运行,也在 SKILL.md 中被列为 Agent 必须遵守的规则:
2.1 优化器必须基于 DTensor 参数构建
fully_shard(model) 会把参数原地替换为 DTensor。优化器必须在调用 fully_shard 之后创建,且 step 必须作用于 DTensor 参数上。如果优化器在切分前构建,它持有的将是普通 nn.Parameter 引用,与切分后的 DTensor 参数脱钩,梯度更新会静默失效。这是最常见的错误之一。
2.2 必须调用 model(input) 而不是 model.forward(input)
FSDP2 的 all-gather/free-reshard 逻辑依赖前向钩子。只有通过 model(input) 调用时钩子才会触发;直接调用 model.forward(input) 会绕过钩子调度,导致参数从未被聚合,数值错误甚至运行时异常。如果确实需要绕过,必须显式调用 unshard(),或者自行注册 forward 方法以便挂接钩子。
2.3 自底向上应用 fully_shard(Bottom-up)
API 文档给出了一个 ≤25 词的摘录:"Users generally should not call fully_shard() only on the topmost root module"(用户通常不应只在最顶层的根模块上调用 fully_shard())。
正确做法是:先切分子模块(如 Transformer 的各个 Block),最后再切分根模块。原因在于 fully_shard 会为已被前序调用归组过的参数建立"参数组"(parameter groups)以提升集合通信效率,自底向上的顺序能形成更高效的通信分组、获得更好的计算/通信重叠并降低峰值显存。反之,若只对根模块调用一次,所有参数将被揉进一个大的通信组,内存与性能都会明显恶化。
2.4 fully_shard 会"联合"模块类型
fully_shard 会以 FSDPModule 原地扩展(union)模块类型,使模块获得 unshard() / reshard() 等方法,便于在特殊场景下手动控制参数聚合状态。
2.5 初始化顺序的完整范式
结合 pytorch_fsdp2_tutorial.md 的迁移指南,一个大模型推荐的初始化流程是:
import torch
import torch.distributed as dist
from torch.distributed.fsdp import fully_shard
dist.init_process_group(backend="nccl")
torch.cuda.set_device(int(os.environ["LOCAL_RANK"]))
# 1) 大模型先在 meta 设备上构建,避免每卡先实例化完整权重
with torch.device("meta"):
model = build_model()
# 2) 自底向上切分:先切子模块,再切根模块
for m in model.modules():
if isinstance(m, TransformerBlock):
fully_shard(m)
fully_shard(model)
# 3) 物化权重
model.to_empty(device="cuda")
model.reset_parameters() # 或自定义初始化
# 4) 切分之后创建优化器,确保持有 DTensor 参数
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4)
这套"meta 构建 → 自底向上 fully_shard → to_empty 物化 → reset_parameters → 构建优化器"的流程正是官方教程迁移章节展示的范式,也是技能包 SKILL.md 中 Workflow A 的核心步骤。
三、混合精度与 offload 策略类
同页 API 文档还定义了三个配套策略类,它们作为 mp_policy 与 offload_policy 参数的取值。
3.1 MixedPrecisionPolicy
控制 FSDP2 内部各个阶段的张量精度:
| 字段 | 作用 |
|---|---|
param_dtype |
forward/backward 期间非切分参数使用的 dtype(即聚合计算时的精度) |
reduce_dtype |
梯度归约(reduce-scatter)时使用的 dtype |
output_dtype |
forward 输出的 dtype |
cast_forward_inputs |
是否将 forward 输入转换为 param_dtype |
SKILL.md 给出的实践规则是:在 H100/A100 级别 GPU 上优先使用 BF16 参数与归约(若模型数值上稳定);reduce_dtype 要与梯度归约预期保持一致。典型用法:
from torch.distributed.fsdp import MixedPrecisionPolicy
fully_shard(
model,
mp_policy=MixedPrecisionPolicy(
param_dtype=torch.bfloat16,
reduce_dtype=torch.bfloat16,
output_dtype=torch.bfloat16,
cast_forward_inputs=True,
),
)
3.2 OffloadPolicy 与 CPUOffloadPolicy
OffloadPolicy 控制张量驻留的设备,包括 param_device / reduce_device / output_device;CPUOffloadPolicy 在此基础上额外提供 optimizer_state_device,可将优化器状态一并卸载到 CPU。技能包提示:使用 CPU offload 时必须为 PCIe/NVLink 流量与运行时开销做好预算,它适合显存极度受限的场景,但会牺牲吞吐。
from torch.distributed.fsdp import CPUOffloadPolicy
fully_shard(model, offload_policy=CPUOffloadPolicy())
3.3 FSDP1 → FSDP2 概念映射
pytorch_fsdp2_tutorial.md 提供了官方迁移对照表,帮助旧 FSDP1 用户快速对齐:
| FSDP1 | FSDP2 |
|---|---|
sharding_strategy(如 HYBRID_SHARD) |
reshard_after_forward(+ 2D mesh 表达混合切分) |
cpu_offload |
offload_policy=CPUOffloadPolicy() |
no_sync() |
set_requires_gradient_sync |
sync_module_states |
DCP 的 broadcast_from_rank0 流程 |
其中梯度累积场景的迁移尤其值得注意:FSDP2 不再使用 FSDP1 的 no_sync() 上下文管理器,而是调用 set_requires_gradient_sync 来控制梯度同步时机。
四、reshard_after_forward 的完整语义与调优
该参数是 FSDP2 中最重要的内存/性能权衡旋钮,API 文档给出了四档取值:
True:forward 结束后立即释放聚合出的完整参数,backward 时再次 all-gather。显存占用最低,代价是 backward 阶段多一次集合通信。False:forward 后保留完整参数,省去 backward 的 all-gather。适合吞吐敏感、显存有富余的场景。None(默认):非根模块取True、根模块取False——这是官方默认的平衡策略。int:forward 后重切分到更小的 world size(要求该值整除切分维大小),例如 forward 后只在节点内(intra-node)保留聚合,属于进阶用法。
SKILL.md 的调优启发式:显存紧张时保持默认或对更多模块强制 True;吞吐优先且显存可负担时,可让参数保留更久(根模块通常就是 False)。调试清单中还有一条对应经验——"forward 后显存尖峰"通常可以通过对更多模块设置 reshard_after_forward=True 缓解。
五、与 DeviceMesh 的组合:1D 全切分与 2D 混合切分
mesh 参数决定了切分拓扑,是 FSDP2 与多维并行组合的关键接口。
- 1D mesh:
init_device_mesh("cuda", (world_size,)),对应经典 FSDP 全量切分,placement 为(Shard(0),)。 - 2D mesh:
init_device_mesh("cuda", (dp, tp)),一个维度切分、另一个维度复制(HSDP),placement 为(Replicate(), Shard(0))。
与 Tensor Parallel 组合时,pytorch_tp_tutorial.md 给出的官方推荐拓扑是:TP 运行在节点内高速互联(如 NVLink)上,FSDP 跨节点运行。具体模式为:
from torch.distributed.device_mesh import init_device_mesh
from torch.distributed.tensor.parallel import parallelize_module
mesh_2d = init_device_mesh("cuda", (dp, tp))
tp_mesh = mesh_2d["tp"]
dp_mesh = mesh_2d["dp"]
parallelize_module(model, tp_mesh, ...) # TP 只作用于 tp 维度
fully_shard(model, mesh=dp_mesh, ...) # FSDP2 只作用于 dp 维度
关键约束是:传给 fully_shard 的 mesh 只应包含数据并行维度(通常是跨节点的 dp 维),TP 维度交由 torch.distributed.tensor.parallel 管理,避免两组并行逻辑在通信组上互相踩踏。
六、检查点:DTensor 场景下不要裸用 torch.save
参数变成 DTensor 后,朴素地执行 torch.save(model.state_dict()) 会保存分片状态的张量视图,通常不是期望结果。官方与技能包推荐两条路线(详见 pytorch_dcp_overview.md、pytorch_dcp_recipe.md 与 pytorch_fsdp2_tutorial.md):
A)Distributed Checkpoint(DCP)—— 推荐默认
- 多 rank 并行保存/加载,支持加载时重新切分(不同拓扑间迁移 checkpoint);
- 每次保存产生多个文件(通常每 rank 至少一个),操作是"就地"的——模型先分配存储,DCP 再写入;
- 注意官方明确提示:DCP 不保证跨 PyTorch 版本的向后兼容;若显式传入进程组,只有组内 rank 应调用 save/load。
B)分布式状态字典辅助函数
- 模型:
get_model_state_dict/set_model_state_dict,配合StateDictOptions(full_state_dict=True, cpu_offload=True, broadcast_from_rank0=True, ...); - 优化器:
get_optimizer_state_dict/set_optimizer_state_dict; - 这两组辅助函数的完整端到端示例位于 pytorch_examples_fsdp2.md 所指向的官方
pytorch/examples脚本中。
C)DTensor 手工 API(手动路线)
- 保存:调用
DTensor.full_tensor()做 all-gather,可选在 rank 0 上 CPU-offload 以避免峰值 GPU 显存; - 加载:用
distribute_tensor(full_tensor, meta_param.device_mesh, meta_param.placements)重新分布,再配合model.load_state_dict(..., assign=True)。
另外,若检查点保存经常阻塞训练且 CPU 内存有富余,可参考 pytorch_dcp_async_recipe.md 的 torch.distributed.checkpoint.async_save,将保存移出训练关键路径——但它会先把模型状态拷贝进内部 CPU 缓冲,带来额外的内存开销。
七、落地清单与常见问题排查
综合 SKILL.md 的 Workflow A 与调试清单,一套完整的 FSDP2 接入流程为:
- [ ] 用
torchrun --nproc_per_node <gpus>启动,dist.init_process_group(backend="nccl"),并按LOCAL_RANK设置 CUDA 设备; - [ ] 需要多维并行时尽早创建
DeviceMesh; - [ ] 大模型在
meta设备构建,自底向上依次fully_shard(子模块)与fully_shard(根模块),再to_empty(device="cuda")+reset_parameters()物化; - [ ] 切分完成后再创建优化器,确保其持有 DTensor 参数;
- [ ] 用
model(inputs)触发钩子;梯度累积用set_requires_gradient_sync而非 FSDP1 的no_sync(); - [ ] 用 DCP(或分布式状态字典辅助函数)保存/加载,不要裸用
torch.save。
高频问题的根因定位(对应 SKILL.md 的"Common issues and fixes"):
| 现象 | 根因与修复 |
|---|---|
| forward 钩子不执行 | 直接调用了 model.forward(...);改为 model(inputs),或显式 unshard() / 注册 forward 方法 |
| 优化器看到非 DTensor 参数 | 优化器创建早于切分;改为在所有 fully_shard 调用之后创建 |
| 只有根模块被切分 | 未自底向上应用;先切子模块再切根模块 |
| forward 后显存尖峰 | 对更多模块设置 reshard_after_forward=True |
| 梯度累积失步 | 误用 FSDP1 的 no_sync();改用 set_requires_gradient_sync |
| 所有 rank 使用同一 GPU | 未执行 torch.cuda.set_device(LOCAL_RANK),检查 torchrun 参数 |
八、本文证据出处与延伸阅读
本文所有事实均来自仓库内文档,可进一步查阅:
- API 语义主参考:pytorch_fully_shard_api.md
- 技能使用契约与工作流:SKILL.md
- 官方教程要点与 FSDP1→FSDP2 迁移对照:pytorch_fsdp2_tutorial.md
- DeviceMesh 与 2D mesh 背景:pytorch_device_mesh_tutorial.md
- TP + FSDP 组合模式:pytorch_tp_tutorial.md
- DCP 概览、使用与异步保存:pytorch_dcp_overview.md、pytorch_dcp_recipe.md、pytorch_dcp_async_recipe.md
- 官方示例脚本指引:pytorch_examples_fsdp2.md
- 对照阅读(DDP 与 FSDP1):pytorch_ddp_notes.md、pytorch_fsdp1_api.md
如需在真实代码中快速上手,仓库技能 SKILL.md 建议保持"init_distributed → build_model_meta → build_optimizer → train_step → checkpoint_save/load"的五段式脚本结构,并优先从官方示例中复制检查点模式,而不是自造保存逻辑。对于超大规模 LLM 训练中的生产化配置与 FSDP 选择经验,还可参考仓库收录的 torchtitan_fsdp_notes.md(语义以官方 API 文档为准)。