Hugging Face's logo

Diffusers documentation

AutoRound

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

and get access to the augmented documentation experience

to get started

AutoRound

AutoRound 是一款先进的量化工具包。它利用符号梯度下降方法，在极低位宽（2-4 位）下以极少的调优即可实现高精度，并提供广泛的硬件兼容性。有关更多详细信息，请参阅我们的论文 SignRoundV1 和 SignRoundV2。

安装 auto-round（版本 ≥ 0.13.0）：

pip install "auto-round>=0.13.0"

要使用 Marlin 内核实现更快的 CUDA 推理，请安装 gptqmodel：

pip install "gptqmodel>=5.8.0"

加载量化模型

通过向 from_pretrained() 传入 AutoRoundConfig 来加载预量化的 AutoRound 模型。该方法适用于任何可通过 Accelerate 加载且包含 torch.nn.Linear 层的模型。

您可以使用 PipelineQuantizationConfig 来量化流水线中的特定组件：

import torch
from diffusers import DiffusionPipeline, PipelineQuantizationConfig, AutoRoundConfig

pipeline_quant_config = PipelineQuantizationConfig(
    quant_mapping={"transformer": AutoRoundConfig(backend="auto")}
)
pipe = DiffusionPipeline.from_pretrained(
    "INCModel/Z-Image-W4A16-AutoRound",
    quantization_config=pipeline_quant_config,
    dtype=torch.bfloat16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)

image = pipe("a cat holding a sign that says hello").images[0]
image.save("output.png")

或者直接加载量化模型组件：

import torch
from diffusers import ZImageTransformer2DModel, ZImagePipeline, AutoRoundConfig

model_id = "INCModel/Z-Image-W4A16-AutoRound"

quantization_config = AutoRoundConfig(backend="auto")
transformer = ZImageTransformer2DModel.from_pretrained(
    model_id,
    subfolder="transformer",
    quantization_config=quantization_config,
    dtype=torch.bfloat16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)

pipe = ZImagePipeline.from_pretrained(
    model_id,
    transformer=transformer,
    dtype=torch.bfloat16,
    device_map="cuda",
)

image = pipe("a cat holding a sign that says hello").images[0]
image.save("output.png")

Diffusers 中的 AutoRound 仅支持加载预量化模型。若要从头开始量化模型，请直接使用AutoRound CLI 或 Python API，然后通过 Diffusers 加载量化结果。

torch.compile

AutoRound 与 torch.compile 兼容，可实现更快的推理。您可以对量化后的 transformer（DiT）进行编译，以获得更好的性能：

import torch
from diffusers import DiffusionPipeline, PipelineQuantizationConfig, AutoRoundConfig

pipeline_quant_config = PipelineQuantizationConfig(
    quant_mapping={"transformer": AutoRoundConfig(backend="auto")}
)
pipe = DiffusionPipeline.from_pretrained(
    "INCModel/Z-Image-W4A16-AutoRound",
    quantization_config=pipeline_quant_config,
    dtype=torch.bfloat16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)

pipe.transformer = torch.compile(pipe.transformer, mode="default", fullgraph=False)

后端

AutoRound 支持多种推理后端，用于 Weight-only 量化模型。后端决定了在前向传播过程中由哪个内核执行反量化。在 AutoRoundConfig 中设置 backend 参数以选择其中一个：

后端值设备要求备注
Auto"auto"任意—默认值。自动选择最佳可用后端。
PyTorch"torch"CPU / CUDA—纯 PyTorch 实现。兼容性最广。
Triton"tritonv2"CUDAtriton基于 Triton 的 GPU 推理内核。
ExllamaV2"exllamav2"CUDAgptqmodel>=5.8.0通过 ExllamaV2 内核实现良好的 CUDA 性能。
Marlin"marlin"CUDAgptqmodel>=5.8.0通过 Marlin 内核实现最佳 CUDA 性能。
from diffusers import AutoRoundConfig

# Auto-select (default)
config = AutoRoundConfig()

# Explicit Triton backend for CUDA
config = AutoRoundConfig(backend="tritonv2")

# Marlin backend for best CUDA performance (requires gptqmodel>=5.8.0)
config = AutoRoundConfig(backend="marlin")

# ExllamaV2 backend for good CUDA performance (requires gptqmodel>=5.8.0)
config = AutoRoundConfig(backend="exllamav2")

# PyTorch backend for CPU/CUDA inference
config = AutoRoundConfig(backend="torch")

保存和加载

保存
load

AutoRound 需要数据校准来量化模型。此操作在 Diffusers 之外直接通过 AutoRound 库 完成：

from auto_round import AutoRound

autoround = AutoRound(
    "Tongyi-MAI/Z-Image",
    scheme="W4A16",  # W4G128 symmetric
    enable_torch_compile=True,
    num_inference_steps=3,
    guidance_scale=7.5,
    dataset="coco2014",
)
autoround.quantize_and_save("Z-Image-W4A16-AutoRound")

有关校准选项的更多详细信息，请参阅 AutoRound 文档。

支持的量化方案

AutoRound 支持多种方案：

  • W4A16（bits:4,group_size:128,sym:True,act_bits:16）
  • W8A16（bits:8,group_size:128,sym:True,act_bits:16）
  • W3A16（bits:3,group_size:128,sym:True,act_bits:16）
  • W2A16（bits:2，group_size:128，sym:True，act_bits:16）
  • GGUF:Q4_K_M（llamacpp 提供的所有 Q_K,Q_0,Q*_1 均受支持）
  • NVFP4（实验性功能，建议导出为 llm_compressor 格式。data_type nvfp4,act_data_type nvfp4,static_global_scale,group_size 16）
  • MXFP4(研究功能，无实际内核，标准 MXFP4，data_type mxfp，act_data_type mxfp，bits 4，act_bits 4，group_size 32)
  • MXINT4(研究功能，无实际内核，标准 MXINT4，data_type mxint,act_data_type mxint,bits 4, act_bits 4, group_size 32)
  • MXFP4_RCEIL(研究功能，无实际内核，NVIDIA 的变体，data_type mxfp，act_data_type mxfp_rceil，bits 4，act_bits 4，group_size 32)
  • MXFP8(研究功能，无实际内核，data_type mxfp,act_data_type mxfp_rceil,group_size 32)
  • FPW8A16(研究功能，无实际内核，data_type fp8,group_size 0->per tensor )
  • FP8_STATIC(研究功能，无实际内核，data_type:fp8,act_data_type:fp8,group_size -1 ->按通道，act_group_size=0->按张量)

此外，你还可以修改group_size、bits、sym以及许多其他配置，尽管可能并没有真正的内核实现。

资源

Update on GitHub

←NVIDIA ModelOpt SDNQ→