SuperAPI AI 工具集

pytorch-fsdp2

编程与开发

查看项目

更新于 10-21 16:19

技能介绍

用途

该技能面向编码智能体,教它如何把 PyTorch FSDP2(fully_shard)正确加入训练循环,包括初始化、分片、混合精度/offload 配置以及检查点处理。FSDP2 主要通过 torch.distributed.fsdp.fully_shard 以及它就地添加到模块上的 FSDPModule 方法暴露。

何时使用

适合以下情况:

  • 模型无法放入单张 GPU(参数 + 梯度 + 优化器状态)。
  • 希望采用 eager 模式、基于 DTensor 的逐参数分片,相比 FSDP1 更易检查、分片 state dict 更简单。
  • 之后可能用 DeviceMesh 将数据并行与张量并行组合。

需要谨慎或避免的情况:

  • 需要跨 PyTorch 版本严格向后兼容的检查点(DCP 对此有警告)。
  • 被迫使用没有 FSDP2 栈的旧版 PyTorch。

替代方案:DistributedDataParallel(DDP)用于经典数据并行;FullyShardedDataParallel(FSDP1)用于原始参数分片。

智能体必须遵守的约定

  • 使用 torchrun 启动,并为每个进程设置 CUDA 设备(通常通过 LOCAL_RANK)。
  • 自底向上应用 fully_shard(),即先分片子模块(如 Transformer 块),再分片根模块。
  • 调用 model(input) 而不是 model.forward(input),以便 FSDP2 钩子运行(除非显式 unshard() 或注册 forward 方法)。
  • 在分片之后创建优化器,并确保它建立在 DTensor 参数(post-fully_shard)之上。
  • 使用分布式检查点(DCP)或分布式 state dict 辅助函数保存检查点,不要用朴素的 torch.save(model.state_dict()),除非有意收集为完整张量。

使用方式(分步流程)

0)版本与环境检查:优先使用近期稳定版 PyTorch;使用 torchrun --nproc_per_node <gpus_per_node> ... 并确保 RANK、WORLD_SIZE、LOCAL_RANK 可见。

1)初始化分布式并设置设备:

dist.init_process_group(backend="nccl")
torch.cuda.set_device(int(os.environ["LOCAL_RANK"]))

可选创建 DeviceMesh 描述数据并行组。

2)在 meta 设备上构建模型(推荐用于超大模型):

with torch.device("meta"): model = ...
# 对子模块应用 fully_shard(...),然后 fully_shard(model)
model.to_empty(device="cuda")
model.reset_parameters()  # 或你的初始化流程

3)自底向上应用 fully_shard():不要只对最顶层模块调用。对 transformer 类模型的推荐模式是遍历模块,若 isinstance(m, TransformerBlock) 则 fully_shard(m, ...),最后 fully_shard(model, ...)。原因:fully_shard 会为集合通信效率形成“参数组”,并排除已被先前调用分组的参数;自底向上能获得更好的重叠与更低的峰值内存。

4)配置 reshard_after_forward 以权衡内存/性能:默认 None 表示非根模块为 True、根模块为 False(良好默认)。内存受限时保持默认或对许多块强制 True;吞吐受限且内存允许时可让参数更久保持未分片(根模块常为 False)。高级用法:使用整数在 forward 后重新分片到更小的 mesh(如节点内),前提是它是有效的除数。

5)混合精度与 offload(可选但常见):FSDP2 使用 mp_policy=MixedPrecisionPolicy(param_dtype=..., reduce_dtype=..., output_dtype=..., cast_forward_inputs=...) 以及 offload_policy=CPUOffloadPolicy() 实现 CPU offload。经验法则:在 H100/A100 级 GPU 上从 BF16 参数/归约开始(若模型数值稳定);保持 reduce_dtype 与梯度归约预期一致;使用 CPU offload 时需为 PCIe/NVLink 流量与运行时开销做预算。

6)优化器、梯度裁剪、累积:在分片后创建优化器以持有 DTensor 参数。若需梯度累积/no_sync,使用 FSDP2 的 set_requires_gradient_sync 机制而非 FSDP1 的 no_sync()。梯度裁剪使用 FSDP2 教程中展示的方法(因为参数/梯度是 DTensor)。

7)检查点:优先 DCP 或分布式 state dict 辅助函数。

  • A)分布式检查点(DCP)——最佳默认:从多个 rank 并行保存/加载,支持加载时重新分片;产生多个文件(通常每 rank 至少一个),就地操作。
  • B)分布式 state dict 辅助函数: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。 避免:用普通 torch.save 保存 DTensor state dict,除非有意用 DTensor.full_tensor() 转换并小心管理内存。

工作流清单

工作流 A:将 FSDP2 改造进现有训练脚本

  • 用 torchrun 启动并初始化进程组。
  • 从 LOCAL_RANK 设置 CUDA 设备;如需多维并行则创建 DeviceMesh。
  • 构建模型(必要时用 meta),自底向上应用 fully_shard,然后 fully_shard(model)。
  • 在分片后创建优化器以捕获 DTensor 参数。
  • 使用 model(inputs) 使钩子运行;用 set_requires_gradient_sync 做累积。
  • 通过 torch.distributed.checkpoint 辅助函数添加 DCP 保存/加载。

工作流 B:添加 DCP 保存/加载(最小模式)

  • 将状态包装为 Stateful 或通过 get_state_dict 组装状态。
  • 从所有 rank 调用 dcp.save(...) 到共享路径。
  • 调用 dcp.load(...) 并用 set_state_dict 恢复。
  • 加载到不同 mesh 时验证任何重新分片假设。

调试清单

  • 所有 rank 是否在不同 GPU 上?若不是,检查 torch.cuda.set_device(LOCAL_RANK) 与 torchrun 参数。
  • 是否误直接调用 forward()?应使用 model(input) 或显式 unshard()/注册 forward。
  • fully_shard() 是否自底向上应用?若只分片根模块,内存/性能更差且可能造成困惑。
  • 优化器创建时机是否正确?必须在分片后基于 DTensor 参数构建。
  • 检查点路径是否一致?若用 DCP,不要与临时 torch.save 混用,除非理解转换。注意 DCP 的 PyTorch 版本兼容性警告。

常见问题与修复

  • 前向钩子未运行 → 调用 model(inputs)(或显式 unshard())而非 model.forward(...)。
  • 优化器看到非 DTensor 参数 → 在所有 fully_shard 调用之后创建优化器。
  • 只有根模块被分片 → 在根之前对子模块自底向上应用 fully_shard。
  • 前向后内存尖峰 → 对更多模块设置 reshard_after_forward=True。
  • 梯度累积失步 → 使用 set_requires_gradient_sync 而非 FSDP1 的 no_sync()。

最小参考实现大纲

编码智能体应实现包含以下标记块的脚本:init_distributed()(初始化进程组、设置设备);build_model_meta()(meta 上建模型、应用 fully_shard、物化权重);build_optimizer()(分片后创建优化器);train_step()(用 model(inputs) 与 DTensor 感知模式做前向/反向/步进);checkpoint_save/load()(DCP 或分布式 state dict 辅助函数)。具体示例见参考文件与官方教程。

限制

资料未提供该技能的具体收费、价格、平台支持范围或效果数据。跨 PyTorch 版本检查点兼容性存在限制(DCP 有相关警告)。使用 CPU offload 会带来 PCIe/NVLink 流量与运行时开销。