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 exija menos memória. Os modelos geralmente são carregados em bf16, o que ocupa 2 bytes por parâmetro. Um modelo de 8B requer 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(), 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.

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.

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 ou BitsAndBytesConfig. A maioria deles não requer um conjunto de dados de calibração. 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.

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.

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 instalado, para Qwen3.5 e Qwen3.5 MoE. Consulte GGUF para mais detalhes.

Salvar um modelo quantizado

Chame save_pretrained() ou 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 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 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 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, GGUF e MLX.

Recursos

• curso Fundamentos de Quantização com Hugging Face
• curso Quantization in Depth

Próximas etapas

• Leia Conceitos de quantização 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.
• Quantize um modelo ao exportá-lo com Quantização de exportações.
• Contribua com um novo método com Contribuir com um método de quantização.