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 mengkuantisasi bobot dan aktivasi ke format MXFP4 atau NVFP4, menerapkan rotasi (secara default transformasi Hadamard) sebelum kuantisasi, dan menjalankan matmul dengan kernel QuTLASS pada GPU NVIDIA Blackwell. Gunakan untuk inferensi FP4 pada GPU Blackwell, atau emulasikan kuantisasi FP4 pada GPU lain untuk mengevaluasi akurasi atau menjalankan quantization-aware training (QAT).

Tabel di bawah ini merangkum apa yang didukung oleh FP-Quant di Transformers.

KonfigurasiFPQuantConfig
quant_methodfp_quant
Alur KerjaKuantisasi saat memuat
Bit4
Perangkat KerasGPU NVIDIA Blackwell; GPU CUDA lainnya dan Intel XPU dengan pseudoquantization=True
Simpan✅
Fine-tuneHanya dengan store_master_weights=True
Auto-compile❌

Install FP-Quant

Install fp_quant 0.3.2 atau yang lebih baru. Untuk menjalankan kernel FP4 asli pada GPU Blackwell, juga bangun QuTLASS 0.2.0 atau yang lebih baru dari sumber.

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

Kuantisasi model dengan FP-Quant

Buat FPQuantConfig dan teruskan ke from_pretrained(). Atur device_map ke GPU Anda. Konfigurasi default mengkuantisasi setiap lapisan linear kecuali lm_head ke NVFP4.

from transformers import AutoModelForCausalLM, FPQuantConfig

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

FP-Quant hanya mendukung bf16, sehingga model selalu dimuat dalam bf16. dtype lainnya akan diganti dengan peringatan.

Tanpa GPU Blackwell, atur pseudoquantization=True. FP-Quant kemudian mensimulasikan kuantisasi FP4 dengan kernel Triton. Hal ini mereproduksi akurasi model terkuantisasi tetapi tidak mempercepatnya.

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

Untuk memuat model yang telah dikuantisasi sebelumnya dengan GPTQ untuk akurasi yang lebih baik, berikan repositori Hub-nya ke from_pretrained() tanpa quantization_config. Organisasi ISTA-DASLab menyediakan checkpoint FP-Quant, dan repositori FP-Quant memiliki kode untuk membuatnya.

Konfigurasi FP-Quant

Parameter FPQuantConfig ini mengubah cara bobot dan aktivasi dikuantisasi.

ParameterDefaultEfek
forward_dtype"nvfp4"Format FP4 untuk forward pass, yaitu "nvfp4" atau "mxfp4".
hadamard_group_sizeNoneUkuran transformasi Hadamard. Dengan None, nilainya 16 untuk NVFP4 dan 32 untuk MXFP4. NVFP4 menerima 16, 32, 64, dan 128, sedangkan MXFP4 menerima 32, 64, dan 128.
transform_init"hadamard"Bagaimana matriks transformasi diinisialisasi, yaitu "hadamard", "identity", atau "gsr".
pseudoquantizationFalseMeniru FP4 dengan kernel Triton alih-alih menjalankan kernel QuTLASS. Diperlukan pada GPU selain Blackwell.

Lihat FPQuantConfig untuk parameter lainnya.

Latih dengan bobot terkuantisasi

FP-Quant mendukung QAT. Atur store_master_weights=True untuk mempertahankan bobot berpresisi tinggi agar dapat diperbarui, dan atur forward_method="quest", yang bekerja lebih baik daripada "abs_max" untuk QAT. Metode "quest" hanya berfungsi dengan MXFP4. Dengan jalur maju MXFP4, backward_dtype juga dapat mengkuantisasi jalur mundur menjadi "mxfp8" atau "mxfp4" alih-alih "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",
)

Para penulis FP-Quant mencatat bahwa QAT saat ini hanya berfungsi dengan pseudoquantization=True.

Keterbatasan

  • FP-Quant membutuhkan GPU CUDA atau Intel XPU. Memuatnya tanpa perangkat tersebut akan memicu NotImplementedError.
  • Tanpa QuTLASS yang terpasang, memuat dengan pseudoquantization=False akan memicu ImportError.
  • Pseudo-quantization NVFP4 memerlukan GPU CUDA dengan compute capability 9.0 atau lebih tinggi (Hopper atau lebih baru). Pada GPU yang lebih lama, ini akan memicu ValueError. Gunakan forward_dtype="mxfp4" sebagai gantinya.
  • Tanpa pseudoquantization, memuat model tanpa device_map akan memicu ValueError. device_map yang menyebar model di antara GPU dan CPU juga memicu ValueError.
  • device_map yang mencakup "disk" akan memicu ValueError.
  • Pseudo-quantization tidak mendukung beberapa GPU.
  • Pelatihan tanpa store_master_weights=True tidak didukung.

Sumber daya

Update on GitHub