Megatron FSDP 配置与性能指南
帮助在 Megatron-Bridge 中启用、排查并验证 Megatron FSDP。
内容仅指导配置和运行分布式训练，未见恶意行为、凭据处理、隐蔽外传或破坏性默认操作；配置范围和检查点路径基本透明，并提供验证命令。扣分原因是没有明确的用户确认、权限隔离、敏感数据处理、回滚/恢复流程，且训练与检查点写入可能产生较大外部资源影响。
配置项、互斥条件、代码锚点、已知陷阱和2-GPU烟测路径相互一致，异常限制也有一定说明。扣分原因是依赖版本、环境前置条件、失败诊断和边界输入不完整；静态审查无法确认命令可复现，因此不超过10分。
目标用户、FSDP启用场景、OOM/回归排查场景和触发词明确，并说明FSDP2、TP/PP/CP及CPU offload等限制。扣分原因是未明确非适用范围、输入输出契约和环境矩阵，也没有中文使用支持说明；不过核心流程不完全依赖海外服务，因此未作网络可达性额外扣分。
SKILL.md结构清楚，包含启用示例、代码锚点、陷阱和验证；许可证、NVIDIA所有者、版本/验证日期和后续验证项可从附属文件获知。扣分原因是缺少Instructions和Examples推荐章节，缺少安装/依赖说明、作者和tags元数据、完整变更记录及明确维护更新流程；仓库级维护信号不能完全替代技能级治理信息。
示例直接给出关键配置、检查点格式、性能入口和验证标准，能够覆盖评测任务的核心需求；附属评测报告也显示正向任务存在较好的正确性和有效性。扣分原因是只有一个评测任务，性能收益仍标为doc_only，且实际适配不同并行组合仍需用户自行验证，因此静态评分不超过7分。
存在具体源码路径、配置锚点、功能测试路径、card.yaml证据清单以及评测报告，关键主张具备一定审计线索。扣分原因是提供材料未包含可独立复核的测试日志或完整CI覆盖，card中的live validation属于报告性陈述，性能主张明确为文档级证据，因此不超过5分。
- 启用保存或加载时必须确认检查点格式为fsdp_dtensor，并先验证目标分支与当前配置约束。
- 不要同时启用Megatron FSDP和Torch FSDP2；use_tp_pp_dp_mapping及部分TP/PP/CP/EP组合需要单独验证。
- 烟测命令依赖2张CUDA GPU、uv、PyTorch分布式环境和项目测试依赖；本评估未执行该命令。
- 性能收益没有可复核的基准数据，不能仅凭该技能推断实际加速或显存收益。
这个 Skill 能做什么，适合哪些场景？
该技能面向在 Megatron-Bridge 中使用 Megatron FSDP 数据并行的开发者。它给出必要的配置覆盖项、代码定位点、性能测试入口、常见陷阱和两 GPU 功能验证命令。内容特别关注检查点格式、FSDP 与 FSDP2 的互斥关系，以及可能导致 OOM 或性能回归的配置变化。它适合需要从 DDP 切换到 FSDP，或调查 FSDP 配置问题的场景。
指导用户设置 use_megatron_fsdp、data_parallel_sharding_strategy、average_in_collective 和 fsdp_dtensor 等配置；提供示例 recipe fixup 和性能 harness 命令；指出配置定义、验证逻辑、运行时数据并行包装器选择及性能覆盖项所在的代码位置；列出 CPU offloading、TP/CP 与 CUDA_DEVICE_MAX_CONNECTIONS 相关限制；提供两 GPU pytest 冒烟测试，并以测试通过、末次迭代 loss 有限且无检查点格式断言作为成功标准。
- 需要把 Megatron-Bridge 训练从 DDP 切换到 Megatron FSDP 的工程师。
- 启用 FSDP 后遇到 OOM、训练回归或检查点加载问题的开发者。
- 需要确认 fsdp_dtensor 检查点配置是否正确的训练维护者。
- 需要定位 Megatron-Bridge FSDP 配置定义、验证逻辑或运行时包装器的代码审查者。
- 需要用两张 GPU 运行基础 FSDP 训练冒烟测试的工程师。
这个 Skill 有哪些优点和局限？
- 提供可复制的最小配置和 recipe 示例。
- 同时覆盖配置、运行时选择、性能 harness、陷阱和验证标准。
- 明确指出 Megatron FSDP 只能使用 fsdp_dtensor 检查点格式。
- 提供现成的两 GPU功能冒烟测试命令。
- 内容聚焦 Megatron-Bridge 的 Megatron FSDP，不是通用 FSDP 教程。
- 未提供安装 Megatron-Bridge、CUDA 或 GPU 环境的完整步骤。
- 未说明经过验证的 GPU 型号、软件版本或完整平台矩阵。
- FSDP2 在所述分支可能在训练前因 pg_collection 参数失败；该技能不提供修复实现。
如何安装这个 Skill？
使用 NVIDIA/skills 仓库提供的 skills CLI 安装指定技能：
npx skills add nvidia/skills --skill nemo-mbridge-perf-megatron-fsdp --yes
README 未说明该命令的具体安装目录；CLI 会处理技能选择和安装目标。技能目录应包含 SKILL.md，并在智能体重新加载技能后可用。
如何使用这个 Skill？
向智能体提出与 Megatron FSDP 相关的请求，例如：“在 Megatron-Bridge 中启用 Megatron FSDP，并检查检查点格式和验证测试。”也可以使用触发词 use_megatron_fsdp、data_parallel_sharding_strategy、sharded data parallel 或 Megatron FSDP。指南建议设置 cfg.dist.use_megatron_fsdp 和 cfg.ddp.use_megatron_fsdp 为 true，将 data_parallel_sharding_strategy 设为 optim_grads_params，将 average_in_collective 设为 false，并将 checkpoint.ckpt_format 设为 fsdp_dtensor。验证命令为：
CUDA_VISIBLE_DEVICES=0,1 uv run python -m torch.distributed.run --nproc_per_node=2 -m pytest tests/functional_tests/training/test_megatron_fsdp.py::TestMegatronFSDP::test_fsdp_pretrain_basic -v -s
这个 Skill 与同类方案有什么区别？
指南明确将 Megatron FSDP 与 DDP、torch FSDP2 进行区分：运行时会在三者之间选择不同的数据并行包装器；Megatron FSDP 与 FSDP2 互斥，且 FSDP2 当前不适用于流水线并行。它没有提供性能基准来证明某一方案普遍优于其他方案。