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は、重みと活性化をMXFP4またはNVFP4形式に量子化し、量子化の前に回転(デフォルトではHadamard変換)を適用します。また、NVIDIA Blackwell GPU上でQuTLASSカーネルを使用して行列積を実行します。Blackwell GPUでのFP4推論に使用するか、他のGPU上でFP4量子化をエミュレートして精度を評価したり、量子化認識学習(QAT)を実行したりできます。

以下の表は、Transformers で FP-Quant がサポートする内容をまとめました。

設定FPQuantConfig
quant_methodfp_quant
ワークフロー読み込み時に量子化
ビット4
ハードウェアNVIDIA Blackwell GPU。その他のCUDA GPUおよびIntel XPUはpseudoquantization=Trueを使用
保存✅
ファインチューニングstore_master_weights=True の場合のみ
自動コンパイル❌

FP-Quantのインストール

fp_quant 0.3.2 以降をインストールしてください。Blackwell GPU で実際の FP4 カーネルを実行するには、QuTLASS 0.2.0 以降をソースからビルドする必要があります。

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

FP-Quantでモデルを量子化

FPQuantConfig を作成し、from_pretrained() に渡します。device_map を GPU に設定します。デフォルトの構成では、lm_head 以外のすべての線形層が NVFP4 に量子化されます。

from transformers import AutoModelForCausalLM, FPQuantConfig

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

FP-Quantはbf16のみをサポートするため、モデルは常にbf16で読み込まれます。その他のdtypeは警告とともに置き換えられます。

Blackwell GPU がない場合は、pseudoquantization=True を設定してください。FP-Quant は Triton カーネルを使用して FP4 量子化をエミュレートします。量子化モデルの精度を再現しますが、高速化は行われません。

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

GPTQ により事前に量子化され、より高い精度が得られるモデルを読み込むには、quantization_config を指定せずに、その Hub リポジトリを from_pretrained() に渡します。ISTA-DASLab 組織が FP-Quant チェックポイントをホストしており、FP-Quant リポジトリにはそれらを作成するためのコードが含まれています。

FP-Quantを設定

これらのFPQuantConfigパラメータは、重みと活性化値の量子化方法を変更します。

パラメータデフォルト効果
forward_dtype"nvfp4"フォワードパス用のFP4形式。"nvfp4"または"mxfp4"のいずれかです。
hadamard_group_sizeNoneHadamard変換のサイズ。Noneの場合、NVFP4では16、MXFP4では32になります。NVFP4は16、32、64、128を受け入れ、MXFP4は32、64、128を受け入れます。
transform_init"hadamard"変換行列の初期化方法。"hadamard"、"identity"、または"gsr"のいずれかです。
pseudoquantizationFalseQuTLASSカーネルの実行ではなく、TritonカーネルでFP4をエミュレートします。Blackwell以外のGPUでは必須です。

その他のパラメータについては、FPQuantConfigを参照してください。

量子化された重みで学習

FP-Quant は QAT をサポートしています。高精度の重みを保持して更新できるようにするには store_master_weights=True を設定し、QAT では "abs_max" よりも効果的な forward_method="quest" を設定します。"quest" メソッドは MXFP4 のみで動作します。MXFP4 のフォワードパスでは、"bf16" の代わりに backward_dtype を設定することで、バックワードパスを "mxfp8" または "mxfp4" に量子化することもできます。

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",
)

FP-Quantの著者たちは、QATは現在pseudoquantization=Trueでのみ動作すると述べています。

制限事項

  • FP-QuantにはCUDA GPUまたはIntel XPUが必要です。これらなしで読み込むと、NotImplementedErrorが発生します。
  • QuTLASSがインストールされていない場合、pseudoquantization=Falseで読み込むとImportErrorが発生します。
  • NVFP4擬似量子化には、計算能力9.0以上(Hopper以降)のCUDA GPUが必要です。古いGPUではValueErrorが発生します。代わりにforward_dtype="mxfp4"を使用してください。
  • pseudoquantizationなしでdevice_mapなしで読み込むと、ValueErrorが発生します。モデルをGPUとCPUに分散させるdevice_mapも、ValueErrorを引き起こします。
  • "disk" を含む device_map は ValueError を発生させます。
  • Pseudo-quantizationは複数GPUをサポートしていません。
  • store_master_weights=Trueなしでのトレーニングはサポートされていません。

リソース

Update on GitHub