Skip to content

refactor(moe): 实现默认专家计算并补齐 EP 模块族骨架 - #1594

Open
Er1ckPang wants to merge 1 commit into
mindspore-ai:masterfrom
Er1ckPang:refactor/moe_ep_1115
Open

Er1ckPang wants to merge 1 commit into
mindspore-ai:masterfrom
Er1ckPang:refactor/moe_ep_1115

Conversation

@Er1ckPang

@Er1ckPang Er1ckPang commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Paired: GitHub #1594 ↔ GitCode !1968

What type of PR is this?
/kind refactor


What does this PR do / why do we need it:

基于 #1523 的 ModuleFamily 机制,把 routed 专家数学与 EP slot 运输分开。模型保留 router、aux-loss、共享专家、gate/mask 和返回结构;统一专家入口消费模型给出的 hidden_states/topk_ids/topk_weights。

  • 新实现位于 components/modules/moe/grouped_experts/。公开 GroupedExperts 和 GroupedExpertsConfig,内部默认算法类不作为包级接口。
  • forward 直接执行 validate_and_flatten_inputs -> permute -> dispatch -> compute_experts -> combine -> unpermute,阶段间直接传 Tensor、split 列表和逆排列索引。
  • EP=1 只做一次来源 permute;EP>1 在 A2A 后增加一次 owner-local expert permute,combine 依次撤销接收排列、A2A 和来源排列。
  • 默认计算复用 NPU 融合 permute/unpermute 与 grouped-GEMM。参数保持 HF packed 方向:gate_up_proj [E,2I,H]、down_proj [E,H,I]。
  • routing_weight_mode 仅保留 before_fc2 和 output。直接构造默认前者,HF 来源默认后者;概率只应用一次。
  • 初始化使用 init_method_std=0.02,FC2 std 为 init_method_std / sqrt(2 * num_layers)。模型替换自动从来源/祖先 config 读取总层数和标准差;已有 Parameter 直接复用。
  • 注册 local、ep、mega、ep_mega、ep_moonep。local/ep 已实现;Mega/MoonEP 为显式失败的骨架;本期不实现低精。
  • 专家参数只沿 EP Shard(0),保持完整 H/I,支持 dense TP 的 TP-extend-EP(ETP=1)。FSDP/HSDP 继续负责 unshard、预取和 reshard。
  • planner 先用完整参数角色识别父 MoE,再排除子专家已经拥有的参数;根据参数所有权和通信协议选择默认 moe_mlp_routed 模板。父层保留原生 forward,不重复执行专家 EP,也不把完整输出标成 TP Partial。
  • module_binding.py 只借用作业已有 EP mesh 并注入 EPContext;没有额外参数保护层或 state_contract()。

模型接入:

  • Qwen3-MoE、Qwen3.6、DeepSeek-V3、DeepSeek-V3.2 和 Kimi-K2.6 的普通配方选择新族。
  • DeepSeek-V4.1 普通专家通过模型 adapter 注入现有 FP32 clamp/SwiGLU;MegaMoe 路径、在线 YAML 和 quick-start 保持不变。
  • Qwen3-VL、Qwen2-MoE、DeepSeek-V2 可在 Transformers 5.11+ packed 契约下显式选择,但不声明其默认配方已经迁移。
  • Kimi-K3 当前官方结构不满足 packed 三 Tensor 契约,因此不注册 replacement;删除假设性 adapter。后续需模型先完成参数打包、训练 forward 与 checkpoint 映射。
  • 最低依赖保持 transformers>=5.11.0,固定核对版本为 5.13.1。

保留旧 components/modules/grouped_experts.py、公共 module-family 实现及受保护示例;删除未使用的 routing 辅助函数,routing.py 最终与基线一致。


Which issue(s) this PR fixes:

Fixes #1593


Test Plan and Test result:What scenarios were tested, and what were the verification results(Function, performance, reliability, etc.):

功能与门禁:

  • AutoGit 静态检查、pylint、launcher import contract:PASS。
  • 相关 UT:12 passed。
  • 单卡 local NPU ST:PASS,覆盖两种 routing mode 的输出、输入/概率/FC1/FC2 梯度;EP=1 permute 次数为 1。
  • 4 卡 EP NPU ST:PASS,覆盖两种 routing mode、完整前后向和 EP>1 两次 permute;FP32 定位也通过。
  • 完整 tests/ut:BLOCKED。默认环境是 Transformers 4.57.1,缺少 DeepSeek-V4、hyper_multicore、OR-Tools、pyarrow 等,收集阶段 74 个依赖错误。
  • GitCode/Jenkins 门禁:BLOCKED。当前环境未配置 GITCODE_TOKEN 和 JENKINS_URL,无法查询或触发。

