
名称	nemo-mbridge-perf-moe-comm-overlap
描述	Megatron Bridge中的MoE专家并行通信重叠。涵盖dispatch/combine重叠、flex调度器后端以及专家wgrad调度。
开源协议	Apache-2.0 when_to_use: 调优MoE通信重叠，或将MoE吞吐量回归追溯到通信重叠配置变更；‘overlap_moe_expert_parallel_comm’、‘MoE dispatch overlap’、‘flex dispatcher’、‘DeepEP overlap’、‘expert wgrad scheduling’。

MoE 通信重叠

高级概述请参阅：

@docs/training/communication-overlap.md
@skills/nemo-mbridge-perf-moe-comm-overlap/card.yaml

快速决策

在以下情况使用MoE通信重叠：

EP > 1
token dispatch或combine时间在profile中可见
运行已经正确，现在正在调优吞吐量

避免在早期bring-up阶段开启。在dispatcher、routing模式和recompute计划已经稳定后再验证会更容易。

启用

cfg.comm_overlap.overlap_moe_expert_parallel_comm = True

# 可选：为额外重叠延迟wgrad计算
cfg.comm_overlap.delay_wgrad_compute = True

# 重要：使用dispatch重叠时禁用共享专家重叠
cfg.model.moe_shared_expert_overlap = False

前提条件

expert_model_parallel_size > 1
num_moe_experts > 1
moe_token_dispatcher_type 必须是 "alltoall" 或 "flex"
精度：BF16或FP16
如果使用PP，必须设置VPP（virtual_pipeline_model_parallel_size）（非None）

Flex dispatcher激活

仅设置 moe_flex_dispatcher_backend 并不会激活flex dispatch。还必须设置 moe_token_dispatcher_type = "flex"。

重计算与CUDA图交互

完整的重计算与重叠路径不兼容。
如果CUDA图作用域包含注意力或MoE路由器工作，delay_wgrad_compute会增加更多约束。
实践中，启用重叠时，选择性重计算是更安全的搭配。

实测证据

HybridEP生产形态验证

2026-07-25的一次受控Qwen3 30B-A3B预训练对比使用了16个H100 GPU，BF16，序列长度4096，TP=1、PP=1、CP=1、EP=16、MBS=1、GBS=1024，强制平衡路由，HybridEP，以及Transformer Engine CUDA图作用域moe_router和moe_preprocess。唯一的性能变化是纯EP重叠；延迟wgrad保持禁用。

情况	稳态窗口	步进时间	模型TFLOPS/GPU
EP重叠关闭	迭代5-20	24.7138s	244.039
EP重叠开启，搜索运行	迭代5-20	21.0725s	286.208
EP重叠开启，独立验证	迭代41-50	20.9920s	287.305

独立结果相对于复现的基线，步进时间减少了15.059%，吞吐量增加了17.729%。损失保持有限，没有迭代被跳过或出现NaN，rank-0峰值分配内存为62.166 GiB。

采用相同方法的rank-0 Nsight Systems对比捕获了每种情况下的463,348个内核：

Profile指标	重叠关闭	重叠开启
与GEMM/注意力并发的通信	9.079ms	3,958.997ms
被计算隐藏的通信时间	0.11%	36.55%
GPU活动区间并集	22.821s	21.221s
HybridEP dispatch-with-permute NVTX	4.253s	1.767s
HybridEP metadata-preprocess NVTX	3.109s	0.670s

这是直接证据，表明增益来自于隐藏暴露的HybridEP dispatch/combine工作，而不是因为更改了dispatcher、路由、图作用域、批处理形状或并行布局。

正确性优先的alltoall冒烟测试

2026-05-18的current-main H100 x16冒烟测试在Qwen3 30B-A3B模拟预训练上使用了EP=16、alltoall、全局批大小1024，禁用CUDA图，并且moe_permute_fusion=false，因为PyTorch 25.11 / TE / Triton栈在之前的bring-up中在Transformer Engine融合排列中失败。

结果具有方向性而非发布级：

无EP重叠：迭代3-8的稳态平均41.25s
EP重叠：迭代3-8的稳态平均31.31s
EP重叠加delay_wgrad_compute：迭代3-8的稳态平均31.20s

将此视为证据，表明当通信暴露时，EP重叠可以帮助跨节点alltoall MoE形态。这并不是延迟wgrad单独获胜的证据，也没有验证融合排列路径。更早的2026-05-16在同一形态上的短冒烟测试显示了同样的模式。

代码锚点

重叠验证：src/megatron/bridge/training/comm_overlap.py
Flex调度器后端：src/megatron/bridge/training/flex_dispatcher_backend.py
配置：src/megatron/bridge/training/config.py
单元测试：tests/unit_tests/training/test_comm_overlap.py
DeepEP测试：tests/unit_tests/training/test_deepep.py

陷阱

共享专家重叠冲突：moe_shared_expert_overlap 和 overlap_moe_expert_parallel_comm 可能冲突。使用dispatch重叠路径时禁用共享专家重叠。
没有VPP的PP：当流水线并行激活时，MoE重叠需要VPP。没有它，重叠调度无法正确交错。
Flex != 后端标志：如果moe_token_dispatcher_type仍是"alltoall"，单独设置moe_flex_dispatcher_backend="deepep"没有任何作用。
保守的recipe默认值：大多数公开的recipe保持MoE重叠禁用。需要通过overrides显式启用。
性能增益取决于工作负载：当dispatch通信已经是步进时间的可见部分时，重叠帮助最大。并不能保证对每个小型或轻负载的EP运行都有帮助。
内核时间总和不是墙钟时间：并发内核可能运行更长时间，因为它们竞争SM或带宽，因此重叠可能会增加每个流的内核持续时间总和，同时减少暴露的区间并集和端到端步进时间。

验证

在初始化期间查找与重叠相关的日志消息。如果不满足前提条件，comm_overlap.py中的通信重叠验证将抛出异常，因此干净启动确认该功能已激活。

对于短性能测试，保持命令形状明确，一次只改变一个重叠旋钮：

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

如果在bring-up期间融合的MoE排列失败，添加model.moe_permute_fusion=false以将重叠计时与运行时栈验证分离，然后使用匹配的生产容器重新测试。

对于性能验证，使用未分析的稳态窗口作为验收指标。使用匹配的Nsight A/B建立因果关系：

保持dispatcher、路由、CUDA图、批处理形状、并行度和运行时固定。
仅切换overlap_moe_expert_parallel_comm；首次隔离时保持delay_wgrad_compute=false。
比较通信和计算的区间并集及其交集，而不仅仅是内核持续时间总和。
报告稳态步进时间、模型TFLOPS/GPU、损失有限性、跳过/NaN迭代以及峰值分配内存。

上次签名刷新：2026-08-03。