# Visão geral

A quantização armazena os pesos de um modelo, e às vezes suas ativações, em menos bits, de modo que o modelo precise de menos memória. Os modelos geralmente são carregados em bf16, o que ocupa 2 bytes por parâmetro. Um modelo de 8B precisa de cerca de 16GB para seus pesos em bf16, cerca de 8GB em 8 bits e cerca de 4–5GB em 4 bits. Menos bits implicam em alguma perda de precisão, e cada método de quantização faz um compromisso diferente entre memória, velocidade e precisão.

O Transformers integra mais de 20 métodos de quantização por meio de [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained), de modo que você usa o mesmo código de carregamento, independentemente do método escolhido.

## Duas formas de usar um modelo quantizado

A forma como você usa a quantização depende de o seu checkpoint já estar quantizado.

| Você tem | O que você faz | Métodos |
|---|---|---|
| Um checkpoint de precisão completa | Passe uma configuração de quantização para `from_pretrained` e os pesos serão quantizados durante o carregamento. | [Quantizar um modelo durante o carregamento](#quantize-a-model-while-loading) |
| Um checkpoint que já está quantizado | Chame `from_pretrained` sem uma configuração de quantização. O Transformers lê o método do `config.json` do checkpoint ou do arquivo GGUF que você especificar. | [Carregar um checkpoint pré-quantizado](#load-a-pre-quantized-checkpoint) |

Alguns métodos, como AWQ, AutoRound, AQLM, compressed-tensors e GGUF, só podem ser carregados a partir de um checkpoint. Você quantiza o modelo primeiro com a própria biblioteca do método e, em seguida, carrega o resultado no Transformers.

## Quantize um modelo durante o carregamento

Crie a classe de configuração do método e passe-a para `quantization_config`. O exemplo abaixo carrega um modelo de 8B em 4 bits com [bitsandbytes](./bitsandbytes).

```py
import torch
from transformers import AutoModelForCausalLM, BitsAndBytesConfig

quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B-Instruct",
    quantization_config=quantization_config,
    device_map="auto",
)
```

Cada método deste grupo possui sua própria classe de configuração, como [TorchAoConfig](/docs/transformers/main/pt/main_classes/quantization#transformers.TorchAoConfig) ou [BitsAndBytesConfig](/docs/transformers/main/pt/main_classes/quantization#transformers.BitsAndBytesConfig). A maioria deles não requer um conjunto de dados de calibração. [GPTQ](./gptq) é a exceção, pois realiza a calibração em um conjunto de dados durante o carregamento do modelo.

## Carregar um checkpoint pré-quantizado

Um checkpoint pré-quantizado armazena um `quantization_config` em seu `config.json`. Quando o `from_pretrained` o encontra, o quantizador correspondente é selecionado automaticamente.

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "TheBloke/zephyr-7B-alpha-AWQ",
    device_map="auto",
)
print(model.config.quantization_config.quant_method)
```

Instale a biblioteca na qual o método depende antes de carregar o checkpoint. Cada página de método lista o que deve ser instalado. Para alterar as opções de carregamento, como o backend de kernel que será executado, passe uma config do mesmo tipo. Suas opções são mescladas com as armazenadas no checkpoint.

### Checkpoints GGUF

Um checkpoint GGUF é um arquivo único que contém os pesos, a configuração e o tokenizer, e não possui um `config.json` para o `from_pretrained` ler. Nomeie o arquivo com `gguf_file`.

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "unsloth/Qwen3.5-4B-GGUF",
    gguf_file="Qwen3.5-4B-Q4_K_M.gguf",
)
```

A maioria dos modelos GGUF é desquantizada para precisão total durante o carregamento, o que faz com que utilizem a mesma quantidade de memória de um modelo não quantizado. Os pesos permanecem compactados apenas no MPS, com o pacote [kernels](https://huggingface.co/docs/kernels/index) instalado, para Qwen3.5 e Qwen3.5 MoE. Consulte [GGUF](./gguf) para mais detalhes.

## Salvar um modelo quantizado

Chame [save_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.save_pretrained) ou [push_to_hub()](/docs/transformers/main/pt/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) para salvar os pesos quantizados e seu `quantization_config`. Nem todo método consegue salvar seus pesos quantizados.

## Escolha um método

[Escolha um método](./selecting) recomenda um ponto de partida para objetivos comuns e compara todos os métodos por hardware, largura de bits, economia, ajuste fino e suporte a `torch.compile`. Use o [seletor de quantização](https://huggingface.co/spaces/stevhliu/quantization-picker) para verificar se um modelo cabe na memória do seu hardware em cada precisão.

## Outras ferramentas

Essas ferramentas quantizam modelos fora do Transformers.

- [Optimum](https://huggingface.co/docs/optimum/index) quantiza modelos para hardwares e runtimes específicos, como CPUs da Intel e ONNX Runtime.
- Os Spaces do Hub quantizam um modelo e enviam o resultado para sua conta: [bitsandbytes](https://huggingface.co/spaces/bnb-community/bnb-my-repo), [GGUF](https://huggingface.co/spaces/ggml-org/gguf-my-repo) e [MLX](https://huggingface.co/spaces/mlx-community/mlx-my-repo).

## Recursos

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

## Próximas etapas

- Leia [Conceitos de quantização](./concept_guide) para entender como funcionam os esquemas de quantização, a granularidade e as técnicas.
- Quantize o cache KV para economizar memória durante gerações longas com o [cache quantizado](../kv_cache#quantized-cache).
- Quantize um modelo ao exportá-lo com [Quantização de exportações](../exporters_quantization).
- Contribua com um novo método com [Contribuir com um método de quantização](./contribute).