Usando Transformers: abrir la caja negra de pipeline()

0. Abrir la caja negra

Todo lo que sigue es, literalmente, desarmar la función pipeline("sentiment-analysis") del Capítulo 1 en sus tres pasos — preprocesar, correr el modelo, postprocesar — y mostrar cada uno por separado. La razón para hacer este ejercicio no es académica: el día que necesites algo que pipeline() no ofrece de fábrica (batching custom, un head propio, streaming token a token), vas a estar trabajando exactamente en esta capa.

1. Detrás del pipeline: tensores, cabezas y proyección matemática

Los modelos de transformers no leen texto — procesan tensores multidimensionales. El primer trabajo es siempre de un tokenizer, que convierte texto crudo en una secuencia de identificadores enteros (input_ids) y una máscara binaria (attention_mask), usando AutoTokenizer:

from transformers import AutoTokenizer

checkpoint = "distilbert-base-uncased-finetuned-sst-2-english"
tokenizer = AutoTokenizer.from_pretrained(checkpoint)

raw_inputs = ["Llevo toda mi vida esperando un curso así.", "Odio esto tanto."]
inputs = tokenizer(raw_inputs, padding=True, truncation=True, return_tensors="pt")

El resultado es un diccionario de tensores PyTorch. Los input_ids tienen forma $[B,N]$ (donde $B$ es el tamaño del batch y $N$ es la longitud de la secuencia). Al pasarlo al modelo:

from transformers import AutoModelForSequenceClassification

model = AutoModelForSequenceClassification.from_pretrained(checkpoint)
outputs = model(**inputs)
print(outputs.logits.shape)  # torch.Size([2, 2])

La cirugía tensorial: del cuerpo al head

El flujo matemático exacto dentro de la GPU se descompone en tres operaciones matriciales sucesivas:

1. Embedding Lookup: Cada token $i\in [0,V-1]$ (donde $V$ es el tamaño del vocabulario) indexa una fila de la matriz de embedding ${\mathbf{W}}_{\text{embed}}\in {\mathbb{R}}^{V\times d_{\text{model}}}$. El tensor resultante tiene dimensión $[B,N,d_{\text{model}}]$ (por ejemplo, $[2,16,4096]$).
2. El Cuerpo Transformer: Los vectores pasan por $L$ capas idénticas de atención multicabeza (MHA/GQA) y redes feed-forward (MLP) con conexiones residuales y normalización (RMSNorm o LayerNorm). El tensor que emerge del cuerpo conserva la misma forma geométrica: $\mathbf{H}\in {\mathbb{R}}^{B\times N\times d_{\text{model}}}$. Estos son los hidden states (estados ocultos) finales: representaciones contextualizadas donde cada vector de 4.096 dimensiones ha absorbido el significado de toda la secuencia.
3. La Proyección del Head: Los hidden states por sí mismos son números continuos abstractos. El head es una transformación lineal que proyecta $d_{\text{model}}$ al espacio concreto que requiere la tarea:
   • En *ForSequenceClassification, se extrae el vector de un token representativo (como [CLS] o pooling global: ${\mathbf{h}}_{\text{pool}}\in {\mathbb{R}}^{B\times d_{\text{model}}}$) y se multiplica por la matriz del head ${\mathbf{W}}_{\text{head}}\in {\mathbb{R}}^{d_{\text{model}}\times C}$, donde $C$ es el número de clases (por ejemplo 2: positivo/negativo). El resultado son los logits $\mathbf{z}\in {\mathbb{R}}^{B\times C}$.
   • En *ForCausalLM (el head de todo LLM generativo), cada posición temporal $t\in [1,N]$ debe predecir el token siguiente. Por lo tanto, se multiplican los hidden states completos por la matriz del vocabulario ${\mathbf{W}}_{\text{lm\_head}}\in {\mathbb{R}}^{d_{\text{model}}\times V}$: $\mathbf{Z}=\mathbf{H}{\mathbf{W}}_{\text{lm\_head}}\in {\mathbb{R}}^{B\times N\times V}$.

El punto que vale la pena remarcar: la librería no tiene un solo "modelo", tiene una familia de heads (*ForCausalLM, *ForSequenceClassification, *ForQuestionAnswering, *ForTokenClassification...) que se enchufan sobre el mismo cuerpo transformer. El cuerpo no cambia entre tareas — lo que cambia es qué head le ponés encima.

2. Modelos: from_pretrained / save_pretrained

