Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /pt /quantization /overview.md

mishig

2 days ago

preview code

download

raw

10.6 kB

# Começando

A quantização foca em representar dados com menos bits, ao mesmo tempo em que tenta preservar a precisão dos dados originais. Isso geralmente significa converter um tipo de dados para representar a mesma informação com menos bits. Por exemplo, se os pesos do seu modelo forem armazenados como números de ponto flutuante de 32 bits e forem quantizados para números de ponto flutuante de 16 bits, isso reduz o tamanho do modelo pela metade, o que facilita o armazenamento e diminui o uso de memória. A menor precisão também pode acelerar a inferência, pois leva menos tempo para realizar cálculos com menos bits.

O Diffusers suporta vários backends de quantização para tornar grandes modelos de difusão, como o [Flux](../api/pipelines/flux), mais acessíveis. Este guia mostra como usar a classe [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.PipelineQuantizationConfig) para quantizar um pipeline durante sua inicialização a partir de um checkpoint pré-treinado ou não quantizado.

## Quantização em nível de pipeline

Existem duas formas de usar [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.PipelineQuantizationConfig), dependendo do nível de personalização que você deseja aplicar à configuração de quantização.

- para casos de uso básicos, defina os argumentos `quant_backend`, `quant_kwargs` e `components_to_quantize`
- para controle granular de quantização, defina um `quant_mapping` que fornece a configuração de quantização para componentes individuais do modelo

### Quantização básica

Inicialize [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.PipelineQuantizationConfig) com os seguintes parâmetros.

- `quant_backend` especifica qual backend de quantização usar. Os backends atualmente suportados incluem: `bitsandbytes_4bit`, `bitsandbytes_8bit`, `gguf`, `quanto` e `torchao`.
- `quant_kwargs` especifica os argumentos de quantização a serem usados.

> [!TIP]
> Esses argumentos de `quant_kwargs` são diferentes para cada backend. Consulte a documentação da [Quantization API](../api/quantization) para ver os argumentos de cada backend.
- `components_to_quantize` especifica qual(is) componente(s) do pipeline devem ser quantizados. Normalmente, você deve quantizar os componentes mais intensivos em computação, como o transformer. O codificador de texto é outro componente a ser considerado para quantização se o pipeline tiver mais de um, como no caso de [FluxPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/flux#diffusers.FluxPipeline). O exemplo abaixo quantiza o codificador de texto T5 em [FluxPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/flux#diffusers.FluxPipeline), mantendo o modelo CLIP intacto.
   `components_to_quantize` aceita uma lista para vários modelos ou uma string para um único modelo.
O exemplo abaixo carrega o backend bitsandbytes com os seguintes argumentos de [BitsAndBytesConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.BitsAndBytesConfig), `load_in_4bit`, `bnb_4bit_quant_type` e `bnb_4bit_compute_dtype`.
```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"],
)
```
Passe o `pipeline_quant_config` para [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) para quantizar o 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]
```

### Quantização avançada

O argumento `quant_mapping` oferece mais opções sobre como quantizar cada componente individual em um pipeline, como combinar diferentes backends de quantização.

Inicialize [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.PipelineQuantizationConfig) e passe um `quant_mapping` para ele. O `quant_mapping` permite especificar as opções de quantização para cada componente do pipeline, como o transformer e o text encoder.

O exemplo abaixo usa dois backends de quantização, [QuantoConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.QuantoConfig) e [transformers.BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.22.2/en/main_classes/quantization#transformers.BitsAndBytesConfig), para o transformer e o codificador de texto.

```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
        ),
    }
)
```

Existe um backend bitsandbytes separado no [Transformers](https://huggingface.co/docs/transformers/main_classes/quantization#transformers.BitsAndBytesConfig). Você precisa importar e usar [transformers.BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.22.2/en/main_classes/quantization#transformers.BitsAndBytesConfig) para componentes que vêm do Transformers. Por exemplo, `text_encoder_2` em [FluxPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/flux#diffusers.FluxPipeline) é um [T5EncoderModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/t5#transformers.T5EncoderModel) do Transformers, então você precisa usar [transformers.BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.22.2/en/main_classes/quantization#transformers.BitsAndBytesConfig) em vez de [diffusers.BitsAndBytesConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.BitsAndBytesConfig).

> [!TIP]
> Use o método de [quantização básica](#basic-quantization) acima se você não quiser gerenciar esses imports distintos ou não tiver certeza de onde cada componente do pipeline vem.

```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
        ),
    }
)
```

Passe o `pipeline_quant_config` para [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) para quantizar o 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]
```

## Carregando checkpoints pré-quantizados

Alguns backends de quantização suportam o carregamento de checkpoints que já foram quantizados e enviados ao Hub. Nesse caso, a configuração de quantização é armazenada no `config.json` do modelo e é lida automaticamente — você não precisa criar um [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.PipelineQuantizationConfig) nem passar um argumento `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"
```

Os seguintes backends suportam o carregamento de checkpoints pré-quantizados nativamente.

