【Bug已解决】Add support for Gemma4ClippableLinear (Gemma 4 QLoRA fails) 解决方案一、现象长什么样给Gemma 4做QLoRA4-bit NF4 量化 LoRA时加载/训练直接失败ValueError: Gemma4ClippableLinear cannot be quantized with BitsAndBytes (no .weight as nn.Linear)或TypeError: prepare_model_for_kbit_training got unexpected module type Gemma4ClippableLinear根因是QLoRA 需要把模型权重做 4-bit 量化而 BitsAndBytes 的量化路径只认标准nn.Linear它替换module.weight为QuantizedLinear。Gemma 4 的Gemma4ClippableLinear是自定义层权重可能在子模块self.linear.weight或属性名不同BitsAndBytes 量化时找不到标准weightQLoRA 直接失败。本文讲清 QLoRA 下这个自定义层为何失败、如何支持。二、背景QLoRA 的两步量化k-bitprepare_model_for_kbit_training/BitsAndBytesConfig把模型里每个nn.Linear的weight替换成 4-bit 量化表示Linear4bit等base_layer变成量化层挂 LoRA在量化后的层上注入 LoRA A/B。问题卡在第 1 步。BitsAndBytes的量化函数大致逻辑def quantize(module): if isinstance(module, nn.Linear): module.weight bnb.nn.Params4bit(module.weight) # 需要 module.weightGemma4ClippableLinear不是nn.Linear或weight在self.linear.weightisinstance检查失败或module.weight不存在量化跳过/报错QLoRA 失败。注意这和 348 篇纯 LoRA 支持是同一根因的不同表现——纯 LoRA 是“不识别”QLoRA 是“量化也失败”。本文聚焦量化路径如何适配这个自定义层。三、根因根因 ABitsAndBytes 量化只认nn.Linear最直接。量化函数isinstance(m, nn.Linear)m.weight自定义层不满足。根因 B自定义层权重在子模块Gemma4ClippableLinear的权重在self.linear.weight顶层没有weight属性量化函数找不到。根因 Cprepare_model_for_kbit_training的类型白名单不含自定义层PEFT 的 kbit 准备函数有“可量化模块”白名单没列Gemma4ClippableLinear跳过。根因 D量化后 LoRA base 指向错误的层即使量化成功LoRA 的base_layer没正确指向量化后的内部 linear前向失败。根因小结QLoRA 量化路径只认标准nn.Linear自定义Gemma4ClippableLinear不被量化修复让量化函数识别自定义层指向内部 linear 量化或让自定义层继承nn.Linear量化和 LoRA 两步都要正确适配。四、最小可运行复现下面脚本模拟“量化函数只认 nn.Linear自定义层被跳过/失败”与适配import torch import torch.nn as nn class Gemma4ClippableLinear(nn.Module): def __init__(self, in_f, out_f): super().__init__() self.linear nn.Linear(in_f, out_f) def forward(self, x): return self.linear(x) def quantize_module(module): # 模拟 BitsAndBytes只量化 nn.Linear if isinstance(module, nn.Linear): module.weight nn.Parameter(module.weight.half()) # 伪量化 return True return False def demo(): layer Gemma4ClippableLinear(16, 8) ok quantize_module(layer) # 顶层不是 nn.Linear - False print(直接量化自定义层:, ok) # False - QLoRA 失败 # 适配量化其内部 linear ok2 quantize_module(layer.linear) print(量化内部 linear:, ok2) # True - 成功 x torch.randn(2, 16) out layer(x) print(量化后前向形状:, tuple(out.shape)) if __name__ __main__: demo()运行后直接量化自定义层失败False量化其内部linear成功证明适配方案。五、解决方案第一层最小直接修复量化时把Gemma4ClippableLinear的内部linear当标准 Linear 量化再挂 LoRAimport torch from transformers import BitsAndBytesConfig from peft import get_peft_model, LoraConfig # 1) 先把模型里所有 Gemma4ClippableLinear 的内部 linear 量化 # 最稳让 Gemma4ClippableLinear 继承 nn.Linear见第六层则自动被量化 bnb_config BitsAndBytesConfig( load_in_4bitTrue, bnb_4bit_quant_typenf4, bnb_4bit_compute_dtypetorch.bfloat16, ) model AutoModelForCausalLM.from_pretrained( google/gemma-4, quantization_configbnb_config, device_mapauto ) # 2) 挂 LoRAtarget 指向内部 linear 或标准命名 config LoraConfig(r4, target_modules[q_proj, v_proj]) model get_peft_model(model, config)若不能改模型定义用自定义量化遍历def quantize_clippable(model): for name, module in model.named_modules(): if isinstance(module, Gemma4ClippableLinear): # 量化其内部 linear复用 bnb 的量化 module.linear bnb.nn.Linear4bit( module.linear.in_features, module.linear.out_features, biasmodule.linear.bias is not None, )六、解决方案第二层结构性改进6.1 让Gemma4ClippableLinear继承nn.Linearclass Gemma4ClippableLinear(nn.Linear): def __init__(self, in_f, out_f, **kw): super().__init__(in_f, out_f, **kw) self.clip_ratio 1.0 def forward(self, x): return super().forward(x)这样isinstance(m, nn.Linear)通过BitsAndBytes 自动量化QLoRA 直接可用。6.2 给 PEFT/transformers 提 PR注册 Gemma 4 量化映射社区修复在 kbit 准备的“可量化模块”白名单里加Gemma4ClippableLinear并指明其内部 linear 属性名。6.3 升级 transformers/peft/bitsandbytespip install -U transformers peft bitsandbytes新版可能已支持 Gemma 4 的量化。七、解决方案第三层断言 / CI 守护import torch import pytest import torch.nn as nn def test_clippable_inherits_linear(layer_factory): layer layer_factory(16, 8) assert isinstance(layer, nn.Linear), 应继承 nn.Linear 以便量化 def test_quantize_internal_linear(model_gemma4): # 守护Gemma4ClippableLinear 的内部 linear 被量化 quantized False for m in model_gemma4.modules(): if isinstance(m, nn.Linear) and getattr(m, weight, None) is not None: if m.weight.dtype in (torch.uint8, torch.int8): quantized True assert quantized, 未找到被量化的 Linear def test_qlora_forward(model_gemma4): m get_peft_model(model_gemma4, LoraConfig(r4, target_modules[q_proj])) out m(torch.randint(0, 100, (1, 8))) assert out is not None def test_no_quantize_error(model_gemma4): try: _ get_peft_model(model_gemma4, LoraConfig(r4, target_modules[q_proj])) except (ValueError, TypeError) as e: pytest.fail(fQLoRA 仍失败: {e})CI 跑这四条Gemma 4 QLoRA 支持被守住。八、排查清单Gemma 4 QLoRA 失败时查Gemma4ClippableLinear是nn.Linear子类吗不是则量化函数不认。权重在子模块吗self.linear.weight需被量化。BitsAndBytes 量化只认 nn.Linear 吗自定义层需继承或被映射。kbit 准备白名单含它吗注册自定义层到可量化列表。量化后 LoRA base 指向对吗指向量化后的内部 linear。升级 transformers/peft/bitsandbytes 了吗新版可能内置。CI 测了 Gemma 4 QLoRA 吗加量化前向断言防回归。九、小结“Add support for Gemma4ClippableLinear (Gemma 4 QLoRA fails)” 是QLoRA 量化路径不识别 Gemma 4 的自定义Gemma4ClippableLinear根因BitsAndBytes 量化只认标准nn.Linearmodule.weight自定义层不是 nn.Linear 或权重在子模块量化失败第一层量化其内部linear或让自定义层继承nn.Linear再挂 LoRA第二层让Gemma4ClippableLinear继承nn.Linear、提 PR 注册量化映射、升级库版本第三层pytest 守护“继承 nn.Linear 内部 linear 被量化 QLoRA 前向通过 无量化错误”。一句话Gemma 4 的Gemma4ClippableLinear因不是标准nn.Linear导致 QLoRA 量化失败让它继承nn.Linear或量化其内部linear、注册到 kbit 白名单即可让 4-bit LoRA 正常工作。