Cargar un modelo pre-entrenado y guardar uno propio usan el mismo par de métodos en cualquier clase de la librería — modelos, tokenizers, todo:

from transformers import AutoModel

model = AutoModel.from_pretrained("bert-base-cased")
model.save_pretrained("mi_carpeta")
# genera: config.json + model.safetensors

config.json guarda la arquitectura (cuántas capas $L$, tamaño oculto $d_{\text{model}}$, cabezas de atención $n_{\text{heads}}$, tamaño del vocabulario $V$); el archivo de pesos guarda los tensores numéricos entrenados. Son dos entidades separadas a propósito: la configuración define el grafo de cómputo vacío, mientras que los pesos parametrizan las operaciones matriciales.

La física de los pesos: cálculo exacto de VRAM

¿Cuánta memoria VRAM ocupa un modelo en GPU? La fórmula física base es estrictamente lineal:

${\text{VRAM}}_{\text{pesos}}=N_{\text{parámetros}}\times \text{Bytes por parámetro}$

Por qué safetensors y mmap cambiaron la carga de modelos

El formato histórico (pytorch_model.bin) utiliza pickle de Python. Cuando hacés unpickle, Python reconstruye objetos ejecutando la función mágica __reduce__; un archivo .bin descargado de internet puede ejecutar comandos de terminal en tu máquina en el instante en que lo cargás. Además, obliga a cargar todos los bytes en la memoria RAM del sistema primero, parsear objetos Python y luego transferirlos a la GPU mediante PCIe.

safetensors resolvió ambos problemas:

• Cero ejecución de código: Es únicamente un encabezado JSON con metadatos (formas de tensores, tipos de datos y offsets de bytes) seguido de un buffer binario plano con los números crudos contiguos.
• Memory Mapping (mmap) y DMA directo: En vez de copiar gigabytes de disco a RAM y de RAM a VRAM, el sistema operativo mapea las páginas del archivo directamente en el espacio de direcciones virtuales del proceso. Las transferencias DMA (Direct Memory Access) mueven los pesos del disco NVMe a la VRAM a velocidades de bus completas (5–14 GB/s).
• Sharding transparente: Checkpoints grandes se dividen en archivos de ~5 GB acompañados de un model.safetensors.index.json. Este índice mapea cada matriz (ej. layers.15.self_attn.q_proj.weight) a su archivo específico, permitiendo cargar y descargar capas individualmente sin agotar la memoria.

Cómo se carga un LLM real hoy

Cargar un modelo decoder-only moderno en 2026 requiere especificar precisión y mapeo de dispositivos:

import torch
from transformers import AutoTokenizer, AutoModelForCausalLM

model_id = "HuggingFaceTB/SmolLM2-360M-Instruct"   # chico a propósito: corre en CPU · con GPU potente: "google/gemma-4-E2B-it", mismo código
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16,   # 2 bytes por parámetro en vez de 4
    device_map="auto",            # GPU si hay, CPU si no; reparte entre varias si hace falta
)

inputs = tokenizer("La capital de Francia es", return_tensors="pt").to(model.device)
out = model.generate(**inputs, max_new_tokens=20, do_sample=False)
print(tokenizer.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))

Tres cosas fundamentales para advertir: torch_dtype=torch.bfloat16 divide la memoria a la mitad respecto a FP32 sin inestabilidad numérica. device_map="auto" utiliza la librería accelerate para calcular la memoria libre en cada GPU visible y distribuir las capas sequentialmente. Y generate() devuelve el tensor concatenado [prompt_tokens + generated_tokens] en la dimensión de la secuencia: por eso el slice out[0][inputs["input_ids"].shape[1]:] es indispensable para extraer únicamente los tokens nuevos generados.

3. Tokenizers: de texto a números

Hay tres formas básicas de cortar texto en piezas, y cada una tiene un problema que la siguiente intenta resolver:

La mecánica de Byte-level BPE (Byte-Pair Encoding)

Los LLMs modernos (Llama, GPT-4, Gemma, Qwen) no usan tokenización por palabras ni por caracteres puros: utilizan Byte-level BPE. Su funcionamiento mecánico consta de dos reglas esenciales:

