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 là định dạng số thực 4-bit từ quy định Microscaling (MX) của Open Compute Project. Định dạng này lưu trữ các giá trị E2M1 trong các khối chia sẻ chung một thang đo lũy thừa của hai (E8M0). Trong Transformers, MXFP4 lượng tử hóa các lớp mixture-of-experts của các mô hình GPT-OSS, do đó hãy sử dụng nó để chạy GPT-OSS với bộ nhớ ít hơn.

Bảng dưới đây tóm tắt những gì MXFP4 hỗ trợ trong Transformers.

Cấu hìnhMxfp4Config
quant_methodmxfp4
Quy trình làm việcThực hiện lượng tử hóa khi tải, tải mô hình đã lượng tử hóa sẵn
Bits4
Phần cứngCUDA (khả năng tính toán 7.5+), XPU, CPU
Lưu✅
Tinh chỉnh❌
Tự động biên dịch❌

Cài đặt MXFP4

Transformers tải các kernel Triton MXFP4 từ kho kernels-community/gpt-oss-triton-kernels trên Hub. Cài đặt thư viện kernels, Accelerate và Triton. CUDA yêu cầu Triton 3.4.0 trở lên, còn XPU và CPU yêu cầu Triton 3.5.0 trở lên.

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

Lượng tử hóa một mô hình với MXFP4

Tạo một Mxfp4Config và truyền nó vào from_pretrained() để lượng tử hóa checkpoint GPT-OSS bf16 trong khi nó được tải. MXFP4 chỉ lượng tử hóa trọng số chuyên gia. Các lớp chú ý, router, embeddings và lm_head giữ nguyên độ chính xác ban đầu.

from transformers import AutoModelForCausalLM, Mxfp4Config

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

Nếu phần cứng hoặc các gói mà MXFP4 cần không khả dụng, hãy đặt dequantize=True để tải mô hình ở dạng bf16 thay thế.

Tải checkpoint đã lượng tử hóa

Các checkpoint openai/gpt-oss-20b và openai/gpt-oss-120b được lưu trữ ở định dạng MXFP4, và config của chúng đặt quant_method thành mxfp4. Hãy tải chúng mà không cần Mxfp4Config.

from transformers import AutoModelForCausalLM

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

Nếu phần cứng hoặc các gói của bạn không thể chạy MXFP4, Transformers sẽ ghi nhận một cảnh báo và khử lượng hóa checkpoint đã được lượng hóa trước thành bf16 thay vì gây ra lỗi.

Chọn backend kernel

Mặc định, MXFP4 chạy các lớp chuyên gia bằng các kernel Triton trên CUDA và XPU. Truyền use_kernels=True vào from_pretrained() để chạy chúng bằng kernel MegaBlocks từ Hub.

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

Backend bạn nhận được phụ thuộc vào thiết bị.

Thiết bịuse_kernels=Falseuse_kernels=True
CUDAMXFP4 với các kernel TritonKhử lượng tử hóa xuống bf16
XPUMXFP4 với các kernel TritonMXFP4 với MegaBlocks
CPUKhử lượng tử hóa xuống bf16MXFP4 với MegaBlocks

Hạn chế

  • MXFP4 chỉ lượng tử hóa các lớp chuyên gia của GPT-OSS. Các mô hình khác được nạp mà không có bất kỳ lớp nào được lượng tử hóa, và Transformers sẽ ghi lại một cảnh báo.
  • MXFP4 yêu cầu GPU CUDA có khả năng tính toán 7.5 trở lên, một XPU, hoặc CPU. Việc lượng tử hóa mô hình trên phần cứng không được hỗ trợ hoặc không có Triton hoặc kernels sẽ gây ra ValueError. Việc lượng tử hóa mô hình trên máy có bộ tăng tốc khác, chẳng hạn như MPS, sẽ gây ra RuntimeError.
  • Việc lượng tử hóa mô hình trong khi nó đang được nạp không thể offload ra đĩa. Một device_map bao gồm "disk" sẽ gây ra ValueError.
  • Các mô hình MXFP4 không thể được tinh chỉnh. Hãy tải mô hình với dequantize=True để huấn luyện nó ở bf16.

Tài nguyên

Update on GitHub