Visão geral

O Transformers oferece diversas técnicas de otimização de inferência para tornar os modelos rápidos, acessíveis e viáveis. As opções incluem mecanismos de atenção alternativos para reduzir o tráfego de memória, compilação de código para uma execução mais rápida e kernels otimizados para aumentar a taxa de transferência. Combine essas técnicas para obter o máximo desempenho.

Para configuração de dispositivo e ajustes específicos de hardware, consulte os guias de Hardware. Verifique quais técnicas são suportadas pelo seu hardware antes de aplicar as otimizações abaixo.

Agent prompt

Ajude o usuário a escolher uma otimização para sua carga de trabalho de inferência com Transformers. Primeiro, identifique se a memória ou a velocidade se torna um problema ao carregar o modelo, processar entradas longas, gerar sequências mais longas ou atender a solicitações simultâneas. Use o guia correspondente abaixo e verifique o suporte para o modelo e o hardware do usuário antes de recomendar uma alteração.

Solicite o modelo e a revisão, as versões das bibliotecas, a GPU e a VRAM disponível, a RAM do CPU, o comprimento da entrada, o limite de geração, o tamanho do lote e o número de solicitações simultâneas. Faça perguntas de acompanhamento quando detalhes ausentes possam alterar a recomendação e declare suas premissas.
Use o ponto em que o problema ocorre para escolher o que investigar. Verifique os pesos do modelo e as configurações de carregamento para a memória no momento do carregamento, o cache KV conforme as sequências geradas crescem, as alocações de atenção para entradas longas e o estado e agendamento por solicitação para solicitações concorrentes. Trate a quantização de pesos e a quantização do cache KV como configurações separadas.
Recomende uma alteração por vez. Verifique a compatibilidade do modelo e do hardware, em seguida, meça a memória de pico da GPU, a latência ou o throughput e a qualidade da saída no mesmo trabalho representativo. Explique qualquer redução no comprimento da entrada, no comprimento da geração ou na concorrência como um compromisso do trabalho.
Relate a configuração proposta, a documentação que a sustenta, os compromissos esperados, as questões de compatibilidade não resolvidas e um procedimento de validação. Separe medições de estimativas. Se você não puder executar a carga de trabalho, declare que o ajuste e o desempenho permanecem não verificados.

Memória e velocidade estão intimamente relacionadas, mas não são a mesma coisa. Reduzir a pegada de memória torna um modelo “mais rápido” porque há menos dados para mover. Otimizações puras de velocidade nem sempre reduzem a memória e, às vezes, aumentam o uso. Escolha a otimização adequada com base no seu caso de uso e no seu hardware.

Use a tabela abaixo para escolher uma técnica de otimização.

Técnica	Velocidade	Memória
Compilação	✅
Backends de atenção	✅	✅
Kernels	✅	✅
Quantização	✅	✅
Cache	✅	✅
Paralelismo	✅
Loteamento contínuo	✅

Este guia oferece uma introdução rápida às otimizações do Transformers.

Compilação

torch.compile reduz a sobrecarga do Python, funde operações e cria kernels ajustados para as suas formas e o seu hardware. A primeira execução faz o aquecimento e as execuções subsequentes usam o caminho compilado mais rápido.

Passe um cache de tamanho fixo para generate() para acionar automaticamente o torch.compile.

import torch
from transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B", dtype=torch.float16, device_map="auto")
input = tokenizer("The French Bread Law states", return_tensors="pt").to(model.device)

output = model.generate(**input, do_sample=False, max_new_tokens=20, cache_implementation="static")
tokenizer.batch_decode(output, skip_special_tokens=True)[0]

Evite chamar torch.compile(model) fora de generate() para evitar que o modelo seja recompilado a cada etapa.

Backends de atenção

Backends alternativos de atenção reduzem o tráfego de memória. Por exemplo, o FlashAttention aplica tiles às computações de atenção e evita tensores intermediários grandes para reduzir a pegada de memória.

