Transformers documentation

FP-Quant

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

FP-Quant

FP-Quant quantifie les poids et les activations dans les formats MXFP4 ou NVFP4, en appliquant une rotation (une transformation de Hadamard par défaut) avant la quantification, et exécute les produits matriciels avec les noyaux QuTLASS sur les GPU NVIDIA Blackwell. Utilisez-le pour l’inférence FP4 sur les GPU Blackwell, ou pour émuler la quantification FP4 sur d’autres GPU afin d’évaluer la précision ou d’exécuter un entraînement conscient de la quantification (QAT).

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

ConfigurationFPQuantConfig
quant_methodfp_quant
Flux de travailQuantifier lors du chargement
Bits4
MatérielGPU NVIDIA Blackwell ; autres GPU CUDA et XPU Intel avec pseudoquantization=True
Enregistrer✅
Ajustement finUniquement avec store_master_weights=True
Auto-compilation❌

Installer FP-Quant

Installez fp_quant 0.3.2 ou une version ultérieure. Pour exécuter les noyaux FP4 réels sur un GPU Blackwell, compilez également QuTLASS 0.2.0 ou une version ultérieure à partir du code source.

pip install -U "fp_quant>=0.3.2"
git clone https://github.com/IST-DASLab/qutlass.git
cd qutlass && pip install --no-build-isolation .

Quantifier un modèle avec FP-Quant

Créez un FPQuantConfig et passez-le à from_pretrained(). Définissez device_map sur vos GPU. La configuration par défaut quantise chaque couche linéaire, à l'exception de lm_head, en NVFP4.

from transformers import AutoModelForCausalLM, FPQuantConfig

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-8B",
    quantization_config=FPQuantConfig(),
    device_map="cuda",
)

FP-Quant ne prend en charge que bf16, le modèle est donc toujours chargé en bf16. Tout autre dtype est remplacé avec un avertissement.

Sans GPU Blackwell, définissez pseudoquantization=True. FP-Quant émule alors la quantification FP4 à l’aide de noyaux Triton. Cela reproduit la précision du modèle quantifié, mais n’apporte pas d’accélération.

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-8B",
    quantization_config=FPQuantConfig(forward_dtype="mxfp4", pseudoquantization=True),
    device_map="cuda",
)

Pour charger un modèle quantisé à l'avance avec GPTQ afin d'obtenir une meilleure précision, passez son dépôt Hub à from_pretrained() sans quantization_config. L'organisation ISTA-DASLab héberge des points de contrôle FP-Quant, et le dépôt FP-Quant contient le code pour les créer.

Configurer FP-Quant

Ces paramètres FPQuantConfig modifient la manière dont les poids et les activations sont quantifiés.

ParamètrePar défautEffet
forward_dtype"nvfp4"Format FP4 pour le passage avant, soit "nvfp4" soit "mxfp4".
hadamard_group_sizeNoneTaille de la transformation de Hadamard. Avec None, elle est de 16 pour NVFP4 et de 32 pour MXFP4. NVFP4 accepte 16, 32, 64 et 128, et MXFP4 accepte 32, 64 et 128.
transform_init"hadamard"La façon dont la matrice de transformation est initialisée, soit "hadamard", "identity" ou "gsr".
pseudoquantizationFalseÉmule FP4 avec des noyaux Triton au lieu d'exécuter les noyaux QuTLASS. Requis sur les GPU autres que Blackwell.

Voir FPQuantConfig pour le reste des paramètres.

Entraîner avec des poids quantifiés

FP-Quant prend en charge le QAT. Définissez store_master_weights=True pour conserver les poids haute précision afin qu’ils puissent être mis à jour, et définissez forward_method="quest", qui fonctionne mieux que "abs_max" pour le QAT. La méthode "quest" ne fonctionne qu’avec MXFP4. Lors d’un passage avant MXFP4, backward_dtype peut également quantifier le passage arrière en "mxfp8" ou "mxfp4" au lieu de "bf16".

from transformers import AutoModelForCausalLM, FPQuantConfig

quantization_config = FPQuantConfig(
    forward_dtype="mxfp4",
    forward_method="quest",
    store_master_weights=True,
    pseudoquantization=True,
)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-8B",
    quantization_config=quantization_config,
    device_map="cuda",
)

Les auteurs de FP-Quant notent que QAT ne fonctionne actuellement qu'avec pseudoquantization=True.

Limites

  • FP-Quant nécessite un GPU CUDA ou un XPU Intel. Le chargement sans l'un d'eux provoque une NotImplementedError.
  • Sans QuTLASS installé, le chargement avec pseudoquantization=False lève une ImportError.
  • La pseudo-quantisation NVFP4 nécessite un GPU CUDA avec une capacité de calcul 9.0 ou supérieure (Hopper ou plus récent). Sur les GPU plus anciens, elle lève une ValueError. Utilisez plutôt forward_dtype="mxfp4".
  • Sans pseudoquantization, le chargement sans device_map lève une ValueError. Un device_map qui répartit le modèle entre un GPU et le CPU lève également une ValueError.
  • Un device_map qui inclut "disk" lève une ValueError.
  • La pseudo-quantisation ne prend pas en charge plusieurs GPU.
  • L’entraînement sans store_master_weights=True n’est pas pris en charge.

Ressources

Update on GitHub