Transformers documentation
MXFP4
MXFP4
MXFP4는 Open Compute Project Microscaling (MX) 사양의 4비트 부동소수점 형식입니다. E2M1 값을 하나의 2의 거듭제곱(E8M0) 스케일을 공유하는 블록에 저장합니다. Transformers에서 MXFP4는 GPT-OSS 모델의 mixture-of-experts 레이어를 양자화하므로, 이를 사용하여 메모리를 덜 소모하면서 GPT-OSS를 실행할 수 있습니다.
아래 표는 Transformers에서 MXFP4가 지원하는 내용을 요약합니다.
| 설정 | Mxfp4Config |
quant_method | mxfp4 |
| 워크플로 | Quantize while loading, load pre-quantized |
| Bits | 4 |
| 하드웨어 | CUDA (compute capability 7.5 이상), XPU, CPU |
| 저장 | ✅ |
| 파인튜닝 | ❌ |
| 자동 컴파일 | ❌ |
MXFP4 설치
Transformers는 Hub의 kernels-community/gpt-oss-triton-kernels 저장소에서 MXFP4 Triton 커널을 다운로드합니다. kernels 라이브러리, Accelerate, 그리고 Triton을 설치하세요. CUDA에는 Triton 3.4.0 이상이 필요하고, XPU와 CPU에는 Triton 3.5.0 이상이 필요합니다.
pip install -U "transformers[kernels]" accelerate "triton>=3.4.0"MXFP4로 모델 양자화
Mxfp4Config를 생성하고 from_pretrained()에 전달하여 bf16 GPT-OSS 체크포인트를 로드하는 동안 양자화합니다. MXFP4는 전문가(expert) 가중치만 양자화합니다. 어텐션 레이어, 라우터, 임베딩 및 lm_head는 원래의 정밀도를 유지합니다.
from transformers import AutoModelForCausalLM, Mxfp4Config
quantization_config = Mxfp4Config()
model = AutoModelForCausalLM.from_pretrained(
"unsloth/gpt-oss-20b-BF16",
quantization_config=quantization_config,
device_map="cuda",
)MXFP4에 필요한 하드웨어 또는 패키지가 사용 불가능한 경우, dequantize=True를 설정하여 모델을 대신 bf16으로 로드합니다.
pre-quantized 체크포인트 로드
openai/gpt-oss-20b 및 openai/gpt-oss-120b 체크포인트는 MXFP4로 저장되어 있으며, 해당 config에서 quant_method가 mxfp4로 설정되어 있습니다. Mxfp4Config 없이 로드하세요.
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("openai/gpt-oss-20b", device_map="cuda")하드웨어나 패키지로 MXFP4를 실행할 수 없는 경우, Transformers는 오류를 발생시키지 않고 경고를 기록한 뒤 사전 양자화 체크포인트를 bf16으로 역양자화합니다.
커널 백엔드 선택
기본적으로 MXFP4는 CUDA와 XPU에서 전문가 레이어를 Triton 커널로 실행합니다. 대신 Hub의 MegaBlocks 커널로 실행하려면 from_pretrained()에 use_kernels=True를 전달하세요.
model = AutoModelForCausalLM.from_pretrained("openai/gpt-oss-20b", device_map="cpu", use_kernels=True)사용하는 장치에 따라 백엔드가 결정됩니다.
| 장치 | use_kernels=False | use_kernels=True |
|---|---|---|
| CUDA | Triton 커널을 사용한 MXFP4 | bf16로 역양자화 |
| XPU | Triton 커널을 사용한 MXFP4 | MegaBlocks를 활용한 MXFP4 |
| CPU | bf16로 역양자화 | MegaBlocks를 활용한 MXFP4 |
한계
- MXFP4는 GPT-OSS의 expert 레이어만 양자화합니다. 다른 모델은 양자화된 레이어 없이 로드되며, Transformers가 경고를 기록합니다.
- MXFP4는 compute capability 7.5 이상의 CUDA GPU, XPU 또는 CPU가 필요합니다. 지원되지 않는 하드웨어에서, 또는 Triton 또는 kernels 없이 모델을 양자화하면
ValueError가 발생합니다. MPS와 같은 다른 가속기가 있는 머신에서 모델을 양자화하면RuntimeError가 발생합니다. - 모델을 로드하는 동안 양자화를 수행하면 디스크로 오프로드할 수 없습니다.
"disk"를 포함하는device_map은ValueError를 발생시킵니다. - MXFP4 모델은 파인튜닝할 수 없습니다.
dequantize=True로 모델을 로드하여 bf16으로 학습하세요.
리소스
- OCP Microscaling Formats (MX) v1.0 사양
- gpt-oss 트릭 블로그 게시물의 MXFP4 양자화 섹션
- kernels-community/gpt-oss-triton-kernels Hub 커널