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)。

下表总结了 FP-Quant 在 Transformers 中的支持情况。

配置FPQuantConfig
quant_methodfp_quant
工作流加载时量化
位4
硬件NVIDIA Blackwell GPU;其他 CUDA GPU 以及使用 pseudoquantization=True 的 Intel XPU
保存✅
微调仅在 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 进行量化以获得更高精度的模型,请在调用 from_pretrained() 时传入其 Hub 仓库,且不要提供 quantization_config。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"。
pseudoquantizationFalse使用 Triton 内核模拟 FP4,而不是运行 QuTLASS 内核。在非 Blackwell GPU 上必需。

有关其余参数,请参阅 FPQuantConfig。

使用量化权重进行训练

FP-Quant 支持 QAT。设置 store_master_weights=True 以保留高精度权重,使其能够被更新,并设置 forward_method="quest",该方法在 QAT 中比 "abs_max" 表现更好。"quest" 方法仅适用于 MXFP4。在使用 MXFP4 前向传播时,backward_dtype 还可以将反向传播量化为 "mxfp8" 或 "mxfp4",而不是 "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",
)

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。
  • 伪量化不支持多 GPU。
  • 不支持在未设置 store_master_weights=True 的情况下进行训练。

资源

Update on GitHub