执行摘要

• 一句话：融合共享专家至AITER MoE，提升MiniMax-M3 TPOT 4-17%
• 推荐动作：此PR值得精读，特别是它展示了如何在不破坏现有非AITER路径的前提下，引入AITER专属的优化路径。设计上采用多函数共存、条件分支清晰，是平台特定性能优化的良好案例。建议工程师关注_aiter_moe_fused_shared_experts_enabled的设计以及如何利用aiter的grouped top-k实现共享专家融合。如果后续需要为其他模型做类似优化，可以参考此模式。

功能与动机

MiniMax-M3模型包含一个始终激活的共享专家，原有实现将其作为独立的密集MLP运行，增加了kernel启动和显存访问。融合共享专家到routed MoE的一次调用中，可以显著减少延迟。本PR是#46419（AITER MoE后端选择）的后续，进一步利用AITER的grouped top-k能力来支持融合共享专家，从而最大化性能。

实现拆解

实现分以下几步：

1. 新增AITER专用融合检测函数：在vllm/models/minimax_m3/amd/model.py中添加_aiter_moe_fused_shared_experts_enabled()，判断是否满足：已启用FSE（环境变量VLLM_ROCM_USE_AITER_FUSION_SHARED_EXPERTS）、不在专家并行下、运行在gfx950且AITER的is_fusion_moe_shared_experts_enabled()返回True。该函数专用于AITER MoE路径，与#46545已有的fse_topk_bias_router_enabled（适用于非AITER）共存。

2. 改造MiniMaxM3MoE初始化：在MiniMaxM3MoE.__init__中，根据self.use_aiter_moe_fse（源自上述函数）设置不同的gating参数：当使用AITER路径时，启用use_grouped_topk=True、num_expert_group=1、topk_group=1以通过aiter的biased grouped top-k；同时apply_routed_scale_to_output设为False（aiter内部处理缩放）。非AITER路径保持原有vLLM topk router行为。

3. 调整量子化MoE后端（vllm/model_executor/layers/quantization/quark/quark_moe.py及相关文件）：为支持新路径中的中间维度填充需求，在FusedMoEConfig中添加intermediate_size_per_partition_unpadded和hidden_dim_unpadded等配置项，允许模型指定未填充的维度，避免因填充导致kernel计算错误。

4. 性能验证：通过GSM8K评估（5-shot）验证准确率无回归，并在ISL/OSL 8K1K场景下测试TPOT，得到4.5%-16.9%的加速。

注意：此PR依赖#46419的AITER MoE后端和#46545的FSE Router，三者共同提供全路径优化。

关键文件：

• vllm/models/minimax_m3/amd/model.py（模块 模型；类别 source；类型 core-logic；符号 _fuse_shared_experts_enabled, _aiter_moe_fused_shared_experts_enabled, MiniMaxM3MoE.init, MiniMaxM3MoE.forward）: 核心变更文件，新增AITER专用融合检测函数、改造MiniMaxM3MoE条件分支以实现共享专家融合。

关键符号：_fuse_shared_experts_enabled, _aiter_moe_fused_shared_experts_enabled, _m3_fuse_shared_experts_enabled, MiniMaxM3MoE.init, MiniMaxM3MoE.forward, MiniMaxM3MoE.load_weights

关键源码片段

vllm/models/minimax_m3/amd/model.py

核心变更文件，新增AITER专用融合检测函数、改造MiniMaxM3MoE条件分支以实现共享专家融合。

# vllm/models/minimax_m3/amd/model.py
​
def _aiter_moe_fused_shared_experts_enabled(config: PretrainedConfig) -> bool:
    """判断是否通过AITER的biased grouped top-k实现共享专家融合。
​
    条件：必须已启用FSE（`_fuse_shared_experts_enabled`返回True）、
    非专家并行、运行在gfx950且AITER内部表示支持融合。
    """
    if not _fuse_shared_experts_enabled(config):
        return False
    from vllm.platforms.rocm import on_gfx950
    # 此时已确认是 ROCM 平台，import 安全
    return on_gfx950() and rocm_aiter_ops.is_fusion_moe_shared_experts_enabled()
​
​
class MiniMaxM3MoE(nn.Module):
    def __init__(
        self,
        config: PretrainedConfig,
        prefix: str = "",
    ):
        super().__init__()
        # ... 其他初始化 ...
​
        # 判断是否使用 AITER 专用 FSE 路径（条件：AITER MOE 激活且 gfx950）
        self.use_aiter_moe_fse = _m3_fuse_shared_experts_enabled(config)
