半二次量化 (HQQ)

本仓库包含我们在以下文章中提出的半二次量化的官方实现：

• HQQ：https://dropbox.github.io/hqq_blog/
• HQQ+：https://dropbox.github.io/1bit_blog/

什么是HQQ？

HQQ 是一种快速且精确的模型量化工具，无需校准数据即可使用。您可以在短短几分钟内对最大规模的模型进行量化，完全不需要校准数据 🚀。

常见问题解答

为什么我应该选择HQQ而不是其他量化方法？

• HQQ 量化模型的速度非常快。
• 它支持 8、4、3、2、1 位量化。
• 您可以将其应用于任何模型（如大语言模型、视觉模型等）。
• 反量化步骤是一个线性操作，这意味着 HQQ 可以与各种优化的 CUDA/Triton 内核兼容。
• HQQ 与 PEFT 训练兼容。
• 我们正在努力使 HQQ 完全兼容 `torch.compile`，以加速推理和训练。

量化后的模型质量如何？
我们针对语言和视觉模型进行了详细的基准测试。请参阅我们的博客文章：HQQ 和 HQQ+。

量化后的模型运行速度如何？
使用 axis=1 的 4 位模型可以利用优化的融合推理内核。此外，我们正致力于让 HQQ 完全兼容 torch.compile，从而加速训练和推理。更多细节请参阅下方的后端部分。

我应该使用哪些量化设置？
建议从 nbits=4, group_size=64, axis=1 开始。这些设置在质量、显存占用和速度之间提供了良好的平衡。如果您希望在相同显存占用下获得更好的效果，可以切换到 axis=0 并使用 ATEN 后端，但该设置目前不支持快速推理。

axis 参数是什么意思？
axis 参数指定了分组操作沿哪个维度进行。通常情况下，axis=0 比 axis=1 效果更好，尤其是在低比特量化时。然而，目前优化的推理运行时仅支持 axis=1。

HQQ 和 HQQ+ 有什么区别？
HQQ+ 是在 HQQ 的基础上加入了可训练的低秩适配器，以提升低比特量化下的模型质量。

安装

首先，请确保您安装的 PyTorch 2 版本与您的 CUDA 版本匹配：https://pytorch.org/

您可以通过以下方式安装 hqq：

# 最新稳定版
pip install hqq;

# 最新更新 - 推荐
pip install git+https://github.com/dropbox/hqq.git;

# 禁用构建 ATEN 后端的 CUDA 内核
DISABLE_CUDA=1 pip install ...

或者，您可以克隆仓库，并在此目录下运行 pip install .。

基本用法

要使用 HQQ 进行量化，只需将线性层（torch.nn.Linear）替换为如下代码：

from hqq.core.quantize import *
# 量化配置
quant_config = BaseQuantizeConfig(nbits=4, group_size=64)

# 替换您的线性层
hqq_layer = HQQLinear(your_linear_layer, # torch.nn.Linear 或 None
                      quant_config=quant_config, # 量化配置
                      compute_dtype=torch.float16, # 计算数据类型
                      device='cuda', # CUDA 设备
                      initialize=True, # 使用 False 可稍后再量化
                      del_orig=True # 如果为 True，则删除原始层
                      )

W_r = hqq_layer.dequantize() # 反量化
W_q = hqq_layer.unpack(dtype=torch.uint8) # 解包
y   = hqq_layer(x) # 前向传播

量化参数的设置如下：

• nbits（整数）：支持 8、4、3、2、1 位。
• group_size（整数）：只要 weight.numel() 能被 group_size 整除即可，无限制。
• view_as_float（布尔值）：如果为 True，则将量化后的参数视为浮点数，而非整数类型。

与模型结合使用

Transformers 🤗

关于与 Hugging Face Transformers 结合使用的说明，请参阅 文档中的示例：

from transformers import AutoModelForCausalLM, HqqConfig

# 所有线性层将使用相同的量化配置
quant_config = HqqConfig(nbits=4, group_size=64)

# 加载并量化
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.float16,
    device_map="cuda",
    quantization_config=quant_config
)

您可以像普通 Transformers 模型一样使用 save_pretrained 和 from_pretrained 来保存和加载量化后的模型。

