Megatron-Bridge 通信重叠调优指南
帮助分布式训练用户配置并验证 TP、DP 与 PP 通信重叠。
技能仅提供配置建议、代码锚点和测试命令，未见恶意行为、凭据处理、隐蔽外传或破坏性默认操作；权限范围基本最小且作用域清楚。扣分原因是没有明确的用户确认、变更回滚、数据流说明或失败时的隔离策略，且执行训练配置可能带来显著资源影响。
配置示例、门控条件、陷阱和验证命令彼此基本一致，且说明了 TP overlap 被禁用的关键条件。静态审查不能执行复现；测试文件内容未随选定技能提供，异常输入、依赖缺失和失败诊断覆盖有限，因此按静态上限保守给分。
描述、when_to_use、TP/DP/PP 场景和主要非适用条件较明确，覆盖 Megatron-Bridge 性能配置用户。扣分原因是没有系统说明版本、硬件、依赖和输入输出边界，也没有中文使用指导；其核心功能不依赖海外在线服务，因此未因大陆网络可达性额外扣分。
SKILL.md 结构清晰，包含启用、代码锚点、陷阱和验证；技能卡说明 Apache 2.0、所有者、版本和已知限制，BENCHMARK.md 提供评估摘要。扣分原因是缺少推荐的 Instructions、Examples、author/tags 元数据，安装依赖、变更日志、维护责任和更新路径不完整。
示例直接覆盖目标配置，并给出测试验证路径；提供的基准报告显示正向任务表现良好。静态审查无法确认报告或代表性输出，且没有 benchmark-backed 最优参数或完整 PP smoke，实际收益和跨环境适用性仍需人工验证，因此不超过静态有效性上限。
代码行号锚点、card.yaml 的证据清单、测试命令和评估报告为审计提供了线索，并区分了 code_verified 与 doc_only。扣分原因是未提供所引用源文件和测试内容，基准结果缺少可独立复现细节，不能形成多来源独立验证。
- 执行前确认 Megatron-Bridge、Transformer Engine、sequence parallel、分布式优化器及 TP/PP 配置与当前版本一致；文档未提供自动回滚或安全恢复步骤。
- 不要将 bucket_size 误解为字节数；PP overlap 的自动选择依赖 PP/VPP 条件，TP overlap 可能因依赖或 sequence_parallel 缺失而静默关闭。
- BENCHMARK.md 的结果是静态提供的报告，不能替代在目标硬件、版本和工作负载上的实际测试；建议补充代表性性能基准和 PP smoke 测试。
这个 Skill 能做什么，适合哪些场景？
该技能面向使用 Megatron-Bridge 的分布式训练工程师，提供张量并行、数据并行和流水线并行通信重叠的配置示例。它说明关键配置项、Bridge 源码锚点、启动时环境变量以及常见失效原因。技能还给出通信重叠单元测试和可选插件测试的验证命令。适合排查通信重叠未生效或吞吐量因配置变更下降的情况。
提供 CommOverlapConfig、TP/DP/PP 并行参数、分布式优化器和混合精度设置示例；指出 comm_overlap.py 与 run_plugins.py 中的 gating、PP 选择、DP 默认值和环境变量代码位置；说明 sequence parallel、Transformer Engine、VPP、bucket size 及启动环境变量之间的限制；指导运行 tests/unit_tests/training/test_comm_overlap.py 和可选的 test_run_plugins.py。
- 使用 Megatron-Bridge 训练大模型，并希望启用 TP 通信重叠的工程师。
- 已配置 DP 优化器，但需要检查梯度归约和参数聚合是否重叠的用户。
- 使用多级流水线并行并需要判断 `overlap_p2p_comm` 是否会自动启用的用户。
- 发现吞吐量回退，怀疑来自 `overlap_param_gather`、`overlap_grad_reduce` 或相关配置变更的维护者。
这个 Skill 有哪些优点和局限？
- 覆盖 TP、DP、PP 三类通信重叠配置。
- 包含可直接参考的 Python 配置、源码位置和故障排查要点。
- 提供明确的单元测试验证命令及成功标准。
- TP 重叠依赖 sequence parallel 和 Transformer Engine，否则会被禁用。
- PP 重叠仅在 PP 大于 1 且 VPP 大于 1 时由 Bridge 自动选择。
- 源材料未提供实测吞吐提升、支持平台矩阵或完整性能基准。
- 仓库元数据标为 `NOASSERTION`，而该 SKILL.md 声明 Apache-2.0，采用前需核对许可证范围。
如何安装这个 Skill？
使用仓库 README 提供的 skills CLI 安装指定技能：npx skills add nvidia/skills --skill nemo-mbridge-perf-tp-dp-comm-overlap --yes。CLI 会处理技能选择和安装目标；具体目标目录未在源材料中规定。
如何使用这个 Skill？
在已加载该技能的兼容 Agent Skills 客户端中提出具体请求，例如：“为 Megatron-Bridge 启用 TP、DP 和 PP communication overlap，并检查 sequence parallel 和 VPP 前置条件。”随后按技能中的配置示例修改 Bridge 配置，并运行：uv run python -m pytest tests/unit_tests/training/test_comm_overlap.py -q。源材料规定首个命令的成功标准为 26 passed；若具备 nemo_run，可额外运行 recipes 测试。