• Alfabeto base de 256 bytes (0x00 a 0xFF): En vez de inicializar el vocabulario con letras de algún idioma, el vocabulario base son exactamente los 256 valores posibles de un byte. Como cualquier texto del planeta (incluyendo kanjis japoneses, emojis compuestos como 👨‍👩‍👧‍👦 o código en binario) se codifica en UTF-8 como una secuencia de bytes, es matemáticamente imposible que un tokenizer de Byte-level BPE arroje un error de token desconocido ([UNK]). Siempre puede descomponer un símbolo no visto en sus bytes individuales constituyentes.
• Fusión iterativa de pares (Merges): Durante el entrenamiento del tokenizer, se cuenta la frecuencia de todos los pares de tokens adyacentes en el corpus de terabytes. El par más frecuente (por ejemplo, los bytes de 'e' y 's') se fusiona en un nuevo token 'es'. El proceso se itera $V-256$ veces hasta alcanzar el tamaño de vocabulario meta (ej. $V=128.256$).
• Preservación estricta de espacios: Los espacios en blanco no se eliminan con strip(); se codifican explícitamente (a menudo reemplazados por un carácter visible como Ġ o ). Así, " banco" (con espacio precedente) y "banco" (al inicio de frase) son tokens distintos con identificadores numéricos y roles semánticos diferentes.

tokens = tokenizer.tokenize("Using a Transformer network is simple")
# ['Using', 'Ġa', 'ĠTransform', 'er', 'Ġnetwork', 'Ġis', 'Ġsimple']

ids = tokenizer.convert_tokens_to_ids(tokens)
# [7993, 257, 11303, 260, 2443, 318, 2829]

Y decodificar es el camino inverso — de IDs a bytes, recomponiendo las secuencias UTF-8 en texto legible.

En código, la conversación es una lista de diccionarios con role y content, y el tokenizer se encarga de envolverla. Con tokenize=False podés inspeccionar el texto exacto generado:

messages = [
    {"role": "system", "content": "Sos un asistente conciso."},
    {"role": "user", "content": "¿Qué es un tokenizer?"},
]
texto = tokenizer.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
print(texto)

El string resultante estructura la interacción para los núcleos de atención:

<|im_start|>system
Sos un asistente conciso.<|im_end|>
<|im_start|>user
¿Qué es un tokenizer?<|im_end|>
<|im_start|>assistant

Notá la última línea: add_generation_prompt=True agrega el encabezado del turno del asistente abierto, condicionando a que el siguiente token predicho por el modelo sea el primer token de su respuesta. Para pasarlo a la GPU, tokenizás con add_special_tokens=False (para evitar que el tokenizer inserte un segundo BOS redundante delante del template):

inputs = tokenizer(texto, return_tensors="pt", add_special_tokens=False).to(model.device)
out = model.generate(**inputs, max_new_tokens=100)

4. Batching, padding y attention masks

Un modelo siempre espera un lote (batch), incluso si es de un solo elemento — por eso tokenizer(...) agrega una dimensión extra que fácilmente se te puede pasar por alto la primera vez. El problema real aparece cuando el lote tiene más de una frase: las frases casi nunca miden lo mismo, y un tensor tiene que ser rectangular.

La solución es padding: rellenar las frases más cortas con un token especial (pad_token_id) hasta igualar la longitud máxima $N_{\text{max}}$ del lote. Pero esto introduce un problema matemático grave: la atención (Capítulo 1, §3) compara todos los tokens entre sí; si no intervenimos, los tokens reales atenderían a los tokens de relleno y promediarían sus vectores Value, distorsionando por completo la semántica.

La máscara aditiva de atención en la ecuación de Softmax

La solución matemática es la Attention Mask: un tensor binario ${\mathbf{M}}_{\text{bin}}\in \{0,1{\}}^{B\times N}$. Dentro del kernel de atención de la GPU, esta máscara se transforma en una matriz aditiva $\mathbf{M}$ que se suma directamente a la matriz de productos punto antes de calcular el Softmax:

$\text{Attention}(\mathbf{Q},\mathbf{K},\mathbf{V})=\text{Softmax}(\frac{\mathbf{Q}{\mathbf{K}}^{\top }}{\sqrt{d_k}}+\mathbf{M})\mathbf{V}$

Los elementos de la matriz $\mathbf{M}$ toman valores discretos:

Al calcular el Softmax sobre cada fila: $exp(-\infty )=0$. El peso de atención asignado a cualquier posición de relleno queda forzado exactamente a cero absoluto. El vector Value del padding se multiplica por 0 y se anula completamente de la sumatoria.

batched_ids = [
    [200, 200, 200],
    [200, 200, tokenizer.pad_token_id],
]
attention_mask = [
    [1, 1, 1],
    [1, 1, 0],  # la GPU sumará -inf a la columna 2 del segundo ejemplo
]
outputs = model(torch.tensor(batched_ids), attention_mask=torch.tensor(attention_mask))

