执行摘要

• 一句话：修复 LoRA MoE 专家参数映射前缀顺序错误
• 推荐动作：值得精读。这是一个小而关键的数据契约修复：2 行改动修复了 LoRA + MoE 权重同步的完整阻断路径，展示了'参数命名顺序即隐式接口'的工程教训。重点关注 build_expert_params_mapping 中 param_name 与 weight_name 两侧前缀顺序相反的设计，以及重构（#41184）如何悄悄破坏这种隐式契约；同时应留意缺少单元测试这一短板。

功能与动机

PR body 明确指出：这是 #31104 的后续，被 #41184 的重构破坏。旧实现把 LoRA base-layer 前缀拼接在 routed_experts_prefix 之后，产生 experts.routed_experts.base_layer.w13_，而实时 LoRA 参数树嵌套方向相反，是 experts.base_layer.routed_experts.w13_weight，因此严格加载器（DeepseekV2/DSV3 等）执行 params_dict[name_mapped] 时会对每个 routed-expert 权重同步抛 KeyError，LoRA + MoE 的权重同步路径完全不可用。

实现拆解

1. 定位错误拼接位置

在 vllm/model_executor/layers/fused_moe/routed_experts.py 的 build_expert_params_mapping 中，w13/w2 前缀由 f-string 拼接。旧实现为 f"experts.{routed_experts_prefix}{lora_base_layer_prefix}w13_"，把 LoRA base-layer 前缀错误地放在了 routed_experts_prefix 之后。

2. 理清两侧命名空间

• param_name 面向运行时 LoRA 参数树：experts.base_layer.routed_experts.w13_weight（base_layer 在外层）。
• weight_name 面向 checkpoint：如 fused 条目中的 experts.{gate_up}，或 extend 条目中的 experts.{logical_expert}.{gate_up}.{lora_base_layer_prefix}（base_layer 出现在路径末尾）。

两侧顺序天然相反，旧实现把 checkpoint 侧的顺序误用到了 param_name。

3. 交换拼接顺序

w13/w2 改为 f"experts.{lora_base_layer_prefix}{routed_experts_prefix}w13_"。当 lora_base_layer_prefix 为空字符串时行为不变，非 LoRA 场景零影响；routed_experts_prefix 为空时同样不改变原逻辑。

4. 端到端验证

作者用 verl LoRA merge=False + Moonlight 16B 实测，权重同步通过；Buildkite CI 多次触发/重试后通过，维护者 jeejeelee 直接批准合并。

5. 配套缺口

本次无新增测试、配置或文档变更。考虑到这是重构引入的回归，缺少针对 build_expert_params_mapping 前缀拼接顺序的单元测试是明显短板，建议后续补充。

关键文件：

• vllm/model_executor/layers/fused_moe/routed_experts.py（模块 MoE 专家层；类别 source；类型 data-contract；符号 build_expert_params_mapping）: 唯一改动文件。build_expert_params_mapping 中 w13/w2 前缀拼接顺序是本次修复的核心：交换 lora_base_layer_prefix 与 routed_experts_prefix 顺序后，param_name 才能命中运行时 LoRA 参数树，修复 DeepseekV2/DSV3 等严格 loader 的权重同步 KeyError。

关键符号：build_expert_params_mapping

评论区精华

该 PR 无实质性技术争论。review 评论中 claude[bot] 因 fork PR 跳过自动审查，copilot 因配额上限未能审查，唯一的 review 是 jeejeelee 的直接 APPROVED。评论区主要活动是 CI 流程：mergify[bot] 提示 pre-commit 失败并给出修复命令，作者 HollowMan6 通过 /ci run、/ci retry 多次触发与重试 Buildkite CI（#84132、#84202、#84211）。合并依据主要来自 PR body 对两种参数树结构的比对说明和 Moonlight 16B 的端到端验证结果。

• CI 流程与 pre-commit 失败处理（无实质技术争论） (testing): pre-commit 修复后 CI 通过，维护者 jeejeelee 直接批准合并；合并依据为 PR body 的根因分析、Moonlight 16B 端到端结果与 CI 通过状态。

风险与影响

• 风险：1）缺少测试覆盖：+2/-2 的改动没有任何配套测试，build_expert_params_mapping 的前缀拼接顺序没有回归保护，同类重构（如本次 #41184）可能再次破坏该隐式契约。
  2）数据契约变更：param_name 同时被 liveset 更新、update_from_named_tensors 等 LoRA 同步路径用作 params_dict 查找键，本次修改了带 routed_experts_prefix 的 LoRA 场景下的键值。
  3）回归范围控制：lora_base_layer_prefix="" 时新拼接退化为原逻辑，非 LoRA 场景行为不变；受影响面限定在同时设置 routed_experts_prefix 与 lora_base_layer_prefix 的 MoE 层。
  4）从旧顺序必然 KeyError 可推断不存在依赖旧命名的成功路径，兼容风险较低。

• 影响：用户影响：修复 Moonlight 16B、DeepseekV2/DSV3 等模型在 LoRA merge=False 下的权重同步 KeyError，属于功能阻断修复，对受影响用户是直接受益。系统影响：仅涉及 vllm/model_executor/layers/fused_moe/routed_experts.py 单文件两行字符串拼接，运行期性能与内存无任何变化。团队影响：该文件是 fused_moe 核心模块，近期改动活跃，本次修复为参数命名约定增加了一个需要回归保护的敏感点。

• 风险标记：缺少测试覆盖, 数据契约变更, 重构回归风险

关联脉络

• PR #31104 原始 LoRA 专家参数映射 PR（标题未提供）: PR body 声明本修复是 #31104 的后续，该 PR 首次引入 build_expert_params_mapping 中的 lora_base_layer_prefix 逻辑，是本次修复的对象。
• PR #41184 破坏映射顺序的重构 PR（标题未提供）: PR body 指出 #41184 的重构把 lora_base_layer_prefix 拼接到了 routed_experts_prefix 之后，是本 bug 的引入源。