执行摘要

• 一句话：修复 Gemma4-MM ViT 量化线性层兼容性
• 推荐动作：值得精读。设计上选择通用递归替换而非模型特定补丁，体现了模块化封装思想。BitsAndBytesWeightParameter 的 dtype 修复技巧可复用。建议关注后续 LoRA 准确性修复。

功能与动机

PR #42825 通过模型特定补丁修复了 ViT 量化，但该补丁将在 BNB OOT 插件迁移 (#43529) 后废弃；PR #43440 因注意力掩码限制无法替换常见线性层。因此需要一个通用递归替换方案，通过 transformers 后端替换线性层实现 ViT 原生化。

实现拆解

1. 在 vllm/model_executor/models/transformers/utils.py 中新增 recursive_replace_linear 函数，递归遍历模块子层，将 nn.Linear 替换为 vLLM 的 ReplicatedLinear（根据量化配置），并包含内部辅助函数 _recursive_replace。

2. 修改 vllm/model_executor/models/gemma4_mm.py，在 Gemma4MultimodalEmbedder 和 Gemma4ForConditionalGeneration 中传递 quant_config 和 prefix，并在 vision tower 和 audio tower 初始化后调用 recursive_replace_linear 替换其内部线性层。

3. 新增 vllm/model_executor/layers/quantization/bitsandbytes.py 中的 BitsAndBytesWeightParameter 类，通过 cached_property 提供正确的 dtype，避免量化参数 dtype 不匹配导致加载失败。

4. 在 vllm/model_executor/model_loader/bitsandbytes_loader.py 的 _stack_quantization_states 方法中，对 attention_k_eq_v=True 的模型（如 Gemma4）复制 k_proj 的量化状态到 v_proj，解决量化状态缺失问题。

关键文件：

• vllm/model_executor/models/transformers/utils.py（模块 公共工具；类别 source；类型 core-logic；符号 recursive_replace_linear, _recursive_replace）: 核心新增函数，提供递归替换线性层的通用工具，是本次变更的基石。
• vllm/model_executor/models/gemma4_mm.py（模块 模型定义；类别 source；类型 core-logic；符号 Gemma4MultimodalEmbedder.init, Gemma4ForConditionalGeneration.init）: 在 ViT 和嵌入器中调用递归替换，集成量化支持，并调整初始化流程。
• vllm/model_executor/layers/quantization/bitsandbytes.py（模块 量化层；类别 source；类型 data-contract；符号 BitsAndBytesWeightParameter）: 新增 BitsAndBytesWeightParameter 解决 dtype 不匹配，是量化兼容性修复的关键。
• vllm/model_executor/model_loader/bitsandbytes_loader.py（模块 权重加载；类别 source；类型 bugfix；符号 _stack_quantization_states）: 修复 Gemma4 k_eq_v 配置下量化状态重复问题，确保 v_proj 获得正确参数。

关键符号：recursive_replace_linear, _recursive_replace, BitsAndBytesWeightParameter.dtype

关键源码片段

vllm/model_executor/models/transformers/utils.py

核心新增函数，提供递归替换线性层的通用工具，是本次变更的基石。

def recursive_replace_linear(
    model: nn.Module,
    quant_config: "QuantizationConfig | None",
    prefix: str = "",
):
    """Recursively replace linear modules in the model as needed."""
​
    def _recursive_replace(module: nn.Module, prefix: str):
        for child_name, child_module in module.named_children():
            new_module = child_module
            qual_name = maybe_prefix(prefix, child_name)
            # 遇到 nn.Linear 就替换为 vLLM 原生线性层
            if isinstance(child_module, nn.Linear):
                style = "replicate"
                new_module = replace_linear_class(
                    child_module,
                    style,
                    quant_config,
                    prefix=qual_name,
                )
            else:
                # 非 Linear 则递归进入子模块
                _recursive_replace(child_module, prefix=qual_name)
            if new_module is not child_module:
                setattr(module, child_name, new_module)
​
    _recursive_replace(model, prefix=prefix)

评论区精华

Isotr0py 请求 linitra24 测试 ViT LoRA 兼容性，后者测试后反馈 LoRA 加载成功但推理准确性存在问题，将在后续继续排查。Reviewer jeejeelee 和 mgoin 已批准。

• ViT LoRA 兼容性测试 (correctness): 准确性问题将在合并后继续排查。

风险与影响

• 风险：
  • 递归替换可能对非量化场景带来微小性能开销（原本 PyTorch 直接优化 nn.Linear）
  • BitsAndBytesWeightParameter 的 dtype 依赖 get_default_dtype()，若上下文默认 dtype 不符预期可能导致精度问题
  • k_eq_v 量化状态重复假设严格，若模型结构不一致可能触发断言失败
  • LoRA 推理准确性尚未完全验证，可能影响生产使用
• 影响：
  • 用户影响：直接消除 Gemma4-MM 量化模型无法启动或推理错误的问题，使 BNB 4bit/8bit 正常使用
  • 系统影响：引入的 recursive_replace_linear 可作为通用工具用于未来模型，提升维护性
  • 团队影响：减少模型特定补丁依赖，但需关注 LoRA 准确性和回归测试
  • 风险标记：dtype 潜在不匹配, 递归替换影响非量化性能, k_eq_v 假设严格, LoRA 准确性待验证

关联脉络

• PR #42825 Model-specific ViT quantization fix: 本 PR 旨在替代该模型特定补丁，使用通用递归替换方法。
• PR #43440 Attention mask limit for MMEncoderAttention: 该 PR 的注意力掩码限制使得无法替换常见线性层，故本 PR 仅替换线性层。
• PR #43529 Migrate bitsandbytes support to OOT plugin: 该迁移将使模型特定补丁不可用，本 PR 提前适应通用方案。