tokenizer.padding_side = "left"
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

5. Servir en serio: TGI, vLLM, llama.cpp

Esta sección es enteramente nueva desde 2022 — el original ni la tenía. Todo lo anterior asume que corrés el modelo vos mismo, en tu proceso de Python. En producción, casi nadie hace eso: se usa un servidor de inferencia dedicado, optimizado para atender muchas requests a la vez.

PagedAttention: la virtualización de la VRAM

La idea detrás de PagedAttention (vLLM) conecta directo con la ecuación del KV cache del Capítulo 1. En los servidores tradicionales, para atender una petición se debía reservar por adelantado un bloque contiguo de VRAM para la longitud máxima posible ($L_{\text{max}}=4096$ o $8192$ tokens). Esto provocaba dos pérdidas masivas de memoria:

• Fragmentación interna: La mayoría de las respuestas reales tienen menos de 300 tokens. El 90% restante del bloque contiguo reservado quedaba vacío pero bloqueado, impidiendo que otras requests entraran.
• Fragmentación externa: Al liberarse peticiones de distintos tamaños, la memoria quedaba salpicada de huecos discontinuos donde ninguna petición nueva de tamaño grande encajaba. Se desperdiciaba entre el 60% y el 80% de la VRAM útil.

vLLM importó la solución que los sistemas operativos usan desde hace 50 años para la memoria RAM: Paginación.

1. El KV cache no se almacena en tensores contiguos. Se divide en bloques físicos de tamaño fijo (típicamente 16 o 32 tokens).
2. Cada secuencia lógica de tokens tiene una Block Table (tabla de páginas) que mapea bloques lógicos contiguos a bloques físicos dispersos en cualquier lugar de la VRAM.
3. A medida que un token nuevo se genera en el paso de decode, si el bloque actual se llena, el motor le asigna un nuevo bloque físico libre desde un pool central.
4. Copy-on-Write (CoW): Si generás 4 respuestas paralelas al mismo prompt (o en agentes con branching), todas las peticiones comparten los mismos bloques físicos del prompt en memoria. Solo cuando una respuesta escribe un token divergente, se clona ese bloque específico.

Resultado: la fragmentación externa pasa a ser exactamente cero, y la fragmentación interna queda acotada como máximo a los tokens vacíos del último bloque individual ( tokens). El throughput del servidor se multiplica de 4× a 24× con la misma GPU.

Continuous Batching y Chunked Prefill

Además de PagedAttention, servir a escala requiere resolver la asincronía temporal de los usuarios:

• Continuous Batching (Orca / vLLM): En el batching estático de PyTorch clásico, si procesás 4 peticiones juntas, el batch entero debe iterar hasta que la petición más larga termine de generar sus 500 tokens. Si las otras 3 terminaron en el token 20, la GPU pasa 480 ciclos ejecutando GEMVs sobre tokens de padding vacíos para el 75% del batch. En Continuous Batching, las decisiones de scheduling se toman a nivel de iteración individual: en cada paso de decode, si una secuencia emite el token <|end_of_text|>, se desaloja instantáneamente de la GPU, se liberan sus bloques de KV cache y una nueva petición en cola entra a ocupar su lugar en el siguiente ciclo de reloj.
• Chunked Prefill: Como vimos en el Capítulo 1, el *prefill* es compute-bound (GEMM masivo) y el *decode* es memory-bound (GEMV sensible a la latencia por token). Si un usuario envía un prompt largo de 8.000 tokens mientras el servidor está haciendo decode para otros 30 usuarios, un prefill monolítico congelaría el servidor durante 200 ms, provocando tartamudeo (jitter) perceptible en el streaming de todos los clientes. Chunked Prefill divide los prompts largos en fragmentos de 512 tokens y los intercala en cada batch de decode, manteniendo constante la fluidez de tokens por segundo.

# Levantar un servidor vLLM compatible con la API de OpenAI
python -m vllm.entrypoints.openai.api_server \
    --model google/gemma-4-E2B-it \
    --host 0.0.0.0 --port 8000

¿Te suena familiar ese comando? Es la misma familia de flags que ves en serve_lacan_vllm.sh — con --quantization, --kv-cache-dtype y --speculative-config encima, que son las variantes de producción de exactamente este mismo comando base.