Defina attn_implementation em from_pretrained() para carregar um backend de atenção otimizado.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B", attn_implementation="flash_attention_2")

Kernels

Kernels fundem operações para aumentar a taxa de transferência e reduzir o uso de memória. A biblioteca Kernels carrega kernels de computação otimizados do Hub de forma flexível e com segurança de versão.

O exemplo abaixo carrega um kernel otimizado do FlashAttention-2 sem instalar o pacote.

import torch
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B", attn_implementation="kernels-community/flash-attn2"
)

Quantização

Quantização reduz o tamanho de cada parâmetro, o que diminui a pegada de memória e aumenta a velocidade, pois é possível executar mais operações.

Passe uma configuração de quantização para o argumento quantization_config em from_pretrained(). Cada backend de quantização possui uma configuração diferente com argumentos distintos. O exemplo abaixo quantiza um modelo para 4 bits e configura o dtype de computação com o backend bitsandbytes.

import torch
from transformers import AutoModelForCausalLM, BitsAndBytesConfig

bnb_config = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_compute_dtype=torch.bfloat16)

model = AutoModelForCausalLM.from_pretrained(
    "allenai/Olmo-3-7B-Think", quantization_config=bnb_config
)

Cache

Caching acelera a geração reutilizando chaves e valores anteriores, em vez de recalculá-los para cada token. Para compensar e reduzir o custo de memória de armazenar chaves e valores anteriores, o Transformers suporta o offloading do cache para a CPU. Apenas a camada atual permanece na GPU.

Use o argumento cache_implementation em generate() para definir uma estratégia de cache.

import torch
from transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B", attn_implementation="kernels-community/flash-attn2"
)
inputs = tokenizer("The Le Décret Pain states that a baguette must,", return_tensors="pt")
outputs = model.generate(**inputs, do_sample=False, max_new_tokens=50, cache_implementation="offloaded")

Paralelismo

Paralelismo distribui um modelo entre dispositivos para que modelos grandes demais para um único dispositivo sejam executados com rapidez. Essa abordagem utiliza mais memória devido ao overhead de sharding e à comunicação necessária para sincronizar os resultados.

Paralelismo de tensor divide uma camada do modelo entre dispositivos. Defina o número de dispositivos com DistributedConfig(tp_size=N) e passe-o para from_pretrained() para ativá-lo.

from transformers import AutoModelForCausalLM, DistributedConfig

distributed_config = DistributedConfig(tp_size=4)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Meta-Llama-3-8B-Instruct",
    distributed_config=distributed_config,
)
print(model._tp_plan)

Loteamento contínuo

Continuous batching maximiza a taxa de transferência mantendo a GPU ocupada com agendamento dinâmico e pré-preenchimento em blocos. Aplicações de Serving o utilizam para processar múltiplas solicitações recebidas simultaneamente.

Use generate_batch() para habilitar o loteamento contínuo.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from transformers.generation import ContinuousBatchingConfig, GenerationConfig

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="sdpa",
    device_map="auto",
    torch_dtype=torch.bfloat16,
)
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")

prompts = [
    "The Le Décret Pain states that a baguette must",
    "Explain gravity in one sentence.",
    "Name the capital of France.",
]
inputs = [tokenizer.encode(p) for p in prompts]

generation_config = GenerationConfig(
    max_new_tokens=32,
    eos_token_id=tokenizer.eos_token_id,
    pad_token_id=tokenizer.pad_token_id,
    do_sample=False,
)
continuous_batching_config = ContinuousBatchingConfig(max_batch_tokens=512)

outputs = model.generate_batch(
    inputs=inputs,
    generation_config=generation_config,
    continuous_batching_config=continuous_batching_config,
)

for request_id, output in outputs.items():
    text = tokenizer.decode(output.generated_tokens, skip_special_tokens=True)
    print(f"[{request_id}] {text}")

Update on GitHub