执行摘要

• 一句话：重命名 MoE 专家参数映射函数为独立函数
• 推荐动作：值得精读。该 PR 是大规模 MoE 重构的铺垫，展示了如何通过细小步骤安全解耦核心模块。设计决策（预留临时转发函数、批量替换调用）可作为类似重构的参考。建议后续关注删除 FusedMoE 类的 PR，以完整理解架构演进。

功能与动机

PR body 明确指出："This is prep work for deleting the FusedMoE class and replacing it with MoERunner." 通过将方法提升为模块级函数，解耦模型实现与 FusedMoE 类，为后续重构扫清障碍。

实现拆解

1. 定义独立函数：在 vllm/model_executor/layers/fused_moe/layer.py 末尾新增模块级函数 fused_moe_make_expert_params_mapping，内部委托给原 FusedMoE.make_expert_params_mapping，并标记为临时转发层。

2. 更新模型导入：在所有使用该函数的模型文件（如 llama4.py、glm4_moe_lite.py、AXK1.py 等）中，将导入从仅导入 FusedMoE 改为同时导入 FusedMoE 和新函数。

3. 替换调用点：将模型文件中所有 FusedMoE.make_expert_params_mapping(...) 调用替换为 fused_moe_make_expert_params_mapping(...)，并更新相关文档字符串（如 llama4.py 中 load_moe_expert_weights 的 docstring）。

4. 批量同步：类似的导入和调用修改同步应用于其他约 30 个模型文件（如 ernie45_vl_moe.py、glm4_moe_mtp.py、deepseek_eagle.py 等），改动模式一致。

代码展示 layer.py 中新增的函数定义：

关键文件：

• vllm/model_executor/layers/fused_moe/layer.py（模块 MoE核心层；类别 source；类型 core-logic；符号 fused_moe_make_expert_params_mapping）: 定义新的模块级函数 fused_moe_make_expert_params_mapping，作为原类方法的临时转发层，是本次变更的核心。
• vllm/model_executor/models/llama4.py（模块 模型定义；类别 source；类型 data-contract）: LLaMA4 模型实现，需修改导入和两处调用（expert_params_mapping 和 expert_params_mapping_fused），并更新 docstring。
• vllm/model_executor/models/glm4_moe_lite.py（模块 模型定义；类别 source；类型 data-contract）: GLM4 MoE Lite 模型，需修改导入和两处调用（get_expert_mapping 和 load_weights）。
• vllm/model_executor/models/AXK1.py（模块 模型定义；类别 source；类型 data-contract）: AXK1 模型，需修改导入和两处调用（get_expert_mapping 和 load_weights）。
• vllm/model_executor/models/ernie45_vl_moe.py（模块 模型定义；类别 source；类型 data-contract）: Ernie45 VL MoE 模型，需修改导入和一处调用。
• vllm/model_executor/models/glm4_moe_lite_mtp.py（模块 模型定义；类别 source；类型 data-contract）: GLM4 MoE Lite MTP 模型，需修改导入和一处调用。

关键符号：fused_moe_make_expert_params_mapping

关键源码片段

vllm/model_executor/layers/fused_moe/layer.py

定义新的模块级函数 fused_moe_make_expert_params_mapping，作为原类方法的临时转发层，是本次变更的核心。

# 临时转发函数，位于 vllm/model_executor/layers/fused_moe/layer.py
# 作为从 `FusedMoE` 类方法到独立函数的迁移桥梁，后续将移除此临时层
def fused_moe_make_expert_params_mapping(
    model: torch.nn.Module,
    ckpt_gate_proj_name: str,
    ckpt_down_proj_name: str,
    ckpt_up_proj_name: str,
    num_experts: int,
    num_redundant_experts: int = 0,
) -> list[tuple[str, str, int, str]]:
    # 内部仍委托给原始的 FusedMoE.make_expert_params_mapping
    return FusedMoE.make_expert_params_mapping(
        model,
        ckpt_gate_proj_name,
        ckpt_down_proj_name,
        ckpt_up_proj_name,
        num_experts,
        num_redundant_experts,
    )

评论区精华

唯一一条 review 来自 gemini-code-assist[bot]，指出新函数签名缺少 ckpt_up_proj_name 和 num_experts 的默认值，可能导致尚未更新的模型调用时抛出 TypeError。但该评论未获作者直接回复，PR 随后被批准合并。实际检查发现，本次 PR 已覆盖所有内部调用方，统一提供了完整参数，因此风险可控，但外部可能还有未更新的调用点。

• 新函数签名缺少默认值参数 (correctness): PR 已合并，且所有被修改的调用方均提供完整参数；但潜在风险存在于仓库外或旧分支的调用中。

风险与影响

• 风险：接口兼容性风险：新函数签名要求必须提供 ckpt_up_proj_name 和 num_experts（除 num_redundant_experts 外无默认值），若仓库外或历史分支中有代码仍通过 FusedMoE.make_expert_params_mapping 调用，或使用旧参数模式，将会报错。

核心路径变更：模型权重加载属于关键路径，此变更影响大量 MoE 模型，一旦引入 bug 会导致加载失败或权重映射错误。

跨模块耦合：虽然本次是纯重命名，但未来删除 FusedMoE 类时可能引发更深层依赖断裂。

• 影响：影响范围：涉及 53 个文件，覆盖 vLLM 中几乎所有 MoE 类模型（如 LLaMA、Qwen、DeepSeek、GLM4 等），影响面广。

影响程度：中等——不改变逻辑，但所有模型文件需同步修改导入和调用；若漏改则运行时崩溃。测试未配套变更（无新增测试），但 CI 已通过。

团队影响：降低 MoE 模块与具体类的耦合，方便后续重构；贡献者需注意新接口的使用方式。

• 风险标记：接口兼容性风险, 核心路径变更, 跨模块改动

关联脉络

• PR #40574 [MoE] Move cutlass moe to fused_moe/experts/: 同为 MoE 重构系列，进一步将 CUTLASS MoE 移动至子目录，与本次解耦方向一致。
• PR #40412 fused_moe: treat NIXL EP as batched experts: 修复 fused_moe 中 NIXL EP 后端的问题，与 MoE 层紧密相关。