# 快速入门

量化旨在用更少的位数来表示数据，同时尽量保留原始数据的精度。这通常意味着将数据类型转换为用更少的位数表示相同的信息。例如，如果你的模型权重以 32 位浮点数存储，并将其量化为 16 位浮点数，模型大小将减半，从而更易于存储并减少内存占用。较低的精度还可以加速推理，因为使用更少的位数进行计算所需的时间更短。

Diffusers 支持多种量化后端，使 [Flux](../api/pipelines/flux) 等大型扩散模型更易用。本指南介绍如何使用 [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/zh/api/quantization#diffusers.PipelineQuantizationConfig) 类，在从预训练或非量化检查点初始化流水线时对其进行量化。

## Pipeline 级别的量化

根据您希望对量化配置进行自定义的程度，有两种方式使用 [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/zh/api/quantization#diffusers.PipelineQuantizationConfig)。

- 对于基本使用场景，请定义 `quant_backend`、`quant_kwargs` 和 `components_to_quantize` 参数
- 如需进行细粒度的量化控制，请定义一个 `quant_mapping`，为各个模型组件提供量化配置。

### 基础量化

使用以下参数初始化 [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/zh/api/quantization#diffusers.PipelineQuantizationConfig)。

- `quant_backend` 指定要使用的量化后端。目前支持的后端包括：`bitsandbytes_4bit`、`bitsandbytes_8bit`、`gguf`、`quanto` 和 `torchao`。
- `quant_kwargs` 指定要使用的量化参数。

> [!TIP]
> 这些 `quant_kwargs` 参数因后端而异。请参阅 [量化 API](../api/quantization) 文档以查看各后端的参数。

- `components_to_quantize` 指定要量化的流水线组件。通常，您应该量化计算量最大的组件，例如 transformer。如果流水线包含多个文本编码器（例如 [FluxPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/flux#diffusers.FluxPipeline)），则文本编码器是另一个需要考虑量化的组件。下面的示例对 [FluxPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/flux#diffusers.FluxPipeline) 中的 T5 文本编码器进行量化，同时保持 CLIP 模型不变。

   `components_to_quantize` 可以接受一个列表（用于多个模型）或一个字符串（用于单个模型）。

以下示例使用 [BitsAndBytesConfig](/docs/diffusers/v0.43.0/zh/api/quantization#diffusers.BitsAndBytesConfig) 中的 `load_in_4bit`、`bnb_4bit_quant_type` 和 `bnb_4bit_compute_dtype` 参数加载 bitsandbytes 后端。

```py
import torch
from diffusers import DiffusionPipeline
from diffusers.quantizers import PipelineQuantizationConfig

pipeline_quant_config = PipelineQuantizationConfig(
    quant_backend="bitsandbytes_4bit",
    quant_kwargs={"load_in_4bit": True, "bnb_4bit_quant_type": "nf4", "bnb_4bit_compute_dtype": torch.bfloat16},
    components_to_quantize=["transformer", "text_encoder_2"],
)
```

将 `pipeline_quant_config` 传递给 [from_pretrained()](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) 以量化该 pipeline。

```py
pipe = DiffusionPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    quantization_config=pipeline_quant_config,
    dtype=torch.bfloat16,
).to("cuda")  # or "mps", "xpu", "cpu"

image = pipe("photo of a cute dog").images[0]
```

### 高级量化

`quant_mapping` 参数提供了更多选项，用于指定流水线中各个组件的量化方式，例如组合使用不同的量化后端。

初始化 [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/zh/api/quantization#diffusers.PipelineQuantizationConfig) 并向其传入 `quant_mapping`。`quant_mapping` 允许你为流水线中的每个组件（例如 transformer 和 text encoder）指定量化选项。

下面的示例使用两个量化后端 [QuantoConfig](/docs/diffusers/v0.43.0/zh/api/quantization#diffusers.QuantoConfig) 和 [transformers.BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.22.2/en/main_classes/quantization#transformers.BitsAndBytesConfig)，分别用于 transformer 和文本编码器。

```py
import torch
from diffusers import DiffusionPipeline
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig
from diffusers.quantizers.quantization_config import QuantoConfig
from diffusers.quantizers import PipelineQuantizationConfig
from transformers import BitsAndBytesConfig as TransformersBitsAndBytesConfig

pipeline_quant_config = PipelineQuantizationConfig(
    quant_mapping={
        "transformer": QuantoConfig(weights_dtype="int8"),
        "text_encoder_2": TransformersBitsAndBytesConfig(
            load_in_4bit=True, compute_dtype=torch.bfloat16
        ),
    }
)
```

[Transformers](https://huggingface.co/docs/transformers/main_classes/quantization#transformers.BitsAndBytesConfig) 中有一个独立的 bitsandbytes 后端。对于来自 Transformers 的组件，您需要导入并使用 [transformers.BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.22.2/en/main_classes/quantization#transformers.BitsAndBytesConfig)。例如，[FluxPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/flux#diffusers.FluxPipeline) 中的 `text_encoder_2` 是 Transformers 中的 [T5EncoderModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/t5#transformers.T5EncoderModel)，因此您需要使用 [transformers.BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.22.2/en/main_classes/quantization#transformers.BitsAndBytesConfig) 而不是 [diffusers.BitsAndBytesConfig](/docs/diffusers/v0.43.0/zh/api/quantization#diffusers.BitsAndBytesConfig)。

> [!TIP]
> 如果您不想管理这些不同的导入，或者不确定每个流水线组件的来源，请使用上述的[基础量化](#basic-quantization)方法。

```py
import torch
from diffusers import DiffusionPipeline
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig
from diffusers.quantizers import PipelineQuantizationConfig
from transformers import BitsAndBytesConfig as TransformersBitsAndBytesConfig

pipeline_quant_config = PipelineQuantizationConfig(
    quant_mapping={
        "transformer": DiffusersBitsAndBytesConfig(load_in_4bit=True, bnb_4bit_compute_dtype=torch.bfloat16),
        "text_encoder_2": TransformersBitsAndBytesConfig(
            load_in_4bit=True, compute_dtype=torch.bfloat16
        ),
    }
)
```

将 `pipeline_quant_config` 传递给 [from_pretrained()](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) 以量化该 pipeline。

```py
pipe = DiffusionPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    quantization_config=pipeline_quant_config,
    dtype=torch.bfloat16,
).to("cuda")  # or "mps", "xpu", "cpu"

image = pipe("photo of a cute dog").images[0]
```

## 加载预量化检查点

某些量化后端支持加载已量化并上传至 Hub 的检查点。在这种情况下，量化配置存储在模型的 `config.json` 中并会被自动读取——您无需创建 [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/zh/api/quantization#diffusers.PipelineQuantizationConfig) 或传入 `quantization_config` 参数。

```py
import torch
from diffusers import DiffusionPipeline

pipe = DiffusionPipeline.from_pretrained(
    "rootonchair/ERNIE-Image-Turbo-nunchaku-lite-nvfp4",
    dtype=torch.bfloat16,
).to("cuda")  # or "mps", "xpu", "cpu"
```

以下后端开箱即支持加载预量化检查点。

| 后端 | 备注 |
|---|---|
| [bitsandbytes](./bitsandbytes) | Config 保存在 `config.json` 中，无需额外参数。支持即时量化以及加载预量化检查点。 |
| [torchao](./torchao) | 同上。 |
| [GGUF](./gguf) | 使用 `from_single_file` 与 Model 类；不支持 pipeline 级别的加载。 |
| [BFL](./bfl) | 使用 `from_single_file` 加载 Black Forest Labs 的 `fp8r` 和 `nvfp4` 单文件检查点；不支持流水线级别的加载。 |
| [AutoRound](./autoround) | 仅支持加载；请先使用 AutoRound CLI 或 Python API 进行量化。 |
| [Nunchaku Lite](./nunchaku) | Config 保存在 `config.json` 中；需要 `kernels` 包。仅支持加载。 |
| [ModelOpt](./modelopt) | 仅支持加载预量化模型。 |
| [SDNQ](./sdnq) | 支持在运行时进行量化以及加载预量化模型；需要 `sdnq` 包。 |

## 资源

请查看以下资源，以了解更多有关量化的信息。

- 如果您是量化新手，我们推荐查看以下与 DeepLearning.AI 合作推出的入门友好课程。

    - [使用 Hugging Face 了解量化基础](https://www.deeplearning.ai/short-courses/quantization-fundamentals-with-hugging-face/)
    - [深入量化](https://www.deeplearning.ai/short-courses/quantization-in-depth/)

- 如果您有兴趣添加新的量化方法，请参阅[贡献新量化方法指南](https://huggingface.co/docs/transformers/main/en/quantization/contribute)。

- Transformers 量化[概述](https://huggingface.co/docs/transformers/quantization/overview#when-to-use-what)介绍了不同量化后端的优缺点。

- 阅读[探索 Diffusers 中的量化后端](https://huggingface.co/blog/diffusers-quantization)博客文章，了解每个量化后端的简要介绍、如何选择合适的后端，以及如何将量化与其他内存优化技术结合使用。