执行摘要

此PR修复了Gemma4ForCausalLM模型加载LoRA适配器时因命名路径不一致导致的失败问题，通过添加权重映射器（hf_to_vllm_mapper）对齐键名，确保兼容性。影响范围仅限于Gemma4模型的LoRA功能，风险低且已通过测试验证，推荐相关工程师关注映射设计。

功能与动机

PR旨在解决Gemma4模型中两个变体（Gemma4ForConditionalGeneration和Gemma4ForCausalLM）的模型路径命名差异。如PR body所述，Gemma4ForConditionalGeneration使用model.language_model.*路径，而纯文本的Gemma4ForCausalLM使用model.*路径，这导致针对前者训练的LoRA适配器无法在后一种模型上正确加载。因此，需要引入映射机制来重命名LoRA键。

实现拆解

关键改动分为两个文件：

1. vllm/model_executor/models/gemma4.py：在Gemma4ForCausalLM类中添加hf_to_vllm_mapper属性，使用WeightsMapper定义映射规则。
   - orig_to_new_prefix: 将"model.language_model."映射到"model."。
   - orig_to_new_substr: 处理MoE组件，如将".moe.experts.gate_up_proj"映射到".moe.gate_up_proj"。
2. tests/lora/test_lora_checkpoints.py：新增两个测试函数：
   • test_gemma4_lora_weights_mapping: 验证普通层的映射。
   • test_gemma4_moe_lora_weights_mapping: 验证MoE层的映射。
     代码示例（取自gemma4.py）：

hf_to_vllm_mapper = WeightsMapper(
    orig_to_new_prefix={
        "model.language_model.": "model.",
    },
    orig_to_new_substr={
        ".moe.experts.gate_up_proj": ".moe.gate_up_proj",
        ".moe.experts.down_proj": ".moe.down_proj",
    },
)

评论区精华

review中主要讨论围绕映射的完整性：

• gemini-code-assist[bot]: 指出初始mapper可能缺少MoE组件映射，建议使用orig_to_new_substr更健壮地处理路径。
• ShubyM（作者）: 回复解释per_expert_scale不是LoRA目标，因此无需映射，并已补充MoE映射。
  最终，评审者jeejeelee批准PR，表明讨论已解决。

风险与影响

• 风险: 映射逻辑简单，但若未来模型结构变化或存在未覆盖路径，可能导致LoRA加载失败。测试覆盖了主要场景，但依赖映射正确性。
• 影响: 直接影响使用Gemma4和LoRA的用户，修复加载问题提升兼容性；对系统其他部分无影响，属于模型特定优化。

关联脉络

从历史PR看，相关PR如#39450（添加Gemma4 Eagle3支持）也涉及Gemma4模型修改，表明仓库正持续增强Gemma4功能。此PR作为bug修复，补全了LoRA支持链条，与近期模型功能演进趋势一致。