HQQ 库

您也可以使用 HQQ 库来量化 Transformers 模型：

# 在 CPU 上加载模型
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=compute_dtype)

# 量化
from hqq.models.hf.base import AutoHQQHFModel
quant_config = BaseQuantizeConfig(nbits=4, group_size=64)
AutoHQQHFModel.quantize_model(model, quant_config=quant_config, compute_dtype=compute_dtype, device=device)

您可以按照以下方式保存和加载量化后的模型：

from hqq.models.hf.base import AutoHQQHFModel

# 保存：务必在任何补丁之前保存模型
AutoHQQHFModel.save_quantized(model, save_dir)

# 以 safetensors 格式保存（可通过 Transformers 或 VLLM 加载）
AutoHQQHFModel.save_to_safetensors(model, save_dir)

# 加载
model = AutoHQQHFModel.from_quantized(save_dir)

❗ 请注意，通过 HQQ 库保存的模型与 .from_pretrained() 不兼容。

后端

原生后端

HQQLinear 模块可以使用以下原生反量化后端：

HQQLinear.set_backend(HQQBackend.PYTORCH)          # PyTorch 后端 - 默认
HQQLinear.set_backend(HQQBackend.PYTORCH_COMPILE)  # 编译后的 PyTorch
HQQLinear.set_backend(HQQBackend.ATEN)             # Aten/CUDA 后端 - 仅支持 axis=0

❗ 注意，HQQBackend.ATEN 仅支持 axis=0。

优化推理

我们支持外部后端以实现更快的推理，并采用融合内核。在模型完成量化后，您可以按如下方式启用其中一个后端：

from hqq.utils.patching import prepare_for_inference

# PyTorch 后端，使模型与 fullgraph torch.compile 兼容：适用于任何设置
# prepare_for_inference(model)

# Gemlite 后端：nbits=4/2/1，compute_dtype=float16，axis=1
prepare_for_inference(model, backend="gemlite") 

# Torchao 的 tiny_gemm 后端（batch-size<4 时速度快）：nbits=4，compute_dtype=bfloat16，axis=1
# prepare_for_inference(model, backend="torchao_int4")

请注意，这些后端仅适用于 axis=1。此外，根据不同的后端，还存在关于组大小值的额外限制。在 RTX 4090 上，使用 Llama3-8B 的 4 位量化模型时，预计每秒可处理约 158 个 token。

当指定的推理后端不支持某个量化配置时，hqq 将回退到原生后端。

自定义量化配置 ⚙️

您可以通过为每个层名称指定设置，为不同层配置各种量化方案：

Transformers 🤗

# 具有相同标签的每个线性层将使用专用的量化配置
q4_config = {'nbits':4, 'group_size':64}
q3_config = {'nbits':3, 'group_size':32}

quant_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,
})

HQQ 库

from hqq.core.quantize import *
q4_config    = BaseQuantizeConfig(nbits=4, group_size=64) 
q3_config    = BaseQuantizeConfig(nbits=3, group_size=32)

quant_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,
}

VLLM

您可以在 vllm 中使用 HQQ。请确保在使用该后端之前安装 GemLite。

# 或者您也可以进行在线量化
from hqq.utils.vllm import set_vllm_onthefly_hqq_quant
skip_modules = ['lm_head', 'visual', 'vision']

# 选择以下模式之一：

# INT/FP 格式
set_vllm_onthefly_hqq_quant(weight_bits=8, group_size=None, quant_mode='int8_weightonly', skip_modules=skip_modules) #A16W8 - 仅 INT8 权重
set_vllm_onthefly_hqq_quant(weight_bits=4, group_size=128, quant_mode='int4_weightonly', skip_modules=skip_modules) #A16W4 - 仅 HQQ 权重
set_vllm_onthefly_hqq_quant(weight_bits=8, quant_mode='int8_dynamic', skip_modules=skip_modules) #A8W8 - 动态 INT8 x INT8
set_vllm_onthefly_hqq_quant(weight_bits=8, quant_mode='fp8_dynamic', skip_modules=skip_modules) #A8W8 - 动态 FP8 x FP8

