名称: hqq-quantization 描述: 用于LLMs的无校准数据半二次量化。当需要将模型量化到4/3/2-bit精度而无需校准数据集时使用，适用于快速量化工作流，或与vLLM或HuggingFace Transformers部署。版本: 1.0.0 作者: Orchestra Research 许可证: MIT 标签: [量化, HQQ, 优化, 内存效率, 推理, 模型压缩] 依赖项: [hqq>=0.2.0, torch>=2.0.0]

HQQ - 半二次量化

快速、无需校准的权重量化，支持8/4/3/2/1-bit精度，并提供多种优化后端。

何时使用HQQ

使用HQQ当:

量化模型无需校准数据（无需数据集）
需要快速量化（分钟级 vs GPTQ/AWQ的小时级）
与vLLM或HuggingFace Transformers部署
使用LoRA/PEFT微调量化模型
实验极端量化（2-bit、1-bit）

关键优势:

无需校准: 无需样本数据即可即时量化任何模型
多后端支持: PyTorch、ATEN、TorchAO、Marlin、BitBlas，用于优化推理
灵活精度: 8/4/3/2/1-bit，可配置组大小
框架集成: 原生支持HuggingFace和vLLM
PEFT兼容: 使用LoRA微调量化模型

使用替代方案当:

AWQ: 需要基于校准的准确性，生产环境服务
GPTQ: 有校准数据时追求最大准确性
bitsandbytes: 简单8-bit/4-bit，无需自定义后端
llama.cpp/GGUF: CPU推理，苹果芯片部署

快速入门

安装

pip install hqq

# 安装特定后端
pip install hqq[torch]      # PyTorch后端
pip install hqq[torchao]    # TorchAO int4后端
pip install hqq[bitblas]    # BitBlas后端
pip install hqq[marlin]     # Marlin后端

基本量化

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

# 配置量化
config = BaseQuantizeConfig(
    nbits=4,           # 4-bit量化
    group_size=64,     # 量化组大小
    axis=1             # 沿输出维度量化
)

# 量化线性层
linear = nn.Linear(4096, 4096)
hqq_linear = HQQLinear(linear, config)

# 正常使用
output = hqq_linear(input_tensor)

使用HuggingFace量化完整模型

from transformers import AutoModelForCausalLM, HqqConfig

# 配置HQQ
quantization_config = HqqConfig(
    nbits=4,
    group_size=64,
    axis=1
)

# 加载并量化
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B",
    quantization_config=quantization_config,
    device_map="auto"
)

# 模型已量化并准备使用

核心概念

量化配置

HQQ使用BaseQuantizeConfig定义量化参数：

from hqq.core.quantize import BaseQuantizeConfig

# 标准4-bit配置
config_4bit = BaseQuantizeConfig(
    nbits=4,           # 每权重比特数（1-8）
    group_size=64,     # 每量化组权重数
    axis=1             # 0=输入维度，1=输出维度
)

# 激进2-bit配置
config_2bit = BaseQuantizeConfig(
    nbits=2,
    group_size=16,     # 低比特使用更小组
    axis=1
)

# 每层类型混合精度
layer_configs = {
    "self_attn.q_proj": BaseQuantizeConfig(nbits=4, group_size=64),
    "self_attn.k_proj": BaseQuantizeConfig(nbits=4, group_size=64),
    "self_attn.v_proj": BaseQuantizeConfig(nbits=4, group_size=64),
    "mlp.gate_proj": BaseQuantizeConfig(nbits=2, group_size=32),
    "mlp.up_proj": BaseQuantizeConfig(nbits=2, group_size=32),
    "mlp.down_proj": BaseQuantizeConfig(nbits=4, group_size=64),
}

HQQLinear层

核心量化层，替代nn.Linear：

from hqq.core.quantize import HQQLinear
import torch

# 创建量化层
linear = torch.nn.Linear(4096, 4096)
hqq_layer = HQQLinear(linear, config)

# 访问量化权重
W_q = hqq_layer.W_q           # 量化权重
scale = hqq_layer.scale       # 缩放因子
zero = hqq_layer.zero         # 零点

# 反量化以检查
W_dequant = hqq_layer.dequantize()

后端

HQQ支持多种推理后端，适应不同硬件：

from hqq.core.quantize import HQQLinear

# 可用后端
backends = [
    "pytorch",          # 纯PyTorch（默认）
    "pytorch_compile",  # torch.compile优化
    "aten",            # 自定义CUDA内核
    "torchao_int4",    # TorchAO int4矩阵乘法
    "gemlite",         # GemLite CUDA内核
    "bitblas",         # BitBlas优化
    "marlin",          # Marlin 4-bit内核
]

# 全局设置后端
HQQLinear.set_backend("torchao_int4")

# 或每层设置
hqq_layer.set_backend("marlin")

后端选择指南:

后端	最适合	要求
pytorch	兼容性	任何GPU
pytorch_compile	中等加速	torch>=2.0
aten	良好平衡	CUDA GPU
torchao_int4	4-bit推理	torchao已安装
marlin	最大4-bit速度	Ampere+ GPU
bitblas	灵活比特宽度	bitblas已安装

HuggingFace集成

加载预量化模型

from transformers import AutoModelForCausalLM, AutoTokenizer

