Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /zh /quantization /autoround.md

mishig

4 days ago

preview code

download

raw

7.17 kB

# AutoRound

[AutoRound](https://github.com/intel/auto-round) 是一款先进的量化工具包。它利用符号梯度下降方法，在极低位宽（2-4 位）下以极少的调优即可实现高精度，并提供广泛的硬件兼容性。有关更多详细信息，请参阅我们的论文 [SignRoundV1](https://arxiv.org/pdf/2309.05516) 和 [SignRoundV2](https://arxiv.org/abs/2512.04746)。

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

```bash
pip install "auto-round>=0.13.0"
```

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

```bash
pip install "gptqmodel>=5.8.0"
```

## 加载量化模型

通过向 [from_pretrained()](/docs/diffusers/v0.43.0/zh/api/models/overview#diffusers.ModelMixin.from_pretrained) 传入 `AutoRoundConfig` 来加载预量化的 AutoRound 模型。该方法适用于任何可通过 [Accelerate](https://hf.co/docs/accelerate/index) 加载且包含 `torch.nn.Linear` 层的模型。

您可以使用 [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/zh/api/quantization#diffusers.PipelineQuantizationConfig) 来量化流水线中的特定组件：

```python
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")
```

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

```python
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")
```

> [!NOTE]
> Diffusers 中的 AutoRound 仅支持加载*预量化*模型。若要从头开始量化模型，请直接使用[AutoRound CLI 或 Python API](https://github.com/intel/auto-round)，然后通过 Diffusers 加载量化结果。

## torch.compile

AutoRound 与 [`torch.compile`](../optimization/fp16#torchcompile) 兼容，可实现更快的推理。您可以对量化后的 transformer（DiT）进行编译，以获得更好的性能：

```python
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"` | CUDA | `triton` | 基于 Triton 的 GPU 推理内核。 |
| **ExllamaV2** | `"exllamav2"` | CUDA | `gptqmodel>=5.8.0` | 通过 ExllamaV2 内核实现良好的 CUDA 性能。 |
| **Marlin** | `"marlin"` | CUDA | `gptqmodel>=5.8.0` | 通过 Marlin 内核实现最佳 CUDA 性能。 |

```python
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")
```

## 保存和加载

AutoRound 需要数据校准来量化模型。此操作在 Diffusers 之外直接通过 [AutoRound 库](https://github.com/intel/auto-round) 完成：

```python
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 文档](https://github.com/intel/auto-round)。

```python
import torch
from diffusers import ZImageTransformer2DModel, ZImagePipeline
model_id = "INCModel/Z-Image-W4A16-AutoRound"
# The inference backend will be automatically selected.
pipe = ZImagePipeline.from_pretrained(
    model_id,
    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")
```

### 支持的量化方案

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`以及许多其他配置，尽管可能并没有真正的内核实现。
## 资源
- [Hub 上的预量化 AutoRound 模型](https://huggingface.co/models?search=autoround)

Xet Storage Details

Size:: 7.17 kB
Xet hash:: 71dba01b0040de5aa1a68586207f8dfcdbec81313b2175ba3a0637935bda51c4

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# AutoRound

	[AutoRound](https://github.com/intel/auto-round) 是一款先进的量化工具包。它利用符号梯度下降方法，在极低位宽（2-4 位）下以极少的调优即可实现高精度，并提供广泛的硬件兼容性。有关更多详细信息，请参阅我们的论文 [SignRoundV1](https://arxiv.org/pdf/2309.05516) 和 [SignRoundV2](https://arxiv.org/abs/2512.04746)。

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

	```bash
	pip install "auto-round>=0.13.0"
	```

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

	```bash
	pip install "gptqmodel>=5.8.0"
	```

	## 加载量化模型

	通过向 [from_pretrained()](/docs/diffusers/v0.43.0/zh/api/models/overview#diffusers.ModelMixin.from_pretrained) 传入 `AutoRoundConfig` 来加载预量化的 AutoRound 模型。该方法适用于任何可通过 [Accelerate](https://hf.co/docs/accelerate/index) 加载且包含 `torch.nn.Linear` 层的模型。

	您可以使用 [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/zh/api/quantization#diffusers.PipelineQuantizationConfig) 来量化流水线中的特定组件：

	```python
	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")
	```

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

	```python
	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")
	```

	> [!NOTE]
	> Diffusers 中的 AutoRound 仅支持加载预量化模型。若要从头开始量化模型，请直接使用[AutoRound CLI 或 Python API](https://github.com/intel/auto-round)，然后通过 Diffusers 加载量化结果。

	## torch.compile

	AutoRound 与 [`torch.compile`](../optimization/fp16#torchcompile) 兼容，可实现更快的推理。您可以对量化后的 transformer（DiT）进行编译，以获得更好的性能：

	```python
	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"` \| CUDA \| `triton` \| 基于 Triton 的 GPU 推理内核。 \|
	\| ExllamaV2 \| `"exllamav2"` \| CUDA \| `gptqmodel>=5.8.0` \| 通过 ExllamaV2 内核实现良好的 CUDA 性能。 \|
	\| Marlin \| `"marlin"` \| CUDA \| `gptqmodel>=5.8.0` \| 通过 Marlin 内核实现最佳 CUDA 性能。 \|

	```python
	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")
	```

	## 保存和加载

	AutoRound 需要数据校准来量化模型。此操作在 Diffusers 之外直接通过 [AutoRound 库](https://github.com/intel/auto-round) 完成：

	```python
	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 文档](https://github.com/intel/auto-round)。

	```python
	import torch
	from diffusers import ZImageTransformer2DModel, ZImagePipeline

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

	# The inference backend will be automatically selected.
	pipe = ZImagePipeline.from_pretrained(
	model_id,
	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")
	```

	### 支持的量化方案

	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`以及许多其他配置，尽管可能并没有真正的内核实现。

	## 资源

	- [Hub 上的预量化 AutoRound 模型](https://huggingface.co/models?search=autoround)