执行摘要

• 一句话：修复Gemma4 MoE权重重映射重复.moe前缀的bug
• 推荐动作：此PR虽小但修复了一个明确的加载崩溃bug，设计上使用负向lookbehind简洁有效。建议负责模型加载的开发者关注此实现，并在其他类似需要条件替换的场景中复用此模式。

功能与动机

在加载某些Gemma4 NVFP4或AWQ量化检查点时，原有的专家权重重映射逻辑对已经包含.moe.experts前缀的键再次应用替换，产生.moe.moe.experts的错误键名，导致参数查找失败。此修复旨在兼容已包含和不含.moe前缀两种命名模式的检查点，确保权重加载成功。

实现拆解

1. 提取重映射逻辑为独立函数：在vllm/model_executor/models/gemma4.py中新增_remap_gemma4_expert_weight_name(name: str) -> str函数，将原有的内联re.sub调用封装成可测试的独立单元。
2. 使用负向lookbehind避免重复前缀：正则表达式从r"\.experts\.(\d+)\."改为r"(?<!\.moe)\.experts\.(\d+)\."，确保当键中已包含.moe.experts时不再插入.moe前缀。
3. 替换调用点：在_weight_iterator内，原名称重映射行替换为调用上述新函数，保持其余逻辑不变。
4. 移除临时测试文件：根据reviewer建议，移除了最初包含的tests/models/test_gemma4.py，但保留了通过py_compile和直接断言进行的本地验证。

关键文件：

• vllm/model_executor/models/gemma4.py（模块 模型加载；类别 source；类型 data-contract；符号 _remap_gemma4_expert_weight_name）: 唯一的变更文件，包含核心修复：新增_remap_gemma4_expert_weight_name函数，并替换_weight_iterator中的内联替换逻辑，修复重复前缀bug。

关键符号：_remap_gemma4_expert_weight_name

关键源码片段

vllm/model_executor/models/gemma4.py

唯一的变更文件，包含核心修复：新增_remap_gemma4_expert_weight_name函数，并替换_weight_iterator中的内联替换逻辑，修复重复前缀bug。

# gemma4.py — 新增的 helper 函数，安全重映射 MoE 专家权重名
# 避免已包含 .moe.experts 前缀的键被重复插入 .moe.
​
def _remap_gemma4_expert_weight_name(name: str) -> str:
    """
    Remap expert weight names to include .moe prefix only once.
    Uses negative lookbehind (?<!\.moe) to avoid double-prefixing
    when the key already contains .moe.experts.
    """
    return re.sub(r"(?<!\.moe)\.experts\.(\d+)\.", r".moe.experts.\1.", name)
​
# 在 _weight_iterator 中，替换原内联 re.sub 为调用此函数：
# 旧代码（有 bug）：
# name = re.sub(r"\.experts\.(\d+)\.", r".moe.experts.\1.", name)
# 新代码（修复）：
name = _remap_gemma4_expert_weight_name(name)

评论区精华

审查中主要讨论了三个问题：

• 哪个HF repo受影响：作者提供了具体检查点名并确认问题普遍存在。
• 是否为breaking change：作者澄清现有模式仍工作，向后兼容。

• 测试文件存废：reviewer要求移除单独的测试文件，作者遵从并仅保留本地断言验证。
  用户tbooher89在讨论中证实了该bug的存在并支持合并。

• 受影响检查点确认 (question): 确认问题影响多个Gemma4量化变体，包括NVFP4和AWQ检查点，不限于单一repo。

• 变更是否为breaking change (design): 确认不是breaking change，向后兼容。
• 移除测试文件 (testing): 测试文件被移除，作者通过本地验证保证质量。

风险与影响

• 风险：低风险。修复仅针对已含.moe.experts前缀的键名，对不含该前缀的键名行为完全不变。但该路径是模型加载关键路径，如果仍有其他未覆盖的命名模式（如.moe出现在其他上下文中），可能仍有错误。缺乏集成测试覆盖是潜在风险，但作者提供了本地断言验证。
• 影响：影响所有使用Gemma4模型（特别是量化变体NVFP4/AWQ）的用户。对于尚未遇到bug的用户，升级后无行为变化；对于受影响的用户，修复后模型可正常加载。无性能影响。
• 风险标记：核心路径变更, 向后兼容已确认

关联脉络

• PR #39045 Unknown (referenced in comments as PR #39045): 在讨论中tbooher89提及该PR的review曾预测此问题可能发生，两者直接相关。