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 以降なら Marlin、柔軟性を重視するなら TorchAO を使います
4. 品質を確認する：量子化後は必ず生成品質をテストしてください
5. 混合精度：アテンションは高い精度に保ち、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

関連スキル

• gguf-quantization：効率的な CPU／GPU 推論のための GGUF 形式と llama.cpp の量子化。
• gptq：AutoGPTQ と transformers を使い、グループ単位の量子化（デフォルトのグループサイズは128）で GPTQ により LLM を4ビット（3ビットにも）に量子化します。
• quantizing-models-bitsandbytes：精度をほとんど損なわずにメモリを50～75％削減できるよう、LLM を8ビットまたは4ビットに量子化します。