Por qué "API compatible con OpenAI" es más que un detalle de marketing: el formato de request (/v1/chat/completions con una lista de messages) se volvió el estándar de facto, y todo el ecosistema de clientes, frameworks de agentes y herramientas de observabilidad habla ese formato. Tu aplicación cambia de un modelo alojado a uno servido por vos con vLLM en tu propia GPU tocando una línea — la URL base — y ni una del resto:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="sin-uso")
resp = client.chat.completions.create(
    model="google/gemma-4-E2B-it",
    messages=[{"role": "user", "content": "¿Qué es un tokenizer?"}],
)
print(resp.choices[0].message.content)

Y el servidor aplica el chat template de §3 por vos — otra razón para no armar prompts a mano: si lo hacés, el template se aplica dos veces.

6. Errores comunes

Casi todos estos comparten un rasgo: el código corre sin excepción y el resultado está mal.

7. Resumen

1. pipeline() es tokenizer + modelo + postprocesado — ahora sabés manejar cada pieza por separado.
2. Un LLM se carga con AutoModelForCausalLM, en bf16 y con device_map="auto"; generate() devuelve prompt + respuesta, y los inputs tienen que vivir en el mismo device que el modelo.
3. Un modelo es cuerpo (produce hidden states) + head (los proyecta a algo útil para la tarea) — el mismo cuerpo sirve para clasificar o para generar, según qué head le pongas.
4. La tokenización por subpalabras (BPE/WordPiece) es el estándar; los chat templates son la capa 2026 que decide cómo se arma el prompt de un modelo de chat.
5. Padding + attention mask son inseparables: sin la mask correcta, el padding contamina el resultado en silencio.
6. En producción no corrés el modelo a mano — lo servís con vLLM, TGI, SGLang o llama.cpp, cada uno optimizado para un escenario distinto, y todos detrás de la misma API compatible con OpenAI.

8. Ponete a prueba

Respondé antes de abrir cada respuesta. Si fallás una, volvé a la sección indicada.

9. Para practicar

import torch
from transformers import pipeline, AutoTokenizer, AutoModelForSequenceClassification

ckpt = "distilbert-base-uncased-finetuned-sst-2-english"
frase = "I've been waiting for a course like this my whole life."

print(pipeline("sentiment-analysis", model=ckpt)(frase))

tok = AutoTokenizer.from_pretrained(ckpt)
model = AutoModelForSequenceClassification.from_pretrained(ckpt)
inputs = tok(frase, return_tensors="pt")
with torch.no_grad():
    logits = model(**inputs).logits
probs = torch.softmax(logits, dim=-1)
print(logits, probs, model.config.id2label)

corta, larga = "Great.", "This was honestly one of the most boring afternoons I have ever spent."
sola = model(**tok(corta, return_tensors="pt")).logits[0]

batch = tok([corta, larga], padding=True, return_tensors="pt")
con_mask = model(**batch).logits[0]
sin_mask = model(input_ids=batch["input_ids"], attention_mask=torch.ones_like(batch["attention_mask"])).logits[0]

print(sola, con_mask, sin_mask, sep="\n")

from transformers import AutoTokenizer, AutoModelForCausalLM

model_id = "HuggingFaceTB/SmolLM2-360M-Instruct"
tok = AutoTokenizer.from_pretrained(model_id)
messages = [{"role": "user", "content": "Explicá en una frase qué es un tokenizer."}]

for flag in (False, True):
    print(repr(tok.apply_chat_template(messages, add_generation_prompt=flag, tokenize=False)))

model = AutoModelForCausalLM.from_pretrained(model_id)
inputs = tok.apply_chat_template(messages, add_generation_prompt=True, return_tensors="pt")
out = model.generate(inputs, max_new_tokens=60, do_sample=False)
print(tok.decode(out[0][inputs.shape[1]:], skip_special_tokens=True))

10. Fuentes y para seguir

• Hugging Face LLM Course — Chapter 2: Using 🤗 Transformers — el capítulo original, con el desarme de pipeline() paso a paso.
• Transformers docs — Chat templates — la referencia de apply_chat_template(), cómo escribir un template propio y cómo agregar herramientas a la conversación.
• Transformers docs — Generation with LLMs — el tutorial oficial de generate(): padding a la izquierda, pad_token, y los errores típicos de §6, con código.
• safetensors — documentación — el formato y por qué reemplazó a pickle; leé la sección de seguridad.
• Efficient Memory Management for Large Language Model Serving with PagedAttention (Kwon et al., 2023) — el paper de vLLM; de acá sale el "hasta 24×" de §5.
• vLLM — documentación — el servidor compatible con OpenAI que ya usás; el índice de flags de vllm serve es la referencia para tu script.