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 adalah format floating-point 4-bit dari spesifikasi Microscaling (MX) Open Compute Project. Format ini menyimpan nilai E2M1 dalam blok yang berbagi satu skala pangkat dua (E8M0). Di Transformers, MXFP4 mengkuantisasi lapisan mixture-of-experts pada model GPT-OSS, sehingga gunakan format ini untuk menjalankan GPT-OSS dengan memori yang lebih sedikit.

Tabel di bawah ini merangkum apa yang didukung oleh MXFP4 di Transformers.

KonfigurasiMxfp4Config
quant_methodmxfp4
Alur KerjaKuantisasi saat memuat, memuat yang sudah dikuantisasi
Bit4
Perangkat KerasCUDA (kemampuan komputasi 7.5+), XPU, CPU
Simpan✅
Fine-tune❌
Auto-compile❌

Install MXFP4

Transformers mengunduh kernel Triton MXFP4 dari repositori kernels-community/gpt-oss-triton-kernels di Hub. Instal pustaka kernels, Accelerate, dan Triton. CUDA membutuhkan Triton 3.4.0 atau lebih baru, sedangkan XPU dan CPU membutuhkan Triton 3.5.0 atau lebih baru.

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

Kuantisasi model dengan MXFP4

Buat Mxfp4Config dan teruskan ke from_pretrained() untuk mengkuantisasi checkpoint GPT-OSS bf16 saat dimuat. MXFP4 hanya mengkuantisasi bobot expert. Lapisan perhatian, router, embeddings, dan lm_head tetap mempertahankan presisi aslinya.

from transformers import AutoModelForCausalLM, Mxfp4Config

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

Jika perangkat keras atau paket yang dibutuhkan MXFP4 tidak tersedia, atur dequantize=True untuk memuat model dalam bf16 sebagai gantinya.

Muat checkpoint yang sudah dikuantisasi

Checkpoint openai/gpt-oss-20b dan openai/gpt-oss-120b disimpan dalam MXFP4, dan config mereka mengatur quant_method menjadi mxfp4. Muat mereka tanpa Mxfp4Config.

from transformers import AutoModelForCausalLM

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

Jika perangkat keras atau paket Anda tidak dapat menjalankan MXFP4, Transformers mencatat peringatan dan melakukan dekuantisasi checkpoint yang sudah dikuantisasi ke bf16 alih-alih melempar error.

Pilih backend kernel

Secara default, MXFP4 menjalankan lapisan expert dengan kernel Triton pada CUDA dan XPU. Luluskan use_kernels=True ke from_pretrained() untuk menjalankannya dengan kernel MegaBlocks dari Hub.

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

Backend yang Anda dapatkan bergantung pada perangkat.

Perangkatuse_kernels=Falseuse_kernels=True
CUDAMXFP4 dengan kernel TritonMendequantisasi ke bf16
XPUMXFP4 dengan kernel TritonMXFP4 dengan MegaBlocks
CPUMendequantisasi ke bf16MXFP4 dengan MegaBlocks

Keterbatasan

  • MXFP4 hanya mengkuantisasi lapisan ahli (expert layers) GPT-OSS. Model lain dimuat tanpa lapisan terkuantisasi apa pun, dan Transformers mencatat peringatan.
  • MXFP4 memerlukan GPU CUDA dengan compute capability 7.5 atau lebih baru, XPU, atau CPU. Mengkuantisasi model pada perangkat keras yang tidak didukung atau tanpa Triton atau kernel akan memicu ValueError. Mengkuantisasi model pada mesin dengan akselerator lain, seperti MPS, akan memicu RuntimeError.
  • Kuantisasi model saat dimuat tidak dapat melakukan offload ke disk. device_map yang mencakup "disk" akan memicu ValueError.
  • Model MXFP4 tidak dapat dihaluskan. Muat model dengan dequantize=True untuk melatihnya dalam bf16.

Sumber daya

Update on GitHub