| Backend | Observações |
|---|---|
| [bitsandbytes](./bitsandbytes) | Config é salvo em `config.json`; nenhum argumento extra é necessário. Suporta quantização em tempo de execução, bem como o carregamento de checkpoints pré-quantizados. |
| [torchao](./torchao) | Igual ao acima. |
| [GGUF](./gguf) | Usa `from_single_file` com classes de Model; o carregamento em nível de pipeline não é suportado. |
| [BFL](./bfl) | Carrega checkpoints de arquivo único `fp8r` e `nvfp4` da Black Forest Labs com `from_single_file`; o carregamento em nível de pipeline não é suportado. |
| [AutoRound](./autoround) | Apenas o carregamento é suportado; quantize primeiro com a CLI ou a API Python do AutoRound. |
| [Nunchaku Lite](./nunchaku) | Config é salvo em `config.json`; requer o pacote `kernels`. Apenas o carregamento é suportado. |
| [ModelOpt](./modelopt) | Apenas o carregamento de modelos pré-quantizados é suportado. |
| [SDNQ](./sdnq) | Suporta tanto a quantização em tempo de execução quanto o carregamento de modelos pré-quantizados; requer o pacote `sdnq`. |

## Recursos

Confira os recursos abaixo para saber mais sobre quantização.