数值:

  • Transformers 5.13.1 下,六个实际接入的两层裁剪完整模型均完成 10-step:Qwen3-MoE、Qwen3.6、DeepSeek-V3、DeepSeek-V3.2、DeepSeek-V4.1、Kimi-K2.6。
  • Qwen3-MoE、DeepSeek-V3.2 完整模型完成 1000-step;最大 loss 差均为 1.91e-6,最后一步 loss、logits 和 pre-clip 全局梯度范数一致,无累积漂移。
  • Qwen3.6 10-step 最大 loss 差 1.07e-4(相对约 2.2e-5),最大梯度范数差 4.89e-4(相对约 2.3e-4),来自 BF16 grouped-GEMM 累加顺序,未发现生产语义错误。

性能:

  • 4 卡 EP,B=8/S=128/H=512/I=1024/E=4/top-k=2,10 warmup + 50 前后向:新 staged EP 相对旧路径平均快 0.7%–1.5%。
  • local 旧/新 GMM 在较大裁剪形状上,Qwen3 p50 基本一致,DeepSeek-V3.2 p50 快约 9.1%;小形状 mean 受固定开销影响为 -3.7% 到 -3.9%。
  • 相对 Transformers native 逐专家循环,Qwen3 与 DeepSeek-V3.2 裁剪 MoE block 分别快 3.44x 和 2.86x;该数据说明 grouped-GEMM 收益,不作为旧 GMM 对新 GMM 的重构收益。

完整逐步数据、关键日志与限制记录在本地报告 output/_codex-docs/moe_ep_refactor_validation_20261120.md(output 为忽略目录)。完整模型使用结构保持的裁剪配置与合成 token,未下载发布 checkpoint 或真实数据集。


Self-checklist:

  • 设计:等待 Maintainer 评审。
  • 测试:相关 UT、单卡/4 卡 ST、10/1000-step 数值与性能已完成;外部门禁阻塞项已说明。
  • 接口:公开入口、输入输出、成员选择和使用方式已记录。
  • 文档:模块 README、Issue 和 PR 描述已同步最终实现。

@Er1ckPang
Er1ckPang force-pushed the refactor/moe_ep_1115 branch from b485fd1 to ea0d121 Compare November 18, 2026 02:44
@Er1ckPang Er1ckPang changed the title refactor(moe): 建立专家模块族骨架并拆分 EP 阶段 refactor(moe): 实现默认专家计算并补齐 EP 模块族骨架 Nov 18, 2026
@Er1ckPang
Er1ckPang force-pushed the refactor/moe_ep_1115 branch 2 times, most recently from e3b3624 to 5f0a3b6 Compare November 18, 2026 03:34
@Er1ckPang
Er1ckPang force-pushed the refactor/moe_ep_1115 branch 3 times, most recently from 71dd06d to 630b854 Compare November 18, 2026 07:32
@Er1ckPang
Er1ckPang force-pushed the refactor/moe_ep_1115 branch 9 times, most recently from 30eb4fd to 7bd526a Compare November 19, 2026 08:49
@Er1ckPang

Copy link
Copy Markdown
Contributor Author

/check-pr

@Er1ckPang
Er1ckPang force-pushed the refactor/moe_ep_1115 branch 3 times, most recently from 66f09ea to 1683a4e Compare November 19, 2026 14:11
@Er1ckPang
Er1ckPang force-pushed the refactor/moe_ep_1115 branch 4 times, most recently from 9d1d0df to 9306412 Compare November 19, 2026 16:06
Comment on lines +196 to +198
if self.gate_up_proj.is_meta:
# HF's initializer no longer recognizes the replaced expert class after materialization.
self._hp_reset_after_materialization = True

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

确认下这块是在meta初始化适配,还是在这里适配

Comment on lines +199 to +200
for name, child in module.named_children():
self.add_module(name, child)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

把源模块的子模块注册到新模块上

"""Validate named input and output layout declarations against the module interface."""
injection_fields = ("local_compute_fn", "inner_wrapper", "inner_target", "region_dispatch")
# A local execution policy does not inject a replacement compute function.
injection_fields = ("local_compute_fn", "inner_wrapper", "inner_target")

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

为了让父mlp模块可以设置region_dispatch=False,从而继续使用原来模型的mlp.forward

Comment on lines +113 to +117
else:
order = local_ids.argsort(stable=True)
hidden = hidden.index_select(0, order)
rows = torch.arange(order.numel(), dtype=torch.int32, device=order.device)
recv_inverse = torch.empty_like(rows).scatter_(0, order, rows)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

保留回退场景实现,是不是在ops目录下实现这个比较好

@Er1ckPang
Er1ckPang force-pushed the refactor/moe_ep_1115 branch from 9306412 to dbd500e Compare November 19, 2026 16:27
@Er1ckPang
Er1ckPang force-pushed the refactor/moe_ep_1115 branch from dbd500e to bfdbbd5 Compare November 19, 2026 17:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[RFC]: MoE/EP 专家模块族与算法并行解耦

2 participants