用途
该技能面向编码智能体,教它如何把 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 流量与运行时开销。