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 es el formato de punto flotante de 4 bits de la especificación Microscaling (MX) de Open Compute Project. Almacena valores E2M1 en bloques que comparten una escala de potencia de dos (E8M0). En Transformers, MXFP4 cuantiza las capas mixture-of-experts de los modelos GPT-OSS, por lo que se utiliza para ejecutar GPT-OSS con menos memoria.

La tabla siguiente resume lo que MXFP4 admite en Transformers.

ConfigMxfp4Config
quant_methodmxfp4
Flujo de trabajoCuantizar al cargar, cargar pre-cuantizado
Bits4
HardwareCUDA (capacidad de cómputo 7.5+), XPU, CPU
Guardar✅
Ajuste fino❌
Compilación automática❌

Instalar MXFP4

Transformers descarga los núcleos Triton MXFP4 del repositorio kernels-community/gpt-oss-triton-kernels en el Hub. Instale la biblioteca kernels, Accelerate y Triton. CUDA requiere Triton 3.4.0 o posterior, mientras que XPU y CPU requieren Triton 3.5.0 o posterior.

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

Cuantizar un modelo con MXFP4

Cree una Mxfp4Config y pásela a from_pretrained() para cuantizar un checkpoint de GPT-OSS en bf16 mientras se carga. MXFP4 cuantiza únicamente los pesos de los expertos. Las capas de atención, el router, los embeddings y lm_head conservan su precisión original.

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 el hardware o los paquetes que requiere MXFP4 no están disponibles, establezca dequantize=True para cargar el modelo en bf16 en su lugar.

Cargar un punto de control pre-cuantizado

Los puntos de control openai/gpt-oss-20b y openai/gpt-oss-120b se almacenan en MXFP4 y su configuración establece quant_method en mxfp4. Carguelos sin una Mxfp4Config.

from transformers import AutoModelForCausalLM

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

Si tu hardware o paquetes no pueden ejecutar MXFP4, Transformers registra una advertencia y descuantiza un checkpoint pre-cuantizado a bf16 en lugar de lanzar un error.

Elija un backend de kernel

Por defecto, MXFP4 ejecuta las capas de expertos con los kernels de Triton en CUDA y XPU. Pasa use_kernels=True a from_pretrained() para ejecutarlos con el kernel MegaBlocks del Hub en su lugar.

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

El backend que obtienes depende del dispositivo.

Dispositivouse_kernels=Falseuse_kernels=True
CUDAMXFP4 con kernels de TritonDesquantiza a bf16
XPUMXFP4 con kernels de TritonMXFP4 con MegaBlocks
CPUDesquantiza a bf16MXFP4 con MegaBlocks

Limitaciones

  • MXFP4 cuantiza únicamente las capas de expertos de GPT-OSS. Otros modelos se cargan sin capas cuantizadas y Transformers registra una advertencia.
  • MXFP4 requiere una GPU CUDA con capacidad de cálculo 7.5 o posterior, un XPU o una CPU. Cuantizar un modelo en hardware no compatible o sin Triton o kernels genera un ValueError. Cuantizar un modelo en una máquina con otro acelerador, como MPS, genera un RuntimeError.
  • Cuantizar un modelo mientras se carga no permite descargarlo en el disco. Un device_map que incluye "disk" genera un ValueError.
  • Los modelos MXFP4 no se pueden ajustar. Cargue el modelo con dequantize=True para entrenarlo en bf16.

Recursos

Update on GitHub