AI-Research-SKILLs 实战指南:PyTorch FSDP2 `fully_shard` API 完整解读与分布式训练落地

原创2026-09-22 18:09:181,877 阅读
文章标签:人工智能AI 技能AI 插件大模型机器学习深度学习

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 参数

八、本文证据出处与延伸阅读

本文所有事实均来自仓库内文档,可进一步查阅:

如需在真实代码中快速上手,仓库技能 SKILL.md 建议保持"init_distributed → build_model_meta → build_optimizer → train_step → checkpoint_save/load"的五段式脚本结构,并优先从官方示例中复制检查点模式,而不是自造保存逻辑。对于超大规模 LLM 训练中的生产化配置与 FSDP 选择经验,还可参考仓库收录的 torchtitan_fsdp_notes.md(语义以官方 API 文档为准)。

登录后查看全文
AI-Research-SKILLs