Transformers documentation

MXFP4

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.23.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

MXFP4

MXFP4は、Open Compute Project Microscaling (MX)仕様で定義された4ビット浮動小数点形式です。E2M1の値を、共通の2のべき乗(E8M0)スケールを共有するブロック内に格納します。Transformersでは、MXFP4はGPT-OSSモデルのmixture-of-experts層を量子化するために使用されるため、メモリ使用量を削減してGPT-OSSを実行する際に利用できます。

TransformersにおけるMXFP4のサポート状況を下表にまとめます。

設定Mxfp4Config
quant_methodmxfp4
ワークフロー読み込み時に量子化、事前量子化済みを読み込む
ビット4
ハードウェアCUDA(計算能力 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 はエキスパートの重みのみを量子化します。アテンション層、ルーター、埋め込み、および 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 でモデルを読み込むようにしてください。

事前量子化されたチェックポイントを読み込む

openai/gpt-oss-20b と openai/gpt-oss-120b のチェックポイントは MXFP4 で保存されており、その設定では 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=Falseuse_kernels=True
CUDATritonカーネルによるMXFP4bf16にデクアンタイズします
XPUTritonカーネルによるMXFP4MegaBlocksによるMXFP4
CPUbf16にデクアンタイズしますMegaBlocksによるMXFP4

制限事項

  • MXFP4はGPT-OSSのエキスパート層のみを量子化します。その他のモデルは量子化された層なしで読み込まれ、Transformersが警告をログに記録します。
  • MXFP4には、計算能力7.5以降のCUDA GPU、XPU、またはCPUが必要です。サポートされていないハードウェア上で、またはTritonやカーネルなしでモデルを量子化すると、ValueErrorが発生します。MPSのような別のアクセラレータを搭載したマシン上でモデルを量子化すると、RuntimeErrorが発生します。
  • モデルの読み込み中に量子化を行う場合、ディスクへのオフロードはできません。"disk" を含む device_map を指定すると、ValueError が発生します。
  • MXFP4モデルはファインチューニングできません。dequantize=Trueを指定してモデルを読み込み、bf16で学習してください。

リソース

Update on GitHub