Skip to content

artubss/SKILLS-CLAUDE-CODE / skills/skills/ai-research/optimization-hqq

hqq-quantization

Verified

Quantização Half-Quadratic para LLMs sem dados de calibração. Use ao quantizar modelos com precisão 4/3/2-bit sem necessidade de conjuntos de calibração, para workflows de quantização rápida, ou ao fazer deploy com vLLM ou HuggingFace Transformers.

HQQ - Half-Quadratic Quantization

Quantização de pesos rápida e sem calibração, suportando precisão 8/4/3/2/1-bit com múltiplos backends otimizados.

Quando usar HQQ

Use HQQ quando:

  • Quantizar modelos sem dados de calibração (nenhum dataset necessário)
  • Precisa de quantização rápida (minutos vs horas para GPTQ/AWQ)
  • Fazer deploy com vLLM ou HuggingFace Transformers
  • Fine-tuning de modelos quantizados com LoRA/PEFT
  • Experimentar quantização extrema (2-bit, 1-bit)

Principais vantagens:

  • Sem calibração: Quantize qualquer modelo instantaneamente sem dados de amostra
  • Múltiplos backends: PyTorch, ATEN, TorchAO, Marlin, BitBlas para inferência otimizada
  • Precisão flexível: 8/4/3/2/1-bit com tamanhos de grupo configuráveis
  • Integração com frameworks: Suporte nativo para HuggingFace e vLLM
  • Compatível com PEFT: Fine-tune modelos quantizados com LoRA

Use alternativas no lugar:

  • AWQ: Quando precisa de acurácia baseada em calibração, serving em produção
  • GPTQ: Máxima acurácia com dados de calibração disponíveis
  • bitsandbytes: Simples 8-bit/4-bit sem backends customizados
  • llama.cpp/GGUF: Inferência em CPU, deploy em Apple Silicon

Início rápido

Instalação

pip install hqq

# Com backend específico
pip install hqq[torch]      # Backend PyTorch
pip install hqq[torchao]    # Backend TorchAO int4
pip install hqq[bitblas]    # Backend BitBlas
pip install hqq[marlin]     # Backend Marlin

Quantização básica

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

# Configure quantização
config = BaseQuantizeConfig(
    nbits=4,           # Quantização 4-bit
    group_size=64,     # Tamanho do grupo para quantização
    axis=1             # Quantize ao longo da dimensão de saída
)

# Quantize uma camada linear
linear = nn.Linear(4096, 4096)
hqq_linear = HQQLinear(linear, config)

# Use normalmente
output = hqq_linear(input_tensor)

Quantizar modelo completo com HuggingFace

from transformers import AutoModelForCausalLM, HqqConfig

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

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

# Modelo está quantizado e pronto para uso

Conceitos principais

Configuração de quantização

HQQ usa BaseQuantizeConfig para definir parâmetros de quantização:

from hqq.core.quantize import BaseQuantizeConfig

# Config 4-bit padrão
config_4bit = BaseQuantizeConfig(
    nbits=4,           # Bits por peso (1-8)
    group_size=64,     # Pesos por grupo de quantização
    axis=1             # 0=dim entrada, 1=dim saída
)

# Config agressivo 2-bit
config_2bit = BaseQuantizeConfig(
    nbits=2,
    group_size=16,     # Grupos menores para baixo-bit
    axis=1
)

# Precisão mista por tipo de camada
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),
}

Camada HQQLinear

A camada quantizada principal que substitui nn.Linear:

from hqq.core.quantize import HQQLinear
import torch

# Crie camada quantizada
linear = torch.nn.Linear(4096, 4096)
hqq_layer = HQQLinear(linear, config)

# Acesse pesos quantizados
W_q = hqq_layer.W_q           # Pesos quantizados
scale = hqq_layer.scale       # Fatores de escala
zero = hqq_layer.zero         # Pontos zero

# Dequantize para inspeção
W_dequant = hqq_layer.dequantize()

Backends

HQQ suporta múltiplos backends de inferência para diferentes hardwares:

from hqq.core.quantize import HQQLinear