​
        # 当使用 AITER FSE 时，设定 grouped top-k 参数为单组（退化为普通 top-k 但走 aiter biased 路线）
        # 同时 `apply_routed_scale_to_output` 取反（aiter 内部处理缩放）
        self.gate = GroupedTopKRouting(
            self.num_total_experts,
            self.top_k,
            scoring_func=config.scoring_func,
            e_score_correction_bias=self.e_score_correction_bias,
            renormalize=True,
            use_grouped_topk=self.use_aiter_moe_fse,
            num_expert_group=1 if self.use_aiter_moe_fse else None,
            topk_group=1 if self.use_aiter_moe_fse else None,
            activation="swigluoai_uninterleave",
            swiglu_limit=config.swiglu_limit,
            swiglu_alpha=config.swiglu_alpha,
            apply_routed_scale_to_output=not self.use_aiter_moe_fse,
        )
        # 其他初始化 ...

评论区精华

Review中主要讨论了以下要点：

• AITER导入位置：tjtanaa建议将from aiter.ops.flydsl.moe_common import GateMode移到函数内部，避免在没有aiter的环境下造成导入错误。Fangzhou-Ai采纳，将其置于特定条件分支内。

• activation_interleave未定义风险：dllehr-amd指出activation_interleave变量只在swigluoai等特定激活下定义，在其他激活（如gelu）下未定义。要求设默认值None，并清理GateMode.INTERLEAVE的误用。作者修复。

• 两个FSE函数共存：tjtanaa要求保留#46545中的fse_topk_bias_router_enabled作为非AITER路径的入口，新增_aiter_moe_fused_shared_experts_enabled仅控制AITER路径，并通过_m3_fuse_shared_experts_enabled作为OR合并。作者执行。

• CK MoE后端选择机制：BowenBao批评直接在quark_moe.py中添加_ck_moe_enabled判断不符合oracle/kernel backend设计理念，应通过oracle统一调度。Fangzhou-Ai后续重构了该部分，最终获得批准。

• load_weights修改必要性：tjtanaa质疑为何修改weight加载逻辑，认为mxfp4和mxfp8权重参数名一致。Fangzhou-Ai验证后revert了该改动。

  • AITER导入位置安全性 (design): Fangzhou-Ai将导入放入条件分支内，确保只在需要时加载。
  • activation_interleave默认值未定义风险 (correctness): 作者给activation_interleave添加默认值None，并清理了相关的GateMode.INTERLEAVE误用。
  • 保留两个FSE函数分别对应aiter和非aiter (design): 作者保留fse_topk_bias_router_enabled（重命名自_fuse_shared_experts_enabled），新增_aiter_moe_fused_shared_experts_enabled，并使用_m3_fuse_shared_experts_enabled作为OR组合。
  • CK MoE后端选择不应绕过oracle机制 (design): Fangzhou-Ai移除了该独立判断，改为在oracle中进行后端选择? 最终BowenBao APPROVED，可能通过其他方式解决。
  • load_weights修改不必要 (correctness): Fangzhou-Ai验证后revert了该修改，保持与#46545一致。

风险与影响

• 风险：
  • 核心路径变更：MoE是模型前向的关键部分，引入分支可能影响非AITER路径的稳定性。需确保use_grouped_topk等参数在非AITER下不变。
  • 平台特定：代码假设AITER仅存在于ROCM/gfx950，在其他平台上不会触发，但若未来有其他平台支持AITER，需要调整守卫条件。
  • 依赖绑定：该优化依赖aiter库的最低版本（v0.1.15.post3），若用户使用旧版aiter，可能导致功能不可用或错误。PR body中作者明确要求等待aiter bump合并后才可合并（但最终未体现，可能需要后续跟进）。
  • 测试覆盖：没有看到直接针对融合共享专家的测试新增，依赖手工验证（GSM8K和perf sweep）。未来若其他模型复用此机制，需要更好的测试。
  • 配置理解成本：新增多个环境变量（如VLLM_ROCM_USE_AITER_FUSION_SHARED_EXPERTS），用户可能不清楚何时启用，可能造成预期外的行为。
• 影响：
  • 用户影响：使用AMD ROCm gfx950并搭载MiniMax-M3模型的用户可获得4.5%-17%的TPOT性能提升，但需设置环境变量VLLM_ROCM_USE_AITER_FUSION_SHARED_EXPERTS=1并确保aiter版本满足要求。无需额外的代码改动即可享受加速。
  • 团队影响：维护成本上升，因为现在有两个FSE路径（vLLM router和AITER），需要保持两者行为一致且不退化。未来模型若想复用此机制，需类似的条件分支设计。
  • 系统影响：对非ROCM平台无影响，对gfx950以外的GPU无影响。
  • 风险标记：核心路径变更, 平台特定依赖, 环境变量控制, 缺少测试覆盖, 依赖aiter版本

关联脉络

• PR #46419 [ROCm][Perf] Use flydsl moe with Minimax-M3 mxfp8 weights on gfx950 and implemented moe-backend selection: 本PR是#46419的follow-up，在其AITER MoE后端基础上融合共享专家。
• PR #46545 [ROCm][Perf] Fused shared expert topk bias router: 引入了vLLM router的共享专家融合（fuse_topk_bias_router），本PR在其基础上新增AITER专用路径。