# HQQ

[Half-Quadratic Quantization (HQQ)](https://github.com/mobiusml/hqq/) optimise ses paramètres de quantisation à partir des poids uniquement, sans nécessiter de données de calibration. Utilisez-le pour quantiser un modèle jusqu'à 1 ou 2 bits pendant son chargement.

Le tableau ci-dessous résume ce que HQQ prend en charge dans Transformers.

| | |
|---|---|
| Configuration | [HqqConfig](/docs/transformers/v5.24.0/fr/main_classes/quantization#transformers.HqqConfig) |
| `quant_method` | `hqq` |
| Flux de travail | Quantifier lors du chargement |
| Bits | 1, 2, 3, 4, 8 |
| Matériel | CUDA, XPU |
| Enregistrer | ✅ |
| Ajustement fin | ✅ |
| Auto-compilation | ❌ |

## Installer HQQ

Installez hqq 0.2.1 ou une version ultérieure.

```bash
pip install -U hqq
```

## Quantifier un modèle avec HQQ

Créez un [HqqConfig](/docs/transformers/v5.24.0/fr/main_classes/quantization#transformers.HqqConfig) et passez-le à [from_pretrained()](/docs/transformers/v5.24.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained). L’exemple ci-dessous quantise chaque couche linéaire en 4 bits par groupes de 64 poids.

```py
import torch
from transformers import AutoModelForCausalLM, HqqConfig

quantization_config = HqqConfig(nbits=4, group_size=64)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    quantization_config=quantization_config,
    device_map="cuda",
)
```

## Configurer HQQ

Ces paramètres [HqqConfig](/docs/transformers/v5.24.0/fr/main_classes/quantization#transformers.HqqConfig) modifient la manière dont les poids sont quantifiés.

| Paramètre | Par défaut | Effet |
|---|---|---|
| `nbits` | `4` | Nombre de bits par poids. Prend en charge 8, 4, 3, 2 et 1. |
| `group_size` | `64` | Nombre de poids qui partagent une échelle et un point zéro. Des groupes plus petits sont plus précis et utilisent plus de mémoire. |
| `axis` | `1` | Axe le long duquel regrouper les poids, soit 0, soit 1. Les backends torchao et BitBlas, plus rapides, ne fonctionnent qu'avec `1`. |
| `view_as_float` | `False` | Stocke les poids quantifiés sous forme de type de données flottant, pour l'entraînement distribué. |
| `skip_modules` | `["lm_head"]` | Types de couches à ne pas quantiser. |

## Quantifier les types de couches avec des paramètres différents

Passez `dynamic_config` pour quantiser chaque type de couche linéaire avec ses propres paramètres. Chaque clé est un *balise de couche*, le nom du module avec `model`, `layers` et le numéro de couche supprimés. Par exemple, `model.layers.3.self_attn.q_proj` a la balise `self_attn.q_proj`.

L'exemple ci-dessous quantifie les projections d'attention sur 4 bits et les projections MLP sur 3 bits.

```py
q4_config = {"nbits": 4, "group_size": 64}
q3_config = {"nbits": 3, "group_size": 32}
quantization_config = HqqConfig(dynamic_config={
    "self_attn.q_proj": q4_config,
    "self_attn.k_proj": q4_config,
    "self_attn.v_proj": q4_config,
    "self_attn.o_proj": q4_config,
    "mlp.gate_proj": q3_config,
    "mlp.up_proj": q3_config,
    "mlp.down_proj": q3_config,
})
```

Un tag s’applique à ce type de couche dans chaque couche décodeuse, il est donc impossible de donner à une couche décodeuse des paramètres différents de ceux des autres. Les couches linéaires dont les tags ne figurent pas dans `dynamic_config` restent non quantifiées. Les mêmes tags sont utilisés pour correspondre à `skip_modules`.

## Choisir un backend

HQQ exécute les couches quantifiées via un backend de la bibliothèque hqq. Les backends PyTorch et CUDA fonctionnent avec le fine-tuning PEFT et les GPU plus anciens. Changez de backend avec `HQQLinear.set_backend`.

```py
from hqq.core.quantize import HQQBackend, HQQLinear

HQQLinear.set_backend(HQQBackend.PYTORCH)
```

Pour une inférence 4 bits plus rapide, convertissez le modèle quantisé vers un backend de noyaux fusionnés, comme torchao, après son chargement. Le backend torchao nécessite `axis=1`, qui est la valeur par défaut.

```py
from hqq.utils.patching import prepare_for_inference

prepare_for_inference(model, backend="torchao_int4")
```

Consultez le guide du [Backend](https://github.com/mobiusml/hqq/#backend) hqq pour connaître les backends disponibles.

## Limites

- HQQ ne peut pas décharger sur le CPU ou le disque. Le chargement avec un `device_map` qui inclut `"cpu"` ou `"disk"` lève une `ValueError`.
- Les balises de couche ne peuvent pas cibler une couche décodeur spécifique, de sorte que `dynamic_config` et `skip_modules` s’appliquent à un type de couche sur l’ensemble du modèle.

## Ressources

- article de blog [Half-Quadratic Quantization of Large Machine Learning Models](https://mobiusml.github.io/hqq_blog/)
- [hqq](https://github.com/mobiusml/hqq/) dépôt