# Backends disponíveis
backends = [
    "pytorch",          # PyTorch puro (padrão)
    "pytorch_compile",  # Otimizado com torch.compile
    "aten",            # Kernels CUDA customizados
    "torchao_int4",    # Matmul int4 TorchAO
    "gemlite",         # Kernels CUDA GemLite
    "bitblas",         # Otimizado BitBlas
    "marlin",          # Kernels 4-bit Marlin
]

# Defina backend globalmente
HQQLinear.set_backend("torchao_int4")

# Ou por camada
hqq_layer.set_backend("marlin")

Guia de seleção de backend:

BackendMelhor paraRequisitos
pytorchCompatibilidadeQualquer GPU
pytorch_compileSpeedup moderadotorch>=2.0
atenBom equilíbrioGPU CUDA
torchao_int4Inferência 4-bittorchao instalado
marlinMáxima velocidade 4-bitGPU Ampere+
bitblasBit-widths flexíveisbitblas instalado

Integração HuggingFace

Carregue modelos pré-quantizados

from transformers import AutoModelForCausalLM, AutoTokenizer

# Carregue modelo HQQ-quantizado do 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 normalmente
inputs = tokenizer("Hello, world!", return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=50)

Quantize e salve

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

# Salve modelo quantizado
model.save_pretrained("./llama-8b-hqq-4bit")

# Faça push para Hub
model.push_to_hub("my-org/Llama-3.1-8B-HQQ-4bit")

Quantização de precisão mista

from transformers import AutoModelForCausalLM, HqqConfig

# Precisão diferente por tipo de camada
config = HqqConfig(
    nbits=4,
    group_size=64,
    # Camadas de atenção: precisão maior
    # Camadas MLP: precisão menor para economia de memória
    dynamic_config={
        "attn": {"nbits": 4, "group_size": 64},
        "mlp": {"nbits": 2, "group_size": 32}
    }
)

Integração vLLM

Sirva modelos HQQ com vLLM

from vllm import LLM, SamplingParams

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

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

vLLM com config HQQ customizado

from vllm import LLM

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

Fine-tuning PEFT/LoRA

Fine-tune modelos quantizados

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

# Carregue modelo quantizado
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"
)

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

# Treine normalmente com Trainer ou loop customizado

Treinamento estilo 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()

Workflows de quantização

Workflow 1: Compressão rápida de modelo

from transformers import AutoModelForCausalLM, AutoTokenizer, HqqConfig

# 1. Configure quantização
config = HqqConfig(nbits=4, group_size=64)

# 2. Carregue e quantize (sem calibração necessária!)
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. Verifique qualidade
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. Salve
model.save_pretrained("./llama-8b-hqq")
tokenizer.save_pretrained("./llama-8b-hqq")

Workflow 2: Otimize para velocidade de inferência

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

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

# 2. Defina backend rápido
HQQLinear.set_backend("marlin")  # ou "torchao_int4"

# 3. Compile para speedup adicional
import torch
model = torch.compile(model)

# 4. Faça 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")

Melhores práticas

  1. Comece com 4-bit: Melhor tradeoff qualidade/tamanho para maioria dos modelos
  2. Use group_size=64: Bom equilíbrio; menor para quantização extrema
  3. Escolha backend com cuidado: Marlin para 4-bit Ampere+, TorchAO para flexibilidade
  4. Verifique qualidade: Sempre teste qualidade de geração após quantização
  5. Precisão mista: Mantenha atenção em precisão maior, comprima MLP mais
  6. Treinamento PEFT: Use LoRA r=16-32 para bons resultados de fine-tuning

Problemas comuns

Falta de memória durante quantização:

# Quantize camada por camada
from hqq.models.hf.base import AutoHQQHFModel

model = AutoHQQHFModel.from_pretrained(
    "meta-llama/Llama-3.1-8B",
    quantization_config=config,
    device_map="sequential"  # Carregue camadas sequencialmente
)

Inferência lenta:

# Mude para backend otimizado
from hqq.core.quantize import HQQLinear
HQQLinear.set_backend("marlin")  # Requer GPU Ampere+

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

Qualidade ruim em 2-bit:

# Use tamanho de grupo menor
config = BaseQuantizeConfig(
    nbits=2,
    group_size=16,  # Grupos menores ajudam em baixo-bit
    axis=1
)

Referências

Recursos

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexVerifiedInstall