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 cuantiza los pesos y las activaciones a los formatos MXFP4 o NVFP4, aplicando una rotación (una transformación de Hadamard por defecto) antes de la cuantización, y ejecuta las multiplicaciones de matrices con kernels de QuTLASS en GPUs NVIDIA Blackwell. Úsalo para inferencia FP4 en GPUs Blackwell, o emula la cuantización FP4 en otras GPUs para evaluar la precisión o ejecutar entrenamiento consciente de la cuantización (QAT).

La tabla siguiente resume lo que FP-Quant admite en Transformers.

ConfigFPQuantConfig
quant_methodfp_quant
Flujo de trabajoCuantizar al cargar
Bits4
HardwareGPUs NVIDIA Blackwell; otras GPUs CUDA y XPU de Intel con pseudoquantization=True
Guardar✅
Ajuste finoSolo con store_master_weights=True
Compilación automática❌

Instalar FP-Quant

Instale fp_quant 0.3.2 o una versión posterior. Para ejecutar los kernels reales de FP4 en una GPU Blackwell, también compile QuTLASS 0.2.0 o una versión posterior desde el código fuente.

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

Cuantizar un modelo con FP-Quant

Cree una FPQuantConfig y pásela a from_pretrained(). Establezca device_map en sus GPUs. La configuración por defecto cuantiza cada capa lineal, excepto lm_head, a NVFP4.

from transformers import AutoModelForCausalLM, FPQuantConfig

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

FP-Quant solo admite bf16, por lo que el modelo siempre se carga en bf16. Cualquier otro dtype se reemplaza con una advertencia.

Sin una GPU Blackwell, establezca pseudoquantization=True. FP-Quant emulará la cuantización FP4 con kernels de Triton. Esto reproduce la precisión del modelo cuantizado, pero no lo acelera.

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

Para cargar un modelo que fue cuantizado previamente con GPTQ para obtener una mayor precisión, pase su repositorio de Hub a from_pretrained() sin un quantization_config. La organización ISTA-DASLab aloja puntos de control de FP-Quant, y el repositorio FP-Quant tiene el código para crearlos.

Configurar FP-Quant

Estos parámetros de FPQuantConfig modifican cómo se cuantizan los pesos y las activaciones.

ParámetroPredeterminadoEfecto
forward_dtype"nvfp4"Formato FP4 para la pasada hacia adelante, ya sea "nvfp4" o "mxfp4".
hadamard_group_sizeNoneTamaño de la transformación de Hadamard. Con None, es 16 para NVFP4 y 32 para MXFP4. NVFP4 acepta 16, 32, 64 y 128, y MXFP4 acepta 32, 64 y 128.
transform_init"hadamard"Cómo se inicializa la matriz de transformación, ya sea "hadamard", "identity" o "gsr".
pseudoquantizationFalseEmula FP4 con kernels de Triton en lugar de ejecutar los kernels de QuTLASS. Es obligatorio en GPUs distintas de Blackwell.

Consulte FPQuantConfig para el resto de los parámetros.

Entrenar con pesos cuantizados

FP-Quant admite QAT. Establezca store_master_weights=True para conservar los pesos de alta precisión y poder actualizarlos, y establezca forward_method="quest", que funciona mejor que "abs_max" para QAT. El método "quest" solo funciona con MXFP4. Con una pasada hacia adelante en MXFP4, backward_dtype también puede cuantizar la pasada hacia atrás a "mxfp8" o "mxfp4" en lugar 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",
)

Los autores de FP-Quant señalan que QAT actualmente solo funciona con pseudoquantization=True.

Limitaciones

  • FP-Quant requiere una GPU CUDA o una XPU de Intel. Cargar sin una de ellas provoca un NotImplementedError.
  • Sin QuTLASS instalado, cargar con pseudoquantization=False genera un ImportError.
  • La pseudo-cuantización NVFP4 requiere una GPU CUDA con capacidad de cálculo 9.0 o superior (Hopper o más reciente). En GPUs más antiguos, se genera un ValueError. Utilice forward_dtype="mxfp4" en su lugar.
  • Sin pseudoquantization, cargar sin un device_map provoca un ValueError. Un device_map que distribuye el modelo entre una GPU y la CPU también provoca un ValueError.
  • Un device_map que incluye "disk" genera un ValueError.
  • La pseudo-cuantización no admite múltiples GPUs.
  • El entrenamiento sin store_master_weights=True no está soportado.

Recursos

Update on GitHub