# MXFP 格式
set_vllm_onthefly_hqq_quant(weight_bits=8, group_size=None, quant_mode='mxfp8_dynamic', skip_modules=skip_modules) #A8W8 - MXFP8 x MXPF8 - post_scale=True
set_vllm_onthefly_hqq_quant(weight_bits=8, group_size=32, quant_mode='mxfp8_dynamic', skip_modules=skip_modules) #A8W8 - MXFP8 x MXPF8 - post_scale=False
set_vllm_onthefly_hqq_quant(weight_bits=4, quant_mode='mxfp4_weightonly', skip_modules=skip_modules) #A16W4 - 仅 MXFP4 权重
set_vllm_onthefly_hqq_quant(weight_bits=4, quant_mode='mxfp8_dynamic', skip_modules=skip_modules) #A8W4 - 动态 MXFP8 x MXFP4
set_vllm_onthefly_hqq_quant(weight_bits=4, quant_mode='mxfp4_dynamic', skip_modules=skip_modules) #A4W4 - 动态 MXPF4 x MXPF4
set_vllm_onthefly_hqq_quant(weight_bits=4, quant_mode='nvfp4_dynamic', skip_modules=skip_modules) #A4W4 - 动态 NVFP4 x NVFP4


llm = LLM(model="meta-llama/Llama-3.2-3B-Instruct", max_model_len=4096, gpu_memory_utilization=0.80, dtype=torch.float16)

Peft 训练

Peft 训练在 HuggingFace 的 peft 库中得到直接支持。如果您仍想使用 hqq-lib 的 peft 工具，操作方法如下：

# 首先，量化或加载一个已量化的 HQQ 模型
from hqq.core.peft import PeftUtils

base_lora_params = {'lora_type':'default', 'r':32, 'lora_alpha':64, 'dropout':0.05, 'train_dtype':torch.float32}
lora_params      = {'self_attn.q_proj': base_lora_params,
                    'self_attn.k_proj': base_lora_params,
                    'self_attn.v_proj': base_lora_params,
                    'self_attn.o_proj': base_lora_params,
                    'mlp.gate_proj'   : None,
                    'mlp.up_proj'     : None,
                    'mlp.down_proj'   : None}


# 将 LoRA 添加到线性/HQQ 模块
PeftUtils.add_lora(model, lora_params)

# 可选：设置您的后端
HQQLinear.set_backend(HQQBackend.ATEN if axis==0 else HQQBackend.PYTORCH_COMPILE)

# 开始训练....

# 将 LoRA 权重转换为与模型相同的数据类型，以加快推理速度
model.eval()
PeftUtils.cast_lora_weights(model, dtype=compute_dtype)

# 保存 LoRA 权重
PeftUtils.save_lora_weights(model, filename)

# 加载 LoRA 权重：会自动调用 add_lora
PeftUtils.load_lora_weights(model, filename)

我们提供了一个完整的示例，展示如何使用 HQQ/LoRA 训练模型，您可以在 examples/hqq_plus.py 中找到该示例。

如果您希望通过 FSDP 进行多 GPU 训练，请查看 Answer.AI 提供的优秀仓库：https://github.com/AnswerDotAI/fsdp_qlora

示例

我们在 examples 目录中提供了多种示例，展示了在不同后端上对模型进行量化的过程。

引用 📜

