hqq-quantization

用途

HQQ（Half-Quadratic Quantization，半二次量化）是一种面向大语言模型的权重量化方法，其核心特点是无需校准数据（calibration-free）。当需要在不准备样本数据集的情况下对模型进行量化，或需要快速完成量化（相比 GPTQ/AWQ 的耗时以分钟计而非小时计），以及需要部署到 vLLM 或 HuggingFace Transformers、用 LoRA/PEFT 微调量化模型、或尝试 2 比特乃至 1 比特极端量化时，可以使用 HQQ。

主要能力

免校准：无需样本数据即可对任意模型即时量化。
多后端：支持 PyTorch、ATEN、TorchAO、Marlin、BitBlas 等优化推理后端。
灵活精度：支持 8/4/3/2/1 比特，并可配置分组大小（group size）。
框架集成：原生支持 HuggingFace 与 vLLM。
PEFT 兼容：可用 LoRA 微调量化后的模型。
混合精度：可按层类型（如注意力层与 MLP 层）设置不同量化配置。

使用方式

安装：

pip install hqq

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

基础量化：使用 BaseQuantizeConfig 配置 nbits、group_size、axis，再用 HQQLinear 替换 nn.Linear。

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

config = BaseQuantizeConfig(
    nbits=4,
    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

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"
)

后端设置：可全局或按层设置，例如 HQQLinear.set_backend("torchao_int4") 或 hqq_layer.set_backend("marlin")。可选后端包括 pytorch、pytorch_compile、aten、torchao_int4、gemlite、bitblas、marlin。

加载与保存：可从 Hub 加载已量化模型（如 mobiuslabsgmbh/Llama-3.1-8B-HQQ-4bit），也可量化后用 save_pretrained 保存或 push_to_hub 推送。

vLLM 集成：加载时指定 quantization="hqq"，并可传入自定义 quantization_config。

PEFT/LoRA 微调：加载量化模型后应用 LoraConfig 与 get_peft_model，再配合 Trainer 进行 QLoRA 风格训练。

适用场景

快速模型压缩：无需校准数据，直接量化并验证生成质量。
推理速度优化：选择 Marlin、TorchAO 等后端，并可配合 torch.compile。
混合精度量化：注意力层保持较高精度，MLP 层进一步压缩以节省显存。
量化模型微调：通过 LoRA 在量化模型上继续训练。

限制与注意事项

若需要基于校准的精度或生产级服务，可考虑 AWQ；若有校准数据并追求最高精度，可考虑 GPTQ；若只需简单 8/4 比特且不需要自定义后端，可考虑 bitsandbytes；若面向 CPU 推理或 Apple Silicon 部署，可考虑 llama.cpp/GGUF。
量化时显存不足可改用逐层加载（device_map="sequential"）。
推理慢可切换优化后端或使用 torch.compile。
2 比特质量不佳时可减小 group size（如 16）。
建议从 4 比特开始，group_size 取 64；Marlin 需要 Ampere 及以上 GPU。

资源

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

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项

资源