Transformers documentation

MXFP4

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

MXFP4

MXFP4 est le format à virgule flottante sur 4 bits issu de la spécification Microscaling (MX) du Open Compute Project. Il stocke des valeurs E2M1 dans des blocs partageant une même échelle de puissance de deux (E8M0). Dans Transformers, MXFP4 quantise les couches mixture-of-experts des modèles GPT-OSS, permettant ainsi d’exécuter GPT-OSS avec moins de mémoire.

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

ConfigurationMxfp4Config
quant_methodmxfp4
Flux de travailQuantifier au chargement, charger pré-quantifié
Bits4
MatérielCUDA (capacité de calcul 7.5+), XPU, CPU
Enregistrer✅
Ajustement fin❌
Auto-compilation❌

Installer MXFP4

Transformers télécharge les noyaux Triton MXFP4 depuis le dépôt kernels-community/gpt-oss-triton-kernels sur le Hub. Installez la bibliothèque kernels, Accelerate et Triton. CUDA nécessite Triton 3.4.0 ou une version ultérieure, tandis que XPU et CPU nécessitent Triton 3.5.0 ou une version ultérieure.

pip install -U "transformers[kernels]" accelerate "triton>=3.4.0"

Quantifier un modèle avec MXFP4

Créez un Mxfp4Config et passez-le à from_pretrained() pour quantiser un checkpoint GPT-OSS en bf16 pendant son chargement. La quantification MXFP4 ne s'applique qu'aux poids des experts. Les couches d'attention, le routeur, les embeddings et lm_head conservent leur précision d'origine.

from transformers import AutoModelForCausalLM, Mxfp4Config

quantization_config = Mxfp4Config()
model = AutoModelForCausalLM.from_pretrained(
    "unsloth/gpt-oss-20b-BF16",
    quantization_config=quantization_config,
    device_map="cuda",
)

Si le matériel ou les paquets requis par MXFP4 ne sont pas disponibles, définissez dequantize=True pour charger le modèle en bf16 à la place.

Charger un point de contrôle pré-quantifié

Les points de contrôle openai/gpt-oss-20b et openai/gpt-oss-120b sont stockés en MXFP4, et leur configuration définit quant_method sur mxfp4. Chargez-les sans Mxfp4Config.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("openai/gpt-oss-20b", device_map="cuda")

Si votre matériel ou vos paquets ne peuvent pas exécuter MXFP4, Transformers journalise un avertissement et déquantise un point de contrôle pré-quantisé en bf16 au lieu de lever une erreur.

Choisir un backend de noyau

Par défaut, MXFP4 exécute les couches d’experts avec les noyaux Triton sur CUDA et XPU. Passez use_kernels=True à from_pretrained() pour les exécuter avec le noyau MegaBlocks du Hub à la place.

model = AutoModelForCausalLM.from_pretrained("openai/gpt-oss-20b", device_map="cpu", use_kernels=True)

Le backend que vous obtenez dépend de l'appareil.

Appareiluse_kernels=Falseuse_kernels=True
CUDAMXFP4 avec des noyaux TritonDésquantise en bf16
XPUMXFP4 avec des noyaux TritonMXFP4 avec MegaBlocks
CPUDésquantise en bf16MXFP4 avec MegaBlocks

Limites

  • MXFP4 quantifie uniquement les couches d'experts de GPT-OSS. Les autres modèles sont chargés sans aucune couche quantifiée, et Transformers affiche un avertissement.
  • MXFP4 nécessite une GPU CUDA avec une capacité de calcul 7.5 ou ultérieure, un XPU, ou un CPU. La quantification d'un modèle sur un matériel non pris en charge ou sans Triton ou noyaux soulève une ValueError. La quantification d'un modèle sur une machine avec un autre accélérateur, comme MPS, soulève une RuntimeError.
  • La quantification d'un modèle pendant son chargement ne permet pas de décharger sur le disque. Un device_map qui inclut "disk" lève une ValueError.
  • Les modèles MXFP4 ne peuvent pas être affinés. Chargez le modèle avec dequantize=True pour l’entraîner en bf16.

Ressources

Update on GitHub