# 从Hub加载HQQ量化模型
model = AutoModelForCausalLM.from_pretrained(
    "mobiuslabsgmbh/Llama-3.1-8B-HQQ-4bit",
    device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.1-8B")

# 正常使用
inputs = tokenizer("Hello, world!", return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=50)

量化并保存

from transformers import AutoModelForCausalLM, HqqConfig

# 量化
config = HqqConfig(nbits=4, group_size=64)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B",
    quantization_config=config,
    device_map="auto"
)

# 保存量化模型
model.save_pretrained("./llama-8b-hqq-4bit")

# 推送到Hub
model.push_to_hub("my-org/Llama-3.1-8B-HQQ-4bit")

混合精度量化

from transformers import AutoModelForCausalLM, HqqConfig

# 每层类型不同精度
config = HqqConfig(
    nbits=4,
    group_size=64,
    # 注意力层：更高精度
    # MLP层：更低精度以节省内存
    dynamic_config={
        "attn": {"nbits": 4, "group_size": 64},
        "mlp": {"nbits": 2, "group_size": 32}
    }
)

vLLM集成

使用vLLM服务HQQ模型

from vllm import LLM, SamplingParams

# 加载HQQ量化模型
llm = LLM(
    model="mobiuslabsgmbh/Llama-3.1-8B-HQQ-4bit",
    quantization="hqq",
    dtype="float16"
)

# 生成
sampling_params = SamplingParams(temperature=0.7, max_tokens=100)
outputs = llm.generate(["What is machine learning?"], sampling_params)

vLLM使用自定义HQQ配置

from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-3.1-8B",
    quantization="hqq",
    quantization_config={
        "nbits": 4,
        "group_size": 64
    }
)

PEFT/LoRA微调

微调量化模型

from transformers import AutoModelForCausalLM, HqqConfig
from peft import LoraConfig, get_peft_model

# 加载量化模型
quant_config = HqqConfig(nbits=4, group_size=64)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B",
    quantization_config=quant_config,
    device_map="auto"
)

# 应用LoRA
lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM"
)

model = get_peft_model(model, lora_config)

# 使用Trainer或自定义循环正常训练

QLoRA风格训练

from transformers import TrainingArguments, Trainer

training_args = TrainingArguments(
    output_dir="./hqq-lora-output",
    per_device_train_batch_size=4,
    gradient_accumulation_steps=4,
    learning_rate=2e-4,
    num_train_epochs=3,
    fp16=True,
    logging_steps=10,
    save_strategy="epoch"
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    data_collator=data_collator
)

trainer.train()

量化工作流

工作流1：快速模型压缩

from transformers import AutoModelForCausalLM, AutoTokenizer, HqqConfig

# 1. 配置量化
config = HqqConfig(nbits=4, group_size=64)

# 2. 加载并量化（无需校准！）
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B",
    quantization_config=config,
    device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.1-8B")

# 3. 验证质量
prompt = "The capital of France is"
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=20)
print(tokenizer.decode(outputs[0]))

# 4. 保存
model.save_pretrained("./llama-8b-hqq")
tokenizer.save_pretrained("./llama-8b-hqq")

工作流2：优化推理速度

from hqq.core.quantize import HQQLinear
from transformers import AutoModelForCausalLM, HqqConfig

# 1. 使用优化后端量化
config = HqqConfig(nbits=4, group_size=64)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B",
    quantization_config=config,
    device_map="auto"
)

# 2. 设置快速后端
HQQLinear.set_backend("marlin")  # 或 "torchao_int4"

# 3. 编译以进一步加速
import torch
model = torch.compile(model)

# 4. 基准测试
import time
inputs = tokenizer("Hello", return_tensors="pt").to(model.device)
start = time.time()
for _ in range(10):
    model.generate(**inputs, max_new_tokens=100)
print(f"平均时间: {(time.time() - start) / 10:.2f}s")

最佳实践

从4-bit开始: 对于大多数模型，最佳质量/大小平衡
使用group_size=64: 良好平衡；极端量化时使用更小组
明智选择后端: 4-bit Ampere+用Marlin，灵活性用TorchAO
验证质量: 量化后始终测试生成质量
混合精度: 保持注意力更高精度，更多压缩MLP
PEFT训练: 使用LoRA r=16-32以获得良好微调结果

常见问题

量化期间内存不足:

# 逐层量化
from hqq.models.hf.base import AutoHQQHFModel

model = AutoHQQHFModel.from_pretrained(
    "meta-llama/Llama-3.1-8B",
    quantization_config=config,
    device_map="sequential"  # 顺序加载层
)

推理缓慢:

# 切换到优化后端
from hqq.core.quantize import HQQLinear
HQQLinear.set_backend("marlin")  # 要求Ampere+ GPU

# 或编译
model = torch.compile(model, mode="reduce-overhead")

2-bit质量差:

# 使用更小组大小
config = BaseQuantizeConfig(
    nbits=2,
    group_size=16,  # 更小组帮助低比特
    axis=1
)

参考

高级用法 - 自定义后端、混合精度、优化
故障排除 - 常见问题、调试、基准测试

资源

仓库: https://github.com/mobiusml/hqq
论文: Half-Quadratic Quantization
HuggingFace模型: https://huggingface.co/mobiuslabsgmbh
版本: 0.2.0+
许可证: Apache 2.0