Low-Rank Adaptation: ajuste fino de pequenos pesos adaptadores em vez do modelo completo. Reduz drasticamente a memória para ajuste fino.

Hugging Face transformers

Q: Como controlo o comprimento da geração?

max_new_tokens limita os novos tokens (preferível a max_length). min_new_tokens garante o comprimento mínimo da resposta.

Q: O que é temperatura em generate()?

Igual à temperatura da API: maior = mais aleatório. do_sample=False para decodificação gulosa (determinística).

Q: Posso usar transformers com PyTorch 2.6+?

Sim - transformers suporta versões recentes do PyTorch. torch.compile pode acelerar a geração em modelos suportados.

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:

pipeline para geração de texto sem configuração.
AutoTokenizer e AutoModelForCausalLM para controle manual.
apply_chat_template para 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 login e 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; use local_files_only=True em produção.
float32 na GPU - dobra a memória em comparação com float16. Correção: torch_dtype=torch.float16 ou bfloat16.

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()

Veja Aprendizado de Transferência.

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_tokens limita os novos tokens (preferível a max_length).
min_new_tokens garante o comprimento mínimo da resposta.

O que é temperatura em generate()?

Igual à temperatura da API: maior = mais aleatório.
do_sample=False para 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.compile pode 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-transformers diretamente.

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+.

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:

pipeline para geração de texto sem configuração.
AutoTokenizer e AutoModelForCausalLM para controle manual.
apply_chat_template para 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 login e 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; use local_files_only=True em produção.
float32 na GPU - dobra a memória em comparação com float16. Correção: torch_dtype=torch.float16 ou bfloat16.

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()

Veja Aprendizado de Transferência.

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_tokens limita os novos tokens (preferível a max_length).
min_new_tokens garante o comprimento mínimo da resposta.

O que é temperatura em generate()?

Igual à temperatura da API: maior = mais aleatório.
do_sample=False para 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.compile pode 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-transformers diretamente.

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+.

Hugging Face transformers

Buscar na documentação

Hugging Face transformers