- Se você é novo em quantização, recomendamos conferir os seguintes cursos introdutórios, desenvolvidos em colaboração com a DeepLearning.AI.

    - [Fundamentos de Quantização com Hugging Face](https://www.deeplearning.ai/short-courses/quantization-fundamentals-with-hugging-face/)
    - [Quantização em profundidade](https://www.deeplearning.ai/short-courses/quantization-in-depth/)

- Consulte o [Guia para contribuir com um novo método de quantização](https://huggingface.co/docs/transformers/main/en/quantization/contribute) se você estiver interessado em adicionar um novo método de quantização.

- A [Visão geral](https://huggingface.co/docs/transformers/quantization/overview#when-to-use-what) da quantização do Transformers fornece uma visão geral das vantagens e desvantagens dos diferentes backends de quantização.

- Leia o post no blog [Exploring Quantization Backends in Diffusers](https://huggingface.co/blog/diffusers-quantization) para uma breve introdução a cada backend de quantização, como escolher um backend e como combinar a quantização com outras otimizações de memória.

Xet Storage Details

Size:: 10.6 kB
Xet hash:: b6a21492c5f5ac3b7c4b79a3c1ff9f7a26be167b6bcc962f83cc40bf7cdb0662

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

	# Começando

	A quantização foca em representar dados com menos bits, ao mesmo tempo em que tenta preservar a precisão dos dados originais. Isso geralmente significa converter um tipo de dados para representar a mesma informação com menos bits. Por exemplo, se os pesos do seu modelo forem armazenados como números de ponto flutuante de 32 bits e forem quantizados para números de ponto flutuante de 16 bits, isso reduz o tamanho do modelo pela metade, o que facilita o armazenamento e diminui o uso de memória. A menor precisão também pode acelerar a inferência, pois leva menos tempo para realizar cálculos com menos bits.

	O Diffusers suporta vários backends de quantização para tornar grandes modelos de difusão, como o [Flux](../api/pipelines/flux), mais acessíveis. Este guia mostra como usar a classe [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.PipelineQuantizationConfig) para quantizar um pipeline durante sua inicialização a partir de um checkpoint pré-treinado ou não quantizado.

	## Quantização em nível de pipeline

	Existem duas formas de usar [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.PipelineQuantizationConfig), dependendo do nível de personalização que você deseja aplicar à configuração de quantização.

	- para casos de uso básicos, defina os argumentos `quant_backend`, `quant_kwargs` e `components_to_quantize`
	- para controle granular de quantização, defina um `quant_mapping` que fornece a configuração de quantização para componentes individuais do modelo

	### Quantização básica

	Inicialize [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.PipelineQuantizationConfig) com os seguintes parâmetros.

	- `quant_backend` especifica qual backend de quantização usar. Os backends atualmente suportados incluem: `bitsandbytes_4bit`, `bitsandbytes_8bit`, `gguf`, `quanto` e `torchao`.
	- `quant_kwargs` especifica os argumentos de quantização a serem usados.

	> [!TIP]
	> Esses argumentos de `quant_kwargs` são diferentes para cada backend. Consulte a documentação da [Quantization API](../api/quantization) para ver os argumentos de cada backend.

	- `components_to_quantize` especifica qual(is) componente(s) do pipeline devem ser quantizados. Normalmente, você deve quantizar os componentes mais intensivos em computação, como o transformer. O codificador de texto é outro componente a ser considerado para quantização se o pipeline tiver mais de um, como no caso de [FluxPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/flux#diffusers.FluxPipeline). O exemplo abaixo quantiza o codificador de texto T5 em [FluxPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/flux#diffusers.FluxPipeline), mantendo o modelo CLIP intacto.

	`components_to_quantize` aceita uma lista para vários modelos ou uma string para um único modelo.

	O exemplo abaixo carrega o backend bitsandbytes com os seguintes argumentos de [BitsAndBytesConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.BitsAndBytesConfig), `load_in_4bit`, `bnb_4bit_quant_type` e `bnb_4bit_compute_dtype`.

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

	Passe o `pipeline_quant_config` para [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) para quantizar o 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]
	```

	### Quantização avançada

	O argumento `quant_mapping` oferece mais opções sobre como quantizar cada componente individual em um pipeline, como combinar diferentes backends de quantização.

	Inicialize [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.PipelineQuantizationConfig) e passe um `quant_mapping` para ele. O `quant_mapping` permite especificar as opções de quantização para cada componente do pipeline, como o transformer e o text encoder.

	O exemplo abaixo usa dois backends de quantização, [QuantoConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.QuantoConfig) e [transformers.BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.22.2/en/main_classes/quantization#transformers.BitsAndBytesConfig), para o transformer e o codificador de texto.

	```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
	),
	}
	)
	```

	Existe um backend bitsandbytes separado no [Transformers](https://huggingface.co/docs/transformers/main_classes/quantization#transformers.BitsAndBytesConfig). Você precisa importar e usar [transformers.BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.22.2/en/main_classes/quantization#transformers.BitsAndBytesConfig) para componentes que vêm do Transformers. Por exemplo, `text_encoder_2` em [FluxPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/flux#diffusers.FluxPipeline) é um [T5EncoderModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/t5#transformers.T5EncoderModel) do Transformers, então você precisa usar [transformers.BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.22.2/en/main_classes/quantization#transformers.BitsAndBytesConfig) em vez de [diffusers.BitsAndBytesConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.BitsAndBytesConfig).

	> [!TIP]
	> Use o método de [quantização básica](#basic-quantization) acima se você não quiser gerenciar esses imports distintos ou não tiver certeza de onde cada componente do pipeline vem.

	```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
	),
	}
	)
	```

	Passe o `pipeline_quant_config` para [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) para quantizar o 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]
	```

	## Carregando checkpoints pré-quantizados

	Alguns backends de quantização suportam o carregamento de checkpoints que já foram quantizados e enviados ao Hub. Nesse caso, a configuração de quantização é armazenada no `config.json` do modelo e é lida automaticamente — você não precisa criar um [PipelineQuantizationConfig](/docs/diffusers/v0.43.0/pt/api/quantization#diffusers.PipelineQuantizationConfig) nem passar um argumento `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"
	```

	Os seguintes backends suportam o carregamento de checkpoints pré-quantizados nativamente.

	\| Backend \| Observações \|
	\|---\|---\|
	\| [bitsandbytes](./bitsandbytes) \| Config é salvo em `config.json`; nenhum argumento extra é necessário. Suporta quantização em tempo de execução, bem como o carregamento de checkpoints pré-quantizados. \|
	\| [torchao](./torchao) \| Igual ao acima. \|
	\| [GGUF](./gguf) \| Usa `from_single_file` com classes de Model; o carregamento em nível de pipeline não é suportado. \|
	\| [BFL](./bfl) \| Carrega checkpoints de arquivo único `fp8r` e `nvfp4` da Black Forest Labs com `from_single_file`; o carregamento em nível de pipeline não é suportado. \|
	\| [AutoRound](./autoround) \| Apenas o carregamento é suportado; quantize primeiro com a CLI ou a API Python do AutoRound. \|
	\| [Nunchaku Lite](./nunchaku) \| Config é salvo em `config.json`; requer o pacote `kernels`. Apenas o carregamento é suportado. \|
	\| [ModelOpt](./modelopt) \| Apenas o carregamento de modelos pré-quantizados é suportado. \|
	\| [SDNQ](./sdnq) \| Suporta tanto a quantização em tempo de execução quanto o carregamento de modelos pré-quantizados; requer o pacote `sdnq`. \|

	## Recursos

	Confira os recursos abaixo para saber mais sobre quantização.

	- Se você é novo em quantização, recomendamos conferir os seguintes cursos introdutórios, desenvolvidos em colaboração com a DeepLearning.AI.

	- [Fundamentos de Quantização com Hugging Face](https://www.deeplearning.ai/short-courses/quantization-fundamentals-with-hugging-face/)
	- [Quantização em profundidade](https://www.deeplearning.ai/short-courses/quantization-in-depth/)

	- Consulte o [Guia para contribuir com um novo método de quantização](https://huggingface.co/docs/transformers/main/en/quantization/contribute) se você estiver interessado em adicionar um novo método de quantização.

	- A [Visão geral](https://huggingface.co/docs/transformers/quantization/overview#when-to-use-what) da quantização do Transformers fornece uma visão geral das vantagens e desvantagens dos diferentes backends de quantização.

	- Leia o post no blog [Exploring Quantization Backends in Diffusers](https://huggingface.co/blog/diffusers-quantization) para uma breve introdução a cada backend de quantização, como escolher um backend e como combinar a quantização com outras otimizações de memória.