hqq-quantization

HQQ - Half-Quadratic Quantization

キャリブレーション不要で高速に重みを量子化でき、8/4/3/2/1ビットの精度に対応し、複数の最適化されたバックエンドを備えています。

HQQを使うべき場合

HQQを使用する場合:

• キャリブレーションデータ（データセットは不要）なしでモデルを量子化する場合
• 高速に量子化したい場合（GPTQ/AWQで数時間かかるところを数分で完了）
• vLLMまたはHuggingFace Transformersでデプロイする場合
• LoRA/PEFTを使って量子化済みモデルをファインチューニングする場合
• 極端な量子化（2ビット、1ビット）を試す場合

主な利点:

• キャリブレーション不要: サンプルデータなしで任意のモデルを即座に量子化できます
• 複数のバックエンド: 最適化された推論のために PyTorch、ATEN、TorchAO、Marlin、BitBlas をサポートします
• 柔軟な精度: 設定可能なグループサイズで 8/4/3/2/1 ビットに対応します
• フレームワーク統合: HuggingFace と vLLM をネイティブにサポートします
• PEFT互換: LoRAで量子化済みモデルをファインチューニングできます

代わりに使うべき手法:

• AWQ: キャリブレーションに基づく精度や本番環境でのサービング提供が必要な場合
• GPTQ: キャリブレーションデータが利用可能で最大限の精度が必要な場合
• bitsandbytes: カスタムバックエンドを必要としない、シンプルな8ビット/4ビット量子化の場合
• llama.cpp/GGUF: CPU推論やApple Siliconへのデプロイの場合

クイックスタート

インストール

pip install hqq

# With specific backend
pip install hqq[torch]      # PyTorch backend
pip install hqq[torchao]    # TorchAO int4 backend
pip install hqq[bitblas]    # BitBlas backend
pip install hqq[marlin]     # Marlin backend

基本的な量子化

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

# Configure quantization
config = BaseQuantizeConfig(
    nbits=4,           # 4-bit quantization
    group_size=64,     # Group size for quantization
    axis=1             # Quantize along output dimension
)

# Quantize a linear layer
linear = nn.Linear(4096, 4096)
hqq_linear = HQQLinear(linear, config)

# Use normally
output = hqq_linear(input_tensor)

HuggingFaceでモデル全体を量子化

from transformers import AutoModelForCausalLM, HqqConfig

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

# Load and quantize
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B",
    quantization_config=quantization_config,
    device_map="auto"
)

# Model is quantized and ready to use

コアコンセプト

量子化設定

HQQでは BaseQuantizeConfig を使って量子化パラメーターを定義します:

from hqq.core.quantize import BaseQuantizeConfig

# Standard 4-bit config
config_4bit = BaseQuantizeConfig(
    nbits=4,           # Bits per weight (1-8)
    group_size=64,     # Weights per quantization group
    axis=1             # 0=input dim, 1=output dim
)

# Aggressive 2-bit config
config_2bit = BaseQuantizeConfig(
    nbits=2,
    group_size=16,     # Smaller groups for low-bit
    axis=1
)

# Mixed precision per layer type
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

# Create quantized layer
linear = torch.nn.Linear(4096, 4096)
hqq_layer = HQQLinear(linear, config)

# Access quantized weights
W_q = hqq_layer.W_q           # Quantized weights
scale = hqq_layer.scale       # Scale factors
zero = hqq_layer.zero         # Zero points

# Dequantize for inspection
W_dequant = hqq_layer.dequantize()

バックエンド

HQQは異なるハードウェア向けに複数の推論バックエンドをサポートします:

from hqq.core.quantize import HQQLinear

# Available backends
backends = [
    "pytorch",          # Pure PyTorch (default)
    "pytorch_compile",  # torch.compile optimized
    "aten",            # Custom CUDA kernels
    "torchao_int4",    # TorchAO int4 matmul
    "gemlite",         # GemLite CUDA kernels
    "bitblas",         # BitBlas optimized
    "marlin",          # Marlin 4-bit kernels
]

# Set backend globally
HQQLinear.set_backend("torchao_int4")

# Or per layer
hqq_layer.set_backend("marlin")

バックエンド選択ガイド:

バックエンド	最適な用途	要件
pytorch	互換性	任意のGPU
pytorch_compile	中程度の高速化	torch>=2.0
aten	良好なバランス	CUDA GPU
torchao_int4	4ビット推論	torchao がインストール済み
marlin	4ビットでの最大速度	Ampere以降のGPU
bitblas	柔軟なビット幅	bitblas がインストール済み

HuggingFace統合

量子化済みモデルの読み込み

from transformers import AutoModelForCausalLM, AutoTokenizer

# Load HQQ-quantized model from Hub
model = AutoModelForCausalLM.from_pretrained(
    "mobiuslabsgmbh/Llama-3.1-8B-HQQ-4bit",
    device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.1-8B")

# Use normally
inputs = tokenizer("Hello, world!", return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=50)

量子化して保存

from transformers import AutoModelForCausalLM, HqqConfig

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

# Save quantized model
model.save_pretrained("./llama-8b-hqq-4bit")

# Push to Hub
model.push_to_hub("my-org/Llama-3.1-8B-HQQ-4bit")

混合精度量子化

from transformers import AutoModelForCausalLM, HqqConfig

# Different precision per layer type
config = HqqConfig(
    nbits=4,
    group_size=64,
    # Attention layers: higher precision
    # MLP layers: lower precision for memory savings
    dynamic_config={
        "attn": {"nbits": 4, "group_size": 64},
        "mlp": {"nbits": 2, "group_size": 32}
    }
)

vLLM統合

vLLMでHQQモデルを提供

from vllm import LLM, SamplingParams

# Load HQQ-quantized model
llm = LLM(
    model="mobiuslabsgmbh/Llama-3.1-8B-HQQ-4bit",
    quantization="hqq",
    dtype="float16"
)

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

カスタムHQQ設定でvLLMを使用

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

# Load quantized 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"
)

# Apply 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)

# Train normally with Trainer or custom loop

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. Configure quantization
config = HqqConfig(nbits=4, group_size=64)

# 2. Load and quantize (no calibration needed!)
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. Verify quality
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. Save
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. Quantize with optimal backend
config = HqqConfig(nbits=4, group_size=64)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B",
    quantization_config=config,
    device_map="auto"
)

# 2. Set fast backend
HQQLinear.set_backend("marlin")  # or "torchao_int4"

# 3. Compile for additional speedup
import torch
model = torch.compile(model)

# 4. Benchmark
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"Avg time: {(time.time() - start) / 10:.2f}s")

ベストプラクティス

1. まずは4ビットから始める: ほとんどのモデルで品質とサイズのバランスが最良です
2. group_size=64を使う: 良好なバランスです。極端な量子化の場合はより小さい値にします
3. バックエンドを慎重に選ぶ: 4ビットのAmpere以降のGPUではMarlin、柔軟性を求めるならTorchAOを選びます
4. 品質を検証する: 量子化後は必ず生成品質をテストします
5. 混合精度: Attentionは高い精度を維持し、MLPをより強く圧縮します
6. PEFTの学習: 良好なファインチューニング結果を得るには、LoRA の r=16-32 を使用します

よくある問題

量子化中にメモリ不足になる場合:

# Quantize layer-by-layer
from hqq.models.hf.base import AutoHQQHFModel

model = AutoHQQHFModel.from_pretrained(
    "meta-llama/Llama-3.1-8B",
    quantization_config=config,
    device_map="sequential"  # Load layers sequentially
)

推論が遅い場合:

# Switch to optimized backend
from hqq.core.quantize import HQQLinear
HQQLinear.set_backend("marlin")  # Requires Ampere+ GPU

# Or compile
model = torch.compile(model, mode="reduce-overhead")

2ビットで品質が低い場合:

# Use smaller group size
config = BaseQuantizeConfig(
    nbits=2,
    group_size=16,  # Smaller groups help at low bits
    axis=1
)

参考資料

• 高度な使い方 - カスタムバックエンド、混合精度、最適化
• トラブルシューティング - よくある問題、デバッグ、ベンチマーク

リソース

• リポジトリ: https://github.com/mobiusml/hqq
• 論文: Half-Quadratic Quantization
• HuggingFace モデル: https://huggingface.co/mobiuslabsgmbh
• バージョン: 0.2.0+
• ライセンス: Apache 2.0