@misc{badri2023hqq,
title  = {大型机器学习模型的半二次量化},
url    = {https://dropbox.github.io/hqq_blog/},
author = {Hicham Badri 和 Appu Shaji},
month  = {十一月},
year   = {2023}

HQQ 快速上手指南

HQQ (Half-Quadratic Quantization) 是一款快速且高精度的模型量化工具，最大特点是不需要校准数据即可对大型模型（如 LLM、视觉模型）进行量化。支持 8/4/3/2/1 bit 多种精度，并兼容 PEFT 训练和 torch.compile。

环境准备

• 操作系统: Linux / Windows / macOS
• Python: 建议 3.8+
• PyTorch: 版本需 >= 2.0，且必须与本地 CUDA 版本匹配。
  • 安装前请确认环境：访问 PyTorch 官网 获取对应命令。
• 硬件: 推荐使用 NVIDIA GPU 以获得最佳推理速度（支持 CUDA 后端）。

安装步骤

推荐使用 pip 直接安装最新稳定版或开发版。国内用户若遇网络问题，可配置清华或阿里镜像源。

方式一：安装最新稳定版

pip install hqq
# 国内加速示例
# pip install hqq -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：安装最新开发版（推荐，包含最新优化）

pip install git+https://github.com/dropbox/hqq.git
# 国内加速示例
# pip install git+https://github.com/dropbox/hqq.git -i https://pypi.tuna.tsinghua.edu.cn/simple

方式三：禁用 CUDA 内核构建（仅使用纯 PyTorch 后端） 如果编译环境缺少 CUDA 工具链，可使用此命令：

DISABLE_CUDA=1 pip install hqq

或者克隆仓库后安装：

git clone https://github.com/dropbox/hqq.git
cd hqq
pip install .

基本使用

1. 核心用法：替换线性层

这是最基础的使用方式，直接将 torch.nn.Linear 替换为 HQQLinear。

import torch
from hqq.core.quantize import BaseQuantizeConfig, HQQLinear

# 定义量化配置：4-bit, 分组大小 64 (推荐起始配置)
quant_config = BaseQuantizeConfig(nbits=4, group_size=64)

# 假设你有一个原始的 linear 层
# your_linear_layer = torch.nn.Linear(512, 512) 

# 创建 HQQ 线性层并进行量化
hqq_layer = HQQLinear(
    your_linear_layer,          # 原始 torch.nn.Linear 层，若为 None 则稍后初始化
    quant_config=quant_config,  # 量化配置
    compute_dtype=torch.float16,# 计算数据类型
    device='cuda',              # 设备
    initialize=True,            # True: 立即量化; False: 稍后量化
    del_orig=True               # True: 量化后删除原始层以节省显存
)

# 使用前向传播 (自动反量化计算)
# x = torch.randn(1, 512).half().cuda()
# y = hqq_layer(x)

# 手动反量化获取权重 (可选)
# W_r = hqq_layer.dequantize() 

2. 结合 Hugging Face Transformers

快速加载并量化预训练模型。

from transformers import AutoModelForCausalLM, HqqConfig
import torch

model_id = "meta-llama/Llama-2-7b-hf" # 示例模型

# 配置量化参数
quant_config = HqqConfig(nbits=4, group_size=64)

# 直接加载并量化模型
model = AutoModelForCausalLM.from_pretrained(
    model_id, 
    torch_dtype=torch.float16, 
    device_map="cuda", 
    quantization_config=quant_config
)

# 此时 model 已完成量化，可直接用于推理或保存
# model.save_pretrained("./quantized_model")

3. 进阶：使用 HQQ 库量化已加载的模型

如果你已经在一个 CPU 或 GPU 上加载了模型，可以使用 HQQ 专用接口进行转换。

from transformers import AutoModelForCausalLM
from hqq.models.hf.base import AutoHQQHFModel
from hqq.core.quantize import BaseQuantizeConfig
import torch

compute_dtype = torch.float16
device = "cuda"
model_id = "meta-llama/Llama-2-7b-hf"

# 1. 在 CPU 上加载原始模型
model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=compute_dtype)

# 2. 执行量化
quant_config = BaseQuantizeConfig(nbits=4, group_size=64) 
AutoHQQHFModel.quantize_model(
    model, 
    quant_config=quant_config, 
    compute_dtype=compute_dtype, 
    device=device
)

# 3. 保存量化后的模型 (注意：此处不能使用标准的 from_pretrained 加载)
save_dir = "./hqq_quantized_model"
AutoHQQHFModel.save_to_safetensors(model, save_dir)

# 4. 加载量化模型
# loaded_model = AutoHQQHFModel.from_quantized(save_dir)

4. 优化推理速度 (可选)

量化完成后，可通过切换后端或使用融合内核进一步提升推理速度。需确保量化配置为 axis=1。

from hqq.utils.patching import prepare_for_inference

# 启用 Gemlite 后端 (推荐用于 4-bit, axis=1, float16)
# 需先安装 gemlite: pip install git+https://github.com/dropbox/gemlite.git
prepare_for_inference(model, backend="gemlite")

# 或者启用 torch.compile 优化
# prepare_for_inference(model)