Hugging Face transformers
La biblioteca transformers carga y ejecuta modelos de código abierto del Hugging Face Hub. Usa pipeline para inferencia rápida o AutoModel para bucles de generación personalizados.
Receta
Tarjeta de referencia rápida - lista para copiar y pegar.
from transformers import pipeline
generator = pipeline("text-generation", model="meta-llama/Llama-3.2-1B-Instruct")
output = generator("Explica los decoradores de Python:", max_new_tokens=100)
print(output[0]["generated_text"])Cuándo usar esto:
- Ejecutar LLMs de código abierto localmente o en tu infraestructura.
- Ajustar modelos con la API Trainer.
- Acceder a miles de modelos preentrenados del Hub.
- Construir generación personalizada con control sobre los parámetros de muestreo.
Ejemplo de trabajo
"""hugging_face_transformers.py - pipeline y generación manual."""
from __future__ import annotations
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, pipeline
model_id = "meta-llama/Llama-3.2-1B-Instruct"
# Inferencia rápida con pipeline
gen = pipeline("text-generation", model=model_id, torch_dtype=torch.float16, device_map="auto")
result = gen("¿Qué es pytest?", max_new_tokens=80, do_sample=True, temperature=0.7)
print("pipeline:", result[0]["generated_text"][-200:])
# Bucle de generación manual
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float16, device_map="auto")
messages = [{"role": "user", "content": "Escribe un hola mundo de Python en una línea."}]
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)Lo que esto demuestra:
pipelinepara generación de texto sin configuración.AutoTokenizeryAutoModelForCausalLMpara control manual.apply_chat_templatepara modelos ajustados a instrucciones.device_map="auto"para asignación automática de GPU.
Inmersión Profunda
Cómo funciona
- Hub aloja pesos de modelos, configuraciones y tokenizadores.
- Clases Auto resuelven la arquitectura desde
config.json. - Tokenizer convierte texto a IDs de tokens y viceversa.
- generate() ejecuta decodificación autorregresiva con muestreo o búsqueda greedy.
- Trainer ajusta modelos en conjuntos de datos personalizados.
APIs Clave
| API | Usar cuándo | Complejidad |
|---|---|---|
pipeline() | Prototipado rápido | Bajo |
model.generate() | Parámetros de generación personalizados | Medio |
Trainer | Ajuste fino | Medio |
trl (SFT, DPO) | Alineación estilo RLHF | Alto |
Notas de Python
# Cuantización de 4 bits para memoria 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")Errores comunes
- No usar plantilla de chat - los modelos de instrucciones producen resultados deficientes sin el formato adecuado. Solución:
tokenizer.apply_chat_template. - OOM en modelos grandes - los modelos de 70B necesitan multi-GPU o cuantización. Solución: carga de 4 bits,
device_map="auto", o modelos más pequeños. - Acceso a modelos protegidos - Llama y algunos modelos requieren inicio de sesión en el Hub y aceptación de licencia. Solución:
huggingface-cli loginy aceptar la licencia en la página del modelo. - No establecer pad_token - la generación falla sin token de relleno. Solución:
tokenizer.pad_token = tokenizer.eos_token. - Descarga en cada ejecución - las redescargas desperdician tiempo. Solución: establecer el directorio de caché
HF_HOME; usarlocal_files_only=Trueen producción. - float32 en GPU - duplica la memoria frente a float16. Solución:
torch_dtype=torch.float16obfloat16.
Alternativas
| Alternativa | Usar cuándo | No usar cuándo |
|---|---|---|
pipeline | Inferencia rápida | Lógica de decodificación personalizada |
| vLLM | Servicio de alto rendimiento | Experimentos locales sencillos |
| Ollama | Gestión local sencilla de modelos | Ajuste fino |
| Proveedores de API | Sin infraestructura de GPU | La privacidad de los datos requiere local |
Preguntas frecuentes
¿Cómo me autentico con el Hub?
pip install huggingface_hub
huggingface-cli login- Requerido para modelos protegidos.
¿Qué es device_map auto?
- Distribuye automáticamente las capas del modelo entre las GPUs disponibles.
- Esencial para modelos más grandes que la memoria de una sola GPU.
¿Cómo ajusto un 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()¿Qué modelos se ejecutan en un portátil?
- Modelos de 1B-3B parámetros con cuantización de 4 bits.
- Llama 3.2 1B, Phi-3 mini, SmolLM.
¿Cómo controlo la longitud de la generación?
max_new_tokenslimita los nuevos tokens (preferido sobremax_length).min_new_tokensasegura una longitud mínima de respuesta.
¿Qué es la temperatura en generate()?
- Igual que la temperatura de la API: más alta = más aleatorio.
do_sample=Falsepara decodificación greedy (determinista).
¿Cómo hago inferencia por lotes?
- Rellena las entradas a la misma longitud; pasa el tensor del lote a
generate. - vLLM maneja el procesamiento por lotes de manera eficiente para el servicio.
¿Puedo usar transformers con PyTorch 2.6+?
- Sí, transformers soporta versiones recientes de PyTorch.
torch.compilepuede acelerar la generación en modelos compatibles.
¿Qué es PEFT/LoRA?
- Low-Rank Adaptation: ajusta pequeños pesos adaptadores en lugar del modelo completo.
- Reduce drásticamente la memoria para el ajuste fino.
¿Cómo almaceno modelos en caché localmente?
export HF_HOME=/data/hf_cache- Los modelos se descargan una vez y se reutilizan de la caché.
¿Cómo ejecuto embeddings?
from transformers import AutoModel
embedder = pipeline("feature-extraction", model="sentence-transformers/all-MiniLM-L6-v2")- O usa la biblioteca
sentence-transformersdirectamente.
¿Qué es la tarjeta de modelo del Hub?
- Documenta las capacidades, limitaciones y uso previsto del modelo.
- Lee antes de desplegar cualquier modelo abierto.
Relacionado
- Modelos Locales y Abiertos - Ollama y vLLM
- Embeddings y Similitud - modelos de embeddings
- Aprendizaje por Transferencia y Ajuste Fino - patrones de ajuste fino
- Streaming y Llamadas LLM Asíncronas - generación en streaming
- Tokens, Costo y Límites de Tasa - costo local vs API
Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 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+, y uv 0.6+.