Transformers documentation

HQQ

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

HQQ

Half-Quadratic Quantization (HQQ) 仅从权重中优化其量化参数,因此无需校准数据。您可以在加载模型时,使用它将模型量化至最低 1 或 2 位。

下表总结了 HQQ 在 Transformers 中的支持情况。

配置HqqConfig
quant_methodhqq
工作流加载时量化
位1, 2, 3, 4, 8
硬件CUDA、XPU
保存✅
微调✅
自动编译❌

安装 HQQ

安装 hqq 0.2.1 或更高版本。

pip install -U hqq

使用 HQQ 量化模型

创建一个 HqqConfig 并将其传递给 from_pretrained()。下面的示例将每个线性层量化为 4 位,每 64 个权重为一组。

import torch
from transformers import AutoModelForCausalLM, HqqConfig

quantization_config = HqqConfig(nbits=4, group_size=64)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    quantization_config=quantization_config,
    device_map="cuda",
)

配置 HQQ

这些 HqqConfig 参数会改变权重的量化方式。

参数默认效果
nbits4每个权重的位数。支持 8、4、3、2 和 1。
group_size64共享缩放因子和零点的权重数量。更小的分组精度更高,但会占用更多内存。
axis1用于对权重进行分组的轴,取值为 0 或 1。速度更快的 torchao 和 BitBlas 后端仅支持 1。
view_as_floatFalse以浮点数据类型存储量化后的权重,用于分布式训练。
skip_modules["lm_head"]要保留未量化的层类型。

使用不同的设置量化层类型

将 dynamic_config 传入,以使用各自的设置对每种类型的线性层进行量化。每个键都是一个 层标签,即模块名称去掉 model、layers 和层编号后的部分。例如,model.layers.3.self_attn.q_proj 的标签为 self_attn.q_proj。

下面的示例将注意力投影量化为 4 位,将 MLP 投影量化为 3 位。

q4_config = {"nbits": 4, "group_size": 64}
q3_config = {"nbits": 3, "group_size": 32}
quantization_config = HqqConfig(dynamic_config={
    "self_attn.q_proj": q4_config,
    "self_attn.k_proj": q4_config,
    "self_attn.v_proj": q4_config,
    "self_attn.o_proj": q4_config,
    "mlp.gate_proj": q3_config,
    "mlp.up_proj": q3_config,
    "mlp.down_proj": q3_config,
})

标签适用于每个解码器层中的该层类型,因此无法为某个解码器层设置与其他层不同的配置。dynamic_config 中未包含其标签的线性层将保持未量化状态。相同的标签也用于匹配 skip_modules。

选择后端

HQQ 通过 hqq 库中的后端来运行量化层。PyTorch 和 CUDA 后端支持 PEFT 微调以及较旧的 GPU。使用 HQQLinear.set_backend 切换后端。

from hqq.core.quantize import HQQBackend, HQQLinear

HQQLinear.set_backend(HQQBackend.PYTORCH)

为了获得更快的 4 位推理速度,请在加载量化模型后,将其转换为融合内核后端,例如 torchao。torchao 后端需要 axis=1,这也是默认值。

from hqq.utils.patching import prepare_for_inference

prepare_for_inference(model, backend="torchao_int4")

有关可用的后端,请参阅 hqq Backend 指南。

局限性

  • HQQ 无法卸载到 CPU 或磁盘。使用包含 "cpu" 或 "disk" 的 device_map 进行加载时,会引发 ValueError。
  • 层标签无法针对单个解码器层,因此 dynamic_config 和 skip_modules 会应用于整个模型中的该层类型。

资源

Update on GitHub