本技能面向 Megatron-Bridge 中 MoE（混合专家）模型的专家并行（EP）通信重叠配置与验证。
用途 专家并行重叠用于隐藏 token dispatch/combine all-to-all 通信成本：让通信与专家 FFN 计算并发执行。可选地，延迟专家权重梯度计算（delay_wgrad_compute）会把 wgrad 推迟到与下一层前向重叠，从而提供额外重叠。
适用判断 适合在以下情况使用 EP 重叠：模型为 MoE 且 EP > 1；专家 dispatch/combine 通信在单步耗时中占比较大；有显存余量并以吞吐为调优目标。首次上线建议先用 alltoall dispatcher（兼容性更广）；在支持的 GPU 上追求额外收益时再用 flex + DeepEP/HybridEP。以下情况应避免：启用 full activation recompute；启用 moe_shared_expert_overlap；仍处于正确性调试阶段；PyTorch < 2.6.0。
两种 dispatcher 路径
- alltoall：标准 MoE all-to-all，默认、兼容性最广。
- flex：使用 DeepEP 或 HybridEP，在 Ampere/Hopper/Blackwell 上可获得更高重叠。
启用方式（配置片段） alltoall： cg.comm_overlap.overlap_moe_expert_parallel_comm = True cfg.comm_overlap.delay_wgrad_compute = False cfg.model.moe_shared_expert_overlap = False cfg.model.expert_model_parallel_size = 8 cfg.model.num_moe_experts = 64 cfg.model.moe_token_dispatcher_type = "alltoall" cfg.model.bf16 = True cfg.model.fp16 = False
仅在确认普通重叠路径可用、并核查过额外兼容性约束后，再启用 delay_wgrad_compute=True。
flex（DeepEP 或 HybridEP）： from megatron.bridge.training.flex_dispatcher_backend import apply_flex_dispatcher_backend cfg.comm_overlap.overlap_moe_expert_parallel_comm = True cfg.comm_overlap.delay_wgrad_compute = True cfg.model.moe_shared_expert_overlap = False apply_flex_dispatcher_backend(cfg.model, moe_flex_dispatcher_backend="deepep")
或：apply_flex_dispatcher_backend(cfg.model, moe_flex_dispatcher_backend="hybridep")
最小可用配置（正确性优先起点） cg.comm_overlap.overlap_moe_expert_parallel_comm = True cfg.comm_overlap.delay_wgrad_compute = False cfg.model.expert_model_parallel_size = 4 cfg.model.num_moe_experts = 64 cfg.model.moe_token_dispatcher_type = "alltoall" cfg.model.moe_shared_expert_overlap = False cfg.model.bf16 = True
兼容性与约束 expert_model_parallel_size > 1；num_moe_experts > 1；moe_token_dispatcher_type 必须为 "alltoall" 或 "flex"；moe_shared_expert_overlap = False；基础精度为 BF16 或 FP16；PyTorch >= 2.6.0；若 PP > 1，必须设置 virtual_pipeline_model_parallel_size；recompute_granularity != "full"，recompute_method = None，recompute_num_layers = None；mtp_num_layers 必须为 None 或 1。delay_wgrad_compute 以 overlap_moe_expert_parallel_comm 为前提；与 overlap_grad_reduce 或 gradient_accumulation_fusion 同用时要求 TE >= 2.7.0；CUDA graph attn 范围 + delay_wgrad_compute 要求 TE >= 2.12.0、gradient_accumulation_fusion = True 且无 attention bias。DeepEP 仅支持 Ampere、Hopper、B200、B300；HybridEP 支持 Ampere、Hopper、B200、B300 及 NVL72 的 GB200/GB300。
最小可运行命令
在 Slurm 分配内，性能测试脚本示例：保持模型、并行度、dispatcher、运行时不变，仅变动两个重叠开关。
uv run python scripts/performance/run_script.py
-m qwen
-mr qwen3_30b_a3b
--task pretrain
-g h100
-c bf16
-ng 16
-gn 8
--max_steps 8
--cuda_graph_impl none
--moe_flex_dispatcher_backend None
--moe_a2a_overlap false
--tokenizer_type NullTokenizer
comm_overlap.overlap_moe_expert_parallel_comm=true
comm_overlap.delay_wgrad_compute=false
model.moe_shared_expert_overlap=false
注意：不要把 --moe_a2a_overlap true 用于该隔离测试，因为性能测试辅助脚本会同时启用 overlap_moe_expert_parallel_comm 和 delay_wgrad_compute，无法隔离出普通 EP 重叠。
单元测试验证：
uv run python -m pytest
tests/unit_tests/training/test_comm_overlap.py -k "moe"
tests/unit_tests/training/test_deepep.py -q
基准数据（Qwen3 MoE 30B-A3B SFT，16 张 H100） 测量配置：EP=16、alltoall、BF16、global batch size 1024、禁用 CUDA graphs、moe_permute_fusion=false，统计第 3-8 次迭代。 无 EP 重叠：41.25s（1.000x）；EP 重叠：31.31s（1.317x）；EP 重叠 + delay_wgrad_compute：31.20s（1.322x）。 该结果表明在此跨节点 all-to-all 形态下启用普通 EP 重叠有效；未显示延迟 wgrad 有明显独立收益，也未验证融合 MoE 排列（该路径在运行时栈中已禁用）。
验证与成功标准 运行后确认：CommOverlapConfig 最终化无断言错误；日志配置中 overlap_moe_expert_parallel_comm 为 True；若使用 flex dispatcher，确认 moe_token_dispatcher_type = "flex" 及正确后端。成功标准：所选 dispatcher 与重叠设置通过配置校验；训练完成且无挂起或断言失败；目标工作负载吞吐提升或不回退；loss 轨迹与基线一致（重叠不应影响收敛）。
失败诊断（症状、原因、确认、修复）
- 断言 expert_model_parallel_size > 1：EP 未配置，检查该项，设为 EP > 1。
- 断言 moe_token_dispatcher_type：dispatcher 错误，检查类型，使用 "alltoall" 或 "flex"。
- BF16/FP16 断言：精度错误，检查并使用 bf16 = True。
- 训练挂起：PyTorch < 2.6，检查版本并升级到 >= 2.6.0。
- 断言 virtual_pipeline_model_parallel_size：PP > 1 但无 VPP，检查并设置 VPP。
- 断言 recompute_granularity：启用了 full recompute，检查并禁用。
- 断言需要 overlap_moe_expert_parallel_comm：delay wgrad 缺少 EP 重叠，先启用 EP 重叠。
- 断言 gradient_accumulation_fusion：CUDA graph + delayed wgrad，检查图范围与 wgrad 设置，启用 gradient_accumulation_fusion。
- attention bias 断言：CUDA graph attn + delayed wgrad + bias，检查 add_bias_linear/add_qkv_bias 并禁用 attention bias。
- flex dispatcher 无吞吐收益：未调用 apply_flex_dispatcher_backend，检查日志中的 moe_token_dispatcher_type 并调用该函数。
- DeepEP/HybridEP 被静默跳过：GPU 不支持，检查警告日志并在 Ampere/Hopper/Blackwell 上运行。
已知限制 仅设置 moe_flex_dispatcher_backend 不会激活 flex dispatch，必须调用 apply_flex_dispatcher_backend(...)。公开 recipe 常较保守，默认可能禁用 MoE 重叠。并非每个模型系列都已在受控 Bridge 实验中测量端到端吞吐收益；代码校验强于单一通用性能声明。MoE 重叠与 shared-expert 重叠互斥。CUDA graph + delayed wgrad 是多约束路径，需要仔细校验 TE 版本与范围。