Hugging Face transformers
A biblioteca transformers carrega e executa modelos de código aberto do Hugging Face Hub. Use pipeline para inferência rápida ou AutoModel para loops de geração personalizados.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
from transformers import pipeline
generator = pipeline("text-generation", model="meta-llama/Llama-3.2-1B-Instruct")
output = generator("Explique os decoradores Python:", max_new_tokens=100)
print(output[0]["generated_text"])Quando usar isso:
- Executando LLMs de código aberto localmente ou em sua infraestrutura.
- Ajustando modelos com a API Trainer.
- Acessando milhares de modelos pré-treinados do Hub.
- Construindo geração personalizada com controle sobre parâmetros de amostragem.
Exemplo de Trabalho
"""hugging_face_transformers.py - pipeline e geração manual."""
from __future__ import annotations
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, pipeline
model_id = "meta-llama/Llama-3.2-1B-Instruct"
# Inferência rápida com pipeline
gen = pipeline("text-generation", model=model_id, torch_dtype=torch.float16, device_map="auto")
result = gen("O que é pytest?", max_new_tokens=80, do_sample=True, temperature=0.7)
print("pipeline:", result[0]["generated_text"][-200:])
# Loop de geração manual
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float16, device_map="auto")
messages = [{"role": "user", "content": "Escreva um hello world em Python de uma linha."}]
text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(text, return_tensors="pt").to(model.device)
with torch.inference_mode():
outputs = model.generate(**inputs, max_new_tokens=60, temperature=0.7, do_sample=True)
response = tokenizer.decode(outputs[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
print("manual:", response)O que isso demonstra:
pipelinepara geração de texto sem configuração.AutoTokenizereAutoModelForCausalLMpara controle manual.apply_chat_templatepara modelos ajustados por instruções.device_map="auto"para posicionamento automático da GPU.
Mergulho Profundo
Como Funciona
- Hub hospeda pesos de modelos, configurações e tokenizadores.
- Classes Auto resolvem a arquitetura a partir de
config.json. - Tokenizer converte texto em IDs de token e vice-versa.
- generate() executa a decodificação autorregressiva com amostragem ou busca gulosa.
- Trainer ajusta modelos em conjuntos de dados personalizados.
APIs Principais
| API | Use Quando | Complexidade |
|---|---|---|
pipeline() | Prototipagem rápida | Baixa |
model.generate() | Parâmetros de geração personalizados | Média |
Trainer | Ajuste fino | Média |
trl (SFT, DPO) | Alinhamento estilo RLHF | Alta |
Notas Python
# Quantização de 4 bits para memória de GPU limitada
from transformers import BitsAndBytesConfig
bnb_config = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_compute_dtype=torch.float16)
model = AutoModelForCausalLM.from_pretrained(model_id, quantization_config=bnb_config, device_map="auto")Armadilhas
- Não usar template de chat - modelos de instrução produzem saída ruim sem formatação adequada. Correção:
tokenizer.apply_chat_template. - OOM em modelos grandes - modelos de 70B precisam de multi-GPU ou quantização. Correção: carregamento de 4 bits,
device_map="auto"ou modelos menores. - Acesso a modelos com portão - Llama e alguns modelos exigem login no Hub e aceitação da licença. Correção:
huggingface-cli logine aceite a licença na página do modelo. - Não definir pad_token - a geração falha sem o token de preenchimento. Correção:
tokenizer.pad_token = tokenizer.eos_token. - Baixando a cada execução - redownloads desperdiçam tempo. Correção: defina o diretório de cache
HF_HOME; uselocal_files_only=Trueem produção. - float32 na GPU - dobra a memória em comparação com float16. Correção:
torch_dtype=torch.float16oubfloat16.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
pipeline | Inferência rápida | Lógica de decodificação personalizada |
| vLLM | Servidor de alta taxa de transferência | Experimentos locais simples |
| Ollama | Gerenciamento fácil de modelos locais | Ajuste fino |
| Provedores de API | Sem infraestrutura de GPU | Privacidade de dados exige local |
FAQs
Como me autentico no Hub?
pip install huggingface_hub
huggingface-cli login- Necessário para modelos com portão.
O que é device_map auto?
- Distribui automaticamente as camadas do modelo entre as GPUs disponíveis.
- Essencial para modelos maiores que a memória de uma única GPU.
Como faço o ajuste fino de um modelo?
from transformers import TrainingArguments, Trainer
args = TrainingArguments(output_dir="./out", num_train_epochs=3, per_device_train_batch_size=4)
trainer = Trainer(model=model, args=args, train_dataset=dataset)
trainer.train()Quais modelos rodam em um laptop?
- Modelos de 1B-3B parâmetros com quantização de 4 bits.
- Llama 3.2 1B, Phi-3 mini, SmolLM.
Como controlo o comprimento da geração?
max_new_tokenslimita os novos tokens (preferível amax_length).min_new_tokensgarante o comprimento mínimo da resposta.
O que é temperatura em generate()?
- Igual à temperatura da API: maior = mais aleatório.
do_sample=Falsepara decodificação gulosa (determinística).
Como faço inferência em lote?
- Preencha as entradas para o mesmo comprimento; passe o tensor em lote para
generate. - vLLM lida com o loteamento de forma eficiente para servir.
Posso usar transformers com PyTorch 2.6+?
- Sim - transformers suporta versões recentes do PyTorch.
torch.compilepode acelerar a geração em modelos suportados.
O que é PEFT/LoRA?
- Low-Rank Adaptation: ajuste fino de pequenos pesos adaptadores em vez do modelo completo.
- Reduz drasticamente a memória para ajuste fino.
Como faço cache de modelos localmente?
export HF_HOME=/data/hf_cache- Modelos são baixados uma vez e reutilizados do cache.
Como faço para obter embeddings?
from transformers import AutoModel
embedder = pipeline("feature-extraction", model="sentence-transformers/all-MiniLM-L6-v2")- Ou use a biblioteca
sentence-transformersdiretamente.
O que é o cartão do modelo do Hub?
- Documenta as capacidades, limitações e uso pretendido do modelo.
- Leia antes de implantar qualquer modelo aberto.
Relacionados
- Modelos Locais e Abertos - Ollama e vLLM
- Embeddings e Similaridade - modelos de embedding
- Aprendizado de Transferência e Ajuste Fino - padrões de ajuste fino
- Streaming e Chamadas LLM Assíncronas - geração de streaming
- Tokens, Custo e Limites de Taxa - custo local vs API
Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.