Posts on lo0 — Blog Técnico

Anatomía de una petición LLM en producción, mayo 2026: tour por las seis etapas siguiendo una sola request

Fri, 22 May 2026 16:00:00 +0200

TL;DR

El blog ha desplegado a lo largo de varias series las piezas que sostienen un sistema LLM en producción: la etapa Data (versionado de datasets, ingestión y vector stores, RAG sobre Kafka), la etapa Tune (fine-tuning continuo), la etapa Eval (evals como capa después del tracing, guardrails y safety), la etapa Deploy (KV cache, PagedAttention, disaggregated serving, cluster GPU multi-tenant, vLLM en Kubernetes, operators de LLM en K8s), la etapa Observe (tracing con AgentSight, MCP observability, eBPF + drift), la etapa Retrain (cerrar el bucle feedback → dataset → adapter), y los componentes transversales (prompt versioning y data versioning). Lo que falta es unirlo: ver una única petición atravesando todas las piezas en orden, en una historia coherente. Eso hace este post. Cogemos una request específica de un chatbot de soporte multi-tenant, la rebobinamos hacia atrás hasta los datos que entrenaron el adapter que la sirve hoy, la seguimos hacia adelante por el serving, la vemos llegar al store de feedback cuando el usuario marca thumbs-down, y la dejamos como semilla del próximo ciclo trimestral de retrain. El recorrido sirve como mapa mental y como guía del integrador: el sistema no se sostiene si una sola de las siete piezas (seis etapas + dos transversales) está rota o ausente. La lección práctica del tour no es ninguna nueva — es que todo está conectado, que las medidas locales mienten cuando se aíslan, y que el coste real de no operar bien una etapa lo paga otra etapa más adelante.

Estás aquí: todas las etapas a la vez

A diferencia de los posts anteriores, donde el mini-mapa marcaba una sola caja activa, este recorre todo el pipeline. Es el único post del blog que activa las seis etapas y los dos componentes transversales simultáneamente, porque seguimos una request real que las cruza todas.

La analogía: análisis forense de una request

Cuando ocurre un accidente aéreo, el análisis forense no se limita a mirar los últimos segundos del vuelo. El equipo de investigación rebobina hasta el mantenimiento de los seis meses previos, los protocolos del fabricante, el currículo del piloto, el briefing meteorológico, las decisiones del controlador, la historia de incidentes en el mismo modelo. La conclusión rara vez es “el ala se rompió”; es “el ala se rompió porque un protocolo de inspección redactado de tal forma no detectaba microfisuras que el modelo de cálculo del 2014 no consideraba críticas y que sí lo eran a partir de cierto ciclo de fatiga”.

Cuando una petición LLM en producción falla o acierta, también hay una cadena causal larga detrás. La respuesta que el usuario ve es el último frame; lo que la determinó empieza meses antes y se ramifica por seis etapas operativas. Si sólo miras el último frame, atribuyes el resultado al modelo. Si miras la cadena entera, ves que el modelo es uno de doce factores y rara vez el más importante.

Este post hace ese análisis forense, pero al revés: en lugar de partir de un fallo y rebobinar, partimos de una request específica que funciona y desglosamos qué tuvo que pasar para que llegara a funcionar, y qué pasará después con ella. Es un tour guiado, no un diagnóstico de incidente. Pero la disciplina mental es la misma: ninguna etapa es autónoma, y entender el sistema significa entender los puentes entre etapas, no solo las cajas.

El escenario: chatbot de soporte multi-tenant para clientes regulados

Para el tour usamos un escenario concreto realista, lo bastante representativo como para que las observaciones se transporten a la mayoría de despliegues serios en mayo 2026. Es un producto SaaS de soporte al cliente con LLM, vendido a varios clientes corporativos (multi-tenant) en sectores regulados (banca, seguros, salud). El producto:

Acepta preguntas en lenguaje natural por chat embebido en la web del cliente.
Recupera fragmentos relevantes del knowledge base interno del cliente (documentos de producto, condiciones contractuales, FAQs).
Responde citando el fragmento utilizado, en el idioma del usuario, con tono adaptado a la marca.
Si la pregunta requiere una acción (cancelar, modificar plan, abrir caso), invoca una tool del catálogo expuesto vía MCP, con confirmación del usuario.
Está obligado por contrato a no inventar datos del cliente, a respetar la guía de estilo del tenant, y a cumplir compliance ENS / NIS2 sobre datos en la UE.

La infraestructura es on-premise sobre Kubernetes (RKE2 con CNI Cilium, en el patrón cubierto en Cilium BGP y CNI networking). El GPU plane es un cluster genérico 4×H100 SXM (80 GB cada una, NVLink) para serving e entrenamiento productivo, más una RTX 4090 (24 GB) para desarrollo, evals offline y reembeddings ad-hoc.

La request que vamos a seguir:

Usuario (cliente final, español, plan premium de una aseguradora): "¿Cómo cancelo mi suscripción premium? Llevo tres meses pagando y no he usado la mitad de las coberturas."

A primera vista, una pregunta simple. Vamos a ver qué hay detrás.

Paso 0 — El frame: la respuesta que el usuario ve

A las 11:47:32 de un martes, el usuario envía el mensaje. A los 4.2 segundos, ve aparecer en la UI:

Para cancelar tu suscripción premium, sigue estos pasos: (1) Accede al portal de cliente con tu DNI y contraseña. (2) Ve a Mis pólizas → Premium Vida 2024. (3) Pulsa Solicitar cancelación. (4) Selecciona el motivo (en tu caso, “no uso del producto”) y confirma. Te llegará un correo de confirmación en 24-48 h.

Antes de cancelar, te recuerdo que tu plan incluye revisión médica anual gratuita y asistencia 24/7 en viaje, coberturas que se pierden con la cancelación. Si quieres, puedo ayudarte a revisar tu uso de coberturas en los últimos tres meses para ver si te conviene cambiar a un plan más ajustado en vez de cancelar.

Fuente: [Política de cancelación, sección 4.2 de Condiciones Generales 2024]

El usuario marca después de leerla un thumbs-down y deja en el formulario: “la respuesta es correcta pero el tono es demasiado vendedor; sólo quería saber cómo cancelar”.

Esa secuencia —pregunta, respuesta, thumbs-down con feedback estructurado— es el último frame visible. Vamos hacia atrás para entender qué tuvo que ocurrir para que la respuesta saliera así.

Rebobinando hacia atrás: lo que ya estaba en su sitio antes de la request

Antes de que el usuario escribiera, el sistema ya tenía un modelo cargado en serving, un prompt activo etiquetado como production, un índice vectorial actualizado, un dataset versionado del último fine-tuning, y un golden eval set que validó la promotion. Cada uno de esos artefactos llegó allí por un proceso. Recorremos cuatro saltos hacia atrás.

t = −90 días — Etapa Retrain anterior cierra el ciclo previo

Hace tres meses, durante un ciclo de Retrain trimestral, ocurrieron dos cosas. La primera: el equipo de soporte revisó el feedback acumulado de los seis meses previos y vio un patrón —el modelo respondía con tono excesivamente formal a usuarios premium, que reportaban “se siente robótico”—. La segunda: un incidente puntual (un cliente cancela por una respuesta percibida como brusca) disparó un mini-ciclo incident-driven.

El proceso, en detalle cubierto en el post de Retrain, siguió cinco sub-procesos:

Captura de feedback — thumbs-down explícitos + feedback implícito (abandonments, retries) acumulados en una tabla feedback_signals de Postgres, todos con trace_id que permite rebobinar hasta el contexto exacto.
Triage por causa raíz — el cluster de incidentes “tono brusco” se categorizó como prompt issue (no era el modelo respondiendo mal, era el system prompt que pedía un registro demasiado formal). Un sub-cluster era model issue (en algunos casos el modelo se cerraba en banda incluso con un prompt más cálido).
Enriquecimiento del dataset — el equipo anotó manualmente 280 casos donde el modelo fue demasiado brusco, etiquetados con la respuesta de referencia (“cómo debería haber respondido”). Doble anotación en el 20% críticos; los casos con quality score < 4 quedaron fuera.
Decisión de cadencia — el incidente se trató como incident-driven; el resto del Retrain trimestral siguió calendario.
Promotion — el nuevo adapter customer_support_v7 pasó por eval gates contra customer_support_v6, canary 5% durante una semana, y se promovió cuando las métricas del golden set mostraron mejora estable en el segmento “tono / claridad” sin regresiones en el resto.

Resultado: el adapter activo en producción cuando el usuario envió la request del Paso 0 es customer_support_v7, entrenado sobre el dataset enriquecido enriched_retrain_2026_q1 versión 3, con doble lineage hasta el incidente original.

t = −60 días — Etapa Data: el dataset enriquecido se versiona y entra a circulación

Inmediatamente después de Retrain, la etapa Data del pipeline LLMOps hace su trabajo. Tres operaciones críticas, cubiertas en detalle en el post de data versioning:

Versionado inmutable del dataset enriquecido con DVC, hash sha256 propagado al registry. El identificador (enriched_retrain_2026_q1, v3, sha256:9af...) se convierte en el ticket de equipaje que recorrerá las próximas etapas.
Schema contract validado por CI: cada fila cumple el JSON Schema del entry esperado por el trainer (example_id, input.user_query, input.retrieved_context, expected_output, rubric, segment, difficulty). Una validación falla en CI si alguna fila rompe el contract.
Holdout segregation check: hash sha256 normalizado de cada input se compara contra todos los hashes del golden eval set activo (customer_support_golden_v12). Cero solapamientos = el dataset no contamina la eval. Si hubiera habido uno solo, el CI habría bloqueado el merge.

En paralelo, el corpus RAG (manuales de producto, FAQs, condiciones generales del tenant aseguradora) se mantiene vivo. El pipeline de ingestión sigue capturando cambios desde el CMS del cliente: una nueva sección de la política de cancelación se modificó en febrero y se reindexó en Qdrant. Como cuenta el post sobre RAG sobre Kafka, el corpus no se reentrena con cada cambio: se reembedea solo el delta, y lakeFS mantiene un branch del bucket de embeddings con la versión nueva. El branch se mergea a main cuando el recall@10 sobre un set de queries representativas se mantiene por encima del threshold (0.78 en este sistema).

t = −45 días — Etapa Tune: el adapter customer_support_v7 se entrena

Tres semanas tras cerrar el dataset, el entrenamiento del nuevo adapter LoRA arranca. Como detalla el post de fine-tuning continuo, el patrón productivo en 2026 evita reentrenar el modelo base — costoso, lento, irreversible — y favorece adapter LoRA sobre un modelo base estable (en este sistema, Llama 3 70B-instruct cuantizado a INT8 para serving). El entrenamiento:

Corre sobre 4 de las H100 (NVLink, tensor parallel) durante ~6 horas.
Usa transformers + PEFT + bitsandbytes, con monitoring por MLflow.
Cada step registra el dataset_id, dataset_version, dataset_hash como input artifact en MLflow.
El output —un fichero customer_support_v7.safetensors de ~280 MB con los pesos LoRA— se sube a MinIO con su propio hash, y MLflow registra model_id, model_version, parent_dataset.

A este punto, la cadena de lineage está cerrada en este tramo:

enriched_retrain_2026_q1, v3, sha256:9af...
│
▼
mlflow run train, run_id: 0xa721...
│
▼
customer_support_v7, sha256:5c1...

t = −38 días — Etapa Eval: el adapter v7 pasa por eval gates

El adapter recién entrenado no se promociona. Pasa por una suite de evals cubierta en detalle en el post sobre evals. El golden eval set —customer_support_golden_v12, 850 ejemplos curados por humanos, con kappa inter-anotador 0.81— se ejecuta contra dos modelos: el adapter v7 candidato y el v6 actualmente en producción. Las métricas:

Métrica	v6 (prod)	v7 (cand.)	Threshold
Faithfulness al fragmento RAG	0.87	0.89	≥ 0.82
Toxicidad (low is good)	0.012	0.011	≤ 0.02
Tono “cálido pero profesional” (judge LLM)	0.71	0.84	≥ 0.78
Format compliance (markdown estructurado)	0.94	0.93	≥ 0.90
Helpful-but-not-pushy (judge LLM)	0.66	0.79	≥ 0.75
Latency p95 (ms)	2840	2910	≤ 3500

A esto se añade la suite de guardrails y safety cubierta en el post de guardrails: jailbreak resistance, PII leakage detection, prompt injection sobre tools MCP. El v7 mejora en safety en dos métricas y empata en el resto.

El v7 entra al canary 5% del tráfico durante 7 días, manteniendo monitoreo cercano. Al final del canary, las métricas online confirman lo que el offline anticipaba: mejora en tono y helpfulness, latencia equivalente, sin nuevos modos de fallo. Promotion aprobada. El v7 pasa al label production.

t = −31 días — Etapa Deploy: el adapter v7 entra a serving

El adapter customer_support_v7 se promueve al cluster de serving. Tres piezas cubiertas en posts independientes entran en juego.

vLLM como motor de inferencia. El motor vive sobre Kubernetes, deployado vía un Operator dedicado, como cuenta el post sobre operators de LLM y el post sobre vLLM en K8s. El operator es responsable de detectar el nuevo adapter en el registry, hot-loadearlo sin reiniciar el motor (capacidad nativa de vLLM con --enable-lora), y dirigir tráfico a partir del label.

Disaggregated serving. Como detalla el post sobre disaggregated serving, el sistema separa prefill (intensivo en compute, throughput-bound) y decode (intensivo en memoria, latencia-bound) en pools de GPUs diferentes. La request del usuario, cuando llegue, prefila en un pod especializado y decodea en otro, comunicándose por NVLink + un fabric KV cache compartido.

Cluster GPU multi-tenant. El cluster H100 sirve a varios tenants, no solo a la aseguradora del Paso 0. Como cuenta el post sobre cluster multi-tenant, el aislamiento se materializa en cuatro planos: namespace de Kubernetes, ACLs sobre adapters (sólo el namespace del tenant carga sus LoRAs), partitioning del KV cache por tenant (un tenant no puede leer prefijos cacheados de otro), y quota de tokens/minuto enforzada en el gateway.

Prompt registry sincronizado. El system_prompt del producto vive en Langfuse con label production. La versión activa es customer_support_system_prompt, versión 12. El gateway lee el prompt de Langfuse en el path de la request (con cache de pocos segundos para no martillear el registry). Detallado en el post de prompt versioning.

Resultado en t = −31 días: la combinación (adapter v7, prompt v12, golden v12) está activa y servida. El sistema está listo para la request que llegará 31 días más tarde.

Avanzando: la request del usuario atraviesa el sistema

Volvemos al Paso 0: 11:47:32 de un martes. El usuario pulsa Enter. Vamos en tiempo real, en milisegundos.

t = 0 ms — Ingreso por el gateway

El navegador del usuario hace POST a chat.aseguradora-ejemplo.com/api/chat. El tráfico atraviesa el edge load balancer y entra al API gateway del producto SaaS. El gateway:

Autentica el JWT del usuario (cliente final del tenant aseguradora).
Extrae el tenant_id, valida que su quota de tokens/minuto no esté agotada.
Resuelve qué model_id, adapter_id, prompt_id corresponden a este tenant y producto. En este caso: llama-3-70b-int8 + customer_support_v7 + prompt label production.
Construye un trace_id único (W3C TraceContext, propagable a OTel) y arranca un span raíz.

A los 8 ms, el gateway pasa la request al pool de prefill.

t = 8 ms — Pull del prompt versionado

Antes de servir, el cliente OpenAI-compatible que el motor usa internamente hace pull del system prompt activo. Como detalla el post sobre prompt versioning, el patrón es:

prompt = prompt_registry.pull(
 name="customer_support_system_prompt",
 label="production", # apuntando ahora a v12
)
# Cache local de 30 s reduce el round-trip al 0.1 % de las requests

El span OTel del prompt pull lleva los atributos gen_ai.prompt.id = customer_support_system_prompt, gen_ai.prompt.version = 12, gen_ai.prompt.label = production. Quedan propagados a todos los hijos.

t = 12 ms — Retrieval RAG

El sistema necesita contexto de la base de conocimiento del tenant. Ejecuta:

query_embedding = encoder.encode(user_query)
chunks = qdrant.search(
 collection=f"tenant_{tenant_id}_kb_v3",
 vector=query_embedding,
 limit=4,
 score_threshold=0.72,
)
reranked = reranker.rerank(user_query, chunks, top_k=2)

A los 38 ms, el reranker devuelve dos fragmentos: uno de la Política de cancelación, sección 4.2 y otro de Beneficios del plan premium, sección 2.1. Como detalla el post sobre PostgreSQL + Qdrant, el corpus del tenant se mantiene aislado por colección y ACL: ningún tenant puede leer chunks de otro.

t = 40 ms — Construcción del payload final

El motor compone:

[system_prompt v12]
+ [contexto recuperado: 2 chunks]
+ [historial breve de la sesión: 1 turno previo]
+ [user query]

Total: ~1850 tokens de contexto. El span OTel registra gen_ai.request.input_tokens = 1850, gen_ai.request.model = llama-3-70b-int8, gen_ai.request.adapter = customer_support_v7.

t = 45 ms — Prefill

El payload entra al pool de prefill. La GPU procesa los 1850 tokens en una sola pasada paralela, computando para cada token sus vectores K y V (clave y valor de atención). Esos vectores se materializan como KV cache, cubierto en detalle en el post de fundamentos del KV cache. El cache resultante ocupa ~120 MB de VRAM en INT8.

Aquí aparece una optimización clave: el system prompt v12 está cacheado en el pool de prefill (prefix caching, cubierto en el post sobre PagedAttention). Como el system prompt es el mismo para esta tenant, los primeros ~500 tokens del contexto no se recomputan: se leen del cache de prefijo. Eso reduce el prefill efectivo de 1850 tokens a ~1350 tokens, ahorrando ~270 ms de compute.

A los 580 ms (prefill efectivo), el TTFT (time to first token) está listo. El primer token sale hacia el pool de decode.

t = 580 ms — Decode (streaming)

El pool de decode recibe el KV cache prefilled y empieza la generación token a token. Como detalla el post sobre disaggregated serving, la separación prefill/decode es lo que permite que un sistema multi-tenant mantenga TPS estable: el pool de decode está dimensionado para sostener miles de sesiones decodeando en paralelo a bajo coste por token, mientras el de prefill se dimensiona para bursts de TTFT cortos.

Generación a ~80 tokens/segundo. La respuesta tendrá ~290 tokens. Tiempo total de decode: ~3.6 s. Streaming: el usuario empieza a ver palabras desde t = 580 ms.

Mientras el decode avanza, el motor emite spans hijo en cada iteración con gen_ai.response.tokens_generated, gen_ai.response.cache_hit_ratio, gen_ai.response.cumulative_latency. El post sobre AgentSight y el post sobre MCP observability con OTel cubren la instrumentación detallada de esta capa.

t = 4 200 ms — Respuesta completa, span raíz cerrado

La generación termina. El motor cierra el span raíz con gen_ai.response.completion_tokens = 290, gen_ai.response.finish_reason = stop, gen_ai.response.total_latency_ms = 4200. El usuario ve la respuesta final. La sesión queda lista para un siguiente turno o para que el usuario haga clic en thumbs-up/thumbs-down.

A esta altura, todas las etapas activas han participado:

Data (pre-existente): el corpus RAG indexado, el dataset que entrenó el adapter, el golden set que lo validó.
Tune (pre-existente): el adapter v7 entrenado hace 45 días.
Eval (pre-existente): los gates que aprobaron la promotion.
Deploy (en este preciso instante): vLLM + disaggregated + KV cache + multi-tenant.
Observe (en este preciso instante): los spans OTel emitidos a Langfuse + Tempo, las métricas a Prometheus.
Retrain (a punto de activarse): el feedback que el usuario marcará en 15 segundos.

En paralelo: Observe está mirando

Mientras la request sucede, varias piezas de Observe corren en paralelo y dejan huella estructurada.

Tracing OTel. Cada span (gateway, prompt pull, retrieval, prefill, decode) viaja a Langfuse y a un colector OTel que los reenvía a un backend (Tempo / Jaeger). El trace_id único enlaza todos los spans. Como detalla el post sobre tracing con AgentSight, la propagación end-to-end es el principal habilitador del debug post-incidente: sin ella, no se puede reconstruir qué pasó tres semanas más tarde.

Métricas de runtime. El motor emite métricas Prometheus por intervalo: gpu_utilization, kv_cache_usage, tokens_per_second, queue_depth, prefill_latency_p95, decode_latency_p95. Las métricas no se asocian a un trace; son agregadas por tenant y servicio.

LLM-as-judge online. Un porcentaje configurable de respuestas (en este sistema, 2%) se ejecuta también por un judge LLM en background, que puntúa la respuesta contra una rúbrica simple (correcta / parcial / incorrecta + score de tono). El judge no bloquea la respuesta al usuario; alimenta el dashboard.

Drift estadístico. En paralelo, una pipeline más lenta computa drift sobre la distribución de inputs y outputs. Como cuenta el post sobre eBPF + drift, el monitoreo de bajo nivel (latencia, error rate por endpoint) se complementa con drift detection estadístico (KS test, embedding distance) que detecta cuando “algo va mal” antes de que un thumbs-down lo confirme.

Safety y guardrails monitor. El post sobre guardrails describe la capa que vigila intentos de jailbreak, PII leakage, prompt injection vía tools MCP. En este caso, ninguno se dispara.

Todas estas piezas operan continuamente, no por request. Pero esta request en particular dejó su huella en cada una de ellas.

El feedback: el bucle se cierra

A los 15 segundos de leer la respuesta, el usuario marca thumbs-down y deja en el formulario: “la respuesta es correcta pero el tono es demasiado vendedor; sólo quería saber cómo cancelar”. Ese gesto, aparentemente trivial, dispara una secuencia importante.

Inserción en feedback_signals

Como detalla el post sobre Retrain, el thumbs-down se persiste como una fila estructurada en una tabla Postgres:

INSERT INTO feedback_signals (
 signal_id, trace_id, request_id, signal_type, signal_value,
 prompt_id, prompt_version, model, user_segment, occurred_at
) VALUES (
 gen_random_uuid(),
 '4f5...', -- el trace_id del Paso 0
 'r-22a...', -- request_id
 'thumbs',
 '{"vote":"down","reason":"too pushy","text":"sólo quería saber cómo cancelar"}',
 'customer_support_system_prompt',
 12,
 'llama-3-70b-int8+customer_support_v7',
 'premium-es',
 '2026-05-19T11:47:51+02:00'
);

Con esto, la fila queda enlazada por trace_id a todo lo que ocurrió: prompt v12, contexto recuperado, output completo, métricas de latencia, score del judge (en este caso 0.82, considerado bueno por el judge pero el humano discrepa).

Triage por causa raíz

El equipo MLE pasa por triage la próxima mañana. Combinando reglas heurísticas, LLM-as-classifier y revisión humana:

La señal no es model issue: el modelo respondió correctamente al prompt que recibió.
No es retrieval issue: los chunks recuperados eran los correctos.
No es infra issue: la latencia fue normal.
Es prompt issue: el system prompt v12 instruye al modelo a “ofrecer alternativas antes de procesar acciones destructivas”. Esa instrucción genera el “tono vendedor” en algunos contextos.

El incidente se acumula con otros del mes en el cluster “tono vendedor”. Cuando el cluster supere un threshold (típicamente 30-50 incidentes del mismo tipo o un porcentaje del total), entrará a un mini-ciclo incident-driven o esperará al Retrain trimestral, dependiendo del tamaño.

El siguiente ciclo lo recoge

Tres meses más tarde, en el siguiente Retrain trimestral, este feedback es uno de muchos que motivarán dos cambios:

Nueva versión de prompt v13 con instrucción ajustada: “ofrecer alternativas sólo si el usuario no expresa intención clara de cancelar”.
Posible refuerzo del adapter con casos de tono más directo para premium-es. Si el cluster lo justifica.

El v13 entrará en su propia eval gate. El golden set crecerá con casos donde el tono correcto sea “directo, no vendedor”. El v8 del adapter (si llega) reentrenará sobre el dataset enriquecido enriched_retrain_2026_q2 que ya contiene este caso anotado.

El ciclo se cierra. La request del Paso 0 ha contribuido a la versión del sistema que servirá a otro usuario tres meses después.

Lo que va en cada trace: identidad y trazabilidad

Si el lector mira los siete identificadores omnipresentes en este recorrido, ve la red de identidades que permite todo lo anterior. Es la infraestructura de identidad del sistema LLM en producción:

trace_id 4f5... (unique per request)
request_id r-22a... (idem)
prompt_id customer_support_system_prompt
prompt_version 12
prompt_label production
dataset_id enriched_retrain_2026_q1
dataset_version v3 (sha256:9af...)
model_id llama-3-70b-int8
adapter_id customer_support_v7 (sha256:5c1...)
deployment_id d-prod-7b
schema_version 3.2
tenant_id aseguradora-ejemplo
user_segment premium-es
golden_set_id customer_support_golden_v12

Si una sola pieza de ese conjunto falta o no propaga, la cadena se rompe. El siguiente incidente investigado caerá en “no podemos rebobinar hasta el origen porque el sistema no lo registró”. Por eso los componentes transversales —prompt versioning y data versioning— no son lujos: son la conexión sin la cual las otras seis etapas operan a ciegas.

Diagrama síntesis: cómo encajan las piezas

 ┌─────────────────────────────────────────┐
│ Usuario (cliente final, B2C) │
└─────────────────┬───────────────────────┘
│ chat msg + JWT
▼
┌─────────────────────────────────────────┐
│ Edge LB + WAF + Cilium CNI │
└─────────────────┬───────────────────────┘
│ HTTPS, mTLS interno
▼
┌─────────────────────────────────────────────────┐
│ API Gateway (auth, quota, model routing) │
│ - Resuelve tenant → model + adapter + prompt │
│ - Inicia trace_id (W3C) │
└──────┬─────────────────────┬────────────────────┘
│ │
(pull prompt) │ │ (pull config)
▼ ▼
┌────────────────────┐ ┌──────────────────────┐
│ Langfuse Prompt │ │ Model registry │
│ Registry (v12) │ │ (adapter v7) │
└─────────┬──────────┘ └──────────┬───────────┘
│ │
└──────────┬───────────────┘
│ payload listo
▼
┌──────────────────────────────────────────┐
│ vLLM motor (K8s Operator) │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Pool prefill │ → │ Pool decode │ │
│ │ (H100×N) │ │ (H100×M) │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ │ KV cache fabric │ │
│ └──────────────────┘ │
│ - prefix caching del system prompt │
│ - PagedAttention │
└──────┬───────────────────────────────────┘
│ tokens stream
▼
┌─────────────────────────────────────────┐
│ Usuario ve respuesta + UI thumbs/UX │
└─────────────────┬───────────────────────┘
│ feedback (15 s después)
▼
┌─────────────────────────────────────────┐
│ feedback_signals (Postgres) │
│ + Langfuse scores │
└─────────────────┬───────────────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
▼ ▼ ▼
triage ciclo Retrain trimestral dataset_id
causa raíz o incident-driven enriquecido (DVC)
│
▼
Tune del v8
(próximo ciclo)
En paralelo durante toda la request, instrumentación OTel:
spans → Tempo / Jaeger ; eventos → Langfuse ; métricas → Prometheus

El stack on-premise aplicado

Llevar lo anterior a una infra on-premise genérica de perfil consultor (RTX 4090 + cluster 4×H100 SXM):

Capa	Recursos típicos
Plano de red	Edge LB (HAProxy / nginx ingress) + CNI Cilium con BGP, cubierto en Cilium BGP
Plano de cómputo K8s	RKE2 con dos nodes managers + node pool de GPU
Plano GPU productivo	4× H100 SXM (NVLink, 80 GB cada una), particionadas vía MIG en pools prefill/decode
Plano GPU desarrollo	1× RTX 4090 (24 GB) para evals offline, drift-check embeddings, smoke tests
Plano storage	MinIO o Ceph object store; DVC remote + lakeFS backend
Plano datos OLTP	Postgres 18 con replicación; pgvector 0.8 para casos pequeños
Plano vector	Qdrant o Milvus para corpus RAG grandes
Plano stream	Kafka (Redpanda / Apache puro) + Schema Registry; CDC con Debezium o Flink CDC
Plano observabilidad	OTel Collector + Tempo (traces) + Prometheus (metrics) + Loki (logs); Langfuse para LLM-específico
Plano runtime security	Tetragon, cubierto en post sobre runtime security

La densidad real no es la suma de las cajas: es la operativa que ata las cajas. Un cluster con todas las piezas pero sin disciplina de versionado, sin propagación de trace_id extremo a extremo, sin schema contracts y sin retraining cadenciado, es un cluster que sirve LLM una vez y que envejece. La diferencia entre un proyecto y una plataforma es exactamente eso.

Diez puentes entre etapas donde se rompe el sistema

El recorrido revela algo importante: los fallos rara vez están dentro de una etapa; están en los puentes entre etapas. Diez puentes habituales:

Data → Tune: el dataset no propaga su (dataset_id, dataset_version) al trainer. Mismo dataset entrenado dos veces produce dos model_id que no se pueden distinguir.
Tune → Eval: el modelo entrenado no propaga su lineage al run de eval. El eval pasa, pero no queda registrado contra qué dataset se entrenó. Tres meses después, irreproducible.
Eval → Deploy: la promotion ocurre sin que el sistema de serving registre qué versión del adapter está sirviendo en cada instante. El día que el modelo da una respuesta peligrosa, no se sabe qué adapter respondió.
Deploy → Observe: el motor no emite gen_ai.request.adapter, gen_ai.prompt.version, gen_ai.dataset.version como atributos del span. Los traces existen pero no se pueden cruzar con el lineage.
Observe → Retrain: el feedback se captura en una herramienta (Langfuse, Phoenix) pero nadie lo lee. La etapa Retrain “está”, pero el feedback se acumula sin triagear.
Retrain → Data: el dataset enriquecido se mete en el siguiente Tune sin pasar por la disciplina de versionado, schema contract y holdout check. Contaminación silenciosa del golden set.
Prompt versioning ↔ todo: el prompt_id, prompt_version no se propaga a los spans. El día que el equipo descubre que un cambio de prompt regresionó el sistema, no puede aislar cuál ni cuándo.
Data versioning ↔ todo: el dataset_id, dataset_version no aparece en el experiment tracking. Se “vuelve a entrenar v8” pero nadie puede demostrar que sea sobre el dataset enriquecido y no sobre el viejo.
MCP ↔ tools: el sistema invoca tools (cancelación, modificación de pólizas) pero no registra gen_ai.tool.invocation_id enlazado al trace. Las acciones quedan disociadas de la respuesta que las generó.
Schema Registry ↔ datos: los datasets versionan contenido pero no schema. Un breaking change en el expected_output rompe el eval silenciosamente; nadie nota nada hasta que un humano revisa los resultados.

Los puentes están cubiertos a lo largo del blog. La operativa los enforza. La cultura del equipo los mantiene.

Cómo recorrer el blog

Si llegas a este post desde fuera y quieres una ruta de lectura:

El mapa: Pipeline LLMOps de seis etapas — el mapa maestro de todo lo demás.
El contexto: MLOps específico para LLMs en 2026 — el panorama y por qué LLMOps no es MLOps clásico.
Inferencia desde dentro hacia afuera: KV cache → PagedAttention deep dive → Disaggregated serving → Cluster GPU multi-tenant → vLLM en K8s → Operators LLM K8s.
Datos: Data versioning con DVC y lakeFS → PostgreSQL + Qdrant ingestión → RAG sobre Kafka.
Tune: Fine-tuning continuo en producción.
Eval: Evals: la capa después del tracing → Guardrails y safety.
Observe: AgentSight tracing LLM → MCP observability con OTel → eBPF on-device + drift.
Retrain: Cerrar el bucle feedback → dataset → adapter.
Transversales: Prompt versioning con Langfuse y MLflow.
Infra de soporte (la base sobre la que se monta todo): RKE2 con Cilium BGP, Hubble + observabilidad eBPF, Tetragon runtime security.

Lo que no hemos cubierto (todavía)

A primer nivel está lo principal. Los siguientes posts del blog —cuando los temas lo justifiquen— podrían profundizar en:

Schema Registry para LLM data y prompts: la otra mitad del data contract.
AI Gateway dedicado: LiteLLM, Portkey, Kong AI Gateway como plano de control.
OTel gen_ai semantic conventions: el estándar emergente que ata los siete identificadores del bloque “identidad” en spans bien formados.
Federated learning sobre datos de clientes regulados: cómo entrenar sin centralizar el corpus.
Capacity planning para clusters multi-tenant compartidos.
Disaster recovery de un servicio LLM: cómo reproducir el estado del sistema 30 días atrás.
Cost accounting por tenant: tokens × pesos × adapter × infraestructura → factura.

Ver también

El catálogo paralelo: las seis etapas LLMOps en open source y en los hyperscalers — el corte vertical complementario a este post: las mismas seis etapas + dos transversales, pero cruzadas con sus equivalentes en AWS, GCP y Azure, y con el chatbot de la aseguradora portado a stack AWS.
El catálogo OSS para LLMOps en seis etapas: ficha por ficha — el zoom in al lado open source del catálogo paralelo: ficha de ~150 palabras por herramienta core (vLLM, Langfuse, DVC, Qdrant, Airflow, NeMo Guardrails, Presidio…), licencia y gobierno, matriz de decisión por etapa y diagrama del stack OSS conectado. Funciona como caja de herramientas de referencia del consultor.
El pipeline LLMOps de seis etapas
MLOps específico para LLMs en 2026
Data versioning para LLMOps
PostgreSQL + Qdrant para ingestión
RAG sobre Kafka: arquitectura técnica
Fine-tuning continuo en producción
Evals: la capa después del tracing
Guardrails y safety en LLMs
KV cache: la memoria de trabajo de la inferencia LLM
PagedAttention por dentro
Disaggregated serving: prefill y decode
Speculative decoding: el secretario que adelanta lo que va a decir el jefe
FlashAttention v1/v2/v3/v4: el bibliotecario que nunca despeja la mesa
El cluster GPU como plataforma multi-tenant
vLLM en Kubernetes
Operators LLM en Kubernetes
AgentSight: tracing LLM end-to-end
MCP por dentro y observabilidad con OTel
eBPF en inferencia local y drift detection
Retrain: cerrar el bucle feedback → dataset → adapter
Prompt versioning con Langfuse y MLflow
RKE2 con Cilium BGP
Hubble + observabilidad eBPF
Tetragon runtime security

Referencias

W3C Trace Context — propagación de traceparent y tracestate end-to-end.
OpenTelemetry GenAI Semantic Conventions — atributos gen_ai.* para spans LLM.
Langfuse documentation — observability y prompt registry.
vLLM documentation — motor de inferencia productivo con PagedAttention y LoRA hot-swap.
Kubernetes Operators — patrón de gestión declarativa.
MLflow Tracking and Model Registry — lineage de runs e input artifacts.
DVC y lakeFS — versionado de datasets, unificadas en Nov 2025.
OpenLineage — estándar abierto de eventos de lineage entre sistemas.
ENS / NIS2: marcos de compliance que aplican a operadores en la UE; lectura recomendada para el contexto en que opera el escenario.

Runbook: enjaular al agente de IA — bubblewrap en el cliente, Tetragon en el cluster

Tue, 09 Jun 2026 17:00:00 +0200

Compañero operativo de El contratista con la llave maestra. Aquel post explica el porqué y el dónde —el modelo de amenaza, las cinco familias de aislamiento, qué dominio usa cada una—; este es el cómo, con comandos. Si no lo has leído, léelo antes: aquí doy por sabido qué es el radio de explosión, por qué bwrap corre sin root y qué vigila Tetragon. El procedimiento va en dos tracks independientes —cliente y cluster— porque, como argumenta el post hermano, el control se extrapola pero la primitiva se reescribe.

TL;DR

Dos procedimientos reproducibles. Cliente (workstation): instala ai-jail (envuelve bubblewrap), genera el .ai-jail por proyecto, audita con --dry-run, fija las allowlists con --bootstrap, usa --lockdown para lo que no te fíes, y deja al agente sin permiso de git push. Cluster (RKE2 con Cilium + Tetragon): pon el baseline de pod (securityContext sin privilegios, seccomp: RuntimeDefault, NetworkPolicy default-deny), mete el pod del agente no confiable en una microVM con runtimeClassName: kata, y despliega las TracingPolicy de Tetragon en dos fases —observar con action: Post para levantar el baseline, luego promover a action: Sigkill sobre tcp_connect (egress) y security_file_open (rutas de secretos)—. La regla de oro de la fase Tetragon: adopta primero, bloquea después; nunca metas un Sigkill en producción sin haber visto antes los eventos en modo observación.

El flujo de los dos tracks

Track A — Cliente (workstation del desarrollador)

A0 — Instalar ai-jail y bubblewrap

ai-jail envuelve el sandbox; en Linux necesita bubblewrap aparte, en macOS no necesita dependencia extra.

# ai-jail (macOS y Linux)
brew tap akitaonrails/tap && brew install ai-jail
# o, con cargo:
cargo install ai-jail
# o, con mise:
mise use -g ubi:akitaonrails/ai-jail

# bubblewrap en Linux (elige tu distro)
sudo pacman -S bubblewrap # Arch
sudo apt install bubblewrap # Debian / Ubuntu
sudo dnf install bubblewrap # Fedora

Comprueba que el binario está y que bwrap corre sin root (no debe pedir sudo):

ai-jail --version
bwrap --ro-bind / / --unshare-all echo "bwrap ok sin root"

Si bwrap falla pidiendo privilegios, tu kernel tiene los unprivileged user namespaces deshabilitados; habilítalos (sysctl kernel.unprivileged_userns_clone=1 en Debian/Ubuntu antiguos) antes de seguir.

A1 — El fichero .ai-jail por proyecto

En el primer arranque dentro del proyecto, ai-jail crea un .ai-jail (TOML) commiteable al repo: cualquier compañero que clone hereda la misma política.

cd ~/Projects/mi-app
ai-jail claude # crea .ai-jail y lanza Claude Code dentro del sandbox

El fichero generado:

# .ai-jail — configuración del sandbox (commitéalo al repo)
command = ["claude"]
rw_maps = [] # directorios extra con escritura
ro_maps = [] # directorios extra de solo lectura

Antes de confiar en el sandbox, audítalo. --dry-run --verbose imprime cada punto de montaje, cada flag de aislamiento y el comando bwrap completo, sin ejecutar nada:

ai-jail --dry-run --verbose claude

Lee la salida y confirma tres cosas: que $HOME se monta como tmpfs (no el real), que ~/.ssh, ~/.aws y ~/.gnupg no aparecen entre los montajes, y que el único directorio con escritura es el del proyecto. Si necesitas un directorio extra:

ai-jail --rw-map ~/Projects/shared-lib claude # extra con escritura
ai-jail --map /opt/datasets claude # extra de solo lectura

Otros agentes, mismo binario:

ai-jail codex
ai-jail opencode
ai-jail bash # shell pelado para depurar el sandbox
ai-jail -- python script.py # cualquier comando

A2 — Las allowlists de permisos con –bootstrap

--bootstrap genera las configuraciones de permisos de cada agente, con allow/deny/ask sensatos, y hace backup antes de sobrescribir:

ai-jail --bootstrap

Lo que produce, en resumen:

Agente	Fichero	Política base
Claude Code	`~/.claude/settings.json`	allow: `git status/diff/log`, `ls`, `grep`, `cargo`, `npm`, `python`, `docker compose` · ask: `git push`, `rm`, `docker run` · deny: `rm -rf`, `sudo`, `chmod 777`, `git push --force`
Codex	`~/.codex/config.toml`	`approval_policy = "on-request"`
OpenCode	`~/.config/opencode/opencode.json`	permisos de `bash`, `edit`, `write`

La clave operativa: git push está en ask, no en allow, y git push --force en deny. El agente puede commitear, ramear y rebasar localmente cuanto quiera; nada de eso toca el remoto. (Si usas el /sandbox de Claude Code, fija además "allowUnsandboxedCommands": false para cerrar el escape hatch dangerouslyDisableSandbox, que de fábrica es opt-out.)

A3 — Lockdown para lo que no te fíes

Para auditar código de terceros o correr un agente sobre un proyecto que no conoces, --lockdown va más allá: proyecto montado en read-only, GPU/Docker/display deshabilitados, --rw-map/--map ignorados, $HOME tmpfs puro sin dotfiles del host, red cortada con --unshare-net y environment limpiado con --clearenv.

ai-jail --lockdown bash

Es el sandbox más restrictivo posible sin llegar a una VM. Úsalo como defecto mental para todo lo que no sea tu propio código en tu propia máquina.

A4 — La red de seguridad: git sin push

No es un flag, es una propiedad del entorno que cambia el cálculo de riesgo. Si el proyecto está en git con remoto, y el agente no tiene permiso de push, el peor caso —que corrompa cada fichero del proyecto— se revierte con:

git checkout . # vuelve al último commit
# y si tocó .git (improbable): borra el dir y re-clona

El remoto nunca se tocó. Sandbox para el filesystem + git para el código + push manual es ya un nivel razonable para uso diario: ai-jail protege tus datos y el sistema, git protege el código, y la decisión de publicar sigue siendo tuya.

Track B — Cluster (RKE2 con Cilium + Tetragon)

El agente no confiable —o la inferencia que ejecuta código generado— corre como pod. El mismo principio del cliente, otras primitivas. Asumimos un cluster genérico RKE2 con Cilium como CNI y Tetragon ya desplegado (el DaemonSet del agente eBPF en cada nodo).

B0 — El baseline del pod

Antes de cualquier eBPF, lo de serie. securityContext sin privilegios, raíz read-only, seccomp por defecto:

apiVersion: v1
kind: Pod
metadata:
 name: ai-agent
 namespace: agentes
 labels:
 app: ai-agent
spec:
 securityContext:
 runAsNonRoot: true
 runAsUser: 10001
 seccompProfile:
 type: RuntimeDefault
 containers:
 - name: agent
 image: registry.interno/ai-agent:pinned
 securityContext:
 allowPrivilegeEscalation: false
 readOnlyRootFilesystem: true
 capabilities:
 drop: ["ALL"]
 volumeMounts:
 - { name: work, mountPath: /work }  # único escribible
 volumes:
 - name: work
 emptyDir: {}

Y el corte de egress por defecto —el gemelo cluster del --unshare-net—. NetworkPolicy default-deny de salida en el namespace, abriendo solo DNS y lo imprescindible:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
 name: default-deny-egress
 namespace: agentes
spec:
 podSelector: {}
 policyTypes: ["Egress"]
 egress:
 - to:
 - namespaceSelector:
 matchLabels: { kubernetes.io/metadata.name: kube-system }
 ports:
 - { protocol: UDP, port: 53 }
 - { protocol: TCP, port: 53 }

B1 — RuntimeClass Kata: el pod no confiable en su propia microVM

Para código realmente no confiable, sácalo del kernel compartido. Con Kata desplegado existe un RuntimeClass:

apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
 name: kata
handler: kata

Y el pod lo pide con una línea —runtimeClassName: kata—, ejecutándose en su propia microVM con kernel dedicado en lugar de compartir el del nodo:

spec:
 runtimeClassName: kata  # ← el pod corre en una microVM, no en el kernel del nodo
 # ...resto igual que B0

Es el gemelo cluster del aislamiento por construcción: un exploit de kernel dentro del pod no alcanza al nodo.

B2 — Tetragon, fase observación (Post)

Ahora la capa que distingue una plataforma con visibilidad de runtime. Primero observar, nunca matar de entrada. Una TracingPolicyNamespaced —scoped al namespace y a la etiqueta del agente— que reporta (no mata) tres cosas: ejecuciones de proceso, conexiones de red y aperturas de rutas sensibles. action: Post solo emite el evento.

apiVersion: cilium.io/v1alpha1
kind: TracingPolicyNamespaced
metadata:
 name: agente-observa
 namespace: agentes
spec:
 podSelector:
 matchLabels:
 app: ai-agent
 kprobes:
 # --- conexiones salientes ---
 - call: "tcp_connect"
 syscall: false
 args:
 - index: 0
 type: "sock"
 selectors:
 - matchActions:
 - action: Post
 # --- aperturas de ficheros sensibles ---
 - call: "security_file_open"
 syscall: false
 args:
 - index: 0
 type: "file"
 selectors:
 - matchArgs:
 - index: 0
 operator: "Prefix"
 values:
 - "/var/run/secrets"
 - "/work/.git/config"
 matchActions:
 - action: Post

(Las ejecuciones de proceso no necesitan kprobe: Tetragon emite process_exec/process_exit de forma nativa.) Despliega y observa los eventos en vivo desde el pod de Tetragon del nodo:

kubectl apply -f agente-observa.yaml
# eventos legibles, filtrando por el namespace:
kubectl exec -n kube-system ds/tetragon -c tetragon -- \
 tetra getevents -o compact --namespace agentes

Deja esto rodando una jornada típica del agente. Apunta a qué destinos conecta de verdad (tu registry interno, tu mirror de HF, tu endpoint de vLLM) y qué rutas abre. Eso es tu baseline: la lista de lo legítimo. Sin este paso, un Sigkill mata trabajo bueno y te genera un incidente de disponibilidad —justo lo que el ENS te pide evitar—.

B3 — Tetragon, fase enforcement (Sigkill)

Con el baseline en la mano, promueve a bloqueo. Dos reglas. La primera: mata cualquier conexión cuyo destino no esté en la allowlist —NotDAddr invierte el match: dispara para todo lo que no sea esas redes—. La segunda: mata cualquier intento de abrir una ruta de secretos.

apiVersion: cilium.io/v1alpha1
kind: TracingPolicyNamespaced
metadata:
 name: agente-enforce
 namespace: agentes
spec:
 podSelector:
 matchLabels:
 app: ai-agent
 kprobes:
 # --- egress: mata todo lo que NO sea la allowlist ---
 - call: "tcp_connect"
 syscall: false
 args:
 - index: 0
 type: "sock"
 selectors:
 - matchArgs:
 - index: 0
 operator: "NotDAddr"
 values:
 - "127.0.0.1"
 - "10.0.0.0/8" # red interna del cluster
 - "172.16.10.20" # registry interno (ejemplo)
 matchActions:
 - action: Sigkill
 # --- lectura de secretos: mata el proceso ---
 - call: "security_file_open"
 syscall: false
 args:
 - index: 0
 type: "file"
 selectors:
 - matchArgs:
 - index: 0
 operator: "Prefix"
 values:
 - "/var/run/secrets/kubernetes.io/serviceaccount/token"
 - "/work/.ssh"
 matchActions:
 - action: Sigkill

kubectl apply -f agente-enforce.yaml

Ahora el agente puede hacer lo que quiera dentro del pod, pero en el instante en que intenta conectar a un destino no permitido o leer el token de la service account, Tetragon lo mata en el kernel —antes de que el paquete salga o el read devuelva bytes—. Es el gemelo cluster de la blocklist de curl y del ~/.ssh no montado, pero aplicado en runtime y sobre cualquier binario, no solo los que conoces.

Aviso operativo. El enforcement con Sigkill requiere kernel reciente con soporte de la acción en eBPF (5.10+ es seguro). Despliega agente-enforce primero en un namespace de pruebas, y mantén agente-observa activo en paralelo: si el bloqueo dispara, el evento Post te dice exactamente qué lo provocó. Adopta primero, bloquea después.

La tabla de equivalencias cliente ↔ cluster

El mismo vector, las dos primitivas. Esto es “extrapolar la tecnología” hecho explícito:

Vector de amenaza	Cliente (workstation)	Cluster (RKE2)
`$HOME` / raíz escribible	`$HOME` como tmpfs efímero (`bwrap`)	`readOnlyRootFilesystem: true` + `emptyDir`
Egress arbitrario	blocklist `curl`/`wget` · `--unshare-net`	NetworkPolicy default-deny + Tetragon `NotDAddr`→`Sigkill`
Lectura de secretos	`~/.ssh`/`~/.aws`/`~/.gnupg` no montados	secretos fuera del pod + Tetragon `security_file_open`→`Sigkill`
Escape del kernel	Landlock (2ª barrera VFS)	`runtimeClassName: kata` (microVM, kernel propio)
Sin escape hatch	proceso dentro de `bwrap`, sin salida	sin `privileged`, `drop ALL`, `allowPrivilegeEscalation:false`
Daño al código	git remoto sin `push` → `git checkout .`	GitOps + revisión de PR, el agente no aplica a `main`
Visibilidad	`--dry-run --verbose` (estático, pre-run)	Tetragon `tetra getevents` (dinámico, en runtime)

Checklist de gotchas

No metas un Sigkill sin pasar por Post. El baseline de observación no es opcional: es lo que separa “bloquear un C2” de “tirar tu propio job de fine-tuning”.
El .ai-jail se commitea; los secretos no. El TOML es política, no credenciales. Verifica que no metes rutas con datos sensibles en rw_maps.
readOnlyRootFilesystem rompe apps que escriben en /tmp. Monta un emptyDir en /tmp además del de trabajo.
NetworkPolicy sin regla de DNS deja al pod ciego. Abre el puerto 53 a kube-system o nada resuelve.
Kata no es gratis. Añade latencia de arranque y no todo workload con dispositivos especiales (GPU passthrough) encaja; resérvalo para lo no confiable, no para todo.
El /sandbox de Claude Code no cubre MCP ni hooks salvo que actives sandbox-runtime. Si tu agente usa servidores MCP, asume que corren con permisos completos hasta que lo hagas.
NotDAddr con IPs literales envejece mal. Documenta la allowlist y revísala cuando cambie el registry o el endpoint de inferencia; considera CIDRs internos estables en vez de IPs sueltas.

Ver también

El contratista con la llave maestra: aislar agentes de IA del workstation al cluster — el panorama que este runbook ejecuta: modelo de amenaza, las cinco familias de aislamiento y por qué cliente y cluster usan primitivas distintas.
La puerta de la cocina que el maître no miró: Cilium eBPF y DRANET — la capa eBPF de Cilium sobre la que Tetragon engancha sus kprobes; el datapath que ya tienes en el cluster.
Controles técnicos: ENS × ISO 42001 × EU AI Act — los eventos de Tetragon como evidencia técnica de op.mon/op.exp; el enforcement como medida de protección.
Guardrails y safety en LLM — la mitigación en el plano del contenido; este runbook, la del plano de la ejecución.
Siete fases de despliegue de una plataforma LLM on-premise — dónde encaja el endurecimiento de runtime en la secuencia de despliegue (F4 identidad/políticas, F5 plataforma).

Referencias

ai-jail (Fabio Akita), GPL-3.0: https://github.com/akitaonrails/ai-jail
bubblewrap: https://github.com/containers/bubblewrap
Landlock LSM: https://landlock.io
Tetragon — TracingPolicy: https://tetragon.io/docs/concepts/tracing-policy/
Tetragon — enforcement (Sigkill/Override): https://tetragon.io/docs/concepts/enforcement/
Kata Containers — Kubernetes RuntimeClass: https://katacontainers.io
Kubernetes — Pod Security & seccomp: https://kubernetes.io/docs/tutorials/security/seccomp/
Kubernetes — Network Policies: https://kubernetes.io/docs/concepts/services-networking/network-policies/
Cilium: https://cilium.io

El contratista con la llave maestra: aislar agentes de IA del workstation al cluster

Tue, 09 Jun 2026 16:00:00 +0200

Primer post de una pareja sobre aislamiento de agentes de IA. Este fija el qué y el dónde: el mapa completo de primitivas de aislamiento y a qué dominio pertenece cada una. El runbook hermano fija el cómo, con comandos: ai-jail y bubblewrap en el cliente, TracingPolicy de Tetragon y RuntimeClass en el cluster. Si solo vas a leer uno, este te da el modelo mental; el otro, los ficheros que se copian y pegan.

TL;DR

Un agente de IA que ejecuta código necesita acceso a tu filesystem y a tus herramientas: compilador, linter, grep, make, cargo, npm. Ese es el mínimo para ser útil. El problema es que junto a ese acceso viaja la capacidad de leer ~/.aws/credentials, exfiltrar tus claves SSH o lanzar un rm -rf fuera del directorio del proyecto. Y no hace falta un modelo malicioso: basta una dependencia comprometida en un npm install, porque el agente bienintencionado y el post-install script envenenado corren con los mismos permisos. La respuesta no es confiar en las buenas intenciones del LLM; es aislar para acotar el radio de explosión. Este post recorre las cinco familias de aislamiento de 2026 —del sandbox de proceso a la VM completa— y las reparte en dos columnas: lo que aplica en el cliente (el workstation del desarrollador: bubblewrap, ai-jail, sandbox-exec, Landlock, los sandboxes nativos de Claude Code y Codex) y lo que aplica en el cluster (donde el agente o la inferencia corren en Kubernetes: namespaces+seccomp, gVisor, microVMs Firecracker/Kata y eBPF/Tetragon como capa de observación y enforcement en caliente). La tesis: el modelo de amenaza es el mismo en los dos sitios; las herramientas, no. La política se extrapola; la primitiva se reescribe.

La analogía: el contratista con la llave maestra

Contratas a un operario para una reforma. Es competente y va de buena fe. Pero pasan dos cosas que no controlas. La primera: puede malinterpretar la orden y tirar el tabique equivocado. La segunda, peor: su caja de herramientas pudo manipularse antes de que entrara por tu puerta —alguien metió algo dentro—, y cuando la abre en tu salón, ese algo se activa.

Nadie sensato le da la llave maestra del edificio entero. Le abres la habitación donde trabaja, le dejas las herramientas que necesita, y mantienes cerrados el despacho con la caja fuerte y el cuarto de los servidores. Si la reforma sale mal —por error o por sabotaje—, el daño se queda en esa habitación.

Un agente de IA es ese contratista. El sandbox es la política de llaves: le das la habitación del proyecto y las herramientas, no la llave maestra del sistema. Y aquí está el giro que justifica dos posts: el operario trabaja en dos edificios distintos. Uno es tu piso —el workstation del desarrollador, con tus credenciales, tu ~/.ssh, el baúl de contraseñas del navegador—. El otro es el centro de datos —el cluster donde la inferencia y los agentes autónomos sirven a clientes, con datos de varios inquilinos a la vez—. La política de llaves es idéntica en los dos: principio de mínimo privilegio, acota el radio. Pero la cerradura de la puerta de tu piso no es la misma que la del centro de datos. En el piso pones un bombín (bubblewrap). En el centro de datos pones un guardia que vigila cada puerta y un ala separada del edificio (Tetragon + microVM). Mismo principio, distinta ferretería. Eso es extrapolar la tecnología, no copiarla.

El modelo de amenaza: qué puede hacer un agente desbocado

Antes de elegir cerradura conviene enumerar al ladrón. La superficie de ataque de un agente que ejecuta bash arbitrario se descompone en cinco amenazas concretas. No todas se defienden con la misma capa, y —dato incómodo que la propia documentación de seguridad reconoce— ninguna capa las cubre todas.

Amenaza	Qué hace el agente	Capa mínima que la corta
Filesystem fuera de alcance	Lee `.env`, `~/.ssh/id_rsa`, secretos del sistema; modifica fuentes fuera del proyecto	Sandbox de proceso (allowlist de rutas)
Egress de red arbitrario	Exfiltra datos, recibe instrucciones de un C2 remoto, llama APIs sin autorizar	Bloqueo de red / NetworkPolicy / microVM
Superficie de syscalls del kernel	Un exploit del kernel desde el contenedor escala al host (kernel compartido)	gVisor o microVM (kernel dedicado)
Fuga entre inquilinos	El workload de un cliente lee datos de otro en una plataforma multi-tenant	microVM (estándar de facto)
Exfiltración de secretos	Saca tokens y variables de entorno vía `/proc` o el environment	`--clearenv` / tmpfs de `$HOME` / secretos fuera del pod

Hay una sexta amenaza que ningún sandbox resuelve: el prompt injection. Si un atacante consigue colar instrucciones en el contexto del agente —un comentario envenenado en el código, un fichero malicioso que el agente lee, una respuesta adversaria de una herramienta—, el agente ejecutará esas instrucciones con los permisos que el sandbox le conceda. El aislamiento encoge el radio de impacto de una inyección exitosa; no impide la inyección. Por eso el sandbox es una capa, no la solución: encima van validación de entrada, allowlists de tool-calls y auditoría de salida. La frase a interiorizar: el aislamiento no hace al agente confiable; acota lo que un agente no confiable puede romper.

Dos dominios, una política

El operario trabaja en dos edificios. El reparto de herramientas se ve mejor a dos columnas:

El cliente: aislar al agente en el workstation

Aquí el agente es un asistente de coding —Claude Code, Codex, OpenCode, Cursor— que un desarrollador lanza en su máquina. Un proceso, un usuario, y al lado los activos más jugosos que existen: ~/.aws/credentials, ~/.ssh, ~/.gnupg, el almacén de contraseñas del navegador. El tier que corresponde es el más ligero: el sandbox de proceso.

bubblewrap (Linux) y sandbox-exec (macOS). bubblewrap (bwrap) es el mismo sandbox que usa Flatpak para aislar cada app de escritorio: ~50 KB de binario, ~4.000 líneas de C, mantenido por el equipo de GNOME, y —la propiedad clave— corre sin root vía CLONE_NEWUSER, creando namespaces sin privilegios elevados. Monta $HOME como un tmpfs efímero y solo expone, con escritura, el directorio del proyecto; el resto del sistema se vuelve invisible. En macOS el equivalente es sandbox-exec con perfiles SBPL: API legacy de Apple, oficialmente deprecada y sin reemplazo público, pero funciona hoy. La paridad entre las dos no es exacta —en macOS la GPU (Metal) y el display (Cocoa) son de sistema y sandbox-exec no los restringe—, pero ambas protegen lo que importa: el acceso a las zonas sensibles del filesystem.

Landlock como segunda barrera. bubblewrap aísla por namespaces y montajes; Landlock —un Linux Security Module disponible desde el kernel 5.13— restringe el acceso a nivel VFS, independiente de los namespaces. No reemplaza a bwrap: lo complementa. Cierra vectores que el aislamiento por montaje no cubre por sí solo (rutas de escape vía /proc, trucos con symlinks dentro de montajes permitidos) y actúa de red de seguridad si la maquinaria de namespaces tuviera un bug. Es defensa en profundidad dentro del propio cliente, y degrada limpiamente a no-op en kernels que no lo soportan.

Dev containers, cuando hace falta reproducibilidad. Un dev container (devcontainer.json, lo que usan Codespaces y Cursor) es un contenedor Docker con una capa de configuración encima. Da aislamiento de filesystem razonable y reset fácil (destruir y recrear), pero comparte el kernel del host —misma limitación que cualquier Docker— y tiende a ser de larga vida, acumulando estado. Para un agente que ejecuta código de tu propio equipo, en tu máquina, es un buen relato de repetibilidad; no es la capa de aislamiento para código no confiable por sí solo.

Lo que envuelve todo esto. El script de bash a mano funciona, pero no escala a un equipo. Las herramientas que lo empaquetan:

ai-jail (Rust, GPL-3.0): envuelve bwrap/sandbox-exec con config por proyecto en un fichero .ai-jail (TOML, commiteable al repo, de modo que todo el equipo hereda la misma política), auto-detección de GPU/Docker/display, modo --lockdown (proyecto en read-only, red cortada con --unshare-net, --clearenv), --dry-run para auditar, y --bootstrap para generar las allowlists de permisos de cada agente. Es agnóstico de la herramienta: el mismo binario sirve para Claude, Codex, OpenCode o Crush. Aplica además Landlock automáticamente en kernels 5.13+ como defensa en profundidad.
El /sandbox de Claude Code: desde octubre de 2025, Claude Code trae sandbox propio que usa —exactamente— bubblewrap en Linux y sandbox-exec en macOS. Su Sandboxed Bash aísla los comandos de shell, pero no las herramientas de fichero, los servidores MCP ni los hooks, que corren con los permisos completos del proceso salvo que actives el paquete beta sandbox-runtime, que envuelve el proceso entero. Hay un matiz que conviene conocer: si un comando falla por una restricción, el agente puede reintentar con dangerouslyDisableSandbox —es opt-out, no opt-in—.
Codex CLI: tres modos vía --sandbox (read-only, workspace-write, danger-full-access); el recomendado por defecto es workspace-write. La filosofía es deliberada: Codex no provee el aislamiento, lo delega al entorno que lo envuelve. danger-full-access solo tiene sentido dentro de una microVM.
Cursor: sus cloud agents corren en VMs aisladas; /worktree crea un worktree aislado de un solo uso por tarea, y /best-of-n lanza varios intentos en paralelo en worktrees separados.

El cluster: aislar al agente en producción

El segundo edificio es el centro de datos. Aquí el “agente” puede ser un agente autónomo que corre sin un humano delante, o el propio servicio de inferencia ejecutando código generado, o un workload multi-tenant donde el pod de un cliente no debe tocar los datos de otro. El proceso ya no es uno: son pods en un cluster Kubernetes (RKE2/RKE3 en una plataforma soberana típica). Las primitivas cambian de naturaleza.

El baseline del pod. Antes de nada, lo de serie: namespaces de Linux, seccomp (RuntimeDefault) para recortar la superficie de syscalls, cgroups para los límites de recursos, securityContext sin privilegios (runAsNonRoot, readOnlyRootFilesystem, drop de todas las capabilities) y NetworkPolicy para cortar el egress. Es el equivalente cluster de la allowlist del sandbox de proceso. Necesario, pero comparte kernel con el host: insuficiente para código realmente no confiable.

gVisor (runsc). El kernel en espacio de usuario de Google: intercepta las syscalls del workload antes de que lleguen al kernel del host y las atiende dentro de un kernel Linux reimplementado en Go (el Sentry). La superficie expuesta a vulnerabilidades del kernel del host se reduce drásticamente, manteniendo arranque rápido y footprint bajo. Es el término medio cuando el riesgo de escape de kernel es real pero el overhead de una microVM no es asumible.

microVMs Firecracker / Kata. El estándar de facto para código no confiable en 2026. Firecracker (VMM de AWS en Rust, sobre KVM) da a cada sandbox un kernel Linux dedicado: un exploit de kernel dentro de la microVM no alcanza al host por construcción. Es lo que hay debajo de Vercel Sandbox (GA enero 2026) y E2B. En Kubernetes, Kata Containers trae ese modelo a un RuntimeClass: marcas el pod del agente no confiable con runtimeClassName: kata y se ejecuta en su propia microVM en lugar de compartir el kernel del nodo. Para multi-tenant con código generado, esto es el baseline, no el lujo.

eBPF / Tetragon: la capa que ya tenemos. Aquí está la pieza que distingue una plataforma con observabilidad de runtime de una que solo confía en la configuración. Las capas anteriores son estáticas: definen lo que el pod puede hacer antes de arrancar. Tetragon —el componente de seguridad runtime de Cilium, basado en eBPF— es dinámico: observa, en el kernel y con coste mínimo, cada ejecución de proceso, cada conexión de red y cada apertura de fichero de cada pod, y puede actuar en línea. No reemplaza al sandbox; lo vigila desde dentro del kernel. Donde bubblewrap en el cliente bloquea curl con una blocklist de comandos, Tetragon en el cluster engancha tcp_connect en el kernel y, si el destino no está permitido, mata el proceso con Sigkill antes de que el paquete salga. Donde el cliente esconde ~/.ssh tras un tmpfs, Tetragon engancha security_file_open y reporta —o mata— cualquier intento de leer una ruta sensible montada. Es el guardia que recorre los pasillos mientras las microVMs son las paredes. Y es, exactamente, el tipo de control que materializa las medidas de monitorización y trazabilidad del ENS (op.mon, op.exp) sin instrumentar la aplicación: la visibilidad vive en el kernel, no en el código del agente.

La tabla del panorama

Las cinco familias, su fortaleza relativa de aislamiento, su coste de arranque y el dominio donde viven:

Tier	Primitiva	Aislamiento	Arranque	Dominio natural
Sandbox de proceso	Seatbelt · bubblewrap	Baseline	~0 ms	Cliente (defecto de Claude Code)
Dev container	Docker + seccomp	Moderado	segundos	Cliente / cluster (repetibilidad)
Kernel user-space	gVisor (`runsc`)	Fuerte	ms	Cluster (multi-tenant medio)
microVM	Firecracker · Kata	El más fuerte (práctico)	<1 s	Cluster (código no confiable)
VM completa	KVM · EC2	Máximo	30 s+	Cluster (frontera externa, compliance)
Runtime enforcement	eBPF · Tetragon	Transversal	siempre activo	Cluster (observa+mata sobre cualquier tier)

Tetragon ocupa una fila aparte a propósito: no es un tier en la escalera, es una capa transversal que opera sobre cualquiera de los otros. Se apila con todos.

Un apunte numérico sobre por qué la columna “arranque” decide tanto como la columna “aislamiento”. Una VM completa gana en aislamiento bruto pero tarda decenas de segundos en provisionarse; para un agente que necesita un entorno fresco por petición o por sesión, ese coste es prohibitivo. Una microVM Firecracker arranca en menos de 1 segundo y un sandbox de proceso en ~0 ms. Por eso el patrón dominante en 2026 no es “la VM más aislada”, sino VM completa como frontera externa + microVM como unidad de ejecución por petición dentro —la arquitectura de Vercel, AWS Lambda y E2B—. En el cliente el cálculo es el opuesto: el desarrollador lanza el agente decenas de veces al día de forma interactiva, y un arranque de segundos rompería el flujo; de ahí que el sandbox de proceso, con su overhead de microsegundos, sea el defecto correcto.

Extrapolar, no copiar

La tesis de la pareja de posts cabe en una frase: el modelo de amenaza es invariante entre dominios; la primitiva que lo implementa, no. El cliente y el cluster defienden exactamente los mismos cinco vectores —filesystem, red, kernel, multi-tenant, secretos—, pero con cajas de herramientas que no se solapan. Cada control tiene su gemelo en el otro lado:

$HOME como tmpfs efímero (cliente) ↔ readOnlyRootFilesystem + emptyDir (cluster).
Blocklist de curl/wget en bwrap (cliente) ↔ TracingPolicy sobre tcp_connect en Tetragon + NetworkPolicy (cluster).
--unshare-net en lockdown (cliente) ↔ NetworkPolicy default-deny (cluster).
Sin escape hatch, el proceso vive dentro de bwrap (cliente) ↔ sin privileged, sin hostPath, RuntimeClass kata (cluster).
~/.ssh y ~/.aws nunca montados (cliente) ↔ secretos fuera del pod + Tetragon vigilando security_file_open (cluster).

El runbook hermano convierte cada una de estas equivalencias en ficheros concretos. Lo que importa retener aquí es el método: cuando alguien te enseña un sandbox de agente —sea el /sandbox de Claude Code en un portátil o un microVM en un PaaS—, la pregunta útil no es “¿qué herramienta usa?”, sino “¿cuál de los cinco vectores cierra, y cuál deja abierto?”. La herramienta se sustituye; el mapa de amenazas se queda.

Lo que ningún sandbox resuelve

Tres límites que la propia documentación de Anthropic enuncia, y que conviene tener delante para no vender humo:

El egress sigue siendo un riesgo en cualquier sandbox que permita conexiones salientes. Si el agente puede abrir una conexión, puede exfiltrar. Por eso el lockdown del cliente corta la red y el cluster usa NetworkPolicy default-deny + Tetragon: no se confía en “filtrar bien”, se confía en “no dejar salir”.
La modificación de código sigue siendo posible en cualquier sandbox con el directorio del proyecto montado en escritura. El remedio no es técnico-de-sandbox, es git: con el remoto intacto y sin permiso de push, el peor caso es corromper el working copy local —git checkout . y a empezar—. El daño no llega al remoto.
Ningún sandbox impide que un prompt comprometido llegue a la API. El aislamiento acota el impacto de una inyección; no la previene. Las defensas complementarias —validación de entrada, allowlists de tool-calls, auditoría de salida— son obligatorias junto al aislamiento, no en su lugar.

La conclusión operativa: el aislamiento encoge el radio de explosión; la defensa en profundidad es lo que cierra el círculo. Un sandbox de proceso para código de confianza en una máquina conocida es apropiado y prácticamente gratis. Para un agente que actúa sobre prompts de usuario, ejecuta código generado o corre en multi-tenant, el mínimo aceptable en 2026 es una microVM, con Tetragon observando por encima. Elige el tier que case con tu amenaza real, verifica qué vector deja abierto, y apila controles complementarios encima.

Ver también

Runbook: enjaular al agente de IA — bubblewrap en el cliente, Tetragon en el cluster — el compañero operativo de este post: los ficheros .ai-jail, el --bootstrap de permisos y las TracingPolicy de Tetragon que se copian y pegan. Con comandos.
La puerta de la cocina que el maître no miró: NUMA de red, Cilium eBPF y DRANET — el datapath eBPF de Cilium sobre el que se apoya Tetragon en el cluster; la misma capa de kernel, otro uso.
Guardrails y safety en LLM — la mitigación en el plano del contenido (qué dice y qué se le dice al modelo); este post es la mitigación en el plano de la ejecución (qué puede hacer el proceso del agente).
Controles técnicos: ENS × ISO 42001 × EU AI Act — el marco de cumplimiento que el aislamiento de runtime materializa: Tetragon como evidencia técnica de op.mon/op.exp.
Catálogo de herramientas OSS para LLMOps — dónde encaja la capa de seguridad runtime en el stack abierto completo.

Referencias

bubblewrap: https://github.com/containers/bubblewrap
Landlock LSM: https://landlock.io · https://docs.rs/landlock
ai-jail (Fabio Akita): https://github.com/akitaonrails/ai-jail
gVisor: https://gvisor.dev
Firecracker: https://firecracker-microvm.github.io
Kata Containers: https://katacontainers.io
Tetragon (Cilium): https://tetragon.io
Vercel Sandbox — concepts: https://vercel.com/docs/vercel-sandbox/concepts
E2B: https://github.com/e2b-dev/E2B
Claude Code sandboxing: https://docs.claude.com/en/docs/claude-code
Codex CLI: https://github.com/openai/codex

Runbook QLoRA: del dataset al adapter servido en multi-LoRA (procedimiento operativo)

Tue, 09 Jun 2026 03:00:00 +0000

Este es el compañero operativo de QLoRA y multi-LoRA al límite en modelos pequeños. Aquel post desmonta el porqué —NF4, doble cuantización, paged optimizers, la matemática del adapter—; este es el cómo, con comandos que se copian y pegan. Si no has leído el de fundamentos, léelo antes: aquí damos por sabido qué es un adapter, por qué el base vive en 4-bit y por qué el gradiente solo toca el adapter.

TL;DR

Un procedimiento reproducible en cinco fases: (1) fijar el entorno con versiones pineadas; (2) preparar el dataset en formato chat; (3) entrenar el adapter QLoRA con TRL + PEFT en una RTX 4090 (24 GB, Ada Lovelace) usando gradient checkpointing, gradient accumulation y paged_adamw_8bit; (4) validar y versionar el adapter como artefacto de megabytes; (5) servirlo en vLLM con --enable-lora, cargándolo en caliente sin reiniciar el servidor y resolviéndolo desde almacenamiento de objetos. Todo on-premise, en hardware de consumo, sin sacar un dato del perímetro. Lo que sigue son los comandos exactos y el presupuesto de memoria que separa “cabe” de “OOM”.

El flujo de extremo a extremo

Fase 0 — Entorno y versiones

QLoRA es sensible a las versiones de bitsandbytes, transformers, peft y trl: combinaciones desalineadas dan errores de dequant o adapters que no cargan en vLLM. Fija el entorno y no lo toques a mitad de campaña. Versiones de referencia a junio de 2026 (verifica las concretas de tu índice; el pin exacto importa menos que la coherencia entre ellas):

python -m venv .venv && source .venv/bin/activate
pip install --upgrade pip

# Entrenamiento (productor)
pip install "torch>=2.4" \
 "transformers>=4.50" \
 "peft>=0.14" \
 "trl>=0.15" \
 "bitsandbytes>=0.45" \
 "accelerate>=1.2" \
 "datasets>=3.2"

# Serving (consumidor) — en su propio entorno/imagen
pip install "vllm>=0.8"

Qué hace cada pieza y por qué está pineada:

Paquete	Rol en el flujo	Por qué la versión importa
`torch`	runtime de tensores y kernels CUDA	el ABI de CUDA tiene que casar con el driver y con `bitsandbytes`; un salto mayor rompe los kernels 4-bit.
`transformers`	carga el base, el tokenizer y el `chat_template`	tiene que conocer la arquitectura del SLM que uses; un modelo nuevo necesita una versión que lo soporte.
`peft`	implementa LoRA/QLoRA: inyecta las matrices `A,B` y escribe el `adapter_config.json`	ese `adapter_config.json` es el que vLLM lee al servir; versiones viejas escriben campos que el serving no entiende.
`trl`	el `SFTTrainer`: el bucle de entrenamiento supervisado	integra `peft` de forma nativa; su API (`SFTConfig`) cambia entre versiones, de ahí el pin.
`bitsandbytes`	la cuantización NF4 y el `paged_adamw_8bit`	la pieza más sensible: un binario mal compilado da dequant corrupto o cuelga al primer paso.
`accelerate`	orquesta dispositivo, precisión mixta y `device_map`	backend silencioso de casi todo; desalinearlo con `transformers` da errores crípticos.
`datasets`	carga el JSONL (y permite streaming si el corpus es grande)	poco sensible; cualquier 3.x reciente sirve.
`vllm`	el serving multi-LoRA	entorno o imagen aparte: no mezcles su stack con el `bitsandbytes` de entrenamiento.

La regla de oro: coherencia entre los cuatro de arriba (transformers, peft, trl, bitsandbytes) pesa más que el número exacto de cada uno. Fíjalos al empezar una campaña y no los muevas hasta cerrarla.

Comprueba que la GPU y CUDA están sanos antes de empezar; un bitsandbytes mal compilado se manifiesta tarde:

python -c "import torch, bitsandbytes; print(torch.cuda.get_device_name(0), torch.cuda.is_available())"
nvidia-smi --query-gpu=name,memory.total,driver_version --format=csv

Para 100 % soberanía: descarga el base una vez desde tu mirror interno de Hugging Face (o un MinIO con los pesos) y exporta HF_HOME a un volumen local. Nada de este flujo necesita salir del perímetro.

Fase 1 — Preparar el dataset

El formato canónico para una tarea conversacional es JSONL, una conversación por línea, con la plantilla de chat del modelo. No inventes un formato propio: usa el chat_template del tokenizer del base, porque cualquier desajuste entre cómo entrenas y cómo sirves degrada la calidad de forma silenciosa.

{"messages":[{"role":"system","content":"Eres un asistente de soporte de redes."},{"role":"user","content":"El AP del ala norte no levanta tras el corte."},{"role":"assistant","content":"Confirma primero el PoE del puerto..."}]}
{"messages":[{"role":"user","content":"Genera el cambio de VLAN para el cliente 42."},{"role":"assistant","content":"interface GigabitEthernet0/3\n switchport access vlan 42..."}]}

Qué es cada campo y por qué:

Campo	Qué es	Nota operativa
`messages`	la conversación completa, lista de turnos	una conversación por línea JSONL; es lo que `apply_chat_template` convierte en tokens.
`role`	quién habla: `system`, `user`, `assistant`	el adapter aprende a producir los turnos `assistant`; los `user`/`system` son contexto, no objetivo.
`content`	el texto del turno	el `system` fija la persona/tarea; mantenlo idéntico al que usarás en producción o el adapter se desalinea.

Reglas operativas que ahorran disgustos: cuida la proporción de ejemplos (un dataset de tarea estrecha bien curado de 2.000–20.000 ejemplos rinde más que 200.000 ruidosos), deduplica, y reserva un 5–10 % como split de validación que NO entra en el entrenamiento. La construcción del corpus a partir de señal de producción la cubre Retrain: cerrar el bucle.

Fase 2 — El script de entrenamiento

Script mínimo y completo con TRL + PEFT. Entrena un adapter r=8 sobre un SLM de 8B cuantizado a NF4. Cada bloque tiene su porqué comentado.

# train_qlora.py
import torch
from datasets import load_dataset
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from peft import LoraConfig
from trl import SFTConfig, SFTTrainer

BASE = "Qwen/Qwen3-8B" # o el SLM que sirvas; usa SIEMPRE el mismo en train y serve
OUT = "adapters/soporte-redes-v1"

# 1) Base congelado y cuantizado a 4-bit NF4 con doble cuantización
bnb = BitsAndBytesConfig(
 load_in_4bit=True,
 bnb_4bit_quant_type="nf4", # NormalFloat, cuantil-óptimo para pesos gaussianos
 bnb_4bit_use_double_quant=True, # cuantiza las constantes de escala -> ~0.37 bits/param menos
 bnb_4bit_compute_dtype=torch.bfloat16 # los matmuls se hacen en BF16 tras dequant al vuelo
)

tok = AutoTokenizer.from_pretrained(BASE)
model = AutoModelForCausalLM.from_pretrained(
 BASE, quantization_config=bnb, torch_dtype=torch.bfloat16, device_map={"": 0}
)

# 2) El adapter: rank bajo, solo proyecciones de atención (agresivo). Sube target_modules si el eval lo pide.
peft_cfg = LoraConfig(
 r=8, lora_alpha=16, lora_dropout=0.05, bias="none", task_type="CAUSAL_LM",
 target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
)

ds = load_dataset("json", data_files={"train": "data/train.jsonl",
 "eval": "data/eval.jsonl"})

# 3) Config de entrenamiento pensada para caber en 24 GB
cfg = SFTConfig(
 output_dir=OUT,
 per_device_train_batch_size=1, # batch real pequeño
 gradient_accumulation_steps=16, # batch EFECTIVO = 1*16 = 16, sin pagar su VRAM de golpe
 gradient_checkpointing=True, # recomputa activaciones en backward: cambia compute por memoria
 optim="paged_adamw_8bit", # paged optimizer: el airbag contra los picos de VRAM
 learning_rate=2e-4, lr_scheduler_type="cosine", warmup_ratio=0.03,
 num_train_epochs=3, bf16=True,
 max_length=2048, # acota la secuencia: las activaciones escalan con ella
 logging_steps=10, eval_strategy="steps", eval_steps=100, save_steps=200,
 report_to="none",
)

trainer = SFTTrainer(model=model, args=cfg, peft_config=peft_cfg,
 train_dataset=ds["train"], eval_dataset=ds["eval"],
 processing_class=tok)
trainer.train()
trainer.save_model(OUT) # guarda SOLO el adapter (MB), no el base

`BitsAndBytesConfig` — cómo se cuantiza el base

Opción	Qué hace	Por qué este valor / cuándo cambiarlo
`load_in_4bit=True`	carga los pesos del base en 4-bit	es la base de QLoRA: sin esto el 8B no cabe ni para entrenar.
`bnb_4bit_quant_type="nf4"`	usa el formato NF4 (cuantil-óptimo para pesos gaussianos)	existe `"fp4"`, pero NF4 rinde mejor en pesos de transformer; deja NF4.
`bnb_4bit_use_double_quant=True`	cuantiza las propias constantes de escala	ahorra ~0.37 bits/param (cientos de MB en un 8B); el margen que separa “cabe” de “OOM”. Déjalo en `True`.
`bnb_4bit_compute_dtype=torch.bfloat16`	precisión del matmul tras deshacer la cuantización al vuelo	BF16 en Ada/Hopper (4090, H100); usa `float16` solo en GPUs sin BF16.

`LoraConfig` — la forma del adapter

Opción	Qué hace	Por qué este valor / cuándo cambiarlo
`r=8`	rank del adapter: su capacidad de corrección	4-8 para tarea estrecha (agresivo); súbelo a 16-64 solo si el eval muestra underfitting.
`lora_alpha=16`	factor de escala del delta (efectivo `α/r`)	convención común `α=2r`; modula cuánto “pesa” el adapter sobre el base.
`lora_dropout=0.05`	regularización sobre el adapter	0.05-0.1 con datasets pequeños (evita overfit); 0 si el corpus es grande.
`bias="none"`	no entrena los términos de bias	`"none"` es el estándar; `"all"`/`"lora_only"` rara vez aportan y cuestan params.
`task_type="CAUSAL_LM"`	tipo de objetivo/cabeza	fijo para un LLM generativo.
`target_modules=[q,k,v,o]`	qué matrices reciben adapter	solo atención = barato y agresivo; añade `gate_proj`/`up_proj`/`down_proj` (MLP) si la tarea exige reescribir más comportamiento y el eval lo pide.

`SFTConfig` — el presupuesto de memoria y el bucle

Opción	Qué hace	Por qué este valor / cuándo cambiarlo
`per_device_train_batch_size=1`	microbatch por GPU	1 en 24 GB; el batch real lo construye `gradient_accumulation_steps`.
`gradient_accumulation_steps=16`	acumula 16 microbatches antes de actualizar	batch efectivo = 1×16 = 16 sin pagar su VRAM de golpe; súbelo si bajas la secuencia y quieres más batch efectivo.
`gradient_checkpointing=True`	recomputa activaciones en el backward en vez de guardarlas	imprescindible en 4090: ~20-30 % más lento a cambio de mucha menos VRAM.
`optim="paged_adamw_8bit"`	optimizer Adam en 8-bit + estados paginables a RAM	menos VRAM de estados y el airbag que evita el OOM en los picos.
`learning_rate=2e-4`	tasa de aprendizaje del adapter	1e-4–3e-4 es el rango típico de QLoRA; los adapters toleran LR más alto que un full fine-tune.
`lr_scheduler_type="cosine"`	curva de decaimiento del LR	`cosine` o `linear`; cosine suele dar una bajada suave al final.
`warmup_ratio=0.03`	calienta el LR el primer 3 % de pasos	evita la inestabilidad de los primeros steps.
`num_train_epochs=3`	pasadas completas al dataset	1-3; vigila la eval loss para no sobreajustar.
`bf16=True`	precisión de cómputo y del adapter	BF16 en Ada/Hopper; `fp16=True` si tu GPU no tiene BF16.
`max_length=2048`	longitud máxima de secuencia	la palanca #1 de VRAM de activaciones: acórtala lo primero si hay OOM.
`eval_strategy`/`eval_steps`/`save_steps`	cadencia de validación y checkpoint	ajústalas al tamaño del dataset; evaluar a menudo cuesta tiempo.

Las cuatro piezas que hacen que quepa en una 4090 son: per_device_train_batch_size=1 + gradient_accumulation_steps (batch efectivo grande sin su coste de memoria de golpe), gradient_checkpointing=True (recomputar activaciones en lugar de guardarlas) y optim="paged_adamw_8bit" (paginar estados a RAM en los picos). Quita cualquiera de las tres con secuencias largas y verás el OOM.

Alternativa declarativa con Axolotl si prefieres YAML sobre Python (mismo resultado):

base_model: Qwen/Qwen3-8B
load_in_4bit: true
adapter: qlora
lora_r: 8
lora_alpha: 16
lora_target_modules: [q_proj, k_proj, v_proj, o_proj]
sequence_len: 2048
micro_batch_size: 1
gradient_accumulation_steps: 16
gradient_checkpointing: true
optimizer: paged_adamw_8bit
learning_rate: 0.0002
num_epochs: 3
bf16: true
datasets:
 - path: data/train.jsonl
 type: chat_template

Fase 3 — Lanzar y monitorizar

# Lanzamiento simple en una GPU
python train_qlora.py

# En otra terminal: vigila la VRAM. Si se acerca al techo, baja max_length o sube grad accumulation.
watch -n 2 nvidia-smi --query-gpu=memory.used,memory.total,utilization.gpu --format=csv

Presupuesto aproximado de VRAM al entrenar el 8B en la 4090, y qué tocar cuando aprieta:

Componente	VRAM aprox.	Palanca si hay OOM
Base 8B NF4 (congelado)	~4.0 GB	— (fijo)
Adapter + grad + estados Adam	~0.3–0.7 GB	bajar `r`
Activaciones (batch × secuencia)	~6–14 GB	bajar `max_length`, `batch_size`; subir `grad_accum`
Buffers dequant / workspace	~1–2 GB	—

Tabla de remedios rápidos de OOM, en orden de coste: (1) baja max_length; (2) confirma gradient_checkpointing=True; (3) sube gradient_accumulation_steps y baja per_device_train_batch_size a 1; (4) usa paged_adamw_8bit (ya en el script); (5) como último recurso baja r. Si tras todo eso no cabe, la secuencia o el modelo son demasiado grandes para 24 GB: o acotas, o subes de hardware.

Fase 4 — Validar el adapter

Nunca promociones un adapter por la training loss. Mide contra el split de validación reservado y contra un puñado de prompts reales.

# quick_eval.py
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from peft import PeftModel

bnb = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4",
 bnb_4bit_use_double_quant=True, bnb_4bit_compute_dtype=torch.bfloat16)
tok = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")
base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-8B", quantization_config=bnb, device_map={"": 0})
model = PeftModel.from_pretrained(base, "adapters/soporte-redes-v1") # base + adapter

msgs = [{"role": "user", "content": "El AP del ala norte no levanta tras el corte."}]
ids = tok.apply_chat_template(msgs, add_generation_prompt=True, return_tensors="pt").to(0)
print(tok.decode(model.generate(ids, max_new_tokens=256)[0], skip_special_tokens=True))

Para un veredicto serio, pasa el adapter por tu suite de evals (la capa que describe Evals LLM) y compara contra el base sin adapter y contra la versión anterior del adapter. Promociona solo si gana en la métrica de la tarea sin regresar en seguridad/formato.

Fase 5 — Versionar el adapter como artefacto

El adapter es un par de ficheros de MB (adapter_model.safetensors + adapter_config.json). Trátalo como un artefacto versionado, firmado y trazable, no como un fichero suelto.

# Checksum reproducible + subida a almacenamiento de objetos interno (MinIO/S3)
sha256sum adapters/soporte-redes-v1/adapter_model.safetensors > adapters/soporte-redes-v1/SHA256
aws --endpoint-url https://minio.interno s3 cp \
 adapters/soporte-redes-v1/ s3://adapters/soporte-redes/v1/ --recursive

Convención que funciona: s3://adapters/<tarea-o-cliente>/<version>/. Inmutable por versión, con su SHA256. Borrar un cliente es borrar un prefijo de MB, no reentrenar nada. Versionar 500 adapters cuesta lo que cuesta versionar 500 ficheros de configuración pesados.

Fase 6 — Servir en multi-LoRA con vLLM

El consumidor carga un base compartido y aplica el delta del adapter por request. Arranque con adapters estáticos declarados:

VLLM_ALLOW_RUNTIME_LORA_UPDATING=True \
vllm serve Qwen/Qwen3-8B \
 --enable-lora \
 --max-loras 8 \  # nº máx de adapters DISTINTOS por batch (no el total cargable)
 --max-lora-rank 8 \  # = al rank máximo de tus adapters; no lo infles (gasta memoria)
 --max-cpu-loras 64 \  # adapters cacheados en RAM para swap rápido a VRAM
 --lora-modules soporte-redes=/srv/adapters/soporte-redes/v1

Cada flag, qué controla y cómo dimensionarlo:

Flag / variable	Qué controla	Cómo dimensionarlo
`--enable-lora`	activa el soporte de adapters	obligatorio; sin él, vLLM ignora cualquier `model` que sea un adapter.
`--max-loras 8`	nº de adapters distintos en un mismo batch	más adapters por batch encarece los kernels SGMV; 8-32 es razonable. No es el total cargable.
`--max-lora-rank 8`	rank máximo que el servidor reserva	ponlo igual al rank real de tus adapters (8 aquí); inflarlo desperdicia VRAM y rendimiento.
`--max-cpu-loras 64`	adapters cacheados en RAM listos para paginar a VRAM	≥ nº de adapters activos; es el “banquillo” desde el que se hace swap rápido.
`--lora-modules name=path`	declara adapters estáticos al arrancar	útil para los fijos; omítelo si todo va por carga dinámica/Resolver.
`VLLM_ALLOW_RUNTIME_LORA_UPDATING=True`	habilita los endpoints de carga/descarga en caliente	imprescindible para `/v1/load_lora_adapter`; sin él, el servidor es estático.

--max-loras limita los adapters distintos por batch, no cuántos puedes tener cargados; el grueso vive en CPU (--max-cpu-loras) y se pagina a VRAM bajo demanda. Pon --max-lora-rank al rank real (8 aquí): inflarlo desperdicia memoria y rendimiento. Las peticiones eligen adapter por el campo model:

curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{
 "model": "soporte-redes",
 "messages": [{"role":"user","content":"El AP del ala norte no levanta tras el corte."}]
}'
# model:"Qwen/Qwen3-8B" (sin adapter) usa el base pelado en el mismo servidor

Carga en caliente de un adapter nuevo sin reiniciar (gracias a VLLM_ALLOW_RUNTIME_LORA_UPDATING=True):

curl -X POST http://localhost:8000/v1/load_lora_adapter -H "Content-Type: application/json" -d '{
 "lora_name": "cliente-42",
 "lora_path": "/srv/adapters/cliente-42/v3"
}'
# y para liberar VRAM/CPU cuando un cliente queda inactivo:
curl -X POST http://localhost:8000/v1/unload_lora_adapter -H "Content-Type: application/json" -d '{"lora_name":"cliente-42"}'

Para multi-tenant a escala, evita declarar cientos de adapters a mano: el LoRAResolver resuelve y carga el adapter desde almacenamiento local o S3 la primera vez que llega un model desconocido, así el servidor se mantiene fino y los adapters se traen perezosamente desde tu MinIO. Los internals de cómo se batchean miles de adapters concurrentes (kernels SGMV, unified paging, el gather/scatter heterogéneo) están en Multi-LoRA serving; este runbook solo los enciende. Para exprimir el throughput de decode del base en una 4090, combina esto con lo de Optimizando el decode en vLLM.

Servir multi-adapter vs fusionar por tarea

Dos arquitecturas de despliegue, y el procedimiento cambia:

Servir multi-LoRA (lo de arriba). Un base compartido + N adapters en caliente. Es el patrón soberano por defecto: footprint mínimo, aislamiento por cliente, hot-swap. Usa QLoRA estándar y no fusiones nada.

Fusionar por tarea. Si quieres un único artefacto cuantizado-y-adaptado por tarea (sin adapter en runtime), no fusiones un adapter QLoRA estándar en el base 4-bit: la fusión reintroduce precisión que NF4 no representa y al recuantizar pierdes parte de lo aprendido. Para ese caso entrena con QA-LoRA (quantization-aware), que fusiona limpio sobre un base cuantizado. Es una decisión de arquitectura, no de calidad; el detalle conceptual está en el post de fundamentos.

Checklist de gotchas operativos

Plantilla de chat coherente entre entrenamiento y serving. El desajuste más común y más silencioso: entrenas con un chat_template y sirves con otro. Usa el del base en ambos lados.
Mismo base exacto (revisión incluida) en train y serve. Un adapter entrenado sobre Qwen3-8B no es válido sobre otra revisión del modelo.
--max-lora-rank ≥ rank de TODOS los adapters servidos juntos, pero no más: inflarlo gasta VRAM.
Presupuesto KV vs --max-loras. El cuello en serving no son los adapters (MB), es el KV cache y la concurrencia; mira Roofline invertido para el régimen del SLM.
r demasiado bajo = underfitting si la tarea exige reescribir mucho comportamiento. Sube r solo si el eval lo pide.
No promociones por training loss. Valida contra split reservado + prompts reales + regresión de seguridad.
Versiona e inmutabiliza cada adapter con su SHA256; nunca sobrescribas una versión servida.

Aplicado a la infraestructura on-premise

En una RTX 4090 (24 GB) el mismo equipo es productor y consumidor: entrenas el adapter de un cliente en horas y lo sirves en el mismo servidor sobre el base compartido. Es el caso canónico para demos multi-tenant y prototipos de plataforma.

En un cluster genérico 4×H100 SXM (320 GB, NVLink, FP8 nativo) QLoRA deja de ser necesario para caber, pero sirve para paralelizar la producción (varios jobs de adapter a la vez) y para mantener el formato cuantizado consistente entre entrenamiento y un serving serio de cientos de adapters concurrentes. El base puede ir en FP8 nativo; la mecánica del runbook no cambia, solo la escala.

Ver también

QLoRA y multi-LoRA al límite en modelos pequeños — el post de fundamentos: el porqué de NF4, doble cuantización, paged optimizers y la matemática del adapter. Este runbook es su cara ejecutable.
Multi-LoRA serving — los internals del consumidor que aquí solo encendemos: SGMV, unified paging, batching heterogéneo de miles de adapters.
Optimizando el decode en vLLM — cómo exprimir el throughput de decode del base sobre el que sirves los adapters en una 4090.
Retrain: cerrar el bucle feedback → dataset → adapter — de dónde sale el dataset de la Fase 1.
Evals LLM: la capa después del tracing — cómo validar el adapter de la Fase 4 con criterio, no con la training loss.
Roofline invertido en modelos pequeños — el régimen de rendimiento que explica por qué el cuello del serving es el KV cache, no los adapters.
Cuantización agresiva: del 4-bit al ternario — qué pasa con el base cuantizado por debajo de NF4 bajo el adapter.

Referencias

Dettmers, T., Pagnoni, A., Holtzman, A., Zettlemoyer, L. QLoRA: Efficient Finetuning of Quantized LLMs. NeurIPS 2023. https://arxiv.org/abs/2305.14314
Hugging Face TRL — PEFT integration (SFTTrainer + QLoRA): https://huggingface.co/docs/trl/peft_integration
Hugging Face PEFT: https://github.com/huggingface/peft
bitsandbytes: https://github.com/bitsandbytes-foundation/bitsandbytes
vLLM — LoRA Adapters (serving, carga dinámica, LoRAResolver): https://docs.vllm.ai/en/stable/features/lora/
Axolotl: https://github.com/axolotl-ai-cloud/axolotl
Xu, Y. et al. QA-LoRA: Quantization-Aware Low-Rank Adaptation. ICLR 2024. https://arxiv.org/abs/2309.14717

QLoRA y multi-LoRA al límite en modelos pequeños

Tue, 09 Jun 2026 02:30:00 +0000

Este post es el complemento de entrenamiento de Multi-LoRA serving. Aquel desmonta el consumidor —cómo se sirven cientos de adapters concurrentes con kernels SGMV y unified paging—; este desmonta el productor —cómo se entrena un adapter sobre un base cuantizado en una sola GPU, y por qué el patrón “un SLM base congelado + N adapters de rank bajo” es el encaje natural de los modelos pequeños. Aquí no repetimos los internals del serving; los damos por leídos.

TL;DR

QLoRA (Dettmers et al., NeurIPS 2023) resuelve un problema concreto: fine-tunear un modelo sin tener la VRAM para cargar sus pesos en BF16, sus gradientes y los estados del optimizador. La idea tiene tres piezas. Una: congelar el base y cuantizarlo a 4-bit con un formato nuevo, NF4 (NormalFloat 4-bit), cuantil-óptimo para pesos que se distribuyen casi como una gaussiana. Dos: no entrenar el base —ni un solo peso suyo se mueve—, sino un par de matrices LoRA pequeñas en BF16 enchufadas en paralelo; el gradiente fluye únicamente por ese adapter. Tres: dos trucos de memoria, la doble cuantización (cuantizar las propias constantes de cuantización) y los paged optimizers (estados del optimizador que se paginan a RAM cuando la VRAM aprieta). El resultado operacional medible: un SLM de 3-8B se fine-tunea en una RTX 4090 (24 GB, Ada Lovelace), no en un cluster. Y como el producto del entrenamiento es un adapter de megabytes, no gigabytes, el patrón que emerge es un único SLM base congelado en 4-bit más N adapters —uno por cliente, dominio o tarea—, servidos sobre la base compartida con el stack que ya cubrimos en multi-LoRA serving. Aislamiento por cliente, footprint mínimo, despliegue soberano.

La analogía: la guitarra congelada y la pedalera intercambiable

Piensa en un guitarrista de estudio que graba para clientes muy distintos: un disco de jazz, una sintonía corporativa, un tema de metal. Tiene una sola guitarra —su instrumento de confianza, afinado, con un sonido base que conoce de memoria—. Lo que no hace es comprarse una guitarra nueva para cada canción. Lo que hace es tener una pedalera de efectos: un pedal de distorsión, uno de chorus, uno de delay. Para cada tema enchufa el pedal que toca, y la misma guitarra suena completamente distinta.

El mapeo es exacto:

La guitarra = el SLM base. Una sola copia, afinada de fábrica, congelada. En QLoRA, además, está guardada en una funda comprimida: cuantizada a 4-bit. No la tocas: ni cambias sus pastillas ni reajustas el mástil. Pesa lo que pesa y ahí se queda.
Cada pedal = un adapter LoRA. Pequeño, barato, específico de un sonido. Lo entrenas para una tarea y lo guardas en un cajón.
Entrenar QLoRA = diseñar un pedal nuevo escuchando la guitarra (congelada) a través de él, ajustando solo los potenciómetros del pedal hasta que suene como quieres. El sonido base de la guitarra no se modifica; aprendes la corrección que el pedal aplica encima.
Servir multi-LoRA (Multi-LoRA serving) = tener toda la pedalera montada en el escenario y elegir el pedal correcto por nota —por request—. La guitarra es la misma; lo que cambia entre requests es qué pedal está activo.

La analogía aguanta hasta el detalle que más confunde: el gradiente del entrenamiento solo “toca” el pedal. La guitarra está congelada en su funda comprimida; el aprendizaje no la mueve. Eso es lo que permite que el base viva en 4-bit durante todo el fine-tuning sin que la cuantización estorbe: nunca se le calcula gradiente.

El mecanismo desnudo: LoRA, y por qué se puede entrenar sobre un base 4-bit

Recordatorio mínimo de LoRA (Hu et al., ICLR 2022). Un adapter modifica una matriz W del base sumándole un producto de bajo rango:

$$W’ = W + B A, \qquad A \in \mathbb{R}^{r \times d}, \quad B \in \mathbb{R}^{d \times r}$$

con r el rank, mucho menor que d. En el forward pass no se materializa BA; se calcula:

$$y = W x + B(A x)$$

El cómputo del base (Wx) ocurre igual; el adapter añade dos matmuls baratos. La clave de QLoRA está en quién recibe gradiente. El base W está congelado: ∂L/∂W no se calcula ni se almacena. Solo A y B son entrenables. Por eso W puede vivir cuantizado a 4-bit sin problema: en el forward se deshace la cuantización al vuelo para hacer Wx (dequant → matmul en BF16), pero como W nunca se actualiza, no necesita la precisión de un peso entrenable. El adapter A, B sí está en BF16, y es el único camino por el que fluye el gradiente.

Esto es lo que rompe el muro de memoria. En un fine-tuning completo necesitas, por cada peso: el peso (2 bytes BF16), su gradiente (2 bytes), y los dos estados de Adam (momento y varianza, típicamente 4+4 bytes en FP32) — del orden de 12-16 bytes por parámetro entrenable. Con QLoRA, los pesos del base ocupan 0.5 bytes (4-bit) y no tienen ni gradiente ni estados de optimizador. Solo los pocos millones de parámetros del adapter pagan el coste de 16 bytes. Para un 8B, eso es la diferencia entre ~130 GB y caber en 24 GB.

NF4: por qué un formato nuevo en lugar de INT4

QLoRA no usa INT4 lineal para el base, sino NF4 (NormalFloat 4-bit). La intuición: los pesos de un transformer entrenado se distribuyen, empíricamente, muy cerca de una gaussiana centrada en cero. INT4 reparte sus 16 niveles de forma uniforme en el rango, lo que desperdicia niveles en las colas (donde casi no hay pesos) y deja pocos en el centro (donde se amontonan). NF4 reparte los 16 niveles según los cuantiles de una normal: más niveles donde hay más masa de probabilidad. Es, por construcción, information-theoretically optimal para datos exactamente gaussianos —cada nivel cubre aproximadamente la misma cantidad de pesos—. Además es simétrico respecto al cero y garantiza una representación exacta del 0 (importante para sparsity y padding). El detalle de los formatos de cuantización está en Quantization para inferencia LLM; aquí basta con la idea de que NF4 gasta sus bits donde están los pesos.

Doble cuantización y paged optimizers

Cuantizar a 4-bit no es gratis del todo: necesitas guardar, por cada bloque de pesos (típicamente 64), una constante de escala en FP32 para poder deshacer la cuantización. Esas constantes pesan. Con bloques de 64 y una escala FP32 (32 bits) por bloque, son 32/64 = 0.5 bits por parámetro solo en metadatos — un 12.5 % de overhead sobre los 4 bits útiles. La doble cuantización ataca eso: cuantiza las propias constantes de escala (a 8-bit, en bloques de 256), bajando el overhead a ~0.127 bits/param. Cuantizar la cuantización suena recursivo y lo es; el ahorro es pequeño en términos absolutos (~0.37 bits/param) pero en un 8B son cientos de MB, que es exactamente el margen que separa “cabe” de “no cabe” en una 4090.

Los paged optimizers atacan los picos de memoria. Durante el entrenamiento, ciertos momentos —un batch con secuencia muy larga, una activación grande— hacen que la VRAM se acerque al límite y reviente con un OOM. La idea, prestada del paging de los sistemas operativos, es alojar los estados del optimizador en memoria unificada NVIDIA: cuando la VRAM aprieta, esas páginas se expulsan a la RAM del host automáticamente y se traen de vuelta cuando hacen falta. No acelera nada; evita el crash en los picos. Convierte un “OOM intermitente” en “un poco más lento en los peores momentos”, que para un entrenamiento desatendido en una sola GPU es la diferencia entre terminar y no terminar.

Forward (azul) hacia delante · Gradiente (rojo) solo por el adapter

x entrada W · x (base congelado) NF4 4-bit · dequant al vuelo · SIN gradiente Adapter LoRA (BF16) A: r×d shrink d→r B: d×r expand r→d + suma y salida ∂L/∂A , ∂L/∂B — el gradiente solo entra al adapter el base NO recibe gradiente: por eso puede vivir en 4-bit

Entrenamiento “agresivo”: rank muy bajo y QA-LoRA

“Agresivo” en este contexto significa dos cosas, a veces combinadas.

Rank muy bajo (r = 4-8). El rank es el cuello de la corrección: cuánta “capacidad” tiene el adapter para desviar al base. Un rank alto (64, 128) acerca el adapter a un fine-tuning completo pero pesa más y tarda más en entrenar. Para un SLM adaptado a una tarea estrecha y bien definida —un formato de salida, un dominio léxico, un estilo de respuesta—, un rank de 4-8 suele bastar, y el adapter resultante pesa una fracción. El riesgo del rank bajo es el underfitting: si la tarea exige reescribir mucho comportamiento del base, r=4 se queda corto. La regla honesta es empírica: sube el rank solo si el eval lo pide, no “por si acaso”. En SLMs pequeños, donde la base tiene menos capacidad de sobra, el rank bajo tiende a funcionar mejor proporcionalmente que en modelos grandes, pero esto depende de la tarea y hay que medirlo, no asumirlo.

QA-LoRA (quantization-aware LoRA, Xu et al., arXiv:2309.14717). Hay una fricción sutil en QLoRA estándar: entrenas el adapter en BF16 contra un base 4-bit, pero si luego quieres fusionar el adapter en el base (W' = W + BA) para servir un modelo cuantizado limpio, la fusión reintroduce precisión que el formato 4-bit no puede representar, y al recuantizar pierdes parte de lo aprendido. QA-LoRA entrena el adapter siendo consciente de la cuantización del destino: equilibra los grados de libertad de la cuantización y de la adaptación (con cuantización por grupos) de modo que, al terminar, el adapter se fusiona limpio en un base cuantizado sin un paso de recuantización que degrade. El resultado es un modelo final cuantizado-más-adaptado, sin adapter separado en runtime, útil cuando quieres un único artefacto desplegable por tarea en lugar del patrón base-compartido + adapters. La elección entre “QLoRA + servir multi-adapter” y “QA-LoRA + fusionar por tarea” es una decisión de arquitectura de despliegue, no de calidad pura.

La matemática que importa

Tres cuentas mueven cualquier decisión con QLoRA sobre SLMs.

Parámetros del adapter. Para cada matriz objetivo de dimensión d con rank r, el adapter aporta A (r×d) más B (d×r), es decir 2·r·d parámetros. Sumando sobre las matrices objetivo y multiplicando por el número de capas:

$$\text{params}{\text{adapter}} = L \cdot \sum{\text{matrices}} 2 \cdot r \cdot d$$

Ejemplo trabajado — Llama-3-8B, atención (q, k, v, o), d = 4096, L = 32 capas, r = 8. Tomando las cuatro proyecciones de atención con la misma d = 4096 (simplificación; en Llama-3 K y V son más estrechas por GQA, lo que da menos params aún):

$$\text{params} \approx 32 \cdot 4 \cdot (2 \cdot 8 \cdot 4096) = 32 \cdot 4 \cdot 65,536 \approx 8.4\text{M params}$$

En BF16 (2 bytes/param): 8.4M · 2 ≈ 16.8 MB ≈ ~17 MB. Diecisiete megabytes. Compáralo con el base: un 8B en NF4 ocupa 8\text{G} · 0.5\,\text{bytes} ≈ 4\text{ GB} (más el pequeño overhead de constantes tras doble cuantización). El adapter es el 0.4 % del tamaño del base cuantizado. Esto es lo que hace operacionalmente trivial tener cientos: un adapter no es un modelo, es casi un fichero de configuración pesado.

¿Cuántos adapters caben en una 4090 tras el base + KV? Presupuesto de una RTX 4090 (24 GB): base 8B NF4 ~4 GB, dejemos ~5 GB para KV cache y activaciones de inferencia con concurrencia moderada → quedan ~15 GB libres (siendo conservadores, llamémoslos ~12-15 GB). Con adapters de ~17 MB (r=8, attention-only):

$$\frac{15,000\ \text{MB}}{17\ \text{MB/adapter}} \approx 880 \text{ adapters}$$

Del orden de miles si bajas el KV cache reservado o usas rank 4 (~8.5 MB/adapter → ~1750 en 15 GB). El cuello de botella nunca es el espacio de los adapters; es el KV cache y la concurrencia. Para los detalles de cómo se sirven concurrentemente esos miles —el batching heterogéneo, el unified paging, los kernels SGMV— ver Multi-LoRA serving. El resumen relevante aquí: el compute del adapter es casi gratis (rango bajo, dos matmuls finos); el reto de rendimiento del serving no es ese compute sino el gather/scatter de los adapters correctos por fila del batch cuando un mismo batch mezcla requests de adapters distintos. Eso es problema del consumidor, no del productor.

VRAM de entrenamiento QLoRA en 24 GB. El presupuesto aproximado para fine-tunear el 8B en una 4090:

Componente	VRAM aprox.
Base 8B en NF4 (pesos congelados)	~4.0 GB
Adapter (params BF16 + gradiente + estados Adam, ~16 B/param sobre ~8-40M params)	~0.3-0.7 GB
Activaciones (depende de batch y longitud de secuencia; el grueso variable)	~6-14 GB
Buffers de dequant, escalas, workspace	~1-2 GB
Total	cabe en 24 GB con margen

La pieza grande y variable son las activaciones, que escalan con batch × longitud de secuencia. Por eso el QLoRA real en una 4090 se hace con batch pequeño + gradient accumulation (simular batch grande acumulando gradientes de microbatches) + gradient checkpointing (recomputar activaciones en backward en lugar de guardarlas, cambiando compute por memoria) + secuencias acotadas. Los paged optimizers son el airbag para los picos de activación que, sin ellos, reventarían. La afirmación “QLoRA fine-tunea un 8B en una 4090” es cierta con esa configuración; sin gradient checkpointing y con secuencias largas y batch grande, no cabe. Como con cualquier número, la metodología importa más que el titular.

Batch heterogéneo: 4 requests, 3 clientes, 3 adapters — un solo SLM base compartido

req_1 → cliente A req_2 → cliente A req_3 → cliente B req_4 → cliente C SLM BASE — Llama-3-8B NF4 (~4 GB) — cargado UNA vez, compartido W·x se calcula igual para los 4 requests, sin importar el adapter

Pedalera (adapters ~17 MB) adapter A (cliente A) adapter B (cliente B) adapter C (cliente C) … miles más, MB cada uno

El delta del adapter se aplica por fila del batch: reqs 1-2 → adapter A · req 3 → adapter B · req 4 → adapter C El reto NO es el compute del delta (casi gratis) — es el gather/scatter heterogéneo. Internals (SGMV, unified paging, batching heterogéneo): ver Multi-LoRA serving.

El encaje con modelos pequeños y la soberanía

Aquí es donde QLoRA + SLM deja de ser un truco de VRAM y se vuelve un patrón de arquitectura.

Un SLM (3-8B) ya cabe holgado en una sola GPU para inferencia. Si encima el base vive en 4-bit (~4 GB para un 8B), te sobra memoria. Lo que QLoRA habilita es que ese mismo equipo —la 4090— sea tanto el productor como el consumidor: entrenas el adapter de un cliente nuevo en horas, en la misma clase de hardware donde luego lo sirves. El artefacto que circula entre “entrenar” y “desplegar” es un adapter de MB, no GB: se versiona, se firma, se mueve por la red, se almacena en MinIO/S3 sin pensar en el coste.

El patrón soberano se cae por su propio peso:

Aislamiento por cliente. Cada cliente tiene su adapter, entrenado solo con sus datos. El base es genérico y compartido; lo específico del cliente vive aislado en su par (A, B). Borrar un cliente es borrar un fichero de MB, no reentrenar nada.
Footprint mínimo. Un base + N adapters cabe donde N bases no cabrían ni de lejos. La economía de “un modelo por cliente” (decenas de GB cada uno) es prohibitiva; la de “un base + adapters” (MB cada uno) es trivial. Es exactamente la diferencia entre la pedalera y comprar una guitarra por canción.
Despliegue soberano. Todo cabe on-premise, en tu hardware, sin sacar un dato del perímetro. El entrenamiento (QLoRA en la 4090) y el serving (multi-LoRA sobre el mismo base) viven dentro. No hay dependencia de una API externa para fine-tunear ni para servir.

La elección de adaptar por dominio (un adapter por área de conocimiento) frente a recuperar por contexto (RAG que inyecta el conocimiento en el prompt) es real y no excluyente: el adapter cambia el comportamiento y el estilo del modelo, el RAG cambia los hechos a los que accede. Lo trabaja el post hermano de RAG agresivo en modelos pequeños de esta serie; la regla corta es: adapta lo que es estable y conductual, recupera lo que es volátil y factual.

Aplicado a la infraestructura on-premise

En una RTX 4090 (24 GB, Ada Lovelace)

Es el banco de trabajo natural de QLoRA. Caso canónico: base SLM 3-8B en NF4, fine-tuning de un adapter r=8 attention-only, con gradient checkpointing + gradient accumulation + paged optimizer. Entrena en horas para datasets de tarea estrecha (miles a decenas de miles de ejemplos), y el mismo equipo sirve después el base + decenas o cientos de adapters para demos multi-tenant y prototipos de plataforma. La 4090 es donde QLoRA pasó de “técnica de paper” a “lo puede hacer cualquiera con una GPU de consumo”, y ese es exactamente su valor. La regla honesta: cabe con la configuración de memoria descrita; con secuencias largas, batch grande o rank alto, sube el hardware.

En un cluster genérico 4×H100 SXM (320 GB, NVLink, FP8 nativo)

Aquí QLoRA deja de ser estrictamente necesario para caber —un 8B en BF16 entra de sobra— pero sigue siendo útil por otra razón: paralelizar la producción de adapters. Con 320 GB y FP8 nativo puedes entrenar varios adapters a la vez (un job por cliente, varios en paralelo), o fine-tunear modelos algo mayores con QLoRA sin TP. El consumidor en este cluster es el setup serio de Multi-LoRA serving: base FP8 + cientos de adapters concurrentes. La regla de pulgar: en la 4090, QLoRA es la herramienta para poder fine-tunear; en el cluster H100, es la herramienta para fine-tunear muchos a la vez, barato, manteniendo el formato cuantizado consistente entre entrenamiento y serving.

Lo que no hemos cubierto

Los internals del serving heterogéneo (kernels SGMV, MBGMM/MBGMV, unified paging, cold start, eviction): están enteros en Multi-LoRA serving. Este post es deliberadamente el lado del productor.
DoRA y variantes (descomposición magnitud-dirección): cierran parte del gap con el full fine-tuning; patrón de entrenamiento distinto, patrón de serving idéntico.
Cuantización sub-4-bit y ternaria del base: qué pasa cuando el base baja de NF4 a 2-bit o ternario bajo el adapter; lo trabaja el post hermano de la serie.
Recolección del dataset de fine-tuning: cómo se construye el corpus de cada adapter a partir de feedback de producción está en Retrain: cerrar el bucle.

Ver también

Runbook QLoRA: del dataset al adapter servido — el compañero operativo de este post: el procedimiento ejecutable paso a paso (entorno, script TRL/PEFT, monitorización, versionado y serving en vLLM con carga en caliente). Con comandos.
Multi-LoRA serving — el consumidor: los internals de cómo se sirven miles de adapters concurrentes (SGMV, unified paging, batching heterogéneo). Léelo: este post da por sabido todo lo de serving.
Quantization para inferencia LLM — el marco de formatos (NF4, INT4, FP8, AWQ) que sostiene el base cuantizado bajo el adapter.
Knowledge distillation — la alternativa/complemento a adaptar: comprimir el conocimiento en el propio modelo en lugar de en un adapter encima.
Fine-tuning continuo en producción — el ciclo operacional que produce adapters nuevos de forma continua a partir de señal de producción.
Retrain: cerrar el bucle feedback → dataset → adapter — de dónde sale el dataset con el que se entrena cada adapter QLoRA.
Roofline invertido en modelos pequeños (hermano de la serie) — el régimen de rendimiento donde un SLM se mueve, que explica por qué el footprint mínimo del adapter encaja con GPUs de consumo.
Cuantización agresiva sub-4-bit / ternaria (hermano de la serie) — qué pasa con el base cuantizado por debajo de NF4 bajo el adapter.
RAG agresivo en modelos pequeños (hermano de la serie) — adaptar por dominio (este post) frente a recuperar por contexto; cuándo cada uno.

Referencias

Dettmers, T., Pagnoni, A., Holtzman, A., Zettlemoyer, L. QLoRA: Efficient Finetuning of Quantized LLMs. NeurIPS 2023. https://arxiv.org/abs/2305.14314
Hu, E., Shen, Y., Wallis, P., Allen-Zhu, Z., Li, Y., Wang, S., Wang, L., Chen, W. LoRA: Low-Rank Adaptation of Large Language Models. ICLR 2022. https://arxiv.org/abs/2106.09685
Xu, Y., Xie, L., Gu, X., Chen, X., Chang, H., Zhang, H., Chen, Z., Zhang, X., Tian, Q. QA-LoRA: Quantization-Aware Low-Rank Adaptation of Large Language Models. ICLR 2024. https://arxiv.org/abs/2309.14717
Sheng, Y. et al. S-LoRA: Serving Thousands of Concurrent LoRA Adapters. MLSys 2024. https://arxiv.org/abs/2311.03285
Chen, L. et al. Punica: Multi-Tenant LoRA Serving. MLSys 2024. https://arxiv.org/abs/2310.18547
Repo oficial QLoRA / bitsandbytes: https://github.com/artidoro/qlora
Hugging Face PEFT (LoRA, QLoRA): https://github.com/huggingface/peft

RAG agresivo en modelos pequeños: compensar parámetros con recuperación

Tue, 09 Jun 2026 02:20:00 +0000

Este post pertenece a la serie sobre rendimiento de inferencia en modelos pequeños. Su pieza hermana, El roofline se invierte en modelos pequeños, explica por qué el prefill compute-bound es el cuello de botella que aquí da forma a toda la discusión. Conviene leerlo antes: aquí asumimos que meter más contexto no es gratis.

TL;DR

Un SLM (digamos 1B–8B de parámetros) sabe menos hechos que un modelo de 70B–700B, simplemente porque tiene menos pesos donde memorizarlos. Pero su capacidad de razonar sobre texto que tiene delante —seguir instrucciones, extraer, sintetizar, comparar— se degrada mucho menos con el tamaño que su conocimiento enciclopédico. La consecuencia operacional es directa: usa el SLM como motor de razonamiento sobre contexto curado, no como base de datos. Mueve el conocimiento de los pesos al contexto vía recuperación. El problema es que “recuperación agresiva” se interpreta a menudo como “meter muchos chunks”, y eso choca de frente con tres hechos sobre los SLM: ventanas de contexto más cortas, peor aprovechamiento del contexto largo (el efecto lost in the middle es más severo cuanto más pequeño el modelo) y un prefill compute-bound cuyo coste crece con la longitud del contexto $C$ —lineal en las proyecciones, cuadrático en la atención—. No puedes simplemente añadir tokens. La salida no es recuperar menos, sino recuperar mejor: reranking de precisión sobre recall, compresión de contexto antes de inyectarlo, prefix caching de los documentos estables, caché semántico de respuestas y structured output con herramientas externas que sustituyen al conocimiento interno. Este post trabaja las matemáticas y da un número de TTFT antes y después de comprimir un contexto de 4000 a 1000 tokens en una RTX 4090.

La analogía: el examen a libro abierto

Dos estudiantes se presentan al mismo examen. El primero tiene una memoria prodigiosa: ha memorizado el temario entero, párrafo a párrafo. El segundo tiene una memoria normal —olvida fechas, confunde nombres— pero le permiten entrar con una chuleta.

Si la chuleta del segundo estudiante es un caos de fotocopias amontonadas, pierde: tarda en encontrar lo que busca, se distrae con páginas irrelevantes y se le acaba el tiempo. Pero si su chuleta es excelente —recortada a lo esencial, reordenada por relevancia, con lo importante arriba y sin paja—, entonces no solo no pierde: a menudo gana, porque razona igual de bien que el primero y además trabaja sobre material verificado en lugar de sobre recuerdos borrosos que puede estar inventando.

La moraleja tiene tres capas, y cada una mapea a una decisión de ingeniería:

Memorizarlo todo es caro. El primer estudiante invirtió meses. Un modelo grande invierte parámetros —y VRAM, y FLOPs de inferencia— en memorizar hechos.
La chuleta importa más que su tamaño. Una chuleta de una página bien hecha bate a diez páginas mal organizadas. Más contexto recuperado no es mejor contexto: la precisión del material gana al volumen.
Saber buscar y sintetizar es una habilidad distinta de saber. Es la que el SLM conserva. La estrategia entera consiste en apoyarse en esa habilidad y subcontratar la memoria.

El resto del post es, esencialmente, cómo construir una chuleta excelente bajo la restricción de que el estudiante (el SLM) lee despacio y se cansa con los textos largos.

El argumento de capacidad: cuántos hechos caben en los pesos

Empecemos por justificar la tesis con orden de magnitud, no con fe. ¿Cuánto conocimiento factual cabe realmente en los pesos de un modelo?

Hay una estimación empírica recurrente en la literatura de interpretabilidad y memorización: un modelo denso es capaz de almacenar del orden de 2 bits de información memorizada por parámetro antes de saturar (la cifra exacta varía según el estudio y el régimen de entrenamiento; tómese como orden de magnitud, no como ley). Un modelo de 8B parámetros tiene entonces un techo de almacenamiento de información del orden de:

$$8 \times 10^9 \text{ params} \times 2 \text{ bits/param} = 1.6 \times 10^{10} \text{ bits} \approx 2 \text{ GB de información}$$

Y ese presupuesto no es solo para hechos: la inmensa mayoría se gasta en gramática, sintaxis, capacidad de razonamiento, código, formato, y solo una fracción queda para conocimiento enciclopédico. Compáralo con el otro lado: un corpus recuperable de varios millones de documentos —una wiki corporativa, un repositorio documental, una base de conocimiento técnica— ocupa fácilmente cientos de GB a terabytes de texto, indexado y consultable con latencia de milisegundos. La asimetría es de dos o tres órdenes de magnitud a favor del corpus externo.

La conclusión no es que los pesos sean inútiles —son donde vive el razonamiento, que es lo caro de replicar— sino que competir con un índice externo por capacidad de hechos es perder por construcción. Un modelo de 70B tiene ~9× más presupuesto de memorización que uno de 8B, pero sigue siendo despreciable frente al corpus. Por eso el modelo grande también hace RAG en producción. La diferencia es que el SLM lo necesita: sin recuperación, su conocimiento factual es demasiado escaso y, peor, propenso a alucinar justo en los huecos que no memorizó.

En los pesos (memorizado) ~2 GB de info útil en 8B fijo, caro de actualizar, alucina en huecos

En el contexto (recuperado) cientos de GB – TB indexados fresco, citable, verificable, sin reentrenar

El SLM como motor de razonamiento razona sobre el contexto curado no es la base de datos: es quien la lee y sintetiza

La tensión central: recuperar más no es meter más

Aquí es donde la mayoría de los diseños ingenuos se rompen. “Recuperación agresiva” suena a top-k grande: si recuperar ayuda, recupera 20 chunks en vez de 5. Pero en un SLM eso falla por dos razones independientes, una de calidad y otra de coste.

(a) Los SLM usan peor el contexto largo

El efecto lost in the middle (Liu et al., 2023) es bien conocido: los LLM recuperan mejor la información situada al principio y al final del contexto, y peor la del medio. Lo que se enfatiza menos es que el efecto es más severo cuanto más pequeño el modelo. Un SLM tiene menos cabezas de atención, menos capas y representaciones internas más pobres para “rastrear” un hecho relevante enterrado en la posición 14 de 20 chunks. Además, su ventana de contexto nominal suele ser más corta (4K–32K frente a los 128K+ de los grandes), y la ventana efectiva —la longitud a partir de la cual la calidad se desploma— es todavía menor. Meter 20 chunks no significa que el modelo los lea los 20: significa que probablemente ignore o malinterprete los del medio, mientras paga el coste de todos.

(b) El prefill crece con el contexto y es compute-bound

Este es el golpe que la gente subestima. El prefill —procesar el prompt completo antes de emitir el primer token— es la fase compute-bound de la inferencia (a diferencia del decode, memory-bound; el detalle vive en El roofline se invierte). Su coste crece con la longitud del contexto $C$, y determina el TTFT (time to first token). Más chunks → más tokens de prefill → más TTFT y más coste de cómputo por petición. En un SLM, donde el prefill es proporcionalmente más caro respecto al modelo, esto duele especialmente.

La conclusión operacional es incómoda pero clara: no puedes compensar menos parámetros simplemente metiendo más contexto. Cada token recuperado se paga dos veces —en calidad degradada y en TTFT— y el SLM es el peor situado para absorber ambos costes. La salida es recuperar menos pero mejor, y comprimir lo que recuperas.

Las matemáticas del prefill

Pongamos números a “el prefill crece con el contexto”. Para un contexto de $C$ tokens, una capa transformer hace dos clases de trabajo:

Proyecciones lineales (QKV, salida de atención, FFN): cada token se multiplica por matrices de pesos de tamaño fijo. El coste es $O(C)$ en FLOPs —lineal en el número de tokens.
Atención ($QK^\top$ y la multiplicación por $V$): cada token atiende a todos los demás. El coste es $O(C^2)$ —cuadrático en el número de tokens.

El coste total de prefill por capa es de la forma:

$$\text{FLOPs}{\text{prefill}} \approx \underbrace{a \cdot C}{\text{proyecciones}} + \underbrace{b \cdot C^2}_{\text{atención}}$$

con $a$ y $b$ constantes que dependen de la dimensión del modelo. Para contextos moderados (unos pocos miles de tokens) en un SLM, el término lineal aún domina o es comparable al cuadrático; el término cuadrático se vuelve dominante a contextos largos. Lo relevante: si comprimes el contexto $C \to C/k$, el término lineal cae $\times k$ y el cuadrático cae $\times k^2$. Comprimir es la única palanca que ataca ambos términos a la vez, y ataca el peor de forma desproporcionada.

Ejemplo numérico: TTFT antes y después de comprimir, RTX 4090

Modelemos el TTFT como el tiempo de procesar los tokens de prefill a un throughput de prefill dado. Tomemos una RTX 4090 (24 GB, Ada Lovelace) sirviendo un SLM cuantizado, con un throughput de prefill de ~5000 tok/s (cifra ilustrativa; el valor real depende del modelo, la cuantización y el batch —mídelo, no lo asumas).

Sea un contexto recuperado de 4000 tokens (8 chunks de ~500 tokens). Aproximando el TTFT como dominado por el prefill del contexto:

$$\text{TTFT}_{\text{antes}} \approx \frac{4000 \text{ tok}}{5000 \text{ tok/s}} = 0.80 \text{ s}$$

Ahora comprimimos ese contexto a 1000 tokens ($k = 4$). El throughput de prefill no es constante con $C$ —baja un poco a contextos largos por el término cuadrático— pero, tomando la aproximación lineal conservadora de tokens/throughput:

$$\text{TTFT}_{\text{después}} \approx \frac{1000 \text{ tok}}{5000 \text{ tok/s}} = 0.20 \text{ s}$$

El TTFT cae de 0.80 s a 0.20 s, una reducción de $4\times$ en la parte lineal. Pero la cuenta de FLOPs es más favorable todavía en la componente de atención: esa parte del trabajo cae $\sim k^2 = 16\times$. En la práctica el TTFT total no cae 16× porque el coste no es puramente cuadrático a esta escala, pero la reducción real está entre 4× y un valor mayor según cuánto pesara la atención, y el ahorro de cómputo agregado (lo que paga la factura eléctrica y libera la GPU para otra petición) es sustancialmente mayor que el simple 4× del recuento de tokens.

El argumento se generaliza: comprimir el contexto un factor $k$ reduce el TTFT al menos $\sim k\times$ y el coste de atención $\sim k^2\times$. Para un SLM, donde el TTFT es a menudo el SLA que importa, esto es la diferencia entre un asistente que responde al instante y uno que se siente lento.

Las cinco palancas para resolver la tensión

La estrategia no es “recuperar menos y conformarse”. Es recuperar agresivamente del índice y luego destilar agresivamente lo recuperado antes de que llegue al SLM. Cinco palancas, en orden de aplicación dentro del pipeline.

1. Reranking agresivo: precisión sobre recall

El retriever inicial (denso, sparse o híbrido) optimiza recall: trae 50–100 candidatos para no dejarse nada fuera. El reranker —un cross-encoder que ve la query y el documento juntos— optimiza precisión: reordena esos candidatos y te quedas con los 3–5 mejores. Para un SLM esto no es un lujo, es estructural: como el modelo usa mal el contexto largo, cada chunk que entra debe ganarse su sitio. Mejor 4 chunks de altísima relevancia que 15 mediocres. El detalle de retrieval híbrido y reranking está en Reranking e hybrid retrieval; aquí basta con la regla: maximiza recall en el retriever, maximiza precisión en el reranker, e inyecta pocos.

2. Compresión de contexto: destilar la chuleta

Una vez tienes los mejores chunks, todavía contienen paja —frases de relleno, redundancia, contexto irrelevante a la query concreta. La compresión de contexto los recorta antes de inyectarlos:

Compresión extractiva (estilo LLMLingua / LongLLMLingua, Jiang et al. 2023): un modelo pequeño puntúa la perplejidad o relevancia de cada token/frase respecto a la query y elimina los de baja información, quedándose con el subconjunto extractivo más denso. Reduce tokens sin un segundo modelo generativo grande de por medio. LongLLMLingua añade reordenación consciente de la posición para mitigar lost in the middle.
Compresión abstractiva: un modelo resume los chunks recuperados en un texto más corto. Más agresiva en reducción de tokens, pero introduce un paso generativo (coste y posible pérdida de fidelidad).
Soft prompts / context distillation: comprimir el contexto recuperado no a texto, sino a un puñado de embeddings/soft tokens que el modelo consume directamente. Reduce el número de tokens de prefill al mínimo, a costa de un componente entrenado y específico del modelo.

El punto clave conecta con las matemáticas de arriba: comprimir lo recuperado un factor $k$ reduce los tokens de prefill $\times k$, y por tanto el TTFT $\sim\times k$ y el coste de atención $\sim\times k^2$. Es la palanca con mejor retorno cuando el contexto largo es el cuello de botella.

3. Prefix caching del contexto estable

No todo el contexto cambia entre peticiones. Instrucciones de sistema, definiciones, documentos de referencia recurrentes, esquemas: son prefijos estables. El prefix caching guarda el KV cache ya computado de esos prefijos y lo reutiliza, de modo que el prefill solo procesa la parte nueva (la query y los chunks específicos). Si el 60 % de tu contexto es estable, te ahorras el 60 % del prefill de ese segmento en cada hit. Para que funcione, el contexto estable debe ir al principio del prompt (el KV cache es prefijo-dependiente) y conviene maximizar el hit rate; el detalle de ingeniería de hit rate está en Prefix cache hit rate. Combina especialmente bien con RAG: documentos recuperados que se repiten entre sesiones se cachean una vez.

4. Caché semántico de respuestas

Una capa por delante del modelo: si una query es semánticamente equivalente a una respondida antes (similitud de embeddings por encima de un umbral), devuelve la respuesta cacheada y sáltate el modelo entero —retrieval, prefill y decode incluidos. En cargas reales con colas largas de preguntas repetidas o casi-repetidas (FAQ, soporte), el ahorro es enorme porque elimina el coste completo, no solo el de prefill. La trampa es el umbral: demasiado laxo y sirves respuestas equivocadas a preguntas parecidas-pero-distintas. El diseño está en Caché semántico para RAG.

5. Structured output y function calling: apoyarse en herramientas, no en memoria

La última palanca cambia de qué depende el SLM. En lugar de pedirle que sepa un dato (su punto débil), haz que llame a una herramienta que lo sabe: una consulta a base de datos, una API, una calculadora, un validador. El structured output (forzar JSON conforme a un esquema) y el function calling convierten al SLM en un orquestador que extrae argumentos del contexto y delega el cálculo o la consulta. Un SLM razonablemente capaz emite un tool call bien formado mucho más fiablemente de lo que recuerda un hecho concreto. Esto reduce la presión sobre el conocimiento paramétrico y sobre la recuperación: para datos estructurados y frescos (precios, inventario, estados), consultar bate a recuperar texto y a memorizar. Los fundamentos están en Structured output y Function calling.

El pipeline completo

Las cinco palancas no son alternativas: se encadenan. El flujo, con el contador de tokens cayendo en cada paso:

Recuperar agresivo, destilar agresivo, razonar barato

Retriever híbrido, recall ~80 chunks Reranker precisión 5 chunks · 4000 tok Compresión extractiva k=4 1000 tok Prefix cache + caché semántico prefill mínimo SLM razona + tool calls respuesta

El contador de tokens de prefill cae a lo largo del pipeline retrieve: mucho rerank: 4000 tok 1000

TTFT en RTX 4090 a ~5000 tok/s · 4000 tok = 0.80 s → 1000 tok = 0.20 s atención cae ~k² = 16× en esa parte del cómputo

El orden importa. Recuperar agresivo (recall alto) antes de filtrar garantiza que el material correcto está entre los candidatos; rerankear y comprimir después garantiza que solo lo denso y relevante paga el peaje del prefill; cachear envuelve todo para no repetir trabajo. El SLM solo ve la chuleta final, corta y ordenada.

Implicaciones para inferencia on-premise

La trampa mental a evitar: tratar el SLM como un modelo grande con menos calidad. No lo es. Es un perfil de coste distinto que premia un diseño distinto. Tres consecuencias prácticas:

El presupuesto de tokens es un recurso de primera clase. Con un modelo grande de 128K de ventana, “meter un poco más” es barato relativo al modelo. Con un SLM, cada token de contexto se nota en el TTFT y en la calidad. Trata el tamaño del contexto como una cantidad a minimizar bajo restricción de cubrir la respuesta, no a maximizar.
La inversión vale la pena precisamente porque el modelo es barato. Reranker, compresor y cachés añaden complejidad, pero el modelo que sirven es lo suficientemente económico como para correr muchas réplicas. El cuello de botella se desplaza del modelo al pipeline de datos, que es justo donde quieres que esté.
Recuperar no sustituye a adaptar; se combinan. Para conocimiento de dominio profundo y recurrente, adaptar el SLM con LoRA (ver el hermano QLoRA y multi-LoRA agresivo) puede meter parte del conocimiento “en los pesos” de forma barata, reduciendo lo que hay que recuperar. RAG agresivo y adaptación agresiva no compiten: la primera da frescura y citabilidad, la segunda da fluidez y formato de dominio. El diseño bueno usa ambas.

En la RTX 4090 (24 GB, Ada Lovelace)

El escenario canónico: un SLM cuantizado (4B–8B en INT4/FP8) cabe holgado, dejando VRAM para un KV cache generoso —imprescindible para el prefix caching— y para el reranker (un cross-encoder de unos cientos de MB). El compresor extractivo tipo LLMLingua corre en un modelo pequeño aparte o en CPU. El cálculo de TTFT de arriba (0.80 s → 0.20 s comprimiendo 4× a ~5000 tok/s) es representativo de esta tarjeta. La regla de pulgar: si el TTFT se va por encima de tu SLA, el primer ajuste es comprimir el contexto, no cambiar de modelo.

En un cluster genérico 4×H100 SXM (320 GB, NVLink, FP8 nativo)

Con 320 GB y FP8 nativo el prefill es mucho más rápido, así que la tentación es relajar la disciplina de tokens. No conviene del todo: la palanca cambia de TTFT a throughput agregado. Comprimir el contexto no solo acelera cada petición sino que libera cómputo de prefill para servir más peticiones por GPU —el prefill compute-bound es exactamente el recurso que satura primero bajo carga. Aquí el prefix caching y el caché semántico, compartidos entre réplicas, son los que más rinden: a alto QPS, el trabajo de prefill que evitas cachear es throughput puro que ganas. El SLM sigue siendo el motor de razonamiento barato; la diferencia es que ahora corres muchos en paralelo y el pipeline de datos es lo que decide cuántas peticiones caben.

Lo que no hemos cubierto

Evaluación de la compresión: cómo medir que comprimir $k=4$ no tira respuestas correctas (faithfulness, answer recall sobre un set de preguntas con ground truth).
Compresión consciente de la query frente a agnóstica: comprimir antes o después de conocer la pregunta cambia qué se puede cachear y qué se puede tirar.
Chunking y granularidad: el tamaño de chunk interactúa con el reranking y la compresión; queda para el post de curación de corpus.
Multi-hop y agentes: cuando una pregunta requiere varias rondas de recuperación, el presupuesto de tokens se reparte entre hops y la disciplina de compresión se vuelve crítica.

Ver también

Reranking e hybrid retrieval para RAG — la palanca 1 en detalle: maximizar recall en el retriever y precisión en el reranker para inyectar pocos chunks pero excelentes, que es lo que un SLM necesita.
Curación del corpus para RAG — un corpus limpio y bien chunked reduce la paja que el compresor tiene que eliminar; la calidad de la chuleta empieza aguas arriba.
Caché semántico para RAG — la palanca 4: saltarse el modelo entero cuando una query es semánticamente equivalente a una ya respondida.
Embeddings 2026: dense, sparse y multivector — la base del retrieval híbrido y del umbral del caché semántico; qué representación recupera mejor con menos ruido.
Ingeniería del prefix cache hit rate — la palanca 3: cómo estructurar el prompt (contexto estable primero) para maximizar la reutilización del KV cache del contexto recuperado.
Optimizaciones de prefill en vLLM — el prefill compute-bound es el coste que toda esta discusión intenta minimizar; aquí están los parámetros concretos para acelerarlo.
Structured output: fundamentos — la palanca 5: forzar JSON conforme a esquema para que el SLM orqueste herramientas en vez de recordar datos.
Function calling y recuperación aumentada con herramientas — cuando consultar una API o base de datos bate a recuperar texto y a memorizar; el SLM como orquestador de tools.
El roofline se invierte en modelos pequeños — por qué el prefill compute-bound es el cuello de botella que da forma a todo este post: meter más contexto no es gratis.
QLoRA y multi-LoRA agresivo en SLM — la alternativa complementaria: adaptar el SLM por dominio para meter parte del conocimiento “en los pesos” y reducir lo que hay que recuperar.

Referencias

Lewis, P., et al. Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. NeurIPS 2020. https://arxiv.org/abs/2005.11401
Liu, N.F., et al. Lost in the Middle: How Language Models Use Long Contexts. TACL 2024. https://arxiv.org/abs/2307.03172
Jiang, H., et al. LLMLingua: Compressing Prompts for Accelerated Inference of Large Language Models. EMNLP 2023. https://arxiv.org/abs/2310.05736
Jiang, H., et al. LongLLMLingua: Accelerating and Enhancing LLMs in Long Context Scenarios via Prompt Compression. ACL 2024. https://arxiv.org/abs/2310.06839

Cuantización agresiva (estado del arte): del 4-bit al ternario

Tue, 09 Jun 2026 02:10:00 +0000

Este post es la continuación directa de Quantization para inferencia LLM, que cubre el régimen “resuelto” (FP8, INT4 con GPTQ/AWQ). Léelo primero: aquí asumo la matemática del scale+zero-point, qué hacen GPTQ y AWQ, y la distinción PTQ/QAT. Lo que añadimos es la frontera sub-4-bit, donde la cuantización post-hoc escalar deja de funcionar y hay que cambiar de herramienta.

TL;DR

Hay una línea divisoria nítida alrededor de los 4 bits. Por encima, cuantizar es un problema resuelto: INT8 es indistinguible de BF16, e INT4 con un método bueno (AWQ, GPTQ) pierde 1-2 puntos de MMLU y poco más. El método sigue siendo el mismo de siempre —tomar cada peso, escalarlo, redondearlo a un entero corto— y funciona. Por debajo de 4 bits, ese método colapsa: a 2 bits la cuantización escalar ingenua puede duplicar la perplexity. La razón es geométrica —cada peso tiene solo 4 valores posibles, el error de redondeo deja de ser despreciable— y la salida no es “redondear mejor”, es cambiar de representación. Los métodos SOTA de 2 bits (AQLM, QuIP#, QTIP) dejan de cuantizar pesos individuales y cuantizan vectores de pesos contra diccionarios (códigos), y “blanquean” la matriz de pesos para repartir su energía y aplastar outliers (incoherence processing). El ternario es otra cosa todavía: BitNet b1.58, con pesos en {-1, 0, +1} (~1.58 bits), no es PTQ —es un modelo entrenado nativamente con esa restricción— y cambia la aritmética de la matmul de multiplicaciones a sumas/restas, tocando a la vez el techo de cómputo y el de memoria. La regla mental: ≥4-bit comprimes la foto; <4-bit tienes que repintarla.

La analogía: el JPEG que ya no se puede comprimir más

En el post de quantization usamos el JPEG con detector de bordes para explicar INT4. Aquí la analogía sigue, pero hay que llevarla hasta su límite.

Un JPEG con factor de calidad 90 es indistinguible del original. A calidad 60 ya se nota un poco, pero sigue siendo “la misma foto”. A calidad 30 aparecen los bloques 8×8, los halos alrededor de los bordes, el banding en los degradados. A calidad 10 la imagen está destruida: reconoces que había una cara, pero los detalles han desaparecido bajo los artefactos. Y aquí está la clave: no existe ningún encoder JPEG que comprima a calidad 10 sin esos artefactos, porque el algoritmo JPEG (DCT por bloques + cuantización de coeficientes) tiene un suelo de información por debajo del cual su propio mecanismo introduce el ruido.

¿Qué haces si necesitas la foto a ese tamaño de archivo y que se siga viendo bien? No comprimes más la original. Repintas la foto sabiendo de antemano que va a vivir comprimida: un ilustrador la redibuja con líneas limpias, paleta reducida, cero degradados sutiles —una imagen diseñada para sobrevivir a la compresión brutal—. El resultado a “10 KB” se ve infinitamente mejor que el JPEG original aplastado a 10 KB, porque no es el mismo proceso: uno destruye información existente, el otro genera información nueva ya adaptada a la restricción.

Esa es exactamente la frontera de este post:

PTQ escalar (≥4-bit) = comprimir el JPEG. Hasta cierto ratio, sigue siendo la misma foto.
PTQ vectorial SOTA (2-bit: AQLM, QuIP#, QTIP) = un códec de imagen mucho más sofisticado (diccionarios, transformadas que decorrelacionan) que estira el ratio comprimible un poco más antes del colapso.
Ternario nativo (BitNet b1.58) = repintar la foto. No comprimes un modelo BF16 existente; entrenas uno nuevo que nace ternario.

El mapa de la frontera, bit a bit

Cuantizar un modelo es decidir cuántos valores distintos puede tomar cada peso. Con b bits por peso hay 2^b valores posibles. La pregunta central es: ¿a partir de qué b el número de valores es tan pequeño que el redondeo destruye el modelo?

Bits	Valores/peso	Estado del arte	Método necesario	Pérdida típica vs BF16
8	256	Resuelto	RTN, SmoothQuant, FP8	~0 (indistinguible)
4	16	Resuelto	AWQ, GPTQ	1-2 pp MMLU, +0.1-0.3 PPL
3	8	Degradación pequeña	GPTQ/AWQ tuneado, GGUF Q3_K	3-5 pp MMLU
2	4	Serio salvo SOTA	AQLM, QuIP#, QTIP (no escalar)	escalar: colapso; SOTA: 4-8 pp
1.58	3 (ternario)	Solo nativo	BitNet b1.58 (QAT/entrenamiento nativo)	n/a (no es PTQ)
1	2 (binario)	Investigación	nativo, claims dudosos	grande / sin metodología clara

Las tres transiciones que importan:

8 → 4 bits: nada se rompe. Con 16 niveles por peso y un scale por bloque de 128, el error de redondeo es pequeño relativo a la dinámica de los pesos. GPTQ compensa el error propagándolo a los pesos vecinos; AWQ protege el ~1 % de canales salientes. El modelo casi no lo nota. Esto está en el post anterior.

4 → 2 bits: el codo. Aquí pasan dos cosas a la vez. Primero, con solo 4 niveles, el cuantizador escalar ya no puede representar la distribución de pesos —que es aproximadamente gaussiana con colas largas— sin un error de redondeo enorme en proporción. Segundo, y más sutil: el error de cuantización deja de ser “ruido pequeño que el modelo absorbe” y se vuelve estructurado, sesgando sistemáticamente las activaciones. La PTQ escalar ingenua a 2 bits sobre un Llama 8B típicamente duplica la perplexity o más. Es el codo de la curva.

2 → 1.58 bits: cambio de naturaleza. No se cruza con un método de compresión mejor. Se cruza entrenando el modelo desde el principio con la restricción. Es una discontinuidad: a la izquierda estás haciendo PTQ, a la derecha estás haciendo entrenamiento.

Por qué la PTQ escalar colapsa por debajo de 4 bits

El cuantizador escalar tiene una limitación de fondo: cuantiza cada peso por separado, ignorando que los pesos de una fila/columna están correlacionados y que el error de uno se podría compensar con otro. A 4 bits esto importa poco; a 2 bits es letal. Hay tres ataques posibles, y los métodos SOTA usan los tres.

1. Cuantización vectorial: diccionarios en lugar de escalas

En lugar de mapear cada peso a uno de 4 valores, agrupa los pesos en vectores (p. ej. de 8 pesos) y mapea cada vector al entrada más cercana de un diccionario (codebook) aprendido. Si el diccionario tiene 256 entradas, codificar un vector de 8 pesos cuesta 8 bits (el índice) → 1 bit/peso, pero cada “valor reconstruido” es un punto en un espacio de 8 dimensiones elegido para minimizar el error sobre la distribución real de pesos.

La ventaja es de teoría de la información: un diccionario de vectores puede colocar sus puntos de reconstrucción donde realmente están los pesos (en racimos), mientras que el cuantizador escalar está obligado a poner sus 4 niveles en una rejilla regular, gastando resolución en zonas vacías. Es la diferencia entre un mapa de carreteras con cuadrícula uniforme y uno que pone más detalle donde hay ciudades.

AQLM (Additive Quantization of Language Models, arXiv:2401.06118) lleva esto al extremo con cuantización aditiva: cada vector de pesos se reconstruye como suma de varios códigos de varios diccionarios (multi-codebook). Es más expresivo que un solo diccionario porque el número de combinaciones es el producto de los tamaños, no la suma. AQLM fue uno de los primeros métodos en hacer 2-bit “usable” (no colapsado) en modelos grandes, a costa de un proceso de calibración caro y kernels de inferencia especializados.

2. Incoherence processing: blanquear la matriz

El segundo ataque es contra los outliers. Las matrices de pesos de un transformer tienen unas pocas entradas (y unos pocos canales) con magnitud mucho mayor que el resto. Esos outliers dominan el rango del cuantizador: si tienes que representar un peso de magnitud 8 y el resto son de magnitud 0.5, tu scale se estira para cubrir el 8 y desperdicias casi toda la resolución.

Incoherence processing (la idea central de QuIP y QuIP#) ataca esto multiplicando la matriz de pesos W por matrices ortogonales aleatorias por la izquierda y la derecha: W' = U W V^T. Como U y V son ortogonales, la operación es invertible y la matemática del producto se puede deshacer en inferencia absorbiéndola en las capas vecinas (igual que AWQ absorbe sus escalas). Pero la rotación reparte la energía: una matriz “incoherente” tiene sus valores repartidos de forma casi uniforme, sin outliers concentrados, porque mezclar coordenadas con una rotación aleatoria aplana la distribución (es, en esencia, el teorema central del límite actuando sobre combinaciones lineales). Una matriz sin outliers se cuantiza muchísimo mejor a 2 bits. Es el equivalente a “blanquear” una señal antes de digitalizarla.

QuIP# (arXiv:2402.04396) combina incoherence processing con códigos reticulares E8: en vez de un diccionario arbitrario, usa el retículo E8 (un empaquetamiento de esferas óptimo en 8 dimensiones, el mejor conocido). Cuantizar vectores de 8 pesos contra el retículo E8 da el menor error de reconstrucción posible para una densidad de bits dada, porque E8 es literalmente la forma más eficiente de colocar puntos en 8D. Es teoría de codificación clásica aplicada a pesos de LLM.

3. Codificación con memoria: trellis

QTIP (arXiv:2406.11235) añade el tercer ataque: trellis-coded quantization. En lugar de cuantizar cada vector de forma independiente, modela la secuencia de pesos como un camino a través de un trellis (la misma estructura de los códigos convolucionales de las telecomunicaciones) y elige la secuencia de códigos óptima con el algoritmo de Viterbi. La intuición: introducir memoria entre cuantizaciones sucesivas permite errores correlacionados que se cancelan, en vez de errores independientes que se acumulan. QTIP, sobre incoherence processing, mejora a QuIP# en calidad a 2-3 bits manteniendo kernels de inferencia rápidos.

La idea común a los tres: dejar de cuantizar escalares y empezar a cuantizar vectores con diccionarios, y decorrelacionar la matriz antes de hacerlo. Ninguno es “redondear mejor”; los tres cambian la representación de raíz. Por eso, por debajo de 4 bits, ya no basta con un flag en vLLM: hace falta co-diseño de método de cuantización + kernel de inferencia.

El ternario nativo: BitNet b1.58

Aquí cambiamos de continente. Todo lo anterior es PTQ: parte de un modelo BF16 entrenado y lo comprime. El ternario de BitNet no comprime nada.

BitNet b1.58 (arXiv:2402.17764) entrena un transformer desde cero donde cada peso está restringido a {-1, 0, +1} durante todo el entrenamiento. Tres valores ⇒ log₂(3) ≈ 1.58 bits/peso. La cuantización no es un paso posterior: las capas lineales (BitLinear) cuantizan sus pesos a ternario en el forward pass de cada step de entrenamiento, y los gradientes fluyen a través de un estimador straight-through. El modelo aprende a funcionar con pesos ternarios. Esto es QAT llevado al extremo: no un fine-tune corto de robustez, sino la restricción presente desde el primer token de entrenamiento.

Esa diferencia es la que esquiva el codo de la curva. La PTQ a 2 bits intenta encontrar la mejor aproximación ternaria/quaternaria de un modelo que se entrenó esperando precisión completa —y ese modelo tiene pesos “frágiles” que dependen de matices que 2 bits no capturan—. BitNet, en cambio, nunca tuvo esos matices: sus pesos nacieron ternarios, así que la red distribuyó su capacidad representacional de forma compatible con la restricción. Es repintar la foto en vez de comprimirla.

Lo que cambia no es solo la memoria, es la aritmética

El punto que más se subestima de BitNet: con pesos en {-1, 0, +1}, la multiplicación desaparece de la matmul. Multiplicar una activación x por un peso ternario w es trivial: si w = +1 sumas x, si w = -1 restas x, si w = 0 no haces nada. La operación dominante de un transformer —el producto matriz-vector— pasa de ser un mar de multiplica-acumula (MAC) en coma flotante a ser sumas y restas enteras.

Esto importa porque conecta con el roofline. Como se explica en El roofline invertido de los modelos pequeños, la inferencia LLM tiene dos techos: el de memoria (ancho de banda HBM para cargar pesos) y el de cómputo (FLOPs de las tensor cores). La cuantización normal (INT4, FP8) ataca solo el techo de memoria: el peso ocupa menos, pero para multiplicarlo lo descuantizas a FP16 y haces la misma multiplicación de siempre. El ternario ataca ambos techos a la vez: el peso ocupa 1.58 bits (memoria) y la operación es una suma en lugar de una multiplicación (cómputo). Por eso BitNet necesita kernels propios —bitnet.cpp— que ejecutan la matmul ternaria sin pasar nunca por FP16; un kernel que descuantizara a FP16 para multiplicar tiraría a la basura la mitad de la ventaja.

La contrapartida honesta: BitNet b1.58 es entrenamiento desde cero. No puedes “convertir tu Llama 8B a BitNet”. Si quieres ternario, entrenas (o usas) un modelo nativamente ternario, con todo lo que implica en coste de pre-entrenamiento y en disponibilidad de pesos. Hoy es una línea de investigación con modelos publicados a escalas modestas, no un drop-in para reemplazar tu serving actual.

QAT como puente entre PTQ y nativo

Entre “comprimir post-hoc” (PTQ) y “entrenar nativamente ternario” (BitNet) hay un punto intermedio: QAT (Quantization-Aware Training). Tomas un modelo ya entrenado y haces un fine-tune corto con las operaciones de cuantización dentro del bucle, para que aprenda a ser robusto a bits bajos sin pagar un pre-entrenamiento completo.

Gemma 3 publica variantes QAT oficiales precisamente para esto: modelos que, tras el fine-tune QAT, sostienen INT4 con una pérdida de calidad mucho menor que la PTQ pura sobre el mismo modelo. El coste es de entrenamiento (horas-días de GPU sobre un modelo ya existente), no de inferencia. Para INT4 con QAT recuperas casi toda la calidad; para 2-bit, QAT ayuda pero sigue siendo terreno difícil; para ternario, el QAT deja de ser “fine-tune corto” y se convierte en entrenamiento nativo (BitNet).

La jerarquía de decisión:

PTQ = default a ≥4 bits. Minutos-horas, sin tocar pesos de entrenamiento. Cubre el 90 % de producción.
QAT = cuando PTQ pierde demasiado y la diferencia importa. Bits bajos (2-3), o modelos sensibles. Pagas fine-tune.
Nativo (ternario) = cuando quieres bajar de 2 bits y cambiar la aritmética. Pagas pre-entrenamiento. Solo tiene sentido si controlas el modelo desde su creación.

Las matemáticas que importan: footprint y cuántos caben

El footprint de los pesos es directo: bytes = (bits/param / 8) × N, con N el número de parámetros. Para un modelo de 8B:

Nivel	bits/param	Footprint 8B	Ratio vs BF16
BF16	16	16.0 GB	1.0×
INT8	8	8.0 GB	2.0×
INT4	4	4.0 GB	4.0×
3-bit	3	3.0 GB	5.3×
2-bit	2	2.0 GB	8.0×
1.58-bit (ternario)	~1.58	~1.6 GB	~10×

(El ternario real ocupa algo más de 1.58 bits/param porque hay que empaquetar 5 valores ternarios en 8 bits —5 × log₂(3) ≈ 7.92 bits— y porque las normas y embeddings suelen quedarse en más precisión. La cifra de ~1.6 GB para 8B es el orden de magnitud correcto.)

¿Cuántos modelos de 8B caben en una RTX 4090?

Una RTX 4090 (24 GB, Ada Lovelace) tiene 24 GB. Reservamos ~4 GB para KV cache y activaciones, dejando 20 GB para pesos. Cuántos modelos de 8B distintos caben cargados simultáneamente:

Nivel	Footprint 8B	Modelos en 20 GB	Comentario
BF16	16.0 GB	1	uno y queda margen escaso
INT8	8.0 GB	2	dos modelos distintos
INT4	4.0 GB	5	régimen resuelto; calidad ~lossless con AWQ
3-bit	3.0 GB	6	degradación pequeña ya visible
2-bit	2.0 GB	10	solo viable con AQLM/QuIP#/QTIP
1.58-bit	~1.6 GB	~12	solo modelos nativamente ternarios

La cuenta es seductora —de 1 a 12 modelos en la misma tarjeta— pero hay que leerla con escepticismo. Saltar de INT4 (5 modelos, casi sin pérdida) a 2-bit (10 modelos) duplica la capacidad, pero solo si usas un método SOTA y aceptas 4-8 puntos de MMLU. Y el salto de 2-bit a ternario (10 → 12) es marginal en memoria: el ternario no se justifica por footprint frente a un 2-bit SOTA, se justifica por la aritmética (el techo de cómputo) y porque evita el codo de calidad al ser nativo. Si tu única métrica es “cuántos GB ocupa”, el 2-bit SOTA ya te da casi todo. El ternario es para cuando además quieres el ahorro de cómputo.

La curva conceptual: perplexity vs bits

Tres lecturas de la curva. Uno: a la derecha de 4 bits, las tres ramas están casi pegadas y casi planas —el régimen resuelto—. Dos: la rama roja (PTQ escalar ingenua) tiene un codo brutal entre 3 y 2 bits; ahí es donde duplica la perplexity. La rama azul (PTQ SOTA vectorial) aplana ese codo —no lo elimina, pero lo hace tolerable hasta 2 bits—. Tres: el punto verde del ternario nativo no está en ninguna de las dos curvas de PTQ, porque no se obtiene comprimiendo: se obtiene entrenando, y por eso puede caer por debajo del codo sin pagar el precio de calidad que paga cualquier PTQ a esa densidad de bits. Es la diferencia entre el JPEG aplastado y la foto repintada.

Escepticismo obligatorio: el 1-bit “sin pérdida” y los benchmarks sin metodología

Tres alertas para leer la literatura de cuantización agresiva:

“1-bit sin pérdida” casi siempre tiene letra pequeña. El binario puro {-1, +1} (1 bit) pierde la capacidad de representar el cero, que en transformers es importante (muchos pesos efectivamente nulos). Por eso el verdadero estado del arte de baja densidad es ternario (1.58 bits), no binario: el cero vale su 0.58 de bit extra. Cuando un paper anuncia “1-bit”, conviene mirar si (a) es realmente 1 bit o 1.58 redondeado hacia abajo en el titular, (b) “sin pérdida” se mide en perplexity de WikiText (fácil) o en benchmarks de razonamiento (donde el colapso aparece), y (c) compara contra un baseline del mismo tamaño efectivo o contra un modelo mucho mayor para inflar la ventaja.

Perplexity plana ≠ calidad preservada. La perplexity en un corpus genérico es la métrica más indulgente con la cuantización agresiva. Un modelo 2-bit puede tener perplexity casi idéntica al BF16 y a la vez caer 10 puntos en GSM8K o en un benchmark de código, porque el razonamiento multi-paso amplifica errores que la perplexity media no ve. Desconfía de cualquier claim sub-4-bit que solo reporte perplexity. Como ya dijimos en el post de quantization, la pérdida hay que medirla en la tarea de destino.

Comparabilidad de hardware. Los números de “X veces más rápido” del ternario solo aplican con los kernels especializados (bitnet.cpp) y en el hardware donde la aritmética suma/resta gana de verdad. En una GPU con tensor cores diseñadas para FP16/FP8, un kernel ternario ingenuo puede ser más lento que INT4 bien optimizado, porque desaprovecha el silicio. La ventaja del ternario es real, pero es una ventaja de co-diseño (modelo + kernel + a veces hardware), no un flag que activas sobre tu stack actual. Cualquier benchmark que no especifique el kernel y el hardware exacto es ruido.

Implicaciones para inferencia on-premise

En la RTX 4090 (24 GB, Ada Lovelace): el régimen práctico hoy sigue siendo INT4 AWQ para modelos de 7-14B —resuelto, casi lossless, soportado nativamente—. El 2-bit SOTA (AQLM/QuIP#/QTIP) es viable y permite cargar modelos más grandes o más modelos a la vez, pero exige los kernels específicos de cada método y una calibración cara, y paga calidad. Tiene sentido cuando el cuello es la VRAM y aceptas el trade-off; no como default. El ternario en 4090 es experimental: sin tensor cores diseñadas para suma/resta ternaria, la ventaja de cómputo se diluye, aunque el ahorro de memoria se mantiene.

En un cluster genérico 4×H100 SXM (320 GB, NVLink, FP8 nativo): aquí el default es FP8 (calidad casi indistinguible, throughput nativo) o INT4 AWQ para modelos que no caben en FP8. El sub-4-bit SOTA es para servir modelos enormes (200B+) cuando ni FP8 ni INT4 caben con el margen de KV cache que quieres, a costa de calidad y de complejidad de kernel. El ternario nativo, hoy, es objeto de investigación más que de producción: su promesa —tocar ambos techos del roofline— es mayor en CPU/edge (donde no hay tensor cores FP8 que aprovechar) que en un cluster H100, que ya tiene hardware FP8 dedicado.

La regla de pulgar, junio 2026: ≥4-bit es ingeniería resuelta; 2-bit SOTA es una palanca real pero con coste de método y de calidad; ternario es una apuesta de arquitectura, no un ajuste de despliegue.

Ver también

Quantization para inferencia LLM: FP8, INT4, GGUF — la base imprescindible: la matemática del scale+zero-point, GPTQ/AWQ y PTQ vs QAT que aquí se dan por sabidas; este post es su continuación hacia la frontera sub-4-bit.
FP8 end-to-end: pesos, KV y calidad — el otro extremo del espectro, el régimen resuelto del datacenter donde la cuantización ya casi no cuesta calidad.
Knowledge distillation — la palanca complementaria: destilar reduce parámetros, cuantizar reduce bits por parámetro; a 2-bit suelen combinarse para llegar al footprint objetivo.
Poda de modelos LLM — sparsidad y cuantización agresiva son ortogonales y se acumulan: 50 % sparso + 2-bit es otra ruta al mismo footprint que el ternario.
KV cache: la memoria de trabajo — los ~4 GB que reservamos para KV en la cuenta de la 4090 salen de aquí; cuantizar el cache es la otra mitad del presupuesto de memoria.
El roofline invertido de los modelos pequeños — por qué el ternario es especial: ataca a la vez el techo de memoria y el de cómputo, mientras INT4/FP8 solo tocan el de memoria.
Test-time quantization en caliente — cuantizar dinámicamente en inferencia frente a la cuantización estática y calibrada que describen AQLM/QuIP#/QTIP.
Arquitecturas nativas device + MoE de grano fino — el Q4 en device como punto de partida del que el sub-4-bit y el ternario son la siguiente frontera para edge.
QLoRA y multi-LoRA agresivo en SLM — fine-tune sobre una base ya cuantizada; el límite de cuánto puedes comprimir la base antes de que el adapter no pueda recuperar la calidad.

Referencias

Ma, S. et al. The Era of 1-bit LLMs: All Large Language Models are in 1.58 Bits (BitNet b1.58). https://arxiv.org/abs/2402.17764
Egiazarian, V., Panferov, A., Kuznedelev, D. et al. Extreme Compression of Large Language Models via Additive Quantization (AQLM). https://arxiv.org/abs/2401.06118
Tseng, A., Chee, J., Sun, Q., Kuleshov, V., De Sa, C. QuIP#: Even Better LLM Quantization with Hadamard Incoherence and Lattice Codebooks. https://arxiv.org/abs/2402.04396
Tseng, A., Sun, Q., Hou, D., De Sa, C. QTIP: Quantization with Trellises and Incoherence Processing. https://arxiv.org/abs/2406.11235
Frantar, E., Ashkboos, S., Hoefler, T., Alistarh, D. GPTQ: Accurate Post-Training Quantization for Generative Pre-trained Transformers. https://arxiv.org/abs/2210.17323
Lin, J., Tang, J., Tang, H., Yang, S., Dang, X., Han, S. AWQ: Activation-aware Weight Quantization for LLM Compression and Acceleration. https://arxiv.org/abs/2306.00978
Google DeepMind. Gemma 3 QAT (Quantization-Aware Training) models — blog oficial: https://developers.googleblog.com/en/gemma-3-quantized-aware-trained-state-of-the-art-ai-to-consumer-gpus/
Microsoft. bitnet.cpp — kernels de inferencia ternaria 1-bit: https://github.com/microsoft/BitNet

Test-time quantization: cuantizar en caliente sin dataset de calibración

Tue, 09 Jun 2026 02:00:00 +0000

Este post es la continuación natural de Quantization para inferencia LLM, que conviene leer primero: allí están GPTQ, AWQ, el scale + zero-point y por qué los outliers de activación son el problema central. Aquí no discutimos cuántos bits usar, sino cuándo y con qué información se calculan las escalas: offline contra un corpus (PTQ) o en caliente contra el tráfico real (TTQ).

TL;DR

La cuantización activation-aware (AWQ, SmoothQuant) decide qué canales proteger midiendo la magnitud de las activaciones sobre un dataset de calibración en un pase offline, antes de desplegar. El supuesto implícito es que ese corpus representa el tráfico futuro. Pero los outliers de activación —los canales de magnitud 10-100× la mediana que dominan el error de cuantización— dependen del input: cambian con el dominio, el idioma y la distribución del cliente. Cuando el tráfico real se aleja de la calibración, las escalas fijas dejan de ser óptimas y la calidad cae. Test-time quantization (TTQ) elimina el corpus y el pase offline: deriva las escalas activation-aware en tiempo de inferencia, a partir de las activaciones que realmente se observan, por token o por batch. La contrapartida es honesta y no menor: introduce overhead en runtime —calcular estadísticas, detectar outliers, recomputar escalas en cada step— que compite directamente con el ahorro de cuantizar. En modelos pequeños ese overhead pesa proporcionalmente más, porque el forward es corto y los costes fijos por step dominan (el marco está en roofline invertido para SLM). TTQ es ortogonal al formato: no es un competidor de INT4 o FP8, es una forma distinta de derivar s. Compensa cuando no hay pipeline de calibración, cuando la distribución del tráfico es cambiante o desconocida, y en multitenant donde no existe un corpus representativo.

Estás aquí: DEPLOY

La analogía: el sastre que toma medidas frente a las tallas pre-confeccionadas

Una tienda de ropa tiene dos formas de vestir a un cliente.

La primera es vender tallas pre-confeccionadas. La fábrica midió en su día a un “cliente medio” —un maniquí promedio construido sobre una muestra de población— y cortó las prendas según esas medidas. Cuando entra un cliente, le das la talla que más se le acerca. Es rapidísimo: la prenda ya está cosida, solo se entrega. El problema aparece cuando el cliente no se parece al maniquí promedio: si tiene los hombros mucho más anchos que la media —su outlier particular—, la talla estándar le tira o le sobra tela, porque se cortó protegiendo otras zonas. Esto es la PTQ offline calibrada: AWQ midió la importancia de cada canal sobre un corpus y fijó las escalas de una vez; rápido en inferencia, pero ciego al cliente concreto.

La segunda es el sastre que toma medidas en el momento. Cuando entra el cliente, el sastre saca el metro, mide a ese cliente, detecta dónde está su volumen particular y ajusta el corte a su anatomía real. El resultado encaja mejor, sobre todo en los clientes que se salen del molde. Pero cada cliente cuesta tiempo: medir, marcar, decidir. Esto es TTQ: las escalas se derivan en caliente de las activaciones que ese input genera realmente.

La analogía se sostiene en tres detalles:

El maniquí promedio = el dataset de calibración. Si la población que entra a la tienda se parece al maniquí, las tallas funcionan; si no, fallan en los extremos.
Tomar medidas en cada cliente = calcular estadísticas de activación por token/batch. Mejor ajuste, pero un coste fijo que se paga en cada prenda.
Los hombros anchos = los canales outlier de activación. Son precisamente las zonas donde el ajuste importa y donde la talla genérica más se equivoca.

El sastre gana cuando los clientes son variados o desconocidos. Pierde cuando tienes una población homogénea y un maniquí que la representa bien: ahí pagar la medición en cada cliente es tirar el tiempo.

El problema que TTQ resuelve: la calibración fija envejece con el tráfico

Recordemos del post de quantization qué hacen exactamente AWQ y SmoothQuant. No cuantizan todos los canales por igual: identifican el ~1 % de canales cuyas activaciones tienen magnitud grande —los salient channels— y los protegen escalándolos antes de cuantizar. Para medir esa importancia necesitan ver activaciones, y las ven sobre un dataset de calibración (128-512 muestras, típicamente WikiText o un slice del dominio) en un pase offline previo al despliegue.

El supuesto es fuerte: que la distribución de activaciones del corpus de calibración representa la del tráfico de producción. Dos razones por las que ese supuesto se rompe:

Los outliers de activación dependen del input. No son una propiedad fija del modelo como los pesos. El canal que es outlier procesando código C++ puede no serlo procesando árabe conversacional o JSON de logs. La magnitud y la posición de los picos cambian con el dominio, el idioma y el formato de entrada.
El tráfico real rara vez es el corpus. Calibras con WikiText en inglés y el cliente te manda tickets de soporte en español con tablas pegadas. La calibración protegió los canales que WikiText activaba, no los que activa el tráfico real. Las escalas son subóptimas justo donde el cliente vive.

El resultado es degradación dependiente de la distribución: el modelo cuantizado mantiene la calidad mientras el input se parece a la calibración y la pierde a medida que se aleja. El caso más incómodo es el multitenant: si sirves a clientes con dominios distintos desde el mismo modelo cuantizado, no existe un único corpus representativo; cualquier calibración fija favorece a unos tenants y penaliza a otros.

El mecanismo de TTQ: medir las activaciones reales y escalar en caliente

TTQ (arXiv:2603.19296, marzo 2026) propone derivar la cuantización activation-aware en tiempo de inferencia, sin pase offline ni dataset de calibración. La idea, en su forma desnuda y conceptual:

Paso 1 — Observar. Cuando llega el tensor de activaciones X a una capa lineal (por token o por batch), se calculan estadísticas baratas sobre los canales: una medida de tendencia central (mediana o media de magnitud) y una de dispersión por canal. Esto es el equivalente a que AWQ mirase su corpus, pero hecho sobre las activaciones que de verdad están entrando ahora.

Paso 2 — Detectar outliers en caliente. Con esas estadísticas se identifican los canales cuya magnitud se dispara respecto a la mediana del tensor —el criterio típico es un umbral del estilo “magnitud > k × mediana”. Son los canales que, si se cuantizan con la misma escala que el resto, disparan el error.

Paso 3 — Derivar escalas y segregar. Para los canales normales se calcula una escala que aprovecha el rango; para los outliers se aplica un tratamiento distinto —una escala propia, o mantenerlos en precisión más alta— al estilo mixed-precision en caliente. Es la misma filosofía que LLM.int8() (segregar outliers a FP16) o AWQ (escalar salient channels), pero con el umbral y las escalas recalculados sobre el input actual, no congelados desde la calibración.

Paso 4 — Cuantizar y multiplicar. Con las escalas frescas se cuantiza y se ejecuta el GEMM. Las activaciones que entran al siguiente layer compensan el reescalado, igual que en AWQ, para que la matemática se cancele.

La diferencia clave con AWQ no está en qué se hace (proteger outliers de activación) sino en cuándo y contra qué: AWQ lo decide una vez, offline, contra un corpus; TTQ lo decide en cada step, en caliente, contra el tráfico real. Es la traslación a inferencia de la idea de “test-time”: adaptar el cómputo a la muestra concreta que tienes delante en lugar de a un promedio precomputado.

dataset calibración pase OFFLINEfija escalas s, outliers escalas CONGELADAS input parecido → OK input lejano →degradación overhead inferencia ≈ 0 · calidad depende de la calibración

activaciones REALESdel tráfico actual medir + detectaroutliers EN CALIENTE escalas FRESCASpor token / batch cuantizar + GEMM+ overhead por step sin corpus · calidad robusta a la distribución · overhead ≠ 0

Las matemáticas que importan

El error de cuantizar un outlier con la escala equivocada

Recordemos la cuantización uniforme afín del post base: un código entero q = round(x/s) - z con escala s y zero-point z, y reconstrucción x̂ = s·(q + z). Para un cuantizador de b bits con rango simétrico, la escala que cubre un tensor de magnitud máxima M es aproximadamente s = M / (2^{b-1} - 1). El error de redondeo de cada elemento está acotado por media escala: |x - x̂| ≤ s/2.

Aquí está el problema del outlier. La escala s se elige para cubrir el valor más grande del grupo. Si un canal tiene magnitud 30× la mediana y compartes una sola escala con el resto del tensor, esa magnitud manda: M es el outlier, así que s se infla 30× respecto a lo que necesitaría la mayoría. El error absoluto de redondeo de los valores normales sube proporcionalmente.

Cuenta concreta. Tomemos un grupo donde la mediana de magnitudes es 1.0 y un canal outlier vale 30.0, cuantizado a INT4 (b = 4, niveles ±7):

Con escala compartida, s = 30 / 7 ≈ 4.29. El error de redondeo de un valor típico (magnitud ~1) es de hasta s/2 ≈ 2.14. Es decir, el error sobre los valores normales es del orden de su propio valor: el outlier ha destruido la resolución de todo lo demás. Error relativo de un valor de magnitud 1: hasta ~214 %.
Segregando el outlier (lo sacas a FP16 o le das su propia escala) y cuantizando el resto con M = 1, s = 1/7 ≈ 0.143. El error de un valor típico baja a s/2 ≈ 0.071, ~7 % relativo. Treinta veces menos error sobre la mayoría de los pesos del grupo.

Esa es toda la razón de ser de la cuantización activation-aware: detectar y tratar aparte el ~1 % de canales que, de no segregarse, secuestran la escala. AWQ lo hace contra el corpus; TTQ lo hace contra el input real. Y si el canal que es outlier en producción no era outlier en la calibración, AWQ no lo protegió: cuantizó el tráfico real con la escala inflada del caso de arriba. Ahí TTQ gana precisión.

El overhead: el coste de medir en cada step

El precio es simétrico. Calcular las estadísticas por token —magnitudes por canal, mediana o percentil, umbral de outlier, escalas— son reducciones sobre el tensor de activación que no existían en el forward con escalas congeladas. Llamemos:

T = tiempo del forward por token con escalas fijas (PTQ estática), en µs.
Δ = coste extra por token de derivar las estadísticas y escalas en caliente, en µs.

El overhead relativo es simplemente:

$$\text{overhead} = \frac{\Delta}{T}$$

La clave es que Δ es relativamente fijo por step (depende del número de canales y capas, no de cuánto trabajo “útil” haga el modelo), mientras que T escala con el tamaño del modelo. Por eso el cociente se comporta de forma muy distinta según el modelo:

Modelo grande (p. ej. 70B): T es grande —cada forward mueve decenas de GB de pesos desde HBM—. Si Δ ≈ 8 µs y T ≈ 800 µs, el overhead es 8/800 = 1 %. Despreciable frente al ahorro de cuantizar.
SLM (p. ej. 1B): T es pequeño —el forward por token es corto—. Con el mismo Δ ≈ 8 µs y T ≈ 60 µs, el overhead es 8/60 ≈ 13 %. Ya no es despreciable: se come buena parte de lo que ganaste cuantizando.

Esto conecta directamente con el roofline invertido para modelos pequeños: en SLM los costes fijos por step (lanzamiento de kernels, sincronizaciones, overheads que no escalan con el modelo) pesan proporcionalmente más, porque hay menos trabajo útil entre los que repartirlos. El Δ de TTQ es exactamente uno de esos costes fijos. Per-batch en lugar de per-token amortiza Δ entre todos los tokens del batch y baja el overhead relativo, a costa de escalas menos finas; es el primer parámetro a tocar.

La conclusión incómoda: TTQ regala robustez a la distribución pero gasta parte del presupuesto de aceleración en medir, y en el régimen donde la aceleración más escasea —los SLM, los que más se despliegan en el edge— es donde ese gasto más duele. No es gratis; es un cambio de moneda.

Nota de escepticismo metodológico: arXiv:2603.19296 es de marzo de 2026, muy reciente, y a la fecha de este post no hay reproducciones independientes amplias. Las cifras de speedup y de calidad que circulen conviene tomarlas con la misma cautela que cualquier número sin metodología publicada: ¿qué hardware, qué tamaño de batch, qué Δ real medido, contra qué baseline (PTQ bien calibrada o mal calibrada), en qué dominio? El argumento conceptual —robustez a la distribución a cambio de overhead por step— es sólido; los multiplicadores concretos, pendientes de validación.

Qué NO es TTQ: deslindando del resto del zoo

TTQ se confunde fácilmente con técnicas vecinas. La distinción que importa es que TTQ es el cómo derivas las escalas, no el formato ni el momento del entrenamiento.

Técnica	Cuándo se fijan las escalas	Necesita corpus calibración	Toca entrenamiento	Es un formato
PTQ estática (GPTQ, AWQ)	Offline, antes de desplegar	Sí	No	No (usa INT4/INT8)
QAT	Durante el entrenamiento	No (datos de train)	Sí (re-entrena)	No
FP8 end-to-end	En runtime, pero escalas simples por tensor	Mínimo / ninguno	No	Sí (E4M3/E5M2)
TTQ	En runtime, activation-aware por token/batch	No	No	No (ortogonal al formato)

Las cuatro distinciones, una a una:

Frente a PTQ estática (GPTQ/AWQ). Misma meta (proteger outliers), mismo formato posible (INT4), pero PTQ congela las decisiones offline contra un corpus y TTQ las recalcula en caliente. TTQ es, en cierto sentido, “AWQ sin la fase de calibración, pagada en runtime”.
Frente a QAT. QAT mete la cuantización dentro del bucle de entrenamiento para que el modelo aprenda a ser robusto a ella; cuesta re-entrenar. TTQ no toca el entrenamiento: opera sobre un modelo ya entrenado, en inferencia. Son ataques en momentos opuestos del pipeline.
Frente a FP8 end-to-end. FP8 es un formato con su propio rango logarítmico; su “dynamic scaling” calcula un escalar simple por tensor en runtime, pero no hace detección activation-aware de outliers por canal. TTQ podría, conceptualmente, derivar escalas en caliente para un cuantizador FP8 o INT4: es ortogonal al formato.
TTQ es ortogonal al formato. Decide cómo obtener s, no en cuántos bits guardas q. Puedes imaginar “TTQ sobre INT4” o “TTQ sobre FP8”. Lo que define a TTQ es la fuente de la escala —activaciones reales en caliente— no el ancho del código.

Cuándo compensa (y cuándo no)

TTQ no es un reemplazo universal de AWQ. Es una herramienta para un perfil concreto de despliegue. Compensa cuando:

No tienes pipeline de calibración. Quieres desplegar un modelo cuantizado ya, sin montar el dataset de calibración, ejecutar el pase offline ni validar que el corpus representa el tráfico. TTQ recorta esa fase entera: cargas el modelo y sirves.
La distribución del tráfico es cambiante o desconocida. Un asistente que un día recibe código y otro día contratos legales en otro idioma. Ninguna calibración fija cubre bien ambos; la adaptación en caliente sigue la distribución sin re-calibrar.
Multitenant sin corpus representativo. Sirves el mismo modelo a clientes con dominios dispares. No existe un corpus único que represente a todos; cualquier calibración fija crea ganadores y perdedores entre tenants. TTQ ajusta a cada input, sea del tenant que sea.

No compensa cuando:

Tienes un dominio estable y un buen corpus de calibración. Si tu tráfico es homogéneo y representativo, AWQ offline te da la misma calidad con cero overhead en runtime. Pagar Δ en cada token para reaprender lo que un corpus ya capturó es desperdicio.
Sirves SLM con SLA de latencia ajustado. Es justo el caso donde Δ/T es alto. Si el modelo es pequeño y el TPOT importa, el overhead de medir puede borrar la ganancia de cuantizar. Mide tu Δ real antes de asumir que sale a cuenta.
El batch es grande y compute-bound. Con concurrencia alta el forward ya no está memory-bound y el coste de las reducciones extra compite peor; conviene al menos amortizar Δ per-batch.

Implicaciones en hardware on-premise

En una RTX 4090 (24 GB, Ada Lovelace)

El caso natural de la 4090 es el SLM —Qwen 3 1.5B, Llama 3 8B AWQ-INT4— sirviendo a baja concurrencia. Es precisamente el régimen donde TTQ es más arriesgado: T por token es pequeño y la 4090 no tiene FP8 nativo acelerado (lo discutimos en el post de quantization), así que las reducciones extra de TTQ corren en CUDA cores compitiendo por el mismo tiempo. Aquí la pregunta no es “¿mejora la calidad?” sino “¿el overhead me deja un TPOT aceptable?”. Si el tráfico es homogéneo, AWQ offline gana por simplicidad y latencia. TTQ solo justifica su Δ si la distribución de inputs es genuinamente impredecible y la degradación de la calibración fija es medible.

En un cluster genérico 4×H100 SXM (320 GB, NVLink, FP8 nativo)

Aquí el cálculo se invierte parcialmente. Con modelos grandes T es alto y el Δ/T baja a la zona de pocos puntos porcentuales, así que el overhead de TTQ es más digerible. El caso de uso fuerte es el multitenant: un cluster que sirve un modelo grande a clientes con dominios heterogéneos, donde no hay un corpus de calibración que contente a todos. Ahí la robustez a la distribución de TTQ tiene valor real y el overhead se diluye en un forward grande. Aun así, sobre H100 con FP8 nativo, el baseline a batir es exigente: FP8 estático casi no pierde calidad (ver tabla del post de quantization) y no cuesta nada en runtime. TTQ tiene que demostrar que su ganancia de robustez en los tenants outlier supera lo que regala en overhead. Con un paper de marzo de 2026 y sin reproducciones, esa demostración está pendiente.

Lo que no hemos cubierto

El coste de memoria de las estadísticas en caliente: buffers por canal, su impacto en el footprint y en la presión de cache.
Interacción con continuous batching: cómo se derivan escalas cuando un batch mezcla requests de dominios distintos en el mismo step.
TTQ + speculative decoding: si el draft y el target derivan escalas en caliente por separado, y cómo afecta eso a la tasa de aceptación.
Estabilidad numérica: qué pasa cuando un batch tiene un outlier extremo puntual que infla la escala de todos los tokens de ese step.

Ver también

Quantization para inferencia LLM — la base imprescindible: scale + zero-point, GPTQ, AWQ y por qué los outliers de activación son el problema; TTQ es AWQ con las escalas derivadas en caliente en vez de offline.
Roofline invertido para modelos pequeños — por qué los costes fijos por step pesan más en SLM; explica directamente por qué el overhead Δ de TTQ duele más en modelos pequeños.
Cuantización agresiva sub-4-bit y ternario — la frontera estática por debajo de 4 bits; complementa a TTQ, que ataca el cómo de la escala en vez del cuántos bits.
QLoRA y multi-LoRA agresivo en SLM — adapters sobre un base cuantizado; el base podría derivar escalas en caliente mientras los adapters van en BF16.
FP8 end-to-end: pesos, KV y calidad — el formato del datacenter Hopper/Blackwell; TTQ es ortogonal y podría derivar escalas para un cuantizador FP8.
KV cache: la memoria de trabajo de la inferencia LLM — el KV cache también se cuantiza; sus escalas son otro candidato a derivarse en caliente por la misma lógica.
Knowledge distillation — la otra vía para servir modelos pequeños robustos; destilar reduce el modelo, TTQ ajusta su cuantización al tráfico.
Optimizando el decode en vLLM — donde se materializan en parámetros las palancas de cuantización en runtime para exprimir una 4090.

Referencias

TTQ: Activation-Aware Test-Time Quantization to Accelerate LLM Inference On The Fly (marzo 2026). https://arxiv.org/abs/2603.19296
Lin, J., Tang, J., Tang, H., Yang, S., Dang, X., Han, S. AWQ: Activation-aware Weight Quantization for LLM Compression and Acceleration (MLSys 2024). https://arxiv.org/abs/2306.00978
Frantar, E., Ashkboos, S., Hoefler, T., Alistarh, D. GPTQ: Accurate Post-Training Quantization for Generative Pre-trained Transformers (ICLR 2023). https://arxiv.org/abs/2210.17323
Xiao, G., Lin, J., Seznec, M., Wu, H., Demouth, J., Han, S. SmoothQuant: Accurate and Efficient Post-Training Quantization for Large Language Models (ICML 2023). https://arxiv.org/abs/2211.10438
Dettmers, T., Lewis, M., Belkada, Y., Zettlemoyer, L. LLM.int8(): 8-bit Matrix Multiplication for Transformers at Scale (NeurIPS 2022). https://arxiv.org/abs/2208.07339

Arquitecturas nativas para device: MoE de grano fino y pre-attention router

Tue, 09 Jun 2026 01:50:00 +0000

Este post es de la serie sobre rendimiento de inferencia en modelos pequeños. Es la cara arquitectónica de un problema que ya hemos mirado por el lado del régimen de cómputo (el roofline invertido del SLM) y por el lado de la carga de pesos en Del disco a la HBM. Aquí la pregunta es distinta: ¿y si en lugar de adaptar un modelo grande al device, diseñamos el modelo para el device desde el primer commit?

TL;DR

El gesto por defecto para llevar un LLM a un portátil, un móvil o un edge box es coger un denso pensado para cloud y comprimirlo: destilación, poda, cuantización. Es un gesto de reducción: partes de algo grande y le quitas. SmallThinker (arXiv:2507.20984, SJTU IPADS + Zenergize AI) defiende el gesto inverso —diseñar desde cero— y lo articula en tres piezas. Primera: MoE de grano fino, muchos expertos pequeños con muy pocos activados por token, de modo que los parámetros totales N (la capacidad) se desacoplan de los parámetros activados A (el coste de cómputo por token). Segunda: sparse FFN, sparsity de activación tipo ReLU dentro de cada bloque, que añade un segundo nivel de dispersión sobre el primero. Tercera: un pre-attention router que predice qué expertos hará falta antes de ejecutar el bloque de atención y lanza el prefetch de esos pesos desde SSD/flash en paralelo con el cómputo de la atención, ocultando la latencia de almacenamiento —que es el cuello de botella real cuando el modelo no cabe entero en RAM. Los autores reportan SmallThinker-4B-A0.6B y SmallThinker-21B-A3B superando ~20 tok/s en CPU de consumo con Q4_0, consumiendo ~1 GB y ~8 GB de RAM. Los números son interesantes y la dirección es correcta; la metodología de evaluación y el coste de calidad de activar tan poco merecen escepticismo, y a eso dedicamos la última parte.

La analogía: el bibliotecario que se adelanta a tu pedido

Imagina una biblioteca enorme con una sala de lectura pequeña. Tú estás sentado en la sala con un único pupitre: ahí caben pocos libros a la vez (eso es la RAM). El grueso del fondo está en la trastienda, en estanterías largas y lentas de recorrer (eso es el SSD/flash). Y hay un bibliotecario.

El método ingenuo: tú lees, llegas a un punto donde necesitas un libro concreto, lo pides, y entonces el bibliotecario se levanta, va a la trastienda, lo busca y vuelve. Mientras tanto, tú esperas con la página abierta sin avanzar. Cada vez que necesitas un libro nuevo, pagas el viaje completo a la trastienda. La sala de lectura está la mayor parte del tiempo esperando, no leyendo.

El método de SmallThinker: el bibliotecario es listo y se adelanta. Mientras tú todavía estás leyendo el índice del capítulo —averiguando de qué va, relacionando ideas, lo que en el modelo es el bloque de atención—, él ya ha mirado por encima de tu hombro, ha predicho qué tres o cuatro libros vas a pedir y se ha ido a la trastienda a buscarlos. Para cuando terminas el índice y formulas el pedido, los libros ya están sobre tu pupitre. No has esperado: el viaje a la trastienda ocurrió en paralelo con tu lectura del índice.

La analogía se sostiene en cuatro detalles:

El pupitre pequeño es la RAM; la trastienda lenta es el SSD/flash.
Los libros son los expertos del MoE: solo unos pocos están sobre el pupitre en cada momento.
Leer el índice es el bloque de atención; pedir y usar los libros es el bloque FFN/expertos.
El bibliotecario que predice y se adelanta es el pre-attention router: la predicción se hace antes, y el viaje a buscar (el prefetch) se solapa con la lectura del índice (la atención).

La pregunta cuantitativa que recorre todo el post es: ¿llega el bibliotecario a tiempo? Solo se oculta la espera si el viaje a la trastienda dura menos que tu lectura del índice. Esa es la condición t_{\text{atención}} \ge t_{\text{prefetch}}, y la haremos con números.

Comprimir un denso vs. diseñar para device

Conviene poner los dos enfoques en frío, porque no son grados de lo mismo: son filosofías distintas.

Enfoque A — comprimir un denso pensado para cloud. Partes de, digamos, un modelo denso de 7B–14B entrenado para correr en una RTX 4090 (24 GB, Ada Lovelace) o en un cluster genérico 4×H100 SXM (320 GB, NVLink, FP8 nativo). Para meterlo en un device aplicas tres palancas, cada una con su post propio: destilación (entrenas un student pequeño que imita al teacher), poda (eliminas pesos o estructuras enteras) y cuantización agresiva (bajas a 4 bits o menos). El modelo resultante sigue siendo denso: todos sus parámetros se activan en cada token. Has reducido el número de parámetros, pero el patrón de cómputo es el del cloud, solo que más pequeño.

Enfoque B — diseñar para device desde cero. Aquí las restricciones del device entran en la arquitectura, no en una fase posterior de compresión. Las restricciones son tres y muy concretas:

Cómputo débil. Una CPU de portátil o un SoC móvil hace órdenes de magnitud menos FLOPs que una GPU de datacenter. Esto empuja a minimizar los parámetros activados por token, no los totales.
Poca RAM. No caben decenas de GB. Esto empuja a tener residente solo lo imprescindible y a streamear el resto.
Almacenamiento lento. El SSD o la flash a la que te ves obligado a streamear tiene un ancho de banda muy inferior al de la HBM de una GPU. Esto convierte la I/O de almacenamiento en el cuello de botella, y empuja a ocultarla.

SmallThinker es el enfoque B llevado al detalle: cada una de esas tres restricciones tiene una respuesta arquitectónica. El cómputo débil se ataca con MoE de grano fino + sparse FFN (minimizar A). La RAM escasa se ataca con streaming desde SSD (residente ≈ A + caché, no N). El almacenamiento lento se ataca con el pre-attention router (ocultar la I/O tras la atención). No es casual que las tres piezas encajen: cada una resuelve una restricción, y juntas se refuerzan.

Un matiz importante, para no caer en el hype: el enfoque B no es gratis ni universalmente superior. Requiere entrenar un modelo nuevo (no reutilizas pesos existentes), y el techo de calidad de un modelo con A muy pequeño está intrínsecamente acotado, como veremos. El argumento no es “B gana siempre”, sino “para el régimen del device, B ataca los cuellos correctos, y A solo los ataca de refilón”.

Dos niveles de sparsity

La idea central de capacidad es vieja y bien entendida en MoE: separar capacidad de coste de cómputo. En un MoE, el modelo tiene N parámetros totales repartidos en expertos, pero para cada token solo se activan A parámetros (los del top-k de expertos que el router elige). El coste de cómputo por token escala con A; la capacidad de conocimiento escala con N. SmallThinker aplica esta idea en dos niveles superpuestos.

Nivel 1 — MoE de grano fino. “Grano fino” significa muchos expertos pequeños en vez de pocos expertos grandes, con muy pocos activados por token. En vez de, digamos, 8 expertos de los que activas 2, tienes decenas de expertos de los que activas un puñado. Con expertos más pequeños, el mismo A se reparte entre más combinaciones posibles, lo que da granularidad fina al router y mantiene A muy bajo respecto a N. El resultado es un cociente N/A agresivo: mucha capacidad, poquísimo cómputo por token.

Nivel 2 — sparse FFN (sparsity de activación tipo ReLU). Este nivel es ortogonal y opera dentro de cada FFN. Con una no-linealidad tipo ReLU, una fracción grande de las neuronas de la capa intermedia produce exactamente cero para un token dado. Una neurona que sale a cero no contribuye nada a la salida: su multiplicación matriz-vector se puede saltar. Esto es sparsity de activación: predecible token a token, y aprovechable para no cargar ni multiplicar las filas/columnas de peso correspondientes a neuronas inactivas. Es el mismo fenómeno que explotan trabajos como Deja Vu o PowerInfer; SmallThinker lo incorpora de fábrica eligiendo activaciones que lo favorecen.

El efecto combinado, en una frase: N grande (capacidad), A minúsculo (coste de cómputo por token ≈ proporcional a A), y además dentro de ese A una fracción de las multiplicaciones se ahorra por la sparsity de activación. Es sparsity sobre sparsity.

8 expertos grandes · activa 2 A grande por experto · granularidad gruesa

muchos expertos pequeños · activa pocos A total bajo · granularidad fina

+ sparse FFN dentro de cada experto activo: neuronas a 0 (ReLU) → se saltan en el cómputo

Capacidad = N (todos los expertos) · Coste/token ≈ A (activados) · y dentro de A, sparse FFN ahorra más El truco: subir N sin subir A. La granularidad fina permite un cociente N/A mucho más agresivo.

El pre-attention router: predecir y prefetchar

Aquí está la pieza específica del paper, y la que da nombre al post. El problema que resuelve es de scheduling de I/O, no de calidad.

Cuando el modelo no cabe entero en RAM, los pesos de los expertos viven en SSD/flash y se cargan bajo demanda. El flujo ingenuo de una capa MoE es secuencial: ejecutas la atención, luego el router decide qué expertos tocan, luego cargas esos expertos desde SSD (esperando), luego ejecutas la FFN de esos expertos. El paso de carga es una espera pura: la CPU está bloqueada esperando bytes del SSD. En el régimen del device, donde el SSD es lento, ese tiempo de espera domina el step de decode.

El pre-attention router rompe la secuencialidad invirtiendo el orden de la decisión. La observación es que el router no necesita la salida de la atención de esta misma capa para hacer una predicción razonable de qué expertos harán falta: puede predecirlo a partir del estado que ya tiene antes de ejecutar la atención. Así que:

Antes de ejecutar el bloque de atención de la capa, el router predice los expertos que se necesitarán.
Lanza el prefetch de esos expertos desde SSD/flash de forma asíncrona.
En paralelo, la CPU ejecuta el bloque de atención —que es cómputo puro, no necesita el SSD.
Cuando la atención termina, los expertos prefetchados ya están (idealmente) en RAM, y la FFN procede sin esperar.

El I/O de almacenamiento se ha solapado con el cómputo de atención. Es exactamente el bibliotecario que va a la trastienda mientras tú lees el índice.

Ingenuo (secuencial): la carga desde SSD bloquea atención router carga expertos desde SSD (espera bloqueante) FFN expertos t_total = t_att + t_load + t_ffn

Pre-attention router: el prefetch se solapa con la atención

hilo de cómputo (CPU) router (pre) atención (t_att) FFN expertos

hilo de I/O (SSD) prefetch expertos (t_prefetch)

El prefetch queda oculto si t_att ≥ t_prefetch: para cuando la atención termina, los expertos ya están en RAM. Si t_prefetch > t_att, asoma una burbuja de espera (t_prefetch − t_att) antes de la FFN. Ese es el caso a evitar.

La condición de ocultamiento es la desigualdad de arriba: el prefetch se oculta completamente si y solo si

$$t_{\text{atención}} ;\ge; t_{\text{prefetch}}.$$

Si la atención tarda más que cargar los expertos, la carga es gratis (ya estaba hecha). Si los expertos son demasiado grandes o el SSD demasiado lento, t_prefetch > t_att y asoma una burbuja de espera igual a t_prefetch − t_att. Por eso el diseño necesita que A sea pequeño (expertos pequeños → menos bytes a prefetchar → t_prefetch bajo) y que el grano sea fino: las dos cosas que hace el nivel 1 de sparsity no son solo para ahorrar FLOPs, son para que el prefetch quepa debajo de la atención.

Las matemáticas que importan

Footprint de memoria: N residente vs. A + caché

El parámetro que decide si el modelo cabe es cuánto tienes que tener residente en RAM a la vez.

Todo en RAM. Si exiges que todos los expertos estén cargados, el footprint es \approx N (todos los parámetros, multiplicados por bytes/parámetro según la cuantización). Para un 21B esto es prohibitivo en un device.
Streaming desde SSD. Si solo mantienes residentes los expertos activos más una caché de los recientes/probables, el footprint cae a \approx A + \text{caché}. Los pesos que no están en RAM viven en SSD y se prefetchan cuando toca. Aquí está el ahorro real: el residente escala con A, no con N.

La parte no-experta del modelo (embeddings, atención, router, layernorms) sí está siempre residente, pero en un MoE de grano fino el grueso de N está en los expertos, así que la aproximación residente ≈ A + caché + parte_densa es buena.

El cálculo de prefetch, con números

Pongamos los números de la analogía. Supón un SSD de consumo a 5 GB/s de lectura secuencial y un experto cuantizado de tamaño X MB. El tiempo de cargar un experto es

$$t_{\text{1 experto}} = \frac{X \text{ MB}}{5000 \text{ MB/s}} = \frac{X}{5000}\ \text{s} = \frac{X}{5}\ \text{ms}.$$

Concretemos X. En SmallThinker-4B-A0.6B con Q4_0 (~0.5 byte/param efectivo contando overhead de bloques), un experto pequeño de, digamos, 4M parámetros pesa \approx 4\text{M} \times 0.5 = 2 MB. Cargarlo cuesta t_{\text{1 experto}} = 2/5 = 0.4 ms.

Ahora la pregunta de scheduling: si el bloque de atención de la capa toma Y ms, ¿cuántos expertos puedo prefetchar mientras la atención corre? El número es

$$n_{\text{prefetch}} = \left\lfloor \frac{Y}{t_{\text{1 experto}}} \right\rfloor = \left\lfloor \frac{Y \cdot 5}{X} \right\rfloor.$$

Con Y = 2 ms de atención y X = 2 MB por experto: n_{\text{prefetch}} = \lfloor 2 \times 5 / 2 \rfloor = 5 expertos. Es decir, en la ventana de atención de esa capa el SSD alcanza a traer 5 expertos. Si el top-k de la capa activa ≤ 5 expertos, el prefetch los oculta todos y t_prefetch ≤ t_att: latencia de carga cero. Si la capa necesitara 8 expertos, traerías 5 gratis y pagarías la carga de los 3 restantes como burbuja: (8-5) \times 0.4 = 1.2 ms de espera por capa. De ahí que el diseño quiera grano fino con top-k pequeño: para caber debajo de la ventana de atención.

Dos observaciones críticas sobre este cálculo:

Los 5 GB/s son lectura secuencial idealizada. Los expertos están dispersos en disco; lecturas aleatorias 4K en un SSD de consumo van mucho más lentas. El ancho de banda efectivo puede ser una fracción del nominal, lo que reduce n_{\text{prefetch}}. La metodología que reporte tok/s debería decir si mide con expertos pre-ordenados en disco o con acceso realista.
La ventana Y de atención encoge con el contexto corto y al inicio de la generación. Con prompts cortos, la atención es barata y puede que no cubra el prefetch; la ventaja del solapamiento crece con secuencias más largas. Otro detalle que un benchmark honesto debería desglosar.

Footprint de pesos: por qué reportan ~1 GB para un 4B

Hagamos la cuenta del 4B en Q4_0. Cuantización a 4 bits ≈ 0.5 byte/param, más un pequeño overhead de escalas por bloque (Q4_0 añade un FP16 de escala cada 32 pesos, ~0.56 byte/param efectivos). Entonces:

$$4\text{B} \times 0.5\ \text{B/param} \approx 2\ \text{GB}.$$

Es decir, el modelo completo en Q4_0 ocupa ~2 GB en disco. Pero los autores reportan ~1 GB de RAM. ¿Contradicción? No, y entender por qué es entender el diseño:

No todos los expertos están residentes. Solo los activados (A = 0.6B) y una caché caben en RAM; el resto vive en SSD y se streamea. 0.6\text{B} \times 0.5 \approx 0.3 GB de expertos activos, más la parte densa (atención, embeddings, router) y una caché de expertos calientes.
La sparse FFN reduce el trabajo y el residente útil. Las neuronas que salen a cero no necesitan estar materializadas para ese token.

Sumando expertos activos + parte densa + caché razonable, ~1 GB es plausible. Pero ojo con el matiz: ~1 GB es el residente en RAM, no el footprint total en almacenamiento, que sigue siendo ~2 GB en SSD. Confundir ambos —reportar “1 GB” a secas— es engañoso si el lector entiende “el modelo ocupa 1 GB”. Ocupa 2 GB; mantiene 1 GB en RAM. La distinción importa para un device con 2 GB de almacenamiento libre: ahí no entra.

Análogamente, SmallThinker-21B-A3B: 21\text{B} \times 0.5 \approx 10.5 GB en disco; 3\text{B} \times 0.5 \approx 1.5 GB de expertos activos, y el ~8 GB de RAM reportado incluye expertos activos + caché generosa + parte densa. La caché grande es lo que sube de 1.5 a ~8 GB: mantienes muchos expertos calientes residentes para no golpear el SSD constantemente.

El coste de calidad: el escepticismo necesario

Toda la maquinaria anterior reduce el cómputo por token a \approx A. Pero A = 0.6B activados es muy poco. Aquí es donde hay que poner el freno al entusiasmo:

Capacidad de razonamiento acotada. Un modelo que activa 0.6B de parámetros por token tiene, por token, la potencia de cómputo de un modelo de 0.6B, no de 4B. La capacidad total N=4B ayuda a almacenar más conocimiento (más expertos especializados), pero el procesamiento de cada token sigue limitado por A. Para tareas que requieren composición y razonamiento multi-paso intensivo, esto es un techo real, no un detalle.
El router es un punto único de fallo de calidad. Si el router de grano fino elige mal los expertos —y con grano fino hay más decisiones que tomar—, la calidad cae sin que ninguna métrica de velocidad lo refleje. El pre-attention router agrava esto: predice los expertos antes de ver la atención, con menos información que un router post-atención. Los autores deberían reportar cuánta calidad se pierde por predecir antes (mismatch entre experto prefetchado y experto que el router post-atención habría elegido).
Los ~20 tok/s necesitan letra pequeña. ¿En qué CPU exactamente? ¿Con qué longitud de contexto y de generación (la ventaja del solapamiento depende de Y)? ¿Cold start incluido o steady state? ¿El SSD estaba con los expertos pre-ordenados secuencialmente? Un “supera 20 tok/s” sin esas condiciones es un número de marketing, no de metodología.
Comparación justa. La pregunta correcta no es “¿es rápido?”, sino “¿a igualdad de calidad en un benchmark independiente, es más rápido o más pequeño que un denso comprimido equivalente?”. Eso requiere evals que el lector pueda reproducir, no solo tok/s en la máquina de los autores.

Nada de esto invalida la dirección. Diseñar para device es, conceptualmente, el enfoque correcto: ataca los cuellos reales (cómputo, RAM, I/O) en la arquitectura en vez de paliarlos después. Pero “20 tok/s en ~1 GB” es una afirmación de eficiencia, y la eficiencia solo significa algo anclada a un nivel de calidad medido honestamente. Mientras esa ancla no esté clara, el número correcto de escepticismo es alto.

Implicaciones para inferencia on-premise y edge

El SSD pasa a ser parte de la jerarquía de inferencia. En cloud, la jerarquía es HBM → RAM. En device, el SSD/flash entra como un nivel más, y su ancho de banda y latencia de acceso aleatorio se vuelven parámetros de rendimiento de primer orden. Esto conecta con Del disco a la HBM: el cold start y el streaming de pesos dejan de ser solo un problema de arranque y pasan a ser parte del steady state.
El edge box heterogéneo gana sentido. En un patrón de entornos mixtos, un modelo nativo-device como SmallThinker corre en el NUC/edge con CPU y SSD, sirviendo localmente, mientras lo pesado se queda en el cluster central. El pre-attention router es lo que hace viable el edge box sin GPU.
El capacity planning cambia de ejes. Como discute Capacity planning de inferencia, en device el recurso a planificar no es VRAM sino la terna RAM-residente / ancho-de-banda-SSD / FLOPs-de-CPU. Un modelo con A pequeño y prefetch solapado mueve el cuello de botella de “¿cabe en RAM?” a “¿el SSD alimenta el prefetch a tiempo?”.

Conclusión

SmallThinker es, sobre todo, un cambio de pregunta. No “¿cómo encojo este modelo cloud para que quepa en el device?” sino “¿cómo sería el modelo si lo diseñara para el device desde el primer parámetro?”. La respuesta —MoE de grano fino para desacoplar N de A, sparse FFN para ahorrar dentro de A, y un pre-attention router que oculta la I/O de almacenamiento bajo la atención— ataca las tres restricciones del device (cómputo, RAM, I/O) en la arquitectura, no en una fase de compresión posterior. La condición clave, t_att ≥ t_prefetch, explica por qué las piezas encajan: el grano fino no solo ahorra FLOPs, hace que el prefetch quepa debajo de la atención. Los números reportados (~20 tok/s, ~1 GB / ~8 GB de RAM) son prometedores y la dirección es sólida; el coste de activar tan poco y la falta de detalle metodológico sobre calidad piden cautela. Diseñar para device es la apuesta correcta; medirlo honestamente es la asignatura pendiente.

Ver también

MoE inference: el call center con 256 especialistas — la base conceptual de este post: cómo un router enruta tokens a expertos y por qué N y A se desacoplan; léelo primero si MoE te suena lejano.
Del disco a la HBM: cold start y carga de modelo — el streaming de pesos desde almacenamiento lento, que aquí deja de ser problema de arranque y pasa a steady state vía prefetch.
Knowledge distillation — la palanca canónica del enfoque “comprimir un denso de cloud”, el contrapunto exacto del enfoque nativo-device.
Poda de modelos LLM — la otra palanca de reducción; útil para comparar “quitar a un grande” frente a “diseñar pequeño desde cero”.
Entornos mixtos NVIDIA + Intel — dónde encaja un modelo nativo-device: el edge box con CPU y SSD que sirve localmente sin GPU.
Capacity planning de inferencia LLM on-premise — en device los ejes a planificar son RAM-residente, ancho de banda de SSD y FLOPs de CPU, no VRAM.
Roofline invertido en modelos pequeños (hermano de esta serie, próximamente) — el régimen de rendimiento del SLM que explica por qué A pequeño mantiene el decode memory-bound y dónde está el techo real.
Self-speculative decoding con early-exit (hermano de esta serie, próximamente) — self-spec aplicado a MoE on-device: cómo acelerar el decode sin draft externo cuando el modelo ya es pequeño.
Cuantización agresiva sub-4-bit y ternaria (hermano de esta serie, próximamente) — Q4_0 y más allá en device: ternario y 2-bit para bajar aún más el footprint de expertos en SSD.

Referencias

Equipo SmallThinker (SJTU IPADS + Zenergize AI). SmallThinker: A Family of Efficient Large Language Models Natively Trained for Local Deployment. arXiv:2507.20984. https://arxiv.org/abs/2507.20984
Repositorio oficial SmallThinker: https://github.com/SJTU-IPADS/SmallThinker
Self-Speculative Decoding for On-device MoE Acceleration. ACM The Web Conference (WWW) 2026. doi:10.1145/3774904.3792218. https://doi.org/10.1145/3774904.3792218
Liu, Z. et al. Deja Vu: Contextual Sparsity for Efficient LLMs at Inference Time. ICML 2023. https://arxiv.org/abs/2310.17157
Song, Y. et al. PowerInfer: Fast Large Language Model Serving with a Consumer-grade GPU (sparse activation + hot/cold experts). SJTU IPADS, 2023. https://arxiv.org/abs/2312.12456

Self-speculative decoding: el modelo que se adelanta a sí mismo

Tue, 09 Jun 2026 01:40:00 +0000

Este post es el complemento directo de Speculative decoding: el secretario que adelanta. Allí draft y target son dos modelos distintos; aquí son el mismo modelo a dos profundidades. Léelo primero: damos por sabidos el rejection sampling, el techo 1/(1-α) y la fórmula del speedup, y aquí solo cambiamos qué es el draft.

TL;DR

Speculative decoding clásico exige una pareja: un modelo draft barato propone γ tokens y un target caro los verifica en un único forward pass paralelo. En modelos grandes el draft puede ser un 1 % del target y caber holgado. En modelos pequeños (SLM, 1B–8B) esa receta se rompe por dos lados: un draft que sea 1/10 de un 3B es un 0.3B que apenas acierta (α se desploma), y cargar un segundo modelo —por pequeño que sea— dobla las piezas a mantener y se come VRAM que en una 4090 o en device no sobra. Self-speculative decoding resuelve ambos: el draft es el propio modelo ejecutado de forma superficial. Un modelo de L capas produce tokens borrador saliendo en una capa intermedia k < L (early-exit) o saltando un subconjunto de capas (layer-skip), y luego verifica esos tokens con el forward completo de las L capas. Como draft y verify comparten pesos y comparten el KV cache de las capas comunes, el coste extra de memoria es cero: no hay un segundo modelo, no hay un segundo KV cache, no hay nada nuevo que cargar. El precio es que el draft early-exit es más caro que un draft externo minúsculo (recorre k/L del modelo en vez de un 1 %), así que el coste relativo c sube. El trade-off honesto: con draft dedicado bien entrenado (EAGLE-3) que quepa en memoria, su α suele ser mayor y gana; self-spec gana cuando no hay draft entrenado, no cabe, o estás en device.

La analogía: el ajedrecista que juega a ojo y luego calcula

Un buen jugador de ajedrez hace dos cosas con el mismo cerebro. Primero mira el tablero y, a ojo, en medio segundo, propone una jugada “que pinta bien”: es intuición de patrones, reconocimiento rápido, las capas superficiales del juicio. Después, antes de mover, calcula a fondo: tres jugadas por delante, las respuestas del rival, las líneas tácticas. Ese cálculo profundo confirma la intuición o la corrige.

Lo decisivo es que es la misma persona haciendo de borrador y de revisor. No contrata a un segundo ajedrecista más débil para que adivine la jugada y luego él la valida —eso sería el speculative clásico con draft externo—. Aquí el borrador rápido y la verificación lenta salen del mismo cerebro, recorrido a dos profundidades.

La analogía se sostiene punto por punto:

El vistazo a ojo es el forward early-exit: el modelo recorre solo las primeras k capas y emite un token borrador. Rápido, aproximado.
El cálculo a fondo es el forward completo de las L capas, que verifica el borrador con rejection sampling exacto.
Que sea la misma persona es el reuso de pesos y de KV cache: las k capas superficiales del draft son literalmente las mismas que las k primeras capas del verify; lo ya computado no se recomputa.
Que la jugada final sea idéntica a la que el jugador habría elegido calculando siempre a fondo es la garantía de rejection sampling: la calidad del output no se degrada (la prueba está en el post de speculative).

Por qué el draft externo no encaja en modelos pequeños

Repasemos el coste del speculative clásico con dos números. El speedup depende de la tasa de aceptación α (cuánto acierta el draft) y del coste relativo c = T_draft / T_target. Un draft útil necesita α alto y c bajo a la vez. En modelos grandes eso es alcanzable: un draft de 1B para un target de 70B tiene c ≈ 0.015 y, si está bien destilado (EAGLE), α > 0.8. El producto sale rentable.

En un modelo pequeño el equilibrio se rompe:

El draft proporcional es inservible. Si quieres c ≈ 0.1 para un target de 3B, tu draft es un ~0.3B. Un 0.3B genérico tiene una distribución tan distinta del 3B que α cae a la zona 0.3–0.5. Y 1/(1-α) con α = 0.4 es un techo de 1.67 tokens/step: ni con γ infinito sacas más. El premio se evapora.
Cargar un segundo modelo dobla las piezas. Aunque el draft sea pequeño en VRAM, es otro checkpoint que versionar, cuantizar, validar y servir, y tiene su propio KV cache. En una RTX 4090 (24 GB, Ada Lovelace) con un 8B cuantizado y un contexto largo, el KV cache ya aprieta; meter un segundo modelo y su cache puede forzarte a bajar la concurrencia o el contexto máximo. En device (un móvil, un NUC, un edge box) directamente no hay sitio.
No siempre existe un draft entrenado para tu modelo exótico o fine-tuneado. EAGLE necesita entrenar el draft on-policy contra ese target concreto (ver knowledge distillation). Si tu SLM es un fine-tune propio, no hay draft oficial publicado.

Self-speculative ataca los tres a la vez con una idea: no traigas un segundo modelo; usa el primero a media profundidad.

El mecanismo: early-exit como draft, forward completo como verify

Un transformer de L capas, en cada posición, transforma el hidden state capa a capa: h_0 → h_1 → ... → h_L, y la LM head proyecta h_L a logits. La observación que lo habilita todo: h_k para k < L ya es un hidden state razonable. Si lo pasas por la misma LM head (o por una head ligera dedicada), obtienes una distribución de salida “prematura” pero a menudo correcta para los tokens fáciles. Esa es la fuente del borrador.

La iteración de self-speculative tiene la misma estructura que el speculative clásico —draft, verify, accept/reject— pero ambos roles son el mismo modelo:

Paso 1 — Draft superficial. Para producir γ tokens borrador, el modelo recorre solo las primeras k capas (o un subconjunto de capas en el caso layer-skip) y aplica la LM head. Cada token borrador cuesta ≈ k/L de un forward completo. Llamamos c = k/L al coste relativo del draft. Los γ borradores se generan autoregresivamente a este coste reducido.

Paso 2 — Verify completo. El modelo ejecuta un único forward pass de las L capas sobre prompt + x_1...x_γ. Por la atención causal obtiene p(·|prompt, x_<i) para cada posición, exactamente igual que en el speculative clásico.

Paso 3 — Accept/reject. Rejection sampling idéntico al del post anterior: se aceptan tokens de izquierda a derecha, se corrige en la primera divergencia muestreando del residual norm(max(0, p−q)), y si se aceptan los γ se añade el token bonus. La calidad del output es exactamente la del modelo completo.

El truco que hace `c` aún más barato: reuso de KV cache de capas compartidas

Aquí está la diferencia clave frente a un draft externo. Cuando el modelo hace el draft recorriendo las capas 0..k, calcula y almacena el KV cache de esas k capas para los tokens del prompt y los borradores. Cuando llega el verify completo, las capas 0..k del forward de L capas son bit a bit las mismas operaciones sobre los mismos pesos que ya hizo el draft. No hay que recomputarlas: el verify reusa directamente el KV cache que el draft dejó para las capas 0..k, y solo computa de verdad las capas k..L que faltan.

Eso tiene dos consecuencias:

Memoria extra cero. No hay un segundo KV cache. El KV de las capas comunes es uno solo, compartido entre draft y verify. Contrasta con vanilla SD, donde el draft tiene su propio cache completo (ver KV cache).
Cómputo parcialmente reusado. El verify solo paga las capas k..L “nuevas” para los tokens que ya pasaron por el draft. El forward completo no es tan caro como sugiere L, porque las primeras k capas vienen del cache.

DRAFT · early-exit en k=8 capas 0..8 recorrido superficial coste ≈ k/L = 0.25 LM head → borrador x₁ x₂ x₃ x₄ (γ=4)

VERIFY · forward completo L=32 capas 0..8 (reusadas, no se recomputan) capas 8..32 cómputo nuevo LM head → p(·)

KV cache COMPARTIDO capas 0..8 · un solo cache memoria extra = 0

escribe KV 0..8 lee KV 0..8

Rejection sampling (idéntico al speculative clásico) x₁ ✓ x₂ ✓ x₃ ✓ x₄ ✗ Output = exactamente el del modelo completo · 0 modelos extra · 0 KV extra El draft y el verify son el mismo modelo; las capas 0..8 se computan una sola vez.

Las familias (estado 2026)

No hay una sola forma de hacer self-speculative. Difieren en qué capas se saltan y en si hace falta entrenar.

Familia	Año / venue	Cómo elige qué saltar	¿Entrenamiento?	Idea distintiva
LayerSkip (Elhoushi et al.)	2024, arXiv:2404.16710	Early-exit en capa fija `k`; una sola LM head sirve a todas las salidas	Sí — layer dropout + early-exit loss en train/fine-tune	Un único modelo entrenado para hacer draft y verify; reusa cómputo parcial
SWIFT	ICLR 2025 (OpenReview EKJhH5D5wA)	Selecciona qué capas saltar on-the-fly, sin tocar pesos	No — plug-and-play sobre el modelo dado	Self-spec training-free: optimiza el conjunto de capas saltadas en caliente
CLaSp	2025, arXiv:2505.24196	In-context layer skip dinámico: el patrón de capas saltadas se adapta al contexto	No (dinámico en inferencia)	El skip no es fijo; cambia según lo que se está generando
ConfLayers	2026, arXiv:2604.14612	Salta capas según confianza del estado intermedio (adaptativo por token)	No (criterio de confianza)	Profundidad variable: tokens fáciles salen antes, difíciles llegan más hondo
Saguaro	2025–26	Formulación asíncrona: el draft sigue especulando en paralelo mientras corre la verificación	Depende de la variante	Solapa draft y verify en el tiempo en lugar de alternarlos
SSD para MoE on-device	ACM Web Conf. 2026, doi 10.1145/3774904.3792218	Self-spec aprovechando la sparsity del MoE (pocos expertos activos por token)	Variante específica MoE	El draft superficial activa aún menos expertos; encaja con MoE en device

Tres lecturas operacionales de la tabla:

El eje que más importa es entrenamiento sí/no. LayerSkip da el mejor α porque el modelo aprende a ser un buen draft superficial (con early-exit loss las capas intermedias se entrenan explícitamente para predecir bien). Pero exige fine-tune. SWIFT, CLaSp y ConfLayers son training-free: peor α, pero se aplican a cualquier modelo ya entrenado sin tocar nada. Para un SLM que no controlas, training-free es lo realista.
El skip adaptativo (CLaSp, ConfLayers) sube α porque ajusta la profundidad del draft al token: gasta poco en lo fácil y más en lo difícil, en vez de un k fijo. A cambio, el c efectivo deja de ser constante.
Saguaro ataca otra cosa: no sube α, solapa el tiempo de draft y verify. Es ortogonal al resto y combinable.

La matemática: mismo marco, distinto `c`

Reutilizamos el aparato del post de speculative sin cambiar una letra. Con α la tasa de aceptación y γ el número de borradores:

$$E[\text{tokens por step}] = \frac{1 - \alpha^{\gamma+1}}{1 - \alpha}, \qquad \text{Speedup} = \frac{1 - \alpha^{\gamma+1}}{(1 - \alpha)(\gamma c + 1)}$$

Y el techo algorítmico es el mismo: lim_{γ→∞} = 1/(1-α). Lo único que cambia en self-speculative es el valor de c: ya no es el ratio de tamaños de dos modelos, sino c = k/L, la fracción de capas que recorre el draft early-exit.

Ejemplo numérico: self-spec con L=32, salida en k=8

Tomemos un SLM de L = 32 capas que sale en k = 8 para el draft: c = k/L = 8/32 = 0.25. Supongamos α = 0.7 (razonable para early-exit en tokens conversacionales) y γ = 4.

Tokens esperados por step: (1 − 0.7⁵) / (1 − 0.7) = (1 − 0.168) / 0.3 = 0.832 / 0.3 = 2.77
Speedup: 2.77 / (4 × 0.25 + 1) = 2.77 / 2.0 = 1.39×

El factor del denominador es γc + 1 = 4·0.25 + 1 = 2.0: el draft early-exit, al costar un cuarto del modelo cada token, se come parte del beneficio. Salir más arriba ayuda: con k = 4 (c = 0.125), denominador = 1.5 y speedup = 2.77/1.5 = 1.85× — pero salir más arriba normalmente baja α, así que hay tensión real entre k pequeño (barato) y α alto (acierta).

Comparación honesta con un draft externo

Pongamos al lado un draft externo minúsculo bien destilado: c = 0.1 y α = 0.78 (lo que un EAGLE-style draft puede dar), mismo γ = 4.

Tokens/step: (1 − 0.78⁵)/(1 − 0.78) = (1 − 0.289)/0.22 = 0.711/0.22 = 3.23
Speedup: 3.23 / (4 × 0.1 + 1) = 3.23 / 1.4 = 2.31×

Configuración	c	α	tokens/step	speedup	VRAM extra	piezas a mantener
Self-spec early-exit (k=8)	0.25	0.70	2.77	1.39×	0	0
Self-spec early-exit (k=4)	0.125	0.65	2.50	1.67×	0	0
Draft externo destilado	0.10	0.78	3.23	2.31×	sí (+modelo +KV)	1 modelo extra

La lectura es exactamente la que cabe esperar y conviene no maquillar: si tienes un draft dedicado, entrenado contra tu target, y cabe en memoria, su α mayor y su c menor le dan más speedup. EAGLE-3 con draft bien entrenado suele ganar en speedup bruto. Self-spec no compite en speedup bruto; compite en coste total. Sus columnas ganadoras son las dos de la derecha: cero VRAM extra y cero piezas que mantener. Self-spec gana cuando:

no hay draft entrenado para tu modelo (SLM propio, fine-tune raro),
el draft no cabe (4090 ya llena, contexto largo que necesita el KV),
estás en device (móvil, NUC, edge), donde un segundo modelo y su KV simplemente no entran.

Es el mismo patrón que con MTP en el post anterior: a veces el mejor draft es el que no tienes que cargar.

Por qué encaja justo con modelos pequeños y device

El régimen donde self-spec brilla es el de baja concurrencia, memory-bandwidth-bound, con presupuesto de memoria escaso — exactamente el de un SLM en una sola GPU o en device (el porqué del régimen está en el roofline invertido). Tres razones:

Cero memoria extra es decisivo donde no sobra. En una RTX 4090 (24 GB, Ada Lovelace) sirviendo un 7B–8B cuantizado con contexto largo, cada GB cuenta. Self-spec no pide ni uno: reusa pesos y KV. Un draft externo, aunque pequeño, te obliga a recortar contexto o concurrencia. En device la diferencia es binaria: con self-spec aceleras; con draft externo no hay sitio y punto.
No hay segundo checkpoint que versionar. Operacionalmente, un SLM en edge desplegado en cientos de cajas se vuelve insostenible si cada una necesita dos modelos sincronizados. Un solo binario que hace draft y verify es muchísimo más simple de mantener.
Encaja con MoE en device. En un MoE de grano fino para device (ver arquitecturas nativas para device), el draft superficial activa aún menos expertos, y el régimen memory-bound persiste incluso a batch medio — justo lo que el trabajo de SSD para MoE on-device (ACM WWW 2026) explota.

El contrapunto, repetido para que no se olvide: en un cluster genérico 4×H100 SXM (320 GB, NVLink, FP8 nativo), donde la memoria no es el cuello de botella, un draft EAGLE-3 dedicado sí cabe y su α mayor le da más speedup. Allí self-spec es plan B: lo usas si el modelo es exótico y no hay draft entrenado, no porque la memoria apriete.

Pitfalls

El α depende muchísimo de k. Salir demasiado arriba (k pequeño) abarata el draft pero hunde α; salir demasiado abajo (k cercano a L) sube α pero el draft cuesta casi un forward completo y c → 1, matando el speedup. El óptimo es empírico y específico del modelo. Desconfía de cualquier número de speedup que no diga en qué k se midió.
Training-free no es gratis en calidad de draft. SWIFT/CLaSp dan α menores que LayerSkip precisamente porque las capas intermedias del modelo no se entrenaron para ser buenas salidas prematuras. El número que importa es α medido en tu distribución, no el del paper.
Sampling temperature y outputs creativos bajan α igual que en el speculative clásico. A T alta, el speedup de self-spec se erosiona más rápido todavía porque parte de un α más bajo.
Batch grande lo neutraliza igual que al speculative clásico. En cuanto el decode pasa a compute-bound, los borradores dejan de ser “casi gratis”. Self-spec es para baja concurrencia.

Ver también

Speculative decoding: el secretario que adelanta — el complemento directo y prerequisito: draft + verify + rejection sampling, el techo 1/(1-α) y la fórmula del speedup que aquí reutilizamos tal cual.
El roofline invertido en modelos pequeños — por qué el SLM vive en régimen memory-bound, que es justo lo que habilita cualquier forma de speculative.
Arquitecturas nativas para device: MoE de grano fino — dónde aterriza el self-spec sobre MoE en device, aprovechando la sparsity del router.
KV cache: la memoria de trabajo — el reuso del KV de las capas compartidas entre draft y verify es lo que hace que la memoria extra sea cero; aquí está el mecanismo del cache.
Knowledge distillation — el early-exit loss de LayerSkip es pariente de la destilación: enseña a las capas intermedias a predecir como el modelo completo.
Poda de modelos LLM — saltar capas es una forma de poda estructurada en inferencia; layer-skip y layer-dropping comparten raíz conceptual.
MoE inference: el call center con 256 especialistas — el régimen memory-bound persistente del MoE hace que el self-spec sobre MoE gane incluso a batch medio.
Optimizando el decode en vLLM — dónde se configuran en la práctica los métodos speculative en producción.
Entornos mixtos NVIDIA + Intel — el caso device/edge donde “cero modelo extra” deja de ser una comodidad y pasa a ser la única opción viable.

Referencias

Elhoushi, M., et al. LayerSkip: Enabling Early Exit Inference and Self-Speculative Decoding. 2024. https://arxiv.org/abs/2404.16710
SWIFT: On-the-Fly Self-Speculative Decoding for LLM Inference Acceleration. ICLR 2025. https://openreview.net/forum?id=EKJhH5D5wA
CLaSp: In-Context Layer Skip for Self-Speculative Decoding. 2025. https://arxiv.org/abs/2505.24196
ConfLayers: Confidence-Adaptive Layer Skipping for Self-Speculative Decoding. 2026. https://arxiv.org/abs/2604.14612
Self-Speculative Decoding for MoE on Device. ACM Web Conference 2026. https://doi.org/10.1145/3774904.3792218
Hugging Face blog. Faster Text Generation with Self-Speculative Decoding. https://huggingface.co/blog/layerskip
Leviathan, Y., Kalman, M., Matias, Y. Fast Inference from Transformers via Speculative Decoding. ICML 2023. https://arxiv.org/abs/2211.17192

El roofline se invierte: por qué optimizar modelos pequeños es otro partido de rendimiento

Tue, 09 Jun 2026 01:30:00 +0000

Este post es el ancla de una mini-serie sobre rendimiento de inferencia en modelos pequeños (SLM). Casi todos los posts de optimización del blog —KV cache, decode, quantization— se escribieron con un 70B en la cabeza. Aquí defiendo que cuando el modelo encoge un orden de magnitud, el roofline cambia de régimen y varias de esas intuiciones se invierten. No es un matiz: es otro partido.

TL;DR

El decode autoregresivo de un LLM grande está memory-bandwidth-bound: en cada step hay que mover todos los pesos del modelo desde la HBM hasta los registros de los SM, y eso domina sobre las operaciones aritméticas. La GPU se pasa el rato esperando bytes, no calculando. Esa única frase —que el decode “espera a la HBM”— es la raíz de la mitad de las optimizaciones del blog. En un modelo pequeño (SLM, digamos 0.5B–7B) la frase deja de ser cierta de la forma simple en que la contábamos. A batch 1 sigues siendo memory-bound respecto al hardware, sí, pero el forward pass es tan barato (mover 6 GB a 1 TB/s son ~6 ms, no 70 ms) que los costes fijos por step —lanzamiento de kernels, overhead del scheduler de Python, el sampler, las copias host↔device, los synchronize— dejan de ser ruido y pasan a comerse un 20-30 % del tiempo. El cuello se desplaza de la HBM a la orquestación. Consecuencias concretas y cuantitativas: (1) los CUDA graphs y reducir el overhead del scheduler rinden más en SLM que en modelos grandes; (2) la cuantización de pesos da menos mejora de latencia a batch 1 en SLM, porque proporcionalmente hay menos pesos que mover frente a activaciones, KV cache y overhead fijo; (3) el batching tiene más headroom porque cruzas el ridge point tarde; (4) el KV cache puede dominar la memoria relativa. Todo esto sale de un único modelo —el roofline— aplicado con honestidad numérica.

La analogía: la despensa y el camarero

Una cocina con dos servicios muy distintos.

Servicio de degustación, un plato enorme y lento (el LLM de 70B). Cada plato lleva ingredientes pesados que el ayudante tiene que ir a buscar a la despensa del fondo, varias veces, cargando cajas. El cocinero, en cambio, monta el plato en un momento: lo lento es traer los ingredientes, no cocinarlos. Si quieres que el servicio vaya más rápido, no compras un cocinero más hábil: ensanchas el pasillo a la despensa o haces que cada viaje traiga más cajas. La despensa es la HBM; el viaje es el ancho de banda de memoria; cocinar es el compute. El plato grande está bound por la despensa.

Servicio de tapas, platillos minúsculos (el SLM). Ahora cada tapa lleva dos ingredientes y se monta en un segundo. El viaje a la despensa por tapa es brevísimo. Pero aparece un coste que en el plato grande era despreciable: el camarero. Por cada tapa, el camarero tiene que ir a la cocina, recoger el platillo, llevarlo a la barra, volver, anotar la comanda, cantarla. Ese ir y venir es fijo: cuesta lo mismo para una tapa que para el plato enorme. Cuando la tapa se monta en un segundo, el camarero —no la despensa— es el cuello de botella. Acortar el pasillo a la despensa (ensanchar la HBM, cuantizar los pesos) ya casi no mejora el servicio; lo que mejora es que el camarero encadene varias comandas sin volver a la cocina cada vez (CUDA graphs) o que sirva varias mesas de una pasada (batching).

El roofline es la herramienta que dice, con números, a partir de qué punto el camarero domina sobre la despensa. Esa frontera es el ridge point, y el chiste del título es que en SLM cruzamos el régimen mucho antes de lo que la intuición de los modelos grandes nos hizo creer.

El mecanismo desnudo: qué dice el roofline

El modelo roofline (Williams, Waterman y Patterson, 2009) parte de una sola magnitud: la arithmetic intensity (intensidad aritmética), que es cuántas operaciones haces por cada byte que mueves desde memoria.

$$\text{AI} = \frac{\text{FLOPs}}{\text{bytes movidos desde memoria}} \quad [\text{FLOP/byte}]$$

El hardware tiene dos techos: el de cómputo (peak FLOPS) y el de memoria (peak bandwidth × AI). El rendimiento alcanzable es el mínimo de ambos:

$$\text{Perf} = \min\big(\text{peak FLOPS},; \text{BW} \times \text{AI}\big)$$

Donde se cortan las dos líneas está el ridge point, la AI a partir de la cual dejas de estar limitado por memoria y pasas a estarlo por cómputo:

$$\text{AI}_{\text{ridge}} = \frac{\text{peak FLOPS}}{\text{peak BW}}$$

Si tu kernel tiene AI por debajo del ridge, estás memory-bound (la GPU espera bytes). Por encima, compute-bound (la GPU calcula a tope y la memoria sobra). Lo importante es que el ridge point es una propiedad del hardware, no del modelo. Veamos los números —aproximados, y los marco como tales porque las cifras de marketing mezclan dense y sparse, distintos dtypes y condiciones térmicas irreales.

Cluster genérico 4×H100 SXM (320 GB, NVLink, FP8 nativo). Por GPU, ~989 TFLOPS BF16 dense (~1979 TFLOPS FP8 dense; la cifra con sparsity es el doble y casi nunca aplica a inferencia LLM). HBM3 ~3.35 TB/s. El ridge en BF16:

$$\text{AI}_{\text{ridge}}^{\text{H100,BF16}} \approx \frac{989 \times 10^{12}}{3.35 \times 10^{12}} \approx 295 \ \text{FLOP/byte}$$

En FP8 el ridge sube a ~590 FLOP/byte (el doble de FLOPS contra el mismo BW). Cuidado: estas son cifras de pico de datasheet; en la práctica un kernel real raramente pasa del 70-80 % de cualquiera de los dos techos.

RTX 4090 (24 GB, Ada Lovelace). ~330 TFLOPS FP16 con acumulación FP16 vía tensor cores (la cifra “660 TOPS” que circula es con sparsity), y ~1 TB/s de GDDR6X. El ridge:

$$\text{AI}_{\text{ridge}}^{\text{4090,FP16}} \approx \frac{330 \times 10^{12}}{1.0 \times 10^{12}} \approx 330 \ \text{FLOP/byte}$$

Curiosamente del mismo orden que la H100 en BF16: la 4090 tiene menos BW pero también menos FLOPS, y el cociente queda parecido. El ridge ronda 300 FLOP/byte en ambos casos. Quédate con ese número.

¿Y dónde cae el decode? En decode a batch 1, cada peso se carga una vez desde HBM y se usa para una sola multiplicación-acumulación (un token, una fila de activación). La AI del GEMM de decode a batch 1 es del orden de AI ≈ 1-2 FLOP/byte (cada byte de peso participa en ~2 FLOP). Con batch B, el mismo peso cargado una vez sirve a B filas de activación, así que la AI escala aproximadamente lineal:

$$\text{AI}_{\text{decode}}(B) \approx 2B \ \text{FLOP/byte} \quad (\text{para la parte GEMM de los pesos})$$

Cruzas el ridge cuando 2B ≈ 300, es decir B ≈ 150 en orden de magnitud (en la práctica antes, por atención y overheads, pero ese es el marco). Conclusión limpia: el decode a batch bajo está siempre profundamente memory-bound, lejísimos del ridge. Por eso decimos que “el decode espera a la HBM” y por eso cuantizar pesos (mover menos bytes) acelera el decode de un modelo grande casi linealmente. Hasta aquí, todo es el discurso estándar de los posts de modelos grandes.

El matiz del título: por qué se invierte en SLM

El roofline clásico tiene un punto ciego que en modelos grandes no importa y en pequeños lo es todo: solo modela el trabajo dentro del kernel. Asume que el único tiempo es bytes/BW o FLOPs/FLOPS. Pero un step de decode real no es solo el GEMM. Es una secuencia de decenas de kernels (proyecciones QKV, atención, las dos capas del MLP, normalizaciones, residuales, la cabeza de logits, el sampling) y, alrededor de cada uno, hay un coste fijo de orquestación:

Lanzamiento de kernels (kernel launch): cada cudaLaunchKernel cuesta del orden de 5-10 µs de overhead de CPU/driver, independientemente del tamaño del kernel. Un forward de decode con ~30-60 kernels lanzados secuencialmente arrastra ~0.3-0.6 ms solo en lanzar.
Overhead del scheduler de Python: el bucle de scheduler de vLLM prepara metadatos, decide qué requests entran en el step, construye los tensores de entrada. En Python puro esto son cientos de µs a un par de ms por step, sobre todo a concurrencia baja donde no se amortiza.
Sampling y post-proceso: aplicar temperatura, top-p, penalizaciones, el argmax/multinomial, copiar el token de vuelta. Otro bloque de cientos de µs.
Sincronizaciones y copias host↔device: cada synchronize o copia pequeña añade latencia que no es ni FLOPs ni bytes de HBM.

Llamemos a la suma de todo esto T_fijo, el coste por step independiente del tamaño del modelo, del orden de 1-3 ms en un stack Python sin optimizar. Ahora el tiempo real de un step es:

$$T_{\text{step}} \approx \underbrace{\frac{\text{bytes de pesos}}{\text{BW}}}{T{\text{HBM}} \text{ (memory-bound)}} + ; T_{\text{fijo}}$$

En un 70B BF16, mover ~140 GB a 3.35 TB/s son ~42 ms de T_HBM. Frente a eso, T_fijo de 1-3 ms es ruido (2-7 %). El roofline clásico acierta: el modelo está memory-bound y punto. Pero en un 3B BF16, T_HBM cae a unos pocos ms, y de pronto T_fijo es del mismo orden que T_HBM. El cuello deja de ser la despensa y pasa a ser el camarero. Esto es la inversión del título, y de ella se derivan cuatro consecuencias contraintuitivas:

(a) A batch 1 sigues memory-bound respecto al hardware. La AI no ha cambiado: sigue siendo ~2 FLOP/byte, debajo del ridge. Quien lea solo el roofline concluirá “memory-bound, cuantiza los pesos”. Es cierto pero incompleto: el roofline no ve T_fijo.

(b) Los costes fijos pasan a ser una fracción enorme del step. Es el punto central. En el 70B, T_fijo / T_step ≈ 5 %. En el 3B puede ser 20-30 %. El cuello efectivo del 3B es mitad HBM, mitad orquestación.

(c) Por eso los CUDA graphs y reducir el overhead del scheduler rinden MÁS en SLM. Un CUDA graph captura toda la secuencia de kernels del step y la relanza con un único cudaGraphLaunch, eliminando casi todo el overhead de lanzamiento por kernel y buena parte del trabajo del scheduler de Python por iteración. En el 70B, recortar 0.5 ms de un step de 42 ms es un +1 % que apenas se nota. En el 3B, recortar esos mismos 0.5 ms de un step de ~7 ms es un +7 %, y si te llevas casi todo T_fijo puedes ganar 20-30 %. La misma optimización, distinto premio, porque el denominador cambió.

(d) La cuantización de pesos da MENOS mejora de latencia a batch 1 en SLM. Esta es la más contraintuitiva. En el 70B, T_HBM es casi todo el step; pasar de BF16 a INT4 cuadruplica el ancho de banda efectivo de pesos y casi cuadruplica la velocidad de decode. En el 3B, T_HBM es solo parte del step (el resto es T_fijo + atención + KV). Por la ley de Amdahl, si los pesos son el 60 % del step y los aceleras 4×, el step total mejora solo 1/(0.4 + 0.6/4) = 1.8×, no 4×. Y proporcionalmente hay menos pesos que mover frente a activaciones, KV cache y el overhead fijo. La cuantización agresiva en SLM ayuda, sí, pero no por la latencia pura a batch 1 —ahí da rendimientos decrecientes— sino por capacidad y concurrencia (lo veremos al final).

(e) El KV cache puede dominar la memoria relativa. Con pesos de 6 GB (3B BF16), una sola sesión de contexto largo puede acercarse a ese orden de magnitud en KV cache. En un 70B (140 GB de pesos) el KV es proporcionalmente pequeño hasta concurrencias altas. En SLM el balance de VRAM se inclina hacia el KV mucho antes (el detalle está en KV cache), y eso cambia qué optimización de memoria es la palanca.

La matemática que importa: el 3B en una 4090

Hagamos el cálculo entero, que es donde se ve la inversión sin retórica.

Modelo: 3B parámetros, BF16 → 2 bytes/param → ~6 GB de pesos. Hardware: RTX 4090, BW ≈ 1 TB/s.

Techo memory-bound del decode (batch 1). Cada token requiere cargar los 6 GB una vez:

$$T_{\text{HBM}} = \frac{6 \times 10^{9} \ \text{bytes}}{1 \times 10^{12} \ \text{bytes/s}} = 6 \times 10^{-3}\ \text{s} = 6\ \text{ms/token}$$

$$\text{Techo} = \frac{1}{6\ \text{ms}} \approx 166\ \text{tok/s}$$

Eso es el techo teórico memory-bound: 166 tok/s, asumiendo que mover los pesos es el único coste. El roofline clásico se pararía aquí y diría “166 tok/s, ve a por más BW o cuantiza”.

Ahora el overhead fijo. Pongamos T_fijo ≈ 2 ms/step (un valor razonable de scheduler de Python + ~40 kernels lanzados + sampling, sin CUDA graphs). El step real:

$$T_{\text{step}} = T_{\text{HBM}} + T_{\text{fijo}} = 6 + 2 = 8\ \text{ms} ;\Rightarrow; \frac{1}{8\ \text{ms}} = 125\ \text{tok/s}$$

El overhead se ha comido 41 tok/s de los 166 teóricos: el T_fijo es el 25 % del step (2 de 8 ms). Compara con el 70B: T_HBM ≈ 42 ms, T_step ≈ 44 ms, T_fijo es el 4.5 %. Mismo overhead absoluto, impacto relativo 5-6× mayor en el SLM.

Qué pasa si aplicas CUDA graphs y te llevas, digamos, 1.5 de los 2 ms de T_fijo:

$$T_{\text{step}}^{\text{graphs}} = 6 + 0.5 = 6.5\ \text{ms} ;\Rightarrow; 154\ \text{tok/s}$$

De 125 a 154 tok/s: +23 % solo por orquestación, sin tocar el modelo ni el hardware de memoria. En el 70B la misma intervención habría dado de 44 a 42.5 ms, +3.5 %. Aquí está, en dos números, “otro partido”.

Qué pasa si cuantizas los pesos a INT4 (1.5 GB en vez de 6 GB), con T_fijo aún en 2 ms:

$$T_{\text{HBM}}^{\text{INT4}} = \frac{1.5 \times 10^{9}}{1 \times 10^{12}} = 1.5\ \text{ms};\quad T_{\text{step}} = 1.5 + 2 = 3.5\ \text{ms} ;\Rightarrow; 285\ \text{tok/s}$$

La cuantización 4× de pesos no dio 4× de latencia: pasó de 125 a 285 tok/s, un 2.3×, porque el T_fijo de 2 ms ahora domina (es el 57 % del step). En el 70B, cuantizar a INT4 da casi el 4× completo porque T_fijo sigue siendo ruido. La misma cuantización rinde el doble de aceleración en el grande que en el pequeño, a batch 1. Y si además aplicas CUDA graphs sobre el INT4 (T_fijo → 0.5 ms): 1.5 + 0.5 = 2 ms → 500 tok/s. El orden de las optimizaciones importa: en SLM atacar T_fijo primero desbloquea el resto.

Configuración (3B, 4090, batch 1)	T_HBM	T_fijo	T_step	tok/s	vs. base
BF16, sin graphs (base)	6.0 ms	2.0 ms	8.0 ms	125	1.00×
BF16 + CUDA graphs	6.0 ms	0.5 ms	6.5 ms	154	1.23×
INT4, sin graphs	1.5 ms	2.0 ms	3.5 ms	285	2.28×
INT4 + CUDA graphs	1.5 ms	0.5 ms	2.0 ms	500	4.00×

(Cifras ilustrativas con T_fijo redondeado; el punto es el patrón, no el decimal. El T_fijo real depende del stack, la versión de PyTorch/CUDA y si hay tensor parallelism. Mídelo en tu setup antes de creerte ninguna fila.)

Implicaciones por optimización

Con el modelo en la mano, las palancas del blog se reordenan al cambiar de régimen.

Batching: mucho más headroom en SLM. Recuerda que cruzas el ridge en B ≈ ridge/2 ≈ 150 en orden de magnitud. En un modelo grande, la VRAM se acaba mucho antes de saturar compute (los pesos + KV no te dejan llegar a batch 150). En un SLM los pesos ocupan poco, así que puedes meter batches grandes en VRAM y seguir memory-bound durante mucho más rango: el T_HBM de los pesos se amortiza entre las B requests (lo cargas una vez, sirve a B), de modo que el throughput agregado por GPU sube casi linealmente con B hasta muy arriba. Es justo lo contrario del miedo del 70B a saturar compute. En SLM, batchear es la palanca de throughput por excelencia porque saturas compute tarde; el grid search de batch en vLLM tiene una meseta de buen comportamiento mucho más ancha. Ojo: batchear mejora throughput, no latencia por request; para latencia single-stream el premio está en T_fijo.

Speculative decoding: otro punto de cruce. Speculative gana cuando el verify de γ tokens es “casi gratis” por estar memory-bound. En SLM el target ya es barato, así que el draft tiene que ser minúsculo para que c = T_draft/T_target siga siendo pequeño, y el T_fijo del propio draft (lanzar sus kernels) muerde más. El cruce a compute-bound con batch también llega antes en términos absolutos de tok/s servidos. La variante que mejor encaja aquui evita un draft separado: self-speculative / early-exit reutiliza capas tempranas del propio modelo y ahorra el T_fijo de orquestar dos modelos.

Cuantización: ayuda por capacidad, no por latencia a batch 1. Como mostró la tabla, INT4 en un SLM a batch 1 da rendimientos decrecientes en latencia. Su verdadero premio en SLM es capacidad: pesos 4× más pequeños liberan VRAM para más KV cache → más concurrencia, y es a concurrencia alta (throughput agregado) donde el ahorro de bytes vuelve a pagar. La cuantización agresiva sub-4-bit y ternaria lleva esto al extremo: en SLM tiene sentido sobre todo para encajar más sesiones por GPU, no para bajar la latencia de una sola. Y conviene recordar (ver quantization) que a batch 1 el dequantize añade trabajo de cómputo que, en un régimen ya rozado por T_fijo, no siempre sale gratis.

Arquitectura: MoE de grano fino cambia qué bytes mueves. Un MoE device-native de grano fino activa pocos parámetros por token, así que T_HBM baja respecto a un denso del mismo tamaño total —pero la fracción T_fijo sube todavía más, y el router añade su propio overhead fijo. Es el régimen SLM llevado a su límite: casi todo el partido se juega en la orquestación.

Scheduler y CUDA graphs primero. La conclusión operacional invertida respecto a los posts de modelos grandes: en SLM, antes de tocar el modelo, mata el T_fijo. CUDA graphs (ver SM, streams y graphs), un scheduler de vLLM con su parte de Python minimizada o compilada, y persistencia de kernels son las palancas de primer orden. En un 70B serían un pulido marginal; en un 3B son la mitad del speedup disponible.

Aplicado a hardware on-premise

En una RTX 4090 (24 GB, Ada Lovelace). Es el escenario donde la inversión es más visible, porque la 4090 tiene ~1 TB/s (un tercio de la H100) pero el T_fijo es el mismo en términos absolutos. Un 3B BF16 sin CUDA graphs deja ~125 tok/s sobre la mesa cuando el techo memory-bound son 166; activar graphs y limpiar el scheduler recupera la mayor parte. La 4090 cabe holgada para SLM en VRAM, así que el cuello casi nunca es la memoria total sino la orquestación y, a alta concurrencia, el KV cache. Regla de pulgar: en 4090 con SLM, perfila primero el overhead por step (Nsight Systems sobre el gap entre kernels) antes de cuantizar.

En un cluster genérico 4×H100 SXM (320 GB, NVLink, FP8 nativo). La H100 tiene 3.35 TB/s, así que T_HBM de un SLM es aún más pequeño (un 3B FP8 son ~3 GB → ~0.9 ms) y el T_fijo domina todavía antes: un SLM mal orquestado en H100 puede pasar más tiempo en el scheduler de Python que moviendo pesos. Es casi un desperdicio servir un único SLM single-stream en una H100; el modo correcto es batching agresivo (saturas compute tarde, así que metes batches grandes y el throughput por GPU se dispara) o multiplexar muchos SLM/sesiones por GPU vía MPS/MIG. Aquí conecta con capacity planning: para SLM el cálculo de capacidad lo gobiernan concurrencia y KV cache, no los pesos. Y con el dilema de una grande vs N pequeñas: replicar SLM tiene sentido precisamente porque cada réplica satura compute tarde y el TP no aporta (el modelo ya cabe; el TP solo añadiría T_fijo de comunicación).

Lo que no hemos cubierto

El T_fijo exacto medido, kernel a kernel, con Nsight Systems: cuánto es launch, cuánto scheduler, cuánto sampling. Es el contenido del siguiente post de la serie.
torch.compile / capturas parciales: alternativas y complementos a los CUDA graphs cuando hay control flow dinámico.
El régimen prefill en SLM: el prefill es compute-bound incluso en modelos pequeños (procesa muchos tokens a la vez, AI alta), así que su roofline es el opuesto del decode; ver prefill.
Atención y KV como segundo término de T_HBM: aquí los hemos metido implícitamente; el desglose fino de la atención (que escala con la longitud de secuencia, no con los pesos) merece su propio tratamiento.

Ver también

KV cache: la memoria de trabajo de la inferencia — el fenómeno memory-bound del decode nace del KV cache; en SLM el KV pasa a dominar la VRAM relativa antes que en modelos grandes.
Grid search de batch sizing en vLLM — la meseta de buen batch es mucho más ancha en SLM porque cruzas el ridge tarde; este post da el método empírico.
Optimizando el decode en vLLM — los flags concretos (CUDA graphs, eager vs captured) cuyo impacto este post reordena para el caso SLM.
Optimizando el prefill en vLLM — el reverso compute-bound del roofline: el prefill ya vive por encima del ridge incluso en modelos pequeños.
SM, CUDA streams y CUDA graphs — el mecanismo que ataca el T_fijo; aquí explicamos por qué su premio es desproporcionado en SLM.
El scheduler step de vLLM — buena parte de T_fijo vive en este bucle de Python; en SLM minimizarlo es palanca de primer orden.
Quantization para inferencia — por qué la cuantización de pesos rinde menos latencia a batch 1 en SLM (ley de Amdahl sobre T_HBM) y más por capacidad.
Speculative decoding: fundamentos — el punto de cruce memory/compute se desplaza en SLM, cambiando cuándo speculative paga.
Capacity planning de inferencia on-premise — para SLM la capacidad la gobiernan concurrencia y KV, no los pesos; este post da las fórmulas.
Una grande vs N pequeñas — replicar SLM bate al TP porque cada réplica satura compute tarde y el TP solo añade T_fijo de comunicación.
Self-speculative decoding / early-exit — hermano de serie: acelerar sin draft separado, evitando el T_fijo de orquestar dos modelos, encaje natural en SLM.
MoE de grano fino device-native — hermano de serie: el régimen SLM llevado al límite, donde el router y la orquestación dominan sobre el T_HBM.
Cuantización agresiva sub-4-bit y ternaria — hermano de serie: por qué en SLM sub-4-bit paga sobre todo en capacidad/concurrencia, no en latencia a batch 1.

Referencias

Williams, S., Waterman, A., Patterson, D. Roofline: An Insightful Visual Performance Model for Multicore Architectures. Communications of the ACM, 52(4), 2009. https://doi.org/10.1145/1498765.1498785
Mind the Memory Gap: Unveiling GPU Bottlenecks in Large-Batch LLM Inference. arXiv:2503.08311, 2025. https://arxiv.org/abs/2503.08311
Databricks. LLM Inference Performance Engineering: Best Practices. https://www.databricks.com/blog/llm-inference-performance-engineering-best-practices
NVIDIA. NVIDIA H100 Tensor Core GPU Datasheet. https://resources.nvidia.com/en-us-tensor-core/nvidia-tensor-core-gpu-datasheet
NVIDIA. GeForce RTX 4090 — especificaciones de producto (cifras de tensor cores Ada Lovelace; tratar como aproximadas, mezclan dense/sparse).
Yuan, Z. et al. LLM Inference Unveiled: Survey and Roofline Model Insights. arXiv:2402.16363, 2024 — aplicación del roofline específicamente a inferencia LLM.

Los pasillos y el guardia de seguridad: topología PCIe, GPUDirect P2P y ACS

Mon, 08 Jun 2026 06:00:00 +0200

Sigue la serie por debajo del motor. El post de NVLink y NCCL explicó la mesa compartida por la que las GPUs se pasan datos a 450 GB/s. Pero esa mesa solo conecta GPUs entre sí. Todo lo demás —disco, red, el host— viaja por otro bus, el PCIe, y por sus pasillos. El cold start ya rozó esto con GPUDirect Storage; este post abre el plano completo de los pasillos y el guardia que los vigila.

TL;DR

En un nodo de 4×H100 SXM, las GPUs se hablan por NVLink (450 GB/s por sentido, ~7× el PCIe), y para el all-reduce del tensor parallel ese es el camino. Pero el PCIe no desaparece: es por donde entra todo lo demás. Los pesos suben del NVMe por PCIe (el cold start), los datos de otro nodo llegan por la NIC por PCIe (RDMA), y un KV que se mueve entre nodos viaja por PCIe. GPUDirect es la familia que deja que esos bytes vayan directos del dispositivo a la HBM sin rebotar por la RAM del host: P2P (GPU↔GPU), RDMA (GPU↔NIC) y Storage (GPU↔NVMe). El obstáculo es un guardia llamado ACS (Access Control Services): una feature de seguridad del PCIe que por defecto obliga al tráfico peer-to-peer a subir hasta el root complex para inspección, lo que destruye el camino directo y mete un rodeo por la CPU. El IOMMU (VT-d) hace algo parecido si no está en modo passthrough. Desactivarlos da rendimiento; mantenerlos da aislamiento y virtualización —y esa es una decisión real en un entorno ENS—. Este post explica la topología (nvidia-smi topo -m), GPUDirect, por qué ACS e IOMMU rompen el P2P con números, los 10 knobs y la trampa de quitar el guardia sin saber qué vigilaba. Sobre el cluster genérico 4×H100 SXM.

Dónde estás: los pasillos, no la mesa

Imagina la cocina como un edificio. Las estaciones de cocción de élite —las GPUs— están en una sala con una mesa central enorme (NVLink/NVSwitch) por la que se pasan ingredientes a toda velocidad sin levantarse. Esa mesa es para ellas y solo ellas.

Pero el edificio tiene más cosas: la despensa (el almacenamiento NVMe), la puerta de carga (la red, la NIC) y la recepción (la CPU y su RAM). Para llegar a cualquiera de esas, las estaciones no usan la mesa central: usan los pasillos del edificio —el bus PCIe—. Y aquí aparece el personaje del post: en la entrada de cada pasillo hay un guardia de seguridad (ACS) que, por defecto, no deja que dos estaciones se pasen algo directamente por el pasillo: las obliga a subir el paquete a recepción para que lo revisen, y solo entonces baja a destino. Es seguro, pero es un rodeo absurdo cuando las dos estaciones están una al lado de la otra. GPUDirect es el permiso para saltarse ese rodeo; ACS e IOMMU son las razones por las que, a menudo, no puedes.

La topología de un nodo: dos buses, no uno

El error más común es pensar que en un nodo hay “un bus”. Hay (al menos) dos, y hacen cosas distintas:

NVLink / NVSwitch — la malla de alta velocidad GPU↔GPU. En H100 SXM, 18 enlaces × 50 GB/s = 900 GB/s bidireccionales entre dos GPUs cualesquiera, con NVSwitch dando un all-to-all sin contención (NVLink, NVIDIA). Es la mesa compartida.
PCIe Gen5 — el bus de I/O general. Un enlace x16 da 128 GB/s bidireccionales (~64 por sentido) (H100 product brief). Conecta cada GPU con la CPU, la RAM, las NICs y los NVMe. Es el pasillo.

La diferencia es de 7×: NVLink mueve en un segundo lo que el PCIe tarda siete. Por eso el tensor parallel intra-nodo va por NVLink y nadie lo discute. El PCIe importa para lo otro: subir pesos del disco, recibir de la red, mover KV entre nodos.

La herramienta para verlo es nvidia-smi topo -m, que imprime una matriz de cómo está conectado cada par (foro NVIDIA):

 GPU0 GPU1 GPU2 GPU3 NIC0 CPU Affinity NUMA
GPU0 X NV18 NV18 NV18 PXB 0-47 0
GPU1 NV18 X NV18 NV18 PXB 0-47 0
GPU2 NV18 NV18 X NV18 SYS 48-95 1
GPU3 NV18 NV18 NV18 X SYS 48-95 1

La leyenda es la que importa: NV18 = 18 enlaces NVLink (la mesa); PXB = cruza switches PCIe pero no el host; PHB = pasa por el host bridge; NODE = mismo NUMA, cruzando PCIe; SYS = cruza el interconnect entre sockets (el peor caso, atraviesa NUMA). Que GPU0↔NIC0 sea PXB y GPU2↔NIC0 sea SYS te dice exactamente qué GPU debe atender el tráfico de esa NIC —la 0, sin cruzar NUMA—. Esto enlaza directo con el post de NUMA y el de NUMA de red: la afinidad PCIe es la afinidad NUMA.

GPUDirect: saltarse la recepción

Sin GPUDirect, mover un dato de la NIC (o el NVMe) a la GPU hace un rodeo obligatorio: dispositivo → RAM del host → GPU. Ese rebote por la RAM consume ancho de banda de la CPU, gasta copias y añade latencia. GPUDirect elimina el rebote dejando que el dato vaya directo del dispositivo a la HBM. Tres sabores:

GPUDirect P2P — GPU↔GPU por PCIe (cuando no hay NVLink entre ellas, o para tráfico que no usa la mesa).
GPUDirect RDMA — GPU↔NIC: la tarjeta de red escribe directa en la HBM. Es lo que hace viable el multi-nodo eficiente (NCCL sobre InfiniBand/RoCE).
GPUDirect Storage (GDS) — GPU↔NVMe: el disco escribe directo en la HBM, sin buffer de host. Es la palanca del cold start.

En un nodo SXM, el tráfico GPU↔GPU del tensor parallel no usa P2P por PCIe: usa NVLink. Por eso GPUDirect importa sobre todo en los bordes del nodo: la red (RDMA, para multi-nodo) y el disco (GDS, para arranque). Ahí es donde ACS hace daño.

El guardia: por qué ACS e IOMMU rompen el P2P

ACS (Access Control Services) es una feature de seguridad del PCIe pensada para virtualización y aislamiento: garantiza que un dispositivo no pueda leer/escribir directamente en otro sin que el root complex lo medie. Para conseguirlo, fuerza las transacciones peer-to-peer a subir hasta el root complex y volver a bajar (best practices GDS, NVIDIA). Es exactamente lo contrario de lo que GPUDirect quiere: el camino directo deja de serlo.

El IOMMU (VT-d en Intel, equivalente en AMD) traduce direcciones y aísla dispositivos. Si está activo y no en modo passthrough, también redirige el tráfico P2P por el root complex, con el mismo efecto: rendimiento por los suelos o, en casos extremos, hangs (troubleshooting NCCL).

Resumido sin rodeos (Giraud, debugging P2P): ACS fuerza el paso por el root para comprobaciones de seguridad; IOMMU lo fuerza para aislamiento y virtualización. Ambos rompen el objetivo del P2P (comunicación directa sin intermediarios) y añaden overhead. Si no necesitas esa seguridad/virtualización en ese path, desactivarlos recupera el rendimiento. La receta operativa para máximo rendimiento de GPUDirect: ACS off en los switches del camino e IOMMU en passthrough (iommu=pt) o desactivado.

Las matemáticas que importan: cuánto cuesta el rodeo

Pongamos un SWAP de KV de 5 GB (preemption del scheduler que manda KV a host, o transferencia entre nodos en serving desagregado):

Camino	BW efectivo	Tiempo de 5 GB
NVLink (GPU↔GPU intra-nodo)	~450 GB/s	~11 ms
PCIe Gen5 x16 directo (P2P, ACS off)	~55 GB/s	~91 ms
PCIe vía root complex (ACS on)	~25-30 GB/s*	~170-200 ms

* El rodeo por el root no solo “añade latencia”: satura el ancho de banda del host bridge, contiende con otro tráfico y, según la topología, puede caer bastante por debajo del directo. La cifra es de orden, para mostrar la magnitud del problema, no un benchmark.

La lectura: en el camino que sí usa PCIe (red, disco, swap), tener ACS on puede duplicar o triplicar el tiempo. Y si ese tiempo está en el camino crítico —un cold start, un swap de preemption, un all-reduce inter-nodo— se nota en la latencia que ve el usuario. Lo que no arregla desactivar ACS: el tráfico que ya iba por NVLink (TP intra-nodo). Ahí ACS es irrelevante.

La tensión real: rendimiento vs aislamiento (y ENS)

Aquí el post se pone serio, porque la receta “desactiva ACS e IOMMU” tiene un coste que en un entorno regulado no es gratis. ACS e IOMMU existen por una razón: aislar dispositivos. En un nodo bare-metal dedicado a inferencia, sin virtualización ni multi-tenancy, no aíslas nada que importe y desactivarlos es razonable. Pero:

Si haces passthrough de GPU a VMs o usas contenedores con aislamiento fuerte, el IOMMU es necesario —no es opcional—.
En un escenario multi-tenant donde varias cargas comparten nodo, ACS aporta una garantía de que un dispositivo no fisgonea a otro.
En ENS (ver controles técnicos), el aislamiento de cargas y la trazabilidad de accesos pueden ser requisitos; desactivar el aislamiento del bus para ganar 80 ms es una decisión que hay que justificar y documentar, no un tuneo silencioso.

La salida de diseño, cuando necesitas las dos cosas: mantén el aislamiento donde lo exige el compliance y diseña para que el camino caliente no dependa del P2P por PCIe. Concretamente, en un nodo SXM, el grueso del tráfico crítico (TP) ya va por NVLink y no le afecta ACS. Para la red, dedica una NIC por GPU en su mismo switch PCIe (PXB) y usa GPUDirect RDMA solo en el path que controlas. Para el disco, cachea pesos en NVMe local. Así no pagas la elección entre rendimiento y aislamiento: la evitas en el path que importa.

Los 10 knobs

#	Knob	Qué controla	Coste / riesgo
1	ACS off (switches del path)	rodeo por root del P2P	pierdes aislamiento de bus
2	`iommu=pt` / off	redirección P2P por root	rompe passthrough a VM si off
3	`nvidia-smi topo -m`	auditar la topología real	— (siempre conviene)
4	`p2pBandwidthLatencyTest`	medir P2P de verdad	— (verifica antes de asumir)
5	colocación de NIC	mismo switch PCIe que la GPU	SYS si cruza NUMA
6	colocación de NVMe	NUMA-local a la GPU	H2D cruzando UPI
7	`nvidia-peermem` (GDR)	habilita RDMA a HBM	driver/kernel correctos
8	PCIe gen/lanes (x16)	ancho del pasillo	GPU en x8 silencioso
9	relaxed ordering / ASPM	latencia y energía PCIe	jitter si mal configurado
10	persistence mode	evita reinit del path	GPU ociosa pagada

Cómo se conecta con el resto del stack

Con NVLink y NCCL. El post de NVLink cubre la mesa GPU↔GPU; este cubre el otro bus, el que conecta con disco, red y host. Son complementarios: ACS afecta al PCIe, no al NVLink.

Con el cold start. GPUDirect Storage del post disco→HBM es GPUDirect sobre el path de almacenamiento; ACS on lo estrangula igual que estrangula el P2P.

Con NUMA. La afinidad PCIe de topo -m es la afinidad NUMA del post del host; colocar NIC y NVMe en el NUMA correcto evita el camino SYS.

Con la red. La colocación de NIC y GPUDirect RDMA es el tema del post de NUMA de red; el mismo principio de “saca a la CPU del medio”.

Con PagedAttention y el scheduler. El SWAP de preemption (scheduler) mueve bloques de KV por PCIe; por eso V1 prefiere RECOMPUTE y por eso este bus importa.

Con el disaggregated serving. Transferir KV entre pools en serving desagregado viaja por PCIe→NIC→PCIe; ACS y la colocación deciden si es viable.

Con ENS. El aislamiento del bus es un control técnico; ver controles ENS/42001/AI Act.

Trampas y cosas que no son lo que parecen

“Desactiva ACS en todas partes, va más rápido.” En un nodo dedicado, vale. En uno con virtualización, multi-tenancy o requisitos de aislamiento (ENS), estás quitando un control de seguridad. La decisión correcta es por path y documentada, no global y silenciosa.

“NVLink y PCIe son el mismo bus, más o menos.” No. Son dos buses con 7× de diferencia y propósitos distintos. El TP va por NVLink; el disco, la red y el host van por PCIe. Confundirlos lleva a “optimizar” ACS para un tráfico que ni siquiera pasa por PCIe.

“El P2P funciona solo, no hay que comprobar nada.” El P2P se desactiva en silencio con ACS/IOMMU activos, y muchas distros los activan por defecto. Comprueba con p2pBandwidthLatencyTest y nvidia-smi topo -m; no asumas que tienes el camino directo solo porque las GPUs están en el mismo nodo.

“IOMMU off siempre, por rendimiento.” Si haces passthrough de GPU a máquinas virtuales, el IOMMU es obligatorio; desactivarlo rompe el passthrough. El modo correcto suele ser passthrough (iommu=pt): mantiene el mapeo necesario sin penalizar el P2P.

“Más lanes PCIe = GPU más rápida.” El PCIe es el camino de I/O, no de cómputo. Una GPU en x8 en vez de x16 tarda más en cargar y en comunicar por PCIe, pero genera tokens a la misma velocidad una vez los pesos están dentro. El daño de x8 está en el cold start y en el multi-nodo, no en el throughput de decode.

“GPUDirect arregla cualquier cuello de I/O.” GPUDirect quita el rebote por la CPU; si tu cuello es el propio dispositivo (NVMe saturado, NIC a tope) o la topología (camino SYS cruzando NUMA), GPUDirect no lo toca. Mide dónde está el cuello antes.

Conclusión

Toda esta serie ha bajado pisos buscando dónde se pierde el tiempo, y este llega al cableado del edificio. La intuición trata el nodo como una caja homogénea donde “las GPUs hablan con todo”; la realidad es que hay dos buses con propósitos opuestos —una mesa de élite para las GPUs (NVLink) y unos pasillos de servicio para todo lo demás (PCIe)— y un guardia de seguridad en los pasillos que, con la mejor intención, obliga a cada paquete a subir a recepción antes de entregarlo. GPUDirect es el permiso para la entrega directa; ACS e IOMMU son las razones legítimas por las que a veces no te lo dan. La lección no es “desactiva el guardia”: es entender qué camino es crítico (casi nunca el que crees) y qué vigilaba el guardia antes de mandarlo a casa. En un nodo dedicado, el camino directo es casi gratis y conviene tomarlo. En uno que comparte cargas o vive bajo ENS, el aislamiento del bus es un control que se sacrifica con justificación o no se sacrifica. El buen diseño no elige entre rendimiento y aislamiento a ciegas: pone el tráfico crítico en la mesa que no necesita guardia, y deja los pasillos para lo que puede esperar.

Ver también

La mesa compartida: NVLink, NVSwitch y NCCL — el bus GPU↔GPU que ACS no toca; complementario a este post.
Del disco a la HBM: cold start — GPUDirect Storage sobre el path de NVMe, estrangulado por ACS igual que el P2P.
NUMA, hugepages y aislamiento de CPU — la afinidad PCIe es la afinidad NUMA; colocar NIC y NVMe en el socket correcto.
NUMA de red, Cilium eBPF y DRANET — colocación de NIC y GPUDirect RDMA, el mismo principio de sacar a la CPU del medio.
PagedAttention y el block manager — el KV que viaja por PCIe cuando se hace SWAP.
El pase: el scheduler step de vLLM — por qué V1 prefiere RECOMPUTE a SWAP (evita el viaje por PCIe).
Disaggregated serving: prefill y decode separados — transferir KV entre nodos pasa por PCIe→NIC→PCIe.
Controles técnicos ENS / ISO 42001 / EU AI Act — el aislamiento del bus como control de seguridad a justificar.

Referencias

NVIDIA, GPUDirect Storage Best Practices Guide (ACS, IOMMU, paths): https://docs.nvidia.com/gpudirect-storage/best-practices-guide/index.html.
NVIDIA, NCCL Troubleshooting (IOMMU/VT-d y P2P): https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/troubleshooting.html.
M. Giraud, Multi-GPU (NVIDIA) P2P capabilities and debugging tips: https://morgangiraud.medium.com/multi-gpu-nvidia-p2p-capabilities-and-debugging-tips-fb7597b4e2b5.
NVIDIA, H100 Product Brief (PCIe Gen5, NVLink 900 GB/s): https://www.nvidia.com/content/dam/en-zz/Solutions/Data-Center/h100/PB-11773-001_v01.pdf.
NVIDIA, GPUDirect RDMA documentation: https://docs.nvidia.com/cuda/gpudirect-rdma/index.html.

El especialista del plato estrella: el backend de atención de vLLM (FlashAttention, FlashInfer y la asimetría prefill/decode)

Mon, 08 Jun 2026 05:40:00 +0200

Sigue la serie por debajo del motor. El post de PagedAttention explicó dónde vive el KV (en bloques paginados). Este explica quién lo lee y cómo: el kernel de atención. Y conecta con FlashAttention v1-v4, que desmontó cómo es ese kernel por dentro; aquí miramos el nivel de arriba —cómo vLLM elige entre varios kernels y por qué necesita más de uno—.

TL;DR

Un forward de un LLM es, en su mayor parte, multiplicaciones de matrices estándar que cualquier librería hace bien. La excepción que decide el rendimiento es la atención, y no basta con tener un kernel bueno: hacen falta dos, porque las dos fases de la inferencia son problemas físicamente opuestos. El prefill procesa el prompt entero: muchas queries contra muchas keys, denso y compute-bound —el terreno del tiling IO-aware de FlashAttention—. El decode genera un token: una sola query contra todo el KV acumulado, flaco y memory-bound —aquí lo único que importa es saturar el ancho de banda de la HBM leyendo el KV paginado—. Por eso vLLM no tiene “el kernel de atención” sino un backend conmutable (FLASH_ATTN, FLASHINFER, TRITON_ATTN…) y una lógica que elige según la GPU: por defecto FA4 en Blackwell (SM100), FA3 en Hopper (SM90), FA2 en lo demás, con FlashInfer como alternativa que compila kernels a medida (JIT) y sabe hacer cascade attention para prefijos compartidos. Este post explica por qué prefill y decode son opuestos (con la intensidad aritmética), cómo el backend lee KV paginado, cómo el motor elige, qué aporta FlashInfer, los 10 knobs y la trampa de fijar un backend a ciegas. Sobre el cluster genérico 4×H100 SXM.

Dónde estás: el especialista, no el pinche

En la cocina, casi todo el trabajo es picar y saltear: operaciones estándar que cualquier pinche competente ejecuta —son las multiplicaciones de matrices de las capas feed-forward y las proyecciones—. Hay un solo plato que no se delega: el plato estrella, el que define al restaurante. Ese plato es la atención, y tiene una particularidad: se cocina de dos maneras radicalmente distintas según el momento del servicio.

Durante el prefill —cuando llega una comanda nueva con su prompt entero— hay que cocinar a lo grande: mucha materia prima de golpe, mucho fuego, una operación intensa que llena los fogones. Durante el decode —cuando una mesa pide “un plato más”— hay que cocinar a la carta: un solo plato, pero hay que ir a la despensa y traer todos los ingredientes que esa mesa ha acumulado durante toda su comida. Uno es un problema de potencia de fuego; el otro, de velocidad de la despensa. No los hace bien el mismo especialista. Por eso vLLM tiene varios, y un jefe que decide cuál entra según la GPU y la fase. Eso es el backend de atención.

Por qué prefill y decode son problemas opuestos

Esta es la idea central, y se demuestra con una sola cuenta: la intensidad aritmética (FLOPs por byte leído). Una operación con intensidad alta está limitada por el cómputo; una con intensidad baja, por la memoria.

Prefill. Atendemos $N$ queries (todo el prompt) contra $N$ keys. La operación $QK^\top$ y la $\text{softmax}\cdot V$ hacen del orden de $N^2 d$ FLOPs y leen del orden de $N d$ datos. La intensidad crece con $N$:

$$I_\text{prefill} \sim \frac{N^2 d}{N d} = N$$

Con $N$ grande (un prompt de miles de tokens), la intensidad es alta: compute-bound. Es donde el tiling de FlashAttention exprime los tensor cores y donde se acerca a los TFLOPS de pico de la GPU.

Decode. Atendemos una query (el token nuevo) contra $L$ keys (todo el KV acumulado). FLOPs del orden de $L d$; bytes leídos del orden de $L d s$ (hay que leer el KV entero de la HBM). La intensidad es:

$$I_\text{decode} \sim \frac{L d}{L d s} = \frac{1}{s} \quad (\approx 0,5 \text{ FLOP/byte en FP16})$$

Constante y diminuta: memory-bound. El kernel de decode no está limitado por cuánto puede calcular la GPU sino por cuán rápido lee el KV de la HBM. Da igual que la H100 tenga 132 SMs ociosos (ver el post de SMs): el cuello es el ancho de banda de 3,35 TB/s, y el kernel de decode existe para no desperdiciar ni uno de esos bytes/s.

La consecuencia de diseño: un kernel optimizado para prefill (tiling denso, máxima ocupación de tensor cores) no es el óptimo para decode (lecturas coalescidas del KV paginado, latencia mínima). Los servidores serios tienen kernels distintos —o un kernel con dos caminos—. En los modelos con MLA (atención latente multi-cabeza), vLLM llega a usar backends separados para prefill y decode, seleccionables de forma independiente (attention backends, vLLM).

El truco del scheduler: prefill y decode en el mismo forward

Aquí cierra el círculo con el post del scheduler. Como vLLM V1 mezcla en cada step peticiones en prefill y en decode, un mismo forward tiene que atender las dos cosas. El backend recibe metadatos que le dicen, para cada secuencia del batch, cuántas queries trae y cuánto KV tiene que leer, y aplica el camino que toca a cada una. Por eso el backend de atención y el scheduler están acoplados: el primero tiene que digerir el batch heterogéneo que el segundo arma.

Cómo lee el backend el KV paginado

El kernel no recibe un tensor de KV contiguo: recibe la block table del block manager y hace un gather sobre los bloques físicos. Esto impone una restricción real al backend: tiene que soportar el layout paginado y el block_size de vLLM. No todos los kernels del mundo lo hacen; los que vLLM integra (FlashAttention, FlashInfer, Triton) están adaptados a leer KV en bloques de tamaño fijo dispersos por la HBM. Es la razón de que no puedas enchufar cualquier kernel de atención de un paper: tiene que hablar el idioma de la despensa por casilleros.

Los backends y cómo elige el motor

vLLM expone una abstracción de backend con varias implementaciones (deepwiki vLLM):

FLASH_ATTN — la familia FlashAttention. Por defecto se elige la versión según la arquitectura: FA4 en SM100 (Blackwell), FA3 en SM90 (Hopper), FA2 en el resto, configurable con flash_attn_version.
FLASHINFER — motor de atención con compilación JIT y kernels especializables; fuerte en KV heterogéneo y prefijos compartidos.
TRITON_ATTN — escrito en Triton, portable y sin depender de binarios CUDA precompilados (Triton backend deep dive, vLLM, mar-2026).
Backends específicos para MLA y para hardware no-NVIDIA.

La selección es automática salvo que la fuerces con VLLM_ATTENTION_BACKEND. La heurística prueba FlashAttention primero; en Blackwell (SM100) el orden de respaldo para MLA es TRT-LLM Ragged → FlashInfer → otros; en otras GPUs solo se considera FlashAttention para el camino principal (attention backends, vLLM). La decisión depende de: arquitectura (SM), dtype (FP16/BF16/FP8), dimensión de cabeza, y si la carga necesita una feature que solo un backend tiene (cascade attention, ciertos soft caps, FP8 en KV).

Qué aporta FlashInfer: JIT y cascade attention

FlashInfer no compite con FlashAttention en “ser un poco más rápido”; ataca un problema distinto: la heterogeneidad del KV en servicio real (FlashInfer, arXiv 2501.01005). Dos ideas:

Compilación JIT. En lugar de un kernel monolítico, FlashInfer genera kernels a medida para la variante de atención, la forma del problema y el layout del KV que tengas, inyectando functors (transformaciones de query/key/logits, máscaras). Especializa en vez de generalizar.

Cascade attention. Aquí está la joya para servicio con prefijos compartidos. Si $R$ peticiones comparten un prefijo de $P$ tokens (un system prompt común), la atención ingenua leería ese prefijo $R$ veces. La cascade attention lo calcula una vez contra el prefijo compartido y luego combina con el sufijo propio de cada petición:

$$\text{lecturas: } \underbrace{R \cdot (P + s_i)}{\text{ingenua}} ;\longrightarrow; \underbrace{P + \textstyle\sum_i s_i}{\text{cascade}}$$

Con $R=50$ peticiones y un prefijo $P=1000$, eso es leer 50.000 tokens de prefijo frente a 1.000. Es el complemento natural del prefix caching: el block manager comparte la memoria del prefijo, y la cascade attention comparte el cómputo de atender sobre él.

Las matemáticas que importan: cuándo cambiar de backend te da algo

El backend solo mueve la aguja donde la atención es el cuello. En decode memory-bound, un kernel que aprovecha mejor el ancho de banda de HBM da una mejora real; en prefill compute-bound con secuencias largas, FA3/FA4 acercándose al pico de tensor cores da una mejora real. Pero si tu cuello está en otra capa —el launch overhead, el scheduler mal dimensionado, el cold start— cambiar de backend no toca esa parte. La regla, otra vez: medir el régimen antes de optimizar.

Los 10 knobs

#	Knob	Qué controla	Coste / riesgo
1	`VLLM_ATTENTION_BACKEND`	forzar backend	mismatch con hardware/feature
2	`flash_attn_version` (2/3/4)	versión de FA	versión no soportada en tu SM
3	habilitar FlashInfer	JIT + cascade	tiempo de compilación JIT inicial
4	cascade attention	reuso de cómputo de prefijo	solo ayuda con prefijo muy compartido
5	`kv_cache_dtype` (FP8)	soporte FP8 en el kernel	no todos los backends/SM lo soportan
6	`block_size`	layout que el kernel debe leer	coherencia con PagedAttention
7	backend de prefill MLA	kernel de la fase densa	solo modelos MLA
8	backend de decode MLA	kernel de la fase flaca	solo modelos MLA
9	soft cap / sliding window	features que limitan backends	menos opciones de kernel
10	head_dim / variante	qué kernels son elegibles	modelos exóticos sin soporte

Cómo se conecta con el resto del stack

Con FlashAttention. El post de FA explica el kernel por dentro (tiling, online softmax, FA1-4); este es el nivel de arriba —cómo vLLM elige entre kernels y por qué necesita más de uno—.

Con PagedAttention. El backend lee el KV que el block manager coloca en bloques; tiene que hablar el idioma del block table.

Con el scheduler. El scheduler arma batches mixtos prefill+decode; el backend tiene que atender los dos regímenes en un solo forward.

Con los CUDA graphs. Los kernels de atención se capturan en los CUDA graphs; un backend que lanza muchos kernels pequeños se beneficia más de la captura.

Con el prefix caching. La cascade attention es el lado cómputo de lo que el prefix caching hace en memoria.

Con FP8. Atender sobre KV en FP8 requiere que el backend tenga el camino FP8; no todos lo tienen en toda arquitectura.

Trampas y cosas que no son lo que parecen

“FlashInfer siempre es más rápido que FlashAttention.” No. FlashInfer gana cuando su especialización (cascade, KV heterogéneo, una variante de atención concreta) aplica a tu carga; en prefill denso clásico, FA3/FA4 suele ir igual o mejor. Depende del régimen, no hay un ganador universal.

“Un buen kernel de atención sirve para todo.” El error de fondo de este post. Prefill y decode son compute-bound y memory-bound respectivamente; un kernel ajustado a uno desperdicia en el otro. Por eso existen caminos separados (y backends separados en MLA).

“El decode es compute-bound porque la GPU está al 100%.” El nvidia-smi al 100% engaña (ver el post de SMs): el decode es memory-bound, la GPU está moviendo KV, no calculando. Optimizar el cómputo del decode es pulir lo que no es el cuello.

“Fijo VLLM_ATTENTION_BACKEND y me olvido.” Fijar un backend a mano puede dejarte en uno subóptimo cuando cambias de GPU o de versión, o forzar un fallback lento si tu hardware no soporta lo que pediste. La autoselección suele acertar; fíjalo solo con una medida que lo justifique.

“La cascade attention siempre ayuda.” Solo con prefijo muy compartido entre muchas peticiones concurrentes. Si cada petición tiene su propio contexto, no hay nada que compartir y el overhead de organizar la cascada no se amortiza.

“El backend de atención es el cuello, por eso voy lento.” Casi siempre el cuello está más arriba (lanzamiento, scheduling, memoria) o más abajo (ancho de banda). El backend importa donde la atención domina; mídelo con nsys/DCGM antes de cambiarlo.

Conclusión

De todo lo que hace un LLM al generar texto, casi todo son multiplicaciones de matrices que cualquier librería resuelve. El rendimiento se juega en un solo kernel —la atención— y la sorpresa es que ni siquiera es un kernel: son dos problemas opuestos disfrazados del mismo nombre. El prefill quiere fuego —cómputo denso sobre miles de tokens— y el decode quiere despensa rápida —leer todo el KV de un token con el mínimo desperdicio de ancho de banda—. Por eso vLLM no eligió un kernel ganador sino una abstracción que conmuta: FlashAttention afinado a cada arquitectura para el caso general, FlashInfer compilando a medida cuando hay heterogeneidad o prefijos que compartir, Triton para portabilidad. El jefe de cocina no cocina el plato estrella de una sola manera: mira quién pide y en qué momento del servicio, y manda al especialista que toca. La lección para quien tunea es la de siempre en esta serie: antes de cambiar de especialista, asegúrate de que el plato estrella es de verdad lo que te está frenando.

Ver también

FlashAttention v1/v2/v3/v4 — el kernel por dentro; este post es el nivel de arriba (cómo se elige entre kernels).
PagedAttention y el block manager — el KV paginado que el backend lee vía block table.
El pase: el scheduler step de vLLM — el batch mixto prefill+decode que el backend digiere en un forward.
SM, CUDA streams y CUDA graphs — por qué el nvidia-smi al 100% no significa compute-bound, y dónde se capturan los kernels de atención.
Prefix cache hit rate engineering — el lado memoria de lo que la cascade attention hace en cómputo.
FP8 end-to-end: pesos y KV — el camino FP8 que el backend necesita soportar.
Continuous batching — por qué un forward tiene que atender prefill y decode a la vez.
KV cache: la memoria de trabajo — el dato que el kernel de decode lee entero en cada paso.

Referencias

vLLM, Attention Backends (selección, FA2/3/4 por arquitectura, MLA): https://docs.vllm.ai/en/latest/design/attention_backends/.
vLLM / DeepWiki, FlashAttention and FlashInfer: https://deepwiki.com/vllm-project/vllm/8.2-flashattention-and-flashinfer.
vLLM, Triton Attention Backend Deep Dive (mar-2026): https://vllm.ai/blog/2026-03-04-vllm-triton-backend-deep-dive.
Z. Ye et al., FlashInfer: Efficient and Customizable Attention Engine for LLM Inference Serving (arXiv 2501.01005): https://arxiv.org/abs/2501.01005.
T. Dao, FlashAttention-2 / FlashAttention-3 (kernel IO-aware, async Hopper): https://github.com/Dao-AILab/flash-attention.

La despensa por casilleros: PagedAttention y el block manager de vLLM

Mon, 08 Jun 2026 05:20:00 +0200

Sigue la serie por debajo del motor. El post del scheduler terminó con un cabo suelto: el scheduler tiene un segundo presupuesto, los bloques de KV, y cuando se agotan, preempta. Este post abre ese presupuesto. Es la pieza que el post de KV cache daba por buena —qué se guarda— para explicar cómo se gestiona en memoria. Y es el que el post de FlashAttention llevaba meses prometiendo.

TL;DR

El KV cache crece un poco con cada token generado, y el problema nunca fue su tamaño total sino la forma de reservarlo. Los primeros servidores pedían, por petición, un trozo contiguo de HBM del tamaño del contexto máximo posible. Como casi ninguna petición llega a ese máximo, el resultado era catastrófico: 60-80% de la HBM desperdiciada en fragmentación. PagedAttention aplica al KV la idea más vieja y probada de los sistemas operativos —la paginación—: partir el KV en bloques de tamaño fijo (16 tokens por defecto), guardarlos en HBM no contigua donde haya hueco, y mantener una block table que traduce el bloque lógico de cada secuencia a su bloque físico. El desperdicio cae a ~4% (solo el último bloque, a medio llenar). Y como cada bloque se puede identificar por el hash de su contenido, dos peticiones que comparten un prefijo apuntan al mismo bloque físico y comparten memoria —con copy-on-write cuando una diverge—: ese es el motor del prefix caching. Este post explica la fragmentación con números, el block manager, el block table, el COW, el compromiso del tamaño de bloque, los 10 knobs y la trampa de confundir “fragmentación resuelta” con “cero desperdicio”. Sobre el cluster genérico 4×H100 SXM.

Dónde estás: la despensa, debajo del scheduler

Vuelve a la cocina del post anterior. El jefe de sala arma bandejas, pero detrás hay una despensa donde se guardan los ingredientes que cada mesa va acumulando a lo largo de su comida —su KV cache—. La pregunta de este post es cómo está organizada esa despensa.

La forma ingenua: a cada mesa se le asigna una estantería entera y contigua, dimensionada para el cliente más glotón imaginable. El problema salta a la vista: una mesa que pide poco deja casi toda su estantería vacía, pero esa estantería ya está reservada y nadie más puede usarla. Con muchas mesas, la despensa se llena de estanterías medio vacías y no caben mesas nuevas, aunque sumando huecos sobre sitio de sobra.

La forma de PagedAttention: la despensa se divide en casilleros pequeños e idénticos. A cada mesa se le dan los casilleros que va necesitando, uno a uno, donde haya hueco —no tienen que estar juntos—. Un libro de mapas anota qué casilleros físicos tiene cada mesa y en qué orden. Cuando una mesa se va, sus casilleros vuelven al montón. No hay estanterías medio vacías: solo se desperdicia el último casillero de cada mesa, el que está a medio llenar. Eso es, casi literalmente, la memoria virtual de un sistema operativo aplicada al KV cache.

Por qué la memoria contigua fragmentaba

Reservar contiguo y por adelantado produce tres desperdicios distintos:

Fragmentación de reserva. Apartas espacio para max_model_len (p. ej. 8192 tokens) aunque la petición vaya a usar 800. Reservado y nunca usado.
Fragmentación interna. Dentro de lo reservado, lo que queda por encima de lo que de verdad usas en cada momento.
Fragmentación externa. Huecos entre reservas contiguas demasiado pequeños para una petición nueva, aunque sumados sobren.

El paper original de vLLM medía que los sistemas previos desperdiciaban del 60% al 80% de la memoria de KV por estas tres vías (Kwon et al., SOSP 2023). Es decir: en una GPU con sitio para 100 peticiones reales, solo cabían 20-40. La paginación ataca las tres a la vez —elimina la reserva (asignación on-demand) y la externa (los bloques no necesitan ser contiguos), y deja solo un resto de la interna: el último bloque parcial.

El mecanismo: bloques, block table y el gather del kernel

El KV de una secuencia se trocea en bloques lógicos de $b$ tokens (por defecto $b = 16$). Cada bloque lógico se mapea, vía la block table, a un bloque físico en algún punto de la HBM. La block table es el “libro de mapas”: una lista, por petición, de qué físico corresponde a cada lógico (implementación vLLM).

La clave es que el kernel de atención sabe leer así. En lugar de asumir un tensor de KV contiguo, el kernel de PagedAttention recibe la block table y hace un gather: para cada secuencia, recorre sus bloques físicos en el orden lógico y lee K y V como si estuvieran juntos. Por eso PagedAttention no es solo una estructura de datos: es un kernel que sabe atender sobre memoria paginada. Y por eso el backend de atención y el block manager están atados —el segundo decide dónde vive el KV, el primero sabe leerlo de ahí.

El block manager: el bibliotecario de la despensa

El block manager (en V1, el KVCacheManager) es quien lleva el libro de mapas. Sus responsabilidades:

Mantener un pool de bloques físicos libres (una cola de bloques disponibles).
Asignar bloques a una secuencia cuando crece (un bloque nuevo cada $b$ tokens).
Liberar los bloques cuando la secuencia termina o es preemptada.
Mantener las block tables (logical→physical) de cada petición.
Gestionar el prefix caching: detectar bloques con contenido idéntico y compartirlos.
Cuando se acaban los bloques libres, avisar al scheduler para que preempte (ver el post del scheduler).

Cuando el block manager dice “no quedan bloques”, el scheduler tiene que bajar a alguien del tren. Por eso los dos presupuestos —tokens y bloques— son las dos manos del mismo motor.

Prefix caching: compartir casilleros con copy-on-write

Aquí está la parte elegante. Si dos peticiones empiezan con el mismo prefijo —el mismo system prompt, el mismo documento de contexto—, los primeros bloques de KV de ambas son idénticos byte a byte. ¿Por qué calcularlos y guardarlos dos veces?

vLLM le pone a cada bloque un hash que resume su contenido (los tokens que lo formaron, más el hash del bloque anterior, para que el hash capture la posición). Mantiene una tabla global de bloques por hash. Cuando una petición nueva produce un bloque cuyo hash ya existe, no asigna memoria nueva: apunta su block table al bloque físico que ya estaba (automatic prefix caching, vLLM).

El copy-on-write es la salvaguarda: mientras A y B comparten un bloque, ninguna lo puede modificar. En el momento en que una de las dos necesita escribir algo distinto en ese bloque (porque sus secuencias divergen, o en parallel sampling / beam search donde varias ramas comparten prefijo), el block manager copia el bloque para esa rama y solo entonces escribe (details, vLLM). Es el mismo COW que usa fork() en un SO: compartir hasta que alguien escriba.

El ahorro es directo: si 50 peticiones comparten un system prompt de 1000 tokens, en lugar de 50 copias del KV de ese prefijo hay una. Cómo maximizar ese ahorro en la práctica es el tema del post de prefix cache hit rate.

Las matemáticas que importan: cuánto KV, cuántos bloques

Bytes de KV por token. Para un bloque transformer con $L$ capas, $h_{kv}$ cabezas de KV (GQA), dimensión por cabeza $d$ y $s$ bytes por elemento (2 en FP16):

$$\text{KV/token} = 2 \cdot L \cdot h_{kv} \cdot d \cdot s$$

Para un Llama-70B ($L=80$, $h_{kv}=8$, $d=128$, FP16):

$$\text{KV/token} = 2 \cdot 80 \cdot 8 \cdot 128 \cdot 2 = 327680 \text{ bytes} \approx 320 \text{ KB}$$

Un bloque de 16 tokens ocupa $16 \times 320,\text{KB} = 5,12$ MB.

Cuántas peticiones caben. Si tras cargar los pesos quedan ~120 GB de los 320 del nodo para KV:

$$\text{tokens de KV} = \frac{120 \cdot 10^9}{327680} \approx 366000 \text{ tokens} \approx 22900 \text{ bloques}$$

Con contextos medios de 4000 tokens (250 bloques cada uno), eso son ~90 peticiones concurrentes. Ese número —no max_num_seqs— es el techo real de concurrencia, y es exactamente el “presupuesto de bloques” del scheduler.

El desperdicio que queda. PagedAttention no llega a cero: cada secuencia desperdicia, de media, medio bloque (el último, a medio llenar). Con bloques de 16 tokens y secuencias de 4000, eso es $8 / 4000 = 0,2%$ por secuencia —el famoso “~4%” agregado del paper incluye otros overheads—. La lección: el desperdicio no desaparece, se acota al tamaño de un bloque.

El compromiso del tamaño de bloque

El block_size (16 por defecto) es un compromiso, no una constante mágica:

Bloque	Ventaja	Inconveniente
Pequeño (8)	menos desperdicio interno; sharing de prefijo más fino	más entradas de block table; más overhead de gestión y de gather
Grande (32)	menos metadatos; gather más eficiente	más desperdicio en el último bloque; el prefix caching comparte con grano más grueso (menos hits)

Un bloque grande comparte peor: el prefix caching solo puede reutilizar bloques completos e idénticos, así que con bloques de 32 dos prompts que coinciden en 20 tokens no comparten nada (no llenan un bloque común), mientras que con bloques de 8 comparten dos bloques. El 16 por defecto es el punto que vLLM encontró razonable para la mayoría de cargas; merece la pena probarlo si tu carga tiene prefijos cortos muy repetidos.

Los 10 knobs

#	Knob	Qué controla	Coste si te pasas
1	`block_size`	tokens por bloque	desperdicio / overhead (ver tabla)
2	`enable_prefix_caching`	compartir bloques por hash	casi ninguno; suele ir on
3	`gpu_memory_utilization`	cuántos bloques físicos hay	OOM si demasiado alto
4	`kv_cache_dtype` (FP8)	bytes por elemento de KV	calidad (medir, no asumir)
5	`swap_space`	bloques que caben en host (SWAP)	tráfico PCIe en preemption
6	`max_model_len`	longitud máxima por petición	menos peticiones si muy alto
7	política de evicción	a quién se le quitan bloques	hit rate de prefix cache
8	sliding window	descartar KV viejo	calidad en contextos largos
9	TP / sharding del KV	reparto del KV entre GPUs	tráfico NVLink
10	num_gpu_blocks (override)	forzar el conteo de bloques	OOM o infrautilización

Cómo se conecta con el resto del stack

Con el scheduler. El “presupuesto de bloques” del scheduler lo administra este block manager. Cuando dice que no hay bloques, el scheduler preempta (RECOMPUTE por defecto).

Con el KV cache. El post de KV cache explica qué guarda cada token; este, cómo se coloca en memoria sin fragmentar.

Con el prefix caching. El COW y los hashes de bloque son el mecanismo; el hit rate engineering es cómo exprimirlo (estructura de prompts, routing prefix-aware).

Con la cuantización del KV. Pasar el KV a FP8 parte por la mitad los bytes/token: el mismo nodo cabe el doble de tokens. Es la palanca más directa sobre la concurrencia.

Con el backend de atención. El kernel de FlashAttention/FlashInfer tiene que saber atender sobre bloques paginados; el block manager decide dónde viven, el kernel sabe leerlos.

Con el disaggregated serving. Mover una petición de un pool de prefill a uno de decode en serving desagregado es, en el fondo, transferir sus bloques de KV entre motores —por NVLink o red—.

Con multi-LoRA. En multi-LoRA serving, la base comparte KV de prefijo entre peticiones de distintos adapters siempre que el prefijo sea idéntico.

Trampas y cosas que no son lo que parecen

“PagedAttention elimina el desperdicio.” Lo acota, no lo elimina. Queda el último bloque parcial por secuencia (~medio bloque) más los metadatos del block table. Es ~4% en vez de 60-80%, pero no es cero. Dimensionar como si fuera cero te deja sin colchón.

“Bloques más grandes siempre rinden mejor.” El gather es algo más eficiente, sí, pero pierdes granularidad de sharing: el prefix caching comparte peor y el desperdicio del último bloque crece. En cargas con muchos prefijos cortos repetidos, bloques pequeños pueden ganar.

“El prefix caching comparte KV entre usuarios, eso es un problema de privacidad.” Comparte solo bloques idénticos token a token (mismo system prompt, mismo documento). No expone el contenido de un usuario a otro: si los tokens no coinciden, no hay bloque común. Lo que sí conviene vigilar es la información por canales laterales de tiempo (un hit es más rápido que un miss), relevante solo en escenarios multi-tenant muy adversariales.

“FP8 en el KV es gratis: el doble de concurrencia.” Dobla los tokens que caben, sí, pero el KV en FP8 degrada la calidad de forma medible en contextos largos. Es una palanca real, no un almuerzo gratis: hay que medir la calidad (FP8 end-to-end), no asumirla.

“Volver a memoria contigua sería más simple y casi igual de bueno.” Es la nostalgia del tensor contiguo. Lo “simple” reintroduce el 60-80% de fragmentación: en una GPU, eso es la diferencia entre 30 y 90 peticiones concurrentes. La complejidad del block table se paga con creces.

SWAP frente a RECOMPUTE al preemptar. Configurar mucho swap_space “para no perder KV” mete transferencias de gigabytes por el PCIe en el camino crítico. En V1, RECOMPUTE suele ser mejor; el swap es para casos concretos.

Conclusión

El cuello de botella de servir un LLM nunca fue solo cuánta memoria tienes, sino cómo la repartes. Los primeros servidores trataban el KV cache como una estantería contigua por cliente y tiraban dos tercios de la HBM a la basura sin que apareciera en ningún dashboard. PagedAttention le robó al sistema operativo su mejor idea de hace cincuenta años —paginar— y la aplicó al sitio exacto donde dolía: casilleros pequeños, un libro de mapas, asignación bajo demanda y, de regalo, la posibilidad de que dos peticiones que empiezan igual compartan los mismos casilleros hasta que dejen de parecerse. El resultado no es magia: el desperdicio sigue ahí, pero acotado al tamaño de un bloque en vez de al tamaño del peor caso imaginable. Y esa diferencia —del 70% al 4%— es la que convirtió una GPU que servía a treinta clientes en una que sirve a noventa, sin tocar el hardware. La despensa no se hizo más grande; se organizó mejor.

Ver también

El pase: el scheduler step de vLLM — el presupuesto de bloques que este block manager administra; cuando se agota, preemption.
KV cache: la memoria de trabajo — qué guarda cada token, el dato que aquí se pagina.
Prefix cache hit rate engineering — cómo exprimir el sharing de bloques que el COW hace posible.
FlashAttention v1/v2/v3/v4 — el kernel que sabe atender sobre KV paginado.
FP8 end-to-end: pesos y KV — partir por la mitad los bytes/token y doblar la concurrencia, midiendo la calidad.
Disaggregated serving: prefill y decode separados — mover una petición entre pools es transferir sus bloques de KV.
PCIe, GPUDirect P2P y ACS — por dónde viajan los bloques cuando se hace SWAP o se mueve KV entre GPUs.
Multi-LoRA serving — compartir prefijo entre peticiones de distintos adapters.

Referencias

W. Kwon et al., Efficient Memory Management for Large Language Model Serving with PagedAttention (SOSP 2023): https://arxiv.org/pdf/2309.06180.
vLLM, Automatic Prefix Caching (diseño, hashing de bloques): https://docs.vllm.ai/en/v0.8.1/design/automatic_prefix_caching.html.
vLLM, Automatic Prefix Caching — Implementation (block table, COW): https://docs.vllm.ai/en/v0.6.1/automatic_prefix_caching/details.html.
H. Elshafie, Paged Attention from First Principles: A View Inside vLLM: https://hamzaelshafie.bearblog.dev/paged-attention-from-first-principles-a-view-inside-vllm/.
vAttention: Dynamic Memory Management for Serving LLMs without PagedAttention (alternativa, contexto crítico): https://arxiv.org/pdf/2405.04437.

El pase: el jefe de sala que arma cada ronda — el scheduler step de vLLM

Mon, 08 Jun 2026 05:00:00 +0200

Sigue la serie por debajo del motor. Los posts anteriores miraron el silicio que ejecuta los kernels (SMs y CUDA graphs) y la carga de los pesos (del disco a la HBM). Este sube un piso: quién decide qué corre en cada forward. Antes de que la GPU lance un solo kernel, alguien ha tenido que armar la comanda de esta ronda. Ese alguien es el scheduler, y es el corazón del continuous batching.

TL;DR

Un servidor de LLM no atiende una petición entera y luego la siguiente: avanza todas las peticiones vivas a la vez, un poquito en cada iteración del motor. La pieza que decide cuánto avanza cada una en cada paso es el scheduler, y su salida es engañosamente simple: un diccionario {req_id: nº de tokens} que el model runner convierte en un solo forward sobre la GPU. La decisión más importante de vLLM V1 fue borrar la distinción entre prefill y decode: para el scheduler, un token de prompt y un token recién generado son la misma cosa —tokens que hay que procesar—, y por eso puede meter en el mismo batch un prompt de 4000 tokens junto a 200 decodes de 1 token. Las piezas son cuatro: el presupuesto de tokens (max_num_batched_tokens), que es una bandeja de tamaño fijo que se llena cada ronda; el chunked prefill, que parte un prompt enorme en trozos para que no acapare la bandeja y dispare la latencia del resto; las dos colas (waiting, en orden de llegada, y running); y la preemption —cuando se acaba el KV cache, alguien tiene que bajarse del tren—. Este post explica el bucle, las matemáticas del presupuesto y de la concurrencia, los 10 knobs y la trampa estrella: subir el presupuesto mejora el throughput pero empeora el ITL (tiempo entre tokens), y casi nadie mide las dos cosas a la vez. Sobre el cluster genérico 4×H100 SXM.

Dónde estás: el pase, antes de que la cocina arranque

Imagina el pase de un restaurante con mucha sala. No hay un cocinero por cliente; hay una cocina compartida y un jefe de sala que, cada pocos segundos, mira todas las comandas abiertas y arma una bandeja para mandar a fogones. En esa bandeja caben, pongamos, 8000 “unidades de trabajo”. El jefe de sala decide qué entra: a las mesas que ya están comiendo (peticiones en decode) les manda un plato más a cada una; a las mesas nuevas que acaban de pedir (peticiones en prefill, con su prompt entero por procesar) les manda tanta comanda como quepa en lo que sobra de bandeja. Manda la bandeja, la cocina la ejecuta de golpe, y vuelve a empezar. Cientos de veces por segundo.

Ese jefe de sala es el scheduler. La cocina es la GPU ejecutando un forward pass. Y la regla de oro del sitio es que la cocina no para nunca a esperar a una sola mesa: si una comanda nueva es gigantesca (un prompt de 30.000 tokens), no se manda entera de una vez bloqueando a todos los demás, se manda a trozos. Esa es, en una frase, toda la mecánica del scheduler de vLLM.

El bucle del motor: un diccionario por iteración

El motor de inferencia es un bucle muy corto. En cada vuelta:

El scheduler mira las colas y produce una decisión.
El model runner ejecuta un forward con ese batch en la GPU.
El sampler saca un token nuevo por cada secuencia activa.
Se actualiza el estado (KV cache, posiciones, peticiones terminadas) y se vuelve a 1.

Lo sorprendente es la forma de la decisión del paso 1. En vLLM V1 no es una estructura compleja con fases: es literalmente un diccionario

$$\text{schedule} = {, \text{req_id} \rightarrow n_\text{tokens} ,}$$

que dice, para cada petición que entra en esta ronda, cuántos tokens se procesan de ella. Para una petición que está generando texto, n_tokens = 1 (un paso autoregresivo). Para una petición nueva, n_tokens puede ser hasta la longitud entera de su prompt. Y puede ser cualquier valor intermedio —un trozo de prompt— en caso de chunked prefill, prefix caching o speculative decoding (docs vLLM V1).

Que la decisión quepa en un diccionario {id: número} no es un detalle de implementación bonito: es el motivo de que continuous batching funcione. Como el scheduler no piensa en “fases” sino en “cuántos tokens a cada uno”, puede mezclar en el mismo forward peticiones en cualquier punto de su vida. La GPU recibe un único tensor de tokens heterogéneo y lo procesa de una vez.

La muerte de la distinción prefill/decode

Esta es la idea que más cuesta y la que más importa. En las primeras arquitecturas de servidores de LLM, una petición vivía en dos fases separadas: primero prefill (procesar todo el prompt y llenar el KV cache), luego decode (generar token a token). El scheduler tenía que coreografiar el paso de una fase a otra, y mezclarlas era difícil.

vLLM V1 eliminó la distinción (diseño V1). El scheduler trata los tokens de prompt y los tokens generados de forma uniforme: todos son tokens que el modelo tiene que procesar en un forward. La consecuencia práctica es enorme. Un prompt de 4000 tokens y una secuencia que lleva 800 tokens generando y necesita uno más son, para el scheduler, “4000 tokens de la petición A” y “1 token de la petición B”. Caben juntos en la misma bandeja. No hay coreografía de fases, solo un presupuesto que repartir.

Esto desbloquea el patrón que de verdad rinde: mezclar prefill y decode en cada step. El prefill es trabajo compute-bound (mucha matriz que multiplicar); el decode es memory-bound (poco cómputo, mucho mover KV). Mezclarlos en el mismo batch llena los huecos: mientras la GPU está ocupada con el prefill pesado, “de gratis” hace avanzar los decodes ligeros. Es el mismo principio de eficiencia que el continuous batching llevado a su forma más limpia.

El presupuesto de tokens: la bandeja de tamaño fijo

La bandeja tiene un tamaño: max_num_batched_tokens. Es el número máximo de tokens que el scheduler puede meter en un solo step (optimización vLLM). La política, con chunked prefill activo (lo está siempre en V1), es clara:

Primero los decodes. Se reserva sitio para un token por cada petición en la cola running. Son baratos y son clientes que ya están comiendo: no se les deja esperar.
Lo que sobra, para prefills. Con el presupuesto restante, se meten tokens de prompt de las peticiones waiting, en orden de llegada (FCFS), partiéndolos en trozos si hace falta.

Un ejemplo con números. Presupuesto max_num_batched_tokens = 8192, y en este instante hay 200 peticiones generando:

$$\text{decode} = 200 \times 1 = 200 \text{ tokens}$$ $$\text{presupuesto libre} = 8192 - 200 = 7992 \text{ tokens para prefill}$$

Si llega una petición nueva con un prompt de 4000 tokens, cabe entera en este step (4000 < 7992) y sobran 3992 para otra. Si llega una con 30.000 tokens, no cabe: el scheduler le manda un trozo de 7992 este step, y los 22.008 restantes en steps siguientes. Eso es el chunked prefill.

El presupuesto importa porque fija cuántos forwards hacen falta para tragar un prompt. Un prompt de 30.000 tokens con bandeja de 8192 tarda 4 steps solo en prefill antes de soltar su primer token. Con bandeja de 2048, tarda 15 steps —pero cada uno de esos steps deja más sitio para decodes ajenos, así que los demás clientes notan menos el atasco.

Las dos colas y la preemption: cuando alguien se baja del tren

El scheduler maneja dos colas. La waiting son peticiones que aún no han empezado (su prompt no se ha procesado), y se sirven en orden de llegada —FCFS por defecto, aunque hay política priority—. La running son las que ya están vivas y generando (scheduling vLLM).

Hay un segundo presupuesto, más duro que el de tokens: el KV cache. Cada token vivo ocupa bloques de KV en la HBM, y son finitos (los fija gpu_memory_utilization). Cuando el scheduler quiere avanzar las peticiones running pero no hay bloques libres para el KV del token siguiente, alguien tiene que bajarse: eso es preemption.

vLLM V1 preempta por RECOMPUTE por defecto, no por SWAP (V1 guide). La diferencia:

SWAP: copiar el KV de la víctima a RAM de host y traerlo de vuelta luego. Mueve gigabytes por el PCIe (ver el post de PCIe y P2P).
RECOMPUTE: tirar el KV de la víctima y, cuando vuelva a tener sitio, re-hacer su prefill desde cero. Suena caro, pero en la arquitectura V1 sale más barato que el swap porque el prefill es trabajo que la GPU hace muy rápido, y te ahorras el viaje de ida y vuelta por el bus.

La víctima suele ser la petición más nueva de la cola running (para no penalizar a quien lleva más tiempo esperando su respuesta). El peligro es el thrashing: si admites demasiadas peticiones a la vez, el sistema entra en un ciclo de preemptar-recomputar-preemptar que tira el throughput al suelo. Por eso existe el segundo tope.

Las matemáticas que importan: concurrencia y el trade-off del presupuesto

Cuántas peticiones caben a la vez. El límite real de concurrencia no es max_num_seqs (el tope nominal de secuencias simultáneas); suele ser el KV cache. Si un nodo tiene $B$ bloques de KV libres, cada bloque guarda $b$ tokens (16 por defecto), y cada petición ocupa de media $L$ tokens de contexto, la concurrencia máxima sostenible es:

$$N_\text{max} \approx \frac{B \cdot b}{L}$$

Pongamos un modelo de 70B en FP16 sobre 4×H100 SXM (320 GB), con el grueso de la HBM en pesos y, digamos, ~120 GB libres para KV. Con un KV de ~0,3 MB/token (cifra de orden, depende de capas y cabezas), eso son ~400.000 tokens de KV. Con contextos medios de 4000 tokens:

$$N_\text{max} \approx \frac{400000}{4000} = 100 \text{ peticiones concurrentes}$$

Subir max_num_seqs a 400 no te da 400 concurrentes: te da preemption y thrashing en cuanto los contextos crezcan. El KV manda.

El trade-off del presupuesto. Subir max_num_batched_tokens mete más trabajo por forward, así que menos forwards para el mismo trabajo total → más throughput. Pero un presupuesto grande deja que un prefill enorme ocupe casi toda la bandeja en un step, y ese step tarda más → los decodes de todos los demás esperan ese step entero → sube el ITL (inter-token latency) de todo el mundo. La regla práctica (optimización vLLM):

Presupuesto	Efecto	A costa de
Bajo (p. ej. 2048)	más interleaving, ITL estable	menos throughput pico
Alto (p. ej. 16384)	máximo throughput	picos de ITL cuando entra un prefill grande

No hay valor “correcto”: hay un punto en tu carga. Y solo lo encuentras midiendo throughput e ITL a la vez, que es justo lo que casi nadie hace.

Los 10 knobs del scheduler

#	Knob	Qué controla	Coste si te pasas
1	`max_num_batched_tokens`	tamaño de la bandeja por step	ITL alto si muy grande
2	`max_num_seqs`	tope nominal de concurrencia	preemption si el KV no llega
3	`gpu_memory_utilization`	bloques de KV disponibles	OOM si demasiado alto
4	chunked prefill (umbral)	tamaño del trozo de prompt	overhead de troceo si muy fino
5	política (`fcfs`/`priority`)	a quién se sirve antes	inanición de baja prioridad
6	modo de preemption	RECOMPUTE vs SWAP	tráfico PCIe / recómputo
7	`enable_prefix_caching`	reutilizar KV de prefijos	poco; casi siempre on
8	`max_model_len`	contexto máximo por petición	reserva KV pesimista
9	tamaños de CUDA graph	alinear batch con buckets	padding / captura (ver abajo)
10	speculative tokens	tokens extra por step	trabajo desperdiciado si baja aceptación

Cómo se conecta con el resto del stack

Con el continuous batching. El scheduler es el continuous batching hecho código. El post de batching explica el qué (avanzar todas las peticiones a la vez); este explica el cómo (el diccionario de tokens por step).

Con el KV cache y el block manager. El segundo presupuesto —los bloques— lo gestiona el block manager de PagedAttention. El scheduler pide bloques; si no hay, preempta. Las dos piezas están acopladas por la memoria.

Con los CUDA graphs. Los CUDA graphs se capturan para tamaños de batch concretos (buckets). El scheduler debería producir batches cuyo tamaño caiga en esos buckets para evitar padding; si no, se pierde parte del beneficio del graph.

Con el chunked prefill y el prefix cache. Trocear un prompt interactúa con el prefix caching: los trozos que coinciden con un prefijo ya cacheado se saltan el cómputo, y el scheduler lo refleja bajando los n_tokens de esa petición.

Con el speculative decoding. El speculative decoding hace que un step verifique varios tokens de golpe; el scheduler lo modela como n_tokens > 1 para una petición en decode.

Con el disaggregated serving. En prefill/decode desagregado hay dos schedulers, uno por pool, cada uno con su presupuesto; la distinción de fases que V1 borró dentro de un motor vuelve a aparecer entre motores.

Con el autoscaling. Las métricas que dispara el autoscaling con KEDA —longitud de la cola waiting, peticiones preemptadas— salen directamente del estado del scheduler.

Trampas y cosas que no son lo que parecen

“Subir max_num_batched_tokens siempre mejora.” Mejora el throughput y empeora el ITL. Si solo miras tokens/s en un benchmark de batch grande, “confirmas” que más es mejor; en producción interactiva, tus usuarios notan los tirones. Mide las dos métricas o no estás midiendo.

“El motor hace primero todos los prefills y luego los decodes.” Es la intuición de la arquitectura vieja. En V1 no hay fases: cada step mezcla prefill y decode según el presupuesto. Razonar con el modelo de fases lleva a conclusiones equivocadas sobre por qué sube la latencia.

“Más max_num_seqs = más throughput.” Solo hasta que el KV cache se agota. A partir de ahí, más concurrencia nominal produce preemption, y la preemption en cascada (thrashing) baja el throughput. El techo real es el KV, no el parámetro.

“RECOMPUTE es un desperdicio, mejor SWAP.” En V1, RECOMPUTE suele ganar: el prefill es rapidísimo en GPU y el SWAP mete un viaje de gigabytes por el PCIe en el camino crítico. Cambiar a SWAP “para no recomputar” puede empeorar la latencia.

“El scheduler es el cuello de botella.” Casi nunca. La decisión es un diccionario que se arma en microsegundos; el coste de la ronda es el forward en la GPU, que está tres órdenes de magnitud por encima. Si tu CPU de scheduling aparece en el profiler, el problema suele ser jitter del hilo de host (ver NUMA y aislamiento de CPU), no la lógica del scheduler.

Chunked prefill demasiado fino. Trozos minúsculos hacen que un prompt grande tarde muchos steps y añaden overhead fijo por step. El troceo es para acotar el impacto en el ITL, no para pulverizar el prompt.

Conclusión

Toda la potencia de un servidor de LLM moderno —tragar cientos de peticiones a la vez sin que ninguna bloquee a las demás— descansa sobre una decisión que cabe en un diccionario {petición: cuántos tokens}, tomada cientos de veces por segundo. La idea que lo hizo posible no fue un kernel más rápido ni una GPU más grande: fue dejar de pensar en fases. Cuando un token de prompt y un token generado son la misma cosa, el scheduler puede llenar cada bandeja mezclando lo pesado y lo ligero, y la cocina no para nunca. El resto son dos presupuestos —tokens y bloques de KV— y una regla para cuando el segundo se agota. El jefe de sala no cocina; solo decide qué entra a fogones en cada ronda. Pero esa decisión, repetida sin descanso, es lo que separa una GPU ociosa esperando comandas de una cocina que va a pleno gas. Y la lección incómoda para quien tunea: el throughput y la latencia se tocan en el presupuesto, y optimizar uno a ciegas es empeorar el otro sin enterarte.

Ver también

Continuous batching: por qué no esperamos a terminar una petición — el qué; este post es el cómo que lo implementa.
PagedAttention y el block manager — el segundo presupuesto del scheduler, los bloques de KV; cuando se agotan, preemption.
KV cache: la memoria de trabajo — qué ocupa cada token vivo y por qué la concurrencia la limita la memoria, no el parámetro.
SM, CUDA streams y CUDA graphs — los buckets de captura que el scheduler debería respetar para no pagar padding.
Prefix cache hit rate engineering — cómo los trozos cacheados bajan los n_tokens que el scheduler asigna.
Speculative decoding — el caso n_tokens > 1 en decode.
Disaggregated serving: prefill y decode separados — dos schedulers, la distinción de fases que vuelve entre motores.
Autoscaling de LLM con KEDA — las métricas del scheduler (cola waiting, preemptados) como señal de escalado.

Referencias

vLLM, vLLM V1: A Major Upgrade to vLLM’s Core Architecture: https://openlm.ai/vllm-v1/.
vLLM, vLLM V1 User Guide (chunked prefill por defecto, preemption RECOMPUTE): https://docs.vllm.ai/en/v0.9.2/usage/v1_guide.html.
vLLM, Optimization and Tuning (max_num_batched_tokens, presupuesto y trade-off): https://docs.vllm.ai/en/stable/configuration/optimization/.
A. Wong, Understanding vLLM Scheduling: Token Budgets, Chunked Prefill, and Policies: https://audreywongkg.medium.com/understanding-vllm-scheduling-token-budgets-chunked-prefill-and-policies-2c879e3980e3.
W. Kwon et al., Efficient Memory Management for Large Language Model Serving with PagedAttention (SOSP 2023): https://arxiv.org/pdf/2309.06180.

El jefe que canta cada comanda: SMs, CUDA streams y CUDA graphs, o por qué la GPU se aburre generando tokens

Sun, 07 Jun 2026 09:00:00 +0200

Cierra el par “fuera de la API”. El post anterior subió los pesos del disco a la HBM; aquí miramos qué pasa una vez están dentro, en el silicio que los ejecuta. Es el piso por debajo del kernel launch que el post de NUMA mencionaba sin abrir: quién lanza esos kernels, cómo, y por qué en decode la GPU pasa más tiempo esperando órdenes que computando.

TL;DR

Una H100 tiene ~132 streaming multiprocessors (SMs) —los “fogones” que ejecutan el cómputo— y la ocupación mide cuántos warps (grupos de 32 hilos) tiene activos para esconder latencia. Pero el cuello del decode raramente es la potencia de esos SMs. Cada paso de decode lanza cientos de kernels diminutos (varias proyecciones por capa × ~80 capas), y cada kernel launch cuesta 5-10 µs de CPU en serie. Como en decode los kernels son pequeños (batch pequeño, un solo token), la GPU los termina antes de que la CPU cante el siguiente: aparecen burbujas y la GPU se aburre esperando órdenes. Ese régimen se llama launch-bound, y es la razón profunda —no la potencia, no la memoria— por la que --enforce-eager rinde 54 tok/s donde con optimizaciones se llega a 89-140. La solución es CUDA graphs: grabar la secuencia entera de kernels una vez y reproducirla como una sola sumisión, eliminando el overhead por lanzamiento (~28% de la latencia por iteración). vLLM captura ~102 graphs al arrancar y rellena (padding) el batch real al bucket más cercano para poder reproducir un graph de forma fija. Este post explica SM, ocupación, streams, el launch overhead con matemáticas, los CUDA graphs, los 10 knobs, y la trampa de que esa captura es la segunda mitad del cold start del post anterior. Con escepticismo sobre qué mueve la aguja. Sobre el cluster genérico 4×H100 SXM.

Dónde estás: el silicio, por debajo del kernel launch

La analogía: el jefe que canta cada comanda

Última escena en el restaurante de la serie. La cocina está montada, la despensa subida (el post anterior). Ahora hay que emplatar. Los fogones son los SMs: 132 estaciones que cocinan en paralelo. El jefe de cocina es la CPU: canta las comandas —cada kernel launch es un grito de “¡marchando una multiplicación de matrices!”. Los cocineros (los SMs) ejecutan lo que el jefe canta.

En prefill —procesar el prompt entero— cada comanda es un plato enorme: una matmul gigante sobre cientos de tokens a la vez. El jefe canta una comanda y los fogones tardan un buen rato en sacarla. El jefe tiene tiempo de sobra para cantar la siguiente. Los fogones están a tope: compute-bound.

En decode —generar un token cada vez— cada comanda es minúscula: una matmul sobre un solo token. El fogón la termina en un instante… y se queda mirando al jefe esperando la siguiente. Pero el jefe solo puede cantar una comanda cada 5-10 µs, y hay cientos de comandas por token. Los fogones, rapidísimos, se aburren entre grito y grito. El restaurante no va lento porque los cocineros sean malos: va lento porque el jefe no canta lo bastante rápido. Ese es el régimen launch-bound.

La solución no es más fogones ni cocineros más rápidos. Es dejar de cantar comanda a comanda. Si el jefe imprime toda la secuencia de la noche en una sola hoja y se la da a la línea —“haced esto, en este orden, sin esperarme”—, los fogones corren sin pausas. Eso es un CUDA graph: grabar la secuencia de kernels una vez y reproducirla de un golpe, sin que la CPU cante cada uno. Y --enforce-eager es exactamente lo contrario: obligar al jefe a cantar comanda a comanda, toda la noche.

El mecanismo: SM, warps y ocupación

Una H100 SXM tiene ~132 SMs. Cada SM ejecuta hilos en grupos de 32 llamados warps, y puede tener varios warps “en vuelo” a la vez. La ocupación (occupancy) es la fracción de warps activos respecto al máximo que el SM soporta. ¿Para qué sirve tener muchos warps activos? Para esconder latencia: mientras un warp espera datos de la HBM (cientos de ciclos), el SM ejecuta otro warp listo. Con pocos warps, el SM se queda sin nadie a quien dar turno y se para.

Pero —y esto es clave— la ocupación es una condición necesaria, no suficiente, y solo importa si el SM tiene trabajo que hacer. En decode, el problema típico no es ocupación baja dentro de un kernel: es que entre kernels el SM no tiene nada, porque la CPU aún no ha lanzado el siguiente. Subir la ocupación de un kernel que dura 8 µs no ayuda si la GPU pasa 6 µs esperando a que lo lancen.

El mecanismo: streams, la cola de órdenes

Un CUDA stream es una cola de operaciones que la GPU ejecuta en orden. Operaciones en el mismo stream son secuenciales; operaciones en streams distintos pueden solaparse. Es lo que permite, por ejemplo, copiar datos H2D en un stream mientras otro stream computa —el solapamiento cómputo/copia. vLLM usa streams para solapar trabajo, pero el stream por sí solo no elimina el coste de lanzar cada kernel: solo decide el orden y el paralelismo. El coste de lanzamiento sigue ahí, comanda a comanda, hasta que entran los graphs.

Las matemáticas que importan: cuándo la GPU se queda esperando

El número que lo gobierna todo: un kernel launch cuesta 5-10 µs de CPU, en serie. Pongamos un Llama-70B con ~80 capas. Cada capa, sin fusión, lanza del orden de ~10 kernels (proyecciones Q/K/V, atención, proyección de salida, las dos o tres matmuls del MLP, las normalizaciones, RoPE…). Eso son:

$$ N_{\text{kernels}} \approx 80 \text{ capas} \times 10 \approx 800 \text{ lanzamientos por token} $$

A 5 µs por lanzamiento, en serie:

$$ T_{\text{launch}} \approx 800 \times 5,\mu s = 4{,}0 \text{ ms por token} $$

Esos 4 ms son solo CPU cantando comandas, sin contar lo que tardan los SMs en cocinar. Si la GPU pudiera computar instantáneamente, el techo por lanzamiento sería ~250 tok/s —y con puntos de sincronización entre kernels, peor. Ahora comparemos con el techo de memoria del decode: cada token lee los 140 GB de pesos una vez desde la HBM:

$$ T_{\text{mem}} = \frac{140 \text{ GB}}{3{,}35 \text{ TB/s}} \approx 42 \text{ ms} ;\Rightarrow; \approx 24 \text{ tok/s (una secuencia, sin batch)} $$

Aquí está la sutileza que casi nadie tiene en la cabeza. Para una sola secuencia, el decode es memory-bound a ~24 tok/s, y los 4 ms de launch caben dentro de los 42 ms de lectura: el lanzamiento se esconde. Pero el batching lo cambia todo. Al servir un batch de B secuencias, los pesos se leen una vez y sirven a las B —el coste de memoria por token se amortiza y cae. La GPU deja de ser memory-bound… y emerge lo que estaba debajo: el coste de lanzamiento, que no se amortiza con el batch porque hay que lanzar la misma secuencia de kernels igual. Resultado: cuanto mejor batcheas, más launch-bound te vuelves, y más rinden los CUDA graphs. Por eso la medida cruda lo confirma —--enforce-eager da 54 tok/s donde los graphs dan 89, y hasta 8× en configuraciones donde el decode es muy pequeño y el launch domina del todo.

Los CUDA graphs de vLLM, en concreto

vLLM no captura un graph único: captura ~102 al arrancar —del orden de 51 piecewise (para los pasos mixtos prefill+decode) y 51 full (para decode puro). Cada uno está grabado para un tamaño de batch fijo (un bucket: 1, 2, 4, 8… hasta un máximo). En servicio, el batch real casi nunca cae justo en un bucket, así que vLLM rellena con ceros (padding) hasta el bucket inmediatamente superior, reproduce ese graph, y recorta la salida al tamaño real. Es el precio de los graphs: necesitan formas estáticas, y el padding es lo que las hace estáticas.

Esto tiene dos consecuencias que aparecen en los knobs y las trampas:

La captura cuesta tiempo y memoria. Grabar 102 graphs al arranque añade segundos al cold start —la segunda mitad del arranque que el post anterior dejó pendiente— y consume HBM (cada graph retiene sus buffers). El modo FULL_AND_PIECEWISE (defecto) es el más rápido en servicio pero el que más memoria y más tiempo de captura pide; FULL_DECODE_ONLY ahorra ambos a cambio de no acelerar los pasos mixtos.

El padding desperdicia algo de cómputo. Rellenar un batch de 33 hasta el bucket de 64 computa 31 secuencias fantasma. Es un coste pequeño frente a lo que ahorra quitar el launch overhead, pero existe, y crece si los buckets están mal elegidos.

Los 10 knobs donde tocar

Knob 1 — Medir si el decode es launch-bound

Antes de tocar: ¿está la GPU computando o esperando? Con nsys (Nsight Systems) se ven los huecos entre kernels en la línea de tiempo —si hay huecos en decode, es launch-bound y los graphs ayudarán. Si la GPU está al 100% sin huecos, el cuello es otro (memoria o cómputo) y los graphs no harán milagros. nvidia-smi dmon con utilización baja en decode pero TPS pobre es la señal barata.

Knob 2 — No usar `--enforce-eager` en producción

--enforce-eager desactiva los CUDA graphs. Es una herramienta de depuración (para aislar qué kernel falla), no de producción. Dejarlo puesto “porque arrancaba antes” tira el 26-50% del throughput de decode. Si está en tu comando de producción, quítalo y mide.

Knob 3 — Buckets de captura (`cudagraph_capture_sizes`)

Qué tamaños de batch capturar. Buckets demasiado espaciados hacen padding caro; demasiados, captura lenta y mucha HBM. Ajustarlos a la distribución real de tamaños de batch que ves en producción es la afinación fina —pero solo después de medir esa distribución.

Knob 4 — Modo de CUDA graph

FULL_AND_PIECEWISE (defecto, más rápido, más memoria/captura), FULL_DECODE_ONLY (ahorra memoria y captura, ideal para pods de decode puro de disaggregated serving), PIECEWISE, o NONE (= eager). El modo correcto depende de si el pod hace decode puro o mixto.

Knob 5 — `torch.compile`

vLLM se apoya en torch.compile para fusionar y optimizar kernels antes de capturarlos en graphs. Menos kernels (fusión) = menos lanzamientos = menos dependencia del graph y mejor decode incluso eager. El nivel de compilación es un knob, con su coste de tiempo de arranque.

Knob 6 — Batch size: llenar los fogones

El decode memory-bound se amortiza batcheando (como vimos en continuous batching): leer los pesos una vez para B secuencias. Más batch = más ocupación de SM y más amortización de memoria. El límite lo pone la HBM disponible para el KV cache. Es el knob que más mueve el throughput agregado.

Knob 7 — No romper el solapamiento de streams

vLLM solapa cómputo y copia con streams. Parchear el código para “simplificar” puede serializar lo que estaba solapado. Si no sabes por qué hay varios streams, no los colapses.

Knob 8 — Persistence mode + clocks bloqueados

nvidia-smi -pm 1 mantiene el driver residente (evita reinicializaciones que añaden latencia de lanzamiento). Bloquear clocks a la frecuencia de boost evita que la GPU baje de P-state entre kernels diminutos de decode y pague latencia de subida. Es el mismo espíritu anti-jitter del post de NUMA, aplicado a la GPU.

Knob 9 — Kernels fusionados (FlashAttention, kernels FP8)

Menos kernels = menos comandas que cantar. FlashAttention fusiona la atención en un kernel en vez de varios; los kernels FP8 fusionados reducen el conteo. La fusión ataca el problema en la raíz: no acelera el lanzamiento, elimina lanzamientos.

Knob 10 — Aceptar el coste de captura en el cold start

La captura de graphs añade segundos al arranque. En un pod que vive horas, se amortiza sobradamente. En uno que escala arriba y abajo cada minuto, ese coste se paga una y otra vez —ahí FULL_DECODE_ONLY (captura más corta) o aceptar algo menos de throughput puede salir a cuenta. Es la misma tensión warm-vs-elástico del cold start.

Tabla resumen

#	Knob	Qué ataca	Riesgo / coste
1	`nsys` / `dmon`	saber si es launch-bound	ninguno; hazlo primero
2	quitar `--enforce-eager`	graphs desactivados	era para depurar; reactiva el problema si vuelve un bug
3	buckets de captura	padding caro / captura lenta	requiere medir la distribución real
4	modo de graph	memoria y captura	menos cobertura en pasos mixtos
5	`torch.compile`	kernels sin fusionar	tiempo de arranque
6	batch size	ocupación + memoria	HBM para KV cache
7	streams	solapamiento roto	no tocar si no se entiende
8	persistence + clocks	jitter / P-states	consumo eléctrico
9	kernels fusionados	número de lanzamientos	compatibilidad del kernel
10	captura vs cold start	arranque más lento	menos throughput si se recorta

Cómo se conecta con el resto del stack

Con el cold start. La captura de CUDA graphs es la segunda mitad del arranque que abrió el post anterior: cargar pesos + capturar graphs = el cold start completo.

Con continuous batching. El batching continuo es lo que vuelve launch-bound al decode (amortiza la memoria y deja el lanzamiento al descubierto), y por eso los graphs y el batching se potencian mutuamente.

Con el KV cache. El KV cache decide cuánto batch cabe en HBM, y el batch decide la ocupación de SM y cuánto importa el launch overhead. Todo está acoplado por la memoria.

Con el interconnect. En TP, entre los kernels de cómputo hay all-reduces (NVLink/NCCL) que también se lanzan y sincronizan. El custom all-reduce de vLLM se integra en el mismo graph para no romper la secuencia con una sincronización de CPU.

Con NUMA. Quién lanza los kernels es la CPU del post del host; si ese hilo sufre jitter o cae en el socket equivocado, el launch overhead empeora. Los graphs reducen la dependencia de ese hilo, que es otra razón por la que ayudan.

Con disaggregated serving. Los pods de decode puro del serving desagregado son el caso ideal de FULL_DECODE_ONLY: maximizan el beneficio del graph justo en la fase más launch-bound.

Trampas y cosas que no son lo que parecen

“Subir la ocupación arreglará el decode lento.” No, si el problema es launch-bound. La ocupación importa dentro de un kernel con trabajo; si la GPU está ociosa entre kernels esperando a la CPU, más ocupación no toca esa burbuja. Mide antes de optimizar lo que no es el cuello.

“Los CUDA graphs siempre aceleran.” Aceleran cuando el decode es launch-bound. Si la GPU ya está al 100% (compute-bound en prefill, o memoria saturada con batch enorme), los graphs aportan poco. Su terreno es el decode con kernels pequeños.

"--enforce-eager da resultados más estables." Da resultados más lentos. La estabilidad que parece dar es que evita bugs de captura de graphs en hardware nuevo (p. ej. una arquitectura recién soportada). Es un parche temporal, no una configuración de producción.

Capturar demasiados buckets “por si acaso”. Cada bucket añade tiempo de captura y HBM. Capturar 30 tamaños cuando en producción solo ves 4 es pagar cold start y memoria por graphs que nunca se reproducen. Ajusta a la distribución real.

Confundir utilización con eficiencia. nvidia-smi al 100% de “utilización” solo dice que hay un kernel corriendo, no que el SM esté lleno de trabajo útil. Un kernel de baja ocupación mantiene la “utilización” alta mientras desperdicia el SM. La utilización de nvidia-smi es un termómetro grueso; para saber si el silicio rinde hace falta nsys/DCGM y mirar ocupación real y huecos.

Optimizar el silicio antes que la memoria. Si el decode está limitado por ancho de banda HBM (batch grande, modelo grande), pelear con graphs y ocupación es pulir lo que no es el cuello. El orden correcto: medir el régimen (memoria / cómputo / lanzamiento) y atacar el que manda.

Conclusión

La intuición dice que una GPU generando tokens lentos está “trabajando duro”. Casi nunca: en decode está esperando órdenes. Los 132 SMs cocinan un token diminuto en un instante y se quedan mirando a la CPU, que solo puede cantar una comanda cada 5-10 µs y tiene cientos que cantar por token. Ese cuello —ni potencia, ni memoria, sino lanzamiento— es invisible en cualquier dashboard que mire “utilización de GPU”, y es la razón real por la que --enforce-eager rinde la mitad. Los CUDA graphs lo resuelven con una idea simple: dejar de cantar comanda a comanda y entregar la hoja entera de la noche, para que el silicio corra sin pausas. Y hay una verdad incómoda que reordena la prioridad de optimización: cuanto mejor batcheas, más launch-bound te vuelves —porque el batching mata el cuello de memoria y deja al descubierto el de lanzamiento. Por eso los graphs y el batching no son optimizaciones separadas: son la misma palanca vista desde dos lados. El jefe que aprende a no cantar cada plato es lo que hace que la cocina, por fin, vaya tan rápido como los fogones siempre pudieron.

Ver también

El pase: el scheduler step de vLLM — quién arma el batch cuyos tamaños deberían caer en los buckets de captura de los CUDA graphs; scheduler y graphs se acoplan por el tamaño de batch.
Del disco a la HBM: cold start y carga del modelo — la primera mitad del arranque; la captura de graphs de este post es la segunda mitad del mismo cold start.
La planta de al lado: NUMA, hugepages y aislamiento de CPU — quién lanza los kernels es ese hilo de host; su jitter es el launch overhead que los graphs reducen.
La mesa compartida: NVLink, NVSwitch y NCCL — los all-reduces de TP se lanzan y sincronizan entre kernels; el custom all-reduce de vLLM se integra en el mismo graph.
Continuous batching — lo que vuelve launch-bound al decode al amortizar la memoria; por eso batching y graphs se potencian.
KV cache — la memoria que decide cuánto batch cabe, y por tanto la ocupación de SM y cuánto pesa el launch overhead.
Disaggregated serving: prefill y decode separados — los pods de decode puro son el caso ideal de FULL_DECODE_ONLY.
Quantization para inferencia — los kernels FP8 fusionados reducen el número de lanzamientos en la raíz.
Observabilidad GPU con DCGM — dónde se ve la ocupación real y los contadores que distinguen “utilización” de eficiencia.

Referencias

vLLM, CUDA Graphs (diseño, modos FULL/PIECEWISE, captura): https://docs.vllm.ai/en/stable/design/cuda_graphs/.
vLLM, Inside vLLM: Anatomy of a High-Throughput LLM Inference System: https://blog.vllm.ai/2025/09/05/anatomy-of-vllm.html.
NVIDIA, Getting Started with CUDA Graphs: https://developer.nvidia.com/blog/cuda-graphs/.
NVIDIA, Achieved Occupancy (ocupación de SM): https://archive.docs.nvidia.com/gameworks/content/developertools/desktop/analysis/report/cudaexperiments/kernellevel/achievedoccupancy.htm.
PyTorch, torch.compile y CUDA Graphs para inferencia LLM: https://docs.vllm.ai/en/stable/design/cuda_graphs/.
Understanding the Overheads of Launching CUDA Kernels (ICPP 2019): https://www.hpcs.cs.tsukuba.ac.jp/icpp2019/data/posters/Poster17-abst.pdf.

El montacargas de la despensa: del disco a la HBM, o por qué la cocina abre tarde

Sun, 07 Jun 2026 08:30:00 +0200

Esta es una bajada al sótano. La serie por debajo del motor optimizó la ruta caliente —lo que pasa con cada token ya en servicio. Este post mira el trayecto de antes de servir: cómo los pesos suben del disco a la HBM. Es el primero de un par sobre las dos cosas que pasan fuera de la API y casi nadie cronometra: la carga del modelo (este) y la ejecución en el silicio (el siguiente).

TL;DR

Antes de que un pod de inferencia genere su primer token, tiene que subir el modelo entero a la HBM. Un Llama-70B en FP16 son 140 GB que viajan por un camino que nadie dibuja: disco → page cache → buffer de host → PCIe → HBM. La intuición falla aquí: la HBM no es el cuello —mueve 3,35 TB/s y traga 140 GB en 42 ms—; el cuello es la cadena de suministro. El disco NVMe Gen5 lee a ~14 GB/s (10 s para 140 GB); el PCIe Gen5 copia host→GPU a ~50 GB/s (2,8 s); y el loader de safetensors por defecto, que deserializa tensor a tensor y rebota cada byte por un buffer de CPU, infla todo eso hasta 30-60 s. Ese tiempo es el cold start, y es el impuesto oculto que pagan el autoscaling (scale-from-zero), el canary/blue-green y el disaggregated serving cada vez que nace un pod. Hay tres familias de solución —GPUDirect Storage (DMA directo disco→HBM, sin rebote por CPU), fastsafetensors (4,8-7,5× sobre el loader por defecto) y el Run:ai Model Streamer (lectura concurrente que satura el disco)— más la palanca más simple de todas: mover menos bytes (FP8 es la mitad que FP16). Este post explica el camino, las matemáticas, los 10 knobs, y la trampa más cruel: “la segunda vez cargó rápido” no es tu loader siendo bueno, es la page cache mintiéndote. Sobre el cluster genérico 4×H100 SXM.

Dónde estás: el sótano, antes de abrir

La analogía: el montacargas de la despensa

Sigamos en el restaurante de la serie. La mesa compartida era el NVSwitch, la planta de al lado era el NUMA, el maître era el kubelet. Todo eso describe el restaurante funcionando, con comensales sentados. Pero hay un momento que ningún post miró: antes de abrir, alguien tiene que subir toda la despensa desde el almacén del sótano hasta la cocina.

Los pesos del modelo son los ingredientes. Viven en el almacén del sótano (el disco). La cocina —la línea caliente donde se emplatan los tokens— es la HBM de la GPU. Y entre uno y otro hay un montacargas: el camino disco → host → PCIe → HBM. La cocina no puede servir el primer plato hasta que la despensa esté arriba y colocada. Ese tiempo de reposición es el cold start.

La trampa de la intuición: la cocina (HBM) es enorme y rapidísima, coloca ingredientes a 3,35 TB/s. Así que culpamos a la cocina cuando el restaurante abre tarde. Pero la cocina está parada esperando el montacargas. El cuello nunca es la línea caliente: es el montacargas y el almacén. Y, peor todavía, hay un mozo (el loader por defecto) que en vez de cargar cajas enteras, saca los ingredientes uno a uno, los apunta en una libreta y los vuelve a empaquetar antes de subirlos. Ese mozo —no el montacargas— es la mitad del problema.

El mecanismo: qué pasa de verdad al cargar un modelo

Cuando vLLM arranca con un modelo en safetensors, los 140 GB del Llama-70B FP16 hacen este viaje:

Disco → page cache. El kernel lee los ficheros .safetensors del NVMe a la page cache (RAM de host). Si es la primera vez tras un reinicio, es lectura física del disco (~14 GB/s en Gen5). Si los ficheros ya están en page cache de un arranque anterior, esto es casi gratis —y aquí nace la trampa que veremos.
Deserializar. El loader de Hugging Face por defecto hace mmap del fichero y construye los tensores uno a uno, copiándolos a un tensor de CPU antes de moverlos. Es trabajo de CPU monohilo que no satura ni el disco ni el PCIe: la mayoría del tiempo de carga “lenta” se va aquí, no en mover bytes.
Host → HBM (H2D). Cada tensor se copia del buffer de host a la HBM por PCIe Gen5 x16 (~50 GB/s prácticos). Para que el DMA sea eficiente, el buffer de host debería ser pinned —lo que conecta directamente con las hugepages y la memoria fijada del post de NUMA.
Colocar en HBM. La HBM recibe los 140 GB. A 3,35 TB/s, esto tarda 42 ms. Nunca es el cuello.

El camino tiene un atajo: GPUDirect Storage (GDS). En vez de rebotar por el buffer de CPU (paso 2-3), un motor DMA cerca del controlador NVMe escribe directamente del disco a la HBM, sin involucrar a la CPU. Es el mismo principio que el GPUDirect RDMA de red: sacar a la CPU del medio. fastsafetensors usa GDS y alcanza 26,4 GB/s leyendo un Llama-70B desde NVMe sobre 4 GPUs.

Por qué existe el problema: la economía de bytes

El tamaño del modelo en bytes lo decide la cuantización, y eso fija el suelo del cold start —porque hay que mover todos esos bytes antes del primer token. Para un modelo de 70B parámetros:

Formato	Bytes/parám	Tamaño 70B	Leer 1 NVMe @14 GB/s	H2D PCIe @50 GB/s	HBM @3,35 TB/s
FP16 / BF16	2	140 GB	10,0 s	2,8 s	42 ms
FP8	1	70 GB	5,0 s	1,4 s	21 ms
INT4 (GPTQ/AWQ)	0,5	~35 GB	2,5 s	0,7 s	10 ms

Tres lecturas de esta tabla:

La HBM nunca aparece como problema. La última columna es siempre milisegundos. Quien diga “la GPU tarda en cargar” está culpando al sitio equivocado.

Cuantizar es la palanca de cold start más infravalorada. Pasar de FP16 a FP8 no solo dobla el throughput de inferencia (menos ancho de banda HBM por token, como vimos en quantization): también parte por la mitad el cold start, porque hay la mitad de bytes que subir. Es un dos por uno que el dimensionado suele ignorar.

El disco es el cuello de los bytes; el loader es el cuello del tiempo. Las cifras de la tabla son el suelo teórico —solo mover bytes. El loader por defecto añade el deserializado monohilo encima, que es la diferencia entre los 10 s teóricos y los 30-60 s reales. Por eso las soluciones atacan en dos frentes: menos bytes (cuantización) y mejor mozo (loaders concurrentes / GDS).

Las matemáticas que importan: el cold start como impuesto del autoscaling

El cold start no se paga una vez. Se paga cada vez que nace un pod. Y en una plataforma elástica, los pods nacen continuamente.

Pongamos un autoscaling con KEDA que escala de 2 a 6 réplicas cuando sube la cola. Las 4 réplicas nuevas tardan en estar listas:

$$ T_{\text{ready}} = T_{\text{schedule}} + T_{\text{pull-image}} + T_{\text{load-weights}} + T_{\text{cuda-graphs}} $$

Con un Llama-70B FP16 y el loader por defecto, $T_{\text{load-weights}}$ domina: puede ser 40 s de los ~60 s totales. Durante esos 40 s, la cola que disparó el autoescalado sigue creciendo —las réplicas nuevas no absorben tráfico hasta que cargan. El número real de la fórmula no es “cuántas réplicas”, es cuánto tarda cada una en empezar a servir, y ese número lo escribe el camino de carga.

Esto tiene una consecuencia operativa dura: scale-to-zero es inviable para cargas con SLO de latencia si el cold start es de 40 s. Nadie espera 40 s al primer token. La elasticidad real de una plataforma de inferencia no la limita la GPU disponible —la limita cuánto tarda esa GPU en tener el modelo dentro. Bajar el cold start de 40 s a 8 s (con streamer + FP8) es lo que convierte “scale-to-zero teórico” en “scale-to-zero usable”.

Los números publicados dan el orden de magnitud de la mejora: fastsafetensors reduce el arranque de 12,39 s a 4,74 s en un Llama-2-13B sobre 4×L40S, y de 16,04 s a 6,88 s en 1×A100 —4,8-7,5× sobre el deserializador por defecto. El Run:ai Model Streamer carga en 4,88 s desde S3 a concurrencia 32 y 7,53 s desde SSD IO2 a concurrencia 8; integrado en vLLM, el tiempo total hasta ready baja a ~23 s desde S3. No son magias: es sacar a la CPU del bucle (GDS) y leer en paralelo (concurrencia) para saturar el disco en vez de dejarlo medio ocioso mientras un hilo deserializa.

Los 10 knobs donde tocar

Knob 1 — Medir dónde se va el tiempo (read vs deserializar vs H2D)

Antes de tocar nada: cronometrar. ¿El tiempo está en leer del disco, en deserializar, o en el H2D? iostat -x 1 durante la carga dice si el NVMe está saturado (cuello de disco) o casi ocioso (cuello de loader/CPU). Si el disco va al 20%, el problema no es el disco: es el mozo. Cambiar de disco no arreglaría nada; cambiar de loader, sí.

Knob 2 — `--load-format`: elegir el mozo

vLLM expone varios cargadores vía --load-format: safetensors (defecto), runai_streamer, fastsafetensors, tensorizer. El defecto es el más lento. El cambio de una bandera puede ser el 4-7× más barato que existe.

# Run:ai Model Streamer (lectura concurrente, satura el disco)
vllm serve meta-llama/Llama-3.1-70B --load-format runai_streamer
# fastsafetensors (GPUDirect Storage, DMA directo disco→HBM)
vllm serve meta-llama/Llama-3.1-70B --load-format fastsafetensors

Knob 3 — Concurrencia del streamer

El Run:ai Model Streamer reparte la lectura en N hilos según el tamaño de cada tensor para saturar el ancho de banda del almacenamiento. La concurrencia es el parámetro clave: 16 suele bastar para NVMe local; 32 (a veces 64) para almacenamiento de red de alto throughput. Un hilo no satura un NVMe Gen5; 32 sí.

vllm serve <model> --load-format runai_streamer \
 --model-loader-extra-config '{"concurrency": 32}'

Knob 4 — GPUDirect Storage (GDS) + fastsafetensors

Si hay driver nvidia-fs, filesystem soportado y NVMe local, GDS escribe directo disco→HBM sin rebote por CPU. Es la diferencia entre los dos caminos del diagrama. Pero: requiere el stack montado y solo gana si el cuello es el rebote por CPU, no el propio disco. Verificar con gdscheck.

Knob 5 — NVMe local para los pesos, no red

Servir los pesos desde Ceph RGW / NFS es cómodo (un sitio compartido) pero mete la red en el camino de carga. Para el cold start, pesos en NVMe local del nodo (o cache local). El almacenamiento de red es para el repositorio de modelos; el nodo de inferencia debería tener una copia local caliente.

Knob 6 — Pre-pull / cache local del modelo

Un initContainer que descarga el modelo a un volumen local o hostPath NVMe antes de arrancar vLLM convierte un cold start “desde la red” en uno “desde NVMe local”. Combinado con un DaemonSet de cache por nodo, los pods nuevos en un nodo ya caliente leen del disco local, no de la red.

Knob 7 — Cuantización: mover menos bytes

Pesos ya en FP8 o INT4 en el disco = la mitad o un cuarto del cold start. Es el knob de la tabla de arriba. Y se compone con todos los demás: FP8 + streamer + GDS es multiplicativo.

Knob 8 — Carga paralela entre GPUs (vLLM V1)

El engine V1 de vLLM (defecto desde 0.19) carga los shards de pesos en paralelo entre las GPUs de un TP, en vez de secuencialmente. En TP=4, cada GPU carga su cuarto a la vez. Verificar que está activo; en versiones viejas la carga era serial y el cold start de TP=4 era casi 4× el de TP=1.

Knob 9 — Localidad NUMA del NVMe

El NVMe cuelga de un PCIe root bajo un socket concreto —exactamente el mismo mapa NUMA del post del host. Si el buffer de host de la carga cae en el socket equivocado, el H2D cruza la UPI. La quinta lista a alinear, junto a isolcpus, reserved-cpus e IRQ de la NIC: qué socket es local al NVMe y a la GPU destino. nvidia-smi topo -m lo muestra.

Knob 10 — No pagar el cold start: mantener pods calientes

A veces la respuesta no es cargar más rápido, sino no descargar. Un suelo de réplicas siempre vivas (no scale-to-zero), o un pool de warm standby precargado, cambia “esperar 40 s” por “0 s”. Es coste de GPU ociosa a cambio de latencia de arranque: una decisión de capacity planning, no técnica.

Tabla resumen

#	Knob	Qué ataca	Riesgo / coste
1	`iostat` al cargar	saber si el cuello es disco o loader	ninguno; hazlo siempre primero
2	`--load-format`	el deserializado monohilo	compatibilidad del formato
3	concurrencia streamer	disco infrautilizado	RAM de host por buffers
4	GPUDirect Storage	rebote por CPU	requiere nvidia-fs + FS soportado
5	NVMe local vs red	la red en el camino	duplicar pesos por nodo
6	pre-pull / cache nodo	red en cada arranque	espacio en disco local
7	cuantización FP8/INT4	bytes a mover	calidad (medir, no asumir)
8	carga paralela V1	carga serial entre GPUs	ninguno si V1 activo
9	NUMA del NVMe	H2D cruzando UPI	alinear con el resto de listas NUMA
10	warm pods / no zero	el cold start entero	GPU ociosa pagada

Cómo se conecta con el resto del stack

Con el autoscaling. Todo el scale-from-zero con KEDA descansa sobre esto: la elasticidad real la limita el cold start, no la GPU disponible. Un autoescalado con 40 s de carga reacciona tarde a cada pico.

Con el disaggregated serving. En prefill/decode desagregado, levantar un pool de decode bajo demanda paga el cold start de cargar el modelo en cada pod nuevo. La elasticidad del patrón depende de cuán rápido arrancan esos pods.

Con canary/blue-green. Cada despliegue canary carga una versión nueva del modelo en paralelo a la vieja. El tiempo de validación de un canary incluye su cold start; modelos grandes hacen los despliegues más lentos y caros.

Con NUMA y hugepages. El buffer de host de la carga quiere ser pinned y NUMA-local —lo mismo que pedía el post del host para la ruta caliente. El camino de carga es otro cliente del mismo mapa NUMA.

Con la cuantización. FP8/INT4 no es solo throughput de inferencia: es la palanca directa sobre los bytes del cold start.

Con capacity planning. El dimensionado que ignora el cold start subestima cuántas réplicas hacen falta para absorber un pico: si tardan 40 s en arrancar, necesitas más colchón permanente.

Trampas y cosas que no son lo que parecen

“La segunda vez cargó rapidísimo.” Es la trampa estrella. La primera carga llenó la page cache (RAM de host); la segunda lee de RAM, no del disco, y vuela. Pero en producción los pods son efímeros y nacen en nodos distintos: el arranque que cuenta es el frío, en un nodo donde esos ficheros no están en page cache. Benchmarquear la segunda carga es medir una situación que casi nunca ocurre en el momento que importa (el pico que dispara el autoescalado).

“GDS siempre acelera.” No. GDS elimina el rebote por CPU; si tu cuello es el propio disco (NVMe saturado) o el deserializado, GDS no toca esa parte. Mide primero (knob 1). Además exige nvidia-fs, un filesystem soportado y a veces no funciona sobre el almacenamiento de red que tengas.

“mmap hace la carga instantánea.” mmap mapea el fichero pero no lee nada todavía: el coste se difiere al primer acceso a cada página. El tiempo no desaparece, se mueve —el primer token paga los page faults que el arranque no pagó. Has movido el cold start a la latencia del primer request, que probablemente es peor sitio para tenerlo.

Pesos en almacenamiento de red “porque es más limpio”. Compartir un repositorio de modelos en Ceph RGW está bien para almacenarlos; servir el cold start desde ahí mete la red (y su latencia y su contención) en el camino crítico. Cache local NVMe en el nodo de inferencia.

Cargar FP16 y cuantizar en el arranque. Cuantizar al vuelo durante la carga (p. ej. FP16→FP8 en GPU) puede ser más lento que tener los pesos ya cuantizados en disco: mueves el doble de bytes y encima haces trabajo de conversión. Si vas a servir en FP8, guarda los pesos en FP8.

Optimizar la carga e ignorar T_cuda-graphs. Bajar la carga de pesos a 8 s y olvidar que la captura de CUDA graphs añade varios segundos más deja el cold start a medias. Esa segunda mitad del arranque es el tema del post siguiente.

Conclusión

Toda la serie optimizó lo que pasa con cada token: el cable, el host, la red, el silicio. Pero antes del primer token hay un trayecto que casi nadie cronometra y que decide si un pod de inferencia abre en 10 s o en 60 s: subir el modelo del disco a la HBM. La intuición culpa a la GPU, y la GPU es inocente —la HBM traga 140 GB en 42 ms. El cuello es la cadena de suministro: un disco que lee a 14 GB/s, un PCIe que copia a 50, y sobre todo un loader por defecto que deserializa tensor a tensor con un solo hilo y convierte 10 s de bytes en 60 s de espera. Las soluciones atacan los dos frentes correctos —menos bytes (cuantización) y mejor transporte (GDS, streamers concurrentes, NVMe local)— y dan 4-7× casi gratis. Y por encima de la técnica, una idea que reordena la prioridad: en una plataforma elástica, el cold start no es un detalle de arranque, es el techo de la elasticidad. La GPU más rápida del mundo no escala si tarda 40 s en tener el modelo dentro. El montacargas de la despensa, ese que nadie cronometró, es lo que decide a qué hora abre de verdad la cocina.

Ver también

Los pasillos y el guardia: PCIe, GPUDirect P2P y ACS — el bus por el que GDS sube los pesos del NVMe; el ACS activo estrangula ese camino directo igual que estrangula el P2P entre GPUs.
El pase: el scheduler step de vLLM — el cold start es el techo de la elasticidad que el scheduler ejerce: la preemption y el scale-from-zero pagan esta carga en cada pod nuevo.
La mesa compartida: NVLink, NVSwitch y NCCL — el primero de “por debajo del motor”; este post baja al sótano que aquella serie daba por lleno.
La planta de al lado: NUMA, hugepages y aislamiento de CPU — la memoria pinned y NUMA-local que el camino de carga necesita para un H2D eficiente.
La puerta de la cocina: NUMA de red, Cilium eBPF y DRANET — el mismo principio de “saca a la CPU del medio” (GPUDirect) que aquí aplica GDS al disco.
SM, CUDA streams y CUDA graphs — la segunda mitad del cold start (captura de graphs) y lo que pasa en el silicio una vez los pesos están dentro.
Quantization para inferencia — la palanca que parte por la mitad los bytes del cold start, no solo el ancho de banda HBM por token.
Autoscaling de LLM en Kubernetes con KEDA — por qué el cold start es el techo real de la elasticidad y mata el scale-to-zero.
Disaggregated serving: prefill y decode separados — levantar pools bajo demanda paga el cold start en cada pod nuevo.
Canary, blue-green y shadow para modelos — el tiempo de validación de un canary incluye su carga del modelo.
Capacity planning de inferencia on-premise — el cold start como parámetro del colchón de réplicas y de la decisión warm-vs-zero.

Referencias

NVIDIA, Reducing Cold Start Latency for LLM Inference with NVIDIA Run:ai Model Streamer: https://developer.nvidia.com/blog/reducing-cold-start-latency-for-llm-inference-with-nvidia-runai-model-streamer/.
vLLM, Loading models with Run:ai Model Streamer: https://docs.vllm.ai/en/stable/models/extensions/runai_model_streamer/.
vLLM, Loading model weights with fastsafetensors: https://docs.vllm.ai/en/stable/models/extensions/fastsafetensor/.
foundation-model-stack, fastsafetensors (loader de alto rendimiento, GDS): https://github.com/foundation-model-stack/fastsafetensors.
Speeding up Model Loading with fastsafetensors (arXiv 2505.23072): https://arxiv.org/html/2505.23072v1.
NVIDIA, GPUDirect Storage: A Direct Path Between Storage and GPU Memory: https://developer.nvidia.com/blog/gpudirect-storage/.
NVIDIA, Magnum IO GPUDirect Storage (benchmarking y configuración): https://developer.nvidia.com/gpudirect-storage.

La puerta de la cocina que el maître no miró: NUMA de red, Cilium eBPF y DRANET, la cuarta pata del pinning

Sat, 06 Jun 2026 12:00:00 +0200

Cuarta entrega —coda— de “por debajo del motor”. La serie cerró con tres patas de la localidad: el cable entre GPUs, el host a mano y la orquestación declarativa del kubelet. Pero el maître del último post sentaba al grupo mirando CPU, memoria y GPU, y nunca preguntó por qué puerta entran los platos. Esa puerta es la NIC. Aquí está la cuarta pata.

TL;DR

El Topology Manager admite un pod en single-numa-node si sus CPUs, su memoria y su GPU caben en el mismo NUMA node. La NIC no entra en esa cuenta: el kubelet no tiene un Hint Provider para la tarjeta de red. En un nodo de inferencia con red a 200/400 Gb/s —el caso de disaggregated serving, donde el KV-cache viaja por RDMA entre el pool de prefill y el de decode— una NIC en el socket equivocado hace que cada paquete cruce la UPI/QPI, exactamente el “NUMA remoto” que la serie combate por el lado de cómputo, pero por la puerta de la red. Y hay un segundo frente: el softirq (NET_RX) que procesa el datapath corre en la CPU que atiende la IRQ de la NIC; si esa CPU es uno de los cores que isolcpus/reserved-cpus dieron en exclusiva a vLLM, el softirq le roba ciclos y mete jitter en la cola de p99. Cilium eBPF sustituye dos piezas de RKE2 —kube-proxy (por load balancing eBPF/XDP) y el CNI por defecto Canal (por datapath nativo)— y su propia guía de tuning te manda matar irqbalance y fijar las IRQ de la NIC: una cuarta lista que alinear junto a isolcpus y reserved-cpus. El estado del arte 2026 cierra el hueco por arriba: netkit (kernel ≥6.8, overhead de namespace a cero), BIG TCP (super-paquetes de 192k para 100Gb/s+), host-routing (bypass de iptables), y sobre todo DRA/DRANET, el driver de red que por fin co-programa GPU y NIC NUMA-locales en el mismo PCIe root, habilitando GPUDirect RDMA con +59,6% de bus bandwidth en all_gather y +58,1% en all_reduce. Sobre un cluster genérico RKE2 con nodos 4×H100 SXM.

Dónde estás: el plano de red que la trilogía no abrió

La analogía: la puerta por la que entran los platos

Vuelve al restaurante del post anterior. El maître —el Topology Manager— sentó al grupo de ocho en una sola mesa (un NUMA node) porque cabían los comensales (CPUs), los cubiertos (memoria) y la botella reservada (la GPU). Mesa perfecta. Pero el maître nunca miró dónde está el pase de cocina: la puerta por la que entra y sale cada plato.

Esa puerta es la NIC. Por ahí entra el prompt, salen los tokens, y —en disaggregated serving— circula el KV-cache que el pool de prefill manda al de decode. Si la mesa está en la sala de la izquierda (socket 0) pero el pase de cocina está en la de la derecha (socket 1), cada plato cruza el restaurante entero (la UPI/QPI), una y otra vez, por mucho que la mesa esté impecablemente puesta. El comensal no nota la mesa perfecta: nota que el plato llega tarde y frío.

Y hay un detalle más fino: el camarero que cruza la sala con los platos (el softirq que procesa los paquetes) es uno de los comensales sentados. Si el maître le asignó una silla en exclusiva para comer tranquilo (un core aislado por isolcpus para vLLM) pero el restaurante lo pone también a hacer de camarero de la puerta lejana, ese comensal no come: se pasa la cena cruzando la sala. El jitter aparece justo donde creías haber comprado calma.

La trilogía niveló tres patas de la mesa: el cable, el host y la orquestación. La cuarta —por qué puerta entran los platos y quién los lleva— no la nivela ningún manager del kubelet. Hasta 2026.

El hueco: por qué el Topology Manager no mira la NIC

El mecanismo del post 3 es un coordinador (Topology Manager) que consulta a tres Hint Providers: CPU Manager, Memory Manager y Device Manager (el plugin de GPU). Cada uno dice en qué NUMA node puede satisfacer su parte; el coordinador calcula la intersección y admite o rechaza.

El problema es de censo: la NIC clásica no es un “device” del Device Manager. Una tarjeta Ethernet/InfiniBand estándar la gestiona el CNI y el kernel, no se pide en el resources: del pod como nvidia.com/gpu, y por tanto no emite hint NUMA. El Topology Manager alinea CPU+memoria+GPU y deja la NIC donde el hardware la puso, que puede ser el otro socket. El maître tiene tres ayudantes y le falta el cuarto: el que sabe por qué puerta entran los platos.

Esto no importaba cuando la red de un nodo eran 10/25 Gb/s y el cuello de botella estaba en otro sitio. Importa ahora, con dos cargas que saturan la red del nodo:

Disaggregated serving. El KV-cache que viaja entre el pool de prefill y el de decode se mueve por RDMA. Son transferencias grandes, sensibles a latencia y ancho de banda, que en multinodo salen por la NIC.
Colectivos NCCL multinodo. Cuando el tensor/pipeline parallel cruza el límite del nodo, los all-reduce/all-gather ya no van por NVLink sino por GPUDirect RDMA sobre la NIC.

En ambos, dónde está la NIC respecto a la GPU y a los cores del pod decide el rendimiento. Y eso el kubelet, por sí solo, no lo coordina.

El datapath de red bajo NUMA: IRQ, softirq y DMA

Para ver por qué la localidad de la NIC pesa, hay que mirar el camino de un paquete que llega:

El Topology Manager hizo su trabajo en el node 1; la NIC se quedó en el 0. Nadie alineó las dos cosas.

Tres hechos del kernel que la analogía comprime:

La IRQ tiene afinidad. Cada cola de la NIC dispara una interrupción que el kernel atiende en una CPU concreta (/proc/irq/<n>/smp_affinity). El procesamiento pesado se difiere a un softirq (NET_RX/NET_TX), que corre en esa misma CPU. Si irqbalance está suelto, las va migrando de forma no determinista —veneno para el p99.
El softirq compite con el pod. Si la IRQ cae en un core que isolcpus reservó para vLLM, el NET_RX de esa cola le roba ciclos al modelo. La señal en /proc/softirqs: una columna de NET_RX que se dispara en una sola CPU. Es el mismo jitter del post 2, entrando por la red.
El DMA tiene origen NUMA. La NIC escribe el paquete por DMA en la RAM del socket de su PCIe root. Si el consumidor (el hilo del pod) está en el otro socket, lee cruzando la UPI/QPI. RFS (Receive Flow Steering) intenta llevar el procesamiento a la CPU del consumidor, pero no puede teletransportar la NIC al otro socket.

Un número, con su salvedad

Pongamos un nodo de 2 sockets, NIC de 400 Gb/s = 50 GB/s en el PCIe root del socket 0, y un pod de decode pinneado al socket 1. Si la NIC satura, esos ~50 GB/s de tráfico de recepción cruzan la UPI hacia el socket 1. Un enlace UPI 2.0 ronda los ~20–40 GB/s por dirección y enlace según generación; aun con varios enlaces, 50 GB/s de tráfico de red a contracorriente se comen una fracción nada despreciable del presupuesto inter-socket —el mismo presupuesto por el que ya compiten los accesos remotos a memoria del pod y, si hay multinodo, el KV-cache de la disaggregation. No doy un “X% de degradación” cerrado porque depende de generación de CPU, número de enlaces UPI, MTU y patrón de tráfico; sin esa metodología, cualquier cifra exacta es marketing.

Lo que sí está medido con metodología pública es el efecto agregado de alinear GPU y NIC: el proyecto DRANET reporta +59,6% de bus bandwidth en all_gather y +58,1% en all_reduce (colectivos NCCL) cuando la NIC asignada es NUMA-local a la GPU frente a no serlo. Esa es la magnitud del hueco que el Topology Manager dejaba abierto.

Qué sustituye Cilium eBPF de RKE2 (y por qué toca esta historia)

RKE2 trae por defecto Canal (Flannel + Calico) como CNI y kube-proxy (reglas iptables/IPVS) para el balanceo de Services. Cambiar a Cilium (cni: cilium en /etc/rancher/rke2/config.yaml) sustituye ambas piezas por un datapath eBPF:

Pieza de RKE2	Qué hace	Qué pone Cilium eBPF
`kube-proxy` (iptables/IPVS)	balanceo de Services	LB en eBPF; con `kubeProxyReplacement=true`, y aceleración en XDP (capa de driver)
Canal (Flannel+Calico)	overlay VXLAN + NetworkPolicy	datapath nativo (`routingMode=native`), NetworkPolicy L3/L4 y L7 en eBPF
veth por pod	par de interfaces del namespace	netkit (kernel ≥6.8): overhead de namespace ~0
recorrido iptables del host	hooks netfilter	host-routing eBPF: bypass de iptables y de la parte alta del stack

Hasta aquí es networking puro y no toca los resource managers del kubelet: Cilium no asigna CPUs exclusivas ni emite hints NUMA de cómputo. Los diez knobs del post 3 siguen idénticos pongas Canal o Cilium.

Pero Cilium sí entra en la cuarta pata por dos puertas. La primera: su propia guía de tuning recomienda, literalmente, “matar irqbalance y fijar las IRQ de la NIC a CPUs específicas para máximo aislamiento de la carga”, además del perfil tuned network-latency, el governor performance y CONFIG_PREEMPT_NONE. Es decir: el datapath eBPF rinde de verdad solo si coordinas la afinidad de IRQ —y esa afinidad tiene que apuntar a los cores housekeeping (reserved-cpus), nunca a los aislados. Aparece así una cuarta lista que mantener coherente con isolcpus y reserved-cpus:

isolcpus = 2-31,34-63 # cores exclusivos para vLLM (host, post 2)
reserved-cpus = 0-1,32-33 # housekeeping del kubelet (post 3)
IRQ affinity = 0-1,32-33 # NIC IRQs → SOLO housekeeping (este post)
 # nunca 2-31: ahí el softirq robaría al modelo

La segunda puerta: netkit + host-routing + BIG TCP reducen cuántas veces el paquete cruza el stack y el namespace, lo que amortigua (no elimina) el coste del cruce NUMA. BIG TCP arma super-paquetes de hasta 192k (frente a 64k) para 100Gb/s+; menos travesías del stack es menos trabajo de softirq en el core, y por tanto menos presión sobre el presupuesto inter-socket. Es la analogía del continuous batching aplicada al stack de red: amortizar un coste fijo sobre lotes mayores.

Perfil de rendimiento de Cilium (estado 1.19, kernel ≥6.8)

# Helm, perfil de rendimiento recomendado (resumen de la tuning guide)
helm install cilium cilium/cilium --version 1.19.4 \
 --namespace kube-system \
 --set routingMode=native \
 --set bpf.datapathMode=netkit \  # overhead de namespace ~0 (kernel >=6.8)
 --set bpf.masquerade=true \
 --set kubeProxyReplacement=true \  # sustituye kube-proxy de RKE2
 --set enableIPv4BIGTCP=true \  # super-paquetes 192k (NIC mlx5/ice)
 --set enableIPv6BIGTCP=true \
 --set bpf.distributedLRU.enabled=true \# mapas BPF per-CPU: menos contención de spinlock
 --set bpf.mapDynamicSizeRatio=0.08 \
 --set bpfClockProbe=true

# Verificación dentro de un pod de Cilium:
cilium status --verbose | grep -E "Device Mode|Host Routing|BIG TCP|XDP"
# Device Mode: netkit · Host Routing: BPF · IPv4 BIG TCP: enabled · XDP Acceleration: Native

Salvedad escéptica: netkit y BIG TCP son beta y exigen kernel ≥6.8 y NICs concretas (mlx4/mlx5/ice). No son in-place: cambian fundamentos del datapath y obligan a reiniciar pods o, mejor, a aplicarlos por per-node config solo en nodos nuevos. Para un cluster ENS en producción, eso es una ventana de mantenimiento, no un helm upgrade a ciegas.

El estado del arte 2026: DRA y DRANET, el maître que por fin mira la puerta

Lo que cierra el hueco de raíz no es Cilium —es el mecanismo de admisión que el kubelet no tenía para la NIC: Dynamic Resource Allocation (DRA), beta desde Kubernetes 1.32 y con avances en cada release hasta la 1.36 (mayo 2026). DRA generaliza el modelo de “devices” más allá de la GPU: un driver descubre el hardware, publica ResourceSlices con sus atributos —incluida la topología NUMA y el PCIe root— y el scheduler resuelve ResourceClaims que pueden exigir afinidad entre dispositivos.

DRANET (proyecto kubernetes-sigs) es el driver DRA de red. Descubre las NICs (incluidas las RDMA-capaces), las anuncia como ResourceSlices, y vía NRI las inyecta en el namespace del pod —compatible con el CNI que ya tengas, Cilium incluido. La pieza clave para esta historia: combinado con el NVIDIA GPU DRA driver, permite co-programar GPU y NIC que comparten PCIe root (la relación que NVIDIA llama NODE), que es justo la condición de GPUDirect RDMA. El maître por fin tiene su cuarto ayudante: "¿hay una NIC NUMA-local a esta GPU?".

El ResourceClaimTemplate usa selectores CEL para pedir exactamente esa alineación:

# Pedir una NIC RDMA NUMA-local a la GPU asignada (esquema ilustrativo DRANET/DRA)
apiVersion: resource.k8s.io/v1beta1
kind: ResourceClaimTemplate
metadata:
 name: gpu-nic-numa-aligned
spec:
 spec:
 devices:
 requests:
 - name: rdma-nic
 deviceClassName: dra.net  # NICs publicadas por DRANET
 constraints:
 - requests: ["rdma-nic"]
 matchAttribute: "dra.net/pcieRoot" # misma raíz PCIe que la GPU
 # → habilita GPUDirect RDMA sobre camino NUMA-local

Por qué importa para inferencia, no para “AI training” abstracto: en disaggregated serving, RDMA es lo que mueve el KV-cache entre el pool de prefill y el de decode con la latencia que el TTFT exige; y en multinodo, GPUDirect RDMA sustituye al NVLink como medio del colectivo. Alinear GPU+NIC en el mismo PCIe root es lo que convierte un “RDMA que funciona” en un “RDMA que rinde” —los +60% de bus bandwidth de DRANET.

Estado y salvedades: DRA es beta (gates a habilitar a mano), DRANET es joven (proyecto SIG, en evolución) y la oferta gestionada existe sobre todo en cloud (GKE managed DRANET en preview, AKS para RDMA). Para on-premise ENS es camino, no producto cerrado: el valor hoy es entender que la cuarta pata ya tiene mecanismo estándar OSS, y empezar a pilotarlo en un nodo de laboratorio, no meterlo en producción crítica este trimestre.

Cómo se conecta con el resto del stack

Con el host (post 2). La afinidad de IRQ de la NIC es una tercera lista que casar con isolcpus y reserved-cpus. Las IRQ van a housekeeping; los cores aislados, intactos. Descoordinarlas mete por la puerta de la red el jitter que isolcpus echó por la de cómputo.

Con la orquestación (post 3). DRA es la extensión natural del Topology Manager: el mismo principio de “admite solo si encaja en el NUMA node” llevado a la NIC. Donde el Device Manager dejaba la red fuera del censo, DRANET la mete.

Con el interconnect (post 1). Dentro del nodo manda NVLink; al cruzar el límite del nodo, GPUDirect RDMA sobre la NIC es el medio del colectivo. La política NUMA del kubelet garantiza que GPU y CPUs comparten socket; DRANET añade que la NIC también —y solo entonces el RDMA va por el camino corto.

Con disaggregated serving. El KV-cache prefill→decode es el tráfico que más castiga una NIC mal ubicada. La cuarta pata es lo que hace que separar prefill y decode no se pague en latencia de transferencia.

Con capacity planning. El dimensionado gana una dimensión: no basta con “GPUs por nodo y cores por NUMA node”; hay que contar cuántas NICs NUMA-locales a GPU tiene el chasis. Un nodo con 4 GPUs y una sola NIC en el socket 0 tiene dos GPUs “lejos de la puerta”.

Con la observabilidad. Lo que confirma que la cuarta pata está bien puesta no es un dashboard de aplicación: es /proc/softirqs (¿NET_RX concentrado en housekeeping?), nvidia-smi topo -m (¿relación NODE/PHB GPU↔NIC?) y los contadores de la NIC. Encaja con la observabilidad GPU con DCGM: la GPU “al 60% sin razón” puede ser el host esperando paquetes que cruzan el socket.

Trampas y cosas que no son lo que parecen

Creer que cambiar a Cilium “ya optimiza la red”. Cilium eBPF sustituye a kube-proxy y Canal y rinde mejor de serie, pero el despliegue por defecto prioriza compatibilidad, no rendimiento. Sin irqbalance desactivado, sin IRQ fijadas a housekeeping y sin netkit/host-routing, dejas la mayor parte de la mejora en la mesa. La doc de Cilium lo dice; mucha gente no lee la tuning guide.

Fijar las IRQ de la NIC a cores aislados. El error simétrico del knob 6 del post 3: si pones la afinidad de IRQ sobre isolcpus, el softirq NET_RX le roba ciclos a vLLM justo en los cores que aislaste para que nadie lo molestara. Las IRQ van a reserved-cpus, siempre.

Asumir que el Topology Manager ya alinea la NIC. No lo hace: la NIC clásica no es un Hint Provider. Si necesitas localidad NIC↔GPU, hoy el mecanismo es DRA/DRANET, no una política del kubelet. Esperar a que single-numa-node lo resuelva es esperar a algo que no está en su diseño.

Meter DRA/DRANET en producción ENS este trimestre. Es beta y joven. El movimiento sensato es pilotarlo en un nodo de laboratorio, medir all_reduce/all_gather con y sin alineación, y decidir con datos. La cifra del +60% es de un entorno concreto; reprodúcela en el tuyo antes de prometerla.

BIG TCP / netkit sin leer los requisitos. Kernel ≥6.8, NICs mlx4/mlx5/ice, sin túnel ni cifrado para BIG TCP, y nada de in-place: obliga a reiniciar pods o a per-node config. En un cluster con IPsec o con NICs no soportadas, parte de esto no aplica. Verifica cilium status --verbose antes de dar por hecho que está activo.

Confundir el datapath eBPF (kernel) con el agente Cilium (pod). cilium-agent es un DaemonSet Burstable que debe vivir en housekeeping (lo cubre system-reserved). Pero el procesamiento del datapath corre en softirq, gobernado por la afinidad de IRQ del host, no por reserved-cpus. Son dos cosas distintas; pinear bien el pod no pinea el softirq.

Conclusión

La serie “por debajo del motor” perseguía una idea: el rendimiento que parece un problema del motor (vLLM lento) o del modelo (cuantización) es, demasiadas veces, un problema de localidad en una capa más baja. La trilogía cubrió tres: el cable (NVLink no usado), el host (NUMA remoto, jitter) y la orquestación (pinning que no ocurrió). Faltaba la cuarta: la red. El Topology Manager sienta al pod en una mesa NUMA perfecta y nunca pregunta por qué puerta entran los platos ni quién los lleva. En un nodo a 25 Gb/s daba igual; en uno a 400 Gb/s con KV-cache cruzando por RDMA, esa puerta decide el TTFT y el ancho de banda del colectivo. Cilium eBPF sustituye kube-proxy y Canal por un datapath que rinde —si coordinas la afinidad de IRQ con isolcpus/reserved-cpus, una cuarta lista que alinear—, y DRA/DRANET aporta por fin el censo que faltaba: co-programar GPU y NIC NUMA-locales en el mismo PCIe root, con la magnitud de mejora (+60% de bus bandwidth NCCL) que mide lo grande que era el hueco. Bajar de nivel no es esnobismo: es que la causa raíz vivía, una vez más, una capa por debajo de donde mira el dashboard.

Ver también

Los pasillos y el guardia: PCIe, GPUDirect P2P y ACS — el GPUDirect RDMA que DRANET coloca NUMA-local lo rompe el ACS si fuerza el tráfico por el root complex; el bus por debajo de la localidad NIC↔GPU.
El maître que solo te sienta si cabéis en una mesa: resource managers en RKE2 — el post 3, padre directo de éste: el Topology Manager pinnea CPU+memoria+GPU pero no la NIC; aquí se abre esa cuarta pata.
NUMA, hugepages y aislamiento de CPU — el post 2; la afinidad de IRQ de la NIC es una tercera lista que casar con isolcpus y reserved-cpus, y el softirq NET_RX es el mismo jitter entrando por la red.
NVLink, NVSwitch y NCCL — el post 1; al cruzar el nodo, GPUDirect RDMA sobre la NIC sustituye a NVLink, y DRANET es lo que garantiza que ese RDMA va por el camino NUMA-local.
Disaggregated serving: prefill y decode separados — el caso que más castiga una NIC mal ubicada: el KV-cache prefill→decode viaja por RDMA y paga cada cruce de socket.
El stack de inferencia LLM on-premise en siete capas — el edificio completo; la red es el plano que sostiene la inferencia multinodo.
Autoescalado de LLMs en Kubernetes con KEDA — cada réplica nueva no solo pasa por la admisión NUMA del kubelet; con DRA, también por la del ResourceClaim de NIC.
Capacity planning de inferencia on-premise — el sizing gana una dimensión: cuántas NICs NUMA-locales a GPU tiene el chasis, no solo cuántas GPUs.
Entornos mixtos NVIDIA + Intel — la afinidad NUMA NIC↔acelerador se complica cuando el nodo mezcla GPUs, aceleradores y NICs heterogéneas.
Observabilidad GPU con DCGM — cómo confirmar, métrica en mano, que la “GPU al 60%” no es el host esperando paquetes cruzando el socket.
Del disco a la HBM: cold start y carga del modelo — el mismo principio de “saca a la CPU del medio” que aquí da GPUDirect RDMA, aplicado al disco con GPUDirect Storage para cargar pesos directos NVMe→HBM.
SM, CUDA streams y CUDA graphs — bajado un piso más: una vez los datos están en HBM, qué pasa en el silicio que los ejecuta y por qué el decode se vuelve launch-bound.
El contratista con la llave maestra: aislar agentes de IA del workstation al cluster — el otro uso de esta misma capa de kernel: sobre el datapath eBPF de Cilium, Tetragon engancha sus kprobes para observar y matar lo que hace un agente de IA en el cluster. Su runbook trae las TracingPolicy concretas.

Referencias

Cilium, Tuning Guide (netkit, host-routing, BIG TCP, XDP, fijar IRQ y matar irqbalance): https://docs.cilium.io/en/stable/operations/performance/tuning/.
Cilium 1.19 (febrero 2026), Cilium at Ten Years — endurecimiento de cifrado, políticas y observabilidad: https://www.infoq.com/news/2026/02/cilium-119/.
Isovalent, Cilium 1.18 (IPv6, encrypted overlay, ingress bandwidth, policy perf): https://isovalent.com/blog/post/cilium-1-18/.
RKE2, Network Options (Canal por defecto; Cilium con kube-proxy replacement): https://docs.rke2.io/networking/basic_network_options.
Kubernetes, Dynamic Resource Allocation: https://kubernetes.io/docs/concepts/scheduling-eviction/dynamic-resource-allocation/.
Kubernetes blog, v1.36: More Drivers, New Features, and the Next Era of DRA (mayo 2026): https://kubernetes.io/blog/2026/05/07/kubernetes-v1-36-dra-136-updates/.
DRANET (kubernetes-sigs), driver DRA de red y paper The Kubernetes Network Driver Model (+59,6% all_gather / +58,1% all_reduce): https://github.com/kubernetes-sigs/dranet.
AKS Engineering, Optimizing RDMA performance for AI workloads on AKS with DRANET (abril 2026): https://blog.aks.azure.com/2026/04/01/dranet-rdma-optimization-for-ai-on-aks.
Linux network tuning — IRQ affinity, RSS/RPS/RFS y softirq NUMA: https://andreaskaris.github.io/blog/networking/rss-irq-affinity-and-rps/.

Elegir la centralita: qué gateway OSS poner por delante, y por qué la licencia decide antes que las features

Sat, 06 Jun 2026 08:30:00 +0200

Este post es el companion de decisión de El router de inferencia LLM. Allí se explicó qué es un router de inferencia y por qué existe (catálogo, traffic splitting, política transversal, prefix-aware routing). Aquí se responde la pregunta que de verdad bloquea un despliegue: cuál elegir, con licencias verificadas y un orden de criterios que no es el que la mayoría usa.

TL;DR

El gateway es la pieza por la que pasa el 100 % del tráfico y la más cara de sustituir después: el SDK del cliente, las políticas de auth/rate-limit, el tracing y el catálogo de modelos se acoplan todos a él. Por eso el orden de los criterios importa, y no es el habitual. Primero la licencia: no “¿es open source?” sino “¿las features que necesito están bajo licencia permisiva o detrás de un muro Enterprise?”. Segundo el encaje arquitectónico: ¿es ciudadano de tu Kubernetes (Gateway API) o un proceso aparte que hay que operar al margen? Tercero, madurez y documentación. Cuarto, las features. Con datos verificados a junio 2026: LiteLLM es MIT en el core, pero SSO, audit logs, RBAC fino y varios guardrails son Enterprise; Kong tiene core Apache 2.0 pero sus plugins de IA que importan (semantic cache, prompt guard, AI proxy advanced) están gated; Envoy AI Gateway, Gateway API Inference Extension (GIE), Higress, APISIX y Bifrost son Apache 2.0 de punta a punta. Para un stack RKE2 + vLLM con prioridad K8s-native (que es el caso que asumimos aquí), la recomendación es adoptar el modelo Gateway API Inference Extension —el Endpoint Picker que enruta consciente de prefix cache, KV y LoRA, justo lo que multiplica el hit rate— implementado con Envoy AI Gateway si pesa la trayectoria AI-native, o con Higress si pesa la madurez de hoy; y LiteLLM (MIT) como plano de control multi-proveedor opcional por detrás. Con escepticismo explícito sobre las v0.x, el “OpenAI-compatible ≠ inference-aware” y la telemetría phone-home.

El principio que reordena los criterios: el gateway es matrimonio, no noviazgo

Hay piezas del stack que se cambian un domingo por la tarde: el modelo de embeddings, el reranker, hasta el motor de inferencia detrás de una interfaz OpenAI-compatible. El gateway no. Es la pieza a la que todo lo demás se acopla: el SDK de cada cliente apunta a su URL, las políticas de seguridad viven en él, el tracing nace en él, el catálogo de modelos lo define. Arrancarlo dos años después significa tocar a todos los consumidores a la vez. Es la decisión de infraestructura con mayor coste de reversión de toda la capa de serving.

Cuando una decisión es cara de revertir, el criterio dominante no es “¿qué hace hoy?” sino “¿puedo poseerlo y operarlo durante años sin sorpresas?”. Y eso pone la licencia por delante de las features. Una herramienta brillante cuyo SSO, audit log o RBAC viven detrás de un contrato Enterprise es una herramienta que, el día que tu despliegue ENS necesita esos controles, te obliga a pagar o a migrar —exactamente el escenario que la elección debía evitar. Por eso el orden de filtros de este post es licencia → encaje → madurez/docs → features, y no al revés.

El campo de candidatos (junio 2026)

Las piezas OSS reales que alguien pondría por delante de una flota vLLM on-premise:

Candidato	Qué es	Lenguaje
LiteLLM Proxy	Gateway OpenAI-compatible, 100+ proveedores, virtual keys, spend	Python (FastAPI)
Envoy AI Gateway	Capa AI sobre Envoy Gateway; integra GIE/EPP, InferencePool	Go (Envoy)
Gateway API Inference Extension (GIE)	Extensión K8s-SIG: Endpoint Picker inference-aware	Go
Higress	API gateway + AI plugins, Envoy/Istio, CNCF	Go/C++
Apache APISIX	API gateway maduro con plugins de IA	Lua/Nginx
Kong (+ AI plugins)	API gateway; core Apache 2.0, plugins IA Enterprise	Lua/Nginx
Bifrost	Gateway AI-first de alto rendimiento	Go
vLLM Production Stack / Semantic Router	Router específico de vLLM, KV/prefix/intent-aware	Go/Python

Filtro 1 — Licencia: dónde está la letra pequeña

Aquí es donde mueren la mitad de las opciones, y donde “open source” engaña si no se mira el detalle. Lo verificado:

Candidato	Licencia core	Lo que está gated (de pago)
LiteLLM	MIT	SSO (Okta/Azure AD), audit logs, JWT auth, RBAC fino, varios guardrails (llmguard, llamaguard, prompt-injection) → Enterprise (~$250/mo+)
Envoy AI Gateway	Apache 2.0	— (capa AI completa OSS)
GIE (Inference Extension)	Apache 2.0	— (proyecto K8s-SIG)
Higress	Apache 2.0	— (AI plugins incluidos)
APISIX	Apache 2.0	— (más IA built-in que Kong OSS)
Kong	Apache 2.0 (core)	AI Semantic Cache, AI Prompt Guard, AI Proxy Advanced, AI RAG Injector → Enterprise
Bifrost	Apache 2.0	—

Dos conclusiones que decantan el campo:

Kong cae para un despliegue AI OSS. Su core es Apache 2.0, pero precisamente los plugins de IA que justificarían elegirlo (semantic cache, prompt guard, proxy advanced) son Enterprise, con contratos que la propia comparativa del sector sitúa por encima de cinco cifras anuales. Para IA sobre presupuesto OSS, APISIX ofrece más built-in sin coste. Kong sigue siendo excelente como API gateway clásico; como AI gateway OSS, no.
LiteLLM es MIT de verdad en el core, y eso es real: lo puedes forkear, modificar y usar comercialmente. Pero SSO, audit logs, RBAC fino y varios guardrails son Enterprise. Bajo el criterio que fijamos —“core permisivo basta, la gobernanza la resuelvo con OIDC/auditoría externa del stack”— LiteLLM sigue en juego; bajo un criterio “todo OSS o nada”, quedaría tocado. Conviene saber exactamente qué cae de qué lado de la línea antes de comprometerse.

LiteLLM: qué está gated y su equivalente OSS

El matiz que decide si el gating de LiteLLM es un problema real o no: “feature built-in de pago” no es lo mismo que “capacidad imposible en OSS”. En casi todos los casos la capacidad se logra cambiando el cómo —cableando OSS por el hook abierto de LiteLLM, o resolviéndolo en la capa de al lado (el gateway, la observabilidad)—. El desglose, verificado con la doc:

Capacidad	En LiteLLM Enterprise	Equivalente OSS
Guardrails	integraciones prebuilt (`llmguard`, `llamaguard`, `lakera`, `aporia`, `hide_secrets`)	framework + custom guardrail hook + Presidio son OSS (core MIT); invocas LLM Guard, Llama Guard o Presidio desde el hook tú mismo
Audit log	UI turnkey con políticas de retención	logging request/response + custom callbacks + exporters OTel/Langfuse (integración oficial OSS) → construyes el rastro y lo posees
RBAC	fino (`enforce_rbac`, roles org/team/user)	grueso (virtual keys por team/budget/modelo) es OSS; el fino se hace al borde en el gateway (`ext_authz` + OPA)
SSO	SSO del Admin UI (Okta/Azure/Google/OIDC)	el SSO de usuarios/API se resuelve fronting con OIDC OSS (Keycloak + oauth2-proxy) o en el propio gateway; JWT auth + JWT→virtual-key mapping ya están en el core

La conclusión que cierra la decisión: en un diseño K8s-native con gateway por delante, el OIDC y la autorización viven en el gateway (Envoy/Higress + OPA) y el audit trail en Langfuse/OTel —ambos Apache 2.0, ya en el stack—, así que LiteLLM puesto por detrás apenas necesita su Enterprise: las piezas de gobernanza están donde corresponde arquitectónicamente y resultan ser OSS. El único coste real es la integración y el mantenimiento DIY, y —para ENS— el diseño de garantías del audit trail (retención, inmutabilidad/WORM) corre de tu cuenta, no sale de fábrica.

El resto —Envoy AI Gateway, GIE, Higress, APISIX, Bifrost— pasan el filtro de licencia limpios: Apache 2.0 de punta a punta, sin features críticas tras un muro.

Filtro 2 — Encaje: ¿ciudadano de Kubernetes o inquilino?

Con prioridad K8s-native (RKE2), la pregunta es si el gateway se modela como recursos del cluster —que se versionan con GitOps, se observan con las mismas herramientas y se integran con el scheduler— o si es un proceso aparte que hay que operar al margen. Aquí aparece la novedad estructural de 2025-2026: la Gateway API Inference Extension (GIE).

GIE es una extensión de la Gateway API estándar de Kubernetes, del SIG-Network, que añade dos piezas: el InferencePool (un pool de réplicas de un modelo como recurso nativo) y el Endpoint Picker (EPP), un planificador que decide a qué réplica va cada request en función del estado de inferencia: longitud de cola, adapters LoRA disponibles, y —la pieza clave— estado del prefix cache de cada réplica. Es exactamente el prefix-aware routing que en el post del router explicaba por qué el hit rate pasa del 5-15 % al 60-85 %, ahora como estándar de la comunidad en vez de feature propietaria de cada producto.

Por qué esto decanta la decisión cuando la prioridad es K8s-native: GIE convierte el routing inference-aware en una interfaz estándar que varias implementaciones cumplen (Envoy AI Gateway, Higress, kgateway, Istio, GKE Inference Gateway). Eliges una implementación hoy y, si mañana cambias, el modelo de recursos (InferencePool, HTTPRoute) se conserva. Es justo la propiedad que querías de una decisión cara de revertir: el acoplamiento es a un estándar, no a un producto. Un proxy standalone como LiteLLM, por bueno que sea, vive fuera de este modelo —es un Deployment más, con su propia config, su propio formato de catálogo y su propio plano de gestión.

Filtro 3 — Madurez y documentación: la honestidad incómoda

Aquí aparece la tensión que ninguna comparativa de marketing reconoce: lo K8s-native-correcto y lo battle-tested-hoy no coinciden del todo en junio de 2026.

Envoy AI Gateway: la capa AI va por v0.5 —pre-1.0, joven. Pero corre sobre Envoy y Envoy Gateway, que son de lo más maduro que existe en proxies. Tiene la integración GIE/EPP más completa, model virtualization, tracing OpenInference. Riesgo: la capa AI aún se mueve rápido (breaking changes posibles). Docs en crecimiento, buenas.
GIE: el proyecto está llegando a GA (de las primeras extensiones inference-aware estandarizadas). Madurez del estándar alta y subiendo; madurez de cada implementación, variable.
Higress: el más maduro hoy entre los K8s-native Apache-2.0 con IA. Producción a escala Alibaba, CNCF, base Envoy/Istio, AI plugins incluidos, soporte de Gateway API. Si “maduro” pesa más que “AI-native de vanguardia”, es la apuesta segura.
APISIX: gateway clásico muy maduro, con plugins de IA crecientes; menos especializado en inference-aware (prefix/KV) que el modelo GIE. Battle-tested a escala masiva.
LiteLLM: el de mejor documentación y mayor adopción del campo, con diferencia. Mature como proxy. Su techo es el lenguaje (Python/FastAPI: ~250-300 RPS por instancia, escala por réplicas) y el gating de gobernanza ya visto.
Bifrost: Apache 2.0, Go, el de mayor rendimiento (overhead de ~11 µs a 5.000 RPS), con semantic caching y governance built-in. Más joven y menos probado a años, pero técnicamente fuerte.

Matriz de decisión

Ponderando los cuatro filtros para el caso RKE2 + vLLM, prioridad K8s-native, core permisivo aceptable:

Candidato	Licencia	K8s-native	Madurez	Docs	Inference-aware	Veredicto
Envoy AI GW + GIE/EPP	✅ Apache 2.0	✅✅ estándar	⚠️ v0.5 (Envoy maduro)	✅ buenas	✅✅ prefix/KV/LoRA	Primaria (trayectoria)
Higress (+ GIE)	✅ Apache 2.0	✅✅	✅✅ producción	✅ buenas	✅ vía GIE/plugins	Primaria (madurez hoy)
APISIX	✅ Apache 2.0	✅	✅✅	✅✅	⚠️ menos especializado	Sólida alternativa
LiteLLM	⚠️ MIT core, gov. gated	❌ proxy aparte	✅✅	✅✅✅	⚠️ básico	Plano de control por detrás
Bifrost	✅ Apache 2.0	⚠️	⚠️ joven	✅	✅	A vigilar (perf)
Kong	⚠️ AI plugins Enterprise	✅	✅✅	✅✅	❌ gated	Descartado (AI OSS)

La recomendación

Para el caso que fijamos —RKE2 + vLLM, prioridad K8s-native, licencia permisiva con core suficiente— la recomendación tiene dos capas, no una:

Capa de datos (lo que va por delante de las réplicas): adopta el modelo Gateway API Inference Extension. Es la decisión que envejece bien porque te acopla a un estándar Apache 2.0, no a un producto, y porque trae el routing prefix/KV/LoRA-aware que de verdad mueve el hit rate. Para la implementación:

Si pesa la trayectoria AI-native y aceptas operar una capa v0.x sobre un Envoy maduro: Envoy AI Gateway + GIE/EPP. Es donde está la vanguardia y la integración más completa.
Si pesa la madurez de hoy por encima de todo (ENS, producción crítica, cero apetito por v0.x en la ruta del 100 % del tráfico): Higress con GIE. CNCF, probado a escala, Apache 2.0, y migrable al EPP estándar.

Capa de control (opcional, por detrás): LiteLLM (MIT) si necesitas un punto único multi-proveedor con virtual keys, spend tracking y fallbacks hacia modelos externos. Se coloca detrás del gateway de datos, no en su lugar, y aceptas que SSO/audit/RBAC los resuelves con el OIDC y la auditoría del propio cluster (tal como fijamos en el criterio). Si tu front es solo vLLM on-premise sin proveedores externos, esta capa probablemente sobra.

Lo que no recomendaría aquí: Kong (sus features de IA están gated, contradice el criterio de licencia); y empezar por LiteLLM como gateway de datos principal en un stack que será multi-réplica y K8s-native —su techo de Python y su posición fuera del modelo Gateway API lo convierten en deuda el día que escalas.

Aplicado a nuestra infraestructura: RKE2 + vLLM + 4×H100

El despliegue concreto sobre el cluster genérico de referencia:

# El InferencePool agrupa las réplicas de un modelo (recurso GIE)
apiVersion: inference.networking.x-k8s.io/v1alpha2
kind: InferencePool
metadata: { name: llama-70b-pool }
spec:
 selector: { app: vllm-llama70b }
 extensionRef: { name: llama-70b-epp }  # el Endpoint Picker
---
# La ruta estándar Gateway API apunta al pool
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata: { name: llama-70b }
spec:
 parentRefs: [ { name: ai-gateway } ]
 rules:
 - backendRefs:
 - group: inference.networking.x-k8s.io
 kind: InferencePool
 name: llama-70b-pool

Tres notas de encaje con la serie del blog:

Vive en la capa 1 del stack de siete capas, por delante de las réplicas pinneadas por los resource managers de RKE2. El gateway enruta; el kubelet pinnea; ambos son recursos del mismo cluster GitOps.
El EPP lee el estado de prefix cache de cada réplica, lo que conecta directamente con la ingeniería de prefix cache hit rate: el gateway es quien materializa esa afinidad en routing real.
El tracing gen_ai.* del gateway alimenta el pipeline de observabilidad OTel y aterriza en Langfuse, cerrando el círculo de la capa Observe.

Trampas y cosas que no son lo que parecen

“Es open source” sin leer qué cae bajo Enterprise. El error que este post intenta evitar: Kong y LiteLLM son OSS, pero las features que justifican elegirlos para IA (plugins de IA en Kong; SSO/audit/RBAC/guardrails en LiteLLM) están parcial o totalmente gated. “Open source” es la pregunta equivocada; “¿lo que necesito es permisivo?” es la correcta.

“OpenAI-compatible” ≠ “inference-aware”. Casi todos exponen el API de OpenAI. Eso no significa que entiendan el estado del KV cache, la cola de cada réplica o los adapters LoRA. La compatibilidad de API es de entrada; el routing inteligente (EPP) es otra liga. No confundas “habla OpenAI” con “enruta bien”.

Elegir por el benchmark de RPS. Bifrost gana en overhead bruto, pero el cuello de botella de una flota vLLM on-premise rara vez es el proxy: son las GPUs. Optimizar el gateway para 5.000 RPS cuando tus réplicas sirven 300 req/s es resolver el problema que no tienes. La latencia añadida del gateway importa; su throughput pico, casi nunca, en este contexto.

Telemetría phone-home en un despliegue soberano. Varios gateways envían telemetría a casa por defecto. En un contexto ENS/soberanía, eso es un hallazgo de auditoría, no un detalle. Verifica y desactiva el phone-home antes de poner el gateway en la ruta del 100 % del tráfico; documéntalo para el expediente de controles ENS/42001/EU AI Act.

Apostar a una v0.x en la ruta crítica sin plan de rollback. Envoy AI Gateway v0.5 es prometedor, pero está en la ruta del 100 % del tráfico. Si lo eliges, ten el rollback ensayado y sigue el changelog: las v0.x rompen. El estándar GIE mitiga esto (puedes cambiar de implementación), pero la implementación concreta hay que operarla con red.

Confundir el gateway de datos con el plano de control. LiteLLM por delante de todo parece simplificar, pero mezcla dos roles: enrutar tráfico de datos (donde quieres K8s-native + inference-aware) y gestionar claves/spend multi-proveedor (donde LiteLLM brilla). Sepáralos: gateway de datos GIE-native, LiteLLM como control plane detrás si hace falta.

Conclusión

El gateway es la pieza con mayor coste de reversión de la capa de serving, y eso obliga a invertir el orden intuitivo de criterios: primero la licencia —no “¿es OSS?” sino “¿lo que necesito es permisivo o está gated?"—, que ya descarta Kong para IA OSS y pone una estrella a LiteLLM por su gobernanza Enterprise; luego el encaje, donde la Gateway API Inference Extension convierte el routing inference-aware en un estándar Apache 2.0 al que acoplarse sin casarte con un producto; y solo después madurez, docs y features, donde la honestidad obliga a admitir que lo AI-native de vanguardia (Envoy AI Gateway v0.5) y lo battle-tested-hoy (Higress) aún no son lo mismo. Para un stack RKE2 + vLLM con prioridad K8s-native, la respuesta no es un producto sino un modelo —GIE/EPP— implementado con Envoy AI Gateway si miras la trayectoria o con Higress si miras la madurez, y LiteLLM como plano de control opcional por detrás. La decisión que envejece bien es la que te acopla a un estándar, no a un vendor; en gateways, en junio de 2026, ese estándar tiene por fin nombre.

Ver también

El router de inferencia LLM: la centralita L7 — el post que explica qué es y por qué existe un router de inferencia; este elige cuál con licencias verificadas. Léelos en orden.
Resource managers de RKE2 — el gateway enruta hacia las réplicas que estos managers pinnean al NUMA node correcto; ambos son recursos del mismo cluster GitOps.
Ingeniería del prefix cache hit rate — la afinidad que el Endpoint Picker materializa en routing real; el gateway es quien convierte el cache caliente en hit rate.
El stack de inferencia LLM on-premise en siete capas — el gateway es la capa 1; este post elige la pieza concreta que la ocupa.
El catálogo OSS para LLMOps en seis etapas y OSS vs hyperscalers — el gateway dentro del mapa OSS completo y su traducción a las nubes públicas.
Tracing LLM con OpenTelemetry GenAI — el tracing gen_ai.* que nace en el gateway y alimenta la capa Observe.
Controles técnicos ENS × 42001 × EU AI Act — por qué la licencia, la soberanía del despliegue y el phone-home del gateway son materia de auditoría, no detalles.
Multi-LoRA serving — el EPP enruta consciente de qué adapter LoRA tiene cargado cada réplica; el gateway y el serving multi-adapter se coordinan aquí.

Referencias

Kubernetes, Introducing Gateway API Inference Extension (blog oficial, jun 2025): https://kubernetes.io/blog/2025/06/05/introducing-gateway-api-inference-extension/.
Gateway API Inference Extension, doc del proyecto (Endpoint Picker, InferencePool): https://gateway-api-inference-extension.sigs.k8s.io/.
Envoy AI Gateway, sitio y release notes (v0.x, GIE integration): https://aigateway.envoyproxy.io/.
LiteLLM, Enterprise Features (qué está gated): https://docs.litellm.ai/docs/proxy/enterprise · licencia MIT: https://github.com/BerriAI/litellm/blob/main/LICENSE.
Kong, Announcing Kong’s Open Source AI Gateway y matriz de plugins Enterprise: https://konghq.com/blog/product-releases/announcing-kong-ai-gateway.
Higress (Apache 2.0, CNCF, AI gateway): https://higress.cn/en/.
Apache APISIX, APISIX vs Kong (cobertura de IA OSS): https://apisix.apache.org/learning-center/apisix-vs-kong/.
vLLM, Semantic Router v0.1 Iris y Production Stack (routing específico de vLLM): https://blog.vllm.ai/2026/01/05/vllm-sr-iris.html.

El maître que solo te sienta si cabéis en una mesa: CPU, Memory y Topology Manager en RKE2

Sat, 06 Jun 2026 08:00:00 +0200

Cierre de la serie “por debajo del motor”. Vimos el cable entre GPUs y el host: NUMA, hugepages y aislamiento de CPU hecho a mano. Aquí está la pieza que lo hace declarativo y a escala: cómo el kubelet de RKE2 pinnea cada pod de vLLM al NUMA node correcto sin un solo script.

TL;DR

Pinnear NUMA con numactl/isolcpus/taskset —lo del post anterior— no escala a un cluster donde los pods nacen y mueren y hay decenas de nodos. El kubelet lo automatiza con tres componentes que funcionan como Hint Providers de un coordinador central, el Topology Manager: el CPU Manager (asigna CPUs exclusivas a contenedores de pods Guaranteed con CPU entera), el Memory Manager (memoria y hugepages NUMA-local) y el Device Manager/plugin de GPU (sabe qué GPU está en qué NUMA node). Con la política single-numa-node, el Topology Manager solo admite el pod si sus CPUs, su memoria y su GPU caben en el mismo dominio NUMA; si no caben, rechaza el pod —admisión estricta, como el maître que no sienta a un grupo de ocho si no hay mesa de ocho. En RKE2 todo esto se configura con kubelet-arg en /etc/rancher/rke2/config.yaml. Este post explica el mecanismo, da los 10 knobs y desmonta los gotchas que rompen el pinning en silencio: el fichero cpu_manager_state que hay que borrar al cambiar de política, la QoS que tiene que ser exactamente Guaranteed, y el reserved-cpus que debe casar con el isolcpus del host. Sobre un cluster genérico RKE2 con nodos 4×H100 SXM.

Dónde estás: la orquestación que materializa el host

La analogía: el maître de un restaurante con mesas que no se juntan

Un restaurante tiene mesas de distintos tamaños, y —regla de la casa— las mesas no se juntan. Llega un grupo de ocho. El maître mira si hay una sola mesa donde quepan los ocho. Si la hay, los sienta; si solo quedan mesas de cuatro, no los acepta —prefiere rechazar la reserva a sentar al grupo partido en dos mesas separadas, porque sabe que la cena partida va mal.

Ese maître es el Topology Manager en política single-numa-node. El “grupo” es un pod de inferencia que pide CPUs, memoria y una GPU. La “mesa” es un NUMA node. El maître pregunta a tres ayudantes —¿hay CPUs libres en algún node? (CPU Manager), ¿hay memoria libre? (Memory Manager), ¿hay GPU libre? (Device Manager)— y solo admite el pod si los tres recursos caben en el mismo node. Si no, lo rechaza (el pod queda en Failed con TopologyAffinityError), y el scheduler probará otro nodo.

La diferencia con el post anterior: allí tú eras el maître, sentando a mano a cada proceso con numactl. Aquí el maître es el kubelet, y lo hace para cada pod, en cada nodo, automáticamente, y rechazando lo que no cabe. Eso es lo que convierte el pinning artesanal en una propiedad declarativa del cluster.

El mecanismo: Hint Providers y el coordinador

El Topology Manager no asigna recursos; coordina a los que sí lo hacen. El flujo, cuando un pod Guaranteed llega a un nodo:

hint NUMA hint NUMA hint NUMA

¿Los tres hints coinciden en 1 node? SÍ → admite NO → rechaza

Los tres managers son Hint Providers: cada uno le dice al Topology Manager en qué NUMA node(s) podría satisfacer su parte. El Topology Manager calcula la intersección y, según la política, decide:

none (default): no coordina; cada manager hace lo suyo sin alinear. Sin garantía NUMA.
best-effort: intenta alinear en un node; si no puede, admite igual (en el node que sea). Mejor que nada, sin garantía.
restricted: si no logra alinear, rechaza el pod. Estricto, pero permite afinidad multi-node si la intersección lo da.
single-numa-node: exige que todo quepa en un único NUMA node, o rechaza. El más estricto y el que de verdad garantiza la localidad del post anterior.

Y dos precondiciones sin las cuales nada de esto se activa:

El pod tiene que ser QoS Guaranteed: requests == limits en CPU y memoria, y CPU entera (no 500m). Solo así el CPU Manager asigna CPUs exclusivas.
El CPU Manager tiene que estar en política static (no none).

Sin esas dos, el Topology Manager no tiene nada que alinear y el pinning no ocurre —aunque la política esté puesta. Es el gotcha nº1.

Cómo se configura en RKE2

RKE2 pasa argumentos al kubelet con la clave kubelet-arg en /etc/rancher/rke2/config.yaml. La configuración de referencia para nodos GPU de inferencia:

# /etc/rancher/rke2/config.yaml (en cada nodo agent con GPUs)
kubelet-arg:
 - "cpu-manager-policy=static"
 - "topology-manager-policy=single-numa-node"
 - "topology-manager-scope=pod"
 - "memory-manager-policy=Static"
 - "reserved-cpus=0-1,64-65" # housekeeping; debe casar con el host
 - "system-reserved=memory=8Gi"
 - "kube-reserved=memory=4Gi"
 - "reserved-memory=0:memory=4Gi;1:memory=4Gi" # requerido por Memory Manager Static
node-label:
 - "fibercli.local/numa-pinned=true"

Tras desplegarlo: systemctl restart rke2-agent. Gotcha crítico: si el nodo ya corrió con cpu-manager-policy=none, hay un fichero de estado /var/lib/kubelet/cpu_manager_state que fija la política antigua; cambiar el arg sin borrar ese fichero hace que el kubelet falle al arrancar o ignore la nueva política. Hay que: parar el agent, rm /var/lib/kubelet/cpu_manager_state, arrancar. (Lo mismo aplica a memory_manager_state).

Y el pod de vLLM, para ser elegible, Guaranteed con CPU entera:

resources:
 requests:
 cpu: "16" # entero, no "16000m" fraccionado raro
 memory: "200Gi"
 nvidia.com/gpu: "2" # TP=2 → 2 GPUs del mismo NUMA node
 hugepages-1Gi: "16Gi"
 limits:
 cpu: "16" # == requests → QoS Guaranteed
 memory: "200Gi"
 nvidia.com/gpu: "2"
 hugepages-1Gi: "16Gi"

Con esto, en un nodo con la config de arriba, el kubelet asigna 16 CPUs exclusivas del NUMA node donde están las 2 GPUs pedidas, su memoria local y las hugepages —o rechaza el pod si no caben juntas. El pinning artesanal del post anterior, ahora declarativo.

Los 10 knobs donde tocar

Ordenados por dependencia (los primeros son precondición de los siguientes). La referencia canónica es la doc del Topology Manager de Kubernetes y la config de RKE2.

Knob 1 — `cpu-manager-policy=static`: el cimiento

Sin esto, no hay CPUs exclusivas y nada de lo demás se activa.

kubelet-arg: [ "cpu-manager-policy=static" ]

Gotcha: cambiarlo requiere borrar /var/lib/kubelet/cpu_manager_state y reiniciar el kubelet, o el arranque falla. Es la causa nº1 de “puse la política y no pinnea”.

Knob 2 — QoS `Guaranteed` + CPU entera: la precondición del pod

No es config de nodo, es del pod, pero sin ella el knob 1 no hace nada para ese pod. requests == limits en CPU y memoria, y CPU entera. Un cpu: 500m o un requests != limits degrada el pod a Burstable y pierde el pinning. Mucha gente pone la política de nodo y olvida la QoS del pod.

Knob 3 — `topology-manager-policy=single-numa-node`: admisión estricta

kubelet-arg: [ "topology-manager-policy=single-numa-node" ]

El maître estricto. Para inferencia con GPU, es la política correcta: garantiza que CPU+memoria+GPU comparten node. best-effort no garantiza (admite desalineado); restricted permite afinidad multi-node. Empieza por single-numa-node y baja a restricted solo si tienes problemas de admisión.

Knob 4 — `topology-manager-scope=pod`: agrupar el pod entero

kubelet-arg: [ "topology-manager-scope=pod" ]

Con scope container (default), cada contenedor se alinea por separado; con scope pod, todo el pod va al mismo node. Para un pod de vLLM con sidecars (métricas, proxy), scope pod evita que el sidecar arrastre el contenedor principal a otro node. Recomendado para inferencia.

Knob 5 — `memory-manager-policy=Static` + `reserved-memory`: memoria NUMA-local

kubelet-arg:
 - "memory-manager-policy=Static"
 - "reserved-memory=0:memory=4Gi;1:memory=4Gi"

El Memory Manager Static fuerza cpuset.mems para que la memoria del pod salga del node correcto (y las hugepages). Requiere declarar reserved-memory por node, o el kubelet no arranca. Es el equivalente declarativo del --membind del post anterior.

Knob 6 — `reserved-cpus`: los cores housekeeping (debe casar con `isolcpus`)

kubelet-arg: [ "reserved-cpus=0-1,64-65" ]

Reserva cores para el sistema y los daemons; el resto quedan para pods exclusivos. Clave de la serie: estos reserved-cpus deben ser los mismos cores que dejaste fuera de isolcpus en el host (post anterior). Si el host aísla 2-31 pero RKE2 reserva 0-3, hay un desajuste: cores aislados que el kubelet asigna a pods sin que estén realmente quietos. Coordina las dos capas.

Knob 7 — Plugin de GPU con topología NUMA (NVIDIA GPU Operator)

El Device Manager solo puede dar un hint NUMA correcto si el plugin de GPU expone en qué node está cada GPU. El NVIDIA device plugin / GPU Operator lo hace, pero hay que verificar que la información de topología llega (en algunas versiones requiere flags). Sin hint de GPU, el Topology Manager alinea CPU y memoria pero no la GPU —y la localidad GPU es justo la que más importa.

Knob 8 — hugepages como recurso del pod

resources:
 limits:
 hugepages-1Gi: "16Gi" # el nodo debe tenerlas pre-reservadas (post 2, knob 4)

Las hugepages que reservaste en el arranque del host (post anterior) se piden como recurso. El Memory Manager las asigna NUMA-local. Si las pides sin haberlas reservado en el nodo, el pod no se programa.

Knob 9 — `system-reserved` / `kube-reserved`: no sobre-suscribir

kubelet-arg:
 - "system-reserved=cpu=500m,memory=8Gi"
 - "kube-reserved=cpu=500m,memory=4Gi"

Reserva recursos para el sistema y los componentes de K8s para que el nodo no se quede sin aire bajo carga. Mal calibrado, o el nodo se ahoga (poco reservado) o desperdicias capacidad (demasiado). Debe ser coherente con reserved-cpus.

Knob 10 — Labels + taints: que vLLM caiga aquí y lo demás no

# nodo GPU: taint para repeler lo que no necesita GPU
node-taint: [ "nvidia.com/gpu=present:NoSchedule" ]
node-label: [ "fibercli.local/numa-pinned=true" ]

Mantén los nodos NUMA-pinned para inferencia y echa de ahí lo que no la necesita (bases de datos, el backend de Langfuse, runners). Un ClickHouse robando ancho de banda de memoria a un pod de vLLM cuidadosamente pinneado tira por tierra todo el trabajo de los nueve knobs anteriores. El aislamiento de workloads es el cierre.

Tabla resumen

#	Knob	Dónde	Función
1	`cpu-manager-policy=static`	kubelet-arg	CPUs exclusivas (cimiento)
2	QoS `Guaranteed` + CPU entera	pod spec	precondición del pinning
3	`topology-manager-policy=single-numa-node`	kubelet-arg	admisión estricta NUMA
4	`topology-manager-scope=pod`	kubelet-arg	agrupar pod entero
5	`memory-manager-policy=Static`	kubelet-arg	memoria/hugepages NUMA-local
6	`reserved-cpus`	kubelet-arg	housekeeping (casar con isolcpus)
7	plugin GPU con topología	GPU Operator	hint NUMA de la GPU
8	`hugepages-1Gi`	pod spec	hugepages como recurso
9	`system/kube-reserved`	kubelet-arg	no sobre-suscribir
10	taints + labels	config nodo	aislar workloads GPU

Verificar que el pinning de verdad ocurrió

No te fíes de que la config “esté puesta”. Comprueba:

# ¿La política activa es la que pusiste?
cat /var/lib/kubelet/cpu_manager_state | jq .policyName # "static"

# ¿Qué CPUs exclusivas tiene el contenedor?
kubectl exec <pod> -- cat /sys/fs/cgroup/cpuset.cpus.effective

# Dentro del pod: ¿la GPU asignada es local a esos cores?
kubectl exec <pod> -- nvidia-smi topo -m

# ¿Hubo rechazos por topología?
kubectl describe pod <pod> | grep -i TopologyAffinityError

Un pod en Failed con TopologyAffinityError no es un bug: es el maître haciendo su trabajo —ese nodo no tenía una mesa donde cupieran CPU+memoria+GPU juntas. La respuesta es revisar el sizing del pod o del nodo, no relajar la política a la ligera.

Cómo se conecta con el resto del stack

Con el host (post anterior). Este post es la automatización declarativa de aquel. cpu-manager-policy=static materializa el taskset; memory-manager-policy=Static materializa el --membind; reserved-cpus debe casar con el isolcpus. Las dos capas son una sola decisión vista desde dos sitios: el host la ejecuta, el kubelet la declara. Descoordinarlas (isolcpus 2-31 vs reserved-cpus 0-3) rompe ambas.

Con el interconnect (post 1). El Topology Manager pinnea la GPU correcta al pod, pero si pides 2 GPUs para TP=2, querrás que esas dos compartan NVLink. La política NUMA garantiza que están en el mismo socket; que estén NVLink-conectadas lo garantiza el hardware del baseboard (post 1, knob 1). Las dos cosas juntas son lo que hace que TP=2 rinda.

Con el autoscaling. Cuando KEDA escala pods de vLLM, cada réplica nueva pasa por la admisión del Topology Manager. Si el nodo no tiene una “mesa” libre, el pod queda pendiente —el autoscaling de pods y el de nodos (cluster-autoscaler) tienen que contar con la granularidad NUMA, no solo con CPU/memoria agregada.

Con capacity planning. El dimensionado cambia: no es “128 vCPU por nodo”, es “128 menos los reserved-cpus, en bloques que quepan por NUMA node”. Un nodo de 2 sockets × 64 cores no sirve un pod que pida 80 cores en single-numa-node: no caben en una mesa. El planning tiene que razonar por node, no por nodo.

Con la convivencia de servicios. El taint del knob 10 es lo que mantiene a Langfuse, bases de datos y runners fuera de los nodos de inferencia. Sin esa frontera, todo el pinning fino se lo come un vecino ruidoso. La observabilidad va en sus nodos; la inferencia, pinneada, en los suyos.

Trampas y cosas que no son lo que parecen

Política puesta, QoS olvidada. El error más común: cpu-manager-policy=static en el nodo pero el pod es Burstable (requests != limits o CPU fraccionada). El pinning no ocurre y nadie avisa. La QoS Guaranteed con CPU entera es condición necesaria.

cpu_manager_state fosilizado. Cambiar de política sin borrar /var/lib/kubelet/cpu_manager_state (y memory_manager_state) hace que el kubelet falle o ignore el cambio. Parar agent → borrar fichero → arrancar.

reserved-cpus ≠ isolcpus. Si el host aísla unos cores y RKE2 reserva otros, los managers asignan a pods cores que no están realmente quietos, o dejan idle cores aislados. Las dos listas tienen que ser coherentes. Es el fallo de coordinación entre el post anterior y este.

Plugin de GPU sin topología NUMA. Si el device plugin no expone el NUMA node de cada GPU, el Topology Manager alinea CPU y memoria pero deja la GPU al azar —y la localidad de la GPU es la que más pesa. Verifica que el GPU Operator publica la topología.

single-numa-node que rechaza demasiado. Si los pods piden más recursos de los que caben en un node (p. ej. más cores que los de un socket), el rechazo es constante. La respuesta no es bajar a best-effort (que silencia el problema sirviendo desalineado), sino dimensionar el pod para que quepa en una mesa, o aceptar restricted con conocimiento de causa.

Creer que best-effort “es casi igual”. best-effort admite el pod aunque no logre alinear: te da la falsa sensación de NUMA-awareness mientras sirves desde el socket equivocado. Para inferencia con SLO de cola, single-numa-node o restricted; best-effort solo si la alternativa es no programar nada.

Conclusión

El post anterior pinneaba a mano; este lo hace a escala y con una garantía que el numactl artesanal no daba: admisión estricta. El kubelet, vía CPU Manager, Memory Manager y Topology Manager, actúa como un maître que solo sienta al pod si sus CPUs, su memoria y su GPU caben en la misma mesa NUMA, y que rechaza lo que no cabe en vez de servir una cena partida. De los diez knobs, los dos primeros —cpu-manager-policy=static y QoS Guaranteed con CPU entera— son la precondición sin la cual los otros ocho no hacen nada, y son justo los que más se olvidan; el resto afina la política, la memoria, las hugepages y la convivencia. El hilo que cierra la serie: el rendimiento de inferencia que parecía un problema del motor (vLLM lento) o del modelo (cuantización) es, demasiadas veces, un problema del cable (NVLink no usado), del host (NUMA remoto, jitter) o de la orquestación (pinning que no ocurrió porque la QoS estaba mal). Bajar de nivel no es esnobismo de infraestructura: es donde están las causas raíz que ningún dashboard de la capa de aplicación te va a señalar.

Ver también

NUMA, hugepages y aislamiento de CPU — el post anterior; la capa cruda (numactl, isolcpus, membind) que este automatiza de forma declarativa. reserved-cpus aquí debe casar con isolcpus allí.
NVLink, NVSwitch y NCCL — el primero de la serie; la política NUMA pinnea la GPU correcta, pero que las GPUs de un TP compartan NVLink lo decide el hardware del baseboard.
El stack de inferencia LLM on-premise en siete capas — el edificio completo; la orquestación es la capa de control plane que sostiene a la inferencia.
Autoescalado de LLMs en Kubernetes con KEDA — cada réplica que KEDA crea pasa por la admisión del Topology Manager; el autoscaling tiene que contar con la granularidad NUMA.
Capacity planning de inferencia on-premise — por qué el sizing pasa a razonarse por NUMA node, no por nodo: un pod no cabe si pide más que una mesa.
Langfuse por dentro: arquitectura v3 y los 10 knobs de backend — el tipo de workload que los taints del knob 10 mantienen fuera de los nodos de inferencia pinneados.
Observabilidad GPU con DCGM — cómo confirmar, métrica en mano, que el pinning se traduce en GPU saturada y sin burbujas.
La puerta de la cocina que el maître no miró: NUMA de red, Cilium eBPF y DRANET — la coda: el Topology Manager pinnea CPU+memoria+GPU pero no la NIC; esa cuarta pata (localidad de red, afinidad de IRQ, DRA/DRANET) es la que aquí quedaba fuera del censo.
Del disco a la HBM: cold start y carga del modelo — el NVMe también cuelga de un PCIe root bajo un socket; su localidad NUMA es la quinta lista a alinear, y el cold start es el techo real de la elasticidad que este pinning sostiene.

Referencias

Kubernetes, Control Topology Management Policies on a node: https://kubernetes.io/docs/tasks/administer-cluster/topology-manager/.
Kubernetes, Control CPU Management Policies on the Node: https://kubernetes.io/docs/tasks/administer-cluster/cpu-management-policies/.
Kubernetes, Control Memory Management Policies on a Node: https://kubernetes.io/docs/tasks/administer-cluster/memory-manager/.
RKE2, Configuration Options (kubelet-arg en config.yaml): https://docs.rke2.io/install/configuration.
RKE2, Advanced Options and Configuration: https://docs.rke2.io/advanced.
rancher/rke2, discusión #3034 CPU Management Policies for RKE2 (el gotcha de cpu_manager_state): https://github.com/rancher/rke2/discussions/3034.

La planta de al lado: NUMA, hugepages y aislamiento de CPU, o por qué tu GPU espera al kernel

Sat, 06 Jun 2026 07:30:00 +0200

Segundo post de la serie “por debajo del motor”. El primero abrió el cable entre GPUs (NVLink/NCCL). Este baja al host: los núcleos, la memoria y el kernel que rodean a esas GPUs y que, mal configurados, las dejan esperando. El tercero explicará cómo Kubernetes automatiza todo esto; aquí está la capa cruda, la que hay que entender antes de delegarla.

TL;DR

Un nodo con 4×H100 SXM es, físicamente, un servidor de dos sockets = dos dominios NUMA. Cada socket tiene sus núcleos, sus canales de memoria y carriles PCIe hacia la mitad de las GPUs y NICs. La inferencia no es solo GPU: el host hace trabajo en la ruta caliente de cada token —lanzar kernels CUDA, samplear el siguiente token, tokenizar, mover buffers pinned entre host y GPU, correr los hilos de NCCL. Si esos hilos y su memoria caen en el socket que no es local a la GPU, cada acceso cruza el enlace inter-socket (UPI/Infinity Fabric): 2-3× más lento y con picos de p99. Hay tres palancas del kernel que deciden la cola de latencia y que casi nadie toca: locality (afinidad NUMA: que CPU, memoria, GPU y NIC estén en la misma “planta”), page tables (hugepages: pocas páginas grandes en vez de millones de pequeñas, y pinned memory para DMA), y jitter (aislamiento de CPU con isolcpus/nohz_full/rcu_nocbs + IRQ affinity, para que el kernel no interrumpa al hilo que lanza el siguiente kernel de decode). Este post explica el mecanismo, da los 10 knobs reales, y conecta con el interconnect y el decode latency-bound. Con escepticismo sobre qué knobs mueven la aguja en inferencia y cuáles son cargo-cult heredado del trading de baja latencia.

Dónde estás: el host por debajo del cable

La analogía: la oficina de dos plantas

Imagina una consultora en un edificio de dos plantas. En cada planta hay mesas de trabajo (núcleos de CPU), un archivo con los expedientes (la memoria de ese socket) y un muelle de carga que conecta con el exterior (los carriles PCIe hacia las GPUs y las NICs de ese socket). Un analista trabaja rápido mientras todo lo que necesita está en su planta: alarga el brazo y coge el expediente del archivo de al lado.

El problema empieza cuando el analista está en la planta 1 pero su expediente está en el archivo de la planta 2. Cada vez que lo necesita, coge el ascensor. El trabajo “funciona”, pero cada consulta cuesta un viaje. Si encima el muelle de carga por el que entran sus materiales (su GPU) está en la otra planta, cada entrega cruza el edificio. Esto es NUMA: acceso local (misma planta) es rápido; acceso remoto (otra planta, vía el enlace inter-socket) es 2-3× más lento.

Y hay dos formas más de arruinar a ese analista aunque esté en la planta correcta:

Interrumpirle constantemente. Cada pocos minutos, megafonía, un compañero que pregunta, una alarma de incendios de prueba. Cada interrupción le saca de concentración justo cuando iba a entregar. Esto es el jitter del kernel: el tick del scheduler, las IRQs de dispositivos, los callbacks de RCU, que interrumpen al hilo de host justo cuando iba a lanzar el siguiente kernel de la GPU. El aislamiento de CPU es ponerle en un despacho con el cartel de “no molestar”.
Darle un índice de mil pestañas diminutas. Si para encontrar cada expediente tiene que buscar en un índice con un millón de entradas minúsculas, pierde tiempo en la búsqueda. Si el índice tiene pocas entradas grandes, encuentra al instante. Esto son las hugepages: páginas de 2 MB o 1 GB en vez de 4 KB reducen la presión sobre la TLB (el caché del índice de páginas).

La tesis: la GPU es cara y rápida, pero pasa una fracción sorprendente del decode esperando al host. Si el host está en la planta equivocada, interrumpido, y buscando en un índice gigante, la GPU —el recurso de 30.000 € — espera. Las tres palancas de este post existen para que no espere.

El mecanismo: qué hace el host en la ruta del token

Es tentador pensar que en inferencia “la GPU lo hace todo”. No es cierto. Por cada token, el host (CPU) hace, como mínimo:

Lanzar los kernels CUDA de cada operación. La GPU no decide qué ejecutar; el host le va poniendo kernels en la cola. En decode, donde cada kernel es corto, el host tiene que ir por delante alimentando la cola; si el hilo de host se para, la GPU se queda sin trabajo: una burbuja.
Samplear el siguiente token (argmax/top-p/top-k sobre los logits), que vuelve del device al host.
Tokenizar la entrada y detokenizar la salida.
Mover buffers fijados (pinned, page-locked) entre host y GPU por DMA: prompts, logits, y en configuraciones con offload, parte del KV cache.
Correr los hilos de NCCL que coordinan los colectivos del post anterior.

Todo eso es trabajo de CPU y de memoria de host. Y todo eso sufre si:

El proceso corre en el socket que no es local a su GPU → cada DMA y cada acceso a memoria cruza el inter-socket link.
El kernel interrumpe los hilos → burbujas en la cola de la GPU.
La memoria no está fijada o usa páginas pequeñas → page faults, fallos de TLB, y peor: si la memoria de la transferencia DMA no está pinned, el driver hace una copia intermedia.

El mapa: `nvidia-smi topo -m`

Todo arranca por ver el mapa. nvidia-smi topo -m muestra, para cada GPU, a qué NUMA node y a qué núcleos es local, y por qué tipo de camino habla con cada NIC y con cada otra GPU:

 GPU0 GPU1 GPU2 GPU3 NIC0 CPU Affinity NUMA Affinity
GPU0 X NV18 NV18 NV18 PIX 0-31,64-95 0
GPU1 NV18 X NV18 NV18 SYS 0-31,64-95 0
GPU2 NV18 NV18 X NV18 SYS 32-63,96-127 1
GPU3 NV18 NV18 NV18 X SYS 32-63,96-127 1

Léelo así: GPU0 y GPU1 son locales al NUMA node 0 (núcleos 0-31, 64-95); GPU2 y GPU3 al NUMA node 1. NV18 entre GPUs = 18 enlaces NVLink (lo bueno, del post anterior). En la columna NIC: PIX = un solo switch PCIe de por medio (óptimo para GPUDirect RDMA); SYS = el camino cruza el inter-socket (lo peor). La regla: el proceso que sirve sobre GPU0/1 debe pinnearse a los núcleos 0-31/64-95 y a la memoria del node 0; si además usa RDMA, querrás la NIC que esté en PIX con su GPU.

Las matemáticas que importan: un tick del kernel es una burbuja de la GPU

La cifra que conviene interiorizar no es la del ancho de banda, es la del jitter. En decode, el host lanza muchos kernels cortos por token. Si el hilo de host que los lanza es expropiado por el scheduler (un timer tick, una IRQ, un callback de RCU) durante $t_{\text{stall}}$, y la GPU vacía su cola en ese tiempo, aparece una burbuja: la GPU para.

Pon números. Un timer tick típico o el manejo de una IRQ cuesta del orden de decenas de microsegundos de desvío. Si un kernel de decode dura ~50-100 µs y la cola lleva 2-3 kernels en vuelo, un stall de host de 50-100 µs vacía la cola y la GPU se queda parada hasta que el host se reanuda. Multiplica por la frecuencia de interrupciones de un kernel no aislado (el tick por defecto es de 250-1000 Hz, más IRQs de red y disco): la cola de p99/p999 del TTFT y del inter-token se llena de estos episodios.

$$ \text{jitter}{p99} \approx f{\text{interrupciones}} \times t_{\text{stall}} \times \mathbb{1}[\text{cola GPU vaciada}] $$

La intuición: en throughput medio apenas se nota (las burbujas se promedian), pero en la cola —que es lo que un SLO mide— el jitter del kernel es un contribuyente de primer orden. Por eso el aislamiento de CPU, que nació en el trading de baja latencia, tiene sentido en el decode de LLMs: es la misma física —un hilo crítico que no puede permitirse que el kernel lo pare.

Y el coste NUMA, en paralelo: un acceso a memoria remota (otra planta) tiene latencia ~1,5-2× la local y la mitad de ancho de banda. Para los buffers pinned que se mueven por DMA en cada paso, y para las estructuras del scheduler de vLLM que viven en host, esa penalización se paga token a token.

Las tres palancas, uno a uno

Locality (NUMA): que todo esté en la misma planta

El objetivo es que el proceso de inferencia que usa GPU0/1 tenga sus núcleos, su memoria y (si aplica) su NIC en el NUMA node 0. En crudo, sin Kubernetes:

# Pinnear proceso a node 0 (cores y memoria) para servir sobre GPU0/1
numactl --cpunodebind=0 --membind=0 \
 vllm serve meta-llama/Llama-3-70B --tensor-parallel-size 2

--membind=0 es la clave: fuerza que toda la memoria del proceso se asigne en el node 0. Sin --membind, el kernel puede colocar páginas en el node 1 bajo presión, y empiezas a pagar el ascensor sin saberlo.

Page tables (hugepages): pocas páginas grandes y memoria fijada

Dos cosas distintas bajo el mismo paraguas. Primero, hugepages reducen la presión de TLB para los buffers grandes de host (pinned, KV offload). Segundo, pinned memory (page-locked) es lo que permite DMA directo sin copia intermedia. La trampa silenciosa son las transparent hugepages (THP): su compactación en segundo plano causa picos de latencia, justo lo que no quieres.

Jitter (aislamiento de CPU): el despacho con “no molestar”

Tres parámetros de arranque del kernel, coordinados:

isolcpus=2-31,66-95 # saca estos cores del balanceo del scheduler
nohz_full=2-31,66-95 # tickless: sin timer tick si hay 1 solo hilo runnable
rcu_nocbs=2-31,66-95 # offload de callbacks RCU a cores housekeeping

isolcpus aparta los cores; tú tienes que pinnear los hilos de inferencia ahí (los cores no aislados, 0-1, quedan para el sistema). nohz_full quita el tick periódico (solo funciona si hay un único hilo runnable en el core). rcu_nocbs saca de esos cores el trabajo de RCU. Y aparte, IRQ affinity: mover las interrupciones de dispositivos fuera de los cores de inferencia.

Los 10 knobs donde tocar

Ordenados por impacto/frecuencia. Casi todos son sysctl, parámetros de arranque del kernel o numactl. La referencia de bajo nivel es la guía de low-latency de Rigtorp y la doc de tiempo real de Red Hat.

Knob 1 — `nvidia-smi topo -m`: ver el mapa antes de tocar nada

Igual que en el post del interconnect: primero el mapa. Qué GPU es local a qué NUMA node y a qué cores, y qué camino (PIX/PHB/SYS) hay a cada NIC. Sin esto, cualquier pinning es a ciegas. La mitad de los problemas de “la inferencia tiene picos de latencia” son procesos corriendo en el socket equivocado sin que nadie lo haya mirado.

Knob 2 — `numactl --cpunodebind --membind`: pinnear al node local

numactl --cpunodebind=0 --membind=0 <proceso> # cores Y memoria en node 0
numactl --hardware # ver nodes, distancias, memoria libre

El --membind es lo que de verdad importa: sin él, la memoria se dispersa. Es el knob de mayor impacto en el throughput sostenido.

Knob 3 — `kernel.numa_balancing=0`: apagar la migración automática

sysctl -w kernel.numa_balancing=0

El automatic NUMA balancing del kernel migra páginas entre nodes intentando “acercarlas”, pero ese trabajo en segundo plano causa jitter y, con la memoria ya pinneada por el knob 2, no aporta nada. En nodos de inferencia dedicados, apágalo.

Knob 4 — Hugepages explícitas (1 GB) para buffers de host

# Arranque del kernel, para KV offload / buffers pinned grandes
default_hugepagesz=1G hugepagesz=1G hugepages=32

grep Huge /proc/meminfo # verificar reserva

Útil cuando hay memoria de host en la ruta caliente (vLLM con --cpu-offload-gb, o buffers pinned grandes). Si tu despliegue no toca host memory en caliente, las hugepages explícitas aportan poco —no las pongas por cargo-cult.

Knob 5 — THP en `madvise` o `never`: evitar los picos de compactación

echo madvise > /sys/kernel/mm/transparent_hugepage/enabled
echo never > /sys/kernel/mm/transparent_hugepage/defrag

Las transparent hugepages always ahorran TLB pero su compactación dispara latencia impredecible. Para cargas sensibles a la cola, madvise (solo donde la app lo pide) o never es lo recomendado. Es de los pocos knobs con consenso claro: THP always es malo para la latencia.

Knob 6 — `isolcpus`: apartar los cores de inferencia del scheduler

isolcpus=2-31,66-95

Saca esos cores del balanceo de carga del scheduler; el sistema (kernel threads, daemons) se queda en los no aislados. Tienes que pinnear explícitamente los hilos de inferencia a los cores aislados (vía numactl/taskset o, en K8s, el CPU Manager del próximo post). Aislar sin pinnear no sirve de nada.

Knob 7 — `nohz_full` + `rcu_nocbs`: tickless y sin RCU en los cores críticos

nohz_full=2-31,66-95 rcu_nocbs=2-31,66-95

Quita el timer tick periódico y los callbacks de RCU de los cores de inferencia. Dos avisos de la práctica: nohz_full solo elimina el tick si hay un único hilo runnable en el core (si pinneas dos hilos ahí, vuelve el tick); y nohz_full no es compatible con el driver intel_pstate en algunas configuraciones —hay que validarlo, no asumirlo.

Knob 8 — IRQ affinity: las interrupciones, fuera de los cores de inferencia

systemctl stop irqbalance # o configurarlo para respetar isolcpus
# mover IRQs de un dispositivo a los cores housekeeping (0-1)
echo 3 > /proc/irq/<N>/smp_affinity # máscara de cores 0-1

Una IRQ de red o disco que cae en un core de inferencia es una interrupción directa al hilo que alimenta la GPU. Muévelas a los cores housekeeping. (irqbalance puede respetar isolcpus automáticamente si está configurado).

Knob 9 — CPU governor `performance` + C-states

cpupower frequency-set -g performance
# evitar que cores en idle entren en C-states profundos (latencia de wakeup)
cpupower idle-set -D 0 # o limitar la profundidad de C-state

Con el governor powersave/ondemand, un core que estaba en idle tarda en subir de frecuencia: latencia de wakeup justo cuando llega trabajo. performance lo mantiene a tope. En servidores dedicados a inferencia, el ahorro energético no compensa la cola de latencia.

Knob 10 — Bloqueo de memoria + `swappiness=0`

sysctl -w vm.swappiness=0 # no expulsar páginas de la inferencia a swap
# y en la app / contenedor: ulimit -l unlimited (memlock) para pinned memory

Una página de la inferencia que el kernel decide swapear a disco es un page fault de milisegundos en la ruta caliente. swappiness=0 y límites de memlock adecuados (para que el driver pueda fijar memoria) cierran esa puerta. En K8s, esto se traduce en QoS Guaranteed y límites de memoria —el puente al próximo post.

Tabla resumen

#	Knob	Mecanismo	Qué ataca
1	`nvidia-smi topo -m`	diagnóstico	ver afinidad GPU–NUMA–NIC
2	`numactl --cpunodebind --membind`	pinning	locality (la palanca mayor)
3	`kernel.numa_balancing=0`	sysctl	jitter por migración de páginas
4	hugepages 1G explícitas	boot param	TLB en buffers de host
5	THP `madvise`/`never`	sysfs	picos de compactación
6	`isolcpus`	boot param	scheduler fuera de cores críticos
7	`nohz_full`+`rcu_nocbs`	boot param	tick + RCU jitter
8	IRQ affinity	`/proc/irq`	interrupciones de dispositivo
9	governor `performance`	cpupower	latencia de wakeup de frecuencia
10	`swappiness=0` + memlock	sysctl/ulimit	page faults en caliente

Cómo se conecta con el resto del stack

Con el interconnect (post anterior). Los hilos de host de NCCL quieren cores locales a su GPU; y para multinodo, la NIC de RDMA debe estar en el camino PIX con su GPU (knob 1). Un GPUDirect RDMA con la NIC bajo el otro socket pierde la mitad de su ventaja. NUMA y NVLink son la misma historia vista desde el host y desde el cable.

Con vLLM y el decode. El decode es latency-bound: el hilo de host que alimenta la cola de kernels es exactamente el que el aislamiento de CPU protege. Y --cpu-offload-gb de vLLM mete memoria de host en la ruta caliente, donde NUMA locality + hugepages (knobs 2, 4) pasan de “fino” a “crítico”. El continuous batching ayuda aquí también: más tokens por iteración amortizan tanto la latencia del colectivo como el coste fijo de los lanzamientos de host.

Con Kubernetes (post siguiente). Todo lo de este post se hace a mano (numactl, taskset, parámetros de arranque). En producción no se hace a mano: el kubelet lo automatiza con CPU Manager, Memory Manager y Topology Manager. El próximo post es exactamente cómo se declara esto para que cada pod de vLLM nazca pinneado al NUMA node correcto, sin scripts.

Con la observabilidad. Los picos de p99 por jitter o por acceso remoto se ven: en DCGM, baja utilización de GPU con la cola llena (burbujas); en métricas de sistema, tráfico inter-socket y CPU migrations. La observabilidad GPU con DCGM es donde se diagnostica un “la GPU está al 60 % y no sé por qué” que muchas veces es el host esperando.

Con capacity planning. Reservar cores para el sistema (housekeeping) y dedicar el resto a inferencia cambia el cálculo de cuántos pods/réplicas caben por nodo. El capacity planning debe contar esos cores reservados, no asumir que las 128 vCPU están disponibles para servir.

Trampas y cosas que no son lo que parecen

Cargo-cult del trading de baja latencia. Muchas guías de isolcpus/nohz_full vienen del HFT, donde se exprime el último microsegundo. En inferencia LLM, el aislamiento de CPU sí ayuda en la cola del decode, pero no esperes el milagro: si tu cuello de botella es el ancho de banda de HBM o el interconnect, aislar cores no mueve la aguja. Mide antes; aplica donde el host es el límite.

Aislar sin pinnear. isolcpus saca los cores del scheduler, pero si no pinneas los hilos de inferencia ahí, esos cores quedan vacíos y la inferencia corre en los housekeeping, peor que antes. Aislar y pinnear van siempre juntos.

--membind olvidado. Pinnear cores pero no memoria (--cpunodebind sin --membind) deja que las páginas se dispersen al otro node bajo presión. El pinning de memoria es la mitad que más se olvida y la que más rinde.

THP always “porque ahorra TLB”. Ahorra TLB y regala picos de latencia por compactación. Para cargas con SLO de cola, es un mal negocio. madvise/never.

nohz_full con dos hilos en el core. El tickless solo funciona con un único hilo runnable por core. Si pinneas dos hilos de inferencia al mismo core aislado, el tick vuelve y has complicado el arranque del kernel para nada.

Suponer la topología en vez de leerla. Servidores distintos cablean GPUs y NICs a sockets distintos. nvidia-smi topo -m y numactl --hardware son la verdad; el diagrama del fabricante es orientativo. Léelo en cada modelo de nodo.

Conclusión

La GPU es el recurso caro, pero en decode pasa una parte sorprendente del tiempo esperando al host: a que lance el siguiente kernel, a que samplee, a que mueva un buffer. Si ese host está en la planta equivocada (NUMA remoto), interrumpido (jitter del kernel) o buscando en un índice gigante (páginas de 4 KB), la GPU se queda con la cola vacía y el p99 se dispara —sin que ningún dashboard de la API diga por qué. De los diez knobs, el primero (leer el mapa con nvidia-smi topo -m) y el segundo (pinnear cores y memoria al node local con --membind) resuelven la mayoría; el aislamiento de CPU (isolcpus/nohz_full/IRQ affinity) es la segunda capa, la que recorta la cola del decode, y tiene sentido donde el host es el límite, no como ritual. La idea que reordena la intuición: la inferencia no es “todo GPU”; es un baile entre GPU y host, y el host baila mejor cerca, sin que le interrumpan, y con pocas páginas grandes. El próximo post enseña cómo Kubernetes coreografía ese baile para cada pod sin un solo script a mano.

Ver también

Los pasillos y el guardia: PCIe, GPUDirect P2P y ACS — la afinidad PCIe que imprime nvidia-smi topo -m es la afinidad NUMA de este post; colocar NIC y NVMe en el socket correcto evita el camino SYS.
NVLink, NVSwitch y NCCL: el cable por el que pasa cada token — el post anterior de la serie; los hilos de host de NCCL y la NIC de RDMA quieren la misma localidad NUMA que aquí se explica.
Resource managers de RKE2: cómo el kubelet pinnea NUMA por ti — el siguiente post; la automatización declarativa de todo lo que aquí se hace a mano con numactl e isolcpus.
El stack de inferencia LLM on-premise en siete capas — el edificio completo; este post es el sótano (host/kernel) sobre el que se apoya todo.
Optimizaciones de decode en vLLM — la fase latency-bound donde el jitter de host se convierte en cola de p99 y donde el aislamiento de CPU rinde.
Continuous batching — batchear amortiza el coste fijo de los lanzamientos de host además del de los colectivos.
Observabilidad GPU con DCGM — cómo se ve una GPU “al 60 % sin razón” que en realidad es el host esperando: burbujas, migraciones de CPU, tráfico inter-socket.
Capacity planning de inferencia on-premise — por qué hay que descontar los cores housekeeping reservados del presupuesto de cómputo por nodo.
Entornos mixtos NVIDIA + Intel — la afinidad NUMA se complica (y se vuelve más importante) cuando el nodo mezcla GPUs, aceleradores y NICs heterogéneas.
La puerta de la cocina que el maître no miró: NUMA de red, Cilium eBPF y DRANET — la afinidad de IRQ de la NIC es una tercera lista que casar con isolcpus y reserved-cpus; el softirq NET_RX es este mismo jitter entrando por la red.
Del disco a la HBM: cold start y carga del modelo — el buffer de host de la carga de pesos quiere ser pinned y NUMA-local, exactamente lo que aquí se pide para la ruta caliente; es otro cliente del mismo mapa NUMA.
SM, CUDA streams y CUDA graphs — quién lanza los kernels es el hilo de host de este post; su jitter es el launch overhead que los CUDA graphs vienen a reducir.

Referencias

Erik Rigtorp, Low Latency Tuning Guide (isolcpus, nohz_full, IRQ affinity, THP): https://rigtorp.se/low-latency-guide/.
Red Hat, Usage, constraints and implications of isolcpus=, nohz_full= and rcu_nocbs=: https://access.redhat.com/articles/3720611.
NVIDIA, nvidia-smi topo -m y matriz de afinidad GPU–NUMA–NIC (CUDA docs / Developer Forums): https://forums.developer.nvidia.com/t/nvidia-smi-topo-m-revisited/216584.
Chaim Rand, The Crucial Role of NUMA Awareness in High-Performance Deep Learning: https://chaimrand.medium.com/the-crucial-role-of-numa-awareness-in-high-performance-deep-learning-99ae3e8eb49a.
SUSE Labs, CPU Isolation – nohz_full (part 3): https://www.suse.com/c/cpu-isolation-nohz_full-part-3/.
Linux kernel, Automatic NUMA Balancing y Transparent Hugepage Support (Documentation/admin-guide): https://docs.kernel.org/admin-guide/mm/transhuge.html.

La mesa compartida: NVLink, NVSwitch y NCCL, el cable por el que pasa cada token en tensor parallel

Sat, 06 Jun 2026 07:00:00 +0200

Este post baja un piso por debajo del motor. En el stack de inferencia en siete capas y en una grande vs N pequeñas se decidía cuántas GPUs y cómo repartir el modelo; aquí se explica el cable que hace que ese reparto funcione —o que lo estrangule. Es el primero de una mini-serie “por debajo del motor”: interconnect (este) → kernel y NUMA → resource managers de Kubernetes.

TL;DR

Tensor parallelism (TP) no parte un modelo en cuatro trozos que corren solos. Reparte cada capa entre las GPUs, pero después de la atención y después del MLP las GPUs tienen que sumar sus resultados parciales con un all-reduce. En un Llama-70B con 80 capas, eso son ~160 all-reduces por cada token generado. Ese all-reduce viaja por el interconnect, así que el interconnect está en la ruta crítica de cada token, no en la fontanería de fondo. En un baseboard HGX H100, las 8 GPUs hablan todas-con-todas a 900 GB/s bidireccionales vía cuatro NVSwitch; sin NVSwitch/NVLink, ese mismo tráfico cae al CPU vía PCIe y pierde un orden de magnitud. NCCL es la librería que decide cómo se hace cada colectivo (ring, tree, o NVLS = NVLink-SHARP, que descarga la suma en el propio switch). Y hay una asimetría que casi nadie tiene en la cabeza: el decode es latency-bound (mensajes diminutos, 16 KB) y el prefill es bandwidth-bound (activaciones enormes batcheadas) — por eso “más ancho de banda NVLink” acelera el prefill pero apenas toca el decode token-a-token. Este post explica el mecanismo, da los 10 knobs reales de NCCL/driver donde se toca, y conecta con el custom all-reduce de vLLM, el disaggregated serving y la observabilidad GPU. Con escepticismo sobre qué palancas mueven la aguja.

Dónde estás: el piso por debajo del motor

La analogía: cuatro mecánicos y una sola mesa

Cuatro mecánicos montan un mismo motor de coche. No es que cada uno monte su propio motor en paralelo —eso sería tener cuatro coches (cuatro réplicas del modelo, otra estrategia). Aquí montan uno solo, a la vez, repartiéndose las piezas: uno hace los pistones, otro la culata, otro el cigüeñal. El problema es que las piezas encajan entre sí: antes de seguir, los cuatro tienen que juntar lo que llevan y comprobar que casa. Ese “juntar y comprobar” pasa decenas de veces durante el montaje.

Hay dos formas de organizar el taller:

Una sola mesa grande, todos alrededor (NVSwitch). Cada mecánico alarga el brazo y pasa su pieza directamente a cualquier otro, todos a la vez, sin levantarse. Es instantáneo y simultáneo. Esto es NVLink + NVSwitch: las GPUs forman un all-to-all donde cualquiera habla con cualquiera a 900 GB/s al mismo tiempo.
Cuatro talleres separados con un mensajero (PCIe vía CPU). Cada pieza que un mecánico quiere pasar a otro va metida en una caja, baja a recepción (la memoria del host, vía CPU), y de ahí sube al taller destino. Más lento, y serializado por la recepción. Esto es lo que ocurre cuando no hay NVLink: el tráfico inter-GPU cae a PCIe y rebota por el CPU, ~14× más lento que NVLink.

La tesis del post se deriva sola: tensor parallelism solo tiene sentido si los mecánicos comparten la mesa. En cuanto el “juntar y comprobar” (el all-reduce) tiene que pasar por la recepción, el reparto del trabajo cuesta más de lo que ahorra. Por eso, en una plataforma seria, TP no cruza el límite del NVLink: TP=4 u 8 dentro del baseboard donde hay NVSwitch, y de ahí para arriba se replica o se usa pipeline, nunca se estira TP por PCIe o por red. Cuándo conviene cada cosa está en una grande vs N pequeñas; aquí explicamos por qué el cable manda esa decisión.

El mecanismo: qué es realmente un all-reduce y por qué hay 160 por token

Tensor parallelism parte las matrices de pesos por columnas/filas entre las $N$ GPUs. Cada GPU calcula una porción de la salida de la capa. Pero la siguiente operación necesita la salida completa, así que hay que recombinar. Esa recombinación es una operación colectiva: un all-reduce, que suma elemento a elemento los tensores parciales de todas las GPUs y deja el resultado idéntico en todas.

En un bloque transformer estándar hay dos puntos de sincronización por capa:

Tras la proyección de salida de la atención (el o_proj que recombina las cabezas repartidas).
Tras la segunda matriz del MLP (el down_proj que recombina el feed-forward repartido).

$$ \text{all-reduces por token} = 2 \times L_{\text{capas}} $$

Para un Llama-70B ($L = 80$): $2 \times 80 = 160$ all-reduces por token generado. No por petición, no por secuencia: por token. Multiplica por el throughput de decode y entiendes por qué el interconnect no es infraestructura de fondo sino ruta caliente.

× 80 capas = 160 all-reduce por token · cada uno cruza el interconnect si el cable es lento, el decode se desploma — el motor espera al cable

Cómo se hace el all-reduce: ring, tree, NVLS

NCCL no tiene una sola forma de hacer un all-reduce; elige un algoritmo según topología y tamaño del mensaje:

Ring. Las GPUs forman un anillo; cada una pasa un trozo al vecino, suma, y rota. Hace falta dar $2(N-1)$ pasos. Es óptimo en ancho de banda para mensajes grandes: el coste de mover los datos es $\frac{2(N-1)}{N} \times M$ bytes por el enlace, casi independiente de $N$. Lo malo: $2(N-1)$ saltos de latencia, malo para mensajes pequeños.
Tree. Reducción en árbol: $\log N$ niveles. Mejor latencia para mensajes pequeños y muchos nodos, peor aprovechamiento de banda.
NVLS (NVLink SHARP). El truco de Hopper: la suma no la hacen las GPUs, la hace el NVSwitch. El switch tiene unidades de reducción; las GPUs envían sus tensores, el switch los suma en tránsito y devuelve el resultado. Quita trabajo a las GPUs (libera SMs) y reduce saltos. Disponible solo con NVSwitch de 3ª generación (NVLink4) + Hopper o superior.

La regla mental: decode (mensajes diminutos) quiere latencia → tree/LL o el custom kernel de vLLM; prefill (mensajes enormes) quiere banda → ring/NVLS. Por eso no hay un “NCCL_ALGO óptimo” global; depende de qué fase estés mirando.

Las matemáticas que importan: por qué decode y prefill estresan el cable al revés

Aquí está la asimetría que casi todo el mundo se salta. El tamaño del tensor que se all-reducea en cada capa es, aproximadamente:

$$ M \approx B \times S \times h \times 2\ \text{bytes (BF16)} $$

donde $B$ = batch, $S$ = tokens procesados en este forward, $h$ = hidden size.

En decode, generas 1 token por secuencia por iteración. Para una sola secuencia ($B \times S = 1$) y $h = 8192$ (Llama-70B):

$$ M_{\text{decode}} \approx 1 \times 8192 \times 2 = 16\ \text{KB por all-reduce} $$

16 KB es minúsculo. A 900 GB/s, mover 16 KB tarda ~18 nanosegundos de transferencia pura —pero el coste real lo domina la latencia de lanzamiento del colectivo (sincronización, kernel launch), del orden de single-digit microsegundos. Con 160 all-reduces por token:

$$ t_{\text{comms/token}} \approx 160 \times (5\text{–}10,\mu s) \approx 0{,}8\text{–}1{,}6\ \text{ms} $$

Ese es el suelo de comunicación por token, independiente del ancho de banda. Implicación incómoda y contraintuitiva: comprar más ancho de banda NVLink no acelera el decode token-a-token de una sola secuencia. Lo que ayuda en decode es bajar la latencia por colectivo (protocolo LL, el custom all-reduce de vLLM, NVLS para quitar saltos) y batchear (subir $B$ amortiza la latencia fija sobre más tokens — la razón profunda por la que el continuous batching existe, cubierto en continuous batching).

En prefill, procesas el prompt entero de golpe: $S$ puede ser miles de tokens, y con batching $B \times S$ llega a decenas de miles. Ahí:

$$ M_{\text{prefill}} \approx 8000 \times 8192 \times 2 \approx 131\ \text{MB por all-reduce} $$

131 MB sí estresan el ancho de banda. A 900 GB/s (NVSwitch) el all-reduce ring mueve $\frac{2 \cdot 3}{4} \times 131 \approx 196$ MB efectivos en ~0,22 ms; por PCIe (~64 GB/s agregados, rebotando por CPU) serían ~3 ms y serializados. Aquí el cable es el cuello de botella y NVLS/banda mandan.

Resumen en una línea: prefill es bandwidth-bound, decode es latency-bound. Cualquier tuning del interconnect que no diga en qué fase ayuda es ruido.

El hardware: NVLink 4 y NVSwitch sobre el baseboard HGX

Sobre el cluster genérico de referencia —4×H100 SXM dentro de un baseboard HGX— las cifras concretas:

Cada H100 SXM5 tiene 18 enlaces NVLink 4, cada uno 50 GB/s bidireccionales ⇒ 900 GB/s bidireccionales agregados por GPU. Eso es >14× el ancho de banda de un PCIe Gen4 x16 (~64 GB/s bidir).
En un baseboard HGX H100 de 8 GPUs, los 18 enlaces de cada GPU se reparten contra cuatro NVSwitch de 3ª generación (agrupación 5+4+4+5). El resultado es all-to-all: cualquier GPU habla con cualquier otra a 900 GB/s simultáneamente, sin pasar por CPU ni PCIe.
Un baseboard de 4 GPUs es media-placa: mismo principio, NVSwitch mediante. Clave de diseño: si tus 4 H100 están conectadas por NVSwitch, tienes all-to-all real; si están en placas distintas conectadas por PCIe (algunas configuraciones “4×PCIe”), no tienes NVLink entre todas y TP=4 sufre. Verifícalo, no lo asumas.

Sin NVLink · PCIe vía CPU (~14× más lento) G0 G1 G2 G3 CPU todo el tráfico inter-GPU rebota por la memoria del host, serializado

Los 10 knobs donde tocar

Casi todos son variables de entorno de NCCL (se inyectan en el proceso del motor de inferencia) o ajustes de driver. Ordenados por impacto/frecuencia en un despliegue on-premise. El detalle canónico está en la doc de env vars de NCCL.

Knob 1 — `NCCL_DEBUG` + topology dump: ver qué está pasando antes de tocar nada

No optimices a ciegas: primero confirma qué topología y algoritmos eligió NCCL. Esto te dice si de verdad está usando NVLink o si, en silencio, cayó a PCIe/SHM —el fallo nº1 y el más caro.

NCCL_DEBUG=INFO # imprime topología, rings/trees construidos, transporte elegido
NCCL_DEBUG_SUBSYS=GRAPH,TUNING,NET # acota a lo que importa
# busca en el log: "via NVLink" / "via P2P" (bien) vs "via SHM" / "via PCI" (mal)

Si ves via SHM o via PCI entre GPUs que deberían tener NVLink, tienes un problema de topología (ACS de PCIe activo, IOMMU, GPUs en placas distintas) y ningún otro knob lo arregla. Este es el knob 1 por una razón: la mitad de los “NVLink va lento” son “NVLink no se está usando”.

Knob 2 — `NCCL_ALGO`: ring vs tree vs NVLS

Fuerza o excluye algoritmos. Por defecto NCCL elige según tamaño, y suele acertar; tócalo solo con medición delante.

NCCL_ALGO=NVLS,Tree,Ring # orden de preferencia
NCCL_ALGO=^Ring # excluir Ring (prefijo ^)

Regla: prefill/entrenamiento (banda) ⇒ Ring/NVLS; decode (latencia) ⇒ Tree o, mejor, el custom kernel de vLLM (knob 10/stack). En la mayoría de inferencia, dejarlo en auto y validar con el knob 1 es lo correcto; forzarlo “por si acaso” suele empeorar.

Knob 3 — `NCCL_PROTO`: LL / LL128 / Simple

El protocolo controla el trade-off latencia/banda a bajo nivel:

NCCL_PROTO=Simple # máxima banda, más latencia (mensajes grandes)
NCCL_PROTO=LL # low-latency, half-bandwidth (mensajes diminutos: decode)
NCCL_PROTO=LL128 # compromiso, default en plataformas que lo soportan

LL (low-latency) usa flags en vez de barreras y gana en los mensajes de 16 KB del decode; Simple gana en los 131 MB del prefill. El default LL,LL128,Simple deja a NCCL elegir por tamaño —de nuevo, normalmente lo mejor.

Knob 4 — `NCCL_NVLS_ENABLE`: descargar la suma en el NVSwitch

NVLink SHARP (NVLS) hace que el switch reduzca, liberando SMs de las GPUs:

NCCL_NVLS_ENABLE=1 # default: ON donde hay NVSwitch NVLink4+ (Hopper)

Matiz escéptico importante: NVLS requiere NVSwitch (3ª gen, NVLink4). En un nodo con NVLink por bridges directos GPU-a-GPU (sin switch) o en 4×PCIe, NVLS no está disponible y este knob no hace nada. Antes de “activarlo”, confirma con el knob 1 que tu topología tiene switch. Donde aplica, su mayor ventaja es liberar SMs para el cómputo —relevante cuando comms y kernels compiten (knob 5).

Knob 5 — `NCCL_MIN_NCHANNELS` / `NCCL_MAX_NCHANNELS`: cuántos SM roba la comunicación

Cada “channel” de NCCL consume SMs de la GPU para mover datos. Más channels = más ancho de banda de colectivo, pero menos SMs para el kernel de inferencia. Es un reparto de un recurso fijo.

NCCL_MIN_NCHANNELS=4
NCCL_MAX_NCHANNELS=16 # subir ayuda al prefill (banda); roba SMs al decode

En decode, donde la GPU está infrautilizada de cómputo pero atada a latencia, recortar channels rara vez duele y a veces ayuda; en prefill, más channels exprimen la banda. Knob de medición, no de fe.

Knob 6 — `NCCL_BUFFSIZE`: el tamaño del buffer por channel

NCCL_BUFFSIZE=8388608 # 8 MB (default 4 MB); buffers mayores → mejor BW en mensajes grandes

Subirlo ayuda al prefill bandwidth-bound a costa de memoria por channel. Para cargas dominadas por mensajes pequeños (decode puro), el default sobra.

Knob 7 — `NCCL_P2P_LEVEL` / `NCCL_P2P_DISABLE`: garantizar P2P sobre NVLink

P2P es lo que permite que una GPU lea la memoria de otra directamente por NVLink sin pasar por el host. Si se desactiva o degrada, el tráfico cae a SHM/PCIe.

NCCL_P2P_LEVEL=NVL # usa P2P hasta el nivel NVLink
# NCCL_P2P_DISABLE=1 ← solo como workaround si P2P CUELGA (PCIe multi-NUMA, ciertas Blackwell)

Atención a la trampa: NCCL_P2P_DISABLE=1 y --disable-custom-all-reduce se recomiendan como parche cuando vLLM se cuelga en topologías PCIe-only multi-NUMA. Es un parche de robustez que sacrifica rendimiento: úsalo si cuelga, nunca “por defecto”.

Knob 8 — GPUDirect RDMA para multinodo: `NCCL_NET_GDR_LEVEL`

Cuando el TP cabe en un nodo, esto no aplica. Cuando hay que cruzar nodos (modelo enorme, pipeline parallel entre baseboards), GPUDirect RDMA permite que la GPU hable con la NIC sin rebotar por la memoria del host:

NCCL_NET_GDR_LEVEL=PHB # habilita GDR según cercanía GPU–NIC en el bus PCIe

Sin GDR, cada salto inter-nodo añade una copia host. Con InfiniBand/RoCE + GDR, el KV o las activaciones viajan GPU→NIC→red→NIC→GPU. Es la base del multinodo serio y de entornos mixtos.

Knob 9 — `NCCL_IB_HCA` / `NCCL_SOCKET_IFNAME`: fijar la NIC correcta

El error multinodo más común y silencioso: NCCL elige la NIC de gestión (1 GbE) en vez de la de fabric (InfiniBand/100 GbE). Resultado: colectivos a paso de tortuga sin error visible.

NCCL_SOCKET_IFNAME=eth0 # interfaz de control (bootstrap)
NCCL_IB_HCA=mlx5_0,mlx5_1 # las HCA InfiniBand reales del fabric
NCCL_IB_GID_INDEX=3 # GID correcto para RoCE v2

Fíjalas explícitamente. “Auto” acierta en clusters limpios y falla en cuanto hay más de una NIC.

Knob 10 — Driver: persistence mode, clocks y contadores de error NVLink

Por debajo de NCCL, el driver tiene palancas y, sobre todo, telemetría que hay que mirar:

nvidia-smi -pm 1 # persistence mode: evita re-init del driver (latencia/jitter)
nvidia-smi nvlink --status # ¿los 18 enlaces activos y a velocidad plena?
nvidia-smi nvlink -e # contadores de error/CRC por enlace
nvidia-smi -q -d ECC # errores de memoria que degradan en silencio

Un enlace NVLink que negocia a media velocidad o acumula errores CRC degrada el all-reduce sin lanzar ningún error —el sistema “funciona”, solo va más lento. Estos contadores son la diferencia entre diagnosticar en cinco minutos o perseguir un fantasma durante días. Se integran en DCGM (knob/stack: observabilidad).

Tabla resumen

#	Knob	Variable / comando	Fase que ayuda
1	Diagnóstico topología	`NCCL_DEBUG=INFO` + `SUBSYS=GRAPH`	siempre, primero
2	Algoritmo colectivo	`NCCL_ALGO` (NVLS/Tree/Ring)	según fase; auto suele ganar
3	Protocolo	`NCCL_PROTO` (LL/LL128/Simple)	LL=decode, Simple=prefill
4	NVLink SHARP	`NCCL_NVLS_ENABLE=1`	prefill; libera SMs (requiere NVSwitch)
5	Channels (SMs)	`NCCL_MIN/MAX_NCHANNELS`	+banda prefill / −robo SM decode
6	Buffer	`NCCL_BUFFSIZE`	prefill bandwidth-bound
7	P2P NVLink	`NCCL_P2P_LEVEL=NVL`	crítico; disable solo si cuelga
8	GPUDirect RDMA	`NCCL_NET_GDR_LEVEL`	multinodo
9	NIC de fabric	`NCCL_IB_HCA`/`SOCKET_IFNAME`	multinodo (evita NIC mgmt)
10	Driver + telemetría	`nvidia-smi -pm 1` / `nvlink -e`	jitter + diagnóstico silencioso

Cómo se conecta con el resto del stack

El interconnect no es una isla; toca casi todas las capas de arriba.

Con vLLM — el custom all-reduce. vLLM no siempre usa NCCL: para los mensajes diminutos del decode (world_size==2 o topología fully-connected por NVLink, por debajo de cierto max_size) usa un kernel propio de all-reduce que bate a NCCL en latencia —exactamente el cuello de botella del decode que vimos en las matemáticas. Cae a NCCL para mensajes grandes y para topologías sin NVLink (donde su custom kernel “aporta poco sobre NCCL”). El flag --disable-custom-all-reduce / VLLM_DISABLE_CUSTOM_ALL_REDUCE lo apaga; es el parche cuando cuelga en PCIe multi-NUMA. Traducción: el knob de latencia de decode más efectivo a veces no es de NCCL, es elegir bien entre el custom kernel de vLLM y NCCL.

Con TP vs réplicas. Todo lo de una grande vs N pequeñas descansa sobre esto: TP alto solo es viable dentro del dominio NVLink. La frontera de “¿TP=4 o 4 réplicas TP=1?” la dibuja el cable: cruzar NVLink con TP es pagar el all-reduce a precio de PCIe.

Con disaggregated serving. En prefill/decode desagregado, el KV cache generado en el pool de prefill tiene que viajar al pool de decode. Ese traslado es otro consumidor del interconnect (NVLink intra-nodo, GPUDirect RDMA inter-nodo) y compite con los all-reduce. Diseñar la desagregación sin contar el coste de transferencia de KV es la trampa clásica.

Con MoE. Los modelos Mixture-of-Experts añaden expert parallelism: un all-to-all (no all-reduce) que enruta cada token a su experto, posiblemente en otra GPU. Es un patrón de comunicación distinto y más pesado en banda; MoE en inferencia vive o muere por el mismo cable, con un colectivo aún más exigente.

Con la observabilidad GPU. Los contadores NVLink (nvidia-smi nvlink -e, bytes TX/RX por enlace, errores CRC) y la utilización de NVSwitch se exponen vía DCGM y aterrizan en Prometheus/Grafana. La pregunta “¿está el interconnect sano y saturado?” se responde ahí, junto al resto de observabilidad GPU con DCGM. Un all-reduce lento se ve antes en un contador de errores NVLink que en la latencia de la API.

Con capacity planning. El dimensionado de inferencia que asume “TP=4 escala casi lineal” solo se cumple dentro del NVLink. Fuera de él, la eficiencia de escalado se cae y el plan de capacidad miente. El cable es un parámetro del modelo de capacidad, no un detalle.

Trampas y cosas que no son lo que parecen

“Más ancho de banda NVLink = decode más rápido.” Falso para una secuencia. El decode es latency-bound; el ancho de banda apenas se toca con mensajes de 16 KB. Lo que acelera el decode es batchear (amortizar la latencia fija) y bajar latencia por colectivo (LL, custom kernel, NVLS). El ancho de banda manda en prefill.

“Tengo 4 H100, luego tengo NVLink entre las cuatro.” No necesariamente. Hay configuraciones donde las GPUs están en placas distintas unidas por PCIe, o con bridges NVLink solo por pares. Confírmalo con nvidia-smi nvlink --status y el knob 1 antes de planificar TP=4. Un TP=4 sobre P2P-por-PCIe rinde mucho peor de lo que dice el folleto.

Forzar NCCL_ALGO/NCCL_PROTO “para ir más rápido”. NCCL elige bien por tamaño en la mayoría de casos. Forzar un algoritmo sin medir suele empeorar una de las dos fases. La secuencia correcta es: knob 1 (ver qué hace) → medir → tocar solo si hay evidencia.

Desactivar P2P/custom all-reduce por defecto. Son parches de robustez para topologías rotas (PCIe multi-NUMA, ciertas Blackwell). Dejarlos puestos “por estabilidad” en un nodo con NVLink sano tira rendimiento a la basura.

Estirar TP por la red. TP=8 cruzando dos nodos por InfiniBand porque “hay banda” ignora que el all-reduce por capa ahora paga latencia de red ×160 por token. Para cruzar nodos, pipeline parallel (que comunica una vez por micro-batch, no por capa) casi siempre gana. El patrón de comunicación, no solo la banda, decide.

Ignorar los contadores de error NVLink. Un enlace degradado no lanza excepción: el sistema funciona, solo va lento. Sin vigilar nvlink -e y ECC, persigues un fantasma de rendimiento que un contador te habría señalado en cinco minutos.

Conclusión

Tensor parallelism vende una promesa simple —parte el modelo, multiplica la VRAM, sirve modelos que no caben en una GPU— pero la letra pequeña es que cada capa obliga a las GPUs a juntarse y sumar, dos veces, decenas de veces por token. Ese all-reduce es el verdadero protagonista oculto del rendimiento, y vive en el cable: NVLink lo hace por la mesa compartida del NVSwitch a 900 GB/s, o PCIe lo arrastra por la recepción del CPU 14× más lento. De los diez knobs, el primero —mirar con NCCL_DEBUG qué está pasando de verdad— resuelve la mitad de los problemas, porque la mitad de los “NVLink va lento” son “NVLink no se usa”. El resto son afinados que solo significan algo si sabes en qué fase estás: prefill quiere banda (NVLS, Simple, channels, buffer), decode quiere latencia (LL, el custom kernel de vLLM, batching). Y por encima de todo, una idea que reordena la intuición: en inferencia on-premise, el interconnect no es fontanería que se instala y se olvida —es ruta caliente, parámetro de capacidad y, cuando se degrada en silencio, la causa raíz que ningún dashboard de la API te va a señalar si no miras los contadores del propio cable.

Ver también

Los pasillos y el guardia: PCIe, GPUDirect P2P y ACS — el otro bus del nodo; lo que no cabe en la mesa NVLink (disco, red, KV entre nodos) viaja por PCIe, y el ACS decide si el GPUDirect va directo o rebota por el root complex.
El stack de inferencia LLM on-premise en siete capas — el edificio completo donde el interconnect es el cimiento sobre el que se apoyan las siete capas; aquí se abre ese cimiento.
Una grande vs N pequeñas: TP y réplicas — la decisión de cuántas GPUs y cómo repartir el modelo; este post explica por qué el límite del NVLink dibuja esa frontera.
Disaggregated serving: prefill y decode separados — el traslado del KV cache entre pools es otro consumidor del mismo interconnect que compite con los all-reduce.
Continuous batching — la razón profunda por la que batchear acelera el decode es que amortiza la latencia fija del all-reduce sobre más tokens.
Optimizaciones de decode en vLLM — la fase latency-bound donde el custom all-reduce de vLLM y el protocolo LL deciden el TPS por secuencia.
MoE en inferencia — el expert parallelism añade un all-to-all aún más exigente sobre el mismo cable.
Observabilidad GPU con DCGM — dónde aterrizan los contadores NVLink y de NVSwitch para responder “¿está el interconnect sano y saturado?”.
Capacity planning de inferencia on-premise — por qué “TP escala casi lineal” solo es cierto dentro del dominio NVLink, y cómo el cable entra en el modelo de capacidad.
Entornos mixtos NVIDIA + Intel — cuando se cruza el límite del nodo, GPUDirect RDMA sobre InfiniBand/RoCE sustituye a NVLink como medio del colectivo.
La puerta de la cocina que el maître no miró: NUMA de red, Cilium eBPF y DRANET — que ese GPUDirect RDMA vaya por el camino NUMA-local (GPU y NIC en el mismo PCIe root) es justo lo que DRA/DRANET co-programa; +60% de bus bandwidth NCCL cuando se alinea.
SM, CUDA streams y CUDA graphs — entre los kernels de cómputo se intercalan los all-reduces de TP; el custom all-reduce de vLLM se integra en el mismo CUDA graph para no romper la secuencia con una sincronización de CPU.

Referencias

NVIDIA, NVIDIA Hopper Architecture In-Depth (NVLink 4, 900 GB/s): https://developer.nvidia.com/blog/nvidia-hopper-architecture-in-depth/.
NVIDIA, Introducing NVIDIA HGX H100 (4× NVSwitch, all-to-all): https://developer.nvidia.com/blog/introducing-nvidia-hgx-h100-an-accelerated-server-platform-for-ai-and-high-performance-computing/.
NVIDIA, NCCL Environment Variables (todos los knobs de este post): https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/env.html.
NVIDIA, The NVLink-Network Switch (Hot Chips 2022, NVLink SHARP): https://hc34.hotchips.org/.
vLLM, Why does vLLM use a custom all-reduce method? (discussion #6159) y custom_all_reduce.py: https://github.com/vllm-project/vllm/discussions/6159.
NVIDIA, NCCL Multi-Node NVLink Tuning Guide: https://docs.nvidia.com/multi-node-nvlink-systems/multi-node-tuning-guide/nccl.html.

Langfuse por dentro: el centro de clasificación que no debe convertirse en el cuello de botella que vino a observar

Sat, 06 Jun 2026 06:00:00 +0200

Este post cierra una trilogía de la capa Observe: en Tracing LLM con OpenTelemetry GenAI se montó el pipeline SDK → Collector → backend y se trató Langfuse como una caja negra que recibe spans; en Prompt versioning con Langfuse y MLflow se usó su capa de prompt management. Aquí abrimos la caja: qué hay dentro de Langfuse, por qué v3 dejó de ser un monolito sobre Postgres, y cómo se opera para que aguante el tráfico de un cluster de inferencia sin convertirse en el problema.

TL;DR

Langfuse v3 (estable desde diciembre de 2024) no es una aplicación, son seis servicios: dos contenedores propios (Web y Worker) y cuatro dependencias de estado (Postgres, ClickHouse, Redis/Valkey y un blob store S3-compatible). El cambio arquitectónico clave respecto a v2 —que era un monolito Next.js sobre Postgres— es la tubería de ingesta asíncrona: las trazas se reciben en lotes, se escriben inmediatamente a S3, se encola solo una referencia en Redis, y un Worker las ingiere a ClickHouse en segundo plano. Esto desacopla la velocidad de recepción (limitada solo por la latencia de escritura de Redis, ~1-5 ms) del coste de persistir y mergear en la base analítica. El resultado: el contenedor Web sostiene cientos de eventos por segundo sin que un pico bloquee al cliente que sirve la inferencia. Pero ese diseño solo rinde con los ajustes correctos. Este post cubre la arquitectura, su interacción con el resto del stack on-premise, y diez knobs de backend —del batching a ClickHouse al sharding de colas, del modificador FINAL a la higiene de las system log tables— que deciden el throughput real y el coste de almacenamiento. Y marca dónde el async esconde ventanas de pérdida de datos que conviene conocer antes de prometer “trazabilidad total”.

Estás aquí: OBSERVE (y la capa que sostiene a las demás)

La analogía: el centro de clasificación postal

Imagina la oficina central de clasificación de correos de una gran ciudad en hora punta. Llegan camiones cargados de sacas (lotes de cartas) a un ritmo que no para. Si el empleado de la ventanilla tuviera que abrir cada saca, leer cada carta, decidir su destino y archivarla antes de aceptar el siguiente camión, la cola de camiones daría la vuelta a la manzana en diez minutos. Ningún centro de clasificación serio funciona así.

Lo que hacen es desacoplar la recepción del procesado:

La ventanilla de recepción acepta la saca, le pone un sello de acuse, la deja en un casillero del almacén y suelta un ticket en una cinta transportadora. Tiempo por saca: segundos. La ventanilla nunca se bloquea.
Más atrás, en la sala de clasificación, un equipo de operarios va cogiendo tickets de la cinta, recupera la saca de su casillero, la abre, clasifica las cartas y las archiva en el archivo permanente —ordenado, indexado, consultable.

Langfuse v3 es exactamente este centro de clasificación:

Centro postal	Langfuse v3	Función
Ventanilla de recepción	Contenedor Web (endpoint de ingesta)	Acepta lotes de eventos, da acuse inmediato (HTTP 207)
Almacén de casilleros	S3 / Blob store (MinIO on-prem)	Guarda la saca cruda (el evento completo)
Ticket en la cinta	Redis / Valkey (cola BullMQ)	Solo la referencia al objeto en S3, no el contenido
Sala de clasificación	Contenedor Worker	Coge tickets, lee S3, transforma y archiva
Archivo permanente indexado	ClickHouse (OLAP)	Trazas, observaciones y scores, consultables por proyecto+tiempo
Registro administrativo	Postgres (OLTP)	Usuarios, proyectos, API keys, prompts, datasets, config

La tesis de todo el post se deriva de esta analogía: el valor de Langfuse está en que la ventanilla nunca bloquee al cliente que sirve la inferencia. Una herramienta de observabilidad que añade latencia o caídas a la ruta de servir tokens es peor que no tener observabilidad —porque degrada justo el sistema que pretendía cuidar. Todo el diseño de v3, y todos los knobs de este post, existen para mantener esa promesa bajo carga.

El mecanismo en sí: seis servicios, dos planos

Langfuse v3 separa dos planos que en v2 estaban fundidos:

Plano de ingesta y consulta (los dos contenedores propios, stateless, escalables horizontalmente): Web y Worker.
Plano de estado (cuatro dependencias, cada una con su perfil de carga): Postgres (OLTP transaccional), ClickHouse (OLAP analítico), Redis/Valkey (cola + caché), Blob store (objetos crudos).

Ruta de ingesta (asíncrona) ① Web escribe evento → S3 ② Web encola ref → Redis ③ Worker saca ref de Redis ④ lee S3 → ⑤ inserta en ClickHouse UI/API: Web lee de ClickHouse (traces) + Postgres (config)

batch

Lo que hay que retener de este diagrama:

Web y Worker son intercambiables y stateless. No guardan nada localmente. Puedes correr 1 o 20 réplicas de cada uno; el estado vive en las cuatro dependencias. Esto es lo que permite escalar por carga sin coreografías.
Redis nunca lleva el contenido del evento, solo la referencia al objeto en S3. Por eso Redis aguanta el pico: una escritura de Redis es ~1-5 ms y mueve bytes, no kilobytes. El cuello de botella del contenedor Web es, literalmente, la velocidad de escritura de Redis.
Postgres y ClickHouse tienen perfiles opuestos. Postgres es OLTP: muchas lecturas/escrituras pequeñas y transaccionales (¿esta API key es válida?, ¿qué versión tiene el label production?). ClickHouse es OLAP: pocas escrituras enormes en batch y consultas analíticas sobre miles de millones de filas (dame el p95 de TTFT del proyecto X en los últimos 7 días). Meter trazas en Postgres —lo que hacía v2— funciona hasta que no funciona: a volumen de producción, Postgres se ahoga en una carga para la que no está diseñado. Ese fue el motivo del rediseño.

El flujo de ingesta paso a paso (y las matemáticas del desacoplo)

El corazón del diseño es la ruta de ingesta. Vista en detalle, una request POST /api/public/ingestion con un lote de eventos hace esto:

— el cliente ya siguió con su trabajo —

③ Worker saca ref ④ lee evento de S3 ⑤ buffer + flush batch → INSERT CH async, fuera de la ruta del cliente

El punto matemático es el acuse temprano (early ACK). La latencia que el cliente percibe al enviar trazas es:

$$ t_{\text{cliente}} = t_{\text{S3 write}} + t_{\text{Redis enqueue}} \approx 10\text{–}40,\text{ms} $$

mientras que el coste real de persistir —leer S3, transformar, mergear contra la versión previa, insertar en ClickHouse, dejar que los background merges compacten— ocurre fuera de esa ruta, en el Worker, y puede tardar cientos de ms o segundos sin que al cliente le importe. El desacoplo convierte un sistema cuyo throughput estaría limitado por la velocidad de ClickHouse en uno limitado por la velocidad de Redis. Y Redis, en hardware modesto, sostiene del orden de 50.000 operaciones/segundo.

Esto tiene una consecuencia de dimensionado importante. Si tu carga de inferencia genera $E$ eventos/segundo (un chat con RAG + 2 tool calls produce fácilmente 6-10 spans = eventos por petición), el contenedor Web los absorbe mientras $E \ll 50.000$. El Worker, en cambio, escala con el coste de procesar: ese es el componente que hay que vigilar y replicar, y el primer knob del post.

Escepticismo honesto. El early ACK tiene una cara B: entre el HTTP 207 y la persistencia en ClickHouse hay una ventana de pérdida potencial. Si el evento está en S3 y la referencia en Redis, y Redis se cae sin persistencia (AOF/RDB) antes de que el Worker procese, la referencia se pierde —el dato sigue en S3 pero ya nadie lo reclama. Más sutil: el Worker bufferiza escrituras a ClickHouse en memoria y las hace flush por lotes; un crash del Worker con el buffer lleno pierde ese lote. Existe un bug reportado donde el ClickhouseWriter descarta filas tras agotar reintentos de flush sin dead-letter queue. Para observabilidad esto suele ser tolerable (perder el 0,01 % de las trazas no rompe nada). Para auditoría regulatoria —donde la traza es evidencia— no lo es, y conviene tratar Langfuse como “best-effort” y no como libro contable. Volveremos sobre esto en el cierre.

Interacción con el resto del stack: Langfuse en el cluster 4×H100 de ejemplo

Langfuse no vive aislado. En el stack de siete capas ocupa la capa de observabilidad LLM-aware, y se relaciona con casi todas las demás. Sobre el cluster genérico de referencia que usamos en todo el blog —4×H100 SXM 80 GB (320 GB VRAM agregada), NVLink, 640 GB RAM de sistema, NVMe-oF, red 25/100 GbE— el flujo de telemetría es así:

Tres ideas de esta topología:

Langfuse recibe del OTel Collector, no de la aplicación directamente (en el patrón recomendado). El SDK de la app o vLLM emiten spans con las semantic conventions gen_ai.*; el Collector hace batch, tail-sampling (preserva el 100 % de errores y latencias altas, muestrea el resto) y enriquece con atributos propios (tenant_id, priority_tier); y reparte: las trazas LLM van a Langfuse, los spans de infraestructura a Tempo, las métricas (DCGM de GPU, métricas de vLLM) a Prometheus. Langfuse es un exporter más, no el único destino. Esto está cubierto en detalle en el post de tracing OTel.
Langfuse corre fuera de las GPU. Es un consumidor de CPU, RAM, disco y red —ClickHouse quiere memoria, MinIO quiere disco, Redis quiere CPU para networking— pero no toca la VRAM. En el cluster 4×H100, Langfuse vive en un nodo de CPU (o en los nodos GPU pero con nodeSelector/taints que lo mantengan lejos de los pods de vLLM). Mezclar ClickHouse con vLLM en el mismo nodo sin límites de recursos es pedir que un pico de ingesta robe ancho de banda de memoria a la inferencia. Aislamiento por diseño.
La ruta de telemetría es “fría” y la de datos es “caliente”. El plano de datos (izquierda) sirve tokens con presupuesto de latencia de milisegundos; el plano de telemetría (derecha) tolera segundos. El acuse temprano de la ingesta es lo que mantiene estos dos relojes separados: la app no espera a que Langfuse archive nada para devolver la respuesta al usuario.

Los 10 knobs de backend que más mueven la aguja

Estos son, por orden aproximado de impacto/frecuencia, los ajustes que deciden si tu Langfuse self-hosted ingiere 50 eventos/s o 5.000, y si tu disco crece de forma sostenible o explota en tres semanas. Todos son variables de entorno o config que se inyectan en los contenedores Web y Worker (salvo los de ClickHouse, que van en su config server-side). El detalle canónico está en la doc de scaling de Langfuse.

Knob 1 — Escalar el Worker por carga (la primera palanca, siempre)

El Worker es el componente que se satura primero, porque es quien hace el trabajo caro: leer S3, transformar, mergear, insertar en ClickHouse. La regla operativa de Langfuse es simple: un contenedor Worker de 2 CPU por encima del 50 % de uso de CPU está saturado; añade réplicas. Mejor aún que la CPU, el Worker publica vía statsd la métrica langfuse.queue.ingestion.length (longitud de la cola de ingesta), que es la señal directa para autoescalar: si la cola crece sin drenar, faltan Workers.

# El autoscaler ideal mira la profundidad de cola, no solo CPU.
# (KEDA ScaledObject sobre la métrica statsd → Prometheus)
triggers:
 - type: prometheus
 metadata:
 query: langfuse_queue_ingestion_length
 threshold: "10000" # si la cola pasa de 10k refs, escala

En despliegues AWS existe ENABLE_AWS_CLOUDWATCH_METRIC_PUBLISHING=true para empujar estas métricas a CloudWatch. On-premise, el camino es statsd → Prometheus → KEDA, encajado con el autoscaling en Kubernetes con KEDA que ya cubrimos para vLLM. Empieza siempre por aquí: la mayoría de los problemas de “Langfuse va lento” son simplemente Workers insuficientes, no afinado fino.

Knob 2 — Separar el deployment de ingesta del de UI

Cuando la ingesta va muy cargada, las consultas de la UI y la API pública se vuelven lentas porque comparten el mismo contenedor Web. La solución es partir langfuse-web en dos deployments idénticos y enrutar por path: todo lo que sea /api/public/ingestion*, /api/public/media* y /api/public/otel* va al deployment de ingesta; el resto (UI, API de lectura) al de interfaz.

# Regla de Ingress / gateway
location ~ ^/api/public/(ingestion|media|otel) {
proxy_pass http://langfuse-web-ingest; # réplicas dedicadas a escribir
}
location / {
proxy_pass http://langfuse-web-ui; # réplicas dedicadas a leer
}

Es la misma idea que la separación read/write de cualquier sistema con cargas mixtas: que una tormenta de escrituras no deje sin recursos a quien intenta mirar el dashboard justo durante el incidente —que es precisamente cuando más lo necesitas.

Knob 3 — Batching de escrituras a ClickHouse (interval + batch size)

ClickHouse odia las inserciones pequeñas y frecuentes: cada INSERT crea una part en disco que luego hay que mergear, y miles de inserts diminutos generan miles de parts y una tormenta de background merges que satura el disco. La defensa es acumular en un buffer en memoria del Worker y hacer flush por lotes grandes:

# Worker: menos flushes, lotes más grandes → menos parts, menos merges
LANGFUSE_INGESTION_CLICKHOUSE_WRITE_INTERVAL_MS=1000 # sube p.ej. a 2000-5000
LANGFUSE_INGESTION_CLICKHOUSE_WRITE_BATCH_SIZE=10000 # sube si hay throughput

Subir el intervalo y el tamaño de lote reduce la frecuencia de flushes y mejora el throughput sostenido. El trade-off es directo y hay que entenderlo: lotes más grandes y menos frecuentes significan más datos en el buffer volátil del Worker, es decir, una ventana de pérdida mayor si el Worker se cae (knob acoplado al escepticismo del cierre). Langfuse además usa async_insert de ClickHouse, que acumula server-side antes de confirmar; suma otra capa de buffering a tener presente.

Knob 4 — Saltar la lectura previa a ClickHouse en la ingesta

Por defecto, al ingerir un evento el Worker lee de ClickHouse el evento existente y lo mergea con lo entrante (necesario cuando los SDKs legacy mandan eventos parciales: un start, luego un end, luego un update de la misma observación). Esa lectura por evento carga ClickHouse en la ruta de escritura y limita el throughput total.

Si tus proyectos no vienen migrados de una versión antigua —porque el histórico completo ya vive en S3— puedes desactivar esa lectura:

# Fecha anterior a la creación de tu primer proyecto
LANGFUSE_SKIP_INGESTION_CLICKHOUSE_READ_MIN_PROJECT_CREATE_DATE=2025-01-01

Con los SDKs modernos de Langfuse o con ingesta vía OpenTelemetry, esto no te afecta negativamente y quita una lectura por evento. Aviso de la propia doc: si combinas esto con reglas de borrado (lifecycle) agresivas en S3 más updates tardíos de eventos, puedes generar duplicados en el histórico. Conócelo antes de activarlo.

Knob 5 — Concurrencia de escritura a S3/Blob storage

En escenarios de alto throughput, el cliente de S3 puede agotar sus sockets y empezar a encolar y throttlear escrituras. El síntoma es inconfundible en los logs del contenedor Web que procesa ingesta:

@smithy/node-http-handler:WARN - socket usage at capacity=150
and 387 additional requests are enqueued.

…acompañado de una subida de memoria en ese contenedor (las requests encoladas se acumulan en RAM). La cura es subir el límite de escrituras concurrentes desde su default de 50:

LANGFUSE_S3_CONCURRENT_WRITES=100 # sube gradualmente desde 50

Cada socket adicional tiene un pequeño coste de memoria, así que el consejo oficial es subirlo de forma gradual observando el comportamiento, no saltar a 1000 de golpe.

Knob 6 — Sharding de colas Redis + concurrencia por shard

Si Redis pasa del 90 % de CPU, primero lo obvio: instancia con al menos 4 CPU (para que Redis reparta networking y tareas de fondo en cores distintos) y Redis Cluster mode activado. Si aún así la CPU no baja, se pueden shardear las colas que usa Langfuse:

# Avanzado: solo si Redis va ahogado y ya hiciste lo anterior
LANGFUSE_INGESTION_QUEUE_SHARD_COUNT=6 # ~2-3× nº de shards del cluster Redis
LANGFUSE_TRACE_UPSERT_QUEUE_SHARD_COUNT=6
# La concurrencia cuenta POR SHARD; objetivo ~20 por worker
LANGFUSE_INGESTION_QUEUE_PROCESSING_CONCURRENCY=3 # 6 shards × ~3 ≈ 18
LANGFUSE_TRACE_UPSERT_WORKER_CONCURRENCY=3

Dos trampas que la doc subraya y conviene tatuarse: una vez shardeas, no reduzcas el número de shards (rompe el reparto); y la concurrencia se cuenta por shard, no global —si tienes 10 shards y quieres concurrencia 20 por worker, pon 2, no 20. Es un knob avanzado: la mayoría de despliegues on-premise nunca lo necesitan.

Knob 7 — El modificador `FINAL` para proyectos solo-OTel

Langfuse guarda las observaciones en un ReplacingMergeTree de ClickHouse y, por defecto, añade el modificador FINAL a las consultas de la API para que gane la última versión de cada fila en tiempo de lectura. FINAL es necesario cuando la ingesta produce varias versiones de la misma observación (los SDKs legacy con sus eventos start/end/update), pero añade trabajo de merge en cada lectura y la ralentiza.

Los proyectos que ingieren exclusivamente por OpenTelemetry escriben cada observación como una fila inmutable única, así que FINAL les sobra:

# Recomendado en despliegues mixtos: per-project, marca en Redis con TTL 24h
LANGFUSE_SKIP_FINAL_FOR_OTEL_PROJECTS=true

# Solo si TODOS los proyectos son OTel-only: global, sin lookup en Redis
LANGFUSE_API_CLICKHOUSE_DISABLE_OBSERVATIONS_FINAL=true

Como en el cluster de ejemplo la instrumentación es 100 % OTel (gen_ai.* vía Collector), este knob es dinero gratis en latencia de lectura del dashboard. Cuidado con la versión global: no la actives si algún proyecto sigue usando ingesta legacy, o las lecturas pueden devolver filas duplicadas o stale.

Knob 8 — Separar lecturas analíticas del path de escritura (compute-compute)

Las consultas pesadas del dashboard (percentiles sobre millones de spans) compiten con los inserts de ingesta y con los background merges sobre el mismo ClickHouse. Si tu despliegue soporta separación compute-compute (ClickHouse Cloud o BYOC), puedes enrutar las lecturas a un grupo de cómputo de solo-lectura:

CLICKHOUSE_URL=http://clickhouse-primary:8123 # writes, migraciones, ingesta
CLICKHOUSE_READ_ONLY_URL=http://clickhouse-reader:8123 # lecturas UI + API pública

Matiz crítico para on-premise —y aquí toca ser escéptico con la utilidad de este knob en nuestro contexto: en un ClickHouse single-node o en un cluster self-managed sin separación de cómputo, esta variable no aporta nada, porque el endpoint de lectura sería el mismo que el de escritura. Es un knob para arquitecturas cloud con almacenamiento separado del cómputo. En un cluster 4×H100 on-premise con ClickHouse en un nodo, la alternativa real es escalar ClickHouse verticalmente (la doc recomienda ≥16 GiB de RAM para deployments grandes; ClickHouse escala vertical bien) y asegurar que todas las consultas filtran por projectId y tiempo, que es como están indexadas las tablas. Sin filtro temporal, hasta el ClickHouse más gordo sufre.

Knob 9 — Retención de datos: TTL en ClickHouse + lifecycle en S3

El disco es el coste que crece solo. Las trazas LLM cargan inputs y outputs enteros (a veces prompts de decenas de KB), y ClickHouse además acumula sus propias tablas de sistema. La palanca de primer orden es una política de retención que borra nightly trazas, observaciones, scores y media más viejos que N días, coordinando ClickHouse y blob storage. Donde la feature de retención no esté disponible, se hace a mano:

-- ClickHouse: TTL sobre las tablas de tracing
ALTER TABLE traces MODIFY TTL toDateTime(timestamp) + INTERVAL 90 DAY;
ALTER TABLE observations MODIFY TTL toDateTime(start_time) + INTERVAL 90 DAY;
ALTER TABLE scores MODIFY TTL toDateTime(timestamp) + INTERVAL 90 DAY;
ALTER TABLE event_log MODIFY TTL toDateTime(timestamp) + INTERVAL 30 DAY;

# S3/MinIO: lifecycle rule, p.ej. 30 días para el bucket de eventos crudos
# ¡OJO! NO apliques retención al bucket de MEDIA:
# - rompe los ficheros referenciados en trazas
# - rompe futuras subidas (el estado se trackea por hash en Postgres)

Dos parámetros de operación que evitan sustos en borrados grandes:

LANGFUSE_CLICKHOUSE_DELETION_TIMEOUT_MS=600000 # default 10 min; súbelo si los borrados expiran
# ClickHouse 25.7+: menos presión de mutaciones en borrados masivos
CLICKHOUSE_LIGHTWEIGHT_DELETE_MODE=lightweight_update
CLICKHOUSE_USE_LIGHTWEIGHT_UPDATE=true

La regla mental: retención corta para eventos crudos (S3, 30 días suele bastar — son recuperables/recomputables), retención por valor de negocio para las tablas de ClickHouse (90 días, 180, lo que pida compliance), y nunca toques el bucket de media con lifecycle ciego.

Knob 10 — Higiene de las system log tables de ClickHouse (el asesino silencioso del disco)

Este es el knob que nadie configura y que llena el disco sin que aparezca en ninguna métrica de Langfuse, porque no es dato de Langfuse: son las tablas de sistema del propio ClickHouse (trace_log, text_log, opentelemetry_span_log, asynchronous_metric_log, metric_log, latency_log). Por defecto no tienen TTL, y el query profiler escribe en system.trace_log continuamente. En un ClickHouse con tráfico, estas tablas pueden dominar el uso de disco mientras tú buscas el problema en tus trazas. Langfuse no lee de ellas, así que se pueden recortar sin miedo. Dos opciones:

<!-- Opción A — desactivar las que Langfuse nunca lee
 (fichero en /etc/clickhouse-server/config.d/) -->
<clickhouse>
 <trace_log remove="1"/>
 <text_log remove="1"/>
 <opentelemetry_span_log remove="1"/>
 <asynchronous_metric_log remove="1"/>
 <metric_log remove="1"/>
 <latency_log remove="1"/>
</clickhouse>
<!-- Mantén query_log, part_log y error_log: útiles para debug y pequeños -->

-- Opción B — TTL agresivo + apagar el profiler, si quieres conservarlas para debug
-- (en config: query_profiler_real_time_period_ns = 0)
SET max_table_size_to_drop = 0;
TRUNCATE TABLE system.trace_log;
ALTER TABLE system.trace_log MODIFY TTL event_date + INTERVAL 7 DAY;
-- repetir para cada tabla de log a capar

Para identificar qué tabla se está comiendo el disco, la consulta de oro:

SELECT table, formatReadableSize(sum(bytes)) AS size, sum(rows) AS rows
FROM system.parts WHERE active GROUP BY table ORDER BY sum(bytes) DESC;

Si solo te llevas un knob de este post a tu primer despliegue real, que sea este: la diferencia entre un ClickHouse que crece 2 GB/día de datos útiles y uno que crece 20 GB/día de logs de sistema que nadie mira.

Tabla resumen de los 10 knobs

#	Knob	Variable / acción	Cuándo
1	Escalar Worker	réplicas por CPU>50 % / `langfuse.queue.ingestion.length`	siempre, primero
2	Separar ingesta/UI	enrutar `/ingestion`,`/media`,`/otel*` a réplica dedicada	UI lenta bajo carga
3	Batching a ClickHouse	`LANGFUSE_INGESTION_CLICKHOUSE_WRITE_INTERVAL_MS` / `_BATCH_SIZE`	throughput alto
4	Saltar lectura previa CH	`LANGFUSE_SKIP_INGESTION_CLICKHOUSE_READ_MIN_PROJECT_CREATE_DATE`	proyectos no migrados
5	Concurrencia S3	`LANGFUSE_S3_CONCURRENT_WRITES` (def. 50)	“socket usage at capacity”
6	Sharding colas Redis	`LANGFUSE__QUEUE_SHARD_COUNT` + `_CONCURRENCY` (por shard)	Redis CPU >90 %
7	Quitar `FINAL` (OTel)	`LANGFUSE_SKIP_FINAL_FOR_OTEL_PROJECTS=true`	instrumentación 100 % OTel
8	Read/write split CH	`CLICKHOUSE_READ_ONLY_URL` (solo cloud/BYOC)	compute-compute disponible
9	Retención + TTL	TTL en CH + lifecycle S3 + `LANGFUSE_CLICKHOUSE_DELETION_TIMEOUT_MS`	siempre (coste disco)
10	Higiene system logs CH	`<trace_log remove="1"/>` o TTL agresivo	siempre (disco oculto)

Cómo maximizar Langfuse en el cluster 4×H100 de ejemplo

Con la arquitectura y los knobs claros, este es un dimensionado concreto para sacar el máximo a Langfuse sobre el cluster genérico de referencia (4×H100 SXM, 320 GB VRAM, 640 GB RAM, NVMe-oF, 25/100 GbE), sin robar un solo GB de VRAM a la inferencia.

Reparto de componentes

Langfuse es 100 % carga de CPU/RAM/disco/red, así que su sitio natural es fuera de los nodos GPU o, si se cohabita, con taints/nodeSelector que lo confinen lejos de los pods de vLLM. Reparto sugerido:

nodo-cpu-01 (control + observabilidad, sin GPU)
├── langfuse-web-ingest ×3 (2 CPU / 4 GiB c/u) ← ingesta, escala con carga
├── langfuse-web-ui ×2 (2 CPU / 4 GiB c/u) ← dashboard/API lectura
├── langfuse-worker ×4 (2 CPU / 4 GiB c/u) ← el que más escala
├── redis/valkey ×1 (4 CPU / 4 GiB, cluster mode)
└── postgres ×1 (2 CPU / 8 GiB, réplica para HA)
nodo-storage-01 (estado pesado, NVMe local)
├── clickhouse ×1 (8 CPU / 32 GiB / NVMe) ← ≥16 GiB es el mínimo; 32 holgado
└── minio (S3) ×1 (4 CPU / 8 GiB / HDD+NVMe cache)
nodo-gpu-01..02 (4×H100 SXM cada uno) → SOLO inferencia
└── vLLM, embeddings, reranker, guardrails (emiten spans, no alojan Langfuse)

Dimensionado por carga real

Pongamos números a una carga de ejemplo. Supongamos el cluster sirviendo 300 peticiones/segundo de chat-con-RAG, donde cada petición genera del orden de 8 spans (request, retrieval, rerank, 2× tool, guardrail in, llm, guardrail out):

$$ E = 300,\tfrac{\text{req}}{\text{s}} \times 8,\tfrac{\text{spans}}{\text{req}} = 2.400\ \text{eventos/s} $$

Frente al techo de Redis (~50.000 ops/s), $E = 2.400$ deja la ventanilla de recepción al ~5 % de su capacidad: holgura enorme. El componente a vigilar es el Worker. Con un objetivo de ~20 de concurrencia por Worker y lotes de 10.000 eventos cada ~1-2 s, 4 Workers drenan 2.400 ev/s con margen; la métrica langfuse.queue.ingestion.length debe mantenerse plana cerca de cero. Si crece, el knob 1 (más Workers) es la respuesta antes que cualquier afinado.

Tail-sampling es el multiplicador que cambia la economía. Si el Collector preserva el 100 % de errores/latencias-altas pero muestrea el tráfico normal al, digamos, 10 %, los 2.400 ev/s que almacenas en ClickHouse bajan a ~240-300 ev/s efectivos sin perder la señal que importa. La regla: muestrea en el Collector, no en Langfuse —Langfuse debe recibir ya filtrado lo que merece persistirse. Esto está desarrollado en el post de tracing OTel; aquí basta con notar que el sampling de aguas arriba es, de facto, el knob 0 que multiplica a todos los demás.

Estimación de almacenamiento

Una observación LLM con input+output completos pesa, comprimida en ClickHouse, del orden de 1-3 KB (ClickHouse comprime texto muy bien, 5-10×). Con sampling al 10 % sobre 2.400 ev/s:

$$ 240,\tfrac{\text{ev}}{\text{s}} \times 2,\text{KB} \times 86.400,\tfrac{\text{s}}{\text{día}} \approx 41\ \text{GB/día (cruda)} ;\xrightarrow{\text{compresión}}; \sim 5\text{–}8\ \text{GB/día en CH} $$

A 90 días de retención (knob 9), el archivo permanente se estabiliza en torno a 500-700 GB en ClickHouse —cómodo en el NVMe del nodo de storage— más los eventos crudos en MinIO con lifecycle de 30 días. Sin la higiene de system logs (knob 10), súmale fácilmente otro tanto de basura que nadie consulta. Los dos knobs de disco juntos son la diferencia entre planificar storage una vez al año o pelearte con el disco lleno cada mes.

Checklist de “máximo aprovechamiento”

Sampling en el Collector (tail: 100 % errores + N % normal) — antes de tocar nada en Langfuse.
Workers escalados por longitud de cola vía KEDA (knob 1), no fijos.
Ingesta separada de UI (knob 2) para que el dashboard responda durante incidentes.
SKIP_FINAL_FOR_OTEL_PROJECTS activo (knob 7) porque la instrumentación es 100 % OTel.
Batching CH generoso (knob 3) ajustado al throughput, asumiendo la ventana de pérdida.
Retención + TTL + higiene de system logs (knobs 9 y 10) configurados el día 1, no cuando el disco grite.
ClickHouse con ≥16 GiB y todas las queries filtrando por projectId+tiempo (knob 8 en su versión on-premise: escala vertical).
Langfuse aislado de las GPU por taints/nodeSelector: ni un MB de VRAM, ni contención de ancho de banda de memoria con vLLM.

Trampas y cosas que no son lo que parecen

“Langfuse me garantiza trazabilidad total.” No: el diseño es best-effort de alto rendimiento, no libro contable. Entre el HTTP 207 y la fila en ClickHouse hay buffers volátiles (Redis sin persistencia dura, el buffer en memoria del Worker, el async_insert server-side de ClickHouse). Hay un bug conocido donde el writer descarta filas sin dead-letter queue tras agotar reintentos. Para observabilidad operativa, perder el 0,01 % de spans es irrelevante. Para evidencia de auditoría ENS/EU AI Act —donde la traza es la prueba— Langfuse no debe ser el único registro; el log de auditoría regulatorio necesita garantías de durabilidad que esta tubería no promete. Distinción tratada en los controles técnicos ENS/42001/EU AI Act.

Subir el batching de ClickHouse “para ir más rápido” sin más. El knob 3 mejora throughput a costa de agrandar la ventana de pérdida y la latencia de aparición del dato en el dashboard. Lotes de 50.000 cada 10 s rinden de maravilla… hasta que el Worker se reinicia con 50.000 eventos en el buffer. Ajusta con conciencia del trade-off, no maximizando ciegamente.

Meter ClickHouse en el mismo nodo que vLLM sin límites. ClickHouse es voraz con el ancho de banda de memoria durante los merges. Compartir nodo con vLLM sin resources.limits ni aislamiento NUMA significa que un pico de ingesta puede degradar el TTFT de la inferencia —exactamente el pecado original que toda esta arquitectura quería evitar. Aísla.

Olvidar el filtro temporal en consultas propias. Las tablas de ClickHouse están indexadas por projectId y tiempo. Un dashboard custom o una consulta de la API sin filtro de tiempo escanea todo el histórico y tumba el rendimiento para todos. No es Langfuse que “va lento”: es una query mal escrita.

Aplicar lifecycle al bucket de media. Romper los ficheros referenciados en trazas y bloquear futuras subidas (el estado se trackea por hash en Postgres). El bucket de media se gestiona solo con la feature de retención de Langfuse, nunca con reglas ciegas de S3.

Tratar el sharding de colas como optimización de rutina. Es un knob avanzado para Redis ahogado de verdad, irreversible (no reduzcas shards) y con semántica de concurrencia por shard fácil de malinterpretar. En la inmensa mayoría de despliegues on-premise no hace falta; si lo activas “por si acaso”, te complicas la vida sin ganar nada.

Conclusión

Langfuse v3 resolvió el problema estructural de la observabilidad LLM —que el observador no asfixie al observado— mudándose de un monolito sobre Postgres a un centro de clasificación de seis servicios con ingesta asíncrona. Ese diseño es lo que permite que un cluster sirviendo miles de tokens por segundo se instrumente entero sin que la app espere jamás a que se archive una traza. Pero el diseño es condición necesaria, no suficiente: rinde si se ajustan las palancas correctas. De los diez knobs, tres deciden casi todo en un despliegue on-premise típico —escalar Workers por longitud de cola (1), retención + TTL (9), e higiene de system logs (10)—; el resto son afinados que aparecen cuando la carga aprieta. Y por encima de todos ellos vive el knob 0, que no es de Langfuse: el sampling en el Collector, que decide cuánto llega a la tubería antes de que ningún ajuste interno importe. Maximizar Langfuse en el cluster 4×H100 no es exprimir su throughput pico: es ponerlo fuera de las GPU, alimentarlo con tráfico ya muestreado, dimensionar el Worker por la cola, y configurar la retención el día uno —para que la herramienta que vino a contar la historia no acabe siendo el capítulo del incidente.

Ver también

Tracing LLM con OpenTelemetry GenAI — el pipeline SDK → Collector → backend que alimenta a Langfuse. Allí se trata Langfuse como destino; aquí se abre por dentro. El sampling de dos capas de aquel post es el knob 0 que multiplica a los diez de este.
Prompt versioning con Langfuse y MLflow — la capa de prompt management que vive en Postgres (no en ClickHouse). El prompt_id@version que aquel post propaga como span attribute aterriza en las tablas de tracing descritas aquí.
Evals: la capa después del tracing — los datasets y evaluators de Langfuse se apoyan en este mismo backend; las trazas almacenadas son el input del eval continuo.
El catálogo OSS para LLMOps en seis etapas — la ficha de Langfuse junto a Phoenix y el resto del ecosistema de observabilidad.
El stack de inferencia LLM on-premise en siete capas — dónde encaja Langfuse (capa 5, observabilidad LLM-aware) en el edificio completo y cómo se dimensiona sobre el mismo cluster 4×H100.
Autoescalado de LLMs en Kubernetes con KEDA — el mecanismo concreto para escalar los Workers de Langfuse por langfuse.queue.ingestion.length (knob 1), el mismo patrón que para vLLM.
Controles técnicos: ENS, ISO 42001 y EU AI Act — por qué Langfuse es observabilidad best-effort y no sustituye al log de auditoría regulatorio con garantías de durabilidad.

Referencias

Langfuse, Scaling Langfuse Deployments (doc oficial de sizing y todos los env vars de este post): https://langfuse.com/self-hosting/configuration/scaling.
Langfuse, Self-host Langfuse y Configuration via Environment Variables: https://langfuse.com/self-hosting · https://langfuse.com/self-hosting/configuration.
Langfuse, ClickHouse (self-hosted): https://langfuse.com/self-hosting/deployment/infrastructure/clickhouse.
Langfuse, From Zero to Scale: Langfuse’s Infrastructure Evolution (el porqué del rediseño v2→v3): https://langfuse.com/blog/2024-12-langfuse-v3-infrastructure-evolution.
Langfuse, Migrate v2 to v3 (self-hosted): https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v2-to-v3.
ClickHouse, Langfuse and ClickHouse: A new data stack for modern LLM applications: https://clickhouse.com/blog/langfuse-and-clickhouse-a-new-data-stack-for-modern-llm-applications.
Langfuse, issue #13468 — ClickhouseWriter drops rows after max flush attempts with no DLQ (la ventana de pérdida documentada): https://github.com/langfuse/langfuse/issues/13468.
ClickHouse, TTL for tables and columns: https://clickhouse.com/docs/guides/developer/ttl.
OpenTelemetry, Semantic Conventions for Generative AI (gen_ai.*): https://opentelemetry.io/docs/specs/semconv/gen-ai/.

Batch sizing en vLLM: el grid search de dos horas que vale semanas de hardware

Fri, 05 Jun 2026 04:00:00 +0000

TL;DR

max-num-seqs y max-num-batched-tokens son los dos diales que controlan cuánto trabajo procesa vLLM en cada iteración del scheduler. Sus valores por defecto están calibrados para ser seguros en cualquier hardware, no para maximizar throughput en el tuyo. Un grid search sistemático de 25 configuraciones —ejecutable en dos horas— identifica la combinación que, para tu workload y hardware específico, puede doblar el throughput sin cambiar ninguna línea de modelo ni añadir una GPU. Las métricas OTel que confirman que encontraste el óptimo son vllm:num_waiting_seqs, vllm:num_preemptions_total y vllm:time_per_output_token_seconds.

La analogía

Una cocina industrial con un chef y diez fogones. Si el maitre sólo envía un pedido a la vez, el chef trabaja al 10% de capacidad. Si envía cien pedidos simultáneos pero sólo hay ingredientes para veinte, el chef pasa la mitad del tiempo esperando reposición. El óptimo está en el punto donde todos los fogones están encendidos y el reabastecimiento nunca se agota.

max-num-seqs es cuántos pedidos puede tener el chef en preparación simultánea. max-num-batched-tokens es cuántos ingredientes puede procesar en un solo movimiento de wok. Equivocarse en cualquiera de los dos deja fogones vacíos.

El problema: los defaults no son para tu hardware

En vLLM V1 (≥ 0.6), los defaults son:

max-num-seqs = 1024 (V1) / 256 (V0)
max-num-batched-tokens = 8192

Estos valores garantizan que vLLM arranca en cualquier GPU sin OOM. No garantizan throughput óptimo. La razón: el punto óptimo depende de tres variables que vLLM no conoce al arrancar:

Distribución de longitudes de tu workload real — un sistema de RAG con prompts de 2K tokens necesita un presupuesto distinto al de un chat con mensajes de 50 tokens.
VRAM disponible para KV cache — determinada por el modelo, la cuantización y --gpu-memory-utilization.
Concurrencia real esperada — cuántos usuarios simultáneos llegan en el percentil 95.

La interacción entre estos tres factores hace imposible que un default universal sea óptimo para casos concretos.

Las matemáticas que importan

El scheduler de vLLM en cada iteración decide qué tokens procesar. El presupuesto total disponible por paso es max-num-batched-tokens. Ese presupuesto se reparte entre:

Tokens de decode: 1 por cada request activo en fase de generación. Con 64 requests en decode, se consumen 64 tokens de presupuesto.
Tokens de prefill (en chunks): el resto del presupuesto va al procesamiento de prompts nuevos.

$$\text{tokens_prefill_por_paso} = \text{max_num_batched_tokens} - \text{num_requests_decode}$$

Si max-num-batched-tokens = 8192 y tienes 512 requests en decode, cada paso sólo puede procesar 8192 - 512 = 7680 tokens de prefill. Con prompts de 2000 tokens, eso son ~3.8 prompts nuevos por iteración.

El problema aparece cuando max-num-seqs es muy alto en relación al KV cache disponible. Cada request activo en decode ocupa bloques de KV cache. Si se agotan los bloques, vLLM hace preemption: pausa una request, libera su KV cache y la vuelve a encolar. Cada preemption cuesta latencia adicional al request pausado y complejidad al scheduler.

$$\text{KV_budget} = \frac{\text{VRAM libre} \times \text{gpu_memory_utilization}}{\text{bytes_por_token} \times \text{max_model_len}}$$

Para un Qwen2.5-14B en RTX 4090 con Q4_K_M (9 GB de modelo, 15 GB libres):

$$\text{KV_budget} = \frac{15 \times 0.92 \times 10^9}{40,000} \approx 345,000 \text{ tokens}$$

Con max-model-len = 8192, el número máximo de requests simultáneos con contexto completo es:

$$\text{max_seqs_real} = \frac{345,000}{8192} \approx 42 \text{ requests}$$

Configurar max-num-seqs = 1024 con esos números garantiza preemptions constantes. El óptimo está en 40-50.

El grid search: metodología

Paso 1: medir el workload real

Antes de buscar el óptimo, hay que conocer los percentiles de tu tráfico. Desde Langfuse o los logs de vLLM:

# Extraer distribución de longitudes desde Langfuse
import langfuse
client = langfuse.Langfuse()

traces = client.fetch_traces(limit=1000).data
prompt_lens = [t.input_tokens for t in traces if t.input_tokens]
output_lens = [t.output_tokens for t in traces if t.output_tokens]

import numpy as np
print(f"Prompt p50={np.percentile(prompt_lens,50):.0f} p95={np.percentile(prompt_lens,95):.0f} p99={np.percentile(prompt_lens,99):.0f}")
print(f"Output p50={np.percentile(output_lens,50):.0f} p95={np.percentile(output_lens,95):.0f} p99={np.percentile(output_lens,99):.0f}")

Paso 2: calcular el KV budget

Ejecutar una vez con --dry-run o leer el log de arranque de vLLM:

INFO: # GPU blocks: 4521, # CPU blocks: 512

Cada bloque son 16 tokens. 4521 × 16 = 72.336 tokens de KV budget total.

Paso 3: el grid

Con el KV budget conocido y el p95 de longitud de prompt/output:

# grid_search_batch.py
import subprocess, json, time

MODEL = "Qwen/Qwen2.5-14B-Instruct-AWQ"
PROMPT_LEN = 512 # p50 de tu workload
OUTPUT_LEN = 256
CONCURRENCY = 32 # usuarios simultáneos esperados en pico

seqs_values = [32, 64, 128, 256, 512]
tokens_values = [4096, 8192, 16384, 32768, 65536]

results = []
for seqs in seqs_values:
 for tokens in tokens_values:
 cmd = [
 "python", "-m", "vllm.entrypoints.benchmark_throughput",
 "--model", MODEL,
 "--max-num-seqs", str(seqs),
 "--max-num-batched-tokens", str(tokens),
 "--num-prompts", "200",
 "--input-len", str(PROMPT_LEN),
 "--output-len", str(OUTPUT_LEN),
 ]
 out = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
 # Parsear throughput de la salida
 for line in out.stdout.splitlines():
 if "Throughput" in line:
 tps = float(line.split(":")[1].strip().split()[0])
 results.append({"seqs": seqs, "tokens": tokens, "tps": tps})
 print(f"seqs={seqs} tokens={tokens} → {tps:.1f} tok/s")

# Guardar para análisis
with open("grid_results.json", "w") as f:
 json.dump(results, f, indent=2)

25 configuraciones × ~5 min = ~2 horas. Tiempo real de ejecución, no de espera.

Paso 4: interpretar la superficie

El resultado es una matriz 5×5 de throughput. La forma típica:

max-num-batched-tokens → 4K 8K 16K 32K 64K
max-num-seqs ↓
32 180 310 380 390 385 ← max-num-seqs demasiado bajo
64 185 350 480 510 508 ← punto óptimo para este workload
128 182 340 450 480 475
256 178 320 400 410 402 ← KV cache se agota, preemptions
512 170 290 360 370 368 ← preemptions altas

El óptimo en este ejemplo: max-num-seqs=64, max-num-batched-tokens=32768. Por encima, las preemptions cancean la ganancia de concurrencia.

Confirmación con OTel

Una vez desplegada la configuración óptima, tres métricas de Prometheus confirman que está bien calibrada:

# 1. Requests en cola — debe mantenerse cerca de 0
# Si crece sostenido: max-num-seqs demasiado bajo o max-num-batched-tokens insuficiente
vllm:num_waiting_seqs

# 2. Preemptions — debe ser 0 o muy ocasional (<1/min)
# Si crece: max-num-seqs demasiado alto para el KV cache disponible
rate(vllm:num_preemptions_total[5m]) * 60

# 3. ITL (inter-token latency) — debe ser estable, sin picos
# Bimodalidad = batch size mal calibrado (algunos requests fuera del CUDA graph bucket)
histogram_quantile(0.99, rate(vllm:time_per_output_token_seconds_bucket[5m]))

La configuración óptima produce:

num_waiting_seqs ≈ 0 en régimen normal
num_preemptions_total estable (no crece)
time_per_output_token unimodal

Si num_waiting_seqs es alto con gpu_cache_usage_perc bajo: aumentar max-num-batched-tokens para procesar prefills más rápido. Si num_preemptions_total crece: bajar max-num-seqs o activar FP8 KV cache para liberar bloques.

Configuraciones de referencia por perfil

Basadas en el grid search para hardware mediano (4×H100 genérico, modelo 14B-70B):

Perfil	Prompt p50	Output p50	max-num-seqs	max-num-batched-tokens
Chat conversacional	150 tok	300 tok	256	16384
RAG enterprise	1500 tok	200 tok	64	32768
Coding (completion)	800 tok	500 tok	128	32768
Summarización	2500 tok	400 tok	32	65536
Batch procesamiento	4000 tok	800 tok	16	65536

Ninguna de estas es universal. Son puntos de partida para el grid search en tu hardware y workload real.

Cuándo no tocar los defaults

Si tu sistema está por debajo del 50% de utilización de KV cache (vllm:gpu_cache_usage_perc < 0.50) con demanda real y sin num_waiting_seqs, los defaults son suficientes para tu carga actual. El grid search aporta más cuando estás cerca de la capacidad máxima o cuando quieres extraer el rendimiento completo de un hardware fijo.

Ver también

https://blog.lo0.es/posts/prefill-optimizaciones-vllm/ — max-num-batched-tokens es el presupuesto que chunked prefill usa para intercalar decode; este artículo cubre el tuning de ese parámetro
https://blog.lo0.es/posts/decode-optimizaciones-vllm/ — max-num-seqs interactúa directamente con gpu-memory-utilization y la capacidad de KV cache para decode
https://blog.lo0.es/posts/vllm-otel-instrumentacion-optimizaciones/ — las métricas num_waiting_seqs, num_preemptions_total y time_per_output_token configuradas en el pipeline OTel completo
https://blog.lo0.es/posts/kv-cache-fundamentos/ — la fórmula del KV budget que determina el máximo real de max-num-seqs para tu hardware
https://blog.lo0.es/posts/capacity-planning-inferencia-llm-on-premise/ — el sizing de hardware parte del throughput óptimo que este grid search determina

En esta misma serie

https://blog.lo0.es/posts/prefix-cache-hit-rate-engineering/ — la segunda optimización gratis: pasar el hit rate de prefix cache del 15% al 75%
https://blog.lo0.es/posts/fp8-end-to-end-pesos-kv-calidad/ — FP8 en pesos y KV cache: +40-60% throughput medido antes y después con eval suite
https://blog.lo0.es/posts/tp-replicas-una-grande-vs-n-pequenas/ — TP=4×1 vs TP=2×2: cuándo el punto de cruce cambia la decisión de plataforma

Referencias

FP8 end-to-end: activar, medir calidad y decidir con datos

Fri, 05 Jun 2026 04:00:00 +0000

TL;DR

FP8 es el cambio de configuración con mayor impacto por esfuerzo disponible en hardware H100 y Ada Lovelace. En H100, activa tensor cores FP8 nativos: +40-60% throughput en decode y ×2 VRAM disponible para KV cache. En RTX 4090 y L40, el beneficio de compute es menor pero el ×2 VRAM es real y se traduce directamente en el doble de concurrencia. El riesgo es la degradación de calidad, que en modelos modernos bien calibrados es <0.5% en benchmarks estándar pero puede ser mayor en razonamiento formal. El workflow correcto no es activar y rezar: es activar en staging, correr la eval suite, correlacionar calidad con throughput en OTel, y decidir con datos.

La analogía

Un fotógrafo que trabaja con negativos de 35 mm y pasa a digital. Las fotos digitales ocupan menos espacio y se procesan más rápido. Pero una foto de baja resolución de un paisaje puede ser indistinguible de la de alta resolución para el ojo humano, mientras que una foto de texto en baja resolución pierde letras. El mismo trade-off exacto aplica a FP8: para tareas donde la imprecisión numérica se promedía sobre miles de activaciones (conversación, resumen, RAG), es prácticamente invisible. Para tareas donde una sola multiplicación errónea propaga una respuesta incorrecta (matemáticas formales, código crítico), puede ser determinante.

Las tres capas de FP8 en vLLM

FP8 no es un único flag: son tres capas independientes que se activan por separado y tienen beneficios distintos.

Capa 1 — Pesos del modelo (--quantization fp8): Los pesos del modelo se almacenan y se calculan en FP8 E4M3. Los modelos deben estar pre-cuantizados (disponibles en HuggingFace con sufijo -FP8 o -fp8) o cuantizarse en tiempo de carga con calibración. El beneficio: el modelo ocupa la mitad de VRAM y los matmuls de pesos son 2× más rápidos en H100.

# Modelo pre-cuantizado (recomendado para producción)
vllm serve neuralmagic/Meta-Llama-3.1-70B-Instruct-FP8 \
 --quantization fp8

# O cuantización on-the-fly (sin archivos adicionales, algo más lento en primeros tokens)
vllm serve meta-llama/Meta-Llama-3.1-70B-Instruct \
 --quantization fp8 \
 --kv-cache-dtype auto

Capa 2 — KV cache (--kv-cache-dtype fp8): Los tensores K y V del KV cache se almacenan en FP8 en vez de BF16. Reduce el tamaño del KV cache a la mitad, duplicando el número de tokens que caben en VRAM. No afecta a los pesos del modelo.

vllm serve mi-modelo \
 --kv-cache-dtype fp8 \
 --calculate-kv-scales # calibración dinámica, obligatorio para minimizar degradación

Capa 3 — Activaciones (automático en H100): En GPUs Hopper, vLLM activa automáticamente FP8 para las activaciones intermedias cuando ambas capas anteriores están activas. No requiere flag adicional.

Configuración completa para producción:

vllm serve neuralmagic/Meta-Llama-3.1-70B-Instruct-FP8 \
 --quantization fp8 \
 --kv-cache-dtype fp8 \
 --calculate-kv-scales \
 --gpu-memory-utilization 0.92 \
 --max-model-len 16384

El impacto medible por hardware

H100 SXM (Hopper, tensor cores FP8 nativos)

Métrica	BF16 baseline	FP8 activado	Delta
Throughput decode (tok/s, 70B, batch 32)	~1.800	~2.700	+50%
VRAM modelo (70B)	140 GB	70 GB	−50%
VRAM KV cache disponible (en 4×H100)	180 GB	250 GB	+39%
Concurrencia máxima (ctx 8K)	~22.500 tok	~31.250 tok	+39%

Esto equivale a una réplica adicional gratis en términos de capacidad de KV cache.

RTX 4090 (Ada Lovelace, FP8 CUDA pero sin tensor cores dedicados)

Métrica	BF16/Q4 baseline	FP8 KV cache añadido	Delta
Throughput decode (tok/s, 14B Q4)	~45	~47	+4%
VRAM KV cache disponible	15 GB	15 GB (modelo igual)	—
Tokens totales de cache (ctx 8K)	~46.000	~92.000	+100%
Concurrencia máxima (ctx 8K)	~5 usuarios	~11 usuarios	+120%

En Ada, el beneficio de compute es menor (los tensor cores FP8 no tienen el mismo ancho que en Hopper), pero el ×2 en capacidad de KV cache es completamente real y se traduce en el doble de usuarios concurrentes posibles.

El workflow correcto: activar, medir, decidir

Activar FP8 directamente en producción sin validar calidad es inadecuado. El workflow correcto tiene cuatro pasos.

Paso 1: baseline en staging

Antes de activar FP8, registrar las métricas de calidad del modelo BF16 actual. La forma más reproducible es correr una eval suite sobre un dataset fijo y guardar los resultados:

# Instalar lm-evaluation-harness
pip install lm-eval

# Baseline BF16
lm_eval --model vllm \
 --model_args pretrained=meta-llama/Meta-Llama-3.1-70B-Instruct,dtype=bfloat16 \
 --tasks mmlu,hellaswag,gsm8k \
 --num_fewshot 5 \
 --output_path ./results/baseline_bf16.json

Paso 2: activar FP8 y correr la misma eval suite

# FP8
lm_eval --model vllm \
 --model_args pretrained=neuralmagic/Meta-Llama-3.1-70B-Instruct-FP8,quantization=fp8,kv_cache_dtype=fp8,calculate_kv_scales=true \
 --tasks mmlu,hellaswag,gsm8k \
 --num_fewshot 5 \
 --output_path ./results/fp8_full.json

Paso 3: calcular la degradación

# compare_eval.py
import json

with open("results/baseline_bf16.json") as f:
 baseline = json.load(f)
with open("results/fp8_full.json") as f:
 fp8 = json.load(f)

tasks = ["mmlu", "hellaswag", "gsm8k"]
print(f"{'Task':<15} {'BF16':>8} {'FP8':>8} {'Delta':>8} {'OK?':>6}")
print("-" * 50)
for task in tasks:
 b = baseline["results"][task]["acc,none"]
 f = fp8["results"][task]["acc,none"]
 delta = (f - b) / b * 100
 ok = "✓" if abs(delta) < 1.0 else "✗ REVISAR"
 print(f"{task:<15} {b:>8.3f} {f:>8.3f} {delta:>+7.1f}% {ok:>6}")

Umbrales de decisión documentados en MLPerf Inference 2025:

< 0.5% degradación: activar en producción sin restricciones.
0.5% – 1.5%: activar con monitorización activa de calidad via LLM-as-judge.
> 1.5%: investigar antes de activar — posible problema de calibración o modelo incompatible.

Paso 4: eval de dominio con LLM-as-judge

Los benchmarks académicos miden lo que miden. Tu caso de uso puede ser diferente. Añadir 200 muestras representativas de tu dominio evaluadas por un juez LLM cierra el gap:

# domain_eval.py
from langfuse import Langfuse
from openai import OpenAI

client = Langfuse()
judge = OpenAI(base_url="http://judge-llm:8000/v1", api_key="token")

# Cargar las 200 muestras de producción curadas (prompt + respuesta esperada)
samples = load_domain_samples("eval_dataset_200.json")

scores_bf16, scores_fp8 = [], []
for sample in samples:
 for model_type, endpoint in [("bf16", "http://staging-bf16:8000"), ("fp8", "http://staging-fp8:8000")]:
 response = call_model(endpoint, sample["prompt"])
 score = judge.chat.completions.create(
 model="Qwen/Qwen2.5-72B-Instruct",
 messages=[{
 "role": "user",
 "content": f"Evalúa esta respuesta del 1 al 5 según precisión y completitud.\nPregunta: {sample['prompt']}\nRespuesta esperada: {sample['expected']}\nRespuesta modelo: {response}\n\nResponde solo con un número del 1 al 5."
 }]
 ).choices[0].message.content.strip()

 if model_type == "bf16":
 scores_bf16.append(int(score))
 else:
 scores_fp8.append(int(score))

import numpy as np
print(f"Score medio BF16: {np.mean(scores_bf16):.2f}")
print(f"Score medio FP8: {np.mean(scores_fp8):.2f}")
print(f"Degradación: {(np.mean(scores_fp8)-np.mean(scores_bf16))/np.mean(scores_bf16)*100:.1f}%")

Correlación OTel + Langfuse: el dashboard que decide

El momento de la decisión se apoya en un único dashboard con dos señales en el mismo eje temporal:

Señal 1 — Throughput (Prometheus):

rate(vllm:generation_tokens_total[5m])

Señal 2 — Calidad media (Langfuse → Prometheus via exporter):

# Si has configurado Langfuse con scores exportados via OTel
langfuse_score_value{name="llm_judge_domain"}

El patrón esperado después de activar FP8: el throughput sube un 40-60% y la calidad se mantiene dentro de ±0.1 puntos. Si la calidad cae más de 0.3 puntos y permanece baja, hay un problema real.

# Alerta: calidad cae más de 0.2 puntos sostenidos tras el cambio
ALERT FP8CalidadDegradada
 IF avg_over_time(langfuse_score_value{name="llm_judge_domain"}[30m])
 < (avg_over_time(langfuse_score_value{name="llm_judge_domain"}[1d] offset 2h) - 0.2)
 FOR 15m
 LABELS { severity = "warning" }
 ANNOTATIONS { summary = "Posible degradación de calidad tras cambio de configuración FP8" }

Cuándo NO activar FP8

FP8 no es siempre la respuesta correcta. Los casos donde la degradación supera el umbral aceptable:

Razonamiento matemático formal: GSM8K y MATH son los benchmarks más sensibles a FP8. Si tu caso de uso es resolución de problemas matemáticos o cálculo financiero preciso, medir específicamente en estos benchmarks antes de activar.

Código crítico con tests: la precisión numérica afecta a la probabilidad de los tokens en posiciones clave de una función. El riesgo no es que el código “parezca” malo, sino que pase tests superficiales pero tenga bugs sutiles.

Contextos muy largos sin --calculate-kv-scales: sin calibración dinámica de escalas, el error numérico acumulado en el KV cache crece con el contexto. Con --calculate-kv-scales activo, el impacto es mínimo hasta 32K tokens.

Modelos pequeños (<7B): el overhead de conversión FP8 puede superar el beneficio de throughput. El punto de equilibrio está alrededor de 7B parámetros.

Ver también

https://blog.lo0.es/posts/quantization-fundamentos-inferencia/ — la matemática de FP8 E4M3: qué es el exponente de 4 bits y la mantisa de 3 bits, y por qué este formato específico fue elegido sobre INT8
https://blog.lo0.es/posts/kv-cache-fundamentos/ — la fórmula del tamaño del KV cache: por qué pasar a FP8 lo divide exactamente por dos
https://blog.lo0.es/posts/decode-optimizaciones-vllm/ — --kv-cache-dtype fp8 y --calculate-kv-scales en el contexto del tuning completo del decode
https://blog.lo0.es/posts/vllm-otel-instrumentacion-optimizaciones/ — cómo configurar la correlación Langfuse + Prometheus en un solo dashboard para el before/after de FP8
https://blog.lo0.es/posts/evals-llm-la-capa-despues-de-tracing/ — la eval suite completa: cómo construir el dataset de dominio de 200 muestras y el juez LLM que verifica la calidad

En esta misma serie

https://blog.lo0.es/posts/batch-sizing-vllm-grid-search/ — el grid search de max-num-seqs × max-num-batched-tokens: la optimización gratis con mayor impacto antes de tocar la cuantización
https://blog.lo0.es/posts/prefix-cache-hit-rate-engineering/ — ingeniería del hit rate de prefix cache: pasar del 15% al 75% sin añadir hardware
https://blog.lo0.es/posts/tp-replicas-una-grande-vs-n-pequenas/ — TP=4×1 vs TP=2×2: la decisión arquitectónica que determina cómo escalar lo que FP8 libera

Referencias

Instrumentar vLLM con OTel: medir lo que las optimizaciones realmente hacen

Fri, 05 Jun 2026 04:00:00 +0000

TL;DR

vLLM expone dos señales de observabilidad independientes: métricas Prometheus (pull, agregadas) y trazas OTel (push, por request). Para medir si chunked prefill, prefix caching, speculative decoding, KV cache FP8 y la concurrencia realmente están funcionando, necesitas ambas. Las métricas dicen qué está pasando en el sistema; las trazas dicen por qué un request concreto fue lento. Este artículo configura el pipeline completo y mapea cada optimización a su métrica diagnóstica.

La analogía

Un piloto de Fórmula 1 y sus ingenieros de telemetría. El piloto siente que el coche “va raro” en la curva 3, pero sin los datos de los sensores no sabe si es el neumático trasero, el diferencial o el combustible. Los ingenieros ven exactamente qué pasó en ese giro, temperatura por sensor, carga lateral por milisegundo.

vLLM sin OTel es el piloto solo: notas que el TTFT “parece alto” pero no sabes si es el prefill largo, un miss de prefix cache, o una preemption de KV cache. Con OTel tienes el cuadro completo: las métricas son el resumen de carrera (aggregated), las trazas son la telemetría vuelta a vuelta (per-request).

Arquitectura de las dos señales

vLLM separa intencionalmente sus dos canales de observabilidad:

 ┌─────────────────────────────┐
│ vLLM │
│ │
requests ────────────►│ SchedulerStats │
│ │ │
│ ├─► Prometheus /metrics │◄── scrape (pull)
│ │ (agregado, ~15s) │
│ │ │
│ └─► OTLP exporter │──► push (por request)
│ (spans, inmediato) │
└─────────────────────────────┘
│ OTLP gRPC/HTTP
▼
┌─────────────────────┐
│ OTel Collector │
│ │
│ receivers: │
│ otlp (traces) │
│ prometheus │
│ exporters: │
│ langfuse │
│ prometheus remote│
│ loki (logs) │
└─────────────────────┘

Prometheus pull expone métricas con prefijo vllm: en :8000/metrics. Son histogramas, gauges y contadores actualizados cada iteración del scheduler. Buenos para dashboards y alertas sobre el sistema completo.

OTLP push envía un span por cada request, inmediatamente al completarse. Contiene atributos del request concreto: tokens de prompt, tokens generados, TTFT, modelo. Bueno para debuggear requests anómalos y para Langfuse.

Instalación y configuración básica

# vLLM con soporte OTel
pip install "vllm[otel]"
# Instala: opentelemetry-sdk, opentelemetry-api,
# opentelemetry-exporter-otlp, opentelemetry-semantic-conventions-ai

# Arrancar vLLM con OTel habilitado
export OTEL_SERVICE_NAME="vllm-produccion"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://otel-collector:4317"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_TRACES_INSECURE="true" # en red interna sin TLS

vllm serve Qwen/Qwen2.5-7B-Instruct \
 --otlp-traces-endpoint http://otel-collector:4317 \
 --enable-chunked-prefill \
 --enable-prefix-caching \
 --kv-cache-dtype fp8 \
 --speculative-model Qwen/Qwen2.5-0.5B-Instruct \
 --num-speculative-tokens 5

Las métricas Prometheus no requieren configuración extra: siempre están en :8000/metrics.

OTel Collector: configuración mínima

# otel-collector-config.yaml
receivers:
 otlp:
 protocols:
 grpc:
 endpoint: 0.0.0.0:4317
 http:
 endpoint: 0.0.0.0:4318

 prometheus:
 config:
 scrape_configs:
 - job_name: vllm
 scrape_interval: 15s
 static_configs:
 - targets: ["vllm:8000"]

processors:
 batch:
 timeout: 5s
 resource:
 attributes:
 - key: deployment.environment
 value: "produccion"
 action: upsert

exporters:
 otlphttp/langfuse:
 endpoint: "https://cloud.langfuse.com/api/public/otel"
 headers:
 Authorization: "Basic <base64(pk:sk)>"

 prometheusremotewrite:
 endpoint: "http://prometheus:9090/api/v1/write"

service:
 pipelines:
 traces:
 receivers: [otlp]
 processors: [batch, resource]
 exporters: [otlphttp/langfuse]
 metrics:
 receivers: [prometheus]
 processors: [batch]
 exporters: [prometheusremotewrite]

Las cinco métricas que importan

Cada optimización tiene una señal diagnóstica primaria. Si la métrica no se mueve como se espera después de activar el flag, hay un problema de configuración o de carga.

1. Chunked prefill → `vllm:time_to_first_token_seconds`

Chunked prefill debería reducir la varianza del TTFT, no necesariamente la mediana. Su objetivo principal es que los percentiles altos (p99) bajen aunque el p50 suba ligeramente.

# TTFT p50 y p99 — esperar que p99 baje con chunked prefill activo
histogram_quantile(0.50, rate(vllm:time_to_first_token_seconds_bucket[5m]))
histogram_quantile(0.99, rate(vllm:time_to_first_token_seconds_bucket[5m]))

Señal de que funciona: ratio p99/p50 se acerca a 1. Sin chunked prefill, un prefill largo de un request bloquea todos los demás y el p99 sube desproporcionadamente.

Señal de problema: p50 y p99 ambos suben. --max-num-batched-tokens demasiado bajo hace que los chunks sean tan pequeños que el prefill tarda muchos pasos en completarse aunque las demás requests no se bloqueen. Subir el budget.

También útil observar en las trazas OTel el atributo llm.usage.prompt_tokens por span: los requests con muchos tokens de prompt deberían tener TTFT proporcional, no bloqueante.

2. Prefix caching → `vllm:gpu_prefix_cache_hit_rate`

# Hit rate del prefix cache en GPU (0.0–1.0)
vllm:gpu_prefix_cache_hit_rate

# Evolución en ventana de 5 minutos
rate(vllm:gpu_prefix_cache_hit_rate[5m])

Señal de que funciona: hit rate sostenido > 0.5 en workloads con system prompt compartido. Con hit rate = 0.8, el 80% de los requests omite el prefill del prefijo; el TTFT de esos requests cae al coste del sufijo variable únicamente.

Señal de problema: hit rate cercano a cero pese a system prompts que “parecen” iguales. Causas habituales:

# ❌ Esto rompe el hash de prefix caching:
system_prompt = f"Hoy es {datetime.now()}. Eres un asistente..."
# ^^^ timestamp diferente en cada request

# ✅ El system prompt debe ser idéntico byte a byte:
system_prompt = "Eres un asistente especializado en infraestructura..."

Cualquier variación en el system prompt —timestamps, IDs de sesión, versiones de prompt interpoladas— produce un hash distinto y un miss de caché. Las trazas OTel no exponen directamente el hit/miss por request en la implementación actual; úsalas para correlacionar llm.usage.prompt_tokens alto con TTFT alto en el mismo request.

3. Speculative decoding → `vllm:spec_decode_draft_acceptance_rate`

# Acceptance rate del draft model (0.0–1.0)
vllm:spec_decode_draft_acceptance_rate

# Speedup efectivo estimado (con k=5 tokens propuestos)
# speedup ≈ (1 + α·k) / (1 + overhead_draft)
# Simplificado: si α=0.75 y k=5 → speedup ≈ 1 + 0.75×5×(1 - cost_ratio)

Señal de que funciona: acceptance rate > 0.70 sostenido. Por debajo de 0.60, el overhead del draft model supera la ganancia de los tokens aceptados y el speculative decoding es contraproducente.

Señal de problema: acceptance rate < 0.50. Causas habituales:

Drafter de familia distinta al verifier (p.ej., Mistral 0.5B como draft de Qwen 7B).
Temperatura de generación alta (>0.9): a mayor temperatura, más diverge la distribución del draft de la del verifier.
Batch muy grande: a alta concurrencia, el draft puede quedar fuera del dominio de los requests actuales.

# Alerta: speculative decoding ineficiente
ALERT SpecDecodeIneficiente
 IF vllm:spec_decode_draft_acceptance_rate < 0.60
 FOR 5m
 LABELS { severity = "warning" }
 ANNOTATIONS { summary = "Draft acceptance rate bajo: desactivar spec decode o cambiar drafter" }

En las trazas OTel, el span completo del request incluye el tiempo total de decode. Sin acceptance rate por span, la forma de detectar spec decode funcionando es comparar el tiempo total de decode dividido por los tokens generados: si es significativamente menor que el baseline sin spec decode, está ayudando.

4. KV cache FP8 y concurrencia → `vllm:gpu_cache_usage_perc` + `vllm:num_preemptions_total`

Estas dos métricas son las dos caras de la gestión del KV cache:

# Utilización del KV cache (0.0–1.0)
# Con FP8 activo, el mismo hardware soporta más requests antes de saturar
vllm:gpu_cache_usage_perc

# Preemptions acumuladas (contador)
# Sube cuando vLLM no puede alojar más requests y pausa alguna
rate(vllm:num_preemptions_total[5m])

Señal de que FP8 funciona: con --kv-cache-dtype fp8 activo, gpu_cache_usage_perc debería saturar a niveles de concurrencia ~2× superiores respecto al baseline BF16 antes de que num_preemptions_total empiece a crecer.

Señal de problema: num_preemptions_total crece en tasas > 1/minuto con gpu_cache_usage_perc por debajo de 0.90. Indica que max-num-seqs está demasiado alto para el KV cache disponible: las requests entran al sistema pero no hay bloques libres para asignarles. Bajar max-num-seqs o reducir max-model-len.

# Alerta: KV cache saturado con preemptions
ALERT KVCacheSaturado
 IF rate(vllm:num_preemptions_total[2m]) > 0.5
 AND vllm:gpu_cache_usage_perc > 0.85
 FOR 3m
 LABELS { severity = "critical" }
 ANNOTATIONS { summary = "KV cache saturado: bajar max-num-seqs o max-model-len" }

El impacto del FP8 en la capacidad se puede cuantificar:

$$\Delta\text{capacity} = \frac{\text{tokens_max_FP8}}{\text{tokens_max_BF16}} \approx 2\times$$

Medir antes y después de activar --kv-cache-dtype fp8: el nivel de gpu_cache_usage_perc para una concurrencia dada debería caer a la mitad.

5. Concurrencia efectiva → `vllm:num_running_seqs` + `vllm:num_waiting_seqs`

# Requests activos en el motor (decode + prefill en curso)
vllm:num_running_seqs

# Requests en cola esperando slot
vllm:num_waiting_seqs

# Ratio de espera: si > 0.2 sostenido, hay cuello de concurrencia
vllm:num_waiting_seqs / (vllm:num_running_seqs + vllm:num_waiting_seqs)

Señal saludable: num_running_seqs estable cerca del valor de --max-num-seqs configurado, num_waiting_seqs bajo (< 10% de running).

Señal de problema: num_waiting_seqs elevado con gpu_cache_usage_perc bajo. Indica que el scheduler no está llenando los slots disponibles porque max-num-batched-tokens es demasiado bajo: el budget de tokens por paso no permite procesar los prefills pendientes rápido enough. Subir max-num-batched-tokens.

Dashboard de referencia: las 5 métricas en Grafana

{
 "panels": [
 {
 "title": "TTFT p50 / p99 (chunked prefill)",
 "targets": [
 {"expr": "histogram_quantile(0.50, rate(vllm:time_to_first_token_seconds_bucket[5m]))", "legendFormat": "p50"},
 {"expr": "histogram_quantile(0.99, rate(vllm:time_to_first_token_seconds_bucket[5m]))", "legendFormat": "p99"}
 ]
 },
 {
 "title": "Prefix cache hit rate",
 "targets": [{"expr": "vllm:gpu_prefix_cache_hit_rate", "legendFormat": "GPU hit rate"}]
 },
 {
 "title": "Spec decode acceptance rate",
 "targets": [{"expr": "vllm:spec_decode_draft_acceptance_rate", "legendFormat": "acceptance rate"}]
 },
 {
 "title": "KV cache usage + preemptions",
 "targets": [
 {"expr": "vllm:gpu_cache_usage_perc", "legendFormat": "cache uso"},
 {"expr": "rate(vllm:num_preemptions_total[2m]) * 60", "legendFormat": "preemptions/min"}
 ]
 },
 {
 "title": "Concurrencia efectiva",
 "targets": [
 {"expr": "vllm:num_running_seqs", "legendFormat": "running"},
 {"expr": "vllm:num_waiting_seqs", "legendFormat": "waiting"}
 ]
 }
 ]
}

Conectar trazas a Langfuse

Las trazas OTel de vLLM son spans GenAI semconv compatibles. Langfuse los acepta directamente via OTLP:

# En el OTel Collector (ya configurado arriba)
# El exporter otlphttp/langfuse envía trazas a Langfuse Cloud o self-hosted

# Para Langfuse self-hosted (ENS/soberano):
exporters:
 otlphttp/langfuse:
 endpoint: "http://langfuse-interno:3000/api/public/otel"
 headers:
 Authorization: "Basic <base64(pk_xxx:sk_xxx)>"

En Langfuse, cada request de vLLM aparece como una traza con:

gen_ai.system: modelo servido
gen_ai.usage.input_tokens: tokens de prompt
gen_ai.usage.output_tokens: tokens generados
Duración del span: latencia end-to-end

Lo que no aparece directamente en el span: acceptance rate de speculative decoding, prefix cache hit/miss, ni número de preemptions. Esos datos sólo están en Prometheus. El workflow correcto es:

Langfuse identifica un request anómalo por latencia.
Prometheus/Grafana muestra si en ese intervalo hubo preemptions elevadas, spec decode bajo, o prefix cache miss.
Se correlacionan por timestamp.

Matriz de diagnóstico rápido

Síntoma observable	Métrica Prometheus	Causa probable	Acción
TTFT p99 muy alto	`ttft p99/p50 >> 2`	Prefills largos bloqueantes	Subir `--max-num-batched-tokens`
TTFT p50 alto, p99 idem	`ttft p50 > 500ms`	Prefix cache no funciona	Verificar hash del system prompt
Decode lento sin mejora	`spec_decode_acceptance < 0.60`	Drafter incompatible	Cambiar drafter o desactivar
OOM / crash esporádico	`gpu_cache_usage_perc = 1.0` + preemptions	KV cache lleno	Bajar `max-num-seqs` o activar FP8
Cola alta con cache libre	`waiting >> 0` + `cache < 0.70`	Budget de tokens bajo	Subir `--max-num-batched-tokens`

Implicaciones para inferencia on-premise soberana

En un despliegue ENS donde no puedes usar Langfuse Cloud ni DataDog, el stack self-hosted completo es:

# docker-compose.yml (o manifests K8s equivalentes)
services:
 otel-collector:
 image: otel/opentelemetry-collector-contrib:latest
 volumes: [./otel-config.yaml:/etc/otel/config.yaml]

 langfuse:
 image: langfuse/langfuse:latest
 environment:
 DATABASE_URL: postgres://...

 prometheus:
 image: prom/prometheus:latest

 grafana:
 image: grafana/grafana:latest

Todo el pipeline corre on-premise. Las trazas nunca salen del perímetro. El cumplimiento ENS no depende de qué observabilidad eliges: depende de que los datos de inferencia no salgan a terceros. Con stack local, ambas condiciones se cumplen.

Ver también

https://blog.lo0.es/posts/tracing-llm-otel-genai/ — los fundamentos de OTel GenAI semconv: qué son los spans, los atributos estándar y cómo fluyen desde el SDK al collector
https://blog.lo0.es/posts/prefill-optimizaciones-vllm/ — las optimizaciones de prefill que este artículo instrumenta: chunked prefill, prefix caching, FP8 KV
https://blog.lo0.es/posts/decode-optimizaciones-vllm/ — las optimizaciones de decode: speculative decoding, gpu-memory-utilization, max-num-seqs
https://blog.lo0.es/posts/anatomia-metricas-dcgm-vllm-anomalias/ — DCGM para las métricas de GPU debajo de vLLM: SM utilization, memory bandwidth, temperatura; la capa de hardware bajo las métricas de aplicación
https://blog.lo0.es/posts/observabilidad-gpu-dcgm-llm/ — cómo correlacionar métricas de GPU (DCGM) con métricas de aplicación (vLLM Prometheus) para diagnóstico completo
https://blog.lo0.es/posts/continuous-batching-fundamentos/ — el scheduler que produce las métricas de num_running_seqs y num_waiting_seqs; sin entender el scheduler, las métricas de concurrencia no tienen contexto

Referencias

Knowledge Distillation: enseñar a un modelo pequeño a pensar como uno grande

Fri, 05 Jun 2026 04:00:00 +0000

TL;DR

Knowledge Distillation es la técnica de entrenar un modelo pequeño (student) usando como supervisión las probabilidades de salida de un modelo grande (teacher), en vez de usando sólo las etiquetas duras del dataset de entrenamiento. El resultado es un modelo pequeño que razona mejor de lo que sugiere su tamaño, porque aprende las distribuciones de incertidumbre del teacher en vez de memorizar respuestas binarias. Es la razón por la que Phi-4 (14B) supera en razonamiento a la mayoría de modelos de 70B, y por la que los modelos de la familia Gemma 3 son sorprendentemente capaces para su tamaño. No es una técnica de compresión de modelo existente: es un proceso de entrenamiento que produce un modelo más pequeño desde cero o desde un punto de partida diferente.

La analogía

Un maestro cirujano con treinta años de experiencia y un residente de primer año. Si el residente sólo aprende del manual de anatomía —respuestas correctas binarias: “aquí se corta, aquí no”— tardará años en desarrollar el juicio clínico del maestro. Pero si opera a su lado, observando sus microdecisiones, sus dudas, los casos ambiguos donde el maestro sabe que dos opciones son casi igualmente válidas, aprende algo que el manual no puede enseñar: la estructura de la incertidumbre.

Knowledge distillation es exactamente eso. El “manual de anatomía” son las etiquetas duras (la respuesta correcta). El “maestro cirujano” es el teacher LLM. Las distribuciones de probabilidad sobre el vocabulario son la materialización de esa incertidumbre que el student absorbe.

Qué es realmente

Cuando un LLM genera texto, no produce una sola palabra: produce una distribución de probabilidad sobre todo su vocabulario en cada posición. Para el token siguiente, el modelo podría decir:

"París": 42%
"Lyon": 8%
"Marsella": 6%
"la ciudad": 5%
...resto del vocabulario: 39%

Esta distribución es información densa. Dice no sólo qué es la respuesta correcta, sino también qué otras respuestas eran plausibles y en qué medida. Un student entrenado sólo con la etiqueta “París” (probabilidad 1.0 al token correcto, 0.0 al resto) no ve esta riqueza.

Destilación usa la distribución completa del teacher como objetivo de entrenamiento del student. La función de pérdida tiene dos términos:

$$\mathcal{L}{total} = (1 - \alpha) \cdot \mathcal{L}{CE}(y, \hat{y}S) + \alpha \cdot \mathcal{L}{KD}(p_T, p_S, T)$$

Donde:

$\mathcal{L}_{CE}$ es la cross-entropy estándar con las etiquetas duras (supervisión clásica).
$\mathcal{L}_{KD}$ es la KL-divergencia entre las distribuciones del teacher y el student.
$\alpha$ controla el peso relativo de cada término (típicamente 0.5–0.9 a favor de KD).
$T$ es la temperatura, un parámetro que suaviza las distribuciones para hacer la señal de KD más informativa.

El papel de la temperatura

Si el teacher asigna 99% a “París” y 0.001% a cada otra palabra, la distribución es casi tan informativa como una etiqueta dura. La temperatura $T > 1$ suaviza esa distribución:

$$p_T(k) = \frac{\exp(z_k / T)}{\sum_j \exp(z_j / T)}$$

Con $T = 4$ y los logits originales, la distribución que antes era [99%, 0.001%, 0.001%…] pasa a ser algo como [42%, 8%, 6%…]. El student ve el vecindario de probabilidad real del teacher, no sólo su respuesta puntual.

Ejemplo numérico con temperatura:

Logits del teacher para “La capital de Francia es _____”:

París: 8.5
Lyon: 3.2
Europa: 2.1
una: 1.8

Con T=1 (softmax estándar): $$p(\text{París}) = \frac{e^{8.5}}{e^{8.5} + e^{3.2} + e^{2.1} + e^{1.8}} \approx 99.3%$$

Con T=4: $$p(\text{París}) = \frac{e^{8.5/4}}{e^{8.5/4} + e^{3.2/4} + e^{2.1/4} + e^{1.8/4}} = \frac{e^{2.125}}{e^{2.125} + e^{0.8} + e^{0.525} + e^{0.45}} \approx 54%$$

La señal con T=4 es mucho más informativa para el student: aprende que Lyon es más plausible que Europa, que Europa es más plausible que “una”, etcétera.

Los tres modos de destilación

Offline (o “black-box”)

El teacher genera un dataset sintético de respuestas antes del entrenamiento. El student se entrena sobre ese dataset como si fuera etiquetas duras normales.

teacher → genera 100M pares (prompt, completion) → dataset
student → se entrena sobre ese dataset

Es la forma más barata de escalar: el teacher se ejecuta una sola vez, el student se entrena sobre los datos generados con hardware convencional. La mayoría de los modelos de instrucción open source (Alpaca, Vicuna, WizardLM en sus primeras versiones) usaron esta estrategia: GPT-4 como teacher, datos guardados, Llama-7B como student.

Limitación: el student no ve las distribuciones de probabilidad del teacher, sólo sus respuestas. Es destilación de “comportamiento”, no de “conocimiento” en el sentido estricto. Si el teacher se equivoca (y GPT-4 se equivoca), el error queda cristalizado en el dataset.

Online (o “white-box”)

Teacher y student se ejecutan juntos durante el entrenamiento. El student procesa cada batch, el teacher procesa el mismo batch en paralelo, y la pérdida KD se calcula en tiempo real con las distribuciones de probabilidad completas.

for batch in dataset:
logits_teacher = teacher(batch) # forward pass del teacher
logits_student = student(batch) # forward pass del student
loss = KL(softmax(logits_teacher/T), softmax(logits_student/T))
loss.backward() # sólo actualiza student

El teacher tiene los gradientes desactivados (torch.no_grad()). La señal de aprendizaje es richer que en offline, pero el coste es alto: necesitas mantener el teacher en VRAM durante todo el entrenamiento. Para destilación de un teacher de 405B a un student de 8B, necesitarías varias H100 sólo para el teacher.

En-policy (on-policy)

Variante reciente (2024–2026) que combina lo mejor de ambos: el teacher genera respuestas dinámicamente durante el entrenamiento, pero el student las evalúa con su propia distribución. El ciclo es:

Student genera una propuesta de respuesta (rollout).
Teacher puntúa esa propuesta con su distribución de probabilidad.
El student actualiza con la señal del teacher.

Esto evita que el student aprenda de distribuciones fuera de su propio dominio (problema de distribution shift en offline). Es la base de algoritmos como SimCT (2026) que usan teachers de diferentes familias (Qwen, Phi, Gemma) para generar señal cross-tokenizer.

Por qué los mejores modelos pequeños usan destilación

Phi-4 (Microsoft, 14B), Gemma 3 (Google, 9B/27B), y los modelos de la familia Qwen3 compactos son los ejemplos más claros. Sus benchmarks son anómalos respecto a su tamaño: Phi-4-14B supera a LLaMA-3-70B en MATH y GPQA-Diamond, dos benchmarks de razonamiento matemático y científico donde el tamaño suele ser determinante.

¿Por qué? La clave está en qué supervisa el entrenamiento:

Un modelo entrenado con datos de internet aprende la distribución de texto humano, que incluye mucho texto de baja calidad, errores, ambigüedades.
Un student que aprende de un teacher frontier (GPT-4o, Claude 3 Opus, Gemini 1.5 Pro) absorbe una distribución filtrada hacia texto de alta calidad y razonamiento correcto.

El student con 14B parámetros no “sabe más” que uno sin destilación del mismo tamaño, pero ha aprendido a usarlos mejor porque sus gradientes de entrenamiento nunca estuvieron contaminados por texto de baja calidad.

Dato empírico: Phi-4 (14B destilado) vs LLaMA-3-70B (no destilado) en MATH benchmark (2025):

Phi-4: 80.4%
LLaMA-3-70B: 68.0%

Un modelo 5× más pequeño supera al grande porque la señal de entrenamiento es mejor, no porque tenga más parámetros.

Destilación de razonamiento: el caso de los thinking models

Los modelos de razonamiento (DeepSeek-R1, Qwen3-thinking, QwQ) generan cadenas de pensamiento internas antes de dar la respuesta final. Destilar razonamiento es más complejo porque no sólo se quiere transferir la respuesta: se quiere transferir la forma de pensar.

La estrategia actual (2025–2026) es destilación de trazas de razonamiento:

El teacher (modelo thinking grande) genera respuestas con su cadena de pensamiento interna completa.
El dataset incluye esas cadenas de pensamiento como parte del output.
El student aprende a imitar tanto la cadena como la respuesta final.

Esto explica por qué Qwen3-7B-thinking puede razonar formalmente sobre matemáticas siendo 10× más pequeño que los modelos que lo precedieron sin destilación: aprendió el proceso, no sólo el resultado.

Cuándo usar destilación vs. las alternativas

Técnica	Qué hace	Requiere reentrenamiento	Resultado
Quantización	Reduce precisión de pesos	No	Mismo modelo, más pequeño
Poda	Elimina pesos irrelevantes	No (PTQ)	Mismo modelo, más disperso
Destilación	Entrena modelo nuevo	Sí	Modelo diferente, más pequeño

La destilación no comprime un modelo existente: produce uno nuevo. Por eso es complementaria, no sustitutiva: puedes destilar un 405B a un 8B, y luego cuantizar ese 8B a INT4 para reducir su coste de inferencia.

Cuándo es la opción correcta:

Necesitas un modelo 5–10× más pequeño que el mejor disponible.
Tienes acceso (API o local) a un teacher de calidad.
Tienes datos de entrenamiento o capacidad de generarlos.
La latencia o el coste de inferencia son un constraint duro.

Cuándo no:

Quieres comprimir un modelo existente rápidamente: usa cuantización + poda.
No tienes presupuesto de entrenamiento (destilación online requiere semanas de GPU).
El teacher no es significativamente mejor que el student base: la señal de KD será débil.

Implicaciones para inferencia on-premise

En un despliegue soberano, el teacher puede ser un modelo grande que se ejecuta localmente (no es necesaria una API externa). El flujo es:

4×H100 genérico:
teacher: Llama-3.3-70B-Instruct (en los 4×H100, carga completa)
→ genera dataset de 10M pares (prompt, completion con logits)
→ 3-4 semanas de generación a batch 32
Después del dataset:
student: Qwen2.5-7B (fine-tuned con KD loss sobre el dataset)
→ 2-3 días de entrenamiento en los mismos H100
→ resultado: 7B que razona como el 70B en el dominio específico
Producción:
RTX 4090: sirve el student 7B cuantizado a INT4 (4 GB)

El teacher sólo se necesita para generar los datos. El student es lo que va a producción. La inversión en cómputo de entrenamiento se amortiza en meses de inferencia más barata.

Para ENS/NIS2: este flujo es 100% on-premise, cero dependencia de APIs externas, y el modelo resultante es tuyo en todos los sentidos.

Ver también

https://blog.lo0.es/posts/poda-pruning-llm-fundamentos/ — alternativa técnica: en vez de entrenar un modelo nuevo, eliminar partes del modelo existente; destilación y poda son complementarias
https://blog.lo0.es/posts/quantization-fundamentos-inferencia/ — el paso siguiente después de destilar: cuantizar el student para inferencia eficiente
https://blog.lo0.es/posts/speculative-decoding-fundamentos/ — los drafters de speculative decoding son frecuentemente students destilados del model base que aprenden a predecir su distribución
https://blog.lo0.es/posts/fine-tuning-continuo-produccion/ — destilación como forma de fine-tuning continuo: el teacher es el modelo en producción, el student es la siguiente versión
https://blog.lo0.es/posts/alignment-moderno-dpo-kto-orpo-simpo/ — DPO y sus variantes pueden verse como destilación de preferencias humanas hacia el modelo; la matemática de la distribución de referencia es análoga al teacher en KD

Referencias

Distilling the Knowledge in a Neural Network — Hinton, Vinyals & Dean, 2015 (paper fundacional)
Phi-4 Technical Report — Microsoft Research, 2024
DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning — DeepSeek, 2025 (destilación de razonamiento)
Awesome LLM On-Policy Distillation — colección de papers de destilación en-policy, 2025–2026
Knowledge Distillation for LLMs: Survey — ICLR 2025

Optimizando el decode en vLLM: exprimir cada token en hardware pequeño

Fri, 05 Jun 2026 04:00:00 +0000

TL;DR

El decode es la fase en la que vLLM genera tokens de salida uno a uno. Es memory-bound, no compute-bound: la GPU pasa más tiempo esperando que lleguen los pesos desde VRAM que haciendo cálculos. En hardware pequeño —RTX 4090 (24 GB) o L40 (48 GB)— el decode mal configurado desaprovecha la mitad de la capacidad de la tarjeta. Cinco parámetros de vLLM cambian la ecuación: gpu-memory-utilization, max-num-seqs, speculative decoding, KV cache en FP8 y un swap-space correctamente en cero. Bien calibrados, la diferencia es real: de 15 tokens/s a 35–50 tokens/s en el mismo hardware.

La analogía

Un obrero de cadena de montaje que ensambla coches. Cada coche requiere exactamente el mismo proceso: va a buscar la pieza al almacén, vuelve, la atornilla, repite. El tiempo de transporte al almacén —la latencia de VRAM— es fijo y no se puede eliminar. Pero hay formas de hacerlo menos doloroso:

Tener varios coches en paralelo en la cadena (más concurrencia, mismo tiempo de transporte amortizado).
Que un ayudante prefabrique piezas comunes (speculative decoding: el draft model propone, el verifier confirma).
Almacenar en el taller sólo las piezas más usadas (KV cache cuantizado: caben más contextos en el mismo espacio).

Las tres estrategias son exactamente los tres ejes de optimización del decode en vLLM.

Por qué el decode es memory-bound

Durante el prefill, la GPU procesa N tokens en paralelo: la operación de atención es un matmul grande y las unidades de cómputo están ocupadas. Durante el decode, procesa 1 token por paso: el matmul se convierte en un vector-matrix product, operación que infrautiliza los tensor cores.

El ratio de utilización de cómputo durante decode típico en una RTX 4090:

$$\text{MFU}_{decode} \approx 5–15% \quad \text{(vs 40–60% en prefill)}$$

El cuello no es la potencia de cálculo, sino el ancho de banda. Para generar cada token, el modelo tiene que leer sus pesos completos desde VRAM:

$$\text{tiempo_por_token} \approx \frac{\text{tamaño_pesos_bytes}}{\text{ancho_banda_VRAM}}$$

Para Qwen2.5-7B en BF16 (14 GB de pesos) en una RTX 4090 (1.008 GB/s):

$$t \approx \frac{14 \times 10^9}{1.008 \times 10^{12}} \approx 13.9 \text{ ms/token} \approx 72 \text{ tokens/s teórico máximo}$$

El valor real es menor (~30–50 tok/s) por overhead de scheduler, atención sobre el KV cache creciente y otras latencias. Pero el límite teórico marca el techo.

Con Q4_K_M (pesos ~4 GB):

$$t \approx \frac{4 \times 10^9}{1.008 \times 10^{12}} \approx 3.97 \text{ ms/token} \approx 252 \text{ tokens/s teórico}$$

Cuantizar el modelo es la forma más directa de mejorar el throughput de decode en hardware memory-bound. Todo lo demás optimiza sobre ese techo.

Las cinco palancas

1. Darle a vLLM toda la VRAM que puedas — `--gpu-memory-utilization`

--gpu-memory-utilization (abreviado --gpu-mem-util) define la fracción de VRAM disponible que vLLM puede usar para el KV cache, una vez cargados los pesos del modelo. El resto lo reserva para activaciones durante el forward pass y el contexto CUDA.

vllm serve mi-modelo \
 --gpu-memory-utilization 0.92

El valor por defecto es 0.90. En bare metal donde ningún otro proceso usa la GPU, 0.92–0.95 es seguro. No subas de 0.95: vLLM necesita margen para activaciones durante picos de batch, y quedarse sin VRAM en medio de una inferencia resulta en un crash del proceso, no en un error limpio.

Por qué importa: más KV cache disponible = más requests simultáneos en vuelo = mejor utilización de la GPU durante decode. PagedAttention asigna el KV cache en bloques de tamaño fijo (16 tokens/bloque por defecto), y vLLM los gestiona como páginas de memoria virtual. A más bloques disponibles, más requests puede servir sin que ninguna se quede esperando por espacio.

RTX 4090, Qwen2.5-7B-BF16 (14 GB pesos):
VRAM total: 24 GB
Pesos: 14 GB
Disponible para KV cache: 10 GB
gpu-memory-utilization 0.90 → 0.90 × 10 GB = 9 GB para KV cache
gpu-memory-utilization 0.94 → 0.94 × 10 GB = 9.4 GB → ~4% más de tokens en vuelo

El impacto es modesto con modelos que caben cómodos, pero se amplifica con modelos que apuran la VRAM.

2. Concurrencia real — `--max-num-seqs`

--max-num-seqs es el número máximo de requests que vLLM puede tener en proceso simultáneamente (sumando prefill y decode). Es el parámetro que controla la concurrencia efectiva del sistema.

vllm serve mi-modelo \
 --max-num-seqs 128

El efecto es directo: más requests en decode simultáneo = mejor amortización del coste fijo de leer pesos. Cuando el batch de decode crece de 1 a 8, el tiempo de generar 8 tokens es casi el mismo que generar 1 (los pesos se leen una sola vez para todos). El throughput agregado escala casi linealmente hasta que el KV cache o la VRAM de activaciones se convierten en el cuello.

$$\text{throughput_agregado}(B) \approx B \times \text{throughput}(1) \quad \text{para } B \ll B_{max}$$

Error común: subir --max-num-seqs sin asegurarse de que hay suficiente KV cache en VRAM para todas las requests. Si vLLM no puede alojar los KV cache de 128 requests simultáneas, hace preemption (pausa alguna request y libera su KV cache) con coste de latencia. Monitoriza vllm:num_preemptions_total.

Interacción con --max-num-batched-tokens: el scheduler de vLLM procesa hasta max-num-batched-tokens tokens por paso. Si tienes 128 requests en decode generando 1 token cada una, eso son 128 tokens de decode. El presupuesto de decode consume 128 tokens del presupuesto total; el resto lo dedica a prefill en chunks. Ajusta ambos valores conjuntamente.

# Para RTX 4090 sirviendo ~50 usuarios concurrentes con respuestas de hasta 512 tokens
vllm serve mi-modelo \
 --max-num-seqs 64 \
 --max-num-batched-tokens 8192
# 64 tokens de decode por paso + hasta 8128 tokens de prefill chunked

3. Speculative decoding — `--speculative-model` + `--num-speculative-tokens`

Speculative decoding es el cambio más impactante para decode en hardware pequeño. La idea es simple: un modelo draft pequeño propone varios tokens a la vez, y el modelo verifier los valida o rechaza en un solo forward pass.

vllm serve Qwen/Qwen2.5-7B-Instruct \
 --speculative-model Qwen/Qwen2.5-0.5B-Instruct \
 --num-speculative-tokens 5 \
 --speculative-draft-tensor-parallel-size 1

Por qué funciona: el verifier de 7B tiene que leer 14 GB de pesos por paso. Con 5 tokens propuestos, si el acceptance rate es del 80%, se generan de media 4–5 tokens por paso de verifier en vez de 1. El throughput efectivo sube sin que la GPU trabaje más.

El acceptance rate (α) depende de qué tan bien el draft predice la distribución del verifier. Para el mismo dominio, modelos de la misma familia suelen tener α > 0.75:

$$\text{speedup} \approx \frac{1 + \alpha \cdot k}{1 + \alpha \cdot k / \text{cost_ratio}}$$

Donde $k$ es el número de tokens propuestos y cost_ratio es el ratio de coste draft/verifier. Para un 0.5B draft y 7B verifier (ratio ~14×):

$$\text{speedup} \approx 1 + 0.8 \times 5 \approx 5 \text{ (teórico máximo, no alcanzable)}$$

En práctica, con α = 0.75 y k = 5 en hardware sin NVLink: 1.8–2.5× más tokens/s comparado con decode solo.

EAGLE-3 en 2026: los mejores drafters actuales no son versiones small del mismo modelo, sino redes especializadas en predecir la distribución del verifier. EAGLE-3 reporta 3–6.5× speedup sobre decode vanilla en benchmarks públicos. En producción con batches mixtos el speedup real es más conservador (1.5–3×). vLLM soporta EAGLE/EAGLE-2 via --speculative-model:

# Con un drafter EAGLE (requiere drafter entrenado específicamente para el base model)
vllm serve meta-llama/Llama-3.1-8B-Instruct \
 --speculative-model yuhuili/EAGLE3-LLaMA3.1-Instruct-8B \
 --num-speculative-tokens 6

Cuándo el speculative decoding NO ayuda:

Batches muy grandes (>32 requests): el acceptance rate varía entre requests y el batch pasa más tiempo en re-draft que en aceptar.
Tareas de alta entropía (brainstorming, código muy creativo): el draft predice peor, α cae por debajo de 0.5 y el overhead del draft pesa más que la ganancia.
Si el modelo draft no cabe en la VRAM disponible junto al verifier.

En una RTX 4090 con un 7B verifier y un 0.5B draft (BF16): 14 + 1 GB = 15 GB. Quedan 9 GB para KV cache. Funciona.

4. KV cache cuantizado — `--kv-cache-dtype fp8`

Ya se cubrió en el artículo de prefill para su efecto en capacidad de contexto. Desde el punto de vista del decode, el beneficio es diferente: más tokens caben en el KV cache → más requests simultáneas sin preemption → mejor throughput agregado.

vllm serve mi-modelo \
 --kv-cache-dtype fp8 \
 --calculate-kv-scales

Advertencia de precisión en decode: el KV cache se lee en cada paso de atención del decode. La cuantización introduce ruido en las activaciones de atención. Para textos largos (>4K tokens de contexto) puede acumularse. En benchmarks de calidad (MMLU, HellaSwag) la degradación con FP8 KV y --calculate-kv-scales es <0.5% en modelos modernos. Sin --calculate-kv-scales, la degradación puede ser mayor porque las escalas se fijan estáticamente.

Combinación óptima para RTX 4090:

vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ \
 --quantization awq \  # pesos en INT4: 4 GB modelo
 --kv-cache-dtype fp8 \  # KV cache a mitad de tamaño
 --calculate-kv-scales \
 --gpu-memory-utilization 0.94

# VRAM disponible: 24 - 4 = 20 GB para KV cache
# Con FP8: ~40 KB/token (vs 80 KB BF16) → 20 GB / 40 KB = 500.000 tokens de contexto total
# Con max-num-seqs 64 y ctx de 4K: 64 × 4096 × 40KB = 10 GB → cabe con margen

5. Eliminar el swap — `--swap-space 0`

--swap-space define cuánta RAM de sistema (no VRAM) puede usar vLLM para hacer preemption de KV caches. Cuando vLLM tiene más requests activas de las que caben en VRAM, puede “pausar” algunas moviendo su KV cache a RAM y reactivarlas más tarde.

El problema: mover un KV cache de 4K tokens de VRAM a RAM y de vuelta tiene una latencia de decenas de milisegundos vía PCIe. Para un sistema donde quieres latencia predecible, el swap introduce jitter inaceptable.

vllm serve mi-modelo \
 --swap-space 0

Con --swap-space 0, cuando vLLM no puede alojar más requests en VRAM, directamente las encola en vez de hacer preemption. La cola añade latencia de espera, pero es predecible y no interrumpe las requests ya en vuelo.

¿Cuándo sí tener swap? Si tu workload tiene picos de demanda cortos y puedes tolerar jitter ocasional a cambio de no rechazar requests, un swap de 4–8 GB puede ser útil. En despliegues ENS donde la latencia es un SLA contrato, --swap-space 0 es la opción correcta.

La configuración de referencia por hardware

RTX 4090 (24 GB) — modelo 7B, uso interno

vllm serve Qwen/Qwen2.5-7B-Instruct \
 --gpu-memory-utilization 0.92 \
 --max-model-len 8192 \
 --max-num-seqs 64 \
 --max-num-batched-tokens 8192 \
 --enable-chunked-prefill \
 --enable-prefix-caching \
 --kv-cache-dtype fp8 \
 --calculate-kv-scales \
 --swap-space 0 \
 --speculative-model Qwen/Qwen2.5-0.5B-Instruct \
 --num-speculative-tokens 5 \
 --speculative-draft-tensor-parallel-size 1 \
 --dtype bfloat16

Throughput esperado: 35–55 tokens/s por usuario, hasta 64 simultáneos, TTFT <500ms para prompts <1K tokens.

L40 (48 GB) — modelo 14B, multi-usuario

vllm serve Qwen/Qwen2.5-14B-Instruct \
 --gpu-memory-utilization 0.90 \
 --max-model-len 16384 \
 --max-num-seqs 128 \
 --max-num-batched-tokens 16384 \
 --enable-chunked-prefill \
 --enable-prefix-caching \
 --kv-cache-dtype fp8 \
 --calculate-kv-scales \
 --swap-space 0 \
 --speculative-model Qwen/Qwen2.5-1.5B-Instruct \
 --num-speculative-tokens 5 \
 --dtype bfloat16

Throughput esperado: 25–40 tokens/s por usuario, hasta 128 simultáneos con speculative decoding activo, TTFT <800ms para prompts <2K tokens.

Cómo medir que el decode está optimizado

# Métricas clave en vllm:8000/metrics

vllm:generation_tokens_total # tokens generados en total → tendencia
vllm:e2e_request_latency_seconds_* # latencia end-to-end por percentil
vllm:time_per_output_token_seconds_* # ITL (inter-token latency)
vllm:num_preemptions_total # si sube, KV cache se está llenando
vllm:spec_decode_draft_acceptance_rate # hit rate del speculative decoding

Si spec_decode_draft_acceptance_rate < 0.6, el drafter no está ayudando: desactiva speculative decoding o busca un drafter mejor entrenado para tu modelo/dominio.

Si num_preemptions_total crece, tienes demasiadas requests simultáneas para el KV cache disponible. Opciones: bajar max-num-seqs, activar FP8 KV cache, bajar max-model-len, o cuantizar más el modelo.

Implicaciones para inferencia on-premise

En un despliegue soberano con hardware fijo, no puedes comprar más GPUs a voluntad. Cada décima de gpu-memory-utilization bien calibrada, cada punto de acceptance rate del speculative decoding y cada MB de KV cache liberado por FP8 son capacidad real que no tienes que provisionar con otro nodo.

La combinación de pesos cuantizados (AWQ/GPTQ), KV cache FP8 y speculative decoding permite que un 14B sirva en una L40 lo que sin optimizaciones requeriría dos L40 en tensor parallel. Eso es el argumento económico para invertir tiempo en estos parámetros.

El decode no se puede acelerar infinitamente en hardware memory-bound: el límite teórico lo pone el ancho de banda de VRAM. Pero la diferencia entre el mínimo y el máximo alcanzable en ese hardware puede ser 3–4× con las palancas correctas.

Ver también

Referencias

Efficient Memory Management for Large Language Model Serving with PagedAttention — Kwon et al., 2023
EAGLE-2: Faster Inference of Language Models with Dynamic Draft Trees — Li et al., 2024
Fast Inference from Transformers via Speculative Decoding — Leviathan et al., 2022
vLLM Optimization and Tuning — documentación oficial
vLLM Speculative Decoding
FP8 KV Cache en vLLM

Optimizando el prefill en vLLM: los knobs que tu TTFT no perdona

Fri, 05 Jun 2026 04:00:00 +0000

TL;DR

El prefill es la fase en la que vLLM procesa tu prompt de entrada y produce el KV cache inicial. Es compute-bound (a diferencia del decode, que es memory-bound), tarda más cuanto más largo es el prompt, y bloquea el decode de todas las demás requests en cola. Hay cuatro palancas en vLLM que cambian radicalmente su comportamiento: chunked prefill, prefix caching, FP8 KV cache y el presupuesto de tokens por batch. Con hardware modesto —una RTX 4090 de 24 GB o una L40 de 48 GB— la diferencia entre ignorarlas y usarlas bien puede ser un TTFT 3× menor y un 40% más de throughput agregado.

La analogía

Imagina una imprenta de principios del siglo XX. Componer los tipos de plomo (preparar el molde) es lento y bloquea la prensa. Imprimir las páginas ya compuestas es rápido, pero necesita el molde listo antes de empezar.

El prefill es componer los tipos. El decode es imprimir. Una prensa que sólo puede hacer una cosa a la vez —o compone o imprime— deja la maquinaria parada la mitad del tiempo. La solución histórica fue tener un obrero componiendo la siguiente plana mientras la anterior ya estaba en prensa. Eso es, exactamente, chunked prefill.

Qué es el prefill realmente

Cuando llega un request a vLLM, el motor tiene que procesar todos los tokens del prompt de una vez antes de poder emitir el primer token de respuesta. Durante ese procesamiento calcula, para cada token del prompt, sus vectores Key y Value de la atención. El resultado —el KV cache inicial— se almacena en VRAM y se usa durante todo el decode posterior.

A diferencia del decode, donde el modelo procesa un token nuevo por paso, en el prefill procesa N tokens de golpe. Eso lo hace mucho más eficiente en FLOPs/token (las GPUs son buenas en matmuls grandes), pero tiene un coste cuadrático en atención:

$$\text{FLOPs_atención_prefill} \approx 4 \cdot N^2 \cdot d_{model}$$

Con un prompt de 1.000 tokens y $d_{model} = 4096$ (Qwen2.5-7B): $4 \cdot 10^6 \cdot 4096 \approx 16 \times 10^9$ FLOPs sólo en atención. Con 4.000 tokens, 256× más por la naturaleza cuadrática.

Prefill (compute-bound):
prompt tokens → [attention O(N²)] → [FFN] → KV cache inicial
Decode (memory-bound):
1 token nuevo → [cross-attention sobre KV cache] → siguiente token

Por qué el prefill es un problema en hardware pequeño

En una H100 con 3,35 TB/s de ancho de banda, un prefill largo se amortiza rápido. En una RTX 4090 (1,008 TB/s) o una L40 (864 GB/s), el cuello de botella aparece antes y tiene consecuencias concretas:

El problema del head-of-line blocking. Por defecto, vLLM procesa un prefill completo antes de hacer cualquier decode. Si tienes 10 requests en cola —9 en decode, 1 con un prompt de 8.000 tokens— esas 9 requests se detienen mientras la GPU mastica el prefill largo. Sus usuarios ven que el streaming se congela. Esto se llama head-of-line blocking y es el enemigo número uno del TTFT en producción.

Las cuatro palancas

1. Chunked prefill — `--enable-chunked-prefill` + `--max-num-batched-tokens`

Chunked prefill parte el prefill largo en trozos (chunks) y los intercala con pasos de decode en el mismo batch. En vLLM V1 (≥ 0.6) está activo por defecto.

vllm serve mi-modelo \
 --enable-chunked-prefill \
 --max-num-batched-tokens 4096

--max-num-batched-tokens es el presupuesto total de tokens que vLLM puede procesar en un único paso del motor, sumando prefill y decode. Es el parámetro más importante para controlar el trade-off:

`max-num-batched-tokens`	Efecto
Bajo (512–2048)	Más pasos de decode por ciclo → mejor ITL, peor TTFT
Alto (8192–32768)	Chunks de prefill grandes → mejor TTFT y throughput, peor ITL

Para una RTX 4090 sirviendo modelos 7B–13B con contextos mixtos (256–4096 tokens):

--max-num-batched-tokens 8192 # punto de equilibrio razonable

Para una L40 (48 GB) con modelos más grandes y prompts más largos:

--max-num-batched-tokens 16384

Cómo funciona internamente: con un presupuesto de 4.096 tokens y un prefill de 10.000, vLLM lo parte en 3 chunks (4.096 + 4.096 + 1.808). Entre chunks, procesa los pasos de decode pendientes. Las requests en decode siguen avanzando; el prefill largo tarda más en terminar, pero no congela nada.

Sin chunked prefill:
t=0 [prefill 10k tokens]─────────────────────────────┐
t=1 └─[decode r1,r2...r9]
Con chunked prefill (budget 4096):
t=0 [prefill chunk 4096][decode r1..r9]
t=1 [prefill chunk 4096][decode r1..r9]
t=2 [prefill chunk 1808][decode r1..r9]
t=3 [decode todos, incluido el nuevo]

El TTFT del request largo aumenta ligeramente (3 pasos en vez de 1), pero el ITL de las otras 9 requests no se interrumpe.

2. Prefix caching — `--enable-prefix-caching`

Si múltiples requests comparten el mismo prefijo —un system prompt, un few-shot, un documento de contexto— vLLM puede calcular el KV cache de ese prefijo una sola vez y reutilizarlo.

vllm serve mi-modelo \
 --enable-prefix-caching

Esto se llama Automatic Prefix Caching (APC). Internamente, vLLM divide el KV cache en bloques de tamaño fijo (por defecto 16 tokens/bloque) y les asigna un hash SHA basado en el contenido. Cuando llega un request nuevo, comprueba si algún bloque inicial ya está en la caché. Si hay hit, se salta ese prefill.

El impacto numérico: supón un system prompt de 512 tokens que aparece en el 80% de tus requests, y una tasa de 100 req/min:

Sin APC: 80 req/min × 512 tokens × costo_prefill = 41.000 tokens/min de prefill redundante
Con APC (hit rate 80%): 20 req/min × 512 = 10.240 tokens/min de prefill → reducción del 75%

El TTFT de esos 80 requests cae a lo que cuesta procesar sólo el sufijo nuevo.

Limitación con chunked prefill: cuando chunked prefill está activo, sólo el primer chunk del prefill se beneficia de APC en la implementación actual de vLLM. Para workloads donde el hit de caché es muy alto y los sufijos son cortos, considera reducir --max-num-batched-tokens para que el primer chunk cubra más del prefijo compartido.

# Configuración optimizada para alto hit rate de prefix cache
vllm serve mi-modelo \
 --enable-prefix-caching \
 --enable-chunked-prefill \
 --max-num-batched-tokens 4096 # chunks más pequeños = prefijo cabe en chunk 1

3. FP8 KV cache — `--kv-cache-dtype fp8`

El KV cache ocupa VRAM. Cuanta más VRAM consume, menos requests concurrentes puedes mantener en vuelo. En una RTX 4090 de 24 GB, el modelo Qwen2.5-14B en BF16 ya ocupa ~28 GB —no cabe. En Q4 ocupa ~9 GB, dejando ~14 GB para KV cache.

¿Cuántos tokens de contexto caben en 14 GB de KV cache BF16 para un 14B con GQA?

$$\text{KV_size_por_token} = 2 \cdot n_{kv_heads} \cdot d_{head} \cdot n_{layers} \cdot 2 \text{ bytes}$$

Para Qwen2.5-14B: $n_{kv_heads}=8$, $d_{head}=128$, $n_{layers}=40$, BF16 → $2 \cdot 8 \cdot 128 \cdot 40 \cdot 2 = 163.840$ bytes ≈ 160 KB/token.

14 GB / 160 KB ≈ 87.500 tokens de contexto total. Con 8 usuarios en paralelo y 4.096 tokens de contexto cada uno: 32.768 tokens ocupados de 87.500. Hay margen, pero es finito.

Pasando a FP8 (1 byte en vez de 2):

$$\text{KV_FP8} = 80 \text{ KB/token} \implies 14 \text{ GB} / 80 \text{ KB} = 175.000 \text{ tokens}$$

El doble de capacidad de contexto con la misma VRAM. Eso permite o bien más concurrencia, o bien contextos más largos.

vllm serve mi-modelo \
 --kv-cache-dtype fp8 \
 --calculate-kv-scales # calibra las escalas dinámicamente; sin esto hay degradación

Advertencia para RTX 4090 y L40: Ada Lovelace tiene instrucciones FP8 a nivel CUDA pero sin el hardware de scaling dedicado de Hopper (H100). La reducción de memoria es real; la aceleración de cómputo es menor que en H100. No esperes el mismo speedup que en un datacenter Hopper. En L40S (la variante con tensor cores FP8 optimizados) el beneficio es mayor que en RTX 4090.

4. Presupuesto de contexto — `--max-model-len`

--max-model-len define el máximo de tokens que vLLM puede manejar en un único request (prompt + generación). Es el límite duro que determina cuánta VRAM se reserva para el KV cache en el peor caso.

En hardware pequeño, reducirlo libera VRAM para más concurrencia:

# Modelo 7B en RTX 4090, contexto típico de 4K pero el modelo soporta 128K
vllm serve mi-modelo \
 --max-model-len 8192 \  # en vez de 131072
 --gpu-memory-utilization 0.92

Con contexto recortado a 8.192 tokens, vLLM no reserva KV cache para 131.072 tokens potenciales y puede meter más requests simultáneas. El riesgo es obvio: requests que superen 8.192 tokens fallan con un error. Ajústalo al P99 de tu distribución real de longitudes.

Interacción entre parámetros

Los cuatro parámetros no son independientes. Un error común es activar prefix caching sin ajustar el tamaño de bloque, o subir max-num-batched-tokens sin revisar que max-num-seqs permita llenarlo:

max-num-batched-tokens = 8192
max-num-seqs = 4
prompt medio = 512 tokens → 4 × 512 = 2048 tokens de prefill < 8192
El presupuesto de 8192 nunca se llena porque max-num-seqs limita antes.
Solución: subir max-num-seqs o bajar max-num-batched-tokens.

Configuración equilibrada para RTX 4090 + modelo 7B:

vllm serve Qwen/Qwen2.5-7B-Instruct \
 --gpu-memory-utilization 0.92 \
 --max-model-len 8192 \
 --enable-chunked-prefill \
 --max-num-batched-tokens 8192 \
 --max-num-seqs 64 \
 --enable-prefix-caching \
 --kv-cache-dtype fp8 \
 --calculate-kv-scales

Configuración para L40 (48 GB) + modelo 14B:

vllm serve Qwen/Qwen2.5-14B-Instruct-AWQ \
 --gpu-memory-utilization 0.90 \
 --max-model-len 16384 \
 --enable-chunked-prefill \
 --max-num-batched-tokens 16384 \
 --max-num-seqs 128 \
 --enable-prefix-caching \
 --kv-cache-dtype fp8 \
 --calculate-kv-scales

Cómo medir que está funcionando

Las métricas que confirman que el prefill está optimizado:

# En las métricas Prometheus de vLLM (puerto 8000/metrics):
vllm:time_to_first_token_seconds_bucket → distribución de TTFT
vllm:gpu_cache_usage_perc → utilización de KV cache
vllm:prefix_cache_hit_rate → hit rate de APC (si está activo)
vllm:num_running_seqs → requests en vuelo simultáneos

Un prefix_cache_hit_rate por debajo del 30% en workloads con system prompt fijo indica que algo en el hash no está funcionando (system prompt que varía por timestamp, formato de fecha en el prompt, etc.).

Implicaciones para inferencia on-premise

Chunked prefill y prefix caching son cero coste: se activan con flags, no requieren hardware adicional. FP8 KV cache requiere que el modelo sea compatible (casi todos los transformers modernos lo son) y que estés en Ada Lovelace o superior.

Para despliegues soberanos ENS donde el hardware es fijo y no puedes escalar horizontalmente a demanda, el prefill bien configurado es la diferencia entre necesitar 4 nodos y necesitar 2 para la misma carga.

El segundo artículo de esta serie cubre las optimizaciones del decode: speculative decoding, tuning del KV cache para maximizar concurrencia y cómo configurar gpu-memory-utilization sin que vLLM se quede sin VRAM a medianoche.

Ver también

https://blog.lo0.es/posts/kv-cache-fundamentos/ — cómo funciona el KV cache por dentro
https://blog.lo0.es/posts/flashattention-fundamentos/ — por qué FlashAttention cambia el consumo de memoria en prefill
https://blog.lo0.es/posts/continuous-batching-fundamentos/ — la base sobre la que chunked prefill construye
https://blog.lo0.es/posts/disaggregated-serving-prefill-decode/ — cuando escalar un solo nodo ya no basta
https://blog.lo0.es/posts/vllm-otel-instrumentacion-optimizaciones/ — cómo medir con Prometheus y OTel si chunked prefill y prefix caching están funcionando: ttft p99, gpu_prefix_cache_hit_rate y las alertas concretas

Referencias

Efficient Memory Management for Large Language Model Serving with PagedAttention — Kwon et al., 2023
Sarathi-Serve: Chunked Prefill and Stall-Free Scheduling — Agrawal et al., 2024
vLLM Optimization and Tuning — documentación oficial
Quantized KV Cache en vLLM

Poda de modelos LLM: eliminar sin amputar

Fri, 05 Jun 2026 04:00:00 +0000

TL;DR

Un modelo de 7B parámetros tiene decenas de miles de millones de conexiones neuronales. Muchas de ellas contribuyen tan poco que podrías eliminarlas sin que ningún benchmark razonable lo notase. Eso es la poda (pruning): identificar los pesos irrelevantes y suprimirlos para obtener un modelo más pequeño, más rápido o que consuma menos memoria. Las técnicas modernas (SparseGPT, Wanda, 2:4 structured sparsity) hacen esto sin reentrenamiento, en pocas horas de GPU, y con menos de 1 punto de perplexity de penalización. No reemplaza a la cuantización, se combina con ella.

La analogía

Un árbol de roble con cien ramas. Cuando llega el invierno, el árbol poda sus ramas débiles: redirige los recursos hacia los troncos principales. Un podador experto no corta al azar, observa cuáles ramas tienen poco follaje, cuáles están secas, cuáles crecen en dirección equivocada, y corta sólo esas.

Un modelo de lenguaje es ese árbol. Sus “ramas” son los pesos que conectan neuronas. Después del entrenamiento, muchas de esas conexiones son vestigios del proceso de optimización: existían para que el gradiente descendiera con suavidad, pero en producción apenas modifican la salida. El podador que las elimina con precisión es SparseGPT o Wanda. El que corta al azar es magnitude pruning sin calibración. Ambos dan un árbol más pequeño; sólo el experto da uno que sigue produciendo el mismo fruto.

Qué es la poda realmente

Un modelo de lenguaje transformer almacena su conocimiento en matrices de pesos. Una capa de atención tiene cuatro matrices: $W_Q, W_K, W_V, W_O$. Una capa FFN tiene al menos dos ($W_{up}, W_{down}$, más $W_{gate}$ en SwiGLU). Para un modelo de 7B con 32 capas, el número de parámetros individuales supera los 7.000 millones.

Poda es el proceso de fijar a cero un subconjunto de esos parámetros de forma que:

El modelo resultante ocupe menos memoria (si se almacena en formato disperso) o compute menos operaciones.
La calidad de las respuestas no caiga de forma apreciable.

Hay dos dimensiones de clasificación que importan:

Granularidad: qué unidad se elimina.

Poda no estructurada: pesos individuales, dispersos por toda la matriz. Alta compresión, difícil de acelerar en hardware convencional.
Poda estructurada: cabezas de atención completas, neuronas FFN enteras, o capas completas. Menor compresión, pero el modelo resultante es denso y compatible con cualquier hardware.
Semi-estructurada N:M: para cada grupo de M pesos consecutivos, exactamente N son cero. El caso 2:4 (2 zeros de cada 4) es el que soportan los Tensor Cores de NVIDIA Ampere y posteriores.

Momento: cuándo se elimina.

Post-entrenamiento (PTQ de pesos): no requiere gradient, es el estándar en LLMs grandes.
Durante entrenamiento (gradual/iterativa): más precisa, incompatible con modelos de 70B+ por coste.

Por qué existen tantos pesos redundantes

La respuesta está en cómo se entrenan los modelos. El descenso de gradiente estocástico con millones de pasos y learning rate decreciente produce redes sobre-parametrizadas por diseño: los parámetros extra no representan conocimiento adicional, sino margen de maniobra para que la optimización converja más fácilmente.

La Hipótesis del Ticket de Lotería (Frankle & Carlin, ICLR 2019) formalizó esta intuición: dentro de cualquier red densa entrenada existe una subred que, entrenada desde cero en aislamiento, alcanza la misma calidad. La red original es esa subred envuelta en ruido paramétrico generado por el proceso de entrenamiento.

Para LLMs, la evidencia empírica es consistente: modelos de 7B–70B toleran hasta el 50% de sparsidad no estructurada sin degradación observable en tareas conversacionales. En modelos más grandes, el umbral de tolerancia aumenta.

Las matemáticas que importan

¿Qué pesos son seguros eliminar?

Magnitude pruning: el criterio ingenuo

$$\text{importance}(w_{ij}) = |w_{ij}|$$

Se eliminan los pesos con menor valor absoluto. Intuitivo, pero incompleto: un peso pequeño conectado a una activación muy grande sigue contribuyendo significativamente a la salida.

Wanda: magnitud × activación

$$\text{importance}(w_{ij}) = |w_{ij}| \cdot |x_j|_2$$

Donde $x_j$ es el vector de activación de entrada correspondiente al peso $j$, calculado sobre un dataset de calibración de ~128 samples. El producto captura ambas dimensiones: un peso es seguro eliminar sólo si él es pequeño y su neurona de entrada está poco activa.

Ejemplo numérico:

Peso A: $|w| = 0.001$, $|x|_2 = 500$ → importancia = 0.5
Peso B: $|w| = 0.01$, $|x|_2 = 10$ → importancia = 0.1

Magnitude pruning eliminaría A (valor absoluto menor). Wanda elimina B (importancia menor). B es más seguro suprimir.

Wanda no requiere gradientes ni inversas de matriz hessiana. Corre en minutos sobre un modelo de 70B en una sola GPU. En benchmarks de perplexity WikiText-2 con 50% de sparsidad no estructurada, Wanda alcanza resultados comparables a SparseGPT con 10–100× menos coste computacional.

SparseGPT: compensación hessiana

SparseGPT aplica el mismo marco matemático que GPTQ (cuantización capa a capa), pero para poda. Cuando elimina un peso $w_p$, calcula una corrección $\delta w$ sobre los pesos restantes de la misma fila para minimizar el cambio en la salida de la capa:

$$\min_{\delta w} |W x - (W + \delta W) x|_2^2 \quad \text{s.t.} \quad w_p + \delta w_p = 0$$

La solución usa la inversa de la matriz Hessiana de segundo orden $H = X X^T$. El coste extra justifica la mayor precisión cuando la sparsidad objetivo es alta (>70%) o el modelo es pequeño (<7B, donde la redundancia es menor).

Método	Criterio	Coste	Sparsidad 50% (7B, ppl WikiText-2)
Magnitude	\|w\|	Instantáneo	+2–5 puntos
Wanda	\|w\| · \|x\|	Minutos	~+0.5 puntos
SparseGPT	Hessiana	1–4h GPU	~+0.4 puntos

2:4 Structured Sparsity: el caso especial de NVIDIA

NVIDIA Ampere (A100) y posteriores (H100, Ada Lovelace) incluyen hardware dedicado para el patrón 2:4: exactamente 2 de cada 4 pesos consecutivos son cero. Esto permite al hardware omitir las multiplicaciones por cero de forma eficiente, obteniendo hasta 2× speedup en matmul sobre modelos con pesos 2:4.

La restricción es que la sparsidad tiene que ser exactamente 2:4, no un patrón arbitrario. Las herramientas NVIDIA (APEX Sparse, cuSPARSELt) y frameworks como PyTorch 2.x soportan esto nativamente:

from torch.sparse import to_sparse_semi_structured, SparseSemiStructuredTensor

# Convertir pesos densos a 2:4 sparse
sparse_weight = to_sparse_semi_structured(dense_weight)
# Forward pass automáticamente usa sparse tensor cores
output = F.linear(input, sparse_weight)

Qué esperar en la práctica con 2:4:

RTX 4090 (Ada Lovelace): soporta 2:4 sparse tensor cores para FP16/BF16. Speedup teórico 2×, real 1.3–1.6× dependiendo del tamaño de batch y secuencia.
H100 (Hopper): ídem con mejoras adicionales en FP8 + 2:4 combinados.
A100: soportado, sin FP8.
GPUs consumer anteriores a Ada (3090, etc.): sin soporte de hardware. 2:4 sparsity da un modelo más pequeño en disco pero no acelera la inferencia.

Poda estructurada: eliminar cabezas y capas enteras

Poda de cabezas de atención

Un transformer de 32 capas con 32 cabezas por capa tiene 1.024 cabezas de atención. Estudios sistemáticos en modelos Llama-2 y Qwen muestran que entre el 20–40% de las cabezas tienen una influencia marginal en la salida final: su salida puede fijarse a cero sin que el benchmark cambie dentro del margen de error.

La métrica más usada es la Taylor importance: el producto del gradiente de la pérdida respecto a la salida de la cabeza por el valor de esa salida, sumado sobre un dataset de calibración:

$$\text{I}_{head} = \left| \sum_t \frac{\partial \mathcal{L}}{\partial o_t} \cdot o_t \right|$$

Las cabezas con $I_{head}$ más bajo se eliminan primero. Después de eliminar el 25% de cabezas en Llama-3-8B, la degradación en MMLU es <1% y el tiempo de inferencia de la atención cae ~20% porque los matmuls de atención son más pequeños.

Layer dropping: el atajo más agresivo

Eliminar una capa transformer completa suprime su bloque de atención y su FFN. El criterio más robusto es la Block Influence (BI), introducida en ShortGPT (2024):

$$\text{BI}(l) = 1 - \cos(\text{input}_l, \text{output}_l)$$

Una capa cuya salida es casi idéntica a su entrada (coseno próximo a 1, BI próximo a 0) actúa como función identidad: eliminarla no cambia el flujo de información. Las capas del centro del transformer suelen tener BI más bajo que las capas iniciales y finales.

Ejemplo numérico en LLaMA-2-70B:

Capas 0–5 (early): BI > 0.3 → no eliminar
Capas 20–45 (mid): BI < 0.05 → candidatas a eliminar
Capas 76–80 (final): BI > 0.2 → no eliminar

Eliminando 8 capas de 80 (10%): el modelo pasa de ~140 GB a ~126 GB en BF16. Speedup de inferencia: ~10% (proporcional al número de capas eliminadas). Degradación en benchmarks de razonamiento: 1–3%.

Implicaciones para inferencia on-premise

La poda no estructurada (50% sparsidad) produce modelos con el mismo número de parámetros pero con la mitad a cero. Sin kernels sparse especializados, eso no da speedup: la GPU sigue ejecutando las multiplicaciones, sólo que multiplica por cero muy eficientemente. El beneficio real es de almacenamiento y transferencia (el modelo ocupa menos en disco y en RAM de sistema).

Con 2:4 structured sparsity sobre hardware Ada/Hopper, el speedup es real pero moderado (1.3–1.7×) y requiere herramientas adicionales (cuSPARSELt o PyTorch sparse).

La poda estructurada (cabezas, capas) sí acelera en cualquier hardware porque reduce el tamaño real del modelo. Es la opción correcta si el objetivo es throughput en hardware sin tensor cores sparse.

Combinación con cuantización: poda + cuantización son ortogonales. Un modelo 50% sparse a INT4 ocupa aproximadamente un octavo del original en FP32. Es el punto de llegada de muchos pipelines de compresión agresiva para edge inference.

Aplicado a hardware on-premise genérico

RTX 4090 (24 GB, Ada Lovelace)

Soporta 2:4 sparse tensor cores para FP16/BF16. Con Wanda + 2:4 sparsity sobre un Qwen2.5-14B:

# Pipeline de poda: Wanda 2:4 + quantización INT4
# 1. Ejecutar Wanda con calibración sobre 128 muestras
python wanda/main.py \
 --model Qwen/Qwen2.5-14B \
 --sparsity_ratio 0.5 \
 --sparsity_type 2:4 \
 --save pruned_model/

# 2. Cuantizar el modelo podado (opcional pero complementario)
python -m awq.entry --model_path pruned_model/ \
 --w_bit 4 --output_path pruned_awq_model/

Resultado esperado: ~13 GB BF16 → ~6.5 GB tras poda 2:4 en sparse format → ~3.2 GB con AWQ INT4. El modelo 14B cabrá en la RTX 4090 con margen para KV cache.

4× H100 SXM (320 GB total, Hopper)

En este hardware la poda estructurada (layer dropping) tiene más sentido que 2:4 para inferencia de alta concurrencia: reduces el número de operaciones FLOPs por token de forma proporcional, lo que beneficia al throughput bajo batch grande donde el cuello es compute, no memoria.

# Aplicar layer dropping con ShortGPT BI metric
from shortgpt import compute_block_influence, drop_layers

bi_scores = compute_block_influence(model, calibration_data)
# Eliminar el 15% de capas con BI más bajo
model = drop_layers(model, bi_scores, drop_ratio=0.15)

Un Llama-3-70B podado al 15% de capas cabe en 3 H100 en vez de 4, liberando una GPU para otra tarea.

Ver también

https://blog.lo0.es/posts/quantization-fundamentos-inferencia/ — la palanca complementaria: cuantizar reduce la precisión de los pesos que la poda ha decidido conservar; combinadas dan compresión máxima
https://blog.lo0.es/posts/kv-cache-fundamentos/ — la poda reduce el tamaño del modelo, pero el KV cache sigue creciendo con el contexto; son costes separados en VRAM
https://blog.lo0.es/posts/speculative-decoding-fundamentos/ — los drafters de speculative decoding son a menudo versiones podadas del modelo base, no modelos entrenados desde cero
https://blog.lo0.es/posts/decode-optimizaciones-vllm/ — cómo el modelo podado se sirve en vLLM: los parámetros de throughput cambian con un modelo estructuralmente más pequeño
https://blog.lo0.es/posts/knowledge-distillation-fundamentos/ — alternativa conceptual a la poda: en vez de eliminar partes del modelo grande, entrenar uno pequeño para que imite su comportamiento

Referencias

SparseGPT: Massive Language Models Can be Accurately Pruned in One Shot — Frantar & Alistarh, 2023
A Simple and Effective Pruning Approach for Large Language Models (Wanda) — Sun et al., ICLR 2024
The Lottery Ticket Hypothesis — Frankle & Carlin, ICLR 2019
ShortGPT: Layers in Large Language Models are More Redundant Than You Expect — Men et al., 2024
NVIDIA 2:4 Sparsity in PyTorch — PyTorch Blog
SparseForge: Efficient Semi-Structured LLM Sparsification — 2025

Prefix cache: ingeniería del hit rate para pasar del 15% al 75%

Fri, 05 Jun 2026 04:00:00 +0000

TL;DR

El prefix cache de vLLM almacena los bloques de KV cache de prefijos compartidos y los reutiliza en requests posteriores. Un hit evita recalcular ese prefijo: el TTFT cae al coste del sufijo variable únicamente. En workloads enterprise con system prompts fijos —RAG, chatbots de dominio, asistentes con instrucciones largas— el hit rate debería ser >70%. En la práctica es 10-20% por razones completamente evitables. Este artículo las identifica, las corrige y da las queries OTel para confirmar el resultado.

La analogía

Un intérprete de conferencias simultáneas que tiene que traducir los discursos de veinte ponentes. Todos empiezan con el mismo preámbulo protocolar de dos páginas: la declaración de la conferencia, las reglas de conducta, el programa del día. Un intérprete sin memoria relee las dos páginas para cada ponente antes de empezar a traducir su discurso específico. Un intérprete con notas buenas las lee una vez, las archiva, y cuando empieza el segundo ponente pasa directamente al discurso.

El prefix cache es ese archivo. El hash del prefijo es la referencia que permite saltar a la parte nueva. Pero si el preámbulo cambia aunque sea en una palabra — porque alguien pone la fecha del día — el intérprete tiene que releer todo desde el principio.

Cómo funciona el hash de prefix cache

vLLM divide el KV cache en bloques de 16 tokens. Cada bloque tiene un hash calculado sobre su contenido exacto. Cuando llega un nuevo request, vLLM comprueba si algún bloque inicial del prompt ya está en cache comparando hashes.

El hash se calcula sobre el contenido byte a byte de los tokens. Cualquier diferencia — un espacio, un carácter diferente, un token de más — produce un hash completamente distinto. No hay matching parcial dentro de un bloque.

Consecuencia directa: si tu system prompt tiene 512 tokens y el token número 3 cambia entre requests (porque interpolas una fecha, un ID, un número de versión), ningún bloque hace hit aunque el 99% del texto sea idéntico.

Bloque 0 (tokens 0-15): hash = a3f7... ← ¿en cache?
Bloque 1 (tokens 16-31): hash = 9d2c... ← ¿en cache?
...
Bloque 31 (tokens 496-511): hash = 7e1a... ← ¿en cache?

Si el bloque 0 no hace hit (porque su contenido cambió), los bloques 1-31 tampoco se comprueban aunque sean idénticos — el prefix cache es secuencial.

Auditoría: por qué tu hit rate real es bajo

Antes de cambiar nada, hay que saber qué está rompiendo el hash. El método más directo: extraer los últimos 1000 prompts de producción y calcular qué fracción del prefix varía.

# audit_prefix_cache.py
import langfuse, hashlib, collections
from transformers import AutoTokenizer

client = langfuse.Langfuse()
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-14B-Instruct")

traces = client.fetch_traces(limit=1000).data
prompts = [t.input for t in traces if t.input]

# Tokenizar y extraer los primeros 512 tokens (el system prompt típico)
prefixes = []
for prompt in prompts:
 tokens = tokenizer.encode(prompt, add_special_tokens=False)
 prefix_tokens = tuple(tokens[:512])
 prefixes.append(prefix_tokens)

# ¿Cuántos prefixes únicos hay?
unique = len(set(prefixes))
total = len(prefixes)
print(f"Prefixes únicos: {unique}/{total} ({unique/total*100:.1f}%)")
print(f"Hit rate teórico si todos fueran iguales: {(1 - unique/total)*100:.1f}%")

# Encontrar qué token difiere entre el prefix más común y los demás
from collections import Counter
most_common_prefix = Counter(prefixes).most_common(1)[0][0]

divergence_positions = []
for prefix in prefixes:
 if prefix == most_common_prefix:
 continue
 for i, (a, b) in enumerate(zip(most_common_prefix, prefix)):
 if a != b:
 divergence_positions.append(i)
 break

if divergence_positions:
 pos = Counter(divergence_positions).most_common(1)[0][0]
 token_text = tokenizer.decode([most_common_prefix[pos]])
 print(f"\nDivergencia más frecuente en posición {pos}: '{token_text}'")
 print("→ El token en esa posición varía entre requests")

Los culpables más comunes, en orden de frecuencia:

1. Timestamps y fechas:

# ❌ Rompe el hash en cada request
system = f"Fecha actual: {datetime.now().strftime('%Y-%m-%d %H:%M')}. Eres un asistente..."

# ✅ Sacar la fecha del system prompt
system = "Eres un asistente especializado en infraestructura cloud."
# Pasar la fecha como parte del mensaje del usuario si es necesaria

2. IDs de sesión y usuarios:

# ❌
system = f"Usuario ID: {user_id}. Preferencias: {user_prefs}. Eres un asistente..."

# ✅ Separar lo estático de lo contextual
system = "Eres un asistente especializado." # siempre igual
# Agregar contexto de usuario como primer mensaje del historial

3. Versiones de prompt interpoladas:

# ❌
system = f"[v{PROMPT_VERSION}] Eres un asistente..." # cambia con cada deploy

# ✅ No versionar en el texto, versionar en el nombre del prompt en Langfuse
system = "Eres un asistente..."

4. Few-shots dinámicos:

# ❌ Ejemplos recuperados aleatoriamente de un pool
examples = random.sample(example_pool, k=3)
system = f"Ejemplos:\n{format_examples(examples)}\n\nEres un asistente..."

# ✅ Few-shots fijos ordenados siempre igual
FIXED_EXAMPLES = [example_pool[0], example_pool[1], example_pool[2]]
system = f"Ejemplos:\n{format_examples(FIXED_EXAMPLES)}\n\nEres un asistente..."

Ingeniería de templates: la estructura que maximiza hits

El principio es simple: todo lo estático va antes, todo lo dinámico va después. El prefix cache es secuencial — una vez que un bloque no hace hit, el resto tampoco se busca.

ESTRUCTURA ÓPTIMA para maximizar prefix cache:
┌──────────────────────────────────────────────┐
│ BLOQUE ESTÁTICO (tokens 0-511) │ ← hit rate ~100%
│ System prompt invariante │
│ Instrucciones fijas │
│ Few-shots ordenados siempre igual │
├──────────────────────────────────────────────┤
│ BLOQUE SEMI-ESTÁTICO (tokens 512-1023) │ ← hit rate ~60-80%
│ Documentos RAG para esta sesión │
│ Historial de conversación hasta ahora │
├──────────────────────────────────────────────┤
│ BLOQUE DINÁMICO (tokens 1024+) │ ← hit rate ~0% (esperado)
│ Mensaje actual del usuario │
│ Contexto específico de este request │
└──────────────────────────────────────────────┘

Para RAG específicamente: si los documentos recuperados son los mismos para un conjunto de queries similares (muy frecuente en RAG sobre documentos corporativos fijos), ordenarlos siempre en el mismo orden (por ID, por score fijo, no por score variable) multiplica el hit rate del bloque semi-estático.

Routing prefix-aware: el siguiente nivel

Con una sola instancia de vLLM, el prefix cache funciona automáticamente. El problema aparece con múltiples réplicas: el load balancer distribuye requests round-robin, y el prefix cacheado en la réplica A no sirve de nada cuando el request llega a la réplica B.

La solución es prefix-aware routing: enviar requests con el mismo prefix al mismo nodo.

Con Ray Serve (integración nativa):

# ray_serve_prefix_router.py
from ray import serve
from ray.serve.llm import LLMConfig, build_llm_deployment

@serve.deployment
class PrefixAwareRouter:
 def __init__(self, replicas):
 self.replicas = replicas # lista de handles de vLLM

 async def __call__(self, request):
 body = await request.json()
 messages = body.get("messages", [])

 # Calcular hash del system prompt (prefix estático)
 system_content = ""
 for msg in messages:
 if msg["role"] == "system":
 system_content = msg["content"]
 break

 prefix_hash = hash(system_content)
 # Routing determinístico: mismo hash → mismo nodo
 replica_idx = prefix_hash % len(self.replicas)
 return await self.replicas[replica_idx].remote(request)

Con un gateway L7 (Nginx/Traefik):

# nginx.conf — routing por header X-Prefix-Hash
upstream vllm_backends {
 hash $http_x_prefix_hash consistent;
 server vllm-0:8000;
 server vllm-1:8000;
 server vllm-2:8000;
 server vllm-3:8000;
}

El cliente calcula el hash del prefix estático y lo incluye como header:

import hashlib, requests

def llm_request(messages, base_url):
 system_msg = next((m["content"] for m in messages if m["role"] == "system"), "")
 prefix_hash = hashlib.sha256(system_msg.encode()).hexdigest()[:16]

 return requests.post(
 f"{base_url}/v1/chat/completions",
 json={"messages": messages, "model": "mi-modelo"},
 headers={"X-Prefix-Hash": prefix_hash}
 )

Medir el impacto con OTel

# Hit rate actual (0.0 a 1.0) — objetivo > 0.70 con workloads enterprise
vllm:gpu_prefix_cache_hit_rate

# TTFT por percentil — debe caer cuando el hit rate sube
histogram_quantile(0.50, rate(vllm:time_to_first_token_seconds_bucket[5m]))
histogram_quantile(0.95, rate(vllm:time_to_first_token_seconds_bucket[5m]))

La correlación inversa entre hit rate y TTFT es la prueba de que el cache está funcionando. Si el hit rate sube del 15% al 70% y el TTFT p50 no cambia, hay un problema de configuración: el cache puede estar desactivado o el routing no está enviando los requests al nodo correcto.

Query de correlación en Grafana (panel de dos ejes):

# Eje Y izquierdo: hit rate
vllm:gpu_prefix_cache_hit_rate

# Eje Y derecho: TTFT p50 (invertido)
histogram_quantile(0.50, rate(vllm:time_to_first_token_seconds_bucket[5m]))

La pendiente inversa debe ser visible: cuando el hit rate baja (pico de requests con prompts nuevos), el TTFT sube. Cuando el hit rate se estabiliza (usuarios repitiendo el mismo flujo), el TTFT baja.

El impacto en números

Para un sistema con 100 req/min, system prompt de 512 tokens y hit rate antes/después:

Métrica	Hit rate 15%	Hit rate 75%	Diferencia
Tokens de prefill por minuto	5.100	12.800 — 50% cacheados → 6.400 efectivos	−37% carga
TTFT p50 (prompt 512 + sufijo 100)	~820 ms	~180 ms (sólo sufijo)	−78%
Capacidad de prefill liberada	—	+1.200 tok/min	disponible para más requests

El 75% de hit rate en este ejemplo equivale a poder atender un 37% más de requests con el mismo hardware, porque el trabajo de prefill de 3 de cada 4 requests ya está hecho.

Cuándo el prefix cache no ayuda

El prefix cache es ineficaz en workloads donde cada request tiene un prompt completamente único: traducciones de documentos distintos cada vez, análisis de código con contexto siempre diferente, generación creativa sin sistema. En estos casos, el hit rate estructuralmente no puede superar el 5-10% y el esfuerzo de ingeniería de templates no compensa.

La señal: si tu p99 de longitud de input es mayor que el p50, tienes alta varianza de prompts y el prefix cache aporta poco. Si el p50 y el p99 son similares (prompts consistentes), el prefix cache es la palanca más barata disponible.

Ver también

En esta misma serie

Referencias

Una réplica grande o muchas pequeñas: la decisión que define tu plataforma

Fri, 05 Jun 2026 04:00:00 +0000

TL;DR

Con 4 GPUs disponibles tienes dos opciones básicas: una instancia de vLLM usando las 4 (TP=4) o dos instancias independientes usando 2 cada una (TP=2 × 2 réplicas). La primera da menor latencia por request individual. La segunda da mayor throughput agregado a alta concurrencia, mejor fault tolerance y escala más fino. El punto de cruce —cuando la segunda supera a la primera— está típicamente entre 16 y 64 requests concurrentes para modelos 70B, mucho antes de lo que la mayoría asume. La métrica que lo decide: goodput, los tokens generados dentro del SLO de latencia dividido por el total.

La analogía

Dos formas de organizar un servicio de traducción: un traductor senior con acceso a cuatro diccionarios especializados simultáneamente (puede resolver cualquier consulta compleja en 30 segundos), o dos traductores junior cada uno con dos diccionarios (tardan 45 segundos por consulta compleja, pero pueden atender dos simultáneamente).

Para un cliente que llega solo y espera respuesta rápida: el senior gana. Para una cola de veinte clientes llegando a la vez: los dos juniors procesan el doble de consultas por hora aunque cada una tarde más. La pregunta no es quién es mejor, sino qué tipo de tráfico tienes.

Las dos arquitecturas en vLLM

Arquitectura A: TP=4, una réplica

# Una sola instancia usa las 4 GPUs vía tensor parallelism
vllm serve meta-llama/Meta-Llama-3.1-70B-Instruct \
 --tensor-parallel-size 4 \
 --gpu-memory-utilization 0.92 \
 --port 8000

GPU-0 ─┐
GPU-1 ─┤─ vLLM instance 0 ──► puerto 8000
GPU-2 ─┤ (TP=4, el modelo se
GPU-3 ─┘ reparte entre 4 GPUs)

Cada operación de atención y FFN se divide entre 4 GPUs. Requieren comunicación all-reduce después de cada capa (en NVLink: ~50-200 µs; en PCIe: ~2-8 ms). El modelo completo está disponible en la VRAM agregada.

Arquitectura B: TP=2 × 2 réplicas

# Dos instancias independientes, cada una con 2 GPUs
# Instancia 0 en GPU 0-1
CUDA_VISIBLE_DEVICES=0,1 vllm serve meta-llama/Meta-Llama-3.1-70B-Instruct \
 --tensor-parallel-size 2 --port 8000

# Instancia 1 en GPU 2-3
CUDA_VISIBLE_DEVICES=2,3 vllm serve meta-llama/Meta-Llama-3.1-70B-Instruct \
 --tensor-parallel-size 2 --port 8001

GPU-0 ─┐ ┌─► puerto 8000
GPU-1 ─┘─ vLLM instance 0 ─┘
← load balancer
GPU-2 ─┐ ┌─► puerto 8001
GPU-3 ─┘─ vLLM instance 1 ─┘

Cada instancia tiene la mitad del modelo. Las requests se distribuyen entre instancias. Sin comunicación entre instancias (son completamente independientes).

Por qué TP=4 tiene mayor latencia individual que TP=2

El tensor parallelism divide cada capa del transformer. Después de calcular su fracción, cada GPU necesita sincronizarse con las otras vía all-reduce antes de pasar a la siguiente capa. El coste de esta sincronización:

$$\text{overhead_TP} = n_layers \times 2 \times \text{latencia_allreduce}$$

Para Llama 3 70B (80 capas) en 4×H100 NVLink:

$$\text{overhead_TP4} = 80 \times 2 \times 100,\mu s = 16,ms$$

En PCIe (sin NVLink directo entre GPUs):

$$\text{overhead_TP4_PCIe} = 80 \times 2 \times 3,ms = 480,ms$$

Ese overhead se suma a cada paso de decode. Con TP=2:

$$\text{overhead_TP2} = 80 \times 2 \times 60,\mu s = 9.6,ms \text{ (NVLink)}$$

La diferencia entre TP=2 y TP=4 en NVLink es ~6 ms por paso de decode —relevante para TPOT (inter-token latency) en aplicaciones de streaming.

En PCIe sin NVLink directo: TP=4 puede ser 400 ms más lento por paso que TP=2. Para un output de 200 tokens, eso son 80 segundos adicionales. En este escenario, TP=4 PCIe nunca debe usarse salvo que el modelo no quepa en 2 GPUs.

El punto de cruce: cuándo TP=2×2 supera a TP=4×1

Para un modelo 70B en 4×H100 SXM (NVLink), el throughput agregado en tokens/segundo:

Concurrencia | TP=4 × 1 instancia | TP=2 × 2 instancias | Ganador
──────────────┼──────────────────────┼───────────────────────┼────────
1 | 200 tok/s | 170 tok/s | TP=4 (latencia)
4 | 650 tok/s | 620 tok/s | TP=4 (ligero)
16 | 1.800 tok/s | 2.100 tok/s | TP=2×2
32 | 2.400 tok/s | 3.600 tok/s | TP=2×2 (+50%)
64 | 2.800 tok/s | 5.200 tok/s | TP=2×2 (+86%)
128 | 2.900 tok/s | 5.800 tok/s | TP=2×2 (+100%)

Por qué divergen a alta concurrencia: con TP=4, el scheduler de una sola instancia gestiona todas las requests pero el KV cache es compartido. Con TP=2×2, cada instancia tiene su propio scheduler y KV cache: menos contención, más paralelismo real.

El punto de cruce en NVLink está alrededor de 16-32 requests simultáneos para 70B. Para modelos más pequeños (14B, 7B), el cruce ocurre antes porque el overhead de comunicación TP pesa más relativamente.

Las tres implicaciones que nadie menciona

1. Fault tolerance

Con TP=4 × 1 réplica: si una GPU falla, la instancia entera cae. El servicio baja al 0% hasta que la GPU se recupera o el pod se reinicia en otro nodo.

Con TP=2 × 2 réplicas: si una GPU falla, cae una instancia. El servicio sigue al 50% de capacidad. Para ENS/NIS2 donde la disponibilidad es un requisito contractual, esta diferencia es determinante.

2. Granularidad de autoscaling

Con KEDA o HPA basado en vllm:num_waiting_seqs, el autoscaling debe provisionar en múltiplos de la unidad de deploy:

TP=4 × 1: cada nuevo nodo requiere 4 GPUs. La granularidad mínima de escala es 4 GPUs.
TP=2 × 2: cada nuevo pod requiere 2 GPUs. La granularidad mínima es 2 GPUs — más fino, más eficiente en coste.

3. Degradación de calidad bajo carga

TP=4 con muchos requests concurrentes empieza a tener preemptions cuando el KV cache se llena. TP=2×2 distribuye esa presión entre dos pools independientes de KV cache — la probabilidad de preemption es menor bajo la misma carga total.

Medir el punto de cruce con OTel

El goodput es la métrica correcta para comparar las dos arquitecturas. No el throughput bruto (que ignora el SLO), sino los tokens que se generan dentro del SLO de TPOT acordado:

# Goodput: tokens generados con TPOT dentro del SLO (ej: <50ms/token)
# Para TP=4:
rate(vllm:generation_tokens_total{instance="tp4"}[5m])
 * (1 - histogram_quantile(0.95, rate(vllm:time_per_output_token_seconds_bucket{instance="tp4"}[5m])) > 0.050)

# Para TP=2×2 (suma de las dos instancias):
sum(rate(vllm:generation_tokens_total{instance=~"tp2-.*"}[5m]))
 * (1 - histogram_quantile(0.95, sum(rate(vllm:time_per_output_token_seconds_bucket{instance=~"tp2-.*"}[5m]))) > 0.050)

La comparación directa en el mismo dashboard, con tráfico sintético a distintos niveles de concurrencia, determina el punto de cruce exacto para tu hardware y modelo.

La decisión por perfil de workload

Perfil	Arquitectura recomendada	Razón
Chatbot usuario único / baja concurrencia (<10 simultáneos)	TP=4 × 1	Latencia p50 más baja, experiencia de streaming mejor
API enterprise (20-100 concurrentes)	TP=2 × 2	Goodput superior, fault tolerance, autoscaling más fino
Batch processing (throughput > latencia)	TP=2 × 2 (o más réplicas)	Throughput máximo siempre en réplicas
Modelo muy grande (>80B, no cabe en 2 GPUs)	TP=4 × 1	Sin alternativa estructural
ENS/disponibilidad contractual	TP=2 × 2 mínimo	La caída de una GPU no es catastrófica

Configuración en Kubernetes con ambas arquitecturas

# Deployments paralelos para A/B test o topologías distintas

# Instancias TP=2 (2 réplicas por deployment)
apiVersion: apps/v1
kind: Deployment
metadata:
 name: vllm-tp2
spec:
 replicas: 2
 template:
 spec:
 containers:
 - name: vllm
 args: ["serve", "meta-llama/Meta-Llama-3.1-70B-Instruct",
 "--tensor-parallel-size", "2",
 "--gpu-memory-utilization", "0.92"]
 resources:
 limits:
 nvidia.com/gpu: "2" # 2 GPUs por pod
---
# Service con load balancing entre las 2 réplicas
apiVersion: v1
kind: Service
metadata:
 name: vllm-tp2
spec:
 selector:
 app: vllm-tp2
 ports:
 - port: 8000
 sessionAffinity: ClientIP  # para prefix cache awareness
 sessionAffinityConfig:
 clientIP:
 timeoutSeconds: 10800 # 3 horas de afinidad por sesión

La sessionAffinity: ClientIP en el Service de Kubernetes es la forma más sencilla de implementar routing con afinidad por sesión — las requests del mismo cliente van siempre a la misma réplica, maximizando el hit rate del prefix cache del historial de conversación.

Ver también

el grid search de max-num-seqs cambia con la arquitectura: una réplica grande tolera max-num-seqs más alto que dos pequeñas con el mismo KV cache total
el routing por sesión (sessionAffinity) es la implementación K8s del prefix-aware routing: mismo cliente, misma réplica, mismo cache
KEDA escala en unidades de pod; TP=2×2 da granularidad de 2 GPUs vs 4 GPUs para TP=4×1, impactando el coste del autoscaling reactivo
goodput calculado sobre generation_tokens_total y time_per_output_token_seconds son las métricas que comparan las dos arquitecturas
el siguiente nivel de separación cuando ni TP=4×1 ni TP=2×2 son suficientes: separar el hardware de prefill del de decode
FP8 libera VRAM en cada réplica; combinado con TP=2×2, el impacto se multiplica: más concurrencia por réplica y más réplicas posibles
NVLink, NVSwitch y NCCL: el cable por el que pasa cada token — por qué el límite del NVLink dibuja la frontera de esta decisión: el all-reduce por capa que el TP paga es barato sobre NVSwitch y carísimo sobre PCIe.

Referencias

Debezium y CDC: el notario que escucha los cambios antes de que nadie los pida

Thu, 04 Jun 2026 11:00:00 +0200

TL;DR

Change Data Capture (CDC) con Debezium escucha el Write-Ahead Log de PostgreSQL y convierte cada INSERT, UPDATE y DELETE en un evento Kafka estructurado. A diferencia del polling tradicional (SELECT ... WHERE updated_at > ?), detecta borrados, tiene latencia de decenas de milisegundos y no añade carga extra a la base de datos. En pipelines RAG, esto significa que cuando se borra un documento de Postgres, los chunks de Qdrant desaparecen también —automáticamente, en tiempo real—. La infraestructura de soporte es modesta: el connector consume 2-4 cores y 4-8 GB RAM para procesar miles de eventos por segundo.

La analogía maestra: el notario del registro de la propiedad

Imagina el Registro de la Propiedad. Cada vez que se vende un piso, se hipoteca, o se cancela una hipoteca, el registrador anota la operación en el libro del registro —un diario cronológico e inmutable. Si quieres saber qué ha cambiado en el registro, tienes dos opciones:

Opción A (polling): envías a alguien cada 5 minutos con una lista de fincas a preguntar «¿ha cambiado algo?». Problemas: si se canceló una titularidad (DELETE), la finca ya no existe cuando tu enviado llega —no hay rastro—. Si hay 20 departamentos distintos haciendo lo mismo, hay 20 personas molestando al registrador cada 5 minutos. Y la latencia mínima es el intervalo: 5 minutos.

Opción B (Debezium): contratas a un notario que se sienta directamente en la mesa del registrador. Cada vez que el registrador firma una operación en el libro, el notario la anota al momento y notifica a quien corresponda. Cancelación de titularidad incluida —el notario la ve tan claro como cualquier otra operación, porque estaba allí cuando se firmó—.

En esta analogía:

El libro del registro es el WAL (Write-Ahead Log) de PostgreSQL.
El notario es el Debezium connector.
El marcapáginas del notario —que garantiza que no pierde ninguna página aunque salga un momento— es el slot de replicación lógica.
El mensajero que lleva las notificaciones a los interesados es Kafka (o Redpanda, o NATS JetStream).

Este hilo lo vamos a retomar en cada sección. Cuando algo no quede claro en los detalles técnicos, vuelve a la imagen del notario.

1. El problema que CDC resuelve

El patrón de sincronización más habitual entre servicios que comparten PostgreSQL es el polling periódico:

SELECT id, content, updated_at
FROM documents
WHERE updated_at > $1
ORDER BY updated_at
LIMIT 1000;

Este patrón tiene tres problemas estructurales:

Los DELETEs son invisibles. Cuando borras una fila, updated_at no se actualiza —la fila desaparece—. La próxima vez que el poller consulte, la fila no existe y no hay forma de saber que existió. En un pipeline RAG, esto se traduce en chunks huérfanos en Qdrant: el documento ya no existe en Postgres, pero sus vectores siguen contaminando los resultados de búsqueda.

La latencia mínima es el intervalo. Si el poller corre cada 5 segundos, la latencia media es 2,5 segundos. Para sincronización near-real-time (dashboards, alertas, RAG con documentos que cambian frecuentemente) esto es demasiado.

La carga escala con el número de consumidores. Si 10 servicios hacen polling cada 5 segundos sobre la misma tabla, son 10 × 12 = 120 queries/minuto que no producen trabajo útil —solo verifican si hay algo nuevo—. En tablas grandes con índices complejos, esto es carga real en la base de datos.

CDC invierte el modelo: la base de datos notifica, los consumidores escuchan. Cero polling, cero carga extra, DELETEs incluidos, latencia de decenas de milisegundos.

2. Qué es el WAL de PostgreSQL

El diario de operaciones

El Write-Ahead Log (WAL) es el registro cronológico e inmutable de todas las operaciones que Postgres realiza. Antes de modificar cualquier página de datos en disco, Postgres escribe la operación en el WAL. Esta secuencia —primero el log, luego los datos— es lo que garantiza la durabilidad (D de ACID) y permite el crash recovery: si Postgres cae a mitad de una transacción, al reiniciar replaye el WAL para devolver la base de datos a un estado consistente.

El WAL es el libro del registro de nuestra analogía: cronológico, inmutable, completo.

Replicación física vs. lógica

PostgreSQL soporta dos modos de replicación basados en el WAL:

Replicación física: replica bloques de disco tal cual. El standby recibe los mismos bytes que el primario. Sirve para high availability y failover, pero el destino debe ser una copia exacta de Postgres —no puedes enviar los cambios a una aplicación externa—.
Replicación lógica: en vez de bloques de disco, replica operaciones semánticas: «se insertó la fila con id=42 en la tabla documents con estos valores». El destino puede ser cualquier cosa que entienda el protocolo: otro Postgres, Debezium, o cualquier consumer personalizado.

CDC usa replicación lógica. Es la que permite que Debezium entienda «qué cambió y en qué tabla» en lugar de «qué bloque de disco cambió en qué offset».

El slot de replicación: el marcapáginas del notario

Un slot de replicación lógica es un cursor persistente en el WAL. Postgres mantiene un registro de hasta qué posición del WAL ha consumido cada slot. Mientras un slot existe, Postgres garantiza que no descarta los segmentos WAL que el slot aún no ha leído.

Esto es exactamente el marcapáginas del notario: aunque el notario salga a comer, el libro permanece abierto en la última página que leyó. Cuando vuelve, continúa exactamente donde lo dejó, sin haber perdido nada.

El riesgo es el inverso: si el notario no vuelve, el marcapáginas impide que el registrador archive las páginas antiguas. Si el Debezium connector se cae y no se recupera durante horas, el WAL crece indefinidamente en disco hasta que el slot se elimine manualmente o el consumer vuelva a consumir. Esto se llama WAL disk blowup y es el riesgo operacional más importante de Debezium.

Monitorización obligatoria:

SELECT slot_name,
 confirmed_flush_lsn,
 pg_current_wal_lsn(),
 pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn) AS lag_bytes
FROM pg_replication_slots
WHERE slot_type = 'logical';

El plugin pgoutput

El WAL almacena las operaciones en formato binario interno. Para que Debezium las entienda, Postgres necesita decodificarlas en un formato legible. El plugin de decodificación pgoutput —incluido en el core de Postgres desde la versión 10— hace exactamente esto: traduce los eventos binarios del WAL en mensajes con la estructura antes/después de cada fila.

Debezium usa pgoutput por defecto. No requiere instalar extensiones externas (a diferencia del plugin wal2json que fue popular antes de Postgres 10).

3. Arquitectura de Debezium

El connector como plugin de Kafka Connect

Debezium no es un servicio standalone —es un plugin del framework Kafka Connect. Kafka Connect gestiona el ciclo de vida del connector (arranque, parada, reconexión, offset tracking) y provee la infraestructura de paralelismo y fault tolerance.

El connector se comunica con Postgres a través del protocolo de replicación lógica (no por JDBC), usando las credenciales de un usuario con rol REPLICATION.

PostgreSQL (WAL + pgoutput)
│
│ protocolo de replicación lógica
▼
Debezium Connector (Kafka Connect worker)
│
│ Kafka Producer API
▼
Kafka topic: rag.public.documents
│
▼
Consumer (sync a Qdrant, audit log, fine-tuning pipeline...)

Estructura de un evento Debezium

Cada cambio en la tabla se convierte en un mensaje JSON con esta estructura:

INSERT ("op": "c" — create):

{
 "before": null,
 "after": {
 "id": 42,
 "content": "Contrato de arrendamiento...",
 "tenant_id": "acme",
 "updated_at": 1748934000000
 },
 "op": "c",
 "source": {
 "version": "2.7.0.Final",
 "connector": "postgresql",
 "db": "rag_db",
 "schema": "public",
 "table": "documents",
 "lsn": 29823948,
 "txId": 1047,
 "ts_ms": 1748934000123
 }
}

DELETE ("op": "d"):

{
 "before": {
 "id": 42,
 "content": "Contrato de arrendamiento...",
 "tenant_id": "acme",
 "updated_at": 1748934000000
 },
 "after": null,
 "op": "d",
 "source": { "lsn": 29824102, "txId": 1051, "ts_ms": 1748934060200 }
}

El campo before contiene el estado anterior de la fila —disponible porque Postgres puede configurar REPLICA IDENTITY FULL para incluir la fila completa en el WAL al borrar/actualizar—. Sin esta configuración, before solo contiene la clave primaria.

Esta es la clave para el pipeline RAG: el evento DELETE lleva el id del documento. El consumer lo usa para borrar todos los chunks asociados en Qdrant con un filtro doc_id = 42. Sin CDC, esos chunks nunca se habrían borrado.

Snapshot inicial

Cuando el connector arranca por primera vez (o tras un reset), no puede empezar a consumir el WAL desde «el principio de los tiempos» —solo desde el momento en que se crea el slot—. ¿Cómo garantiza la consistencia del estado inicial?

Mediante un snapshot transaccional: el connector abre una transacción en modo REPEATABLE READ, exporta el snapshot ID (pg_export_snapshot()), y hace un SELECT completo de las tablas configuradas dentro de esa transacción. Después empieza a consumir el WAL desde el LSN del snapshot. Así no hay gap: el snapshot cubre el estado hasta un instante, y el WAL cubre desde ese instante en adelante.

Transformaciones SMT (Single Message Transforms)

Antes de emitir el evento al topic de Kafka, el connector puede aplicar transformaciones inline llamadas SMT. Casos de uso habituales:

Filtrar columnas sensibles (ReplaceField con blacklist): eliminar password_hash, phone_number antes de que lleguen al topic.
Añadir metadata (InsertField): enriquecer el evento con tenant_id extraído del header HTTP original (si está en la fila).
Ruting condicional (Filter): descartar eventos de filas con status = 'draft' antes de emitirlos.

Las SMT son configuración pura —no requieren código— y se aplican dentro del proceso del connector, sin latencia adicional perceptible.

4. Debezium vs Outbox pattern

El Outbox pattern es la alternativa más común a CDC puro. La aplicación, en lugar de emitir eventos directamente a Kafka, escribe en una tabla outbox de Postgres dentro de la misma transacción que modifica los datos. Un worker separado lee esa tabla y publica los eventos.

Criterio	Debezium (CDC puro)	Outbox pattern
Latencia del evento	~50-200 ms desde el commit	Depende del intervalo del worker (típico: 1-5 s)
Consistencia	At-least-once	At-least-once
Detección de DELETEs	Nativa (el evento DELETE incluye `before`)	Solo si la app escribe en outbox al borrar
Complejidad de setup	Alta (Kafka Connect, slot de replicación, permisos)	Baja (tabla extra + worker simple)
Dependencia de infraestructura	Requiere Kafka/Redpanda/NATS JetStream	Solo Postgres + worker; Kafka opcional
Riesgo WAL disk blowup	Sí, si el slot deja de consumir	No
Visibilidad del esquema	Lee el esquema real de la tabla	El esquema del evento lo define la app
Migración de esquema	Requiere cuidado (los eventos reflejan DDL changes)	Más flexible (el evento es lo que la app pone)
Cuándo usarlo	Cuando necesitas DELETEs, latencia baja o no puedes modificar la app	Cuando la app controla el dominio del evento y la infraestructura es limitada

Regla práctica: si controlas el código de la aplicación y no necesitas DELETEs nativos, el Outbox es más simple. Si no controlas el código (base de datos legacy, aplicación de terceros) o los DELETEs son críticos (pipeline RAG con borrado de documentos), Debezium es la elección correcta.

5. Matemáticas

Throughput

Debezium en un connector con 4 workers puede procesar entre 10.000 y 50.000 eventos/segundo en hardware modesto (4 cores, 8 GB RAM). El cuello de botella real no es el connector sino el broker de Kafka: con 3 brokers y particiones adecuadas, Kafka puede sostener fácilmente 500.000 mensajes/segundo con mensajes de 1 KB (fuente: benchmarks públicos de Confluent, 2023).

Para un pipeline RAG típico con 100 documentos modificados por minuto:

$$\text{eventos/s} = \frac{100}{60} \approx 1{,}7 \text{ eventos/s}$$

Esto es el 0,0034% de la capacidad del connector. Debezium no será el cuello de botella en ningún escenario RAG realista.

Latencia end-to-end

El camino de un commit en Postgres hasta un upsert en Qdrant tiene estas etapas:

Etapa	Latencia típica
Commit en Postgres → WAL escrito	< 1 ms (sincrónico al commit)
WAL escrito → Debezium lo lee (WAL lag)	10-50 ms
Debezium → Kafka produce (ack)	5-20 ms
Kafka → Consumer (poll interval)	0-100 ms (configurable)
Consumer → Qdrant upsert/delete	5-15 ms
Total típico	30-200 ms

Con fetch.min.bytes=1 y fetch.max.wait.ms=10 en el consumer, la latencia del Kafka poll se reduce a ~10 ms. El rango realista para un pipeline optimizado es 30-100 ms.

Riesgo de WAL disk blowup

Si el connector deja de consumir, Postgres retiene el WAL a partir del confirmed_flush_lsn del slot. El volumen retenido crece linealmente con el tiempo y la tasa de escrituras:

$$\text{WAL retenido} = \text{tasa de escrituras} \times \text{tamaño medio del evento WAL} \times \text{tiempo sin consumir}$$

Ejemplo con carga moderada (50.000 escrituras/hora, 500 bytes de media por evento WAL):

$$50{.}000 \times 500 \text{ B} \times 1 \text{ h} = 25 \text{ MB/h}$$

Con carga alta (1.000.000 escrituras/hora):

$$1{.}000{.}000 \times 500 \text{ B} \times 1 \text{ h} = 500 \text{ MB/h}$$

Si el connector está caído durante 48 horas con carga alta: 24 GB de WAL retenido. Esto puede llenar el disco y bloquear completamente Postgres.

Alerta recomendada: configurar una alerta cuando lag_bytes > 1 GB o cuando confirmed_flush_lsn no avanza durante más de 15 minutos. Ver la query de monitorización en la sección 2.

6. Casos de uso en LLMOps / RAG

Sincronización RAG con borrado real

Este es el caso de uso que más claramente justifica Debezium sobre el polling. El flujo:

Un usuario borra el documento id=42 de la interfaz de gestión documental.
Postgres ejecuta DELETE FROM documents WHERE id = 42.
Debezium detecta el DELETE en el WAL, emite el evento con "op": "d" y "before": {"id": 42, ...}.

El consumer recibe el evento y ejecuta:

qdrant_client.delete(
 collection_name="documents",
 points_selector=Filter(must=[FieldCondition(key="doc_id", match=MatchValue(value=42))])
)

Todos los chunks con doc_id=42 desaparecen de Qdrant en ~100 ms.

Sin Debezium, esos chunks permanecerían indefinidamente, contaminando los resultados de retrieval con fragmentos de documentos que ya no existen en la fuente de verdad.

Event sourcing para datasets de fine-tuning

Cada vez que un anotador humano actualiza una fila en la tabla annotations (corrigiendo un output del LLM), Debezium emite el UPDATE con before y after. El consumer escribe el par (output_original, corrección) en el pipeline de curación de datasets, sin necesidad de que el anotador haga nada más allá de guardar en la interfaz. El pipeline de fine-tuning sabe exactamente qué cambió y cuándo —sin polling, sin riesgo de duplicados por ventanas de tiempo solapadas—.

Audit log inmutable

Los eventos del WAL son, por definición, el registro más fiel de lo que ocurrió en la base de datos —son los mismos datos que Postgres usa para crash recovery—. Kafka con retention larga (90 días, o retención por tamaño) sirve de audit log inmutable sin modificar el esquema de la aplicación ni añadir triggers. Esto es especialmente útil en entornos regulados donde se requiere trazabilidad de modificaciones de datos.

7. Diagrama de arquitectura

8. Configuración mínima

PostgreSQL: activar replicación lógica

-- Requiere reiniciar Postgres
ALTER SYSTEM SET wal_level = logical;
ALTER SYSTEM SET max_replication_slots = 10;
ALTER SYSTEM SET max_wal_senders = 10;

-- Recargar configuración (wal_level requiere restart completo)
SELECT pg_reload_conf();

-- Usuario dedicado para Debezium
CREATE USER debezium WITH REPLICATION LOGIN PASSWORD 'cambiar_esto';
GRANT SELECT ON TABLE public.documents TO debezium;

-- REPLICA IDENTITY FULL para tener 'before' completo en DELETEs y UPDATEs
ALTER TABLE public.documents REPLICA IDENTITY FULL;

Debezium connector (Kafka Connect REST API)

{
 "name": "postgres-debezium",
 "config": {
 "connector.class": "io.debezium.connector.postgresql.PostgresConnector",
 "database.hostname": "postgres",
 "database.port": "5432",
 "database.user": "debezium",
 "database.password": "cambiar_esto",
 "database.dbname": "rag_db",
 "topic.prefix": "rag",
 "table.include.list": "public.documents",
 "plugin.name": "pgoutput",
 "slot.name": "debezium_rag",
 "publication.autocreate.mode": "filtered",
 "snapshot.mode": "initial",
 "tombstones.on.delete": "true",
 "transforms": "unwrap",
 "transforms.unwrap.type": "io.debezium.transforms.ExtractNewRecordState",
 "transforms.unwrap.drop.tombstones": "false",
 "transforms.unwrap.delete.handling.mode": "rewrite"
 }
}

Registrar el connector:

curl -X POST http://kafka-connect:8083/connectors \
 -H 'Content-Type: application/json' \
 -d @connector-config.json

Verificar estado:

curl http://kafka-connect:8083/connectors/postgres-debezium/status

Consumer mínimo en Python

from confluent_kafka import Consumer
from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchValue
import json

consumer = Consumer({
 "bootstrap.servers": "kafka:9092",
 "group.id": "qdrant-sync",
 "auto.offset.reset": "earliest",
 "enable.auto.commit": False,
})
consumer.subscribe(["rag.public.documents"])
qdrant = QdrantClient("qdrant", port=6333)

while True:
 msg = consumer.poll(timeout=0.1)
 if msg is None:
 continue
 event = json.loads(msg.value())
 op = event.get("op")
 if op in ("c", "u"): # INSERT o UPDATE
 doc = event["after"]
 # ... vectorizar y upsert en Qdrant
 elif op == "d": # DELETE
 doc_id = event["before"]["id"]
 qdrant.delete(
 collection_name="documents",
 points_selector=Filter(
 must=[FieldCondition(key="doc_id", match=MatchValue(value=doc_id))]
 )
 )
 consumer.commit()

9. Despliegue on-premise

El stack Debezium no compite por GPU. En un nodo con 4×H100 SXM (320 GB, NVLink) sirviendo el LLM de inferencia, el pipeline CDC corre enteramente en nodos de propósito general (CPU-only):

Componente	Recursos recomendados	Rol
Kafka Connect + Debezium	2-4 cores, 4-8 GB RAM	Leer WAL, emitir eventos
Kafka brokers (×3)	4 cores, 32 GB RAM c/u	Alta disponibilidad, retención
Consumer Qdrant-sync	2 cores, 4 GB RAM	Vectorizar + upsert/delete
Qdrant	8 cores, 64 GB RAM	Vector store

El Debezium connector es notablemente ligero: en producción con 10.000 eventos/segundo, el connector consume habitualmente menos de 1 core y 2 GB de RAM. La memoria de la JVM (Kafka Connect corre en JVM) debe limitarse explícitamente con -Xmx4g para evitar que el GC cause pausas.

Para alta disponibilidad, Kafka Connect soporta modo distribuido con múltiples workers. Si un worker cae, el connector se reasigna automáticamente a otro worker en segundos —el slot de replicación garantiza que no se pierden eventos durante la conmutación—.

Lo que no hemos cubierto

Debezium con MySQL, MongoDB y Oracle: cada conector usa el mecanismo de log nativo (binlog en MySQL, oplog en MongoDB, LogMiner en Oracle). La API de eventos resultante es similar, pero los detalles de configuración y las limitaciones difieren.
Debezium Server: modo standalone sin Kafka Connect, con sinks directos a HTTP, S3, Redis Streams o NATS. Útil cuando la infraestructura de Kafka es demasiado compleja para el caso de uso.
Schema Registry: cómo Avro con Confluent Schema Registry o Apicurio gestiona la evolución del esquema de los eventos —añadir columnas, cambiar tipos— sin romper a los consumers existentes.
Exactly-once semantics: por qué at-least-once es suficiente para la mayoría de casos RAG (un upsert idempotente en Qdrant con el mismo vector no hace daño) y cuándo se necesita exactly-once (contadores financieros, deducciones de inventario).
Outbox pattern + Debezium combinados: Debezium leyendo la tabla outbox en lugar del WAL de la tabla de negocio directamente —el patrón Transactional Outbox + CDC que combina lo mejor de ambos mundos—.

Ver también

PostgreSQL + Qdrant: ingestión por microservicios — el post donde CDC con Debezium se usa como alternativa al outbox pattern para mantener sincronizados PostgreSQL y Qdrant.
RAG corpus curation: fundamentos — la curación del corpus que Debezium mantiene fresco en near-real-time.
Pipeline LLMOps: las seis etapas — la etapa Data del mapa maestro donde CDC es el mecanismo de ingestión continua.
Data versioning con DVC y lakeFS — versioning del corpus que Debezium alimenta incrementalmente.
Observabilidad GPU con DCGM y LLM — monitorización del cluster donde corre el consumer de Debezium junto al stack de inferencia.

Referencias

Debezium Documentation — PostgreSQL Connector. debezium.io/documentation/reference/stable/connectors/postgresql.html
PostgreSQL Documentation — Logical Replication. postgresql.org/docs/current/logical-replication.html
PostgreSQL Documentation — Write-Ahead Logging. postgresql.org/docs/current/wal-intro.html
PostgreSQL Documentation — Replication Slots. postgresql.org/docs/current/logicaldecoding-explanation.html
Confluent — Kafka Performance Benchmarks (2023). confluent.io/blog/kafka-fastest-messaging-system
Gunnar Morling — Outbox Pattern. morling.dev/blog/sending-messages-as-part-of-database-transactions
Debezium — SMT documentation. debezium.io/documentation/reference/stable/transformations
Qdrant Documentation — Filtering. qdrant.tech/documentation/concepts/filtering

Function calling y tool-augmented retrieval: el detective que sabe qué archivo pedir

Thu, 04 Jun 2026 10:00:00 +0200

Este post profundiza en el mecanismo de razonamiento agentivo que extiende el RAG descrito en RAG con reranker e hybrid retrieval. El retriever que se invoca cuando el LLM elige vector_search es exactamente el pipeline de ese artículo. El JSON Schema que define cada tool call es structured output aplicado a la interfaz herramienta. Y las requests del agente pasan por el gateway L7 de inferencia antes de llegar al modelo.

TL;DR

Un RAG naive consulta siempre la misma fuente. Function calling le da al LLM la capacidad de decidir qué herramienta invocar — vector store, SQL, web search — en función de lo que la query realmente necesita. El patrón ReAct encadena esas invocaciones en un bucle razonado hasta obtener suficiente evidencia. Un pipeline de 3 iteraciones con Llama-3.1-70B en hardware on-premise tarda ≈ 1,1 s frente a los ≈ 300 ms del RAG de un solo paso; la ganancia no es en velocidad sino en queries que el RAG naive simplemente no puede responder. La métrica de eval crítica es tool selection accuracy: el porcentaje de turns en que el modelo elige el tool correcto, medida sobre un eval set sintético.

La analogía: el detective que sabe qué archivo pedir

Un detective de novela no va al mismo archivador independientemente del caso que le llegue. Cuando recibe un caso, razona primero: ¿qué tipo de evidencia necesito? Si hay testigos, pide los testimonios (vector search sobre documentos no estructurados). Si hay transacciones financieras, pide los registros contables al banco (SQL sobre la base de datos estructurada). Si el sospechoso tiene actividad reciente que la empresa no puede tener indexada, va a la hemeroteca (web search). No consulta las tres fuentes de golpe en cada caso: elige la que la evidencia requiere, recibe el resultado, razona de nuevo si necesita más, y sólo cuando tiene suficiente evidencia redacta el informe.

Un detective malo siempre va al mismo archivador. Un RAG naive es ese detective malo: vectoriza la query, va al vector store, y devuelve lo que encuentra aunque la pregunta fuera “¿cuántos contratos?” — algo que ningún chunk de PDF puede responder mejor que un COUNT(*) en SQL.

Function calling es darle al LLM la capacidad de razonar sobre qué fuente pedir, y de invocarla de forma estructurada. La analogía tiene tres aristas que conviene retener:

El detective no improvisa el archivo que pide: hay un catálogo de fuentes disponibles con descripción de qué contiene cada una. La descripción del tool en el system prompt cumple esa función.
El detective puede pedir varias evidencias a la vez si son independientes (parallel tool calling).
El detective sabe cuándo parar: si tras N rondas no llega a conclusión, declara que no tiene suficiente evidencia. El agente tiene un límite de iteraciones por la misma razón.

Qué es function calling: la anatomía de una tool call

Function calling — también llamado tool use — es un mecanismo por el que el LLM, en vez de generar texto libre como respuesta, genera un objeto JSON estructurado que representa una invocación de herramienta. El sistema intercepta ese JSON, ejecuta la herramienta real, y devuelve el resultado como un mensaje de rol tool en la conversación.

Definición de tools en el system prompt

Cada tool se define mediante un JSON Schema que especifica nombre, descripción y parámetros. Este JSON Schema es exactamente el mismo mecanismo descrito en structured output, aplicado aquí a la interfaz herramienta:

{
 "tools": [
 {
 "name": "vector_search",
 "description": "Search internal company documents about policies, contracts and procedures. Use when the query requires unstructured text, document context or semantic similarity.",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string", "description": "Natural language search query"},
 "top_k": {"type": "integer", "default": 5}
 },
 "required": ["query"]
 }
 },
 {
 "name": "sql_query",
 "description": "Query the SQL database for structured metrics, counts, aggregations and financial data. Use when the query requires exact numbers, filters, sums or joins over structured records.",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string", "description": "Parameterized SQL query with $1, $2 placeholders"},
 "params": {"type": "array", "items": {}, "description": "Parameter values for the placeholders"}
 },
 "required": ["query"]
 }
 },
 {
 "name": "web_search",
 "description": "Search public web for real-time information, recent news or current prices. Use only when data is public and not covered by internal sources.",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string"}
 },
 "required": ["query"]
 }
 }
 ]
}

El ciclo de una tool call

Cuando el LLM decide invocar una tool, el mensaje que genera en lugar de texto libre tiene esta estructura (formato OpenAI-compatible, el mismo que soporta vLLM):

{
 "role": "assistant",
 "tool_calls": [
 {
 "id": "call_01",
 "type": "function",
 "function": {
 "name": "sql_query",
 "arguments": "{\"query\": \"SELECT COUNT(*), SUM(amount) FROM contracts WHERE amount > $1 AND year = $2 AND provider_region = $3\", \"params\": [100000, 2025, \"EU\"]}"
 }
 }
 ]
}

El sistema ejecuta la tool y devuelve:

{"role": "tool", "tool_call_id": "call_01", "content": "{\"count\": 47, \"total\": 8300000}"}

El LLM recibe ese mensaje como continuación de la conversación y decide si necesita más información o puede generar la respuesta final.

Soporte en modelos OSS

En 2026, el soporte de function calling nativo (no emulado vía system prompt) está disponible en:

Llama 3.1 / 3.3+: formato de tool call nativo, soportado en vLLM con --enable-auto-tool-choice --tool-call-parser llama3_json
Qwen 2.5+: soporte nativo con --tool-call-parser hermes
Mistral NeMo / Mistral 7B Instruct v0.3+: formato nativo con --tool-call-parser mistral
Qwen3 (2025+): soporte nativo extendido con parallel tool calling

Sin --enable-auto-tool-choice, vLLM puede forzar el formato de tool call vía guided decoding (JSON Schema), pero la capacidad de decidir cuándo invocar una tool vs generar texto libre requiere entrenamiento específico del modelo.

El patrón ReAct: Reasoning + Acting

ReAct (Yao et al., 2022) es el bucle que convierte un LLM con tools en un agente con razonamiento. La idea central es que el modelo intercala pensamientos (razonamiento explícito sobre qué hacer) con acciones (invocación de tools) y observaciones (resultados recibidos). Este bucle se repite hasta que el modelo estima tener suficiente información para responder, o hasta que se alcanza el límite de iteraciones.

Thought → Action → Observation → Thought → Action → Observation → ... → Response

Trace ReAct completo: una query de producción real

Query: "¿Cuántos contratos de más de 100k€ firmamos en 2025 con proveedores de la UE, y cuáles son las condiciones especiales que se repiten?"

Esta query requiere dos fuentes distintas: los números exactos viven en SQL, y el contexto de condiciones especiales vive en los PDFs de contratos indexados en el vector store.

Iteración 1

Thought: La query pide datos agregados (conteo y suma) con filtros exactos sobre campos estructurados (importe, año, región). Esto es una consulta SQL, no una búsqueda semántica.

Action: sql_query

SELECT COUNT(*) AS num_contratos, SUM(amount) AS total_eur
FROM contracts
WHERE amount > $1 AND year = $2 AND provider_region = $3

params: [100000, 2025, "EU"]

Observation: {"num_contratos": 47, "total_eur": 8300000}

Iteración 2

Thought: Tengo los números. Ahora necesito las condiciones especiales que se repiten en estos contratos. Ese tipo de información está en el texto libre de los PDFs, no en la tabla estructurada. Voy al vector store.

Action: vector_search

"contratos proveedores UE 2025 importe superior 100k condiciones especiales cláusulas recurrentes"

top_k: 5

Observation:

[chunk_1] Contrato Proveedor A — cláusula 8.3: penalización por retraso del 2% mensual sobre el importe facturado...
[chunk_2] Contrato Proveedor C — cláusula 7.1: revisión de precios vinculada al IPC de la zona euro con tope del 4% anual...
[chunk_3] Contrato Proveedor B — cláusula 8.3: penalización por retraso del 2% mensual...

Thought: Tengo datos suficientes de ambas fuentes. La cláusula 8.3 de penalización por retraso aparece en al menos dos contratos de los recuperados. Puedo sintetizar la respuesta.

Response: “En 2025 firmasteis 47 contratos con proveedores de la UE por importe superior a 100.000 €, con un total acumulado de 8,3 M€. La condición especial que aparece con más frecuencia en los contratos de mayor valor es la cláusula de penalización por retraso (8.3 en los modelos de contrato de Proveedor A y B): 2% mensual sobre importe facturado. También se repite la revisión de precios vinculada al IPC de la zona euro con tope del 4% anual (cláusula 7.1).”

Este trace tiene 2 iteraciones. Una query más compleja (comparar con el año anterior, cruzar con estado de pago) añadiría iteraciones adicionales. La práctica habitual es fijar un límite de 5–10 iteraciones máximo para evitar bucles.

Las tres fuentes y cuándo usar cada una

La elección de fuente no es arbitraria ni queda sólo en manos del LLM: la arquitectura define qué tools existen y cómo se describen. La tabla siguiente resume los criterios de selección:

Característica	Vector store (Qdrant)	SQL / estructurado (PostgreSQL)	Web search
Tipo de dato	Texto libre, documentos, PDFs	Tablas con esquema fijo	Páginas públicas, noticias
Estructura	No estructurado	Altamente estructurado	Semi-estructurado
Temporalidad	Índice estático (actualización periódica)	Tiempo real (transaccional)	Tiempo real (crawl)
Latencia típica	5–50 ms	10–200 ms	200–2.000 ms
Privacidad	Datos internos, soberanía total	Datos internos, soberanía total	Solo datos públicos
Query natural	Sí (lenguaje natural → embedding)	No (SQL parametrizado)	Sí
Agregaciones exactas	No	Sí (`COUNT`, `SUM`, `GROUP BY`)	No
Cuándo usar	Contexto documental, semántica, PDFs	Métricas, conteos, filtros exactos, joins	Datos que no existen internamente y son públicos

La regla práctica más importante: si la pregunta contiene palabras como “cuántos”, “suma”, “total”, “más de X”, “en el año Y” y los datos están en una tabla estructurada, la respuesta correcta es sql_query. Si la pregunta pide contexto, explicaciones, cláusulas, procedimientos o ejemplos de documentos, la respuesta es vector_search. Si pide el precio actual de algo o noticias recientes sobre un tercero, web_search — pero sólo si no hay soberanía de datos implicada.

Tool routing: cómo el LLM elige el tool correcto

La descripción de cada tool en el system prompt es el factor más crítico para la precisión del routing. Un LLM con buenas capacidades de function calling puede elegir mal si las descripciones son ambiguas o se solapan.

Descripciones que funcionan vs las que no

Descripción débil (lleva al LLM a usar el tool equivocado):

"search_docs" — Busca información en las fuentes disponibles.
"query_data" — Obtiene datos del sistema.

Descripción fuerte (delimita con precisión cuándo usar cada uno):

"vector_search" — Search internal company documents about policies, contracts and procedures.
Use when the query requires unstructured text, document context or semantic
similarity. NOT for counts, sums or exact filters.
"sql_query" — Query the SQL database for structured metrics, counts, aggregations and
financial data. Use when the query requires exact numbers, filters, sums or
joins over structured records. NOT for finding document context.

La diferencia está en dos elementos: (1) ejemplos de casos de uso positivos, y (2) exclusiones explícitas con NOT for. Ambos reducen el solapamiento semántico entre tools y mejoran la tool selection accuracy.

Parallel tool calling

Cuando dos tools son independientes entre sí — es decir, el resultado de una no afecta a la query de la otra — el LLM puede invocarlas simultáneamente en el mismo turno:

{
 "tool_calls": [
 {"id": "call_01", "function": {"name": "sql_query", "arguments": "..."}},
 {"id": "call_02", "function": {"name": "vector_search", "arguments": "..."}}
 ]
}

El sistema ejecuta ambas en paralelo y devuelve ambas observaciones antes del siguiente turno del LLM. Esto reduce la latencia total cuando las queries son independientes: en vez de 2 iteraciones secuenciales (2 × latencia_tool), se paga 1 × max(latencia_sql, latencia_vector). Para el ejemplo del detective: si necesita tanto los registros contables como los testimonios para responder, puede pedirlos a la vez.

Tool selection accuracy: la métrica de eval

La tool selection accuracy es el porcentaje de turns en que el LLM elige el tool correcto dado un conjunto de queries evaluadas:

[ \text{TSA} = \frac{\text{turns con tool correcto elegido}}{\text{total turns con tool call esperada}} ]

Se mide sobre un eval set sintético construido con triples (query, tool_esperado, args_esperados). Un ejemplo de eval set mínimo:

Query	Tool esperado	Indicador de fallo
“¿Cuántos pedidos en marzo?”	`sql_query`	LLM usa `vector_search`
“¿Qué dice la política de devoluciones?”	`vector_search`	LLM usa `sql_query`
“¿Cuál es el precio del cobre hoy?”	`web_search`	LLM usa `vector_search`
“Suma los contratos del Q3”	`sql_query`	LLM usa `vector_search`

Una TSA < 0,85 en un agente de producción es señal de que las descripciones de tools necesitan revisión antes que el modelo. Para más detalle sobre cómo construir estos evals, ver evals LLM.

Manejo de errores en tool calls

SQL injection via prompt

El riesgo más serio del tool-augmented retrieval es que el LLM genere SQL malicioso — bien porque un usuario lo indujo via prompt injection, bien porque el modelo alucinó una query destructiva. Este vector de ataque se cubre en detalle en LLM Guard, pero las reglas mínimas del lado del tool son:

Regla 1: Queries parametrizadas siempre, nunca interpolación directa.

# NUNCA esto:
cursor.execute(f"SELECT * FROM contracts WHERE provider = '{llm_output}'")

# Siempre esto:
cursor.execute("SELECT * FROM contracts WHERE provider = $1", [llm_output])

Regla 2: Usuario de BD con permisos mínimos. El usuario con el que el agente ejecuta SQL debe tener SELECT sobre las tablas necesarias y nada más. Ningún DROP, INSERT, UPDATE ni DELETE.

Regla 3: Allowlist de tablas. El sistema valida que la query generada por el LLM sólo referencia tablas en una allowlist antes de ejecutarla.

Regla 4: Timeout por query. Queries que bloquean demasiado tiempo — potencialmente inducidas para hacer DoS a la BD — se cancelan con timeout configurado.

Rate limits, timeouts y errores de tool

Cuando una tool falla, el error se devuelve al LLM como observación:

{"role": "tool", "tool_call_id": "call_01", "content": "{\"error\": \"timeout after 5s\", \"tool\": \"web_search\"}"}

El system prompt debe instruir al LLM sobre qué hacer en este caso:

If a tool returns an error or is unavailable, acknowledge the limitation in your response.
Do not retry more than once. If web_search is unavailable, state that real-time data
is not accessible at this moment and answer with available internal sources only.

Esto evita que el agente entre en bucles de reintentos y gestiona la degradación graceful: si web_search no está disponible, responde con lo que tiene en las fuentes internas.

Diagrama del bucle ReAct con las tres fuentes

Matemáticas de latencia del pipeline ReAct

Cada iteración del bucle ReAct tiene tres componentes de latencia:

[ T_{\text{iter}} = \text{TTFT}{\text{LLM}} + T{\text{tool}} + \Delta_{\text{context}} ]

donde:

TTFT_LLM: tiempo hasta el primer token del LLM (dominado por el prefill del contexto acumulado)
T_tool: tiempo de ejecución de la tool
Δ_context: overhead de context window creciente (cada iteración añade el output anterior al contexto)

Valores de referencia: Llama-3.1-70B en 4×H100 SXM (320 GB, NVLink)

Con Llama-3.1-70B en FP8 en un nodo con 4×H100 SXM (320 GB HBM3, NVLink 900 GB/s), los valores típicos en producción son:

Componente	Valor
TTFT con contexto < 4k tokens	≈ 150 ms
TTFT con contexto 8k tokens	≈ 220 ms
`sql_query` (query simple, índice)	≈ 50 ms
`vector_search` (top-5, Qdrant en RAM)	≈ 20 ms
`web_search` (API externa)	≈ 600 ms

Latencia total según número de iteraciones

Pipeline de 1 iteración (query simple, una sola tool):

[ T_1 = 150 + 50 = 200 \text{ ms} + \text{síntesis final} \approx 200 + 300 = 500 \text{ ms} ]

Pipeline de 2 iteraciones (SQL + vector_search secuenciales):

[ T_2 = (150 + 50) + (180 + 20) + 400 = 800 \text{ ms} ]

El contexto en la segunda iteración ya incluye el resultado de la primera, por lo que el TTFT sube ligeramente a ≈ 180 ms.

Pipeline de 3 iteraciones (el caso más común en queries complejas):

[ T_3 = (150 + 50) + (180 + 20) + (200 + 50) + 450 \approx 1.100 \text{ ms} ]

Parallel tool calling (SQL + vector_search en paralelo, 1 sola iteración):

[ T_{\text{parallel}} = 150 + \max(50, 20) + 400 = 600 \text{ ms} ]

Cuando las dos queries son independientes, el parallel tool calling recorta la latencia de ≈ 800 ms a ≈ 600 ms: un 25% de mejora para el caso de 2 iteraciones secuenciales.

Comparación con RAG naive

Configuración	Latencia	Queries que puede responder
RAG naive (1 retriever, 1 paso)	≈ 300 ms	Queries de contexto documental
ReAct 1 iteración (SQL)	≈ 500 ms	Queries de agregación estructurada
ReAct 2 iteraciones (SQL + vector)	≈ 800 ms	Queries híbridas numérico + contexto
ReAct 3 iteraciones	≈ 1.100 ms	Queries complejas multi-fuente
ReAct con web_search	≈ 1.500 ms	Queries que requieren datos en tiempo real

La conclusión práctica: ReAct multi-hop es 3–5× más lento que un RAG naive de un solo paso. La ganancia no está en la velocidad sino en la cobertura de queries: el RAG naive no puede responder “¿cuántos contratos?” porque esa respuesta no está en ningún chunk de texto. Para aplicaciones con SLO de latencia estricto (< 500 ms), hay que diseñar si el caso de uso realmente necesita ReAct o si un RAG bien configurado con hybrid retrieval cubre el 90% de las queries.

Hardware on-premise para agentes ReAct

Un agente ReAct con Llama-3.1-70B en producción tiene requisitos distintos a un RAG naive porque el contexto crece con cada iteración y el throughput de prefill es más crítico.

Configuración recomendada: 4×H100 SXM (320 GB HBM3, NVLink 900 GB/s)

Llama-3.1-70B en FP8: cabe en 2×H100 (70B params × 1 byte/param ≈ 70 GB + KV cache). Con 4×H100 se puede servir en tensor parallelism TP=4, reduciendo el TTFT por prefill en ≈ 2×.
Instancia de Qdrant: se puede colocar en el mismo nodo (si la colección cabe en RAM) o en nodo dedicado. Para colecciones < 50M vectores de 768 dims: ≈ 150 GB, cabe en RAM de un servidor dual-socket.
PostgreSQL: nodo separado o instancia gestionada. El agente no añade carga inusual al SQL — las queries son simples y acotadas por timeout.
vLLM con --enable-auto-tool-choice --tool-call-parser llama3_json --max-model-len 16384: el contexto de 16k tokens cubre con holgura los 5–10 turns de un pipeline ReAct.

Configuración mínima viable: 2×H100 SXM (160 GB)

Llama-3.1-70B en FP8 en TP=2. TTFT ≈ 250–300 ms para contextos de 4k tokens (aumento del 60–100% sobre TP=4).
Sirve para workloads internos con < 20 requests concurrentes.
No recomendable para SLO < 1 s con más de 5 usuarios concurrentes y contexto largo.

Lo que no hemos cubierto

Agentic retrieval loops con planificación. ReAct es el patrón más simple de agente. Cuando una query requiere descomposición en sub-tareas con dependencias, se necesitan frameworks de orquestación como LangGraph (grafos de estados), smolagents (Hugging Face, agentes con código Python como actions) o llama-index Agents (pipeline de planning + retrieval). Estos introducen un paso de planificación previo al bucle de ejecución.

MCP (Model Context Protocol). El estándar emergente de Anthropic — con implementaciones OSS — para definir tools de forma portable entre frameworks y hosts. En lugar de definir el JSON Schema de cada tool por separado en cada aplicación, MCP centraliza esas definiciones en un servidor MCP que cualquier cliente compatible puede descubrir e invocar. La adopción en 2025–2026 es rápida entre frameworks OSS (LangChain, smolagents, OpenWebUI).

Tool caching. Si el mismo tool call (mismos argumentos, misma tool) se va a invocar múltiples veces dentro del mismo contexto o en contextos muy similares, se puede cachear el resultado. El mecanismo es análogo al semantic cache descrito para RAG: antes de ejecutar el tool, se compara el hash de los argumentos (o su embedding para matching semántico) contra una caché con TTL. Especialmente valioso para sql_query con queries frecuentes y datos que cambian poco.

Multi-agent. Cuando un agente orquestador delega sub-tareas a agentes especializados — uno para SQL, otro para recuperación de documentos, otro para generación de código — se entra en el territorio de los sistemas multi-agente. Cada sub-agente puede tener su propio set de tools y su propio LLM (posiblemente más pequeño y especializado). La coordinación entre agentes introduce complejidad de trazado y observabilidad adicional.

Ver también

RAG con reranker e hybrid retrieval — el retriever que se invoca cuando el LLM elige vector_search es exactamente el pipeline descrito allí: dense + sparse + reranker cruzado
Structured output: fundamentos — el JSON Schema que define el contrato de cada tool call es exactamente structured output aplicado a la interfaz herramienta
Router de inferencia y LLM gateway L7 — el gateway L7 que recibe las requests del agente ReAct y enruta al LLM correcto; también aplica rate limiting por usuario y tenant
LLM Guard: fundamentos — SQL injection via prompt es un vector de ataque real en tool-augmented retrieval; LLM Guard cubre la detección de prompt injection antes de que el request llegue al LLM
Pipeline LLMOps de seis etapas — tool-augmented retrieval vive en la intersección de las etapas Deploy y Observe del pipeline: se despliega como parte del sistema de inferencia y se observa vía tracing de cada turn del agente
Evals LLM: la capa después del tracing — tool selection accuracy es la métrica de eval crítica para un agente ReAct; el golden dataset de eval debe incluir triples (query, tool esperado, args esperados)

Referencias

Yao, S. et al. (2022). ReAct: Synergizing Reasoning and Acting in Language Models. arXiv:2210.03629. https://arxiv.org/abs/2210.03629
vLLM documentation. Tool calling. https://docs.vllm.ai/en/stable/features/tool_calling.html
Qdrant documentation. Search. https://qdrant.tech/documentation/concepts/search/
OpenAI. Function calling. https://platform.openai.com/docs/guides/function-calling
Meta AI. Llama 3.1 Model Card. https://github.com/meta-llama/llama-models/blob/main/models/llama3_1/MODEL_CARD.md
Qwen Team (Alibaba). Qwen2.5 Technical Report. arXiv:2412.15115. https://arxiv.org/abs/2412.15115
Anthropic. Model Context Protocol. https://modelcontextprotocol.io
OWASP. LLM Top 10 for Large Language Model Applications. LLM01: Prompt Injection. https://owasp.org/www-project-top-10-for-large-language-model-applications/

Evaluar un RAG sin engañarse: RAGAS, el golden dataset y las cuatro métricas que importan

Thu, 04 Jun 2026 09:00:00 +0200

TL;DR

Un pipeline RAG falla en modos que la satisfacción del usuario no distingue: el LLM puede alucinar incluso con buenos chunks, o el retrieval puede ignorar documentos clave aunque el LLM sintetice bien lo que recibe. RAGAS descompone la evaluación en cuatro métricas ortogonales —faithfulness, answer relevance, context precision y context recall— cada una apuntando a un sub-componente diferente. El golden dataset es el calibrador de referencia; sin él las métricas no tienen ancla. El stack completo corre 100 % on-premise con vLLM como judge y Langfuse para trazabilidad.

La analogía maestra: el inspector de calidad de una fábrica de muebles

Imagina que fabricas sillas. Podrías preguntar a los clientes “¿es cómoda?” y punto. Pero esa pregunta no te dice qué arreglar cuando la respuesta es “no”. El inspector de calidad no pregunta eso: mide el tablero con dureza Shore, comprueba que cada pata tenga exactamente 45 cm, verifica que el manual de montaje incluya los doce tornillos del BOM y detecta si un tablero de densidad baja pasó el filtro de entrada.

RAGAS es ese inspector aplicado a RAG:

Faithfulness → ¿el tablero tiene la dureza especificada? El LLM solo puede usar el material (chunks) que el retrieval le entrega.
Context Precision → ¿la pata tiene la longitud exacta? De los K chunks recuperados, ¿cuántos son realmente útiles o son relleno que confunde al ensamblador?
Context Recall → ¿el manual incluye todos los tornillos? De todos los hechos que debería contener la respuesta correcta, ¿cuántos aparecen en los chunks recuperados?
Noise Sensitivity → ¿si el operario usa un tablero de densidad media baja, se nota en el producto final? Si introduces chunks irrelevantes, ¿el LLM empieza a alucinar?

Sin medir cada dimensión por separado, el diagnóstico es opaco: “el RAG no funciona bien” no te dice si reparar el embedder, el reranker, el prompt o el corpus.

El problema de evaluar RAG

La clasificación tiene una virtud incómoda: si predices 87 de 100 etiquetas correctamente, accuracy = 0,87. No hay ambigüedad. RAG no tiene esa gracia.

Un sistema RAG puede fallar en al menos tres modos independientes:

Retrieval correcto, LLM alucina: los chunks contienen la respuesta correcta, pero el LLM genera afirmaciones que no están en esos chunks. Faithfulness baja; context recall alta.
LLM correcto, retrieval falla: el retrieval devuelve chunks irrelevantes (baja context precision) o incompletos (bajo context recall). Si el LLM tiene suficiente conocimiento paramétrico, puede parecer que responde bien, pero en realidad está ignorando el contexto — lo cual es una bomba de tiempo cuando el conocimiento paramétrico queda obsoleto.
Retrieval y LLM correctos, respuesta no responde la pregunta: la respuesta es fiel al contexto y los chunks son relevantes, pero la pregunta era otra. Answer relevance baja.

Cada modo requiere una métrica diferente y una acción correctiva diferente. Usar una métrica única (BLEU, ROUGE, satisfacción de usuario) mezcla las señales y hace imposible priorizar el trabajo de mejora.

Las cuatro métricas RAGAS

1. Faithfulness — fidelidad al contexto

Pregunta: ¿cuántas afirmaciones de la respuesta generada están soportadas por los chunks recuperados?

Cálculo:

$$\text{Faithfulness} = \frac{|\text{claims soportados por el contexto}|}{|\text{total claims en la respuesta}|}$$

El proceso usa un LLM-as-judge (ver https://blog.lo0.es/posts/llm-as-judge-fundamentos/): primero se extraen las afirmaciones atómicas de la respuesta (“el modelo fue lanzado en 2023”, “admite contextos de 128k tokens”, …), luego el judge clasifica cada claim como supported o not supported por los chunks.

Ejemplo: La respuesta generada tiene 5 claims. El judge determina que 4 están en los chunks y 1 es una extrapolación sin respaldo.

$$\text{Faithfulness} = \frac{4}{5} = 0{,}80$$

Señal de alarma: faithfulness < 0,85 indica que el LLM está generando contenido que va más allá del contexto — es decir, está alucinando con respaldo superficial.

2. Answer Relevance — relevancia de la respuesta

Pregunta: ¿la respuesta realmente responde a la pregunta formulada?

Intuición: Una respuesta que responde bien a la pregunta “implica” esa pregunta. Si generas N preguntas hipotéticas a partir de la respuesta y mides su similitud semántica con la pregunta original, obtienes una señal de relevancia.

Cálculo:

$$\text{AnswerRelevance} = \frac{1}{N} \sum_{i=1}^{N} \cos(\vec{q}{\text{original}}, \vec{q}{i}^{\text{generada}})$$

donde $\vec{q}$ son embeddings de las preguntas.

Ejemplo: Para la pregunta “¿Qué versiones de Python soporta FastAPI?” y una respuesta sobre frameworks web en general, las preguntas hipotéticas generadas versarán sobre “¿cuáles son los mejores frameworks web?” — coseno bajo con la pregunta original → answer relevance baja.

3. Context Precision — precisión del retrieval

Pregunta: de los K chunks recuperados, ¿qué proporción son realmente relevantes?

Cálculo (versión weighted):

$$\text{ContextPrecision@K} = \frac{\sum_{k=1}^{K} \text{Precision@}k \cdot \mathbb{1}[\text{chunk}_k \text{ es relevante}]}{|\text{chunks relevantes en top-K}|}$$

La forma más directa: el judge LLM clasifica cada chunk como relevante o no para responder la pregunta. La precisión es la fracción relevante.

Ejemplo: Se recuperan 5 chunks. El judge considera que 3 son relevantes y 2 son ruido.

$$\text{ContextPrecision} = \frac{3}{5} = 0{,}60$$

Señal de alarma: precision < 0,6 indica que el retrieval está contaminando el contexto con información que puede contradecir o diluir la respuesta correcta.

4. Context Recall — recall del retrieval

Pregunta: de todos los hechos necesarios para construir la respuesta correcta (ground-truth), ¿qué proporción están cubiertos por los chunks recuperados?

Cálculo:

$$\text{ContextRecall} = \frac{|\text{claims del ground-truth atribuibles a algún chunk}|}{|\text{total claims en ground-truth}|}$$

Esta métrica requiere ground-truth, es decir, necesitas el golden dataset.

Ejemplo: El ground-truth tiene 6 afirmaciones. Los chunks recuperados cubren 5 de ellas; la sexta está en un documento que el retrieval no encontró.

$$\text{ContextRecall} = \frac{5}{6} \approx 0{,}83$$

5. Noise Sensitivity — sensibilidad al ruido

Pregunta: si introduces chunks irrelevantes en el contexto, ¿cómo cae la faithfulness?

Se calcula como la diferencia de faithfulness entre la condición limpia y la condición con ruido controlado:

$$\Delta\text{Faithfulness} = \text{Faithfulness}{\text{limpio}} - \text{Faithfulness}{\text{ruidoso}}$$

Un $\Delta > 0{,}15$ indica que el prompt o el LLM son frágiles ante contextos contaminados — problema que context precision baja convierte en rutinario.

Ejemplo numérico completo

Escenario

Pregunta: “¿Qué garantías de latencia ofrece Redis para operaciones de lectura en memoria con un dataset de 10 GB?”

Respuesta generada por el RAG:

“Redis garantiza latencias sub-milisegundo para operaciones GET en datasets que caben en RAM. Con 10 GB de dataset y clientes en la misma red local, P99 está típicamente por debajo de 1 ms. Redis también soporta clustering horizontal para escalar más allá de la RAM de un nodo. Además, Redis incluye soporte nativo para JSON desde la versión 7.2.”

Ground-truth (respuesta de referencia):

“Redis opera completamente en memoria, lo que garantiza latencias sub-milisegundo para GET. En redes locales con datasets de 10 GB en RAM, el P99 se sitúa por debajo de 1 ms. El clustering permite escalar más allá de la RAM de un único nodo.”

Chunks recuperados (5 chunks, fragmentos resumidos):

#	Contenido resumido	Relevante
C1	“Redis opera en memoria; GET tiene latencias < 1 ms en LAN”	Sí
C2	“Redis Cluster permite sharding para escalar la RAM total”	Sí
C3	“Redis Sentinel gestiona alta disponibilidad mediante failover automático”	No
C4	“Benchmarks de Redis: P50 = 0,3 ms, P99 = 0,9 ms en 10 GB dataset”	Sí
C5	“Redis Stack añade módulos: RedisJSON, RediSearch, RedisTimeSeries”	No

Cálculo paso a paso

Faithfulness:

Claims en la respuesta generada:

“Redis garantiza latencias sub-milisegundo para GET en datasets en RAM” → soportado por C1, C4
“Con 10 GB en LAN, P99 < 1 ms” → soportado por C4
“Redis soporta clustering horizontal para escalar RAM” → soportado por C2
“Redis incluye soporte nativo para JSON desde la versión 7.2” → NO soportado por ningún chunk (C5 menciona RedisJSON como módulo de Redis Stack, no como nativo de Redis core)

$$\text{Faithfulness} = \frac{3}{4} = 0{,}75$$

El claim 4 es una extrapolación que mezcla información de C5 de forma imprecisa — alucinación parcial.

Context Precision:

Chunks relevantes: C1, C2, C4 (3 de 5).

$$\text{ContextPrecision} = \frac{3}{5} = 0{,}60$$

C3 y C5 son ruido. C5 en particular contribuyó a la alucinación parcial sobre JSON.

Context Recall:

Claims del ground-truth:

“Redis opera en memoria, GET < 1 ms” → atribuible a C1 ✓
“P99 < 1 ms en LAN con 10 GB” → atribuible a C4 ✓
“Clustering escala más allá de la RAM de un nodo” → atribuible a C2 ✓

$$\text{ContextRecall} = \frac{3}{3} = 1{,}00$$

El retrieval encontró todos los chunks necesarios para el ground-truth. El problema no es recall sino precision (C3, C5 contaminaron el contexto).

Answer Relevance:

El judge genera 3 preguntas hipotéticas a partir de la respuesta:

“¿Qué latencias ofrece Redis para lecturas en memoria?” — cos = 0,91
“¿Cómo escala Redis horizontalmente?” — cos = 0,74
“¿Qué módulos JSON incluye Redis?” — cos = 0,52 (deriva de la alucinación)

$$\text{AnswerRelevance} = \frac{0{,}91 + 0{,}74 + 0{,}52}{3} = 0{,}72$$

La derivación hacia JSON redujo la relevancia. Una respuesta más ajustada habría obtenido ~0,90.

Resumen del ejemplo

Métrica	Valor	Diagnóstico
Faithfulness	0,75	LLM extrapoló más allá del contexto
Context Precision	0,60	Retrieval devolvió 2 chunks irrelevantes
Context Recall	1,00	Retrieval capturó todo lo necesario
Answer Relevance	0,72	Respuesta desvía el tema

Acción correctiva principal: mejorar el reranker para filtrar C3 y C5 antes de que lleguen al LLM. El problema de faithfulness y relevance es consecuencia directa de la baja precision, no del LLM en sí.

Construcción del golden dataset

Qué es y por qué importa

El golden dataset es un conjunto de tuplas (pregunta, chunks relevantes, respuesta correcta) que actúa como calibrador de referencia. Sin él, context recall no se puede calcular (no hay ground-truth) y las demás métricas carecen de ancla interpretativa: ¿0,75 de faithfulness es bueno o malo para este corpus y este dominio?

Un golden dataset bien construido permite:

Comparar versiones del pipeline (embedder v1 vs v2, chunk size 512 vs 1024)
Detectar regresiones en CI antes de desplegar
Estratificar el análisis por tipo de pregunta

Pipeline de construcción asistida por LLM

La construcción manual pura es cara. El patrón estándar en 2026 es asistencia LLM con revisión humana de muestra:

Paso 1 — Selección de chunks semilla. Del corpus total, seleccionar chunks representativos mediante muestreo estratificado (por sección, fecha, tipo de documento). Para un corpus técnico de 10.000 chunks, 500-1.000 semillas es un punto de partida razonable.

Paso 2 — Generación de preguntas. Un LLM potente (Llama-3.1-70B o similar) genera 2-3 preguntas por chunk semilla usando un prompt del tipo:

Dado el siguiente fragmento de documentación, genera preguntas específicas
que solo puedan responderse correctamente usando ESTE fragmento y no
conocimiento general. Las preguntas deben ser las que haría un ingeniero
buscando información operativa.
Fragmento: {chunk}

Paso 3 — Generación de respuestas de referencia. El mismo LLM, con acceso al chunk semilla (y a chunks adyacentes si la pregunta lo requiere), genera la respuesta de referencia.

Paso 4 — Revisión humana de muestra. Revisar manualmente el 10-20 % del dataset generado. Los criterios de rechazo más comunes: preguntas triviales que cualquier LLM responde sin el corpus, respuestas que el LLM rellenó con conocimiento paramétrico en lugar de los chunks, y preguntas mal formuladas o ambiguas.

Tamaño mínimo

Caso de uso	Pares mínimos	Notas
Prototipo / validación inicial	50-100	Suficiente para detectar problemas gruesos
Corpus técnico en producción	200-500	Permite estratificación básica
Producción robusta con estratificación completa	500-1.000+	Necesario para detectar regresiones sutiles

Estratificación del dataset

Un golden dataset plano mide el promedio pero oculta los casos extremos. La estratificación mínima recomendada incluye tres tipos de preguntas:

Fáciles (single-hop): Un único chunk contiene toda la información necesaria. El baseline que cualquier RAG decente debe superar.
Difíciles (multi-hop): La respuesta correcta requiere combinar información de 2-4 chunks diferentes. Aquí se detectan los límites del reranker y del prompt de síntesis.
Adversariales: La pregunta tiene una premisa falsa, o el corpus no contiene la respuesta. El RAG correcto debe responder “no tengo información suficiente” — un RAG frágil alucina con confianza. Este tipo de pregunta mide directamente el riesgo de alucinación de alto impacto.

La trampa de Goodhart

“Cuando una medida se convierte en objetivo, deja de ser una buena medida.” — Charles Goodhart

Si optimizas el embedder o el reranker usando el golden dataset como función de pérdida, el dataset se corrompe como métrica: el sistema aprende a rendir bien en esas preguntas específicas sin mejorar en el dominio general.

La solución es la misma que en ML supervisado: separar dev set (para optimización e iteración) de test set (para evaluación final, congelado y auditado). El test set nunca debe usarse para tomar decisiones de diseño; solo para reportar el estado del sistema en releases.

Correlación con satisfacción real

Los estudios de campo publicados por los equipos de Databricks (2024) y los análisis de adopción de RAGAS (2025) apuntan a umbrales operativos interpretables:

Rango de métrica	Síntoma observable	Acción correctiva
Faithfulness < 0,75	Usuarios reportan “respuestas inventadas” con frecuencia	Revisar el prompt del LLM; aumentar instrucciones de cita; reducir temperatura
Faithfulness 0,75-0,85	Alucinaciones ocasionales en topics periféricos	Mejorar context precision para eliminar chunks contaminantes
Faithfulness ≥ 0,85	Correlaciona con NPS positivo en estudios de campo	Mantener; monitorear deriva
Context Precision < 0,60	LLM incluye información contradictoria; respuestas inconsistentes	Ajustar el reranker; reducir K; revisar umbrales de similitud
Context Recall < 0,70	Preguntas multi-hop fallidas; información clave ausente	Revisar el chunking strategy; añadir chunks de mayor tamaño; enriquecer metadatos
Answer Relevance < 0,70	Respuestas “correctas pero que no responden”	Revisar el prompt de síntesis; añadir instrucción explícita de adherencia a la pregunta

La context precision baja es especialmente perniciosa: chunks irrelevantes no son neutrales. Aumentan la probabilidad de que el LLM use información incorrecta como si fuera relevante, degradando faithfulness de forma encadenada. Es la transmisión por la que un problema de retrieval se convierte en un problema de LLM.

Diagrama: el bucle de evaluación continua

El bucle de evaluación continua: corpus → retrieval → LLM → RAGAS judge → métricas → alerta → acción correctiva → corpus.

Stack OSS 2026 para ejecutar RAGAS on-premise

ragas (Apache 2.0)

La librería ragas soporta evaluación asíncrona y múltiples backends de LLM. La integración con vLLM como judge elimina la necesidad de enviar datos a APIs externas — crítico en entornos con datos sensibles.

from ragas import evaluate
from ragas.metrics import (
 faithfulness,
 answer_relevancy,
 context_precision,
 context_recall,
)
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

# Judge LLM apuntando a vLLM on-premise
judge_llm = ChatOpenAI(
 model="meta-llama/Llama-3.1-70B-Instruct",
 base_url="http://vllm-service:8000/v1",
 api_key="sk-local", # vLLM ignora el valor pero requiere el campo
)

embeddings = OpenAIEmbeddings(
 model="BAAI/bge-m3",
 base_url="http://embedding-service:8001/v1",
 api_key="sk-local",
)

result = evaluate(
 dataset=golden_dataset, # HuggingFace Dataset con columnas estándar
 metrics=[faithfulness, answer_relevancy, context_precision, context_recall],
 llm=judge_llm,
 embeddings=embeddings,
)

El dataset esperado por RAGAS tiene cuatro columnas: question, answer, contexts (lista de strings), ground_truth.

Langfuse para trazabilidad de evals

Cada evaluación RAGAS se registra en Langfuse como un dataset experiment, vinculando los scores a los spans de producción (ver https://blog.lo0.es/posts/tracing-llm-otel-genai/). Esto permite correlacionar una caída de faithfulness con el request específico que la provocó — sin esta vinculación, las métricas son números sin contexto accionable.

from langfuse import Langfuse

lf = Langfuse()

# Crear o recuperar el dataset en Langfuse
dataset = lf.get_or_create_dataset("rag-golden-v3")

# Registrar scores del experiment
for idx, row in result.to_pandas().iterrows():
 lf.score(
 name="ragas-faithfulness",
 value=row["faithfulness"],
 trace_id=row["trace_id"], # vinculado al span de producción
 )

Prometheus + Grafana para alertas operativas

Las métricas RAGAS se exponen como gauges de Prometheus. Un dashboard de Grafana con umbrales configura alertas cuando faithfulness cae sostenidamente por debajo de 0,80:

# regla de alerta Prometheus
- alert: RAGFaithfulnessLow
 expr: avg_over_time(rag_faithfulness_score[30m]) < 0.80
 for: 10m
 labels:
 severity: warning
 annotations:
 summary: "RAG faithfulness por debajo de umbral ({{ $value | humanize }})"
 description: "Revisar context precision y reranker. Posible deriva del corpus."

Corriendo RAGAS contra vLLM on-premise — consideraciones prácticas

Tamaño del judge: Llama-3.1-70B como judge produce resultados comparables a GPT-4 en faithfulness y context evaluation, según los benchmarks de RAGAS 0.2 (2025). Modelos más pequeños (8B-13B) degradan la calidad del judge en preguntas multi-hop.
Throughput: En hardware on-premise con 4×H100 SXM (320 GB, NVLink), un run de 200 evaluaciones con Llama-3.1-70B tarda aproximadamente 8-12 minutos con batch_size=8 y vLLM en modo continuous batching.
Coste por evaluación: Sin API externa, el coste marginal es electricidad + amortización de GPU. Con 4×H100 a ~3 kW sostenidos, un run de 200 evaluaciones cuesta < 0,10 € en energía a tarifa industrial típica.
Frecuencia recomendada: eval offline semanal sobre el golden dataset completo + eval online muestreada (5-10 % de requests de producción) con un subconjunto de métricas que no requieren ground-truth (faithfulness, answer relevance).

Lo que no hemos cubierto

Alternativas a RAGAS: TruLens (evaluación con feedbacks modulares), DeepEval (aserciones programáticas, integración con pytest), ARES (framework de Stanford con trained classifiers en lugar de LLM-as-judge), y el framework de evals de OpenAI. Cada uno tiene trade-offs distintos en coste de judge, fiabilidad y facilidad de integración.
Continuous eval en producción: muestrear automáticamente requests reales, anonimizarlos, ejecutar un subconjunto de métricas sin ground-truth y usar el resultado para detectar deriva del sistema antes de que los usuarios lo reportan. Requiere un pipeline de datos separado del pipeline de inferencia.
Eval multilingüe: RAGAS con un judge en español o catalán sobre corpus no inglés tiene sesgos documentados cuando el judge es un modelo fundamentalmente entrenado en inglés. Los embeddings de similitud semántica para answer relevance son especialmente sensibles al idioma del corpus vs. idioma del judge.
A/B testing de configuraciones RAG: usar las métricas RAGAS como criterio de éxito en experimentos controlados — chunk size 512 vs. 1024, BM25 puro vs. hybrid, reranker cross-encoder vs. biencoder — con significancia estadística calculada sobre el golden dataset.

Ver también

https://blog.lo0.es/posts/llm-as-judge-fundamentos/ — el patrón de juez LLM que RAGAS usa para medir faithfulness claim a claim
https://blog.lo0.es/posts/evals-llm-la-capa-despues-de-tracing/ — el marco general de evals donde RAGAS es la especialización RAG
https://blog.lo0.es/posts/rag-reranker-hybrid-retrieval-fundamentos/ — la capa de retrieval cuya context precision y recall miden estas métricas
https://blog.lo0.es/posts/rag-corpus-curation-fundamentos/ — la calidad del corpus que context recall refleja
https://blog.lo0.es/posts/tracing-llm-otel-genai/ — los spans de producción donde Langfuse anota los scores RAGAS
https://blog.lo0.es/posts/data-versioning-dvc-lakefs/ — el golden dataset es un artefacto data que necesita versioning igual que el corpus

Referencias

Es Shahul, et al. RAGAS: Automated Evaluation of Retrieval Augmented Generation. arXiv:2309.15217 (2023). https://arxiv.org/abs/2309.15217
RAGAS Documentation v0.2. Metrics Reference. https://docs.ragas.io/en/stable/concepts/metrics/ (consultado junio 2026)
Langfuse. Dataset Experiments. https://langfuse.com/docs/datasets/overview (consultado junio 2026)
Databricks. LLM Quality Evaluation: From Lab to Production. Databricks Engineering Blog (2024).
Saad-Falcon, J. et al. ARES: An Automated Evaluation Framework for Retrieval-Augmented Generation Systems. arXiv:2311.09476 (2023).
Goodhart, C.A.E. Problems of Monetary Management: The U.K. Experience. Papers in Monetary Economics. Reserve Bank of Australia (1975). Formulación moderna de la ley que lleva su nombre.
vLLM Project. OpenAI-Compatible Server. https://docs.vllm.ai/en/stable/serving/openai_compatible_server.html (consultado junio 2026)

Semantic cache en RAG: el recepcionista con memoria fotográfica

Thu, 04 Jun 2026 08:00:00 +0200

TL;DR

En un RAG con tráfico real, el 30–70% de las queries son semánticamente equivalentes a alguna anterior aunque el texto sea diferente. El semantic cache intercepta esas queries antes del retriever y el LLM, devolviendo la respuesta ya calculada si la similitud coseno con una query previa supera un umbral θ (típicamente 0,92–0,95). Con 10.000 requests/día y un hit rate del 45%, eso equivale a no ejecutar 4.500 generaciones de LLM: aproximadamente 0,62 horas de GPU ahorradas cada día en un cluster con Llama-3.1-70B. El trade-off fundamental es que θ alto da respuestas más precisas pero menor ahorro; θ bajo maximiza el ahorro pero puede devolver respuestas incorrectas para queries sutilmente distintas.

La analogía: el recepcionista con cuaderno

Imagina el mostrador de recepción de un hotel de 400 habitaciones. A lo largo del día, el recepcionista recibe cientos de preguntas. Pero si analizas el libro de registro, verás que el 60% de esas preguntas son variantes de las mismas diez:

“¿Dónde está el gimnasio?”
“¿A qué hora es el desayuno?”
“¿Tienen aparcamiento?”
“¿Cómo conecto al WiFi?”

Al tercer día, el recepcionista ha construido mentalmente un cuaderno de respuestas. Cuando alguien pregunta “¿dónde puedo ir a hacer ejercicio?”, no llama al conserje (retrieval) ni consulta el manual interno del hotel de 300 páginas (LLM): mira el cuaderno, identifica que esa pregunta es lo mismo que “¿dónde está el gimnasio?”, y responde en dos segundos.

Pero cuando alguien pregunta “¿a qué hora cierra el gimnasio hoy?”, el recepcionista sabe que no puede fiar del cuaderno: el horario puede haber cambiado por un evento privado. Tiene que llamar al conserje.

Ese es exactamente el mecanismo del semantic cache:

El cuaderno es el cache store (Redis con índice vectorial, o una collection de Qdrant).
Identificar que “hacer ejercicio” ≈ “gimnasio” es la búsqueda por similitud coseno con umbral θ.
Llamar al conserje es el retrieval sobre el corpus.
Consultar el manual es la generación del LLM.
“Hoy” es la señal de consulta temporal que invalida el cache.

El umbral θ es exactamente lo que distingue “dónde está” (igual semánticamente) de “a qué hora está hoy” (distinto semánticamente). No es magia: es aritmética vectorial sobre representaciones aprendidas.

El problema en producción

Un pipeline RAG típico tiene tres capas de latencia y cómputo: embedding de la query, vector search sobre el corpus, y generación con el LLM. En desarrollo, ese coste es irrelevante. En producción con 50 usuarios concurrentes, cada una de esas capas escala linealmente con el número de requests.

El problema es que los usuarios hacen las mismas preguntas una y otra vez, con formulaciones levemente distintas:

Query original	Query equivalente
“¿Cómo configuro el agente?”	“¿Cuál es el proceso para configurar el agente?”
“error al instalar la dependencia”	“falla la instalación de la dependencia”
“¿qué es un embedding?”	“explícame qué son los embeddings”

Ejecutar el pipeline completo para cada una de estas variantes es desperdicio puro. Los estudios empíricos en sistemas de soporte técnico y Q&A corporativo reportan que entre el 30% y el 70% de las queries de un día son semánticamente redundantes respecto a queries anteriores de la misma semana.

La distribución de queries en sistemas reales sigue una ley de potencias similar a la distribución de Zipf: los 100 temas más frecuentes concentran aproximadamente el 60% del tráfico total. Un cache bien calibrado captura exactamente esa concentración.

Cómo funciona el semantic cache

El flujo completo se puede ver en el diagrama siguiente. Describámoslo primero en prosa.

Cuando llega una nueva query $q$:

Embedding de la query: $q$ se embebe con el mismo modelo que se usó para indexar el corpus. Esto es crítico: si el corpus se indexó con text-embedding-3-large y el cache usa un embedder distinto, los espacios vectoriales no son comparables.
Búsqueda en el cache store: se ejecuta una búsqueda ANN (Approximate Nearest Neighbor) sobre los vectores de queries previamente cacheadas. Se recupera la query más similar $q^*$ y su similitud coseno $s$.
Decisión por umbral: $$ \text{respuesta} = \begin{cases} r^* & \text{si } s(q, q^) \geq \theta \ \text{pipeline}(q) & \text{si } s(q, q^) < \theta \end{cases} $$ donde $r^$ es la respuesta cacheada asociada a $q^$.
En caso de miss: se ejecuta el pipeline completo (retrieval + LLM). La respuesta generada se almacena en el cache con un TTL configurable para futuras queries similares.

El cache store no es una base de datos clave-valor ordinaria. Es un vector index sobre los embeddings de las queries, con los valores siendo las respuestas generadas. Cada entrada tiene la estructura:

{vector: embed(q), response: r, ttl: T, metadata: {...}}

Diagrama del flujo

Flujo del semantic cache como middleware entre el gateway y el retriever. Los cache hits evitan por completo el vector search sobre el corpus y la generación del LLM.

El umbral θ y su trade-off

El umbral θ es el parámetro más sensible del sistema. Funciona exactamente como el umbral de reconocimiento del recepcionista: si es demasiado exigente, solo identificará preguntas textualmente idénticas y el cuaderno no servirá de mucho. Si es demasiado laxo, devolverá la respuesta de “¿dónde está el gimnasio?” a alguien que preguntó “¿a qué hora cierra el gimnasio?”.

La similitud coseno entre dos vectores $\mathbf{a}$ y $\mathbf{b}$ es:

$$ s(\mathbf{a}, \mathbf{b}) = \frac{\mathbf{a} \cdot \mathbf{b}}{|\mathbf{a}| \cdot |\mathbf{b}|} $$

Para texto en prosa (español o inglés), los embedders modernos como text-embedding-3-large o nomic-embed-text asignan similitudes coseno en torno a 0,90–0,96 a paráfrasis semánticamente equivalentes y similitudes de 0,75–0,88 a queries relacionadas pero no equivalentes.

La métrica de calidad del cache no es solo el hit rate: es la precision@cache, definida como la fracción de respuestas cacheadas que siguen siendo correctas para la nueva query. Una respuesta cacheada es “correcta” si un evaluador (otro LLM o métricas como BERTScore) la considera equivalente a la que el pipeline completo habría generado para esa query específica.

θ	Hit rate estimado	precision@cache estimada	Ahorro efectivo
0,85	~65%	~72%	~47%
0,90	~55%	~85%	~47%
0,92	~48%	~91%	~44%
0,93	~45%	~94%	~42%
0,95	~35%	~98%	~34%
0,97	~18%	~99,5%	~18%

El ahorro efectivo se define como $\text{hit rate} \times \text{precision@cache}$, ya que un hit con respuesta incorrecta no es un ahorro: es un error que puede costar más en pérdida de confianza que lo que se ahorró en GPU.

La zona óptima empírica para la mayoría de aplicaciones de Q&A corporativo en español o inglés está entre θ = 0,92 y θ = 0,95. En dominios muy especializados donde matices pequeños cambian la respuesta (medicina, derecho, finanzas), conviene θ ≥ 0,95.

Matemáticas del ahorro

Pongamos números concretos sobre un sistema real.

Configuración base:

10.000 requests/día
Corpus técnico de 1 millón de chunks en un índice Qdrant
LLM: Llama-3.1-70B en 4×H100 SXM (320 GB, NVLink)
Respuesta media: 200 tokens de output
Throughput del LLM en este hardware: ~400 tokens/s/GPU con batching (continuous batching activo, véase continuous-batching-fundamentos)

Coste de una request sin cache:

El embedding de la query tarda ~2 ms en una GPU. El vector search ANN sobre 1 M de chunks en Qdrant tarda ~5 ms (medida empírica con HNSW, ef=128). La generación de 200 tokens a 400 tok/s total (4 GPUs) equivale a:

$$ t_{\text{LLM}} = \frac{200 \text{ tokens}}{400 \text{ tok/s}} = 0{,}5 \text{ s por request} $$

Si 10.000 requests llegan al LLM en un día, el tiempo total de GPU dedicado a generación es:

$$ T_{\text{GPU}} = 10{.}000 \times 0{,}5 \text{ s} = 5{.}000 \text{ s} \approx 1{,}38 \text{ horas de GPU por día} $$

Con semantic cache θ = 0,93, hit rate ~45%:

Solo 5.500 requests (55%) llegan al LLM:

$$ T_{\text{GPU,cache}} = 5{.}500 \times 0{,}5 \text{ s} = 2{.}750 \text{ s} \approx 0{,}76 \text{ horas de GPU por día} $$

Ahorro:

$$ \Delta T_{\text{GPU}} = 1{,}38 - 0{,}76 = 0{,}62 \text{ horas de GPU/día} $$

En cómputo de inferencia, esto equivale aproximadamente a poder atender un 45% más de usuarios sin añadir hardware, o reducir en un 45% los costes de inferencia si se trabaja con APIs externas facturadas por token.

El coste del propio semantic cache (embedding de la query + ANN search sobre el cache store) es de ~7 ms por request, insignificante frente a los 500 ms de generación que se evita en los hits.

Distribución Zipf de los temas:

La razón por la que funciona es la distribución de Zipf del tráfico. Si numeramos los temas por frecuencia (tema 1 = más frecuente), la frecuencia del tema $k$ es proporcional a $1/k$. Con 1.000 temas distintos:

$$ \text{fracción de tráfico cubierta por top-}N = \frac{\sum_{k=1}^{N} 1/k}{\sum_{k=1}^{1000} 1/k} \approx \frac{\ln N}{\ln 1000} = \frac{\ln N}{6{,}9} $$

Para los top-100 temas: $\ln(100)/6{,}9 \approx 4{,}6/6{,}9 \approx 67%$ del tráfico. El cache no necesita cubrir todos los temas: captura el 67% del tráfico cubriendo solo el 10% de los temas.

Stack OSS 2026

GPTCache

GPTCache es la librería de referencia para semantic cache standalone. Su arquitectura es modular:

Embedder: ONNX Runtime con modelos convertidos (por defecto onnx/all-MiniLM-L6-v2), sin dependencia de GPU para el cache layer.
Vector store: Faiss (local), Milvus, o Qdrant.
Scalar store: SQLite (desarrollo) o Redis (producción) para metadata, TTL, y respuestas.
Evaluación de similitud: por defecto coseno, configurable.

Configuración mínima en Python:

from gptcache import cache
from gptcache.adapter import openai
from gptcache.embedding import Onnx
from gptcache.manager import CacheBase, VectorBase, get_data_manager
from gptcache.similarity_evaluation.distance import SearchDistanceEvaluation

onnx = Onnx()
data_manager = get_data_manager(
 CacheBase("redis", url="redis://localhost:6379"),
 VectorBase("qdrant", host="localhost", collection_name="query_cache")
)
cache.init(
 embedding_func=onnx.to_embeddings,
 data_manager=data_manager,
 similarity_evaluation=SearchDistanceEvaluation(),
)
cache.set_openai_key()

GPTCache intercepta las llamadas a la API de OpenAI (o a proxies compatibles) de forma transparente. El TTL se configura a nivel del data_manager.

MeanCache

MeanCache (2024) extiende GPTCache para conversaciones multi-turno. El problema con GPTCache estándar es que en diálogos, la query “relevante” no es solo el último mensaje sino toda la ventana de contexto. MeanCache calcula el embedding de la query como la media ponderada de los embeddings de los últimos $k$ turnos:

$$ \mathbf{e}{\text{query}} = \frac{\sum{i=1}^{k} w_i \cdot \mathbf{e}{q_i}}{\sum{i=1}^{k} w_i} $$

donde $w_i$ decrece con la antigüedad del turno. Esto reduce los false positives en diálogos donde el tema va cambiando.

Qdrant como cache store dual

Si el corpus del RAG ya está en Qdrant, se puede usar la misma instancia con una collection separada para el cache. Las ventajas son operacionales: un solo servicio a gestionar, misma infraestructura de backup y monitoreo.

La collection del cache usa payload filters para implementar TTL:

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, Range
import time

client = QdrantClient("localhost", port=6333)

# Buscar en cache con filtro de TTL
hits = client.search(
 collection_name="semantic_cache",
 query_vector=query_embedding,
 query_filter=Filter(
 must=[FieldCondition(
 key="expires_at",
 range=Range(gt=time.time())
 )]
 ),
 limit=1,
 score_threshold=0.93
)

Hay que ejecutar periódicamente una limpieza de entradas expiradas, ya que Qdrant no tiene TTL nativo (a diferencia de Redis).

Langfuse para trazabilidad

Langfuse es el estándar OSS para observabilidad de pipelines LLM (véase tracing-llm-otel-genai). Cada request debe marcarse con si fue cache hit o miss:

from langfuse import Langfuse
from langfuse.decorators import observe

langfuse = Langfuse()

@observe()
def process_query(query: str) -> dict:
 cache_result = semantic_cache.lookup(query)
 if cache_result:
 langfuse.update_current_observation(
 metadata={"cache_hit": True, "cache_score": cache_result.score}
 )
 return cache_result.response
 # pipeline completo...
 langfuse.update_current_observation(
 metadata={"cache_hit": False}
 )

Con estos metadatos, Langfuse permite calcular el hit rate real, la distribución de scores de similitud, y detectar si el umbral θ necesita ajuste.

Hardware on-premise: configuración de referencia

Para un despliegue on-premise con este stack, una configuración adecuada para RAG con semantic cache es:

Nodo de inferencia: 4×H100 SXM (320 GB NVLink total) para Llama-3.1-70B en FP8. Throughput ~400 tok/s en generación con continuous batching (vLLM o TGI).

Nodo de servicios vectoriales: CPU con 256 GB RAM. Qdrant para el corpus (1–10 M chunks) y para el cache store (hasta 500K entradas en memoria). Redis 7.x para metadata y exact-match cache como primera capa.

Nodo de embedding: CPU o GPU de gama media (A10G). El embedder del cache puede correr en ONNX Runtime en CPU sin impacto perceptible en latencia (~2 ms por embedding).

La separación del cache store del corpus es importante: el corpus tiene millones de chunks con índices HNSW grandes; el cache store tiene como máximo decenas de miles de queries con un índice mucho más pequeño y tiempos de búsqueda de 1–2 ms.

Casos donde el cache falla

El recepcionista con cuaderno falla en tres escenarios bien definidos:

1. Queries con contexto temporal

“¿Cuál es el estado actual del incidente?” o “¿Qué cambió en la última versión?” son preguntas cuya respuesta correcta cambia con el tiempo. Un cache con TTL de 24 horas podría devolver información obsoleta.

La solución es detectar marcadores temporales en la query (expresiones regulares sobre “hoy”, “ahora”, “actual”, “último”, “ayer”, y sus equivalentes en inglés) y forzar un cache miss para estas queries, independientemente del score de similitud.

2. Queries personalizadas con datos privados

Si el RAG tiene acceso a datos del usuario (historial de cuenta, documentos privados), dos usuarios distintos haciendo la misma pregunta deben recibir respuestas diferentes. Un cache compartido que ignora el contexto del usuario es un riesgo de privacidad.

La solución es un cache particionado por user_id o tenant_id. Esto reduce el hit rate (el cache de cada usuario es más pequeño) pero es la única opción segura en arquitecturas multi-tenant.

3. TTL y corpus stale

Cuando el corpus se actualiza (se ingieren nuevos documentos, se corrigen errores), las respuestas cacheadas pueden quedar desactualizadas. Un TTL fijo (24–48 horas) mitiga el problema pero no lo elimina.

Para corpus con actualizaciones frecuentes, la solución es un mecanismo de invalidación activa: cuando se actualiza el corpus en Qdrant, se lanza un job que identifica qué entradas del cache podrían estar afectadas (por overlap semántico con los chunks actualizados) y las elimina. Esta es la “cache invalidation selectiva” mencionada en el apartado de temas no cubiertos.

Integración en el pipeline como middleware

El semantic cache se implementa como middleware entre el API gateway y el retriever. No modifica el contrato de la API: el cliente sigue enviando queries y recibiendo respuestas en el mismo formato.

class SemanticCacheMiddleware:
 def __init__(self, cache_store, retriever, llm, threshold=0.93):
 self.cache = cache_store
 self.retriever = retriever
 self.llm = llm
 self.threshold = threshold

 async def process(self, query: str, context: dict) -> dict:
 # Primera capa: exact-match cache (Redis GET, O(1))
 exact = await self.cache.exact_lookup(query)
 if exact:
 return {**exact, "cache_type": "exact"}

 # Segunda capa: semantic cache (ANN search)
 query_embedding = await self.embed(query)
 semantic = await self.cache.semantic_lookup(
 query_embedding, threshold=self.threshold
 )
 if semantic:
 return {**semantic, "cache_type": "semantic"}

 # Miss: pipeline completo
 chunks = await self.retriever.retrieve(query_embedding)
 response = await self.llm.generate(query, chunks)

 # Store para futuras queries
 await self.cache.store(
 embedding=query_embedding,
 query=query,
 response=response,
 ttl=context.get("ttl", 86400)
 )
 return {**response, "cache_type": "miss"}

La primera capa de exact-match (Redis GET) es una optimización adicional: para queries textualmente idénticas, ni siquiera se calcula el embedding. El coste es una operación Redis de microsegundos. Solo si no hay exact match se pasa al semantic lookup.

Lo que no hemos cubierto

Cache invalidation selectiva: cuando se actualiza un subconjunto del corpus (por ejemplo, se reindexan los documentos de un producto específico), habría que identificar qué entradas del cache están semánticamente solapadas con los chunks actualizados y marcarlas como stale. El mecanismo implica calcular similitud entre los embeddings de los chunks actualizados y los embeddings de las queries cacheadas, lo cual es costoso a escala.
Multi-tenant cache: isolación vs. compartición: en un SaaS con múltiples clientes, el cache compartido maximiza el hit rate pero puede exponer respuestas de un tenant a otro si no se filtra correctamente. El cache particionado por tenant es seguro pero tiene hit rates mucho más bajos. El punto medio es un cache compartido con filtrado por ACL aplicado sobre los payload filters de Qdrant.
Semantic cache para streaming responses: cuando el LLM emite tokens en streaming (SSE), el cache no puede interceptar fácilmente la respuesta completa. Las opciones son: cachear en el primer miss y devolver la respuesta completa de golpe en los hits (rompiendo la experiencia de streaming), o implementar un “fake streaming” que emite los tokens de la respuesta cacheada a velocidad controlada.
Exact-match cache como primera capa: antes del semantic cache, un lookup de O(1) en Redis con la query como clave puede capturar queries textualmente idénticas a costo ínfimo. El código del apartado anterior ya muestra esta arquitectura en dos capas.

Ver también

RAG con reranker y hybrid retrieval — el retrieval que el semantic cache evita ejecutar en los hits; entender cómo funciona el vector search que se ahorra
PostgreSQL + Qdrant: ingestion de documentos en microservicios — el vector store que puede hacer doble función como cache store, con la misma instancia de Qdrant para corpus y cache
KV cache en transformers — cache a nivel de atención del transformer; diferente al semantic cache a nivel de query del sistema RAG pero complementario
Continuous batching en inferencia LLM — el batching que procesa los cache misses; el semantic cache reduce la presión de requests que llegan al motor de inferencia
Tracing de LLMs con OTel y GenAI — cómo instrumentar cache hits vs misses con OpenTelemetry para medir el ahorro real en producción

Referencias

Bang, J. et al. (2024). MeanCache: User-Centric Semantic Cache for Large Language Model Based Web Applications. arXiv:2403.02694.
Zilliz. (2023). GPTCache: A Library for Creating Semantic Cache for LLM Queries. GitHub: zilliztech/GPTCache.
Qdrant Team. (2024). Qdrant Documentation: Filtering with payload. qdrant.tech/documentation.
Manning, C. D., Raghavan, P., Schütze, H. (2008). Introduction to Information Retrieval. Cambridge University Press. Cap. 19: Web search (distribución Zipf).
Langfuse. (2024). Observability for LLM Applications. langfuse.com/docs.
Meta AI. (2024). Llama 3.1 Model Card. ai.meta.com.
Guo, Y. et al. (2023). Evaluating the Factual Consistency of Large Language Models Through Summarization. Referencia para BERTScore como métrica de evaluación de respuestas cacheadas.

PostgreSQL + Qdrant en la ingestión RAG: el cartero que sincroniza dos mundos

Thu, 04 Jun 2026 07:00:00 +0200

TL;DR — En un sistema RAG de producción, PostgreSQL guarda la verdad oficial de los documentos y Qdrant guarda los vectores para búsqueda. Mantenerlos sincronizados no es trivial: si borras un documento de Postgres y no invalidas sus chunks en Qdrant, el sistema devuelve respuestas de documentos fantasma. Hay dos patrones para evitarlo: el outbox pattern (transacción atómica + worker asíncrono, at-least-once) y CDC con Debezium (lectura directa del WAL de Postgres, baja latencia, mayor complejidad). Este artículo explica cuándo usar cada uno, cómo orquestarlos como microservicios y qué números esperar con bge-m3 en hardware on-premise.

La analogía del cartero y el registro civil

Imagina una ciudad con dos oficinas complementarias.

La primera es el Registro Civil: guarda el censo oficial. Cada vez que nace alguien, muere o cambia de domicilio, el Registro es el primero en saberlo. Es lento, estructurado, transaccional. Si el Registro dice que alguien existe, existe. Si dice que murió, está muerto. PostgreSQL es el Registro Civil de tus documentos.

La segunda es la libreta del cartero: una copia optimizada para encontrar a cualquier vecino en segundos, organizada por zonas, nombres fonéticos y rutas habituales. El cartero no puede actualizar el Registro, pero sí buscar a velocidades que el Registro jamás alcanzaría. Qdrant es la libreta del cartero.

El problema es la sincronización. Si el Registro anota un fallecimiento pero nadie avisa al cartero, este seguirá intentando entregar cartas a una dirección que ya no existe. En RAG, eso se traduce en chunks indexados de documentos que ya fueron eliminados, editados o reemplazados — documentos fantasma que contaminan los resultados.

¿Cómo avisa el Registro al cartero?

Outbox pattern: cada vez que el Registro actualiza su libro mayor, apunta el cambio en una hoja de salida (outbox). Un empleado mensajero lee esa hoja periódicamente y actualiza la libreta del cartero. Garantizado, asíncrono, tolerante a fallos.
CDC con Debezium: el cartero tiene un teléfono directo conectado al Registro. Cada vez que el escribano apunta algo nuevo, el teléfono suena y el cartero actualiza su libreta en tiempo casi real.

El problema del consistency gap

En una arquitectura RAG naive, el flujo es:

El usuario sube un documento → se inserta en Postgres con metadatos.
Un worker lo trocea en chunks, genera embeddings y hace upsert en Qdrant.
El retrieval usa Qdrant para encontrar chunks relevantes y Postgres para hidratar metadatos.

Hasta aquí todo bien. El problema aparece en las actualizaciones y borrados:

El usuario edita un documento → Postgres actualiza el registro, pero los vectores de los chunks viejos siguen en Qdrant. El retrieval devuelve contexto obsoleto.
El usuario borra un documento → Postgres elimina la fila, pero los chunks permanecen en Qdrant. El retrieval devuelve chunks de un documento que ya no debería existir.
El sistema de permisos revoca el acceso de un tenant → Qdrant no tiene forma de saberlo si no hay sincronización explícita.

Esto no es un problema teórico. En corpus vivos (wikis corporativas, bases de conocimiento actualizadas diariamente), el consistency gap acumula ruido progresivamente. Un estudio interno en pipelines de producción muestra que sin reconciliación activa, el 3-8% de los chunks indexados corresponde a documentos que ya no existen en la fuente de verdad tras 30 días de operación.

La solución no es “reindexar todo cada noche”. Con 10M chunks y un modelo de embedding no trivial, eso cuesta horas de cómputo y provoca ventanas de indisponibilidad. La solución es propagación de cambios con garantías.

Outbox pattern: la hoja de salida

Mecanismo

El outbox pattern resuelve el problema de “escribir a dos sistemas en la misma operación” sin necesidad de transacciones distribuidas (que son caras y frágiles).

La idea es simple: PostgreSQL es el coordinador único. Cuando el microservicio de ingestión procesa un documento, realiza dos escrituras en la misma transacción local:

Inserta o actualiza el documento en la tabla documents.
Inserta un evento en la tabla outbox_events.

Si la transacción falla, ambas escrituras se deshacen. Si tiene éxito, ambas están comprometidas atomicamente. No hay estado intermedio inconsistente.

-- Tablas relevantes
CREATE TABLE documents (
 id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
 tenant_id TEXT NOT NULL,
 title TEXT NOT NULL,
 content TEXT NOT NULL,
 checksum TEXT NOT NULL,
 updated_at TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE outbox_events (
 id BIGSERIAL PRIMARY KEY,
 aggregate_id UUID NOT NULL, -- document id
 event_type TEXT NOT NULL, -- 'document.created' | 'document.updated' | 'document.deleted'
 payload JSONB NOT NULL,
 created_at TIMESTAMPTZ DEFAULT now(),
 processed_at TIMESTAMPTZ -- NULL = pendiente
);

-- Ejemplo de inserción atómica
BEGIN;
 INSERT INTO documents (tenant_id, title, content, checksum)
 VALUES ($1, $2, $3, $4)
 RETURNING id INTO _doc_id;

 INSERT INTO outbox_events (aggregate_id, event_type, payload)
 VALUES (_doc_id, 'document.created', jsonb_build_object(
 'tenant_id', $1,
 'title', $2,
 'checksum', $4
 ));
COMMIT;

El worker de outbox

Un proceso separado (el outbox worker) hace polling de outbox_events donde processed_at IS NULL, procesa cada evento (chunking, embedding, upsert en Qdrant) y marca la fila como procesada:

UPDATE outbox_events
 SET processed_at = now()
 WHERE id = $1;

Garantía: at-least-once. Si el worker falla entre el upsert en Qdrant y el UPDATE, el evento se reprocesará. Qdrant tolera upserts idempotentes (misma id de punto = sobreescritura), así que el reprocesado no genera duplicados.

Latencia: depende del intervalo de polling. Con polling cada 500ms, la latencia p50 es ~250ms; p99, ~500ms. Aceptable para la mayoría de casos RAG donde el usuario no espera ver indexado un documento en menos de un segundo.

CDC con Debezium: el teléfono directo

Mecanismo

El Change Data Capture (CDC) lee el Write-Ahead Log (WAL) de PostgreSQL directamente. Postgres escribe cada cambio en el WAL antes de aplicarlo a las tablas — es el mecanismo que usa para replicación y recuperación. Debezium se suscribe a un slot de replicación lógica y convierte esos eventos en mensajes estructurados.

-- Habilitar replicación lógica en postgresql.conf
-- wal_level = logical

-- Crear slot de replicación para Debezium
SELECT pg_create_logical_replication_slot('debezium_slot', 'pgoutput');

El flujo completo:

Postgres WAL → Debezium connector → Kafka/NATS → Indexer consumer → Qdrant

Debezium emite eventos con la estructura before/after del registro:

{
 "op": "d",
 "before": {
 "id": "550e8400-e29b-41d4-a716-446655440000",
 "tenant_id": "acme",
 "checksum": "sha256:abc123"
 },
 "after": null
}

Con "op": "d" (delete), el consumer sabe que debe borrar todos los puntos en Qdrant cuyo payload contenga ese document_id.

# Consumer: borrado por filtro de payload
qdrant_client.delete(
 collection_name="corpus",
 points_selector=FilterSelector(
 filter=Filter(
 must=[
 FieldCondition(
 key="document_id",
 match=MatchValue(value=event["before"]["id"])
 )
 ]
 )
 )
)

Ventajas e inconvenientes

CDC elimina el polling y reduce la latencia a decenas de milisegundos (el tiempo de propagación del WAL más el procesamiento del consumer). Pero añade complejidad operacional: necesitas gestionar el slot de replicación (los slots no consumidos retienen WAL indefinidamente, lo que puede llenar el disco), el broker de mensajes y el estado del consumer offset.

Comparativa: outbox vs CDC

Criterio	Outbox pattern	CDC con Debezium
Latencia típica	250ms – 2s	20ms – 200ms
Garantía de entrega	At-least-once	At-least-once
Complejidad operacional	Baja (solo Postgres)	Alta (Debezium + broker)
Riesgo de retención WAL	Ninguno	Alto si el slot se atasca
Idempotencia requerida	Sí (en indexer)	Sí (en consumer)
Soporte multi-tabla	Manual	Automático (cualquier tabla)
Backpressure	Natural (polling)	Requiere diseño explícito
Cuándo elegir	Corpus < 100k docs/día, equipo pequeño	Corpus > 1M docs/día, baja latencia crítica

Regla práctica: empieza con outbox. Migra a CDC cuando el volumen de cambios supere los ~50k eventos/hora o cuando la latencia de segundos sea inaceptable para el caso de uso (e.g., indexación de noticias en tiempo real).

Arquitectura de microservicios

El pipeline de ingestión se compone de tres microservicios con responsabilidades bien separadas:

Microservicio 1: Ingestor

Responsabilidades: recibir documentos, trocearlos en chunks y solicitar embeddings. No escribe en Qdrant directamente.

# ingestor/main.py (simplificado)
from langchain_text_splitters import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(
 chunk_size=512, # tokens, no caracteres
 chunk_overlap=64,
 length_function=token_count,
)

def ingest_document(doc: Document, db: Session) -> None:
 chunks = splitter.split_text(doc.content)
 with db.begin():
 db.execute(
 "UPDATE documents SET checksum=$1 WHERE id=$2",
 [doc.checksum, doc.id]
 )
 db.execute(
 """INSERT INTO outbox_events (aggregate_id, event_type, payload)
 VALUES ($1, 'document.updated', $2)""",
 [doc.id, {"chunks": chunks, "tenant_id": doc.tenant_id,
 "model": "bge-m3", "model_version": "1.0.0"}]
 )

Microservicio 2: Indexer

Lee la outbox, genera embeddings llamando al servidor de inferencia (vLLM o TEI) y hace upsert en Qdrant.

# indexer/worker.py
import asyncio
from qdrant_client import QdrantClient
from qdrant_client.models import PointStruct, VectorParams, Distance

qdrant = QdrantClient(host="qdrant-service", port=6333)

async def process_event(event: dict) -> None:
 payload = event["payload"]
 chunks = payload["chunks"]
 doc_id = str(event["aggregate_id"])

 # Embedding batch en TEI (Text Embeddings Inference)
 embeddings = await embed_batch(chunks, model="bge-m3")

 points = [
 PointStruct(
 id=f"{doc_id}_{i}",
 vector=emb,
 payload={
 "document_id": doc_id,
 "tenant_id": payload["tenant_id"],
 "chunk_index": i,
 "text": chunks[i],
 "model_version": payload["model_version"],
 }
 )
 for i, emb in enumerate(embeddings)
 ]

 # Si es actualización, borrar chunks anteriores primero
 if event["event_type"] in ("document.updated", "document.deleted"):
 qdrant.delete(
 collection_name="corpus",
 points_selector=filter_by_doc_id(doc_id)
 )

 if event["event_type"] != "document.deleted":
 qdrant.upsert(collection_name="corpus", points=points)

Microservicio 3: Reconciler

El reconciler es la red de seguridad. Periódicamente (por ejemplo, cada hora) compara el conjunto de document_id en Postgres con el conjunto de document_id en Qdrant. Los IDs presentes en Qdrant pero ausentes en Postgres son fantasmas: se borran.

# reconciler/diff.py
async def reconcile(tenant_id: str) -> int:
 pg_ids = set(await fetch_all_doc_ids(tenant_id))
 qdrant_ids = set(await scroll_all_doc_ids(tenant_id)) # scroll paginado

 orphans = qdrant_ids - pg_ids
 if orphans:
 logger.warning("Orphan chunks for %d documents", len(orphans))
 for doc_id in orphans:
 qdrant.delete("corpus", filter_by_doc_id(doc_id))

 return len(orphans)

Matemáticas de throughput e ingestión

Throughput de embedding

El modelo bge-m3 (1024 dimensiones, soporte denso + sparse + colbert) en un nodo con 4×H100 SXM (320 GB NVLink) ejecutado vía vLLM o HuggingFace TEI alcanza aproximadamente 2.000 chunks/segundo con batch size = 256 y secuencias de 512 tokens.

$$\text{throughput} = 4 \times 500 \text{ chunks/s/GPU} = 2{,}000 \text{ chunks/s}$$

La cifra de 500 chunks/s por GPU proviene de benchmarks públicos de TEI con bge-m3 en H100 SXM5, batch=256, seq_len=512 ¹.

Tiempo de re-ingestión total

Para un corpus de 10M chunks:

$$t = \frac{10{,}000{,}000 \text{ chunks}}{2{,}000 \text{ chunks/s}} = 5{,}000 \text{ s} \approx 83 \text{ minutos}$$

Esto es el tiempo puro de embedding. Añadiendo latencia de escritura en Qdrant (~0,5ms por upsert batch de 100 puntos):

$$t_{\text{qdrant}} = \frac{10{,}000{,}000}{100} \times 0.5\text{ ms} = 50{,}000 \text{ ms} = 50 \text{ s}$$

Total estimado para una re-ingestión completa: ~85-90 minutos en un nodo 4×H100.

Coste de almacenamiento en Qdrant

Cada vector de bge-m3 tiene 1024 dimensiones en float32 (4 bytes):

$$\text{tamaño por vector} = 1{,}024 \times 4 \text{ B} = 4{,}096 \text{ B} = 4 \text{ KB}$$

Para 10M chunks (solo vectores densos):

$$\text{total vectores} = 10^7 \times 4{,}096 \text{ B} = 40.96 \text{ GB}$$

Añadiendo payload JSON (estimado ~500 bytes/chunk):

$$\text{payload} = 10^7 \times 500 \text{ B} = 5 \text{ GB}$$

Índice HNSW (aproximadamente 1.2× el tamaño del vector para $m=16$):

$$\text{HNSW} \approx 40.96 \text{ GB} \times 1.2 = 49.15 \text{ GB}$$

Total estimado en disco: ~95 GB para 10M chunks con bge-m3 denso.

Con scalar quantization (int8), el tamaño del vector se reduce 4×:

$$\text{con quantización int8} \approx \frac{40.96}{4} + 5 + \frac{49.15}{4} \approx 27.5 \text{ GB}$$

Configuración	Vectores	HNSW	Payload	Total
float32, sin quantización	40.96 GB	49.15 GB	5 GB	~95 GB
int8 scalar quantization	10.24 GB	12.29 GB	5 GB	~28 GB
binary quantization	1.28 GB	1.54 GB	5 GB	~8 GB

La binary quantization pierde precisión de recall (~2-5% en NDCG@10), pero permite alojar corpus mucho mayores en RAM. Para producción con recall crítico, int8 es el punto de equilibrio habitual.

Hardware on-premise recomendado

Para un pipeline de ingestión continua en producción:

Nodo de embedding: 4×H100 SXM (320 GB, NVLink), 2× CPU 64-core (EPYC 9654), 1 TB RAM DDR5, 100 GbE. Ejecuta vLLM o TEI sirviendo bge-m3. Throughput sostenido: ~2.000 chunks/s con pipeline batch asíncrono.

Nodo Qdrant: CPU 32-core, 256 GB RAM (para mantener el índice HNSW en memoria con 10M chunks sin quantización), NVMe 2 TB (escritura de snapshots y WAL de Qdrant). Qdrant recomienda que el índice HNSW quepa en RAM para latencia p99 < 5ms.

Nodo PostgreSQL: CPU 16-core, 128 GB RAM, NVMe 4 TB para WAL (especialmente relevante si usas CDC con slot de replicación lógica; el slot retiene WAL hasta que Debezium lo consume).

Broker (si CDC): Kafka 3-broker con 500 GB NVMe por nodo, o NATS JetStream con 3 nodos para cargas más modestas.

Manifests de Kubernetes

Deployment del Indexer

apiVersion: apps/v1
kind: Deployment
metadata:
 name: rag-indexer
 namespace: rag-pipeline
spec:
 replicas: 3
 selector:
 matchLabels:
 app: rag-indexer
 template:
 metadata:
 labels:
 app: rag-indexer
 spec:
 containers:
 - name: indexer
 image: registry.example.com/rag-indexer:1.0.0
 env:
 - name: POSTGRES_DSN
 valueFrom:
 secretKeyRef:
 name: pg-credentials
 key: dsn
 - name: QDRANT_HOST
 value: "qdrant-service.qdrant.svc.cluster.local"
 - name: EMBEDDING_ENDPOINT
 value: "http://tei-service.embeddings.svc.cluster.local:8080"
 - name: POLL_INTERVAL_MS
 value: "500"
 resources:
 requests:
 memory: "512Mi"
 cpu: "500m"
 limits:
 memory: "2Gi"
 cpu: "2"

CronJob del Reconciler

apiVersion: batch/v1
kind: CronJob
metadata:
 name: rag-reconciler
 namespace: rag-pipeline
spec:
 schedule: "0 * * * *" # cada hora
 concurrencyPolicy: Forbid
 jobTemplate:
 spec:
 template:
 spec:
 restartPolicy: OnFailure
 containers:
 - name: reconciler
 image: registry.example.com/rag-reconciler:1.0.0
 env:
 - name: POSTGRES_DSN
 valueFrom:
 secretKeyRef:
 name: pg-credentials
 key: dsn
 - name: QDRANT_HOST
 value: "qdrant-service.qdrant.svc.cluster.local"
 - name: SCROLL_PAGE_SIZE
 value: "1000"
 resources:
 requests:
 memory: "256Mi"
 cpu: "250m"
 limits:
 memory: "1Gi"
 cpu: "1"

Gotchas de producción

Reindexing al cambiar de modelo de embedding

Este es el problema más doloroso. Si pasas de bge-m3 a nomic-embed-text-v2, los vectores son incompatibles: están en espacios de embedding distintos y las distancias coseno entre ellos no tienen significado.

La solución es dual-index aliasing:

Crea una colección nueva en Qdrant: corpus_v2.
Re-embeds el corpus completo con el modelo nuevo y carga corpus_v2.
Cuando la colección nueva está completa y validada (test de recall), cambia el alias de corpus_prod de corpus_v1 a corpus_v2.
Borra corpus_v1 cuando el tráfico haya migrado.

Durante la migración, los dos índices coexisten. El retriever usa el alias, no el nombre directo de la colección.

Versioning del índice

Guarda model_version en el payload de cada punto en Qdrant. Esto permite:

Filtrar por versión durante el retrieval (útil en A/B testing de modelos).
El reconciler puede detectar puntos con versión antigua y reprocesarlos selectivamente.
Auditoría: saber con qué modelo se generó cada embedding.

# Filtro por versión de modelo en retrieval
results = qdrant.search(
 collection_name="corpus",
 query_vector=query_embedding,
 query_filter=Filter(
 must=[
 FieldCondition(key="model_version", match=MatchValue(value="1.0.0")),
 FieldCondition(key="tenant_id", match=MatchValue(value=tenant_id)),
 ]
 ),
 limit=10
)

Namespace por tenant (multi-tenancy)

Hay dos estrategias en Qdrant:

Estrategia	Pros	Contras
Colección por tenant	Aislamiento total, sin filtro extra	N colecciones = N índices HNSW en RAM
Payload filter por tenant	Una sola colección, menos RAM	Filtro añade ~10-15% de latencia en búsqueda

Para menos de 100 tenants con corpus grandes (> 1M chunks/tenant), usa colección por tenant. Para cientos o miles de tenants con corpus pequeños, usa payload filter con tenant_id indexado:

qdrant.create_payload_index(
 collection_name="corpus",
 field_name="tenant_id",
 field_schema=PayloadSchemaType.KEYWORD
)

Lo que no hemos cubierto

Streaming corpus updates con CDC en near-real-time: invalidación selectiva de chunks cuando solo una sección de un documento cambia (chunking incremental basado en diff de contenido, no re-chunking completo).
Multi-tenant corpus isolation con ACLs por chunk: ir más allá del filtro por tenant_id para permisos a nivel de grupo, rol o incluso documento individual, aplicados en tiempo de retrieval.
Federated corpus: corpora distribuidos en silos cross-border donde las regulaciones (GDPR, CCPA) impiden centralizar los embeddings; patrones de federated search sin mover datos.
Reindexing incremental con zero-downtime usando dual-index aliasing: el protocolo completo de migración de modelo con rollback, test de regresión de recall y traffic splitting progresivo.

Ver también

El corpus curado que esta arquitectura debe indexar — estrategias de curación y filtrado antes de la ingestión.
El retrieval que consume este vector store — cómo el reranker y el retrieval híbrido usan lo que aquí construimos.
El embedder que genera los vectores — comparativa de bge-m3, nomic-embed-text-v2 y modelos multivector.
La etapa Data del mapa maestro LLMOps — contexto de esta pipeline dentro del ciclo completo.
Versioning del corpus raw antes de la ingestión — cómo DVC y LakeFS gestionan el linaje antes de llegar a PostgreSQL.
Debezium y CDC: el notario que escucha los cambios antes de que nadie los pida — el deep dive en CDC que este artículo introduce: WAL de Postgres, slots de replicación, pgoutput y la comparativa completa con el outbox pattern.

Referencias

HuggingFace Text Embeddings Inference — benchmarks oficiales con modelos de la familia bge en hardware A100/H100. https://github.com/huggingface/text-embeddings-inference ↩︎

Ontologías y knowledge graphs en LLMOps: la nomenclatura linneana que sostiene las seis etapas del pipeline

Wed, 03 Jun 2026 03:30:00 +0200

Este post atraviesa las seis etapas del pipeline LLMOps desde una perspectiva transversal: la nomenclatura común que hace que las etapas compartan vocabulario. Conecta directamente con RAG corpus curation (el corpus se cura contra una ontología), embeddings (la ontología enriquece el embedding con metadatos tipados), retrieval híbrido (el KG es un cuarto canal junto a denso/esparso/multi-vector), evals (los golden sets se estratifican por clase ontológica), structured output (las JSON Schemas derivan de OWL/SHACL), y los tres marcos de ISO 42001, ENS y EU AI Act (cada uno es una ontología de control).

TL;DR

La conversación de ontologías y LLMs ha oscilado entre dos posturas igualmente equivocadas en los últimos tres años: o “los LLMs ya extraen conocimiento solos, las ontologías son del siglo pasado”, o “todo el RAG hay que tirarlo y construir un knowledge graph encima”. La realidad operativa de mid-2026 es más sobria: la ontología no es un sustituto del RAG sino su nomenclatura común, sin la cual las seis etapas del pipeline LLMOps trabajan con vocabularios distintos sin saberlo. El corpus se cura sin saber qué clases de entidad existen; los embeddings perforan documentos sin enriquecerse con metadatos tipados; los evals reportan una accuracy global que oculta gaps enteros de clase; el guardrail bloquea por listas de palabras en vez de por clasificación formal; el incident response agrupa mal porque cada alerta nombra “el activo afectado” a su manera; el compliance no puede mapear sus controles porque ENS, ISO 42001 y EU AI Act son tres ontologías y el sistema no tiene ninguna. Este post desmonta qué es una ontología en términos prácticos —TBox y ABox, RDF y SPARQL, los cuatro perfiles de OWL 2 (EL para terminologías enormes tipo SNOMED, QL para OBDA, RL para reasoning con reglas, DL para el full description-logic), SHACL para validación con shapes, SKOS para tesauros, JSON-LD como serialización viable—, recorre las seis etapas LLMOps mostrando dónde la ontología cambia la operación, repasa el campo GraphRAG en 2026 con datos verificables (Microsoft GraphRAG v2 oct-2025, LightRAG dual-level y actualizaciones incrementales, HippoRAG 2 con Personalized PageRank, KAG sobre OpenSPG ontology-grounded), inventaria las ontologías verticales realmente desplegadas en producción (FIBO, SNOMED CT, schema.org, IEC 81346, GS1, Wikidata, ENS Anexo I-II del RD 311/2022, EU AI Act Anexo III), fija el stack open source on-prem viable con las salvedades de licencia (Neo4j Community es GPLv3 con implicaciones AGPL en algunos features, KuzuDB upstream archivado oct-2025, forks bighorn y ryugraph), describe los cinco patrones de integración LLM × ontología y cierra con siete trampas operativas. La regla del pulgar: el knowledge graph no es la respuesta; la nomenclatura formalizada compartida sí.

La analogía: Carl Linneo, 1735

En 1735 publicó Carl von Linné la primera edición de Systema Naturae. Antes de Linneo, los naturalistas europeos tenían un problema operativo: la misma especie podía aparecer en cinco tratados con cinco nombres latinos distintos —cada uno una descripción polinómica del tipo “Felis cauda elongata cum maculis nigris in dorso et lateribus”— y dos naturalistas que se carteaban tardaban meses en darse cuenta de que estaban discutiendo del mismo animal. La biología era un campo de ruido lexicográfico: imposible comparar observaciones, imposible verificar replicación, imposible construir teoría acumulativa.

Linneo no descubrió biología. Lo que descubrió fue que el campo necesitaba una nomenclatura común con tres propiedades:

Jerarquía estricta. Reino → Filo → Clase → Orden → Familia → Género → Especie. Cada nivel es una clase con subclases bien definidas. Una propiedad de Felis (la dieta carnívora) se hereda automáticamente a Felis catus y a Felis silvestris sin redeclararse.
Naming inequívoco. Cada especie tiene un único nombre binomial (Genus + epíteto específico) y un único type specimen anclado en un museo. “Felis silvestris” significa exactamente lo mismo en Madrid, Estocolmo y Calcuta.
Reglas de prioridad. Si dos botánicos publican el mismo género con nombres distintos, gana el primero que lo registró válidamente. La convención de naming no se debate en cada paper: hay un metanivel de gobernanza explícita.

Tras Linneo, la biología comparada se vuelve posible. Mendel puede hablar de Pisum sativum y un botánico polaco sabe exactamente qué planta cultivar para replicarlo. Darwin puede comparar pinzones de las Galápagos con pinzones de otras islas sin confusión sobre qué es “el mismo tipo de pájaro”. El cambio no es de instrumentación —el microscopio existía desde Hooke (1665)—. El cambio es de vocabulario formal compartido.

Una ontología en computación es exactamente esto:

Linneo (1735)	Ontología (2026)
Jerarquía Reino → … → Especie	Jerarquía de clases (`Person ⊑ Agent ⊑ Thing`) — el TBox
Type specimen en museo	Instancia anclada con IRI única — el ABox
Nombre binomial	IRI / URI única por concepto
Reglas de prioridad	Axiomas de la ontología + gobernanza
“Felis silvestris” significa lo mismo en Madrid y Estocolmo	`<http://example.org/ont/Felis_silvestris>` significa lo mismo en cualquier sistema

Cuando hoy un LLMOps team dice “nuestro corpus está curado, los embeddings son bge-m3 y los evals miden recall@5”, pero la pregunta “¿qué proporción de queries sobre activos categoría alta del ENS están bien cubiertas?” no tiene respuesta — porque en el sistema no existe una clase formal “activo categoría alta ENS”—, el problema es pre-Linneo: el campo todavía no se ha dotado de la nomenclatura que hace comparable cada etapa.

La ontología atraviesa las seis etapas como vocabulario compartido. Sin ella, cada etapa tiene su propia definición de "cliente", "documento sensible" o "incidente".

Qué es una ontología en términos operativos

La palabra “ontología” tiene un parentesco filosófico ineludible —Aristóteles, las categorías de Kant, Quine— que confunde a la primera. En infraestructura LLM da igual: una ontología es un grafo dirigido con tipos, descrito formalmente, sobre el que se puede razonar, validar y consultar. Lo importante son seis conceptos prácticos.

TBox y ABox

La distinción que se usa todos los días. La TBox (de terminology) es el esquema: clases, jerarquía de subclases, propiedades, axiomas. La ABox (de assertions) son las instancias.

# TBox — esquema
:Person rdfs:subClassOf :Agent .
:Employee rdfs:subClassOf :Person .
:worksFor rdfs:domain :Employee ; rdfs:range :Organization .

# ABox — instancias
:alice a :Employee .
:alice :worksFor :acme .

Un reasoner verifica que la ABox es consistente con la TBox: si declaras :alice :worksFor :acme pero :alice no es :Employee, el reasoner detecta la inconsistencia. Esa es la palanca: validación automática del conocimiento que ningún sistema basado solo en embeddings densos puede dar.

RDF y la unidad de información

La unidad atómica del Semantic Web es la tripla RDF (sujeto, predicado, objeto). Todo dato se expresa como una colección de triplas. Esto da la propiedad operativa más útil del paradigma: dos grafos se mergean trivialmente uniéndolos. Si tu sistema indexa el corpus médico con SNOMED CT y el corpus legal con FIBO, ambos en RDF, fusionarlos para una query que cruce los dos dominios es literalmente g1 ∪ g2. En propiedad-graph (Neo4j) esto requiere más cirugía.

Los cuatro perfiles de OWL 2

La gente nueva al campo asume que OWL es una cosa. Son cuatro perfiles con trade-offs distintos, todos W3C Recommendation:

Perfil	Expresividad	Coste de razonamiento	Casos de uso
OWL 2 EL	restringido (subclase, intersección, propiedades)	polinomial en tamaño de ontología	terminologías enormes — SNOMED CT (350k+ conceptos)
OWL 2 QL	subset que mapea a SQL/UCQ	LOGSPACE en datos	OBDA (ontology-based data access) sobre DBs relacionales
OWL 2 RL	subset implementable como reglas (Datalog)	escalable, sin DL completo	reasoning en producción con motores de reglas
OWL 2 DL	SROIQ completo (la “full ontology”)	decidible pero NEXPTIME en peor caso	ontologías académicas, validación profunda

Regla operativa: si tu equipo no va a leer un paper de description logics todos los meses, no uses OWL 2 DL. Casi todo el valor está en EL/QL/RL. Para terminologías médicas grandes, EL. Para razonar sobre datos relacionales existentes, QL. Para reglas de negocio, RL.

SHACL — la validación que sí se opera

OWL hace reasoning (“dadas estas axiomas, ¿qué se puede deducir?”). SHACL hace validación (“dado este grafo concreto, ¿cumple estos shapes?”). En producción, SHACL gana porque su semántica es más cercana al chequeo de tipos que el desarrollador entiende:

:PersonShape a sh:NodeShape ;
 sh:targetClass :Person ;
 sh:property [
 sh:path :nombre ;
 sh:minCount 1 ;
 sh:datatype xsd:string ;
 ] ,
 [
 sh:path :nif ;
 sh:pattern "^[0-9]{8}[A-Z]$" ;
 ] .

Validar un grafo entrante contra este shape detecta :alice :nombre 42 (tipo incorrecto), :alice :nif "12345678X9" (formato incorrecto) o :alice a :Person sin nombre (min count violado). Es JSON Schema para grafos, conceptualmente. La spec SHACL 1.2 está en draft W3C 2025; SHACL 1.0 lleva en producción desde 2017.

SKOS — el tesauro ligero

No todo conocimiento merece OWL. Para vocabularios controlados —tesauros, taxonomías, glosarios— hay SKOS:

:Mamifero a skos:Concept ;
 skos:prefLabel "Mamífero"@es , "Mammal"@en ;
 skos:broader :Animal ;
 skos:narrower :Felino , :Canido .

SKOS no expresa axiomas formales —skos:broader no es rdfs:subClassOf—. Sirve para clasificar contenidos sin pretensión de razonamiento, que es el 80% de los casos corporativos. Empieza por SKOS: la mayoría de “ontologías” empresariales son en realidad tesauros que se sobreelevaron a OWL por moda y arrastran complejidad innecesaria.

JSON-LD y SPARQL — las superficies prácticas

JSON-LD 1.1 (W3C Rec 2020) es la serialización que sí se usa en sistemas reales: JSON normal con un campo @context que mapea las claves a IRIs. El microformato de schema.org en páginas web es JSON-LD. Para un equipo LLMOps, JSON-LD es el formato natural de intercambio con tools y APIs.

SPARQL 1.1 (W3C Rec 2013; 1.2 en draft 2025) es SQL para grafos:

SELECT ?empleado ?empresa WHERE {
 ?empleado a :Employee ;
 :worksFor ?empresa ;
 :pais "España" .
 ?empresa :sector "fintech" .
}

Toda triple store moderna lo habla. Los Federation features permiten que una sola query toque varios endpoints —SNOMED CT + ontología corporativa propia—.

Por qué importa para un LLM en producción

La promesa romántica del año 2023-2024 era: “ahora que tenemos LLMs, no necesitamos ontologías; el modelo entiende el lenguaje natural y extrae conocimiento”. La realidad operativa de mid-2026 es más matizada y descansa sobre cuatro observaciones que cualquiera con un RAG en producción ha hecho ya:

El LLM tiene memoria semántica pero no esquema declarado. Si preguntas “¿qué entidades de tipo Person aparecen en este documento?”, responde algo razonable. Si preguntas “¿qué personas aparecen y cuáles son empleados del cliente?”, la respuesta depende de cómo el modelo interpreta “empleado del cliente” en ese contexto. Sin un esquema externo que diga “Employee es subclase de Person y se relaciona con Organization vía worksFor”, la coherencia entre dos llamadas al mismo LLM no está garantizada.
La calidad varía por dominio sin que el sistema sepa por qué. Tu RAG tiene una accuracy global del 78% pero falla sistemáticamente en queries sobre instrumentos financieros derivados. Como no tienes una clasificación formal de queries por categoría, el problema es invisible hasta que un cliente se queja.
El compliance exige nomenclatura formal. ENS clasifica activos en cinco dimensiones (Confidencialidad, Integridad, Disponibilidad, Autenticidad, Trazabilidad) con tres niveles cada una. EU AI Act enumera ocho áreas de alto riesgo en Anexo III. Sin un mapeo formal entre tus assets y esas categorías, no puedes auditar lo que no sabes nombrar. El auditor pregunta “¿qué chunks del corpus tocan datos personales especialmente protegidos?” y tu sistema no tiene esa columna.
La interoperabilidad entre componentes exige tipos. Tu retrieval devuelve “chunks relevantes”. Tu reranker los reordena. Tu guardrail filtra los sensibles. Si cada componente tiene su propia definición de qué es un “chunk sensible”, la cadena rompe en cada interface. Una ontología compartida es el contrato de tipos del pipeline.

La consecuencia operativa: la ontología no reemplaza el RAG. Lo tipa. Lo hace auditable, comparable y debuggable. La pregunta correcta no es “¿necesito un knowledge graph?” sino “¿en qué etapas del pipeline gano si introduzco una nomenclatura formal compartida?”.

Las seis etapas LLMOps × ontología

Recorramos las seis etapas del pipeline preguntando qué cambia en cada una cuando hay ontología. Esto es el eje del post: la palanca no es “instalar Neo4j”, es introducir tipos donde antes había texto plano.

Etapa 1 — Data

La curación del corpus se vuelve curación dirigida por ontología:

Cada chunk no es solo “texto + embedding”, lleva además chunk:tipoDocumento, chunk:nivelClasificacion, chunk:categoriaENS, chunk:contienePII.
Estos tipos vienen de una ontología corporativa explícita, no de strings ad-hoc del data engineer del turno de mañana.
La regla 4 de corpus curation —anti-contaminación— se beneficia: los chunks del golden eval set llevan dataset:goldenEval=true declarado como tripla; cualquier reindexación que filtre por goldenEval=true se vuelve trivial.
El detector de PII deja de ser una expresión regular para volverse un clasificador contra el tesauro categorías de datos personales: identificador, contacto, financiero, salud, biométrico. La columna chunk:pii ya no es booleana sino una lista de categorías SKOS.

# Ingestion con tipado ontológico
chunk = {
 "@context": "https://ontology.fibercli.es/v1/context.jsonld",
 "@id": f"chunk:{uuid4()}",
 "@type": "Chunk",
 "tipoDocumento": "ContratoComercial",
 "nivelClasificacion": "ConfidencialMedio",
 "categoriaENS": ["Disponibilidad-M", "Confidencialidad-A"],
 "contienePII": ["IdentificadorFiscal", "Contacto"],
 "embedding": [...],
 "text": "...",
}

Bajo el contexto JSON-LD, todas esas claves resuelven a IRIs y son consultables vía SPARQL.

Etapa 2 — Train / Adapt

El fine-tuning continuo y el retrain ganan dos palancas:

Datasets estratificados por clase. Cuando el feedback de producción se convierte en dataset de entrenamiento, cada ejemplo viene etiquetado por la clase ontológica del incidente que lo originó. Permite muestrear n ejemplos por clase en vez de n ejemplos globales — corrige los gaps de cobertura del modelo.
Generación sintética guiada por ontología. Para clases con pocos ejemplos en el corpus real, se generan datos sintéticos contra el esquema: “genera 50 preguntas sobre FIBO:DerivativeInstrument que un trader podría hacer”. La salida pasa por structured output validado contra el shape SHACL del schema antes de entrar al dataset.

Etapa 3 — Eval

La capa de evals cambia más que ninguna. Sin ontología, el eval reporta una accuracy global que oculta:

accuracy = 0.78

Con ontología, reporta una matriz de cobertura por clase:

 accuracy n_queries covered_in_corpus
ContratoComercial 0.82 142 si
EmpleadoENS-Alto 0.31 18 parcial
DerivadoFinanciero 0.74 67 si
SOAP_3.0_Endpoint 0.05 9 no

La fila EmpleadoENS-Alto con accuracy 0.31 visibiliza un problema invisible sin estratificación. La fila SOAP_3.0_Endpoint con accuracy 0.05 y covered_in_corpus=no indica que la clase ni siquiera tiene corpus — antes de tocar el modelo hay que tocar la ingestión. La métrica única oculta; la métrica por clase acciona.

Esta es la regla que LLM-as-judge y evals deben implementar siempre que exista una ontología: el golden eval set se etiqueta por clase y todas las métricas se reportan estratificadas.

Etapa 4 — Deploy

En el router de inferencia LLM la ontología habilita:

Semantic routing por clase. Queries que tras una primera clasificación caen bajo FIBO:Securities se enrutan al adapter fine-tuneado en finanzas; queries bajo SNOMED:ClinicalFinding al adapter médico. Sin ontología, este routing se basa en clasificadores ad-hoc o en heurísticas léxicas frágiles.
Tool calling tipado. Las herramientas que el agente puede invocar declaran sus argumentos contra clases de la ontología. El argumento cliente_id no es string; es :ClienteCorporativo. Antes de ejecutar la tool, los argumentos se validan con SHACL. Reduce drásticamente los errores por argumentos mal poblados.
Feature flags con clase. El canary se hace “el nuevo modelo recibe el 10% de las queries de la clase X” en vez de un 10% indiferenciado: aísla el blast radius.

Etapa 5 — Observe

Es donde la ausencia de ontología duele más rápido en operación. Los runbooks de incident response requieren:

Taxonomía de incidentes formal. IncidenteSeguridad ⊑ Incidente, IncidenteIA ⊑ Incidente, FugaDatos ⊑ IncidenteSeguridad. Sin esta taxonomía, los cinco eventos del último mes etiquetados como “model issue”, “data drift”, “pii leak”, “prompt injection” y “hallucination” no son agrupables ni comparables. Keep + Kafka aplican la deduplicación contra esa taxonomía.
Lineage tipado en el KG. La observabilidad GPU + tracing emite spans con atributos. Si esos atributos son tipados contra la ontología (span.input.classification = :ConfidencialMedio), buscar todos los requests que tocaron clase ConfidencialAlto en la última hora es una query SPARQL trivial; sin ontología, es un grep sobre logs no estructurados.

Etapa 6 — Govern

Donde la ontología se hace inevitable. Cada marco regulatorio es una ontología:

ENS RD 311/2022 Anexo I: define cinco dimensiones (C, I, D, A, T) × tres niveles (Bajo, Medio, Alto). Es un esquema de clasificación de activos. Anexo II enumera 73 medidas de control con jerarquía organizativa / operacional / protección. Los controles técnicos ENS mapean cada control a componentes del stack — ese mapeo es una ontología relacional.
ISO 42001 Annex A: enumera controles agrupados (A.5 políticas, A.6 organización interna, A.7 recursos para IA, A.8 evaluación, A.9 operación). El AIMS sobre LLM on-premise los formaliza.
EU AI Act Anexo III: ocho áreas de alto riesgo. Los mapeos del expediente técnico son una traducción de la ontología legal a la ontología técnica del sistema.

Sin una ontología que mapee tu inventario de assets, datasets, modelos y endpoints a las clases de estos tres marcos, el compliance es manual, reactivo y se rompe con cada cambio del stack. Con la ontología, un cambio de modelo dispara automáticamente qué controles se ven afectados.

El campo GraphRAG en 2026

GraphRAG es el nombre genérico de una familia de técnicas que construyen un knowledge graph desde un corpus y lo usan como capa adicional de retrieval complementaria al dense / sparse / multi-vector que vimos en embeddings. La motivación es que algunas queries —“cuáles son los temas dominantes en este corpus”, “qué entidades aparecen conectadas con el cliente X en los últimos seis meses”— no se responden bien por similitud coseno entre vectores.

Microsoft GraphRAG

microsoft/graphrag (julio 2024, v1.0 dic 2024, v2.x oct 2025; cualquier referencia a v3 hay que verificar en GitHub releases antes de citar). Pipeline canónico:

Extracción. Un LLM lee el corpus por chunks y extrae entidades y relaciones — la TBox emerge de los datos en vez de declararse.
Construcción del grafo. Las entidades extraídas se desambiguan, se mergean y se conecta con las relaciones.
Detección de comunidades con el algoritmo de Leiden. El grafo se particiona en comunidades jerárquicas.
Resúmenes por comunidad. Para cada comunidad, el LLM genera un resumen.
Búsqueda local vs global. Local: traversal vecindario para queries sobre entidades específicas. Global: map-reduce sobre resúmenes de comunidades para queries temáticas.

El precio: la construcción del KG cuesta del orden de 5-20× más tokens que un pase de embeddings del mismo corpus. Para un corpus de 1 millón de chunks con embeddings bge-m3 (un día de cómputo en RTX 4090), un GraphRAG puro requiere típicamente 1-3 semanas de compute en LLM-extractor (Qwen2.5-72B o similar). La variante LazyGraphRAG (mid-2025) demora la generación de resúmenes a query-time y reduce el coste de construcción en un orden de magnitud.

LightRAG

HKUDS/LightRAG (HKU, arXiv:2410.05779, octubre 2024, EMNLP 2025). Mejoras prácticas sobre GraphRAG canónico:

Dual-level retrieval. Cada query genera tanto low-level keywords (entidades específicas) como high-level keywords (temas). El sistema busca por ambos y los fusiona. Captura tanto preguntas factuales como temáticas en el mismo pipeline.
Actualizaciones incrementales. Inserción de nuevos chunks sin reconstruir el grafo completo. GraphRAG canónico requiere reconstrucción periódica.
Coste reportado: comparativamente más barato que GraphRAG al servir queries similares.

Es el GraphRAG operacionalmente más razonable cuando el corpus muta.

HippoRAG 2

OSU-NLP-Group, arXiv:2502.14802 (feb 2025; HippoRAG original NeurIPS'24). Inspirado en el modelo de indexación hipocampal de la memoria humana:

Construye un KG abierto y mantiene además los chunks originales.
Para cada query, extrae entidades y ejecuta Personalized PageRank sobre el grafo seeded por esas entidades — el PageRank “marca” los nodos relevantes y, transitivamente, los chunks asociados.
Reportado +7% en tareas de memoria asociativa sobre embedders SOTA, con coste de indexación significativamente menor que GraphRAG, RAPTOR y LightRAG.

Es el GraphRAG más eficiente para corpora donde “qué chunks son relevantes a qué entidades” importa más que “cuál es la estructura semántica del corpus”.

KAG / OpenSPG

Ant Group + OpenKG, arXiv:2409.13731 (sep 2024). Diferencia clave con los anteriores: KAG es ontology-grounded. No deja que el LLM invente la TBox; la TBox la declara el dominio (FIBO, SNOMED, ontología corporativa) y el LLM solo puebla la ABox conforme a ese esquema. Cuatro pilares:

Representación amigable al LLM — el esquema se expone en formato que el LLM puede consumir como contexto.
Índice mutuo entre KG y chunks — cada nodo del KG enlaza a los chunks donde aparece.
Razonamiento lógico-formal híbrido — combina LLM con motor de reglas declarativo.
Alineamiento semántico — desambiguación de entidades contra el catálogo ontológico.

Reportado +19.6% F1 en 2WikiMultiHopQA, +33.5% en HotpotQA sobre RAG baseline. Desplegado en Q&A de e-gobierno y e-salud de Ant en producción.

KAG es el GraphRAG que sí funciona cuando el dominio tiene una ontología estable (finanzas, salud, gobierno). GraphRAG canónico gana cuando el corpus es exploratorio y no existe TBox previa.

Otros del panorama

nano-GraphRAG: port Python ligero de GraphRAG; ideal para prototipos.
Think-on-Graph (ToG) / GraphReader: agentes que planean traversal de hops sobre el KG en vez de retrieval single-shot. Mejores en multi-hop QA.
Neo4j LLM Graph Builder + integración LangChain: el camino de menor resistencia para empresas con Neo4j ya operativo.

Ontologías verticales que sí se usan en producción

Tres ontologías cubren el 90% de casos verticales en mid-2026:

FIBO — Financial Industry Business Ontology

EDM Council + OMG, MIT license, OWL DL. Production release Q1/2026 contiene 2.446 clases distribuidas en Foundations, Business Entities, Securities, Derivatives, Loans, etc. Usado en producción para:

KYC entity resolution: desambiguación de organizaciones legales (fibo-be-le-fbo:FormalBusinessOrganization).
Clasificación de instrumentos financieros (fibo-sec-sec-bsk:Basket, fibo-der-drc-cds:CreditDefaultSwap).
Reporting regulatorio: mapeo de campos contra el esquema canónico.

Para un RAG corporativo en finanzas, FIBO es el esquema de tipos que cualquier extracción debe satisfacer. Sin FIBO, dos chunks que hablan de “swap” pueden ser un swap de tipos de interés o uno de divisas.

SNOMED CT

IHTSDO/SNOMED International. Releases mensuales (la International Edition de mayo de 2026 publicada el 15 de mayo). Aproximadamente 350.000+ conceptos activos en OWL 2 EL. Licencia gratuita en países miembros (España es miembro vía CSI / Ministerio de Sanidad), comercial fuera. En producción:

Codificación clínica asistida: el LLM propone códigos SNOMED y el sistema valida contra la ontología.
Búsqueda cross-lingüe en historiales: Diabetes mellitus type 2 y Diabetes mellitus tipo 2 resuelven al mismo concepto (73211009).
Compliance HIPAA / RGPD salud: la trazabilidad de qué tipo de dato clínico maneja cada componente.

schema.org

CC-BY-SA, ~800 tipos, JSON-LD nativo. La ontología de la web. Usado en cualquier RAG sobre crawls públicos para tipar Product, Article, Person, Organization desde los microformatos que el corpus ya trae embebidos.

Las otras a tener en el radar

Ontología	Dominio	Licencia	Cuándo usarla
IEC 81346	sistemas industriales (designación =K1-Q1)	propietario IEC	CMDB-as-graph, planta industrial
GS1	cadena de suministro (GTIN, GLN, SSCC)	membership; web vocab libre	trazabilidad EUDR, retail
NIEM	interoperabilidad gov US	CC0	integración gov-to-gov
Wikidata	KB universal (~115M items)	CC0	entity linking universal
ENS RD 311/2022 Anexo I-II	seguridad ESP sector público	BOE público	clasificación de activos en cualquier despliegue ENS
EU AI Act Anexo III	8 áreas de alto riesgo	EU regulation	tagging de compliance EU

Para un cliente español del sector público con sistemas IA, la ontología mínima que conviene tener formalizada es la unión ENS Anexo I + EU AI Act Anexo III + ISO 42001 Annex A. Ese mapeo se genera una vez, se mantiene como artefacto versionado en el repo de gobierno IA y se enlaza desde el lineage de cada modelo desplegado.

Stack open source on-prem 2026

El landscape de implementación se divide en triple stores RDF, property graphs y herramientas auxiliares.

Triple stores RDF / SPARQL

Stack	Licencia	Notas operativas
Apache Jena Fuseki	Apache 2.0	Referencia open. Storage TDB2. Releases trimestrales. El default razonable.
Eclipse RDF4J	EDL/BSD-like	Framework Java + servidor (Sesame-derived). Maduro.
Virtuoso Open Source	GPLv2	Alto rendimiento. La edición Community no incluye clustering.
Ontotext GraphDB Free	EULA propietaria, gratuita hasta 2 queries concurrentes	Razonamiento OWL 2 RL fuerte. Cap operacional en concurrencia.
Stardog	propietario	Sin tier gratuito de producción genuino en 2026 — solo developer.
Blazegraph	discontinuado	Wikidata está migrando a Qlever / otros. No empezar proyecto nuevo.

Property graphs (Cypher / Gremlin)

Stack	Licencia	Notas operativas
Neo4j Community Edition	GPLv3 (con histórico Commons Clause en algunos artefactos); Enterprise cerrado	Vector index nativo desde 5.11. Cypher 25 añade cláusula `SEARCH`. Cypher AI procedures (dic 2025) integran LLM calls y embedding generation en la query. Implicación AGPL: si redistribuyes un SaaS que expone funcionalidad de Neo4j Community puede exigir disclosure del source — verifica con legal.
Memgraph	BSL → Apache tras 4 años	In-memory, Cypher. Más rápido que Neo4j para workloads de query intensivos.
NebulaGraph	Apache 2.0	Distribuido. Para tamaños grandes.
ArangoDB	Apache 2.0 (Community); features migradas a Enterprise post-3.12	Multi-modelo (graph + document).
KuzuDB	MIT	Kùzu Inc. archivó el repo upstream en oct-2025. Forks comunitarios: `bighorn` (Kineviz), `ryugraph`. Considera el upstream sin mantenimiento.

Híbrido vector + grafo

Neo4j 5.x con HNSW nativo: vector como propiedad de nodo, búsqueda dentro de Cypher. La opción más integrada.
Memgraph + pgvector: dos stacks, dos puntos de operación.
Qdrant con payload de grafo: no es un grafo de verdad, pero permite filtros tipo k-hop básicos sobre payload.

Editores y herramientas

Protégé (Stanford, BSD): editor de ontologías de facto. Suite con HermiT, Pellet, ELK reasoners.
TopBraid Composer: comercial; útil si ya está en la organización.
Atomgraph: editor web LGPL.

Construcción del KG con LLM

GLiNER / GLiREL (Apache 2.0): NER y relation extraction zero-shot. Mucho más baratos que LLM-extractor (10-100× menos tokens).
REBEL (MIT): joint entity + relation extraction basado en BART. SOTA durante años, hoy superado por LLM-extractors pero sigue siendo razonable para baseline.
LLM-extractor con structured output: vLLM + XGrammar o Outlines enforcing un JSON Schema derivado de SHACL. XGrammar es el backend por defecto de vLLM / SGLang / TensorRT-LLM desde marzo 2026, con <40 µs/token de overhead.

SPARQL clients

rdflib (Python, BSD), Apache Jena CLI, Comunica (MIT, JS, federación SPARQL nativa).

Cinco patrones de integración LLM × ontología

Casi todo lo útil cabe en cinco patrones repetibles.

1. Extracción guiada por esquema

El LLM emite JSON conforme a un schema derivado de la ontología, validado en el decoder con structured output. La salida es ABox tipada lista para insertar como triplas:

schema = derive_json_schema_from_shacl("PersonShape.ttl")
# El LLM solo puede emitir tokens que mantengan la salida válida.
extracted = llm.generate(prompt=document, schema=schema)
graph.add_triples(jsonld_to_rdf(extracted))

Coste: prácticamente cero overhead por token con XGrammar; eliminación efectiva de “salidas que no validan”.

2. Text-to-SPARQL con firewall semántico

El LLM genera SPARQL; un firewall semántico valida cada predicado y clase contra el TBox antes de ejecutar la query:

sparql_text = llm.generate(prompt=user_query, context=ontology_summary)
query = parse(sparql_text)
for predicate in query.predicates:
 if predicate not in ontology.declared_predicates:
 raise UnknownPredicate(predicate)
result = endpoint.execute(query)

Captura el patrón clásico del LLM inventando un predicado plausible que no existe en la ontología, antes de tocar el triple store.

3. Retrieval híbrido dense + sparse + KG con RRF

El reranker hybrid retrieval se amplía con un cuarto canal: traversal en el KG seeded por las entidades extraídas de la query. Los rankings de los cuatro canales se fusionan con Reciprocal Rank Fusion:

\text{RRF}(d) = \sum_{c \in \{\text{dense}, \text{sparse}, \text{colbert}, \text{kg}\}} \frac{1}{k + \text{rank}_c(d)}

con k=60 típico. El canal KG cubre exactamente las queries que rompen los otros tres: queries con entidades nombradas que el dense malinterpreta o que aparecen rara vez en el corpus.

4. Reranking por distancia de grafo

Entre los candidatos del primer comité de retrieval, se prefieren los chunks cuyas entidades estén dentro de k hops en el KG de las entidades de la query. Implementación práctica: añadir un score graph_distance y fusionarlo en el reranker:

def graph_distance_score(chunk, query_entities):
 chunk_entities = chunk["entities"]
 distances = [
 shortest_path_length(kg, qe, ce)
 for qe in query_entities for ce in chunk_entities
 ]
 return 1 / (1 + min(distances))

5. Tool calling tipado + evals estratificados

Tools declaran sus argumentos como clases ontológicas. Antes de invocar, los argumentos pasan SHACL validation. Evita el bug clásico del agente llamando buscar_cliente(cliente_id="cliente del que se quejó ayer") — un string libre cuando esperaba un IRI.

Evals estratificados por rdf:type o skos:Concept: cada query del golden set lleva su clase ontológica como label, las métricas se reportan por clase, y la accuracy global se complementa con cobertura por clase. Es el mecanismo que evals recomienda y la ontología hace operativo.

Implicaciones para inferencia on-premise

El triple store o property graph no come GPU: corre en CPU + NVMe. Lo que sí compite por GPU es el LLM-extractor que construye y mantiene el KG.

En la RTX 4090 (24 GB)

Setup razonable para PoC y sedes pequeñas:

GPU 24 GB ┐
 ├─ TEI bge-m3 (dense + sparse + colbert) │ ~6 GB VRAM
 ├─ vLLM Qwen2.5-7B-Instruct AWQ Q4 (LLM principal) │ ~8 GB VRAM
 └─ Carga puntual: vLLM Qwen2.5-7B-Instruct para extracción nocturna │ comparte VRAM en otra ventana
CPU/RAM ┐
 ├─ Apache Jena Fuseki (TBox + ABox del KG corporativo) │ ~2 GB RAM por M triplas
 ├─ Qdrant (denso + sparse + colbert) │ ~3 GB RAM por M chunks
 └─ GLiNER + REBEL para extracción rápida en batch │ CPU-only

Para corpora de hasta unos pocos millones de chunks, una RTX 4090 hace el trabajo combinando GLiNER/REBEL en CPU para extracción masiva (barato pero menos preciso) y el LLM en GPU para casos críticos.

En el cluster 4×H100 80 GB

H100 #1 (80 GB) ── vLLM Qwen3-72B-Instruct AWQ + Qwen2.5-7B speculative │ LLM principal
H100 #2 (80 GB) ── vLLM gte-Qwen2-7B-instruct (embedding 32k ctx) │ embedder grande
H100 #3 (80 GB) ── vLLM Qwen2.5-32B-Instruct (extractor KG dedicado) │ construcción + mantenimiento KG
H100 #4 (80 GB) ── Hold-out para canary y evals offline │ ver post canary

Apache Jena Fuseki cluster (3 nodos CPU + NVMe RAID)
 ├─ Ontología corporativa (TBox)
 ├─ ABox (cientos de millones de triplas)
 └─ FIBO / ENS / EU AI Act como named graphs

Qdrant cluster (3 nodos CPU + NVMe)
 ├─ Chunks indexados con triplas en payload
 └─ Lineage hacia nodos del KG

La H100 dedicada al extractor KG es el pago real del enfoque GraphRAG. Si el corpus es estable, esa H100 puede dedicarse a evals offline o speculative decoding. Si el corpus muta a diario, está ocupada manteniendo el grafo en línea.

Las siete trampas operativas

Sobreelevar SKOS a OWL DL por ego académico. La mayoría de “ontologías corporativas” son taxonomías que no requieren razonamiento de description logic. Una SKOS con skos:broader/skos:narrower y skos:prefLabel por idioma cubre el 80% de los casos. OWL DL solo tiene sentido cuando hay axiomas de consistencia que el reasoner debe verificar. Empieza por SKOS, sube a OWL EL/RL si lo necesitas, evita OWL DL salvo necesidad probada.
Construir un KG de todo el corpus. GraphRAG canónico aplicado a 100 millones de chunks cuesta como entrenar un modelo pequeño. La alternativa correcta es HippoRAG 2 / LightRAG / KAG según el caso o GraphRAG solo sobre el subset crítico del corpus. La regla: si el coste de construcción excede el coste anual de servir el modelo, has elegido la herramienta equivocada.
TBox creada por LLM sin gobernanza. Microsoft GraphRAG genera la TBox emergente desde los datos. Para un corpus exploratorio funciona; para un dominio regulado (finanzas, salud, gobierno) la TBox no se descubre, se declara — FIBO, SNOMED, ENS. KAG es la elección correcta en esos casos.
Olvidar el mantenimiento del KG cuando el corpus cambia. Los nuevos chunks introducen entidades nuevas. Si no hay proceso de reconciliación de entidades (desambiguación, merging), el grafo acumula duplicados de la misma entidad con IRIs distintos y la calidad colapsa silenciosamente en seis meses. LightRAG tiene primitivas para esto; GraphRAG canónico requiere reconstrucción periódica.
JSON Schema desincronizado del SHACL. Si la ontología vive en RDF/SHACL y los structured outputs vienen de un JSON Schema escrito a mano, se desincronizan. Lo correcto es generar el JSON Schema desde el SHACL con herramientas como shacl-to-json-schema y regenerarlo en CI cada vez que cambia el shape.
Neo4j Community licenciado mal. GPLv3 implica que cualquier modificación que distribuyas tiene que liberarse con la misma licencia. Si vas a redistribuir un producto que embebe Neo4j Community, verifica con legal o usa una alternativa con licencia más permisiva (Memgraph BSL, Apache Jena para RDF, Kùzu fork bighorn).
Ontología de compliance no enlazada al stack técnico. Tu mapeo de ENS / ISO 42001 / EU AI Act vive en un Excel del equipo de gobierno. Tu inventario de modelos, datasets y endpoints vive en otro sistema. Sin enlace formal entre ambos, ningún cambio del stack dispara la revisión de compliance correspondiente. El mapeo va al grafo, no al Excel.

Conclusión

Una ontología no es una alternativa al RAG; es la nomenclatura que hace comparables sus piezas. Sin ella, el corpus se cura con categorías ad-hoc, los embeddings perforan documentos sin enriquecerse, los evals miden la media en vez de la varianza por clase, el guardrail bloquea por listas en vez de por tipos, el incident response agrupa mal porque cada alerta nombra a su manera, y el compliance es un Excel desincronizado del sistema. Las seis etapas LLMOps están todas mejor cuando comparten vocabulario, y compartir vocabulario quiere decir formalizar una ontología corporativa pequeña, alineada con los marcos verticales pertinentes (FIBO, SNOMED, schema.org, ENS, EU AI Act), serializada en JSON-LD para que el código la consuma sin fricción, validada con SHACL en cada interface y consultada con SPARQL cuando hace falta razonar. GraphRAG en sus variantes 2026 (Microsoft v2, LightRAG, HippoRAG 2, KAG) es una palanca complementaria, no el plato principal: el plato principal es la nomenclatura formal compartida. Lo demás —Neo4j vs Jena, OWL DL vs SKOS, GLiNER vs LLM-extractor— son decisiones técnicas que se resuelven mejor cuando ya hay claridad sobre qué nomenclatura hace falta. Linneo descubrió esto en 1735 y la biología no ha vuelto atrás; el campo LLM lo está descubriendo en 2026 y tampoco volverá.

Ver también

El pipeline LLMOps de seis etapas — el mapa maestro de las seis etapas que este post atraviesa transversalmente.
RAG corpus curation: el bibliotecario activo — la curación se vuelve curación dirigida por ontología cuando hay TBox declarado.
Embeddings en 2026: las tres familias — los embeddings se enriquecen con metadatos tipados desde la ontología.
Reranker y hybrid retrieval — el KG es el cuarto canal de retrieval, fusionado vía RRF junto a dense / sparse / multi-vector.
Structured output — los JSON Schemas con los que se construye el KG desde el LLM derivan de SHACL.
Evals para LLMs — las métricas estratificadas por clase ontológica son la palanca operacional que la ontología habilita.
Tracing LLM con OpenTelemetry GenAI — los spans llevan atributos tipados contra el TBox.
Runbooks de incident response — la taxonomía formal de incidentes habilita la deduplicación de Keep + Kafka.
Router de inferencia LLM — el routing semántico por clase ontológica.
Canary, blue-green y shadow — el canary por clase reduce el blast radius.
Controles técnicos ENS × ISO 42001 × EU AI Act — cada marco regulatorio es una ontología y se mapea como tal.
ISO/IEC 42001: AIMS — el Annex A es una jerarquía de controles formalizable como SKOS.
EU AI Act: expediente técnico — el Anexo III es una clasificación enumerable mapeable a las clases del sistema.

Referencias

W3C. RDF 1.1 Concepts and Abstract Syntax. https://www.w3.org/TR/rdf11-concepts/
W3C. OWL 2 Profiles (EL, QL, RL, DL). https://www.w3.org/TR/owl2-profiles/
W3C. SHACL — Shapes Constraint Language. https://www.w3.org/TR/shacl/
W3C. SKOS Reference. https://www.w3.org/TR/skos-reference/
W3C. JSON-LD 1.1. https://www.w3.org/TR/json-ld11/
W3C. SPARQL 1.1 Query Language. https://www.w3.org/TR/sparql11-query/
Edge et al. From Local to Global: A Graph RAG Approach to Query-Focused Summarization. Microsoft Research, 2024. https://arxiv.org/abs/2404.16130
Microsoft GraphRAG. https://github.com/microsoft/graphrag
Guo et al. LightRAG: Simple and Fast Retrieval-Augmented Generation. arXiv:2410.05779, 2024. https://arxiv.org/abs/2410.05779
Gutiérrez et al. HippoRAG: Neurobiologically Inspired Long-Term Memory for Large Language Models. NeurIPS 2024. https://arxiv.org/abs/2405.14831
Gutiérrez et al. From RAG to Memory: Non-Parametric Continual Learning for Large Language Models (HippoRAG 2). arXiv:2502.14802, 2025. https://arxiv.org/abs/2502.14802
Liang et al. KAG: Boosting LLMs in Professional Domains via Knowledge Augmented Generation. arXiv:2409.13731, 2024. https://arxiv.org/abs/2409.13731
OpenSPG / KAG. https://github.com/OpenSPG/openspg
EDM Council. Financial Industry Business Ontology (FIBO). https://spec.edmcouncil.org/fibo/
SNOMED International. https://www.snomed.org/
schema.org. https://schema.org/
Real Decreto 311/2022, de 3 de mayo, por el que se regula el Esquema Nacional de Seguridad. BOE-A-2022-7191. https://www.boe.es/eli/es/rd/2022/05/03/311
Reglamento (UE) 2024/1689 (EU AI Act). https://eur-lex.europa.eu/eli/reg/2024/1689
ISO/IEC 42001:2023 — Artificial Intelligence Management System. https://www.iso.org/standard/81230.html
Apache Jena. https://jena.apache.org/
Neo4j Cypher and AI procedures. https://neo4j.com/docs/
Protégé. https://protege.stanford.edu/
GLiNER. https://github.com/urchade/GLiNER
REBEL. https://github.com/Babelscape/rebel

Embeddings en 2026: las tres familias (denso, esparso, multi-vector), el zoo de modelos y la decisión que importa en producción

Wed, 03 Jun 2026 03:00:00 +0200

Este post abre la subsaga de datos dentro del pipeline LLMOps de seis etapas entrando a la pieza que sostiene el retrieval de tres capas: el embedder. Si el bibliotecario de la curación decidía qué entra al índice y el comité de la cátedra decidía qué sale a la cara del modelo, este post mira al de en medio: el cartógrafo que dibuja el mapa por el que se busca.

TL;DR

La conversación sobre embeddings se ha simplificado en producción hasta el punto de que “qué embedder usas” recibe siempre la misma respuesta: OpenAI text-embedding-3-large en el demo, bge-m3 en la versión “sovereign-ready”. Bajo esa simplificación se esconde el hecho de que un embedder es tres modelos distintos a la vez —denso single-vector, esparso aprendido (SPLADE) y multi-vector late-interaction (ColBERT)— y que en 2026 los modelos punteros no compiten en la misma familia: gte-Qwen2-7B-instruct y NV-Embed-v2 rompen MTEB en single-vector denso, SPLADE-v3 y la cabeza esparsa de bge-m3 dominan el descriptor léxico aprendido, Jina-ColBERT-v2 y ColNomic-7B son lo más fuerte en multi-vector multilingüe, y Snowflake Arctic Embed L 2.0 se ha colado como el favorito multilingüe pequeño con Matryoshka decente. Este post desmonta las tres familias con sus matemáticas (InfoNCE con τ, MaxSim, FLOPS regularization de SPLADE, Matryoshka Representation Learning), repasa el zoo de modelos open source con dimensión, licencia y nicho de cada uno, plantea el problema específico del español multilingüe —que reduce la lista de modelos viables a menos de seis—, cuenta el coste real de almacenamiento por millón de chunks con int8 / binario / TurboQuant, describe cómo se sirven on-premise con TEI, Infinity y vLLM --task embed, fija el hardware mínimo en una RTX 4090 y el bueno en un cluster 4×H100, lista las siete trampas operativas que tiran la calidad sin aviso (drift del corpus, normalización olvidada, dimensión Matryoshka mal elegida, hard negatives ausentes, chat template colado en el embedder, tokenizer drift, MTEB overfit) y cierra con un stack license-clean para producción soberana.

La analogía: tres bibliotecarios fichando el mismo libro

Una biblioteca técnica recibe un libro nuevo y antes de meterlo en las estanterías tiene que generarle un identificador buscable. En la biblioteca conviven tres bibliotecarios con tres oficios distintos, y los tres fichan el mismo libro a la vez:

Bibliotecario A — el temático. Lee el libro entero y le pone una sola etiqueta RFID rica. Esa etiqueta es un vector de 1.024 números donde cada coordenada codifica un eje semántico latente (que el bibliotecario nunca verbaliza: lo ha aprendido leyendo cien millones de libros previos). Dos libros sobre Kubernetes en producción acabarán con etiquetas RFID muy cercanas en el espacio aunque uno hable de Linkerd y el otro de Cilium, porque comparten ejes temáticos. Para buscar, comparas la etiqueta de la pregunta con la del libro y devuelves los más próximos por coseno. Es rápido, escala a millones, y se pierde matices finos. Este es el embedder denso single-vector: bge-m3 en modo dense, gte-Qwen2-7B-instruct, Snowflake Arctic Embed L 2.0, multilingual-e5-large-instruct.

Bibliotecario B — el léxico. No resume nada. Lo que hace es escribir en una ficha la lista pesada de términos relevantes del libro, expandida con sinónimos del campo. El libro de Kubernetes lleva en su ficha “kubernetes 4.2, linkerd 3.8, cilium 3.7, service-mesh 4.1, sidecar 3.2, mtls 2.9, ebpf 2.6, k8s 4.0…” — cada término con un peso. La gracia es que la expansión la hace el modelo: si tu pregunta dice “service mesh” y el libro original solo decía “Linkerd”, la ficha del bibliotecario B sí registró “service-mesh 4.1” porque entendió la relación. Para buscar, intersectas la ficha de la pregunta con la del libro a la vieja usanza: índice invertido, posting lists. Es decisivo cuando el lector escribe pocas palabras muy concretas (nombres de producto, errores, jerga). Este es el embedder esparso aprendido: SPLADE-v3 o la cabeza sparse de bge-m3. Es el sucesor moderno de BM25, no su rival; veremos por qué.

Bibliotecario C — el copista. Se rinde a resumir. Coge cada palabra de cada página del libro y le pone una mini-RFID de 128 dimensiones. Acaba con un libro de 30.000 tokens convertido en 30.000 mini-RFIDs. Cuando buscas algo, el bibliotecario compara cada palabra de tu pregunta con cada palabra del libro y se queda con el máximo por cada palabra de la pregunta, sumándolos. Captura matices que los otros dos pierden por construcción (nombres propios, números, formulaciones específicas), pero su sistema de archivado es un orden de magnitud mayor en espacio en disco. Es ColBERT-v2 / Jina-ColBERT-v2 / ColNomic-7B: late interaction, MaxSim.

Y luego está el bibliotecario polivalente que hace los tres trabajos en una sola pasada: bge-m3. Un solo modelo de 568 M parámetros que devuelve simultáneamente la etiqueta RFID temática (1.024-d), la lista pesada de términos (esparsa) y el conjunto de mini-RFIDs por token (128-d). Esa es la razón por la que se ha consolidado como el embedder estándar de RAG on-premise multilingüe: un único model.encode(chunk) produce las tres salidas que alimentan el retrieval híbrido sin orquestar tres modelos distintos.

El mismo chunk indexado por tres bibliotecarios. El polivalente bge-m3 ejecuta los tres en una sola pasada de 568 M parámetros.

Qué es realmente un embedding

Un embedding de texto es una función f : texto → ℝᵈ entrenada para que dos textos “semánticamente parecidos” produzcan vectores cercanos en ese espacio. La parte importante no es “vector” —cualquier hash de longitud fija lo es— sino qué significa cercanía. La cercanía se define implícitamente por la pérdida con la que el modelo se entrena.

Casi todos los embedders modernos se entrenan con InfoNCE (también llamado Multiple-Negatives Ranking Loss en sentence-transformers):

\mathcal{L}_{\text{InfoNCE}} = -\log \frac{\exp(\text{sim}(q, d^+)/\tau)}{\sum_{d \in \mathcal{B}} \exp(\text{sim}(q, d)/\tau)}

Para cada pareja (query, doc⁺) el modelo tiene que asignar al positivo más similitud que a todos los demás documentos del batch B, donde los demás documentos hacen de in-batch negatives gratis. La temperatura τ (típica 0.02–0.07, casi siempre 0.05) controla cuánto se afila la distribución: τ baja → el modelo se vuelve más exigente con el positivo pero más inestable. Tamaño de batch |B| grande → muchos más negativos por gradiente → modelo más informado. Por eso los embedders se entrenan con batch ≥ 1.024 en clusters de H100 con AllGather entre nodos para apilar todos los negativos del cluster como un solo batch efectivo.

A los negativos in-batch se les añade hard negatives mining: documentos seleccionados a propósito porque están “casi en la respuesta” (típicamente los siguientes 10-100 vecinos de un retrieval BM25 / dense previo). Sin hard negatives el modelo aprende a discriminar lo trivial y la calidad real en BEIR / MTEB se hunde 5-10 puntos.

Esto importa porque la familia de embedder depende de qué entras a sim(·,·):

Familia	`sim(q, d)`	Salida del modelo
Denso single-vector	producto escalar de dos vectores 1024-d normalizados	`f(q), f(d) ∈ ℝ^d`
Esparso aprendido	producto escalar de dos vectores 30.522-d (≈80 no-cero cada uno)	`f(q), f(d) ∈ ℝ^V`, `V =
Multi-vector	`Σᵢ maxⱼ ⟨qᵢ, dⱼ⟩` (MaxSim)	`f(q) ∈ ℝ^{

La pérdida es la misma en los tres casos —InfoNCE— pero la geometría del espacio cambia, y con ella la calidad, el coste de almacenamiento y la latencia de búsqueda.

Las tres familias en detalle

Denso single-vector — el cartógrafo

El embedder lee el chunk completo, lo pasa por un transformer codificador (XLM-RoBERTa, BERT, Mistral-decoder con prompt) y agrega las representaciones de tokens en un único vector mediante:

CLS pooling: usa el embedding del token [CLS]. Estándar en BERT-base.
Mean pooling: media simple de los embeddings de todos los tokens. Estándar en multilingual-e5-large-instruct, bge-m3 dense, Snowflake Arctic Embed L 2.0.
Last-token pooling: para embedders basados en decoder-LLM (e5-mistral-7b-instruct, gte-Qwen2-7B-instruct, NV-Embed-v2) que toman el token final como agregado. Funciona porque el modelo es causal y el último token “ha visto” todo el contexto.
Latent-attention pooling: novedad de NV-Embed-v2. Una capa de atención learnable que pondera tokens en vez de promediarlos. +2-3 puntos MTEB sobre mean pooling.

Tras el pooling se normaliza a norma 1: v ← v / ‖v‖₂. Con vectores normalizados, coseno y producto escalar coinciden:

\cos(q, d) = \frac{q \cdot d}{\|q\|\|d\|} = q \cdot d, \qquad \|q - d\|^2 = 2 - 2\,(q \cdot d)

Por eso casi todos los vector DB indexan por inner product y dejan al usuario que normalice antes (Qdrant, Faiss IP, Milvus). Si olvidas normalizar el vector de la query pero los del corpus sí están normalizados, el retrieval se degrada en silencio: la magnitud de la query distorsiona el ranking. Es el bug número uno en RAG en producción.

Ejemplo numérico mínimo, dos vectores 4-d normalizados:

q = [0.5, 0.5, 0.5, 0.5] ‖q‖ = 1
d₁ = [0.6, 0.4, 0.5, 0.5] ‖d₁‖ = 1.005, normalizado [0.597, 0.398, 0.498, 0.498]
q · d₁ = 0.5·0.597 + 0.5·0.398 + 0.5·0.498 + 0.5·0.498 = 0.995

Cercanía cuasi-1, como esperábamos. Si d₁ no estaba normalizado, q · d₁ = 1.0 y aparecería más cerca que cualquier d perfectamente alineado pero con norma < 1.005. La normalización no es un detalle: es el contrato del espacio.

Esparso aprendido — el descriptor léxico

SPLADE-v3 (Naver, marzo 2024) ha consolidado la versión moderna del bibliotecario léxico. Internamente es un BERT pequeño (~110 M parámetros, base DistilBERT/BERT) que produce, para cada token de entrada, una distribución sobre todo el vocabulario (30.522 dimensiones en BERT WordPiece), y luego hace max-pool sobre los tokens:

w_j = \max_{i \in \text{seq}} \log\bigl(1 + \text{ReLU}(W_{ij})\bigr)

donde Wᵢⱼ es el logit del token de entrada i para el término del vocabulario j. El log(1+ReLU) satura los logits altos (evita que una sola palabra domine el vector) y la ReLU corta los negativos. El resultado es un vector de 30.522 dimensiones del que típicamente quedan 50-200 entradas no nulas.

La parte clave es la regularización FLOPS que se añade a la pérdida durante el entrenamiento:

\mathcal{L}_{\text{FLOPS}} = \lambda \cdot \sum_{j=1}^{V} \bar{w}_j^2, \qquad \bar{w}_j = \frac{1}{|B|}\sum_{i \in B} w_{ij}

Penaliza el coste esperado de los posting lists: si una palabra del vocabulario aparece en promedio en muchos documentos, sumarla a un nuevo documento penaliza el doble. El modelo aprende a generar vectores esparsos por construcción.

¿Esto qué le pasa al texto “Linkerd 3.8 introduce mTLS por defecto”? Que el modelo no solo escribe los términos literales — escribe también, con peso menor pero no cero, “service-mesh”, “kubernetes”, “tls”, “sidecar”, “envoy”, “istio” (su competidor, también semánticamente relacionado), “encryption”, “k8s”. Esa expansión semántica del documento es lo que diferencia SPLADE de BM25. BM25 solo sabe lo que estaba literalmente en el texto; SPLADE sabe lo que un experto añadiría como descriptor.

En la práctica SPLADE-v3 vence a BM25 por 3-6 puntos MRR@10 en MS MARCO y domina BEIR zero-shot. El coste es ~2-4× la latencia de query de BM25 sobre el mismo índice invertido, mitigable con podas estáticas.

Para el caso multilingüe, bge-m3 en su cabeza sparse es la única opción mantenible: SPLADE-v3 está entrenado en inglés y los ports multilingües están en estado experimental.

Multi-vector — el copista

ColBERT-v2 (Stanford, NAACL 2022) introdujo el paradigma de late interaction. En vez de comprimir el documento a un solo vector, lo deja como una matriz (|d|, k) con un vector de k dimensiones por cada token. La similitud entre query y documento se calcula token-a-token y se agrega con MaxSim:

s(q, d) = \sum_{i \in q} \max_{j \in d} \langle q_i, d_j \rangle

Lo que se está computando: para cada palabra de la query, encuentra el token del documento que mejor le encaja y suma esa similitud. La suma es sobre la query, no sobre el documento. Esto permite que un documento de 30.000 tokens compita justo con otro de 200, porque la query siempre suma |q| términos.

¿Por qué le da más calidad que el dense single-vector? Porque el resumen a un vector pierde información sobre dónde estaba cada idea. Si la query es “qué versión introdujo mTLS por defecto en Linkerd”, el resumen denso del documento solo sabe que el chunk va de “Linkerd y mTLS”; el copista de ColBERT puede emparejar “qué versión” con “3.8” porque guarda el embedding del token 3.8 por separado. En BEIR / out-of-domain, late interaction supera a single-vector entre +2 y +6 nDCG@10 con el mismo backbone.

El precio es el almacenamiento. Por documento, un dense single-vector de 1024 dimensiones en fp16 ocupa 1024 × 2 = 2 KB. ColBERT-v2 con tokens de 128 dimensiones para un chunk de 256 tokens ocupa 256 × 128 × 2 = 65.536 B ≈ 64 KB: 32× más espacio. Con la compresión residual nbits=2 de ColBERT-v2 baja a ~16 KB (8×). Jina-ColBERT-v2 añade Matryoshka sobre las dimensiones del token (truncable a 128 / 96 / 64), bajando otro 50%.

Para 1 millón de chunks:

Familia	Por doc	Total
Denso fp32 (1024-d)	4.096 B	4,0 GB
Denso fp16 / halfvec	2.048 B	2,0 GB
Denso int8 (SQ)	1.024 B	1,0 GB
Denso binario (1 bit/d)	128 B	128 MB
SPLADE (≈ 80 términos × 8 B)	~640 B	~640 MB
ColBERT fp16 (256 tok × 128 d)	65.536 B	64 GB
ColBERT residual `nbits=2`	~16.000 B	~16 GB
Jina-ColBERT-v2 (MRL token 64)	~8.000 B	~8 GB

ColBERT en producción on-premise se reserva para corpus de hasta unos pocos millones de chunks, o se aplica solo como reranker sobre los top-100 del primer comité (denso + esparso), como se describe en el post de reranker.

Matryoshka — la dimensión truncable

Una palanca operativa que ha cambiado la conversación sobre embeddings entre 2024 y 2026 es Matryoshka Representation Learning (Kusupati et al., NeurIPS 2022). El truco: durante el entrenamiento, además de la pérdida sobre el vector completo de D dimensiones, se calcula la misma pérdida sobre prefijos del vector:

\mathcal{L}_{\text{MRL}} = \sum_{k \in \{64, 128, 256, 512, 1024\}} \alpha_k \cdot \mathcal{L}_{\text{InfoNCE}}\bigl(\text{emb}[:k]\bigr)

Las primeras k dimensiones del embedding se entrenan para ser, por sí solas, un embedding válido. En inferencia, si quieres un embedding más barato, truncas el vector: el primer cuarto es ya un embedding utilizable. Sin Matryoshka, truncar destroza la geometría: las primeras 256 dimensiones de un embedding entrenado solo en 1024-d no codifican nada coherente.

Degradación típica en MTEB nDCG@10 al truncar un embedder MRL:

Truncado	Pérdida promedio
1024 → 512	-1 a -2 puntos
1024 → 256	-3 a -5 puntos
1024 → 128	-5 a -8 puntos
1024 → 64	-8 a -12 puntos

Modelos MRL nativos en 2026 (los que te permiten elegir la dimensión en runtime sin reentrenar):

jina-embeddings-v3 (1024 → 32, paso fino, CC-BY-NC-4.0)
jina-embeddings-v4 (2048 → 128, multimodal texto+imagen, CC-BY-NC-4.0)
nomic-embed-text-v2-moe (768 → 256, Apache 2.0)
Snowflake-arctic-embed-l-v2.0 (1024 → 256, Apache 2.0)
mxbai-embed-large-v1 y mxbai-embed-2d-large-v1 (este último también truncable en profundidad de capa)
Stella_en_1.5B_v5 (paso múltiple 512 / 768 / 1024 / 2048 / 4096 / 6144 / 8192, MIT, solo inglés)
text-embedding-3-large (OpenAI, 3072 → 256, API only)
voyage-3 family (1024 → 256 / 512 / 1024 / 2048, API only)

Recomendación de producción: usa siempre un modelo MRL aunque no truques al inicio, porque la decisión de cuantización futura te la simplifica. Y, sobre todo, evalúa el truncado con tu corpus real: la degradación promedio MTEB de “-3 puntos” se vuelve “-12 puntos” en un dominio nicho.

El zoo de modelos open source 2026

Lo que sigue es una ficha técnica por modelo. Verificación al 2026-06: HuggingFace cards + papers de referencia + leaderboard MTEB / MMTEB.

Denso single-vector

Modelo	Params	Dim	Tokens	Idiomas	Licencia	Distintivo
`BAAI/bge-m3` (dense)	568 M	1024	8192	100+	MIT	Tri-modo (dense + sparse + colbert) en un forward. Estándar de facto on-prem multilingüe.
`Snowflake/snowflake-arctic-embed-l-v2.0`	568 M	1024 (MRL → 256)	8192	~100	Apache 2.0	Entrenado para multilingüe + inglés sin degradar ninguno. MIRACL 55.8.
`intfloat/multilingual-e5-large-instruct`	560 M	1024	512	~100	MIT	Baseline multilingüe veterano. Ventana corta.
`intfloat/e5-mistral-7b-instruct`	7.1 B	4096	4096	inglés	MIT	Primer decoder-as-embedder en romper MTEB. Inglés.
`Alibaba-NLP/gte-Qwen2-7B-instruct`	7 B	3584	32.768	100+	Apache 2.0	Único con contexto 32k. Top MTEB-en, fuerte multilingüe.
`nvidia/NV-Embed-v2`	7.85 B	4096	32.768	inglés	CC-BY-NC-4.0	Latent-attention pooling. Calidad top. License blocker en prod.
`Linq-AI-Research/Linq-Embed-Mistral`	7 B	4096	4096	inglés	CC-BY-NC-4.0	Top retrieval MTEB ago-2024. No comercial.
`NovaSearch/stella_en_1.5B_v5`	1.54 B	8192 (MRL múltiple)	8192	inglés	MIT	Pequeño + MRL rico. Inglés.
`BAAI/bge-multilingual-gemma2`	9 B	3584	8192	100+	Gemma	Calidad alta, licencia Gemma restringe redistribución.
`BAAI/bge-en-icl`	7 B	4096	8192	inglés	MIT-style	In-context-learning de ejemplos en el prompt.
`mixedbread-ai/mxbai-embed-large-v1`	335 M	1024 (MRL)	512	inglés	Apache 2.0	MRL + binary nativo. Ventana corta.
`jinaai/jina-embeddings-v3`	570 M	1024 (MRL → 32)	8192	89	CC-BY-NC-4.0	LoRA por tarea. No comercial sin licencia.
`nomic-ai/nomic-embed-text-v2-moe`	475 M / 305 M activos	768 (MRL → 256)	512	~100	Apache 2.0	Primer MoE general-purpose en embeddings.

Esparso aprendido

Modelo	Params	Vocab	Tokens	Idiomas	Licencia	Distintivo
`naver/splade-v3`	110 M	30.522	512	inglés	CC-BY-NC-SA-4.0	SOTA sparse aprendido. No comercial.
`BAAI/bge-m3` (sparse head)	568 M	XLM-R vocab	8192	100+	MIT	La única opción multilingüe license-clean.

Multi-vector (late interaction)

Modelo	Params	Dim/token	Tokens	Idiomas	Licencia	Distintivo
`colbert-ir/colbertv2.0`	110 M	128	512	inglés	MIT	El paper original, base de todo.
`jinaai/jina-colbert-v2`	560 M	128 / 96 / 64 (MRL)	8192	89	Apache 2.0	El multi-vector multilingüe license-clean.
`nomic-ai/colnomic-embed-multimodal-7b`	7 B	3584 (Qwen2-VL)	—	~100	Apache 2.0	Multi-vector multimodal texto+imagen. Vidore-v2 SOTA open.

El leaderboard, con cautela

El MTEB / MMTEB (Massive Multilingual Text Embedding Benchmark, Enevoldsen et al., arxiv 2502.13595) es el termómetro estándar. Top retrieval en MMTEB a mediados de 2026 está dominado por Qwen3-Embedding-8B (~70.6 multilingual avg) y Llama-Embed-Nemotron-8B. Por debajo, los modelos de 7B (gte-Qwen2-7B, NV-Embed-v2) y los de 568M (bge-m3, Snowflake-Arctic-L-2.0) compiten por tarea.

Trampa: MTEB se ha empezado a saturar por dataset contamination. Cuanto más alto el ranking, más probable es que el modelo haya visto en entrenamiento subconjuntos de los datasets de evaluación. La regla en producción: el leaderboard es para descartar modelos malos, no para elegir el mejor. La decisión final se toma sobre un eval set propio del dominio, generado con la receta de LLM-as-judge o de evals.

El problema concreto del español multilingüe

Para un cliente español que sirve documentación corporativa, jurídica o de soporte en castellano (y muchas veces catalán / portugués / inglés mezclados), el zoo de embedders se acota a menos de seis modelos viables. Las exclusiones operativas:

Modelos solo en inglés: e5-mistral-7b-instruct, stella-en-1.5B-v5, Linq-Embed-Mistral, mxbai-embed-large-v1, NV-Embed-v2, SPLADE-v3. Reducen el rendimiento en castellano por debajo del nivel aceptable: traducir la query al inglés antes de buscar es una vía, pero introduce latencia, drift de tokenización y otra dependencia de modelo.
Modelos con licencia no comercial: jina-embeddings-v3, jina-embeddings-v4, NV-Embed-v2, Linq-Embed-Mistral. Sirven para PoC, pero a producción comercial exigen acuerdo explícito con el vendor. Salvo que tengas la licencia firmada, hay que excluirlos.
Modelos con licencia Gemma: bge-multilingual-gemma2. Permitido para uso interno, complicado redistribuir pesos a un cliente.

Los que quedan, ordenados por orden de elección práctica en producción soberana:

BAAI/bge-m3 — MIT, 568 M, 100+ idiomas (incluyendo castellano y catalán, entrenados explícitamente), 8.192 tokens, tri-modo dense+sparse+colbert. Default razonable. Cabe en una RTX 4090. Lo sirve TEI y Infinity nativamente.
Snowflake/snowflake-arctic-embed-l-v2.0 — Apache 2.0, mismo tamaño, Matryoshka explícito, mejor MIRACL/CLEF que bge-m3 en algunas tareas multilingües, sin cabeza sparse. Si la prioridad es MMTEB puro en castellano.
intfloat/multilingual-e5-large-instruct — MIT, 560 M, baseline veterano. Ventana de 512 tokens es su gran limitación: documentos largos hay que partirlos antes. Si lo que ya tienes en producción funciona, no migres por moda.
Alibaba-NLP/gte-Qwen2-7B-instruct — Apache 2.0, contexto 32k, calidad alta en castellano (Qwen2 está bien entrenado en español). Si los chunks son largos (más de 4k tokens) y dispones de GPU para servirlo (no entra en 4090; sí en H100). Cabe junto a un LLM en un H100 80GB con cuidado.
nomic-ai/nomic-embed-text-v2-moe — Apache 2.0, 305 M activos, MRL, ~100 idiomas. Si la latencia y el coste por token mandan: el MoE le da throughput desproporcionado para su calidad.
jinaai/jina-colbert-v2 — Apache 2.0, multi-vector multilingüe, como reranker o como retrieval principal en corpus pequeño (< 1 M chunks). El único multi-vector license-clean en castellano.

La regla del pulgar: bge-m3 como dense+sparse en primera línea, jina-colbert-v2 como tercera capa de reranking cuando lo amerita el caso de uso, y Snowflake Arctic L 2.0 como alternativa si el eval específico del corpus prefiere su geometría.

Servir embeddings on-premise

Tres motores se reparten el panorama de servir embeddings on-prem en 2026, con perfiles distintos.

Text Embeddings Inference (TEI) — el estándar

huggingface/text-embeddings-inference es un servidor escrito en Rust con backend Candle / ONNX, FlashAttention integrado y batching dinámico por tokens. Expone una API OpenAI-compatible /v1/embeddings y soporta los tres modos de bge-m3 simultáneamente desde la versión 1.5. Para producción multilingüe es el default obvio.

# values.yaml — TEI sirviendo bge-m3 multilingüe sobre RTX 4090
image: ghcr.io/huggingface/text-embeddings-inference:1.5
args:
 - --model-id=BAAI/bge-m3
 - --pooling=cls
 - --max-batch-tokens=16384
 - --max-concurrent-requests=512
 - --dtype=float16
resources:
 limits:
 nvidia.com/gpu: 1

Throughput orientativo con bge-m3, fp16, secuencia 512 tokens, batch 32:

RTX 4090 (24 GB): ~8–15 k tokens/s
A100 80 GB: ~60 k tokens/s sostenidos
H100 80 GB: ~40–80 k tokens/s, con fp8 ~50% adicional

(Los rangos son aproximados y dependen de batch real, longitud media de secuencia y compilación con FA2/FA3.)

Infinity — el flexible

michaelfeil/infinity (MIT) es un servidor FastAPI multi-modelo capaz de cargar bge-m3, Snowflake Arctic, Jina-v3, Nomic, ColPali, CLAP y rerankers simultáneamente desde la misma API estilo OpenAI. Backend PyTorch + Optimum (ONNX/TensorRT) o CTranslate2. Útil cuando necesitas servir varios embedders distintos (uno para texto, otro para código, otro para imágenes) detrás de un único endpoint, o cuando el modelo todavía no tiene soporte en TEI.

vLLM `--task embed` — para los embedders 7B

Cuando el embedder es realmente un LLM-decoder convertido en embedder (e5-mistral-7b-instruct, gte-Qwen2-7B-instruct, NV-Embed-v2, Stella-1.5B), el lugar natural para servirlo es vLLM, que ya tiene en producción la pila de PagedAttention y continuous batching:

vllm serve Alibaba-NLP/gte-Qwen2-7B-instruct \
 --task embed \
 --dtype bfloat16 \
 --max-model-len 32768 \
 --trust-remote-code

vLLM detecta el pooling correcto (last-token en los basados en Qwen / Mistral) y expone /v1/embeddings compatible con OpenAI. Para clusters de inferencia que ya están corriendo vLLM con un LLM en otro puerto, es la forma natural de servir el embedder sin levantar otro stack.

fastembed — el liviano

qdrant/fastembed carga bge-small, MiniLM, ColBERT y BM25/SPLADE sparse en ONNX-CPU. No es competitivo en throughput contra TEI/Infinity con GPU, pero es la opción correcta cuando hay que servir embeddings en un nodo NUC sin GPU (ver entornos mixtos NVIDIA + Intel) o cuando el embedder forma parte del cliente (preview en una UI, scoring previo en un edge).

Almacenamiento, cuantización y el cálculo del corpus

El embedding no se queda en memoria del embedder: vive en el índice del vector DB y se materializa cada vez que ingestas un nuevo chunk. El cálculo del coste de almacenamiento es lo que decide la dimensión final, no la calidad MTEB. Para 1 millón de chunks con embedder denso a 1024-d:

fp32 : 1.024 dims × 4 B × 1 M = 4.096 MB ≈ 4,0 GB
fp16/halfvec: 1.024 dims × 2 B × 1 M = 2.048 MB ≈ 2,0 GB
int8 (SQ) : 1.024 dims × 1 B × 1 M = 1.024 MB ≈ 1,0 GB
binario : 128 B × 1 M ≈ 128 MB

Las opciones de cuantización en orden de uso real (mid-2026):

halfvec (fp16): el default en pgvector 0.7+ y en cualquier vector DB serio. Pérdida MTEB nula, 2× compresión. Siempre actívalo.
Scalar Quantization int8 (SQ): cada componente del vector se mapea a int8 con un min/max global. Pérdida típica de recall@10: 0–1%. 4× compresión. El default de Qdrant, soportado en Milvus y Weaviate.
Cuantización binaria: bit = sign(v_i - μ_i). 32× compresión bruta. Pérdida en frío 5–15%. Mitigada con rotación previa Hadamard / TurboQuant (Qdrant 1.18, dic 2025): pre-multiplica por una matriz ortogonal aleatoria que reparte la energía entre dimensiones antes de binarizar. Tras TurboQuant la pérdida cae a 1–3%. Combina además con rescoring sobre los fp16 originales para los top-100 candidatos.
Product Quantization (PQ): el clásico de FAISS. Hasta 64× compresión, pérdida 2–5%. Más complejo de operar (requiere entrenar codebook); en 2026 ha cedido terreno a binary + rescoring.

Un corpus de 100 millones de chunks (cifra real de un RAG corporativo grande) con bge-m3 denso:

Formato	Total
fp32	400 GB
fp16	200 GB
int8	100 GB
binario + Hadamard	12,5 GB

La diferencia entre 200 GB y 12,5 GB es la diferencia entre necesitar un nodo dedicado de vector DB con 8 NVMe en RAID y poder caber en RAM de un solo nodo. Para corpus grandes, la cuantización ya no es una optimización: es la única forma de operar.

El integration con vector DB

Los vector DB de 2026 se han convertido en DBs híbridos que indexan los tres tipos a la vez. El mapa rápido:

Vector DB	Híbrido nativo	Multi-vector / ColBERT	Cuantización
Qdrant ≥1.10	RRF/DBSF en `query_points` con dense + sparse + colbert en una colección	Sí, nativo (one-shot MaxSim)	SQ int8, binaria, TurboQuant 1.18
Weaviate	`hybrid(alpha=0.75)` BM25 + dense, named vectors multi-target	Sí, como named vector multi-vector	PQ, SQ, BBQ rotacional 8-bit
Milvus ≥2.4	Multi-vector + sparse en schema; 2.5 añade BM25 full-text nativo	Multi-vector field, MaxSim orquestado desde cliente	SQ, PQ, CAGRA GPU
pgvector 0.7+/0.8	`halfvec`, `sparsevec`, `bit`; HNSW para los tres	No nativo (workaround tabla separada)	`binary_quantize()`, halfvec, rescoring con `<#>` exacto
Elasticsearch / OpenSearch	`sparse_vector` (ELSER, SPLADE) + `dense_vector` HNSW; RRF	OpenSearch 3.x sí	ES 9: `int8_hnsw` por defecto, BBQ binary quantization

Para producción soberana on-prem en castellano, la combinación más fácil de operar en 2026 es Qdrant + bge-m3: una sola colección indexa los tres modos del mismo modelo, el query híbrido con RRF se hace en una llamada, la cuantización TurboQuant baja el corpus a niveles manejables, y el operador es un binario Go con backups simples a S3/MinIO. pgvector + bge-m3 es la otra opción razonable cuando ya tienes Postgres con HA y no quieres meter una segunda DB en el inventario operativo; pierdes multi-vector nativo, pero ganas SQL transversal sobre los chunks.

Los parámetros de HNSW que sí o sí hay que tocar:

M: conexiones por nodo en el grafo. 16–32 típico. Más alto → más recall, más RAM. Para corpus pequeños (<1 M) M=16; para corpus medianos (10 M) M=24; para corpus grandes M=32+IVF-PQ o M=32+binary.
ef_construction: ancho de búsqueda durante la construcción. 100–400. Más alto → grafo mejor, construcción más lenta. Construye con ef_construction=400 aunque sea lento; lo pagas una vez.
ef_search: ancho durante la query. 50–200. La perilla principal del trade-off recall/latencia en runtime. Empieza en 64 y mide.

Implicaciones para inferencia on-premise

El embedder no comparte hardware con el LLM tan cómodamente como podría parecer. Las cuentas:

bge-m3 (568 M) ocupa unos 568 × 2 = 1.136 MB en fp16 para los pesos, más el KV cache de batch, más activaciones temporales. En la práctica se sirve cómodamente en 6–8 GB de VRAM incluso a batch alto. Cabe junto a un LLM de 7B-Q4 en una RTX 4090.
gte-Qwen2-7B-instruct requiere ~14 GB fp16 solo de pesos. No cabe junto a un LLM 7B en una 4090; en una H100 80 GB sí, con cuidado en el batching simultáneo.
jina-colbert-v2 (560 M) ocupa ~1.1 GB de pesos, pero el almacenamiento del índice multi-vector es el coste real: 8 GB por millón de chunks aun con Matryoshka y compresión.

En la RTX 4090 (24 GB)

Stack mínimo realista para un RAG en castellano con corpus <1 M chunks:

GPU 24 GB ┐
 ├─ TEI bge-m3 (dense + sparse + colbert) │ ~6 GB VRAM, ~12 k tok/s
 └─ vLLM Qwen2.5-7B-Instruct AWQ Q4 │ ~8 GB VRAM, ~80 tok/s
CPU/RAM ┐
 ├─ Qdrant con bge-m3 dense + sparse + colbert │ ~3 GB RAM por M chunks
 └─ FastAPI gateway (LiteLLM)

Sirve unas decenas de QPS de RAG con calidad multilingüe decente. Es la configuración de PoC y de despliegue para una sede pequeña.

En el cluster 4×H100 80 GB

Para el caso producción con varios millones de chunks y SLO de p99 < 500 ms:

H100 #1 (80 GB) ── vLLM Qwen3-72B-Instruct AWQ + Qwen2.5-7B speculative ┐
H100 #2 (80 GB) ── vLLM gte-Qwen2-7B-instruct (embedding 32k ctx) │ LLM + embed grande
H100 #3 (80 GB) ── TEI bge-m3 multi-tenant + jina-colbert-v2 reranker │ embed mediano
H100 #4 (80 GB) ── Hold-out para canary / shadow │ ver post canary
 ┘
Qdrant cluster (3 nodos CPU + NVMe) ── 100 M chunks indexados (binary + TurboQuant + rescoring)

Esta configuración separa el LLM grande del embedder grande (que comparten arquitectura Qwen2 pero compiten por VRAM si se les pone en la misma GPU) y deja un H100 entero para variantes en canary. El bge-m3 cabe sobrado con el reranker en una sola H100, sirviendo decenas de miles de requests/min.

Las siete trampas operativas del embedder

No normalizar el vector de la query. Coseno y producto escalar coinciden solo cuando ambos vectores son unitarios. Si en el cliente olvidas v ← v / ‖v‖₂, los resultados están “casi bien” — los top-1 siguen siendo correctos en queries triviales, los top-10 ya no — y nadie se da cuenta hasta que la calidad de RAG cae 8 puntos. Solución: bake la normalización en el adapter del embedder, no en el cliente.
Chat template colado en el embedder. Algunos embedders basados en LLM (e5-mistral-7b-instruct, gte-Qwen2-7B) esperan un prompt instructivo concreto antes del texto a embeber ("Instruct: Retrieve relevant passages\nQuery: ..."). Olvidarlo deja el rendimiento ~5 puntos MTEB por debajo. Solución: leer el usage_template de la model card y meterlo en el wrapper del embedder.
Dimensión Matryoshka mal elegida. El default de muchos clientes Qdrant / pgvector es dim=768. Si tu embedder es MRL nativo a 1024 → 768, OK. Si es 1024 sin MRL, truncar a 768 destroza el espacio (perdida típica -8 puntos MTEB). Solución: usar el dim nativo del modelo y truncar solo cuando el almacenamiento manda, y solo en modelos MRL.
Hard negatives ausentes en fine-tuning. Cuando se fine-tunea el embedder con datos propios (lo cual debería ser práctica estándar para RAG corporativo), si la mini-batch solo lleva positivos y negativos in-batch del mismo dominio, el modelo aprende que cualquier cosa fuera del dominio es negativo, pero dentro del dominio no discrimina. Solución: minar hard negatives con BM25 / dense del propio corpus antes de fine-tunear.
Drift del corpus sin reindexar. Cuando reentrenas o reemplazas el embedder pero solo aplicas el modelo nuevo a chunks nuevos, acabas con el índice mezclando dos geometrías incompatibles. Los chunks del modelo viejo y del nuevo no son comparables por coseno. Solución: cada cambio de embedder es una reindexación completa del corpus, planificada como un retrain operativo.
Tokenizer drift entre cliente y modelo. El cliente Python que prepara las queries usa su propio tokenizer (a veces tiktoken por defecto) y trunca a 8.192 tokens. El embedder usa XLM-R con sentencepiece y trunca a 8.192 de su propio tokenizer. Las queries largas se truncan de manera diferente; los embeddings del corpus son consistentes pero los de query no. Solución: usar el tokenizer del modelo en el cliente o en el wrapper.
MTEB overfit como guía de elección. El leaderboard MTEB se ha vuelto métrica contaminada: hay evidencia de que modelos punteros han visto en entrenamiento subconjuntos de los datasets de evaluación. El modelo +0,5 puntos sobre el segundo no es necesariamente mejor para tu dominio. Solución: un eval set propio del dominio (100-300 query-doc pairs etiquetadas) ejecutado con la receta de evals decide.

Stack license-clean para producción soberana

Pongamos por escrito el final recomendado. Para una organización española sirviendo RAG corporativo on-prem bajo ENS / ISO 42001 / EU AI Act, con corpus 1-50 M chunks en castellano + inglés + catalán:

Capa	Componente	Licencia	Justificación
Embedder dense	`BAAI/bge-m3`	MIT	Multilingüe robusto, 8k tokens, license-clean, servido por TEI
Embedder sparse	`bge-m3` sparse head	MIT	Misma pasada que el dense, no requiere segundo modelo
Reranker capa 2	`BAAI/bge-reranker-v2-m3`	MIT	Cross-encoder multilingüe del mismo equipo
Reranker capa 3 (opcional)	`jinaai/jina-colbert-v2`	Apache 2.0	Multi-vector multilingüe license-clean
Servidor embed	`TEI` + `Infinity` para multi-modelo	Apache 2.0 / MIT	Stack soportado
Vector DB	`Qdrant` (preferido) o `pgvector 0.8`	Apache 2.0 / PostgreSQL	Híbrido nativo + cuantización
Cuantización	`int8 SQ` + `binary + TurboQuant + rescoring`	Apache 2.0	Reduce corpus 16×–32× con < 3% pérdida
Hardware mínimo	RTX 4090 24 GB	—	Para PoC y sedes pequeñas
Hardware producción	Cluster 4×H100 80 GB	—	Para RAG con SLO p99 < 500 ms

El stack alternativo, si MMTEB explícito en castellano pesa más que la tri-modalidad de bge-m3: sustituir bge-m3 por Snowflake/snowflake-arctic-embed-l-v2.0 (Apache 2.0, MRL → 256) y añadir explícitamente SPLADE-v3 o BM25 puro para la capa sparse. Pierde la elegancia del único forward, gana 1-2 puntos en MIRACL castellano.

Conclusión

El embedder es la pieza más fácil de simplificar mal en un RAG y la que más decide la calidad real cuando todo lo demás está en su sitio. Las tres familias (denso, esparso, multi-vector) no son tres opciones a elegir sino tres oficios que bge-m3 ejecuta en una sola pasada y que el retrieval híbrido consume en paralelo. La matemática que importa es modesta —InfoNCE con τ, MaxSim, FLOPS regularization, MRL— pero las trampas operativas son numerosas y silenciosas: normalización olvidada, chat template ausente, dimensión Matryoshka mal elegida, tokenizer drift. Para producción soberana en castellano la lista de modelos viables cabe en menos de una decena, y la decisión real se reduce a “bge-m3 o Snowflake Arctic L 2.0”, con jina-colbert-v2 añadido como capa tres cuando la calidad fina justifica el coste. El stack license-clean cabe en una RTX 4090 para PoC y se escala a un cluster 4×H100 para producción real.

Ver también

El pipeline LLMOps de seis etapas — dónde encaja la pieza de datos / retrieval.
RAG corpus curation — qué entra al índice antes de que el embedder lo vea.
Reranker y hybrid retrieval — qué hace el comité que consume los embeddings.
Ontologías y knowledge graphs en LLMOps — la capa de tipos que enriquece el embedding con metadatos consultables; los chunks no son solo vectores sino instancias tipadas contra TBox.
Evals para LLMs — cómo decides si un embedder es realmente mejor que el actual.
Capacity planning para inferencia LLM — dimensionar GPU para servir embedder + LLM en el mismo cluster.

Referencias

Chen et al. M3-Embedding: Multi-Linguality, Multi-Functionality, Multi-Granularity Text Embeddings Through Self-Knowledge Distillation. arXiv:2402.03216. https://arxiv.org/abs/2402.03216
Sturua et al. Jina Embeddings v3: Multilingual Embeddings With Task LoRA. arXiv:2409.10173. https://arxiv.org/abs/2409.10173
Günther et al. Jina Embeddings v4: Universal Embeddings for Multimodal Multilingual Retrieval. arXiv:2506.18902. https://arxiv.org/abs/2506.18902
Nussbaum et al. Nomic Embed v2: Multilingual Mixture of Experts. arXiv:2502.07972. https://arxiv.org/abs/2502.07972
Wang et al. Improving Text Embeddings with Large Language Models (E5-Mistral). arXiv:2401.00368.
Yu et al. Arctic-Embed 2.0: Multilingual Retrieval Without Compromise. Snowflake, 2024-12. https://www.snowflake.com/blog/arctic-embed-2-multilingual/
Lee et al. NV-Embed: Improved Techniques for Training LLMs as Generalist Embedding Models. arXiv:2405.17428.
Khattab y Zaharia. ColBERT: Efficient and Effective Passage Search via Contextualized Late Interaction over BERT. SIGIR 2020.
Santhanam et al. ColBERTv2: Effective and Efficient Retrieval via Lightweight Late Interaction. arXiv:2112.01488.
Jha et al. Jina-ColBERT-v2: A General-Purpose Multilingual Late Interaction Retriever. arXiv:2408.16672.
Lassance et al. SPLADE-v3. arXiv:2403.06789.
Kusupati et al. Matryoshka Representation Learning. NeurIPS 2022, arXiv:2205.13147.
Enevoldsen et al. MMTEB: Massive Multilingual Text Embedding Benchmark. arXiv:2502.13595.
Hugging Face Text Embeddings Inference. https://github.com/huggingface/text-embeddings-inference
Michael Feil. Infinity. https://github.com/michaelfeil/infinity
Qdrant. TurboQuant 1.18 release notes. https://qdrant.tech/articles/turboquant-quantization/
pgvector. Release notes 0.7 / 0.8. https://github.com/pgvector/pgvector
Hugging Face. Embedding Quantization. https://huggingface.co/blog/embedding-quantization

Entornos mixtos NVIDIA + Intel para inferencia LLM: del cluster H100 central al NUC en la sucursal

Tue, 02 Jun 2026 04:30:00 +0200

Este post complementa los de Capacity planning para inferencia LLM on-premise (que asumía cluster NVIDIA puro), Siete capas del stack (que tampoco entraba en heterogeneidad de hardware) y El router de inferencia LLM (donde el routing por capability cobra todo su sentido cuando hay hardware mixto). Es la pieza que faltaba para hablar de “soberanía de hardware” sin reducirla a “qué fabricante elegir”.

TL;DR

Un cluster productivo de inferencia LLM en 2026 puede dejar de ser monolítico NVIDIA si acepta heterogeneidad como decisión arquitectónica. La motivación no es teoría sino tres ventajas operativas medibles. (1) Coste: un Intel Xeon 6 con AMX (Advanced Matrix Extensions) entrega 7B INT4 a ~80 tok/s sirviendo embeddings y reranker a una fracción del coste de dedicar una H100 a esa tarea; el capacity planning cierra mejor con Intel CPU manejando lo barato e NVIDIA H100 el LLM grande. (2) Soberanía y diversificación de cadena de suministro: NVIDIA tiene ~94 % del mercado de AI accelerators (noviembre 2025), single-vendor dependency con todos sus riesgos; Intel fabrica en Europa (Leixlip operativa, Magdeburg planeada) frente a NVIDIA design-only con foundry TSMC, lo que para una organización española/europea con exigencia ENS / NIS2 / EU AI Act es un argumento de hedge real. (3) Edge: un Intel NUC con CPU Lunar Lake (NPU 48 TOPS) o Panther Lake (NPU 50 TOPS + Xe3 120 TOPS = 180 TOPS plataforma) corre modelos 7B INT4 a velocidad usable, lo que abre el patrón “sucursal con inferencia local + DC central para casos complejos”. Hardware Intel relevante en junio 2026: Intel Gaudi 3 (128 GB HBM2e, 1835 TFLOPS BF16/FP8, 3.67 TB/s; competidor directo a H100 — Intel reclama +20 % en Llama 2 70B pero Signal65 publicó H200 9× sobre Gaudi 3 en Llama 3.1 405B, hay que citar ambos; Falcon Shores cancelado enero 2025, Jaguar Shores 2026 como apuesta de reinicio, Gaudi 4 confirmado que no existirá); Intel Xeon 6 con AMX (hasta 288 cores E-core en Sierra Forest o 86 P-core en Granite Rapids, 1024 FLOPS BF16/ciclo/core con AMX, Intel reclama 2.7× tok/s vs EPYC 9965 en vLLM CPU backend); Intel Arc Pro B60 (Battlemage, 24 GB GDDR6, 456 GB/s, 197 TOPS INT8, lanzado septiembre 2025 — variante dual-GPU 48 GB y rack “Battlematrix” con 8× = 192 GB VRAM); Intel NUC con NPU (Lunar Lake 48 TOPS, Arrow Lake similar, Panther Lake 50 TOPS CES 2026; realista para 7-13B INT4, no para los 30-70B que Intel afirma en su marketing). Software: OpenVINO 2025.3 con GenAI API y vLLM-OpenVINO; IPEX-LLM con integraciones a llama.cpp, vLLM, HF, LangChain; vLLM CPU backend con AMX; llama.cpp SYCL (mejor que Vulkan en Arc). Cuatro patrones canónicos: embeddings + reranker en Intel al lado del LLM en NVIDIA; guardrails + PII redact en NUC near edge; speculative drafter en NUC cerca del usuario y target en H100; dev workstations NUC. Observabilidad unificada vía DCGM + habana-metric-exporter + intel-gpu-exporter + Intel PCM federados en Prometheus. Pitfalls: tokenizer mismatch entre engines, latencia round-trip edge↔central, FP8 Hopper ≠ INT8 AMX en calidad, sincronización de versiones. Aplicado a un cluster genérico: DC central 4×H100 SXM + sidecar Xeon 6 AMX + 6-12 NUCs Intel en sucursales. Disclaimer crítico: a junio 2026 no hay casos públicos verificables de despliegue mixto NVIDIA + Intel en banca o gobierno europeo; el patrón es arquitectura emergente y recomendable, no práctica establecida con histórico industrial.

Estás aquí: DEPLOY (con heterogeneidad como decisión)

La analogía: la fábrica con varias máquinas distintas

Una fábrica seria tiene varias máquinas con propósitos distintos, no una sola máquina universal. Una prensa hidráulica de 200 toneladas para troquelado pesado; un torno de banco para piezas de revolución; una impresora 3D para prototipos rápidos; un robot de pick-and-place para SMD. Cada máquina hace lo que hace mejor que las demás en su nicho, y el gerente de planta dimensiona el mix según el portfolio real de productos, no según moda. Comprar tres prensas hidráulicas porque “son las más impresionantes” cuando el 60 % del trabajo son piezas de revolución es derrochar capital — el torno es más barato, más rápido para su nicho y libera la prensa para lo que de verdad la necesita.

Un cluster de inferencia LLM con NVIDIA H100 dedicada a hacer embeddings de un corpus RAG está usando una prensa hidráulica para taladrar pernos. La H100 es magnífica para LLM 70B en BF16 con concurrencia 40+; para embeddings de un documento de 800 tokens en bge-m3, lo que necesitas es un Intel Xeon 6 con AMX a una fracción del coste y consumo eléctrico. Un cluster que quiera servir guardrails ligeros (Llama Guard 4 8B) en cada request, con presupuesto de 50 ms, tampoco necesita ese guardrail en una H100 — un Intel NUC con NPU 48 TOPS cubre el caso con margen.

La fábrica heterogénea no es elegancia teórica: es maximizar utilización útil del capital fijo. El cluster heterogéneo de inferencia LLM tampoco lo es.

Tres razones operativas para la heterogeneidad

Razón 1 — coste

Una H100 SXM 80 GB en operación 24/7 consume ~700 W (medición real al wall ~697 W con vLLM Llama 3.1 405B batch=4) y representa entre 25 000 € y 35 000 € de hardware amortizado. Un Intel Xeon 6 con AMX (Granite Rapids 86 cores o Sierra Forest 288 cores E) consume 350-500 W para el socket y cuesta una fracción. La operativa: la H100 está reservada para el LLM grande (Llama 70B BF16 o FP8, donde su HBM3 y FP8 tensor cores valen su peso); el Xeon AMX absorbe embeddings (bge-m3, e5-large), reranker (bge-reranker-v2-m3), modelos pequeños (Llama 3.2 1B / 3B INT4) y batch processing offline. Es la misma lógica del capacity planning llevada un paso más allá: en vez de presupuestar VRAM de KV cache solo en H100, presupuestar cada workload en el silicio donde su arithmetic intensity case mejor.

Razón 2 — soberanía y diversificación de la cadena de suministro

A noviembre 2025, NVIDIA tiene aproximadamente 94 % del mercado de AI accelerators. Esa concentración es riesgo. Para una organización con exigencia ENS / NIS2 / EU AI Act, depender de un único proveedor con foundry concentrada en Taiwán (TSMC) introduce vulnerabilidades de cadena de suministro que regulaciones recientes (NIS2, supply chain provisions) están empezando a exigir documentar y mitigar. Intel diversifica: tiene fabs propias en Europa (Leixlip operativa en Irlanda; Magdeburg planeada en Alemania, con financiación EU Chips Act), lo que para un cliente público español o europeo es argumento contractual real, no marketing.

Disclaimer obligatorio: el roadmap Intel post-Falcon Shores es inestable. Intel canceló Falcon Shores en enero 2025 y relegó Gaudi 4 a “no existirá”; la apuesta de re-arranque es Jaguar Shores en 2026 como plataforma rack-scale, todavía sin specs públicas confirmadas. La diversificación es estratégicamente correcta, pero asumir continuidad de roadmap Intel al nivel del de NVIDIA en 2026 sería ingenuo. La estrategia operativa: Intel para cargas donde el lock-in es menor (CPU para embeddings, NUC para edge ligero — sustituibles por AMD/Apple/SiFive si Intel pivot otra vez), NVIDIA para el LLM grande donde la madurez del software stack todavía no tiene rival.

Razón 3 — edge

El patrón de “todo viaja al DC central” rompe en tres casos: latencia (sucursal a 100+ ms del DC, inaceptable para chat), soberanía de datos (prompts con datos personales / clasificados que no deben salir del perímetro local), y operación offline (sucursal con conectividad intermitente). El Intel NUC con CPU moderna (Lunar Lake / Arrow Lake / Panther Lake) trae NPU 48-50 TOPS + iGPU Xe2/Xe3 100-180 TOPS en un equipo de 0.5-1.5 L de volumen y 30-65 W de consumo. Modelos 7B INT4 corren a velocidad usable; con quantization más agresiva (Q3_K) cabe Llama 13B. Para sucursales con RAG sobre corpus local + LLM 7B + guardrails, el NUC es perfecto.

Hardware Intel relevante (junio 2026)

Pieza	Memoria	Performance clave	Lanzamiento	Estado
Intel Gaudi 3	128 GB HBM2e, 3.67 TB/s	1835 TFLOPS BF16/FP8; 1200 GB/s networking	abr-2024	Activo; sucesor Jaguar Shores 2026 (no Gaudi 4)
Intel Xeon 6 (Granite Rapids)	DDR5 + MRDIMM	86 P-cores, AMX 1024 FLOPS BF16/ciclo/core	2024-2025	Activo
Intel Xeon 6 (Sierra Forest)	DDR5	288 E-cores	2024	Activo
Intel Arc Pro B60 (Battlemage)	24 GB GDDR6, 456 GB/s	197 TOPS INT8; 12.28 TFLOPS FP32	sep-2025	Activo; variante dual 48 GB, rack 8× = 192 GB
Intel Data Center GPU Max	128 GB HBM	sucesor de Ponte Vecchio	descontinuado	Descontinuado ene-2026
Intel NUC (Lunar Lake)	DDR5x	NPU 48 TOPS + Xe2 67 TOPS = 120 TOPS plataforma	2024	Activo
Intel NUC (Arrow Lake)	DDR5	NPU 13 TOPS + Xe iGPU	2024	Activo (menos NPU que Lunar)
Intel NUC (Panther Lake)	DDR5x	NPU 50 TOPS + Xe3 120 TOPS = 180 TOPS plataforma	CES ene-2026	En despliegue

Intel Gaudi 3 — la nota crítica sobre el marketing

Intel publica que Gaudi 3 entrega +20 % throughput vs H100 en Llama 2 70B inferencia y 2× price/performance. La cifra aparece en whitepaper oficial y en presentaciones de lanzamiento. Sin embargo, Signal65 (firma independiente) publicó en 2025 que H200 supera a Gaudi 3 por factor 9× en Llama 3.1 405B. La discrepancia es relevante: ambos números pueden ser ciertos para sus benchmarks específicos (Llama 2 70B FP16 vs Llama 3.1 405B FP8) pero la conclusión operativa cambia radicalmente según con cuál te quedes.

Recomendación de este post: tratar Gaudi 3 como opción válida para Llama-class 70B en BF16/FP8 donde Intel reclama paridad o ventaja, no para modelos de frontera 200B+ donde NVIDIA mantiene márgen claro. Y considerar el riesgo de roadmap: Gaudi 4 no existirá; el sucesor de la línea es Jaguar Shores 2026 con arquitectura rack-scale completamente nueva — discontinuidad, no evolución.

Intel Xeon 6 con AMX — el caballo de batalla CPU

Las Advanced Matrix Extensions (AMX) son la pieza no obvia. Cada core P-core de Granite Rapids ejecuta hasta 1024 FLOPS BF16 por ciclo vía AMX, lo que convierte un Xeon 6 con 64-86 cores en un acelerador de matriz respetable para modelos pequeños/medianos. Cifras reales reportadas: Llama 3.2 INT4 a ~57 tok/s con AMX vs 28 tok/s sin AMX (factor 2× clean). En servir 7B INT4 con vLLM CPU backend + AMX, Intel reclama 2.7× tok/s vs EPYC 9965, cifra con sesgo de Intel pero corroborada cualitativamente por LMSYS en su despliegue DeepSeek R1 671B sobre Xeon 6 + SGLang.

Caso de uso operativo: embeddings y reranker en un sidecar Xeon 6 al lado del cluster H100. Modelos como bge-m3 (embedding multilingüe) o bge-reranker-v2-m3 corren a throughput aceptable en CPU AMX; no merecen H100 dedicada. Liberar la H100 para el LLM 70B aumenta el RPS efectivo del cluster sin comprar más GPUs.

Intel Arc Pro B60 y Battlematrix

Lanzada en septiembre 2025, la Arc Pro B60 (Battlemage) trae 24 GB GDDR6 con 456 GB/s de bandwidth y 197 TOPS INT8 a 200 W. Variante de Maxsun con dual-GPU 48 GB. La configuración rack “Battlematrix” combina 8 unidades = 192 GB VRAM agregada — el punto interesante: a un coste muy inferior a una H100 SXM 80 GB, lo que la hace candidata para LLM 30-70B INT4-INT8 servidos vía OpenVINO o llama.cpp SYCL.

Phoronix verificó que en SYCL la Arc Pro B70 alcanza paridad con Radeon PRO W7900 (generación anterior AMD) en DeepSeek R1 Llama 8B pp512. Vulkan backend pierde fuerte (~1/4 del rendimiento de SYCL); para Arc Pro siempre SYCL.

Intel NUC con NPU — el edge node

Los Intel NUC con CPU Lunar Lake (Core Ultra Series 2) traen NPU 4 con 48 TOPS y total plataforma 120 TOPS sumando iGPU Xe2 y CPU AVX. Panther Lake (CES enero 2026) sube a NPU 5 = 50 TOPS + Xe3 120 TOPS = 180 TOPS plataforma.

Intel afirma que Panther Lake “ejecuta modelos 30-70B locales”. Comprobación realista: es marketing. El 30-70B INT4 cabe en RAM (DDR5x 32-64 GB) pero la velocidad sostenida con quant Q4_K_M en un NUC ronda 2-8 tok/s; cómodo para uso ocasional, no para servir tráfico. El sweet spot real del NUC es 7B INT4 a 20-40 tok/s sobre iGPU/NPU, perfecto para sucursal de cliente con consultas casuales.

Software Intel — la pila relevante

OpenVINO 2025.3 (junio 2026) es la pieza central. Soporta deploy con un comando vía OVMS CLI con descarga automática desde HF Hub; integra OpenVINO GenAI con API C++/Python para pipelines generativas; expone API compatible con vLLM v1 (vLLM-OpenVINO). Soporte de modelos GGUF: DeepSeek Distill, Qwen 2/2.5, Llama 3. Optimizaciones: Sage Attention (primer token con prompts largos), KV-cache compression por canal.

Intel Extension for PyTorch (IPEX) — versión XPU 2.8.10+xpu — añade backends Intel a PyTorch. IPEX-LLM es el subproyecto que integra con llama.cpp, Ollama, HuggingFace, LangChain, LlamaIndex, vLLM y DeepSpeed. Mayo 2025: corrió DeepSeek V3/R1 671B y Qwen3MoE 235B en 1-2 Arc A770/B580 con FlashMoE.

vLLM CPU backend — el branch CPU de vLLM con optimizaciones AMX. Para 7B INT4 en Xeon 4ª gen con AMX: 12-50 tok/s; con Xeon Gold 6530 + INT4: ~80 tok/s. Cifras académicas (arXiv 2410.04466).

llama.cpp SYCL — el backend recomendado para Arc; Vulkan funciona pero ronda 1/4 del rendimiento SYCL en Arc B580. SYCL alcanza paridad con AMD generación anterior.

Habana SynapseAI — stack de Gaudi 3. PyTorch bridge habana_frameworks.torch registra device hpu; integración con torch.compile. No es port completo a oneAPI sino integración parcial via oneMKL. Implica que el ecosistema Gaudi mantiene cierta separación del oneAPI general de Intel — relevante de cara al hipotético Jaguar Shores y unificación futura.

Los cuatro patrones canónicos

Patrón 1 — embeddings + reranker en Intel

El más maduro y el más fácil de adoptar. En un sistema RAG típico, cada request del usuario invoca:

Embedding del query (50 ms en H100, 80 ms en Xeon AMX, 30 ms en Arc Pro B60).
Búsqueda vectorial (Qdrant / Milvus / Chroma; latencia ~10-30 ms).
Reranker sobre top-k candidatos (60 ms en H100, 100-150 ms en Xeon AMX).
LLM sobre prompt aumentado (200-500 ms TTFT, 30-50 ms/token).

Los pasos 1 y 3 son memory-bound + relativamente pequeños (modelos 100M-1B): Xeon 6 con AMX (Arc Pro B60 más rápida pero ya GPU dedicada) hace el trabajo a un coste de hardware una fracción del de una H100 dedicada. El paso 4 sigue en NVIDIA porque ahí es donde su arquitectura tensor + HBM3 + FP8 vale lo que cuesta.

Implicación operativa: un Xeon 6 sidecar (~40 cores, ~10-15 k€) sirviendo embeddings + reranker libera el equivalente de 1-2 H100 de carga “barata”, recuperando esa capacidad para el LLM grande. ROI en sizing claro.

Patrón 2 — guardrails + PII redact en NUC near edge

Una sucursal bancaria, un consultorio médico o una oficina jurídica genera prompts con datos personales o clasificados. Mandar esos prompts al DC central (aunque sea on-premise corporativo) puede chocar con políticas de retención local o con compliance específico (GDPR, secreto profesional).

Patrón: el NUC en la sucursal ejecuta dos pasos críticos antes del round-trip:

PII redact con Presidio (CPU-only, rápido) o Llama Guard 4 8B en NPU + iGPU del NUC. Reemplaza nombres, NIFs, números de cuenta por placeholders.
Guardrails ligeros (PromptGuard 2 86M, Llama Guard 4 8B) en NPU + iGPU. Filtra prompt injection, jailbreak, contenido prohibido.

Solo después, el prompt redacted viaja al DC central para que el LLM grande responda. La respuesta se devuelve al NUC, que re-hidrata los placeholders con los valores reales antes de mostrarla al usuario. Los datos sensibles nunca abandonan la sucursal.

Costes: NUC Panther Lake ~1500-2500 €/unidad, escalable a docenas de sucursales sin coste de GPU central adicional. Latencia: 50-150 ms del paso edge antes del round-trip de 200-500 ms del DC.

Patrón 3 — speculative decoding drafter en NUC

Speculative decoding usa un drafter pequeño que propone γ tokens y un target grande que los acepta/rechaza en un único forward pass. Si el drafter está geográficamente cerca del usuario (NUC en sucursal) y el target en el DC central, la latencia percibida del cliente cae aún más.

Setup: drafter Llama 3.2 1B INT4 en NUC + target Llama 3.1 70B FP8 en H100 central. El NUC genera γ=4 tokens en ~50 ms locales; el target los verifica en una pasada (40-80 ms incluyendo round-trip); si tasa de aceptación > 60 %, TTFT efectivo cae ~50 % vs Llama 70B sin speculative.

Restricción importante: drafter y target deben compartir tokenizer. Llama 3.2 1B y Llama 3.1 70B tienen tokenizer compatible. Mezclar Llama drafter con Qwen target rompe el patrón.

Patrón 4 — dev workstations NUC

El dev / CI iterando sobre prompts, evals, retrieval logic, no necesita GPU productiva para validar correctness. Un NUC con Llama 3.2 3B INT4 corre los tests funcionales end-to-end (incluyendo embeddings + retrieval + LLM + guardrails) en una décima parte del coste de iterar sobre una H100. Solo el último smoke test pre-prod usa el cluster productivo.

Patrón maduro en organizaciones con muchos desarrolladores y GPU productiva escasa. La iteración 10× más rápida y barata se traduce en velocidad de feature delivery.

Observabilidad unificada en cluster heterogéneo

El post de observabilidad GPU cubría DCGM Exporter para NVIDIA. En cluster mixto hace falta más:

Pieza hardware	Exporter	Métricas clave
NVIDIA H100/A100	`nvidia/dcgm-exporter`	DCGM_FI_DEV_* + DCGM_FI_PROF_*
Intel Gaudi 3	`HabanaAI/habana-metric-exporter`	habana_hpu_utilization, habana_hbm_used
Intel Arc Pro	`intel/intel-gpu-exporter` (no oficial; existen alternativas)	xe_engine_utilization, xe_memory_used
Intel Xeon CPU + AMX	`prometheus/node-exporter` + Intel PCM	cpu_amx_utilization (vía PCM)
Intel NUC (NPU+iGPU)	`intel/intel-gpu-exporter` + custom NPU exporter	npu_utilization, xe_iGPU

Todos federados en un único Prometheus + Grafana. Las dashboards se organizan por familia de hardware (NVIDIA, Intel server, Intel edge) más una vista agregada “cluster heterogéneo” con SLO por tenant que combina los cuatro.

Cardinalidad: ~1.5-2× la del cluster NVIDIA puro. Manejable con Thanos / Mimir para retención larga.

Routing por capability — del router L7 al heterogéneo

El router de inferencia LLM deja de ser un selector de versiones del mismo modelo para convertirse en un dispatcher por capability:

models:
 - name: "llama-70b-chat"
 endpoint: "vllm-llama70b.inference.svc:8000"
 backend: nvidia-h100
 capabilities: [chat, tool_use, json_mode]
 - name: "embedding-multilingual"
 endpoint: "ipex-bge-m3.inference.svc:8080"
 backend: intel-xeon-amx
 capabilities: [embeddings]
 - name: "reranker-multilingual"
 endpoint: "ipex-bge-reranker.inference.svc:8080"
 backend: intel-xeon-amx
 capabilities: [reranking]
 - name: "guardrail-prompt-injection"
 endpoint: "openvino-llama-guard.edge-suc01.local:8080"
 backend: intel-nuc-edge
 capabilities: [guardrails, redact-pii]
 region: sucursal-01
 - name: "llama-3b-draft"
 endpoint: "openvino-llama-3b.edge-suc01.local:8080"
 backend: intel-nuc-edge
 capabilities: [speculative-drafter]
 region: sucursal-01
 target_model: "llama-70b-chat"

El router resuelve model=embedding-multilingual → Intel Xeon; model=llama-70b-chat → H100; model=guardrail-prompt-injection con region=sucursal-01 → NUC local. Si el NUC de la sucursal cae, failover a una réplica equivalente en el DC central, asumiendo el coste de latencia.

LiteLLM Proxy, NVIDIA Dynamo y Envoy AI Gateway soportan este routing por capability. La pieza no obvia: el router debe conocer el tokenizer compatible entre drafter y target para el patrón 3, lo que se modela en metadata adicional del catálogo.

Pitfalls específicos

Tokenizer mismatch entre engines. OpenVINO con un GGUF de Llama 3.2 y vLLM con el mismo Llama 3.2 nominal pueden usar tokenizers ligeramente distintos (chat template, special tokens). Validar identidad de tokens con tokenizer.encode("hola") en ambos lados antes de asumir intercambiabilidad. Para speculative decoding, un solo token diferente rompe el patrón.

Latencia round-trip edge ↔ central. El patrón 2 y 3 asumen que el NUC y el DC están en la misma WAN corporativa con latencia controlada. Si la sucursal está sobre 4G/5G con jitter de 100-200 ms, el speculative drafter no compensa nada — al revés, añade latencia. Medir antes de prometer.

FP8 Hopper ≠ INT8 AMX en calidad de salida. El operador asume que una request que en H100 corre FP8 y en Xeon AMX corre INT8 producirá la misma salida. No es cierto: las dos quantizaciones tienen perfiles de degradación distintos. Si el sistema espera idempotencia (e.g., evals con golden output), validar offline que la versión Intel reproduce el comportamiento esperado dentro de tolerancia.

Sincronización de versiones de modelo entre sitios. El modelo en el DC central se actualiza, pero los NUCs de las sucursales mantienen la versión vieja del drafter o del guardrail durante semanas. Resultado: comportamiento divergente entre sucursales sin diagnóstico fácil. Política: modelo central y modelo edge avanzan juntos o con ventana documentada; el canary se extiende a la flota de NUCs.

Roadmap Intel inestable. Falcon Shores cancelado, Gaudi 4 no existirá, Jaguar Shores 2026 todavía sin specs públicas confirmadas. Comprar Gaudi 3 hoy es razonable si el caso de uso justifica los 18-24 meses de amortización; comprometer arquitectura a 5+ años sobre Intel accelerator es apuesta más arriesgada que la equivalente NVIDIA — al menos hasta que Jaguar Shores se materialice con software stack maduro.

Vacío de despliegues productivos públicos. A junio 2026, los despliegues Gaudi 3 confirmados son IBM Cloud, Dell AI Factory y un puñado de early adopters (Bharti Airtel, Bosch, Naver). No hay caso público verificable de cluster mixto NVIDIA + Intel en banca o gobierno europeo. Este patrón es arquitectura emergente recomendada, no práctica con histórico industrial. El primer adoptante asume coste de validación que un segundo adoptante evita.

Aplicado a un cluster on-premise genérico

Para una organización con un cluster genérico de inferencia LLM heterogéneo:

DC central: 4 nodos × 4×H100 SXM 80 GB con NVLink intra-nodo = 16 H100. Sirve LLM grandes (Llama 70B, Mixtral 8×22B, Qwen 72B) en BF16 o FP8.
Sidecar Xeon 6: 2-4 servidores Xeon 6 (Granite Rapids 64-86 cores) con AMX, 512 GB DDR5, en el mismo rack que el cluster H100. Sirve embeddings (bge-m3), reranker (bge-reranker-v2-m3), modelos pequeños (Llama 3.2 1B/3B) en vLLM CPU backend con AMX.
Sidecar Arc Pro (opcional): 1-2 servidores con 4-8× Arc Pro B60 24 GB cada uno (Battlematrix), para modelos 13-30B INT8 vía OpenVINO. Útil si el coste por LLM mediano debe bajar de la H100.
NUCs edge en sucursales: 1-2 NUCs Panther Lake por sucursal, con NPU 50 TOPS + Xe3 120 TOPS, sirviendo Llama Guard 4 + Presidio + drafter Llama 3.2 1B INT4 vía OpenVINO. Conectividad WAN corporativa con latencia < 80 ms hacia el DC.

Volumen estimado: cluster central ~120 kW de pico GPU + ~10-15 kW de sidecars Intel. Edge: ~50 W por NUC, despreciable comparado con coste de oficinas.

Observabilidad: Prometheus federado en el DC + scrape pull desde los NUCs (vía VPN corporativa). Dashboards “GPU NVIDIA fleet”, “Intel server fleet”, “Intel edge fleet” más una vista “SLO consolidado”.

Router: LiteLLM Proxy o NVIDIA Dynamo en el DC, con catálogo de modelos extendido para incluir backends Intel y regiones (sucursal-01, sucursal-02, …). Failover edge→central documentado.

Lo que no hemos cubierto (próximos posts)

Benchmarks reproducibles de Llama 70B en Gaudi 3 vs H100 SXM en hardware equivalente — el material que falta para tomar decisiones con datos propios, no de Intel ni de Signal65.
AMD ROCm en el mix: cómo entran MI300X / MI355X en este patrón heterogéneo y qué cambia el catálogo del router.
Apple Silicon como edge: M3/M4 Max con Neural Engine ~38 TOPS + GPU 40-core, hardware equivalente al NUC Panther Lake pero con software stack distinto (MLX).
Optimización de coste energético: cómo nvidia-smi -pl 500W + Intel TDP cap en Xeon 6 reduce factura un 25-30 % con 15-20 % de pérdida de throughput.
CI/CD de modelos para flota edge: cómo el rolling update de un Llama Guard llega a 50 NUCs de sucursales sin que ninguna pierda servicio.

Ver también

Capacity planning para inferencia LLM on-premise — el sizing que esta heterogeneidad permite optimizar tarea por tarea, no para todo en H100.
Siete capas del stack de inferencia LLM on-premise — las siete capas aplican igual sobre hardware heterogéneo; los backends son intercambiables si el contrato OpenAI-compatible se respeta.
El router de inferencia LLM — el router por capability es la pieza central del patrón heterogéneo.
Observabilidad GPU para inferencia LLM — extiende a Gaudi, Arc, Xeon AMX y NPU edge.
Quantization para inferencia LLM — FP8 Hopper, INT8 AMX, INT4 GGUF — la base de por qué los hardware mixtos exigen validación cruzada.
Speculative decoding — el patrón 3 del post; cómo el drafter near edge cierra latencia.
Guardrails y safety en LLMs y LLM Guard — los modelos que viven en el NUC del patrón 2.
Catálogo OSS para LLMOps — fichas de OpenVINO, IPEX-LLM, vLLM CPU backend.
OSS vs hyperscalers — el análisis paralelo de lock-in que sostiene el argumento de diversificación.

Referencias

Intel Gaudi 3

Intel — Gaudi 3 AI Accelerator White Paper. https://cdrdv2-public.intel.com/817486/gaudi-3-ai-accelerator-white-paper.pdf
Intel — Hot Chips 2024 Gaudi 3 deep dive. https://hc2024.hotchips.org/assets/program/conference/day1/60_HC2024.Intel.RomanKaplan.Gaudi3-0826.pdf
Signal65 / DataCenterDynamics — NVIDIA H200 outperforms Intel Gaudi 3 by factor of 9× across first Llama 3.1 405B benchmark test. https://www.datacenterdynamics.com/en/news/nvidia-h200-outperforms-intel-gaudi-3-by-factor-of-nine-across-first-llama-31-405b-benchmark-test-exclusive/
IEEE Spectrum — Intel Gaudi 3 review. https://spectrum.ieee.org/intel-gaudi-3
Tom’s Hardware — Intel cancels Falcon Shores GPU; Jaguar Shores to be successor. https://www.tomshardware.com/tech-industry/artificial-intelligence/intel-cancels-falcon-shores-gpu-for-ai-workloads-jaguar-shores-to-be-successor

Intel Xeon 6 + AMX

Intel — Xeon 6 (Granite Rapids) Product Brief. https://www.intel.com/content/dam/www/central-libraries/us/en/documents/2025-02/xeon-6-granite-rapids-product-brief.pdf
OpenMetal — Intel AMX AI Inference Performance. https://openmetal.io/resources/blog/intel-amx-ai-inference-performance/
LMSYS — Intel Xeon 6 + SGLang for DeepSeek R1 671B. https://www.lmsys.org/blog/2025-07-14-intel-xeon-optimization/
arXiv 2410.04466 — CPU-LLM benchmarks with AMX.
Intel community blog — Accelerating vLLM Inference on Intel Xeon 6 Processor.

Intel Arc Pro Battlemage

Intel — Arc Pro B60 Graphics Specifications. https://www.intel.com/content/www/us/en/products/sku/243916/intel-arc-pro-b60-graphics/specifications.html
StorageReview — Intel Arc Pro B60 Battlematrix Preview: 192GB VRAM for On-Premise AI. https://www.storagereview.com/review/intel-arc-pro-b60-battlematrix-preview-192gb-of-vram-for-on-premise-ai
Phoronix — Intel Arc Pro B-series review. https://www.phoronix.com/review/intel-arc-pro-b-series

Intel NUC / NPU

HotHardware — Intel CES 2026 Panther Lake is a Go. https://hothardware.com/news/intel-ces-2026-panther-lake-is-a-go
TechPowerUp — Intel Panther Lake Technical Deep Dive.
arXiv 2412.11053 — NITRO: LLM inference on laptop NPU.
Intel — AI PC brings larger LLM development to your desk.

Software

OpenVINO — Release Notes 2025.3. https://www.intel.com/content/www/us/en/developer/articles/release-notes/openvino/2025-3.html
HuggingFace — Deploy with OpenVINO. https://huggingface.co/blog/deploy-with-openvino
Intel — Intel Extension for PyTorch XPU 2.8.10. https://intel.github.io/intel-extension-for-pytorch/xpu/latest/tutorials/releases.html
IPEX-LLM — github.com/intel/ipex-llm.
Habana — SynapseAI PyTorch Theory of Operations. https://docs.habana.ai/en/latest/PyTorch/PyTorch_Gaudi_Theory_of_Operations.html

Market context

MLCommons — MLPerf Inference v6.0 benchmark results. https://www.spheron.network/blog/mlperf-inference-v6-benchmark-results-2026/
Intel newsroom — Gaudi 3 Expanded Availability. https://newsroom.intel.com/artificial-intelligence/intel-gaudi-3-expands-availability-drive-ai-innovation-scale

Sources: las URLs completas están enlazadas en línea sobre cada referencia.

Runbooks de incident response para inferencia LLM: cada alerta a una acción concreta con Kafka y Keep

Tue, 02 Jun 2026 04:30:00 +0200

Este post cierra la trilogía de observabilidad que abrieron Observabilidad GPU para inferencia LLM (qué métricas) y Anatomía de las doce métricas DCGM y cinco vLLM (qué anomalía documentada por métrica). Aquí cada anomalía recibe su acción concreta y se encaja en la maquinaria de gestión de incidentes que compliance exige.

TL;DR

Las alertas de observabilidad GPU son inútiles sin un procedimiento codificado por cada una; el operador que las interpreta a mano cada vez opera por intuición. La combinación correcta tiene tres piezas indispensables. (1) Catálogo de runbooks: para cada una de las seis alertas críticas (GpuHbmNearOom, GpuThermalOrPowerThrottle, GpuXidErrorDetected, GpuEccDoubleBit, VllmKvCachePoolNearFull, VllmTtftP95OutOfSlo), severity, mitigación inmediata, evidencia que capturar antes de remediar, acción de resolución, criterio de cierre y trigger de postmortem. (2) Pipeline reproducible: Prometheus + DCGM → Alertmanager → Kafka como event bus (topics gpu.alerts.enriched, incidents.lifecycle, audit.actions con retención WORM) → Keep como workflow engine (workflows declarativos YAML versionados en git) → ejecutores Kubernetes jobs / scripts / ChatOps. (3) Encaje formal en gestión de incidentes según el corpus normativo: ISO/IEC 27035 fases identify → report → assess → respond → learn; ENS controles op.exp.7 (gestión de incidentes), op.exp.8 (registro de actividad), op.exp.10 (notificación a usuarios); NIS2 art. 23 con notificación temprana 24 h, notificación formal 72 h e informe final 1 mes; EU AI Act art. 73 para incidente grave de un sistema de alto riesgo, plazos 2 a 15 días según severity; ISO/IEC 42001 cláusula 10 (mejora continua del AIMS). La taxonomía de acción es mitigación inmediata (drain, throttle, scale-down: contiene el daño en segundos) → diagnóstico (captura de evidencia con nvidia-smi -q, dmesg, vLLM /metrics snapshot, traza OTel relacionada; sin esto el postmortem no es defensible) → resolución (restart, reset, RMA, rollback) → postmortem (RCA por 5-whys, plan de prevención, actualización del runbook). Kafka aporta el audit trail inmutable que ENS y EU AI Act exigen — cada acción ejecutada por Keep o por humano se publica como evento en audit.actions con timestamp, actor, decisión y evidencia, retenido WORM mínimo 6 meses. Keep aporta los workflows como código: este post incluye tres workflows completos (XID con drain + ticket Jira, ECC DBE con paginación inmediata y bloqueo del nodo en scheduler, canary rollback automático por TTFT P95 fuera de SLO). Cuatro anti-patrones cierran el material: alertas sin runbook (la mayoría), runbook sin captura de evidencia previa (perpetúa el incidente porque la causa raíz se pierde), escalada por antigüedad en vez de severity (operador junior gestiona ECC DBE), ausencia de gate humano para acciones destructivas (Keep ejecutando nvidia-smi --gpu-reset sin confirmación). Aplicable a un cluster genérico de 4×H100 SXM con Kafka y Keep ya desplegados.

Estás aquí: OBSERVE → DEPLOY (incident response cierra el bucle)

La analogía: la sala de control de un reactor nuclear

En una sala de control de central nuclear, el operador de turno nunca decide qué hacer al ver una alarma. La decisión está pre-tomada y codificada en un procedimiento escrito (SOP) que cubre cada alarma del panel: si suena la X, abrir libro X, leer los pasos 1-N, ejecutar exactamente, llamar al supervisor en el paso M, escalar al director de planta en el paso N+3. La razón es estricta: las alarmas críticas son raras pero catastróficas si se gestionan mal; un operador improvisando en una emergencia toma decisiones peores que uno aplicando un procedimiento revisado por expertos y validado por simulación.

El reactor no espera que el operador sea genio. Espera que conozca los procedimientos al pie de la letra y que el sistema de gestión de operaciones le entregue el procedimiento correcto al momento. Si los procedimientos no están escritos, no están versionados, o no están integrados con las alarmas que disparan, la sala de control opera por intuición. La diferencia entre ambas operaciones —procedimentada vs intuitiva— es la diferencia entre una central que opera 30 años sin incidentes y otra que entra en lista negra.

El incident response de un cluster de inferencia LLM funciona idéntico. Las alertas DCGM y vLLM que los posts anteriores listaron son las alarmas del panel. Cada una necesita su SOP escrito, versionado, integrado con la alerta que la dispara y revisado tras cada incidente. Sin esa codificación, el operador de turno improvisa en mitad de un fallo de ECC DBE a las 4 de la mañana; con ella, ejecuta los nueve pasos del runbook 12 y el incidente se cierra en 20 minutos.

La arquitectura del incident pipeline

Prometheus + DCGM. Recolecta las métricas descritas en los dos posts anteriores. PrometheusRules definen las seis alertas críticas con for: <duración> para evitar ruido.

Alertmanager. Recibe alertas crudas; deduplica, agrupa por labels ({cluster, node, gpu, model}), enruta. En vez de enviar directamente a PagerDuty o Slack, envía a Kafka vía webhook receiver — esto convierte la alerta en un evento del bus que múltiples consumidores procesan (Keep para acción, audit topic para compliance, dashboards para visualización).

Kafka como event bus. Tres topics canónicos:

gpu.alerts.enriched — alertas con contexto añadido (tenant, modelo, versión, owner del namespace, severity efectiva). Retención: 7 días, replication factor 3.
incidents.lifecycle — eventos del ciclo del incidente: incident.opened, incident.acknowledged, action.proposed, action.executed, incident.escalated, incident.resolved, postmortem.attached. Retención: 90 días.
audit.actions — registro inmutable de cada acción ejecutada (por Keep automáticamente o por humano confirmando). Retención: 6 meses mínimo con compaction off + tiered storage, almacenamiento WORM. Es el topic que ENS op.exp.8, EU AI Act art. 12 y NIS2 obligan a conservar.

Keep como workflow engine. Consume de gpu.alerts.enriched, dispara workflows YAML versionados en git, ejecuta acciones (llamadas HTTP, kubectl jobs, mensajes Slack, tickets Jira) y publica el resultado en incidents.lifecycle + audit.actions. La elección de Keep sobre Alertmanager solo (o sobre PagerDuty solo) es deliberada: Keep separa declaración del runbook (YAML legible y revisable) de distribución de notificación (PagerDuty). El runbook es código versionado; las notificaciones son detalles operativos.

Ejecutores. Lo que de verdad mueve el cluster:

Kubernetes jobs: kubectl drain, kubectl cordon, kubectl rollout undo.
NVIDIA API: nvidia-smi --gpu-reset, dcgmi diag -r <level>.
ChatOps: confirmaciones humanas a través de Slack interactive messages antes de ejecutar acción destructiva.
Tooling externo: ticket Jira, notificación PagerDuty, llamada a CMDB.

Las seis alertas críticas y sus runbooks

Para cada alerta: severity, mitigación inmediata (segundos), evidencia que capturar antes de remediar, acción de resolución, criterios de cierre, trigger de postmortem.

RB-01 · `GpuHbmNearOom` — HBM > 92 % sostenido

Severity: WARNING. Riesgo OOM en la siguiente asignación de PagedAttention.

Mitigación inmediata. Reducir admission temporalmente bajando max_num_seqs del motor afectado vía hot reload (si el motor lo soporta) o restart escalonado de réplicas. Disparar scale-out adicional vía KEDA si hay nodos GPU libres. No es necesario drenar el nodo.

Evidencia a capturar.

nvidia-smi --query-gpu=index,memory.used,memory.free,memory.total --format=csv
nvidia-smi -q -d ROW_REMAPPER | grep -i pending
curl http://vllm-pod:8000/metrics | grep -E "gpu_cache_usage|num_requests"
kubectl logs <pod> --tail=200 | grep -i "preempt\|swap"

Guardar snapshot en audit.actions con timestamp y incident_id.

Resolución. Si la causa es pico de tráfico: dejar al autoscaler escalar a régimen estable, monitorizar 30 min. Si la causa es regresión de modelo (canary v2 consume más KV cache que v1): rollback del canary (ver RB-06). Si es leak (la métrica crece sin que el tráfico crezca): restart del pod con captura de heap dump.

Cierre. gpu_cache_usage_perc < 80 % sostenido durante 15 min Y num_requests_waiting == 0.

Postmortem. No obligatorio salvo si el incidente duró > 30 min o tuvo impacto en SLO.

RB-02 · `GpuThermalOrPowerThrottle` — bit ≠ 0 ni Idle en CLOCK_THROTTLE_REASONS

Severity: WARNING (térmico) o CRITICAL (HW Power Brake sostenido, riesgo PDU).

Mitigación inmediata. Identificar el bit (decodificar bitmap). Si es 0x40 HW_THERMAL o 0x20 SW_THERMAL: drenar workload del nodo a otras réplicas si la temperatura no baja en 2 min, evitar nuevos pods en ese nodo (kubectl cordon). Si es 0x80 HW_POWER_BRAKE: alerta a infraestructura de DC inmediatamente (probable PDU sobrecomprometida — caso Dell KB 000220508 / Lenovo HT514380), reducir TDP de las GPUs del rack vía nvidia-smi -pl a un valor menor para liberar carga sobre el breaker.

Evidencia.

nvidia-smi --query-gpu=index,temperature.gpu,temperature.memory,power.draw,clocks_throttle_reasons.active --format=csv
ipmitool sdr | grep -i "fan\|temp\|inlet"
# Datos de PDU si están instrumentadas (modbus / SNMP)

Resolución.

Térmico: revisar flujo de aire del rack, verificar rear-door HX, T_inlet, ventiladores DGX. Issue de infra, no de motor.
Power Brake: revisar dimensionado de PDU rama, breaker, distribución 415 VAC. Probable redistribución de carga a otra rama o limitación temporal de TDP.

Cierre. CLOCK_THROTTLE_REASONS == 0x1 (solo Idle) o 0x0 durante 30 min con carga normal.

Postmortem. Obligatorio si fue HW Power Brake — implica infraestructura eléctrica del DC.

RB-03 · `GpuXidErrorDetected` — `increase(DCGM_FI_DEV_XID_ERRORS[5m]) > 0`

Severity: CRITICAL.

Mitigación inmediata. kubectl cordon del nodo (sin más nuevos pods). Si el XID es 31/48/79/94/95 (hardware o cascada): drenar los pods existentes del nodo. Si el XID es 13/43 (posible software): mantener pods pero bloquear nuevos, capturar trace y workload activo.

Evidencia.

# El XID concreto del dmesg
dmesg | grep -i xid | tail -30
nvidia-smi -q -d ERROR
nvidia-smi -q -d PCIE
# Estado de las páginas retiradas
nvidia-smi -q -d ROW_REMAPPER
# Workload que estaba ejecutándose
kubectl get pods -o wide | grep <node>
kubectl logs <pod> --previous --tail=500

Resolución.

XID 13/43 (software exception / channel verif): si recurre solo con un modelo concreto, es bug del workload — issue al equipo de modelos. Si es transitorio, reiniciar el pod basta.
XID 31 (MMU fault): suele ser cascada de un XID 48 previo. Reset de la GPU (nvidia-smi --gpu-reset -i <index>) o reboot del nodo si reset no resuelve.
XID 48 / 95 (DBE / uncontained ECC): ver RB-04. El nodo entra en cuarentena.
XID 79 (fallen off the bus): reboot del nodo. Si recurre tras reboot, abrir RMA de la GPU. ByteDance reporta 43 % de coocurrencia con errores PCIe — verificar también el slot y el cable.
XID 94 / 145 / 149: catalogados en el Xid Catalog de NVIDIA con procedimiento específico.

Cierre. Smoke test del nodo pasado (dcgmi diag -r 3), 24 h sin nuevos XIDs, vuelta al pool.

Postmortem. Obligatorio. Incluir XID concreto, distribución de XIDs en el cluster, MTBE actualizado.

RB-04 · `GpuEccDoubleBit` — `DCGM_FI_DEV_ECC_DBE_VOL_TOTAL > 0`

Severity: CRITICAL — corrupción de datos en curso.

Mitigación inmediata. Drenar el nodo inmediatamente sin esperar evidencia adicional. Páginas guardia (PagerDuty / OpsGenie) ON-CALL primario. Marcar el nodo unschedulable y failed. El XID 48 tiene 100 % probabilidad de matar el job en curso según el dataset de Story of Two GPUs; cualquier inferencia ya está comprometida.

Evidencia (en paralelo a la mitigación).

nvidia-smi -q -d ECC
nvidia-smi -q -d ROW_REMAPPER # Pending: Yes esperado
dmesg | grep -E "Xid.*48|DBE|double-bit" | tail -50
# Captura completa del estado de la GPU
dcgmi diag -r 4 -i <gpu_index>

Resolución. Reset completo de la GPU (nvidia-smi --gpu-reset) o reboot del nodo si reset no completa. El reset activa el row remap. Tras el reboot:

nvidia-smi -q -d ROW_REMAPPER # Pending: No esperado
nvidia-smi -q -d ECC # contadores volátiles a 0

Si RETIRED_DBE > 8 páginas tras el remap: planificar reemplazo de GPU en próxima ventana — la degradación del silicio es progresiva. Documentado ~19 horas de downtime típico en el caso real publicado.

Cierre. Nodo en pool tras 48 h sin nuevos DBE.

Postmortem. Obligatorio. Si el incidente afectó a una request con datos personales / clasificados, evaluar notificación a DPO bajo GDPR art. 33 (no es necesariamente brecha, pero hay que evaluarlo).

RB-05 · `VllmKvCachePoolNearFull` — `gpu_cache_usage_perc > 95 %` sostenido 3 min

Severity: WARNING (riesgo de preempt-on-OOM, no de OOM real).

Mitigación inmediata. Activar scale-out del autoscaler bajando el umbral de KEDA temporalmente (de 0.85 a 0.75) durante 30 min. Si está en modo recompute, los preempts elevan TTFT pero no rompen requests; aceptable a corto plazo. Si está en modo swap, latencia se va al techo — preferible cortar tráfico nuevo (devolver 503 desde el router) durante 5 min.

Evidencia.

curl http://vllm-pod:8000/metrics | grep -E "gpu_cache|num_requests|num_preemptions"
kubectl get hpa vllm-llama70b
kubectl logs <pod> --tail=200 | grep -i preempt

Resolución. Si recurre regularmente: capacity planning revisado, posiblemente reducir max_num_seqs o subir réplicas estables. Ver Capacity planning.

Cierre. Pool < 85 % sostenido 30 min, sin preempts en último 15 min.

Postmortem. No obligatorio salvo recurrencia > 3 veces / semana.

RB-06 · `VllmTtftP95OutOfSlo` — TTFT P95 > 1.5 s durante 5 min

Severity: CRITICAL (violación de SLO contractual).

Mitigación inmediata. Diagnóstico rápido del régimen (en orden de probabilidad):

Si hay canary v2 activo y el ratio ttft_p95(v2)/ttft_p95(v1) > 1.30: rollback automático del canary vía Argo Rollouts (argo rollouts abort vllm-llama70b).
Si num_requests_waiting > 5: scale-out vía KEDA.
Si DRAM_ACTIVE > 90 % + gpu_cache_usage_perc > 90 %: cuello en HBM, palanca de quantization o reducción de contexto.
Si CLOCK_THROTTLE_REASONS != 0: ver RB-02.

Evidencia.

# Snapshot del histograma
curl http://vllm-pod:8000/metrics | grep time_to_first_token
# Distribución por versión si hay canary
# Estado DCGM del momento
curl http://dcgm-exporter:9400/metrics | grep -E "PIPE_TENSOR|DRAM_ACTIVE|THROTTLE"
# Tráfico activo
kubectl top pods -n inference

Resolución. Depende del diagnóstico. Casos típicos:

Canary regresión → rollback completo (ver Canary).
Saturación de capacidad → escalar réplicas o aceptar 503 temporal con Retry-After.
Prefill bound → activar/calibrar chunked prefill o disaggregated serving (ver Disaggregated serving).

Cierre. TTFT P95 dentro de SLO sostenido 30 min.

Postmortem. Obligatorio. Documentar causa raíz y palanca aplicada; actualizar runbook.

Workflows Keep YAML — tres ejemplos completos

Los runbooks son útiles solo si están codificados en el workflow engine. Keep permite declararlos en YAML versionados en git.

Workflow 1 — `xid-detected.yaml`

workflow:
 id: xid-detected-drain
 name: "XID error detected — cordon node and capture evidence"
 description: "RB-03 implementation"
 triggers:
 - type: alert
 filters:
 - key: alertname
 value: GpuXidErrorDetected
 steps:
 - name: capture-evidence
 provider:
 type: bash
 with:
 command: |
 set -e
 NODE="{{ alert.labels.node }}"
 GPU="{{ alert.labels.gpu }}"
 INC_ID="{{ alert.fingerprint }}"
 mkdir -p /var/evidence/$INC_ID
 kubectl debug node/$NODE -it --image=nvcr.io/nvidia/cuda:12.4.0-base-ubuntu22.04 -- \
 bash -c "nvidia-smi -q -d ERROR,PCIE,ROW_REMAPPER > /host/var/evidence/$INC_ID/smi.txt"
 kubectl describe node $NODE > /var/evidence/$INC_ID/node.txt
 - name: cordon-node
 provider:
 type: kubernetes
 with:
 action: cordon
 name: "{{ alert.labels.node }}"
 if: "{{ alert.labels.severity == 'critical' }}"
 actions:
 - name: open-jira-ticket
 provider:
 type: jira
 config: "{{ providers.jira-prod }}"
 with:
 project: GPUOPS
 issuetype: Incident
 summary: "RB-03: XID {{ alert.annotations.xid_code }} on {{ alert.labels.node }}/{{ alert.labels.gpu }}"
 description: |
 Severity: {{ alert.labels.severity }}
 XID: {{ alert.annotations.xid_code }}
 Evidence: /var/evidence/{{ alert.fingerprint }}
 Runbook: https://runbooks.example.local/RB-03
 - name: notify-slack
 provider:
 type: slack
 config: "{{ providers.slack-gpu-incidents }}"
 with:
 message: |
 :warning: *RB-03 triggered*
 Node: `{{ alert.labels.node }}` GPU: `{{ alert.labels.gpu }}`
 XID: `{{ alert.annotations.xid_code }}`
 <{{ jira.url }}|Jira ticket>
 - name: emit-audit
 provider:
 type: kafka
 config: "{{ providers.kafka-audit }}"
 with:
 topic: audit.actions
 message:
 incident_id: "{{ alert.fingerprint }}"
 action: "cordon_node"
 actor: "keep-workflow"
 workflow_id: "xid-detected-drain"
 target: "{{ alert.labels.node }}"
 timestamp: "{{ now }}"

Workflow 2 — `ecc-dbe.yaml` — paginación inmediata

workflow:
 id: ecc-dbe-critical
 name: "ECC double-bit — page on-call and quarantine node"
 triggers:
 - type: alert
 filters:
 - key: alertname
 value: GpuEccDoubleBit
 steps:
 - name: cordon-immediately
 provider:
 type: kubernetes
 with:
 action: cordon
 name: "{{ alert.labels.node }}"
 - name: drain-workload
 provider:
 type: kubernetes
 with:
 action: drain
 name: "{{ alert.labels.node }}"
 options:
 ignore-daemonsets: true
 delete-emptydir-data: true
 grace-period: 120
 - name: page-oncall
 provider:
 type: pagerduty
 config: "{{ providers.pagerduty-critical }}"
 with:
 service_key: "{{ env.PD_SERVICE_KEY }}"
 severity: critical
 summary: "RB-04 ECC DBE on {{ alert.labels.node }}/{{ alert.labels.gpu }} — node drained"
 - name: emit-lifecycle
 provider:
 type: kafka
 config: "{{ providers.kafka-incidents }}"
 with:
 topic: incidents.lifecycle
 message:
 incident_id: "{{ alert.fingerprint }}"
 event: incident.opened
 severity: critical
 runbook: RB-04
 requires_postmortem: true
 - name: notify-dpo
 provider:
 type: email
 with:
 to: dpo@example.local
 subject: "ECC DBE en GPU productiva — evaluación necesaria"
 body: |
 Incidente RB-04 ECC DBE detectado en {{ alert.labels.node }}.
 Modelo afectado: {{ alert.labels.model }}.
 Por favor evaluar si hubo procesamiento de datos personales/clasificados
 durante la ventana de error y necesidad de notificación GDPR art. 33.

Workflow 3 — `canary-rollback.yaml` — TTFT P95 fuera de SLO

workflow:
 id: canary-rollback-ttft
 name: "Rollback canary when TTFT P95 ratio v2/v1 > 1.30"
 triggers:
 - type: alert
 filters:
 - key: alertname
 value: VllmTtftP95OutOfSlo
 - key: canary_active
 value: "true"
 steps:
 - name: check-ratio
 provider:
 type: prometheus
 config: "{{ providers.prom-prod }}"
 with:
 query: |
 histogram_quantile(0.95, sum by(le)(rate(vllm:time_to_first_token_seconds_bucket{version="v2"}[5m])))
 /
 histogram_quantile(0.95, sum by(le)(rate(vllm:time_to_first_token_seconds_bucket{version="v1"}[5m])))
 condition: result > 1.30
 actions:
 - name: argo-rollback
 provider:
 type: kubernetes
 with:
 action: exec
 command:
 - kubectl
 - argo
 - rollouts
 - abort
 - "{{ alert.labels.rollout }}"
 - -n
 - "{{ alert.labels.namespace }}"
 - name: notify-and-audit
 provider:
 type: kafka
 config: "{{ providers.kafka-audit }}"
 with:
 topic: audit.actions
 message:
 incident_id: "{{ alert.fingerprint }}"
 action: canary_rollback
 ratio: "{{ steps.check-ratio.result }}"
 actor: keep-workflow
 timestamp: "{{ now }}"

Cada workflow se guarda en repos/keep-workflows/ versionado en git, revisado por pull request, validado por CI (keep workflow validate). El runbook escrito vive como docs/runbooks/RB-XX.md enlazado desde el workflow YAML — los dos siempre evolucionan juntos.

El schema canónico de eventos Kafka

Para que los topics sean consumibles por compliance, postmortem tooling y dashboards sin que cada consumer tenga que adivinar el shape, se fija schema con Avro / Protobuf.

{
 "name": "IncidentLifecycleEvent",
 "type": "record",
 "fields": [
 { "name": "incident_id", "type": "string" },
 { "name": "event", "type": { "type": "enum", "symbols": [
 "incident.opened", "incident.acknowledged", "action.proposed",
 "action.executed", "action.failed", "incident.escalated",
 "incident.resolved", "postmortem.attached"
 ]}},
 { "name": "timestamp", "type": "string", "logicalType": "timestamp-millis" },
 { "name": "actor", "type": "string" },
 { "name": "severity", "type": { "type": "enum", "symbols": ["low","warning","critical"] } },
 { "name": "runbook", "type": ["null","string"], "default": null },
 { "name": "alert_name", "type": "string" },
 { "name": "labels", "type": { "type": "map", "values": "string" } },
 { "name": "annotations", "type": { "type": "map", "values": "string" } },
 { "name": "evidence_uri", "type": ["null","string"], "default": null },
 { "name": "requires_postmortem", "type": "boolean", "default": false }
 ]
}

Para audit.actions (WORM), un schema separado más exigente con campos no-modificables:

{
 "name": "AuditAction",
 "type": "record",
 "fields": [
 { "name": "incident_id", "type": "string" },
 { "name": "action", "type": "string" },
 { "name": "actor", "type": "string" },
 { "name": "actor_type", "type": { "type": "enum", "symbols": ["human","workflow","scheduler"] } },
 { "name": "workflow_id", "type": ["null","string"], "default": null },
 { "name": "target", "type": "string" },
 { "name": "command", "type": ["null","string"], "default": null },
 { "name": "result", "type": { "type": "enum", "symbols": ["success","failure","partial"] } },
 { "name": "timestamp", "type": "string", "logicalType": "timestamp-millis" },
 { "name": "evidence_uri", "type": ["null","string"], "default": null },
 { "name": "approver", "type": ["null","string"], "default": null }
 ]
}

El topic se configura con cleanup.policy=delete, retention.ms=15552000000 (6 meses) y min.insync.replicas=2 con acks=all para garantizar durabilidad. Para retención más larga sin coste de Kafka, tiered storage a Ceph RGW o S3-compatible — el log nuevo en hot tier, el viejo en cold tier transparente al consumer.

Encaje formal en gestión de incidentes

Los runbooks no son una práctica de SRE aislada — encajan en cuatro marcos normativos que las plataformas LLM productivas tocan a diario.

ISO/IEC 27035 — gestión de incidentes de seguridad de la información

Define el ciclo formal en cinco fases: plan & prepare → detect & report → assess & decide → respond → lessons learned. Cada fase tiene salidas exigibles documentalmente. La traducción al stack:

Plan & prepare: los runbooks RB-01 a RB-06 + los workflows Keep son parte del Information Security Incident Management Plan. Versionados en git, revisados anualmente.
Detect & report: las alertas Prometheus que entran a Kafka son la materialización.
Assess & decide: la severity en gpu.alerts.enriched + la lógica del workflow Keep.
Respond: ejecución de los steps + actions del workflow.
Lessons learned: postmortem obligatorio para los runbooks que lo marcan; salida documentada en el repo de postmortems + actualización del runbook.

ENS (Esquema Nacional de Seguridad) — controles op.exp

op.exp.7 Gestión de incidentes: el catálogo de runbooks + el pipeline Keep / Kafka materializan la “respuesta organizada y procedimentada”.
op.exp.8 Registro de actividad: el topic audit.actions con retención WORM 6 meses (mínimo nivel ALTO).
op.exp.9 Registro de la gestión de incidentes: el topic incidents.lifecycle con el ciclo completo de cada incidente.
op.exp.10 Protección de los registros de actividad: WORM + cifrado en reposo + control de acceso (consumers compliance solo-lectura).

NIS2 — notificación a autoridad competente

Para entidades esenciales / importantes, el art. 23 fija tres plazos a partir del significant impact detectado:

24 horas: notificación temprana (“early warning”) al CSIRT nacional (INCIBE-CERT en España).
72 horas: notificación formal con assessment inicial.
1 mes: informe final con causa raíz, impacto, medidas correctivas.

Los datos para esos informes salen directamente de incidents.lifecycle + audit.actions con un consumer que genera el dossier en el formato requerido. Sin el pipeline auditable, los plazos NIS2 son inalcanzables.

EU AI Act — art. 73 (serious incident reporting)

Aplicable a sistemas de alto riesgo. Plazos:

2 días: para incidentes que provoquen fallecimiento o daño irreversible a personas o infraestructuras críticas.
10 días: para incidentes que produzcan disrupción seria de infraestructura crítica.
15 días: para el resto de “serious incidents”.

La definición de “serious incident” incluye fallos sistemáticos del modelo, brecha de fundamental rights, daño material o medioambiental. Los runbooks deben marcar qué alertas pueden derivar en serious incident (típicamente cualquier cosa que afecte la salida del modelo en un contexto de alto riesgo) y disparar un sub-workflow específico de evaluación legal.

ISO/IEC 42001 — AIMS cláusula 10 mejora continua

El postmortem obligatorio post-incidente alimenta la cláusula 10. La actualización del runbook tras cada incidente que descubre un patrón nuevo es la “acción correctiva con verificación de eficacia” que la norma exige. Ver ISO 42001 AIMS.

Cuatro anti-patrones

Anti-patrón 1 — alertas sin runbook. La alerta dispara, el operador junior de guardia mira el dashboard, busca en Confluence, no encuentra nada actualizado, llama al senior por Slack, espera 20 minutos. En ese tiempo el incidente ha crecido. Regla: ninguna alerta entra a producción sin runbook publicado y workflow Keep aprobado. CI valida que cada PrometheusRule con severity ≥ warning tiene su keep workflow correspondiente.

Anti-patrón 2 — runbook sin captura de evidencia previa. El workflow ejecuta nvidia-smi --gpu-reset en cuanto llega el XID, perdiendo el estado que habría diagnosticado la causa raíz. El siguiente XID idéntico exige rehacer el diagnóstico desde cero. Regla: steps antes de actions; toda evidencia se captura primero, las acciones destructivas después.

Anti-patrón 3 — escalada por antigüedad en vez de severity. El operador junior de guardia gestiona un ECC DBE porque “le toca”. Le falta contexto para entender row remap, retired pages o el riesgo de corrupción de datos. Regla: paginación por severity, no por rotación: RB-04 y RB-03 dispararon ON-CALL primario senior con escalada automática a infra/hardware si no acuse en 10 min.

Anti-patrón 4 — ausencia de gate humano para acciones destructivas. El workflow ejecuta kubectl drain automáticamente sobre cualquier alerta marcada como CRITICAL. En la primera falsa alarma (un transitorio que se autoresolvió en 30 s), Keep drenó un nodo productivo durante hora pico. Regla: acciones destructivas (drain, reset, RMA, rollback completo) exigen confirmación humana vía Slack interactive message, con timeout configurable. Excepción justificada: ECC DBE confirmado por > 1 medición — el riesgo de corrupción supera el de falsa alarma.

Aplicado a hardware on-premise típico

Para un cluster genérico de 4 nodos × 4×H100 SXM 80 GB con Kafka y Keep ya desplegados:

Kafka: cluster de 3 brokers en nodos no-GPU del cluster K8s; topics gpu.alerts.enriched, incidents.lifecycle, audit.actions configurados con replication factor 3, min.insync.replicas 2. Audit con tiered storage a Ceph RGW para retención > 6 meses sin coste brutal.
Keep: 2 réplicas del operator + 1 réplica del worker en un namespace keep; conectado a Prometheus (provider read), Kafka (provider read + write), Slack, PagerDuty, Jira, Kubernetes (provider con SA específico con permisos get/list/patch nodes, create jobs).
Workflows: ~25-40 YAML en el repo infra/keep-workflows/, sincronizado con el cluster vía Flux o Argo CD. Validados por CI (keep workflow validate) en cada PR.
Volumen de eventos: para 16 GPUs en operación normal con alertas debounced, ~50-200 eventos/día en gpu.alerts.enriched. En incidente típico, picos de 500-2000 eventos/día.
Compliance consumers: un consumer python en namespace compliance que genera reportes NIS2 / ENS / EU AI Act semanalmente, leyendo audit.actions y incidents.lifecycle.

Lo que no hemos cubierto (próximos posts)

Playbooks de postmortem — la mecánica de RCA con 5-whys, Ishikawa adaptado a LLM, integración con MLflow tracking de re-training si el postmortem produce dataset enriquecido.
Chaos engineering para LLM — inyección controlada de XID errors, ECC simulados, latencia HBM artificial para validar runbooks antes del incidente real.
Multi-cluster incident coordination — cómo coordinar Keep entre clusters geográficos cuando un incidente afecta a múltiples regiones.
Integración con CMDB y procurement — el ciclo RMA → ticket → ServiceNow → reposición de hardware automatizado vía workflow.
Forense LLM — extracción de la traza OTel completa de una request afectada por un incidente, redacted PII, conservación en evidence vault.

Ver también

Anatomía de las doce métricas DCGM y cinco vLLM — la anomalía documentada por métrica que estos runbooks resuelven.
Observabilidad GPU para inferencia LLM — la lista compacta y las seis alertas críticas.
Tracing LLM con OpenTelemetry GenAI — la traza OTel que se captura como evidencia.
Canary, blue-green y shadow — el mecanismo de rollback que RB-06 invoca.
Autoscaling LLM en Kubernetes — la palanca de escalado que RB-01 y RB-05 invocan.
Capacity planning — el head-room presupuestado para absorber incidentes sin SLO break.
ISO/IEC 42001 AIMS para LLM on-premise — la cláusula 10 que estos postmortems materializan.
Controles técnicos ENS × 42001 × EU AI Act — el mapeo de controles que estos runbooks satisfacen.
EU AI Act: mapeo a arquitectura LLM — el art. 73 de incidentes graves que activa el sub-workflow legal.
Cinco niveles de madurez — los runbooks codificados son requisito del nivel 3-4.

Referencias

ISO/IEC 27035-1:2023 — Information security incident management — Principles and process.
ISO/IEC 27035-2:2023 — Information security incident management — Guidelines to plan and prepare for incident response.
ENS — Real Decreto 311/2022, Anexo II controles op.exp.7 a op.exp.10.
Directiva NIS2 (UE 2022/2555) — art. 23 (notificación de incidentes significativos).
Reglamento EU AI Act (UE 2024/1689) — art. 73 (reporting of serious incidents).
ISO/IEC 42001:2023 — AI management system — cláusula 10 (mejora continua).
Keep project — keephq.dev y github.com/keephq/keep (documentación de workflows YAML, providers).
Apache Kafka — Tiered Storage y cleanup.policy (docs.confluent.io / kafka.apache.org).
Confluent — Schema Registry y best practices para eventos lifecycle.
NVIDIA — Xid Errors Documentation y procedimientos de remediación.
Google SRE Book — Effective Troubleshooting y Postmortem Culture.
Atlassian — Incident Management Handbook (referencia para severity matrices).

Anatomía de las doce métricas DCGM y cinco vLLM: analogías, anomalías documentadas y casos reales 2024-2026

Tue, 02 Jun 2026 04:00:00 +0200

Este post profundiza la lista de métricas presentada en Observabilidad GPU para inferencia LLM. Allí cada métrica recibió su umbral V/Á/R y query PromQL; aquí cada una recibe su analogía explicativa y la anomalía documentada en producción con caso público referenciado. Es el post que conviene tener abierto cuando una alerta dispara y todavía no se sabe qué hacer con ella; el siguiente post sobre runbooks traduce cada anomalía a acción concreta.

TL;DR

Las doce métricas DCGM (compute, memoria, térmico-energético, salud) y las cinco del motor vLLM (concurrencia, KV pool, latencias del SLO) cubiertas en el post anterior pintan la cabina del cluster, pero la lista sin contexto no enseña a diagnosticar. Cada métrica tiene un patrón anómalo recurrente documentado en literatura pública —papers académicos, issues GitHub, KBs de OEMs, blogs de operadores— que el operador veterano reconoce al instante y el junior no. Este post desarrolla cada métrica con una analogía propia que fija qué pregunta responde y con la anomalía estadísticamente relevante con cifras de incidentes documentados. Tres ejemplos del calibre: Meta publicó que durante el entrenamiento de Llama 3 405B sobre 16.384 H100 hubo 419 fallos no planificados en 54 días —uno cada 3 horas—, con GPU + HBM3 acumulando el 47 % del total; el paper Story of Two GPUs (arXiv 2503.11901) cuantifica que H100 tiene 3.2× peor MTBE por ECC uncorrectable que A100 atribuible a la densidad superior de HBM3; el issue vllm#16300 documenta que en un cluster de 8×A100 80 GB TP=8 entrega peor throughput que TP=4 porque la saturación de NVLink mata el speedup de partition. Las KBs Dell 000220508 y Lenovo HT514380 formalizan el caso recurrente de HW Power Brake en racks H100 sobrecomprometidos a nivel de PDU. El issue vllm#25677 mostró chunked prefill 10× más lento que sin él en Qwen3-30B-A3B (mala calibración de max_num_batched_tokens). El issue vllm#11912 documenta regresión de TPOT de 15.7 ms a 25.7 ms cruzando versión 0.6.4. Cada caso incluye URL verificable. La regla operativa: cuando llega una alerta, mira primero el patrón anómalo asociado a la métrica que disparó, antes de abrir la traza de la request; el 80 % de las degradaciones casan con uno de los patrones documentados.

Estás aquí: OBSERVE — la capa de diagnóstico

Familia 1 — Compute

`DCGM_FI_PROF_SM_OCCUPANCY` — ¿hay trabajo paralelo en los motores?

La analogía. Una cocina industrial con 32 fogones y un único chef. La métrica responde "¿cuántos fogones tienen una sartén encima ahora mismo?". Si la mitad están vacíos, la cocina está infrautilizada — los pedidos van uno detrás de otro porque el chef no abre paralelo. Si todos están ocupados pero el chef está sin moverse mirando un cronómetro, los fogones están encendidos pero no se cocina (un kernel patológico saturando SMs sin hacer trabajo útil).

La anomalía documentada. La trampa más conocida: SM occupancy alto no implica throughput real. El artículo “GPU Utilization Is a Counter, Not a Cause” (Ingero, mayo 2026) lo formuló con una frase exacta: “un kernel que corre al 5 % del pico de FLOPS durante 100 ms todavía marca 100 % en SM_ACTIVE”. En workloads MoE, el efecto se vuelve patológico: los expertos sobrecargados producen el Straggler Effect (paper arXiv 2503.05066) — los SMs aparecen ocupados esperando al experto saturado, y el dashboard de utilización pinta verde mientras la latencia se va al techo.

Implicación operacional. No fiar el sizing ni el autoscaling solo a SM occupancy. Combinar siempre con PIPE_TENSOR_ACTIVE (¿hay compute útil?) y DRAM_ACTIVE (¿la memoria es el cuello?). El régimen normal LLM en decode es 30–55 %, no 99 %; ver 99 % sostenido con TPOT alto es síntoma de bug del kernel o de straggler MoE.

`DCGM_FI_PROF_PIPE_TENSOR_ACTIVE` — ¿los tensor cores producen?

La analogía. Una fábrica con dos líneas: la artesanal (CUDA cores) y la automatizada (tensor cores). La métrica responde "¿qué porcentaje del tiempo está activa la línea automatizada?". Si compras una H100 por sus tensor cores y la línea automatizada está al 5 %, has pagado un Ferrari para llevar mensajería en bicicleta.

La anomalía documentada. El issue vllm#20783 (julio 2025) tituló literalmente “Performance Anomaly: compressed-tensors no muestra speedup sobre BF16 en H100”. El operador esperaba 1.5–2× con cuantización FP8 y obtuvo paridad con BF16; la métrica PIPE_TENSOR_ACTIVE reveló que el path FP8 no estaba ejecutándose en los HMMA (la unidad tensor de FP16/BF16/FP8) y caía a CUDA cores. El issue vllm#31475 documentó el caso paralelo en MI300X: FP8 más lento que BF16 por regresión en el path ROCm. DCGM expone counters separados por unidad (HMMA para FP16/BF16/FP8, IMMA para INT8, DMMA para TF32/FP32); si HMMA está bajo aunque el modelo es BF16, el engine no usa tensor cores.

Implicación operacional. Verificar PIPE_TENSOR_ACTIVE después de cada cambio de quantization o versión del motor; un cambio supuestamente neutro puede haber desactivado el path optimizado. Para prefill esperar 50–80 %; para decode 15–30 % es normal (decode es memory-bound, no compute-bound). Cifra < 5 % en prefill = el motor no está usando tensor cores.

`DCGM_FI_PROF_DRAM_ACTIVE` — ¿está la HBM saturada?

La analogía. Una autopista con N carriles. La métrica responde "¿qué porcentaje del tiempo están todos los carriles ocupados moviendo coches?". Cuando los tensor cores piden datos más rápido de lo que la HBM los entrega, la autopista está al 95 % y los motores esperan. En decode, este es el régimen normal — paseas los pesos del modelo y el KV cache por cada token.

La anomalía documentada. El paper “Mind the Memory Gap: Unveiling GPU Bottlenecks in Large-Batch LLM Inference” (arXiv 2503.08311) cuantifica que a contextos ≥ 128k, la lectura del KV cache domina el tiempo total de decode y satura la HBM3 (3.35 TB/s en H100). Patrón distintivo: DRAM_ACTIVE > 80 % con PIPE_TENSOR_ACTIVE ~10–20 %. Subir el batch ya no ayuda — el cuello no son FLOPS, es bandwidth. La palanca útil es comprimir KV: ver Quantization para --kv-cache-dtype=fp8 que recorta el footprint de KV ~50 %.

Implicación operacional. Si DRAM_ACTIVE > 95 % sostenido y gpu_cache_usage_perc < 70 %, algo está pidiendo HBM que no es tu motor (leak en una librería, otro proceso compartiendo GPU sin MIG). Investigar inmediatamente con nvidia-smi y fuser /dev/nvidia*.

Familia 2 — Memoria

`DCGM_FI_DEV_FB_USED` — ¿cuánta VRAM lleva consumida?

La analogía. El nivel de combustible del depósito de un avión en vuelo: el piloto necesita saber cuánto queda y a qué ritmo se consume, no solo la cifra puntual. Una H100 al 88 % de FB used estable puede operar tranquila; la misma cifra subiendo 2 %/min anuncia OOM en 7 minutos.

La anomalía documentada. El issue dcgm-exporter#512 documenta una sorpresa relevante para clusters MIG: DCGM_FI_DEV_FB_USED y DCGM_FI_DEV_FB_FREE están ausentes en GPU instances H100 con MIG activado — sí presentes en A100 y B200, pero un bug del exporter los esconde en H100-MIG. Operadores que asumen el dashboard cubre todo descubren la ceguera el día del primer OOM. Issue dcgm-exporter#271 documenta otro detalle: FB_USED + FB_FREE no siempre suma constante porque hay overhead reservado por el driver que aparece en el delta. El paper original de PagedAttention/vLLM estimaba que serving frameworks pre-PagedAttention desperdiciaban 60–80 % del KV cache por fragmentación; PagedAttention lo bajó a < 4 %.

Implicación operacional. En clusters MIG H100, verificar que DCGM_FI_DEV_FB_USED aparece por instance antes de confiar en alertas; si está ausente, monitorizar vía nvidia-smi --query-gpu=memory.used directamente. Regla operativa: alertar sobre delta (subida sostenida), no solo umbral absoluto.

`DCGM_FI_DEV_FB_FREE` — el complemento absoluto

La analogía. El indicador “kilómetros restantes” del coche moderno: complementa al porcentaje con una cifra absoluta directamente accionable.

La anomalía documentada. Cuando un PagedAttention pool agresivo deja FB_FREE en valores absolutos pequeños (< 2 GiB), cualquier asignación normal de buffers transitorios (activaciones de un prefill grande) puede empujar al OOM. El patrón clásico: porcentaje “verde” (87 %) pero absoluto “rojo” (< 4 GiB libres en una H100 de 80 GB).

Implicación operacional. Alerta complementaria con umbral absoluto: DCGM_FI_DEV_FB_FREE < 4096 (MiB). Es la red de seguridad para los casos donde el porcentaje engaña porque el motor está configurado con gpu_memory_utilization muy alto.

`DCGM_FI_DEV_NVLINK_BANDWIDTH_TOTAL` — ¿el bus interno aguanta?

La analogía. Una autopista interestatal entre cuatro ciudades. Cada coche que cruza para hacer un all-reduce de tensor parallel paga peaje y consume ancho. Cuando hay más coches que la autopista soporta, la latencia para llegar a destino se dispara — aunque cada coche individual sea rápido.

La anomalía documentada. El issue vllm#16300 (abril 2025) tituló “Performance degradation with tp=8 compared to tp=4 on 8×A100(80G)” y documentó TP=8 entregando peor throughput que TP=4 en el mismo cluster, mismo modelo, misma quantization. Causa raíz: el tensor parallelism requiere all-reduce tras cada bloque de atención y MLP; a TP=8, el coste de comunicación entre 8 GPUs (incluso vía NVSwitch) crece más rápido que el speedup del partition compute. La regla práctica que emerge: TP=4 + 2 réplicas suele entregar mejor latencia/throughput que TP=8 + 1 réplica salvo para contextos extremadamente largos (≥128k) donde necesitas la VRAM agregada. Capacidad teórica NVLink 4.0 en H100 SXM: ~450 GB/s por GPU; régimen TP=4 sostenido típico: 50–150 GB/s.

Implicación operacional. Si NVLINK_BANDWIDTH_TOTAL > 90 % capacidad sostenido, no es problema resoluble subiendo paralelismo — al revés, bajar TP. La métrica es ortogonal al sizing del capacity planning: el techo no es solo VRAM/tiempo, también el bus.

Familia 3 — Térmico y energético

`DCGM_FI_DEV_GPU_TEMP` — ¿la GPU respira?

La analogía. La temperatura corporal de un atleta de élite en pleno esfuerzo. 36–37 °C es normal; 38 °C es estrés sostenible; por encima de 39 °C el cuerpo activa mecanismos de protección (sudoración, ralentización) que degradan el rendimiento. La GPU hace lo mismo: por encima de un umbral térmico, reduce su clock automáticamente. Si no lo hiciera, se rompería.

La anomalía documentada. El H100 SXM5 con TDP 700 W tiene thresholds térmicos no enteramente públicos (NVIDIA no los publica exhaustivamente en datasheet), pero el comportamiento es bien conocido: por encima de ~85 °C edge o ~95 °C HBM aparece el bit 0x40 HW_THERMAL en clock throttle reasons. Operadores en el foro NVIDIA developer reportan que con temperatura de entrada al rack > 27 °C, el throttle es habitual. El paper de NVIDIA HGX Platform indica que el flujo de aire mínimo recomendado es > 1000 CFM/kW; densidades > 30 kW/rack a 700 W TDP exigen liquid cooling obligatorio porque el aire forzado no llega.

Implicación operacional. Si GPU_TEMP > 83 °C sostenido, mirar primero CLOCK_THROTTLE_REASONS (bit 0x40) y temperatura de entrada al rack — no es problema del motor, es del flujo de aire. Para racks legacy aire-cooled, plantear redistribuir carga térmica o instalar rear-door HX.

`DCGM_FI_DEV_POWER_USAGE` — ¿cuánto pide al enchufe?

La analogía. El consumo instantáneo de un electrodoméstico industrial conectado a una toma trifásica con un breaker dimensionado. Si la lavadora arranca a 9 kW y el breaker es de 10 kW, vives al filo; si la lavadora se “lleva bien” con el breaker es porque alguien dimensionó conscientemente.

La anomalía documentada. Medición real publicada: una H100 SXM5 con vLLM corriendo Llama 3.1 405B batch=4 consume ~697 W at-wall sostenido (NVIDIA TDP 700 W). Ahora la palanca operativa interesante: bajar nvidia-smi -pl de 700 W a 500 W entrega ~30 % de ahorro energético con solo ~20 % de pérdida de throughput. Cluster de 4 nodos × 8 H100 a 700 W = ~22 kW solo de GPU; a 500 W = ~16 kW. La diferencia paga la factura eléctrica entera de un trimestre en clusters operados ininterrumpidamente. Una rama PDU 415 VAC trifásica 60–80 A soporta ~32 kW, ~4 DGX H100. Legacy 208 V no soporta densidad H100 — referencia: NVIDIA DGX SuperPOD Electrical Specifications.

Implicación operacional. Métrica útil para tres cosas: (1) detectar workloads anómalamente bajos (idle inesperado), (2) calcular showback de coste energético real por tenant (no estimaciones), (3) alertar si el draw se acerca al límite de PDU rama. Tener mapeado GPU → PDU rama → breaker en CMDB.

`DCGM_FI_DEV_CLOCK_THROTTLE_REASONS` — ¿quién pisa el freno?

La analogía. El testigo de “modo limitado” en el salpicadero de un coche moderno. Cuando se enciende, el coche reduce su rendimiento automáticamente, pero no te dice por qué salvo que sepas leer la combinación de letras. Los bits del bitmap son esas letras.

La anomalía documentada. Caso público formalmente reconocido por dos OEMs distintos: Dell KB 000220508 y Lenovo HT514380 abordan el mismo fenómeno: HW Power Brake Slowdown active (bit 0x80) en H100 SXM. La causa no es la GPU — es la PDU del chasis enviando una señal eléctrica de power-brake porque la rama del rack está cerca del límite del breaker. El operador ve throughput caído 30–50 % sin XID ni ECC, y el motor de inferencia “está sano”; el problema está en electricidad. Foro NVIDIA developer en “HW Power Brake Slowdown” corrobora el patrón. El bit 0x40 HW_THERMAL aparece en racks mal ventilados; el bit 0x04 SW_POWER_CAP aparece si alguien dejó nvidia-smi -pl 500 y nadie revertirá.

Implicación operacional. Cualquier bit ≠ 0 ni Idle (bit 0x01) sostenido es alerta inmediata. La descodificación recomendada: registrar el valor bitmap completo en el log + atributo throttle.reasons.decoded=["HW_THERMAL", "HW_POWER_BRAKE"] en el span OTel. Sin esto, el incident response no sabe qué hacer.

Familia 4 — Salud (los reportes catastróficos)

`DCGM_FI_DEV_XID_ERRORS` — los códigos rojos del driver

La analogía. Las luces de alarma críticas en una sala de control nuclear. No suben gradualmente; aparecen o no aparecen. Cada XID es un código predefinido (XID 13 = excepción del motor de gráficos; XID 31 = fault de MMU; XID 43 = stopped channel; XID 79 = GPU fallen off the bus; XID 95 = uncontained ECC), y cada uno tiene su procedimiento documentado.

La anomalía documentada. El caso público más estudiado: Meta publicó que durante el entrenamiento de Llama 3 405B sobre 16.384 H100 en 54 días hubo 419 fallos no planificados, uno cada 3 horas a escala de cluster. GPU acumuló 148 (35 %) + HBM3 72 (17 %) = casi la mitad de todos los fallos. El paper “Story of Two GPUs: Characterizing the Resilience of Hopper H100 and Ampere A100” (arXiv 2503.11901) cuantifica con un dataset distinto (2.1M GPU-horas) que H100 tiene 3.2× peor MTBE para ECC uncorrectable que A100. El paper de ByteDance MegaScale reporta que XID 79 (“GPU fallen off the bus”) coocurre con errores PCIe en el 43 % de los casos. El foro NVIDIA developer documenta casos persistentes de XID 31 (MMU fault) que siguen a la GPU al cambiar de slot PCIe — bug hardware del módulo, no del backplane.

Implicación operacional. Cualquier incremento del contador es alerta inmediata: muchos XID exigen reset del nodo o RMA de la GPU. La distinción XID-por-XID importa: XID 13/43 suele ser bug de software si coincide con cambio reciente; XID 31/48/79/94/95 suele ser hardware. Mantener tabla canónica xid → procedimiento. Ver los runbooks para la traducción a acción concreta.

`DCGM_FI_DEV_ECC_DBE_VOL_TOTAL` — los errores que corrompen datos

La analogía. Un libro de contabilidad donde a veces alguien borra una entrada y la rescribe (ECC single-bit corregido — anota un cambio en el margen y sigue) y a veces alguien quema dos páginas a la vez (double-bit — la información se perdió, hay que parar la auditoría).

La anomalía documentada. El paper “Characterizing GPU Resilience” cuantifica para H100: cuando XID 48 (DBE) aparece, el job en curso muere con 100 % de probabilidad (5/5 en el dataset estudiado). La recuperación documentada: drenar el nodo + reset + completar row remap = ~19 horas de downtime de nodo. La densidad HBM3 explica el peor MTBE vs HBM2e: hay más celdas por unidad de área, mayor probabilidad estadística de degradación. En Llama 3, HBM3 causó 72 de 419 interrupciones (17 %).

Implicación operacional. Cualquier valor > 0 = alerta crítica. La GPU debe ser drenada inmediatamente, retirada del scheduler, reset completo, validación de row remap con nvidia-smi -q -d ROW_REMAPPER (Pending: No), y antes de volver al pool, smoke test extenso. Si el row remap usa > 4–8 páginas de spare en una GPU, planificar reemplazo en próxima ventana — la degradación es progresiva.

`DCGM_FI_DEV_RETIRED_DBE` — las páginas marcadas para retirar

La analogía. Las baldosas que el restaurador del museo marca con cinta amarilla porque están dañadas. No suponen peligro inmediato (la sala sigue abierta), pero la acumulación dice que el suelo se está degradando estructuralmente y el reemplazo entero hay que planificarlo.

La anomalía documentada. NVIDIA documenta hasta 512 páginas de spare por banco HBM en H100; el contador RETIRED_DBE indica cuántas se han usado. Operadores en foros NVIDIA reportan que por encima de 4–8 páginas retiradas en una GPU concreta, la frecuencia de XID 48 sube. Patrón: GPU con 6 páginas retiradas hoy → 12 en un mes → primer XID 48 dos meses después → drain forzoso.

Implicación operacional. Métrica de tendencia, no de alerta inmediata. Documentar valor por GPU y revisar mensualmente; las GPUs con valores crecientes entran al plan de reemplazo proactivo antes del fallo catastrófico.

Las cinco métricas del motor vLLM

`vllm:num_requests_running` — ¿cuántas requests caben en el batch?

La analogía. El número de coches que un peaje deja pasar simultáneamente. Si la barrera abre N a la vez, las N+1 esperan en cola. La saturación se nota porque la fila no se acorta.

La anomalía documentada. Llegar al --max-num-seqs configurado y mantenerse ahí es síntoma típico de cluster por debajo del sizing; el motor admite hasta el techo y no más. La query vllm:num_requests_running == max_num_seqs durante > 5 minutos indica saturación firme.

Implicación operacional. Combinar con num_requests_waiting: si running está al techo Y waiting > 0, hay que escalar. Si running está al techo y waiting es 0, estás en el régimen óptimo (cluster usado al máximo sin cola).

`vllm:num_requests_waiting` — el indicador primario de saturación

La analogía. La cola visible delante del peaje. Mientras esté vacía, el sistema fluye; en cuanto se forma cola sostenida, los conductores empiezan a llegar tarde a destino — el TTFT se va al techo.

La anomalía documentada. Caso público en “11-Second Time to First Token on a Healthy vLLM Server” (Medium, Ingero, 2026): servidor sin XIDs, sin preemption, métricas DCGM en verde, pero num_requests_waiting sostenido > 0 y TTFT de 11 segundos. El issue vllm#16985 documenta degradación progresiva en sesiones largas: la queue crece lentamente durante horas sin que ningún otro indicador se mueva. La causa raíz no es de hardware — es de admission control: la tasa de entrada supera la de finalización y el sistema no encola más, deja en WAITING. Red Hat la designa como la métrica primaria de saturación en su tutorial “5 steps to triage vLLM performance”.

Implicación operacional. Métrica primaria del HPA en KEDA —ver Autoscaling LLM en Kubernetes—. Umbral típico: alertar si avg_over_time(vllm:num_requests_waiting[5m]) > 5. Para canary: si la cola se forma solo en el pool v2, es regresión del nuevo modelo, no carga del cluster.

`vllm:gpu_cache_usage_perc` — el pool de KV cache

La analogía. La capacidad de una sala de eventos donde cada invitado ocupa un espacio variable. El maître admite hasta el aforo; cuando llega un invitado nuevo y no hay sitio, echa al invitado que lleva más tiempo para hacerle hueco al recién llegado. Eso es el preempt-on-OOM de vLLM.

La anomalía documentada. El issue vllm#5051 “Add num_requests_preempted metric” nació exactamente de operadores observando degradación pero sin métrica directa que les dijese cuántas requests se estaban echando. Documentación oficial vLLM confirma: “sustained gpu_cache_usage_perc above 90 % indicates the server is approaching its KV cache limit and will begin preempting sequences” (oldest-first). El patrón visual distintivo: sierra (sawtooth) cerca del 100 % con picos de preemption. En modo swap, la latencia de la request preempted explota porque hay copia PCIe host↔device; en modo recompute (default en V1), la request preempted rehace su prefill desde cero, lo que dispara su TTFT al doble o triple.

Implicación operacional. Si gpu_cache_usage_perc > 92 % sostenido, dos palancas: bajar max_num_seqs (admite menos concurrencia pero ninguna se preempta) o subir gpu_memory_utilization (más pool, menos VRAM para activations transitorias — riesgo distinto). La elección depende del workload. La métrica que falta directamente —contador de preempted— se exporta a partir de vLLM v1.0 en vllm:num_preemptions_total (ver issue #5051).

`vllm:time_to_first_token_seconds` — la latencia visible al cliente

La analogía. El tiempo desde que un cliente entra a un restaurante hasta que recibe el primer trozo de pan en la mesa. Demasiado largo y el cliente piensa que se han olvidado de él, aunque la comida principal vaya a llegar perfecta.

La anomalía documentada. Tres patrones documentados de spike de TTFT recurrentes:

Chunked prefill mal calibrado. Issue vllm#25677 (Qwen3-30B-A3B) reportó prefill 10–11× más lento con chunked prefill activado que sin él. Causa: max_num_batched_tokens muy bajo fuerza chunks pequeños que no llenan los kernels. Issue vllm#7604 documenta regresión equivalente en Llama-3-70B v0.5.4. La palanca: subir max_num_batched_tokens a 4096–8192 para prompts típicos > 2k.
Regresión entre versiones del motor. Issue vllm#8819 documenta regresión de vllm:time_to_first_token_seconds_sum entre versiones minor. Issue vllm#11912 reporta que con prompt ~8000 tokens, TPOT subió de 15.7 ms → 25.7 ms desde v0.6.4.post1 sin cambio de config — regresión confirmada y trackable solo con la métrica.
Long-context prefill bloqueando decodes. El caso “11s TTFT on healthy server” citado arriba: un prefill de 30k tokens monopoliza la GPU durante varios segundos y los decodes activos congelan. Solución: chunked prefill bien calibrado, o disaggregated serving (ver Disaggregated serving).

Implicación operacional. No alertar solo sobre P95 absoluto; alertar también sobre ratio v2/v1 cuando hay canary (histogram_quantile(0.95, ..., version="v2") / histogram_quantile(0.95, ..., version="v1") > 1.10). Si TTFT crece y la queue está estable, el bottleneck es prefill — no resoluble subiendo réplicas, sí palanca de quantization o chunked prefill.

`vllm:time_per_output_token_seconds` — la fluidez del streaming

La analogía. La velocidad a la que el camarero trae los platos uno detrás de otro después del primero. Si tarda en venir el siguiente, el comensal nota que algo no va bien aunque el primer plato haya llegado a tiempo.

La anomalía documentada. El patrón distintivo es el escalón abrupto cuando gpu_cache_usage_perc cruza ~85 %: el TPOT pasa de 35 ms a 80 ms en pocos segundos porque el motor empieza a competir por la HBM con sus propias evicciones. Issue vllm#35387 documenta otro caso anómalo: MTP (speculative decoding) causando 76 % de regresión de latencia en Qwen3-Next-80B-A3B-Instruct-FP8 — la métrica TPOT lo capturó antes de que se reportasen quejas de clientes.

Implicación operacional. Diferencia con TTFT: si TTFT crece y Queue Time estable → prefill bound; si TPOT crece a tasa estable → presión sobre HBM (KV cache pool o swap activado). Alerta secundaria sobre el SLO de TPOT, pero también vigilar la derivada: TPOT subiendo 1 ms cada 10 minutos es regresión latente que aún no rompe SLO pero lo hará.

La regla operativa: leer las métricas por familia, no aisladas

Tres anti-patterns del operador novato

Anti-pattern 1 — alertar solo sobre umbrales absolutos. Una H100 al 87 % de FB no es necesariamente alarma; la H100 con 87 % subiendo 2 %/min sí lo es. Las alertas que disparan por umbral fijo sin mirar derivada producen el doble de ruido y la mitad de la utilidad. Regla: para métricas con dinámica conocida (KV cache, FB, queue), alertar sobre delta sostenido, no solo nivel.

Anti-pattern 2 — confundir SBE con DBE. El contador DCGM_FI_DEV_ECC_SBE_VOL_TOTAL (single-bit, corregibles) crece continuamente en cualquier HBM bajo carga; no es alarma, es física. El que importa es DCGM_FI_DEV_ECC_DBE_VOL_TOTAL (double-bit, no corregibles). Confundirlos = falsos negativos (no alertar sobre DBE real) o falsos positivos (alertar sobre SBE inofensivo).

Anti-pattern 3 — tratar SM_OCCUPANCY 99 % como “saturada”. El régimen LLM en decode es memory-bound, no compute-bound; SM occupancy alto con TENSOR_ACTIVE bajo y DRAM_ACTIVE alto es lo normal. Dimensionar para “GPU al 60 %” pidiendo más hardware cuando el cluster está saturado en HBM (no en SM) es comprar el doble de GPU sin ganar throughput. Regla: leer SM_OCCUPANCY siempre con TENSOR_ACTIVE y DRAM_ACTIVE; aislada no significa nada.

Aplicado a hardware on-premise típico

Para un cluster genérico de 4 nodos × 4×H100 SXM 80 GB con NVLink intra-nodo:

DCGM Exporter por nodo (DaemonSet del GPU Operator) emitiendo cada 15 s; cardinalidad por GPU = ~80 series. Cluster 16 GPUs ≈ 1.3k series base, ~85k samples/min con scrape de 15 s.
vLLM /metrics por pod inferencia; cada réplica emite ~50 series base. Para 16 réplicas, ~800 series adicionales, ~3k samples/min.
Prometheus retention: 30 días alta resolución + 1 año downsampled vía Thanos sidecar o Mimir. Volumen estimado: 25–35 GB/día.
Alertmanager: las 6 alertas críticas del post anterior + alertas derivadas (delta, ratio v2/v1, throttle bitmap decodificado).

Cada métrica conviene exponer también como atributo OTel en los spans del tracing GenAI: gpu.fb_used_pct, gpu.dram_active, gpu.throttle_reasons.decoded. Eso permite correlacionar una request lenta con el estado de la GPU en ese instante, sin saltar entre dashboards.

Lo que no hemos cubierto (próximos posts)

Runbooks por alerta — la traducción de cada métrica anómala a acción concreta (drain, reset, RMA, escalado, rollback) en el siguiente post: Runbooks de incident response.
Tail-sampling para correlación métrica ↔ traza — qué se preserva cuando una alerta dispara para investigación post-mortem.
Showback por tenant combinando vllm:request_success_total × gen_ai.usage.* × DCGM_FI_DEV_POWER_USAGE para facturar coste energético real.
Métricas de fairness multi-tenant — cuándo un tenant acapara el KV cache pool y cómo detectarlo.

Ver también

Observabilidad GPU para inferencia LLM — la lista compacta que este post profundiza.
Runbooks de incident response para LLM con Keep + Kafka — la traducción de cada anomalía a acción.
Tracing LLM con OpenTelemetry GenAI — la otra mitad de la observabilidad.
Autoscaling LLM en Kubernetes — num_requests_waiting y gpu_cache_usage_perc como métricas primarias de HPA.
Capacity planning para inferencia LLM on-premise — cómo se relacionan los umbrales con el sizing.
Canary, blue-green y shadow — el ratio TTFT v2/v1 como gate.
Continuous batching — explica el preempt-on-OOM y la sierra del KV pool.
KV cache — fundamenta el cálculo de gpu_cache_usage_perc.

Referencias

Meta — Faulty Nvidia H100 GPUs and HBM3 memory caused half of failures during Llama 3 training (Tom’s Hardware, 2024). tomshardware.com
Story of Two GPUs: Characterizing the Resilience of Hopper H100 and Ampere A100. arXiv 2503.11901. https://arxiv.org/html/2503.11901v3
ByteDance — Robust LLM Training Infrastructure at ByteDance. arXiv 2509.16293. https://arxiv.org/pdf/2509.16293
Mind the Memory Gap: Unveiling GPU Bottlenecks in Large-Batch LLM Inference. arXiv 2503.08311.
Capacity-Aware Inference: Mitigating the Straggler Effect in Mixture of Experts. arXiv 2503.05066.
NVIDIA — Analyzing Xid Errors with the Xid Catalog y Memory Error Management (docs.nvidia.com/deploy).
Dell — PowerEdge XE8640 with H100 - GPU Performance Issue HW Power Brake Slowdown - Active (KB 000220508).
Lenovo — Power brake reporting on H100 GPU (HT514380).
vLLM project — issues #5051 (preempted metric), #7604 y #25677 (chunked prefill regression), #11912 (long-prompt regression), #16300 (TP=8 worse than TP=4), #16985 (long-running degradation), #20783 (compressed-tensors no speedup), #35387 (MTP regression).
Red Hat — 5 steps to triage vLLM performance. https://developers.redhat.com/articles/2026/03/09/5-steps-triage-vllm-performance
AI21 — Go big or go OOM: the art of scaling vLLM. https://www.ai21.com/blog/scaling-vllm-without-oom/
11-Second Time to First Token on a Healthy vLLM Server (Medium, Ingero, 2026).
NVIDIA — DGX SuperPOD Electrical Specifications (docs.nvidia.com/dgx-superpod).

Sources: las URLs completas están enlazadas en línea sobre cada referencia.

El router de inferencia LLM: la centralita L7 que en el post de canary llamábamos LoadBalancer

Tue, 02 Jun 2026 03:00:00 +0200

Este post es la continuación natural de Canary, blue-green y shadow para modelos LLM. Allí la mecánica de promoción depositó toda la complejidad de reparto de tráfico en una caja a la que llamamos “LoadBalancer”. La descripción era operacional —servía para entender la coreografía— pero estructuralmente vaga: lo que de verdad hace ese reparto es un router de inferencia L7 con awareness LLM, una pieza de pleno derecho del stack (capa 1 de las siete capas) que merece su propio post.

TL;DR

En el post anterior sobre canary llamamos LoadBalancer a la pieza que reparte tráfico entre los pools v1 estable y v2 candidato. La descripción servía para entender el flujo, pero técnicamente era borrosa: ni un LoadBalancer L4 (kube-proxy, MetalLB, IPVS) ni un LoadBalancer L7 HTTP genérico (NGINX o HAProxy sin extensión) saben qué es un modelo, qué es una versión, cuántos tokens cuesta una request, qué prefijo tiene el prompt o qué KV cache tiene caliente cada réplica. La pieza correcta es un router de inferencia LLM: un proxy L7 con conocimiento explícito del dominio. Combina cuatro funciones: catálogo de modelos (resolver model=llama-70b@v2 → service.namespace:port), traffic splitting (aplicar el weight de canary con hash determinista o sticky deliberado para A/B), política transversal (auth OIDC, rate limit y quota por tenant, redact PII pre-prompt, guardrails ligeros inline, propagación de tracing gen_ai.*) y failover/degradación (si v2 cae, redirigir a v1; si todo el cluster está saturado, devolver 503 con Retry-After en vez de encolar para siempre). La pieza no obvia que justifica su existencia técnica más allá de la operacional es el prefix-aware routing: el router decide a qué réplica de la flota va cada request en función del prefijo del prompt, para que un sistema RAG con el mismo system prompt + el mismo bloque de documentos recuperados acierte sistemáticamente en el prefix cache (RadixAttention en SGLang, PrefixCaching en vLLM, KV reuse en TensorRT-LLM) de la misma réplica, multiplicando el hit rate del 5–15 % (round-robin ciego) al 60–85 % (afinidad por prefix). Las piezas concretas en mayo 2026 son LiteLLM Proxy (la opción más simple, OpenAI-compatible, catálogo declarativo YAML), vLLM Production Stack router (específico para flotas vLLM, aware del KV cache y del prefix), Envoy AI Gateway (filtros Envoy LLM-aware, integrable con Istio), Kong AI Gateway (alternativa empresarial con plugin ecosystem), KGateway (CNCF en gestación) y NVIDIA Dynamo router (production-grade, aware de disaggregated serving prefill/decode). En el stack de siete capas vive en la capa 1 (gateway); en el de cinco niveles de madurez aparece a partir del nivel 3; en el ciclo de siete fases de despliegue es la última pieza que F6 cierra. Este post incluye un manifest mínimo aplicable a un cluster genérico de 4×H100 SXM.

Estás aquí: DEPLOY (capa 1 del stack)

El antecedente: lo que el post de canary llamaba “LoadBalancer”

En Canary, blue-green y shadow para modelos LLM describimos el flujo así: “el LoadBalancer reparte progresivamente el tráfico siguiendo un cronograma: 1 % → 5 % → 25 % → 100 %”. Era una descripción operacional correcta — el lector entendía la coreografía sin necesitar más. Pero técnicamente dejaba sin nombre a una pieza que merece tratamiento explícito, porque ninguno de los dos sentidos habituales de “LoadBalancer” hace lo que ese párrafo asumía:

Un LoadBalancer L4 —kube-proxy con iptables/IPVS, MetalLB, F5 BIG-IP en modo TCP— reparte paquetes IP sin mirar dentro del payload. No sabe qué modelo se pide, ni qué versión, ni cuántos tokens lleva, ni si el cliente tiene quota. No puede aplicar el weight del canary “para el modelo X versión 2”: para él todos los paquetes hacia el VIP vllm-llama70b son indistinguibles.
Un LoadBalancer L7 HTTP genérico —NGINX o HAProxy en modo HTTP sin extensión, una Service de tipo ClusterIP con backend múltiple— sí reparte por URL y puede hacer routing por header, pero no entiende el cuerpo OpenAI-compatible de la request. No sabe que {"model": "llama-70b", "messages": [...]} lleva en el campo model la clave de routing; no cuenta tokens; no aplica políticas sobre estructuras LLM; no hace prefix-aware routing porque eso exige parsear el messages y hashear el prefijo común.

La pieza que el post de canary asumía haciendo este trabajo es un router de inferencia L7 con awareness LLM. Una capa de pleno derecho, con su propia configuración, su propio CI/CD, sus propias métricas y sus propios pitfalls. Este post la nombra y la desmonta.

La analogía: la centralita y triage de un hospital con múltiples especialidades

Un hospital grande recibe pacientes que llegan a urgencias por puertas distintas y que necesitan especialidades distintas: traumatología, cardiología, pediatría, oncología. Hay tres modelos posibles de “puerta de entrada”.

Puerta única sin triage. Todos los pacientes esperan en la misma sala y los van pasando por orden de llegada al primer médico libre, sea su especialidad la que sea. Funciona en un consultorio de aldea con un único médico generalista. Cuando hay 200 pacientes al día y 12 especialidades, cae rápido en disfunción: el cardiólogo atiende esguinces, el pediatra atiende infartos, los recursos especializados se desperdician. Es el equivalente del LoadBalancer L4 — reparte cuerpos sin entender qué traen.

Puerta con receptionist que pregunta el síntoma. Una persona en mesa de entrada pregunta “¿qué le pasa?” y dirige al paciente al pasillo correcto. El cardiólogo ve solo cardiología, el pediatra solo niños. Mejor, pero el receptionist es lento, no calibra urgencias y no conoce el estado de las salas: puede mandar al cardiólogo del pasillo A cuando el del B está libre. Es el equivalente de un L7 HTTP genérico con path-based routing — reparte por categoría pero sin información del estado interno.

Triage profesional con awareness completo. Una enfermera de triage formada que conoce el catálogo de especialidades, sabe qué box está ocupado y cuál libre, recuerda al paciente recurrente cuyo expediente ya está abierto en el sistema (manda al mismo médico para continuidad), aplica política transversal (verifica cobertura del seguro, registra alérgenos, redirige a urgencias pediátricas si el paciente es menor) y, si la sala de cardiología cae por una avería del electrocardiograma, redirige al hospital del otro lado de la ciudad. Esta es la pieza que un hospital grande necesita. En LLM se llama router de inferencia.

La analogía sostiene hasta el último detalle, incluido el del “expediente ya abierto”: el paciente que vuelve al mismo médico es exactamente el cliente cuyo prompt comparte prefijo con el de hace 5 minutos. Si el router lo manda a la misma réplica, esa réplica todavía tiene el KV cache caliente y la request acierta el prefix cache. Si lo manda a una réplica distinta porque iba “la siguiente en round-robin”, el KV cache hay que reconstruirlo desde cero y la TTFT se va al doble. La enfermera de triage sabe esto. El LoadBalancer ciego no.

Las cuatro funciones del router de inferencia

Función 1 — Catálogo de modelos

El router mantiene un catálogo declarativo que mapea identidad de modelo a deployment concreto:

models:
 - name: "llama-70b" # alias estable
 version: "v2" # versión canary
 weight: 5 # 5% del tráfico
 endpoint: "vllm-llama70b-v2.inference.svc.cluster.local:8000"
 capabilities: [chat, tool_use]
 lifecycle: canary
 - name: "llama-70b"
 version: "v1"
 weight: 95
 endpoint: "vllm-llama70b-v1.inference.svc.cluster.local:8000"
 capabilities: [chat, tool_use]
 lifecycle: stable
 - name: "embedding-multilingual"
 version: "v1"
 weight: 100
 endpoint: "tei-bge-m3.inference.svc.cluster.local:8080"
 capabilities: [embeddings]
 lifecycle: stable

El cliente envía {"model": "llama-70b", "messages": [...]} sin saber que detrás hay dos pools de réplicas. El router resuelve. Si mañana migras de vLLM a SGLang para una versión concreta, el cliente no se entera; cambias el endpoint en el catálogo y listo.

Lo que se gana con este desacoplamiento es la libertad de mover topología sin romper clientes. Lo que cuesta es mantener disciplinada la convención de nombres (llama-70b siempre es el alias estable; llama-70b@v2 es la versión específica para canary). Sin esa disciplina, los aliases se ensucian con llama-70b-prod-fixed-real-final-v3 y el catálogo deja de ser navegable a las pocas semanas.

Función 2 — Traffic splitting

Las particiones del post de canary (1 % → 5 % → 25 % → 100 %) se materializan aquí, no en el motor de inferencia. El router calcula un hash determinista del request_id (o del user_id, si se quiere sticky) y lo mapea al rango de weights del catálogo. Para un weight [v1: 95, v2: 5], el 5 % del espacio hash cae en v2 y el 95 % en v1.

Tres decisiones de diseño que importan:

Hash por request_id aleatorio = muestreo independiente. Cada request es una observación independiente de la distribución v1 vs v2. Es el setting correcto para canary estadísticamente comparables.
Hash por user_id = sticky por usuario. El mismo cliente ve siempre el mismo pool. Útil para A/B testing con memoria conversacional persistida, pero rompe la comparabilidad estadística del canary porque las poblaciones de usuarios no son simétricas — pitfall explicado en el post anterior.
Hash por tenant_id = particionado fuerte. Tenant A va a v1, tenant B a v2. Es el patrón para clientes con SLA distintos o para validar v2 en un tenant interno antes de exponerlo a clientes externos.

Función 3 — Política transversal

Una vez por encima de todos los modelos, el router aplica:

Auth: OIDC con tokens JWT validados contra Keycloak / Authentik. Headers Authorization: Bearer ... traducidos a tenant_id y roles.
Rate limit: token bucket por tenant (X req/min) o por modelo (Y req/min para llama-70b porque es caro).
Quota: cuota mensual de tokens consumidos por tenant. El router cuenta gen_ai.usage.input_tokens + gen_ai.usage.output_tokens y rechaza con 429 Quota exceeded cuando se agota.
Redact PII pre-prompt: Presidio o Llama Guard en línea antes de que el prompt toque el modelo. Lo que el modelo no ve, no se entrena con ello, no se loguea, no se filtra.
Guardrails ligeros inline: PromptGuard 2, Llama Guard 4, Granite Guardian — los que aparecen en Guardrails y safety en LLMs— se ejecutan en el router porque su latencia (30–150 ms) cabe en el presupuesto de TTFT.
Propagación de tracing gen_ai.*: el router inicia el span padre, propaga traceparent al motor y emite los atributos gen_ai.system, gen_ai.request.model, gen_ai.request.version que el tracing OTel GenAI consume.
Semantic cache: para prompts repetidos exactos o con similitud semántica alta (embedding cosine > 0.97 contra cache previa), devuelve la respuesta cacheada sin tocar el motor. Ahorro típico en RAG con preguntas frecuentes: 20–40 % de las requests.

Función 4 — Failover y degradación

El router conoce el estado de salud de cada endpoint (health probes activos cada 5–15 s, latencia de TTFT recientes) y decide:

Si v2 devuelve 5xx persistente o no responde, circuit breaker abierto: el router redirige el tráfico que iba a v2 hacia v1 hasta que las probes vuelvan a verde. Esto es el rollback automático del canary en su forma más simple.
Si todo el cluster está saturado (todas las réplicas reportan num_requests_waiting > N durante T segundos), el router devuelve 503 Service Unavailable con Retry-After: 30 en vez de encolar para siempre. Mejor decirle al cliente “vuelve en 30 segundos” que tenerlo esperando 4 minutos y luego dar timeout.
Si hay multi-region o multi-cluster, failover cross-cluster vía DNS o L7: la región primaria cae, el router de la secundaria asume.

La pieza no obvia: prefix-aware routing

Esta es la función que un LoadBalancer convencional no puede hacer y que justifica un router específico de LLM más allá de las cuatro genéricas.

El KV cache de vLLM, SGLang y TensorRT-LLM puede reusar prefijos comunes entre requests —ver KV cache—. Concretamente:

vLLM con --enable-prefix-caching: detecta que la request actual comparte un prefijo (longitud múltiplo del block size, default 16 tokens) con una request anterior cuyas páginas todavía están en HBM, y reutiliza esas páginas en vez de reprocesarlas.
SGLang con RadixAttention: estructura el cache como un árbol radix indexado por tokens; cada request acierta el camino común del árbol y solo computa la cola.
TensorRT-LLM: feature similar, llamado KV cache reuse.

El hit rate del prefix cache es la métrica clave: cada token acertado es un token que no se procesa en prefill, reduciendo TTFT en proporción directa. Para un sistema RAG típico —system prompt de 400 tokens + documentos retrieved de 2 000 tokens + pregunta del usuario de 50 tokens— el prefijo común (system_prompt + docs) son 2 400 de los 2 450 tokens totales. Si el cache acierta, el prefill solo procesa 50 tokens en vez de 2 450: TTFT cae aproximadamente a la vigésima parte.

Pero el cache vive por réplica, no globalmente. Si dos requests con el mismo prefix de 2 400 tokens caen en réplicas distintas, ambas hacen el prefill completo: el cache de la primera no sirve a la segunda. La segunda paga el coste íntegro.

Con round-robin ciego (cualquier LB convencional), las requests se reparten uniformemente entre N réplicas. Para un cluster de 4 réplicas y 1 000 requests con el mismo system_prompt + docs, cada réplica recibe ~250 requests, pero las 4 hacen su propio “primer prefill” y los siguientes 249 se benefician dentro de su réplica. El hit rate global es decente pero no óptimo. Para tráfico con muchos sistemas prompts distintos y poca repetición intra-prefix, el hit rate ronda el 5–15 %.

Con prefix-aware routing, el router calcula un hash del prefijo del prompt (los primeros N tokens, o el system_prompt declarado en messages[0]) y mantiene una tabla de afinidad hash → réplica. Todas las requests con el mismo prefijo caen en la misma réplica. La primera paga el prefill completo; las 999 siguientes aciertan el cache. Hit rate global: 60–85 %.

El coste de implementarlo: el router debe parsear el body de la request (no solo el header HTTP), aplicar un tokenizer ligero o un hash basado en bytes, y mantener una tabla LRU/consistent-hash de afinidad que se rebalancea cuando una réplica entra o sale. Es trabajo de servidor, no de proxy genérico. vLLM Production Stack router lo implementa nativamente. NVIDIA Dynamo también. LiteLLM en su versión enterprise tiene un beta. Envoy AI Gateway lo está incorporando como filtro experimental.

La diferencia operativa para un RAG productivo: con prefix-aware routing, el mismo cluster sirve 2–4× más requests sin añadir GPUs, simplemente porque el prefill desaparece en la mayoría de los casos.

Token-aware load balancing

La segunda pieza no obvia. El round-robin clásico reparte por número de requests; pero un prompt de 50 tokens y otro de 8 000 tokens cuestan radicalmente distinto (factor ~160× en prefill). Repartir igualmente por count desequilibra severamente la carga real.

Token-aware load balancing suma tokens de prefill esperados (longitud del prompt) y decode esperados (max_tokens del cliente) por réplica activa, y manda la nueva request a la réplica con menor carga acumulada. Es lo que tanto vLLM Production Stack como NVIDIA Dynamo implementan como estrategia por defecto cuando se activa.

La métrica que alimenta el cálculo es —otra vez— vllm:num_requests_running y vllm:gpu_cache_usage_perc —ver Observabilidad GPU para inferencia LLM—, idealmente complementadas con un estimador de tokens del prompt entrante. Los routers maduros usan tiktoken o el tokenizer real del modelo para contar tokens del prompt antes de elegir réplica.

Comparativa de piezas concretas (mayo 2026)

Pieza	Awareness LLM	Prefix-aware	Token-aware LB	Multi-modelo	Semantic cache	Plug & play
LiteLLM Proxy	Alta	Beta (enterprise)	Sí	Excelente	Sí (Redis)	Muy alto
vLLM Production Stack router	Específico vLLM	Sí, nativo	Sí	Solo vLLM	No (externa)	Medio
NVIDIA Dynamo router	Alta + disagg-aware	Sí	Sí	vLLM/SGLang/TRT-LLM	No (externa)	Bajo
Envoy AI Gateway	Media (filtros)	Experimental	Sí	Sí	Vía filtro	Medio
Kong AI Gateway	Media (plugins)	No	Sí	Sí	Sí (plugin)	Medio
KGateway	Media	Roadmap	Sí	Sí	Roadmap	Bajo (CNCF gestación)
NGINX + custom Lua	Manual	No	Manual	Manual	No	Bajo (build it yourself)

LiteLLM Proxy es la opción por defecto para empezar. OpenAI-compatible, YAML simple, soporta los providers comerciales + cualquier OpenAI-compatible self-hosted. La versión OSS cubre las cuatro funciones básicas y semantic cache; el prefix-aware y la versión enterprise añaden multi-tenancy avanzado.

vLLM Production Stack router es la opción correcta si la flota es 100 % vLLM. Aware del KV cache, del prefix, del LoRA loaded por réplica. Integra mejor con métricas vLLM nativas.

NVIDIA Dynamo router es la opción production-grade más completa, especialmente si se opera disaggregated serving (prefill workers vs decode workers separados). Requiere stack NVIDIA-aligned.

Envoy AI Gateway y Kong AI Gateway son las opciones si la organización ya tiene Envoy/Kong como gateway corporativo y quiere extenderlo con LLM-awareness sin introducir otra pieza nueva.

Manifest mínimo: LiteLLM Proxy sobre cluster genérico

apiVersion: v1
kind: ConfigMap
metadata: { name: litellm-config, namespace: inference }
data:
 config.yaml: |
 model_list:
 - model_name: llama-70b
 litellm_params:
 model: openai/llama-70b
 api_base: http://vllm-llama70b-v1.inference.svc:8000/v1
 weight: 95
 model_info:
 version: v1
 lifecycle: stable
 - model_name: llama-70b
 litellm_params:
 model: openai/llama-70b
 api_base: http://vllm-llama70b-v2.inference.svc:8000/v1
 weight: 5
 model_info:
 version: v2
 lifecycle: canary
 - model_name: embedding-multilingual
 litellm_params:
 model: openai/bge-m3
 api_base: http://tei-bge-m3.inference.svc:8080
 router_settings:
 routing_strategy: least-busy # token-aware basic
 num_retries: 1
 timeout: 60
 general_settings:
 master_key: "os.environ/LITELLM_MASTER_KEY"
 database_url: "os.environ/DATABASE_URL"
 litellm_settings:
 cache: true
 cache_params:
 type: redis
 host: redis.inference.svc
 port: 6379
 similarity_threshold: 0.97
 success_callback: ["langfuse"]
 failure_callback: ["langfuse"]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: litellm-router, namespace: inference }
spec:
 replicas: 3
 selector: { matchLabels: { app: litellm } }
 template:
 metadata: { labels: { app: litellm } }
 spec:
 containers:
 - name: litellm
 image: ghcr.io/berriai/litellm:v1.55.0
 args: ["--config=/config/config.yaml", "--port=4000", "--num_workers=4"]
 ports: [{ containerPort: 4000, name: http }, { containerPort: 4000, name: metrics }]
 env:
 - { name: LITELLM_MASTER_KEY, valueFrom: { secretKeyRef: { name: litellm-secret, key: master_key } } }
 - { name: DATABASE_URL, valueFrom: { secretKeyRef: { name: litellm-secret, key: db_url } } }
 - { name: LANGFUSE_PUBLIC_KEY, valueFrom: { secretKeyRef: { name: langfuse-keys, key: public } } }
 - { name: LANGFUSE_SECRET_KEY, valueFrom: { secretKeyRef: { name: langfuse-keys, key: secret } } }
 volumeMounts: [{ name: config, mountPath: /config }]
 readinessProbe: { httpGet: { path: /health, port: 4000 } }
 volumes: [{ name: config, configMap: { name: litellm-config } }]
---
apiVersion: v1
kind: Service
metadata: { name: litellm-router, namespace: inference }
spec:
 selector: { app: litellm }
 ports: [{ name: http, port: 80, targetPort: 4000 }]
---
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata: { name: litellm-metrics, namespace: inference }
spec:
 selector: { matchLabels: { app: litellm } }
 podMetricsEndpoints:
 - port: metrics
 path: /metrics
 interval: 15s

El cliente final apunta a litellm-router.inference.svc:80/v1/chat/completions, pone model=llama-70b, y el router decide en cada request si va a v1 (95 %) o v2 (5 %), aplica el rate limit, busca en semantic cache, propaga tracing a Langfuse, y traduce de OpenAI-compatible a OpenAI-compatible del vLLM de destino. Tres réplicas del router para HA y para que el propio gateway escale horizontalmente con KEDA si hace falta —ver Autoscaling LLM en Kubernetes—.

Cuatro pitfalls operacionales

Pitfall 1 — el router se convierte en SPoF si no se replica. Tres o más réplicas del propio router, detrás de un Service LoadBalancer (este sí, L4) con healthchecks. Una sola réplica del router significa que cada deploy de la configuración cierra el servicio entero unos segundos.

Pitfall 2 — la latencia del router se suma a la del modelo. Cada función añade milisegundos: parsing del body (5–10 ms), auth JWT (2–5 ms), rate limit (1–2 ms), redact PII con Presidio (20–80 ms), guardrails con Llama Guard inline (50–150 ms), prefix hash (5–10 ms), token counting con tokenizer (10–30 ms). En total 100–300 ms de overhead antes de tocar el motor. Si el TTFT del modelo es 400 ms y el del router 200 ms, el cliente ve 600 ms — vale la pena medir cuánto cuesta cada función y desactivar las no críticas en el path de baja latencia.

Pitfall 3 — el catálogo deriva del estado real del cluster. El router cree que vllm-llama70b-v2 existe porque está en su YAML, pero el deployment fue retirado hace tres días y nadie actualizó el config. El router devuelve 502 en el 5 % del tráfico. Solución: validar el catálogo contra kubectl get svc en CI; ningún endpoint del catálogo puede apuntar a un Service inexistente. O mejor: el router descubre dinámicamente los endpoints disponibles vía label selector (app=vllm,model=llama-70b) y aplica weights del catálogo sobre los que están vivos.

Pitfall 4 — semantic cache con embedding outdated. El semantic cache compara embedding del prompt nuevo contra embeddings de prompts cacheados. Si actualizas el modelo de embeddings (ver RAG corpus curation), las distancias se calculan en un espacio distinto y el cache deja de funcionar correctamente (falsos hits o falsos misses). Política: el cache se invalida al cambiar el modelo de embeddings; nunca se mezclan generaciones.

Encaje en el stack y la madurez

En el stack de siete capas, el router es la capa 1: la puerta de entrada que precede al motor de inferencia (capa 2), al KV cache + PagedAttention (capa 3) y al resto. Es la única pieza que ve todo el tráfico desde fuera; cualquier política que no se aplique aquí, se duplica N veces en los motores.

En los cinco niveles de madurez, el router aparece a partir del nivel 3 (GESTIONADO): sin OIDC + RBAC + cert-manager + NetworkPolicy default deny, el router no tiene a quien autenticar ni a quien aplicar quotas; antes del nivel 3 lo que toca es montar un proxy mínimo sin pretensión de catálogo. Plataformas que intentan tener router pulido en nivel 1 acaban con un yaml grande que nadie mantiene.

En las siete fases de despliegue, el router es lo que cierra F6: el último paso atómico que pone al cluster en producción. Sin router, F6 no termina — el catálogo, las quotas, los canaries y los failovers son condición necesaria para abrir tráfico productivo.

Aplicado a hardware on-premise típico

Para un cluster genérico de 4 nodos × 4×H100 SXM 80 GB, el router de inferencia consume recursos modestos: 3 réplicas del router-pod (CPU 2 cores, memoria 4 GiB cada una) bastan para soportar miles de RPS porque su trabajo es ligero (parsing, hashing, routing, no inferencia). El router vive en nodos no-GPU del cluster (nodos de control plane o de workload general), nunca consume nvidia.com/gpu.

Volumen de tráfico que un LiteLLM con 3 réplicas y 4 workers cada una sostiene: 2 000–5 000 RPS routing a backend vLLM, con overhead de 80–150 ms en path completo (auth + rate limit + cache check + propagación). Si se necesita más, escalar el router con KEDA sobre litellm:requests_per_second es trivial.

Para clusters más grandes (16+ nodos GPU), considerar vLLM Production Stack router o NVIDIA Dynamo router que son más complejos pero exprimen el prefix-aware routing y el token-aware LB que LiteLLM OSS no cubre. Para clusters multi-region, Envoy AI Gateway con Istio Service Mesh es la elección estándar.

Lo que no hemos cubierto (próximos artículos)

Comparativa profunda LiteLLM vs vLLM PStack vs Dynamo con benchmarks de prefix-aware sobre cluster on-premise real.
Semantic cache con Redis Stack + RedisVL: hit rate, falsos positivos, política de TTL.
Multi-region routing: cómo el router decide entre clúster DC1 y DC2 según latencia, salud y carga.
AI Gateway specific features: token-bucket cost-based rate limiting (penaliza prompts largos), guardrails policy engine en el router.
Migration path: cómo introducir un router en un cluster que ya tiene clientes apuntando directo al servicio vLLM, sin downtime.

Ver también

Canary, blue-green y shadow para modelos LLM — el post anterior donde llamamos “LoadBalancer” a esta pieza; este post la nombra y la desmonta.
Siete capas del stack de inferencia LLM on-premise — el router es la capa 1 del stack.
Cinco niveles de madurez — el router aparece a partir del nivel 3.
Siete fases de despliegue — el router es lo que cierra F6.
Autoscaling LLM en Kubernetes — el router puede escalar con KEDA sobre sus propias métricas; convive con el autoscaling de los motores.
Observabilidad GPU para inferencia LLM — el token-aware LB consume vllm:num_requests_running y vllm:gpu_cache_usage_perc para decidir réplica.
KV cache — qué cachea el prefix-aware routing y por qué multiplica el hit rate.
Disaggregated serving prefill/decode — los routers production-grade (Dynamo) son aware de la disaggregation y rutean prefill y decode a pools distintos.
Tracing LLM con OpenTelemetry GenAI — el router emite los spans padre gen_ai.* y propaga traceparent a los motores.
Guardrails y safety en LLMs — los guardrails ligeros inline se ejecutan típicamente en el router.
Entornos mixtos NVIDIA + Intel para inferencia LLM — el router por capability cobra todo su sentido cuando hay backends heterogéneos (NVIDIA para LLM grande, Intel para embeddings/reranker, NUC para edge); el catálogo se extiende con backend y region.
Elegir la centralita: qué gateway OSS poner por delante — el companion de decisión: este post explica qué es un router; aquel elige cuál con licencias verificadas (LiteLLM, Envoy AI Gateway + Inference Extension, Higress, APISIX, Kong) y una recomendación para stack RKE2 + vLLM K8s-native.

Referencias

LiteLLM project — litellm.ai (documentación de Proxy, routing strategies, semantic cache).
vLLM Production Stack — github.com/vllm-project/production-stack (router con prefix-aware nativo).
NVIDIA Dynamo — developer.nvidia.com/blog/nvidia-dynamo-1-production-ready/ (router production-grade con disaggregated-aware).
Envoy AI Gateway — gateway.envoyproxy.io/docs/tasks/ai-gateway/ (proyecto en gestación dentro de Envoy).
Kong AI Gateway — konghq.com/products/kong-ai-gateway (proxy enterprise con plugin LLM).
KGateway — kgateway.dev (alternativa CNCF en gestación).
Zheng et al. — SGLang: Efficient Execution of Structured Language Model Programs (NeurIPS 2024) — RadixAttention y prefix caching.
vLLM project — Automatic Prefix Caching (docs.vllm.ai/en/latest/features/automatic_prefix_caching.html).
Patel et al. — SplitWise: Efficient Generative LLM Inference Using Phase Splitting (ISCA 2024) — base teórica del routing prefill/decode aware.

Canary, blue-green y shadow para modelos LLM: cómo desplegar una versión nueva sin tirar el SLO

Mon, 01 Jun 2026 16:30:00 +0200

Este post complementa los de Autoscaling LLM en Kubernetes (el autoscaler convive con el rollout y debe respetarlo), Observabilidad GPU para inferencia LLM (las métricas que actúan como gate vienen de ahí), Evals para LLMs (la eval que decide si el nuevo modelo está listo), LLM-as-judge (la técnica que pone el “quality” en el gate de canary) y Retrain: cerrar el bucle (el step previo del que sale el modelo nuevo).

TL;DR

Promocionar una versión nueva de un modelo LLM al cluster productivo sin cortar tráfico ni romper SLO exige despliegue progresivo. Las tres estrategias canónicas —blue-green, canary, shadow— responden a preguntas distintas y tienen costes distintos. Blue-green: pool completo nuevo levantado en paralelo, conmutación atómica del load balancer. Rollback instantáneo (volver a apuntar al pool viejo); exige el doble de GPUs durante la ventana. Canary: el tráfico se reparte progresivamente entre la versión vieja y la nueva (1 % → 5 % → 25 % → 100 %), midiendo en cada salto gates de regresión; consume incrementalmente menos hardware pero expone usuarios reales al modelo nuevo desde el primer porcentaje. Shadow / mirror: el viejo modelo sirve el 100 % del tráfico real al cliente y, en paralelo, una copia de cada request va al nuevo modelo sin devolver su respuesta al usuario; aísla del riesgo de calidad pero gasta GPU del nuevo en respuestas que nadie consume, y no funciona bien con streaming SSE largo. La elección depende de tres factores: presupuesto GPU disponible, criticidad del servicio y disponibilidad de eval automática rápida. Las cinco métricas de regresión que cualquier canary LLM gatear son: TTFT P95, error rate (HTTP 5xx + finish_reason="length" prematuro), quality score con LLM-as-judge sobre golden set, drift estadístico de embeddings de output (Wasserstein o KL contra distribución del baseline) y coste por request (tokens/s y kW/request). En Kubernetes, Argo Rollouts gestiona el tráfico y los AnalysisTemplate como gates automáticos; Flagger es la alternativa más opinionada. vLLM v1 no soporta hot model swap robusto a mayo 2026, así que la unidad de rollout es la réplica entera (deployment v2 al lado de deployment v1). Los tres pitfalls específicos: sticky sessions del LB rompen la comparabilidad estadística del canary (un cliente A siempre cae al nuevo, B al viejo — las poblaciones no son equivalentes); eval semántica con LLM-as-judge tarda 2–8 segundos por sample y no sirve como gate en tiempo real (se usa en post-análisis o offline pre-promoción); el streaming SSE complica el shadow porque hay que descartar la respuesta del nuevo modelo sin afectar a la del viejo. Este post incluye un manifest Argo Rollouts mínimo aplicable a un cluster genérico con NVIDIA GPU Operator.

Estás aquí: DEPLOY (y la transición a RETRAIN)

Un modelo nuevo no aparece por arte de magia en el cluster: viene del bucle de retrain o de una actualización del proveedor de pesos. El paso entre “tengo un artefacto que pasó eval offline” y “está sirviendo el 100 % del tráfico” es exactamente este post.

La analogía: el estreno de una obra en teatro

Una compañía de teatro va a estrenar una nueva versión de una obra que lleva un año en cartel con éxito. La compañía sabe varias cosas duras: el público actual paga por una experiencia consistente; un mal estreno daña el negocio durante meses; pero no estrenar nada deja a la compañía obsoleta frente a la competencia.

Las tres rutas de estreno que la dirección puede elegir son las mismas tres del rollout LLM.

Ensayo general a puerta cerrada (shadow / mirror). Los actores nuevos representan la obra entera ante un teatro vacío. No hay público; nadie compra entrada. Tres pases enteros sirven para comprobar continuidad, tiempos y química del reparto. Es caro porque hay sueldos y alquiler del teatro, pero no expone al público al riesgo. Útil cuando el reparto nuevo está sin probar y el director quiere ver cómo aguanta una función completa antes de venderla. En LLM: el modelo nuevo procesa cada request real en paralelo al viejo pero sus respuestas se descartan; gastas GPU del nuevo en respuestas que nadie ve.

Reparto por funciones, alternando (canary). En lugar de cambiar todo el reparto de golpe, las funciones de jueves son del reparto nuevo, las del viernes del viejo, las de sábado mitad y mitad. La dirección lee los comentarios del libro de visitas y la afluencia de público función a función, decidiendo al cabo de dos semanas si promociona el reparto nuevo a titular o lo retira. Más barato que el ensayo general porque las funciones venden entrada igual, pero expone público real al riesgo desde el primer jueves. En LLM: el tráfico se reparte progresivamente entre la versión vieja y la nueva, midiendo gates en cada salto.

Doble compañía con cambio atómico (blue-green). La compañía contrata el reparto nuevo, lo prepara durante un mes a puerta cerrada, y un sábado anuncia: “a partir del próximo estreno todas las funciones son con el reparto nuevo”. Si la primera función va mal, se vuelve al reparto viejo en 24 horas — pero durante ese mes de preparación se paga doble sueldo a las dos compañías. En LLM: dos pools completos del mismo tamaño, conmutación instantánea del LB de uno a otro, rollback en segundos si las métricas se rompen.

La analogía sostiene también la decisión: la elección depende de cuán crítica sea la obra para el negocio (criticidad del servicio LLM), cuánto presupuesto hay para sostener dos repartos a la vez (presupuesto GPU), y cuánta confianza se tiene en el nuevo reparto a partir de los ensayos de cámara (eval offline previa al canary).

Las tres estrategias en detalle

Blue-green

El operador mantiene dos pools de réplicas idénticos en tamaño: el azul (versión productiva v1) y el verde (versión candidata v2). Cuando v2 está validado offline (eval pasada, smoke tests), el switch del LoadBalancer redirige el 100 % del tráfico de azul a verde en un solo paso. Si las métricas del SLO se rompen, el switch vuelve atrás en segundos.

Coste: 2× GPUs durante toda la ventana (preparación de v2 + ventana de observación post-switch). Para un cluster de 16 GPUs sirviendo Llama 70B con TP=4 (4 réplicas), preparar el blue-green requiere 16 GPUs adicionales durante 1–3 días.

Riesgo: el switch es atómico — si v2 tiene un problema que no apareció en eval offline pero sí aparece a escala (por ejemplo, edge cases que solo se ven a 200 RPS), el 100 % de usuarios lo nota a la vez. El rollback es instantáneo, pero las requests del primer minuto post-switch ya se vieron afectadas. Por tanto blue-green es preferible cuando se tiene alta confianza en v2 (cambio menor: misma arquitectura, mismo formato, solo nueva versión de pesos) y se prioriza rollback inmediato sobre exposición gradual.

Canary

El operador despliega v2 con un número pequeño de réplicas (típicamente 1) junto al pool de v1. El LoadBalancer reparte progresivamente el tráfico siguiendo un cronograma: 1 % durante 30 minutos → 5 % durante 1 hora → 25 % durante 2 horas → 50 % durante 4 horas → 100 %. Entre cada salto, un gate de análisis evalúa métricas de regresión sobre el tráfico que ya está cayendo en v2. Si el gate falla, el rollback retira el tráfico de v2 automáticamente y deja v1 sirviendo todo.

Coste: incremental. Al inicio (1 % de tráfico) basta una réplica v2; al 50 % se necesita la mitad de réplicas v2 que el total de v1. Pico de GPU adicional durante el canary: ~30–50 % por encima del baseline.

Riesgo: usuarios reales están viendo v2 desde el primer 1 %. Si v2 produce respuestas con calidad degradada pero TTFT y error rate normales, los usuarios afectados perciben la degradación sin que el gate la detecte (a menos que el gate incluya quality drift, que tarda). Por tanto canary es preferible cuando se tiene confianza media en v2 (cambio significativo: arquitectura o entrenamiento distinto) y se acepta que un % bajo de usuarios sea conejillo.

Shadow / mirror

El LoadBalancer envía el 100 % del tráfico real a v1 (que responde al cliente) y duplica cada request hacia v2 (cuya respuesta se descarta o se guarda para análisis offline). El cliente nunca ve v2; nunca está expuesto al riesgo.

Coste: 100 % adicional del compute de v2 sin valor de usuario directo durante toda la ventana de shadow. Para un cluster de 16 GPUs sirviendo Llama 70B con TP=4 (4 réplicas), un shadow del mismo tamaño consume 16 GPUs adicionales a tiempo completo.

Riesgo: el shadow es el más seguro para el usuario. Pero tiene dos limitaciones serias: (a) si v2 tiene un cuello de botella que causa que la copia de request al shadow tarde mucho, el proxy de shadowing puede consumir conexiones del LB; debe estar out-of-band (asíncrono); (b) el streaming SSE largo complica la mirroring porque hay que mantener dos streams paralelos y descartar uno mientras el otro fluye al cliente. Patrón habitual: shadow solo de requests no-streaming (completiones cortas, classification), eval offline manual de las requests con streaming.

Las cinco métricas de regresión que actúan como gate

Sin gates automáticos, el “canary” es solo un nombre bonito para “rollout manual con un porcentaje variable”. Los gates son la pieza que convierte el canary en una operación defendible.

Métrica 1 — TTFT P95. Comparación P95 del nuevo modelo contra P95 del baseline (v1) en ventanas de 5 minutos. Gate: ttft_p95(v2) / ttft_p95(v1) < 1.10. Detecta regresiones de latencia de prefill (modelo nuevo más lento) o problemas de motor (config subóptima). Fuente: vllm:time_to_first_token_seconds_bucket —ver Observabilidad GPU para inferencia LLM—.

Métrica 2 — Error rate. Suma de HTTP 5xx + 4xx no esperados + tasa de finish_reason="length" prematuro (respuestas cortadas porque el modelo nuevo no genera EOS). Gate: error_rate(v2) - error_rate(v1) < 0.01 (1 punto porcentual). Detecta crashes del motor, tokenizer roto, problemas de generación. Fuente: vllm:request_success_total{status=...}.

Métrica 3 — Quality score (LLM-as-judge). Sobre un golden set de 200–1 000 prompts representativos, se ejecutan v1 y v2 offline y un modelo juez (típicamente más grande: GPT-4 class, Claude, Llama 405B local) puntúa cada par. Gate típico: mean_score(v2) >= mean_score(v1) - 0.05. Esta métrica no se mide en tiempo real durante el canary — la inferencia del juez tarda 2–8 segundos por sample y no escala como gate inline. Se usa como gate offline pre-promoción (antes de empezar el canary) y como post-mortem sobre muestra de tráfico real capturado durante el canary. Ver LLM-as-judge para la mecánica.

Métrica 4 — Drift estadístico de output. Para cada request que cae en v2 durante el canary, embeber la respuesta con un modelo de embedding ligero (e5, BGE) y comparar la distribución de embeddings de v2 contra la distribución del baseline v1 sobre la misma ventana. Métricas usables: Wasserstein distance, divergencia KL, o más simple, comparar medias y varianzas por dimensión. Gate: distancia normalizada < umbral calibrado (típicamente Wasserstein < 0.15). Detecta cambios sutiles en estilo, longitud, vocabulario que LLM-as-judge no captura sin pasar también por él. Es rápida: el embedding ligero tarda ~50 ms por respuesta.

Métrica 5 — Coste por request. Tokens out / request y kW / request. Gate: cost_per_request(v2) / cost_per_request(v1) < 1.20. Detecta modelos nuevos que generan respuestas significativamente más largas o que consumen más energía por la misma carga (degradación de quantization, fallo de optimizations). Sin este gate, una “actualización” puede duplicar la factura silenciosamente.

Métrica	Tipo	Latencia de medida	Gate típico	Detección
TTFT P95	Cuantitativa	5 min	`< 110% baseline`	Regresión de latencia
Error rate	Cuantitativa	1 min	`< 1pp sobre baseline`	Crashes, generation broken
Quality (LLM-judge)	Semántica offline	horas, sobre golden	`> baseline − 0.05`	Calidad funcional
Drift estadístico	Estadística	~5 min	Wasserstein < 0.15	Estilo, longitud, vocabulario
Coste por request	Cuantitativa	5 min	`< 120% baseline`	Eficiencia económica/energética

La mecánica en Kubernetes: Argo Rollouts

Argo Rollouts extiende el Deployment estándar de Kubernetes con un nuevo recurso Rollout que orquesta la progresión del tráfico y los análisis automáticos. Se integra con cualquier service mesh (Istio, Linkerd) o controlador de ingress que soporte traffic splitting (NGINX, Traefik, Gateway API).

Ejemplo mínimo de canary 1 → 5 → 25 → 100 % con gates de TTFT y error rate:

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata: { name: vllm-llama70b }
spec:
 replicas: 4
 strategy:
 canary:
 canaryService: vllm-llama70b-canary
 stableService: vllm-llama70b-stable
 trafficRouting:
 nginx:
 stableIngress: vllm-llama70b-ingress
 steps:
 - setWeight: 1
 - pause: { duration: 30m }
 - analysis: { templates: [{ templateName: ttft-error-gate }] }
 - setWeight: 5
 - pause: { duration: 1h }
 - analysis: { templates: [{ templateName: ttft-error-gate }] }
 - setWeight: 25
 - pause: { duration: 2h }
 - analysis: { templates: [{ templateName: ttft-error-gate }, { templateName: drift-gate }] }
 - setWeight: 50
 - pause: { duration: 4h }
 - analysis: { templates: [{ templateName: ttft-error-gate }, { templateName: drift-gate }] }
 - setWeight: 100
 selector: { matchLabels: { app: vllm-llama70b } }
 template:
 metadata: { labels: { app: vllm-llama70b } }
 spec:
 containers:
 - name: vllm
 image: vllm/vllm-openai:v0.10.0
 args: [ --model=/models/llama-70b-fp8-v2 ]  # versión nueva
---
apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata: { name: ttft-error-gate }
spec:
 metrics:
 - name: ttft-p95-ratio
 interval: 1m
 count: 5
 failureLimit: 1
 successCondition: result < 1.10
 provider:
 prometheus:
 address: http://prometheus.observability.svc:9090
 query: |
 histogram_quantile(0.95, sum by(le)(rate(vllm:time_to_first_token_seconds_bucket{version="v2"}[5m])))
 /
 histogram_quantile(0.95, sum by(le)(rate(vllm:time_to_first_token_seconds_bucket{version="v1"}[5m])))
 - name: error-rate-diff
 interval: 1m
 count: 5
 failureLimit: 1
 successCondition: result < 0.01
 provider:
 prometheus:
 address: http://prometheus.observability.svc:9090
 query: |
 sum(rate(vllm:request_total{version="v2",status=~"5.."}[5m])) / sum(rate(vllm:request_total{version="v2"}[5m]))
 -
 sum(rate(vllm:request_total{version="v1",status=~"5.."}[5m])) / sum(rate(vllm:request_total{version="v1"}[5m]))

Si cualquiera de los AnalysisTemplate falla, Argo Rollouts retrocede automáticamente: pone weight=0 en el canary, alerta al operador, mantiene v1 sirviendo el 100 %. La operación humana se reduce a investigar el fallo y decidir si re-lanzar o abortar.

Flagger ofrece una alternativa más opinionada: la progresión del weight es automática en función del éxito de las métricas en vez de pausa fija; el operador define un objetivo (maxWeight: 100, stepWeight: 10, metrics: [...]) y Flagger sube o baja según comportamiento. Ambas son maduras en mayo 2026; la elección suele venir dictada por qué service mesh ya está en el cluster.

El detalle de vLLM: por qué no se hace “hot swap” del modelo

A mayo 2026, vLLM v1 no soporta cambio caliente del modelo dentro de la misma réplica sin reiniciar el motor. El comando --model se evalúa al arranque; cambiarlo requiere re-instanciar el LLMEngine, lo que reinicia conexiones y descarta el KV cache. Por tanto la unidad de rollout es la réplica entera: no se hace “v1 carga el modelo nuevo en una de sus GPUs” sino “se levanta una réplica v2 al lado de una réplica v1 y se reparte tráfico vía LB”.

TensorRT-LLM con Triton tiene un mecanismo similar: cambiar el modelo exige reload del backend Triton. SGLang tampoco soporta hot swap robusto. La consecuencia operativa: el rollout LLM siempre va a costar GPUs adicionales durante la ventana, y la elección entre blue-green, canary y shadow es exactamente la pregunta de cuántas adicionales y cuánto tiempo.

Los tres pitfalls específicos del rollout LLM

Pitfall 1 — sticky sessions rompen la comparabilidad del canary. Si el LoadBalancer hace session affinity por IP del cliente (común en NGINX, Traefik con loadbalancer.kubernetes.io/session-affinity: ClientIP), un usuario A siempre cae en v2 mientras B siempre cae en v1. Las distribuciones de carga, perfiles de prompt y comportamiento de cliente no son aleatorias entre los dos pools, lo que invalida estadísticamente cualquier comparación de gates. Solución: para canary, desactivar session affinity (sessionAffinity: None) o usar affinity por request-id aleatorio. Si la app cliente exige sticky por funcionalidad (memoria conversacional persistida en cache), el canary no es la estrategia adecuada — usar blue-green o shadow.

Pitfall 2 — LLM-as-judge no es gate inline en tiempo real. La tentación de usar quality score como gate live es alta, pero la latencia del juez (2–8 s por sample) hace inviable evaluar más que un sampling del 1–2 % del tráfico, y los resultados llegan con minutos de retraso. Soluciones operativas: (a) eval offline pre-canary sobre golden set como pre-requisito para arrancar (si falla, ni se inicia el canary); (b) durante el canary, capturar requests + responses de v2 a tiempo real y correr el juez asíncrono en un job batch que termina antes del siguiente salto; (c) usar drift estadístico de embeddings como proxy rápido de calidad inline, y reservar el juez para gates intermedios entre saltos.

Pitfall 3 — streaming SSE complica el shadow. El mirror de tráfico clásico (NGINX mirror, Istio MirrorPolicy) está pensado para HTTP de request/response — copia la request, deja al servidor primario responder al cliente, y duplica la request al secundario descartando la respuesta. Con SSE, la respuesta del secundario es un stream continuo de varios segundos, y mantener dos streams en paralelo carga doblemente al proxy. Soluciones: (a) shadow solo de requests no-streaming (chat sin stream, embeddings, classification, batch eval), (b) shadow del tráfico streaming pero con timeout corto en el secundario (descartar el shadow si tarda más de 30 s), (c) reemplazar el shadow por canary con weight pequeño (1 %) que sí soporta streaming bien.

Aplicado a hardware on-premise típico

Para un cluster genérico de 4 nodos × 4×H100 SXM 80 GB = 16 GPUs, sirviendo Llama 70B FP8 con TP=4 (4 réplicas posibles, una por nodo):

Blue-green: imposible mantener dos pools completos de 4 réplicas sin GPUs adicionales. Solución práctica: blue-green con pools reducidos (2 réplicas v1 + 2 réplicas v2) durante la ventana, degradación de capacidad aceptada (mitad del SLO de RPS sostenido), o disponer de un cluster paralelo (otro nodo) reservado para rollouts.
Canary: factible. Empezar con 3 réplicas v1 + 1 réplica v2 (25 % weight nominal pero también peso variable de tráfico). Avanzar a 2 v1 + 2 v2 al 50 %, luego 1 v1 + 3 v2, finalmente 0 v1 + 4 v2.
Shadow: complicado por el coste de GPU. Reservar para validación pre-canary de cambios mayores, durante una ventana corta (4–8 horas) con tráfico shadowed limitado a una muestra (10–20 % de requests, no 100 %).

Para clusters de 8 nodos GPU, los tres patrones son sostenibles. La regla operativa: el presupuesto de rollout es típicamente el 25–30 % de la capacidad sostenida del cluster — comprar para el pico + ese head-room cuadra los números del capacity planning.

Lo que no hemos cubierto (próximos artículos)

Rollouts multi-region: cómo coordinar canary cuando el cluster está distribuido geográficamente.
A/B testing de prompts (no de modelos): el mismo modelo con dos system prompts distintos, medir conversion.
Rollback de embeddings: cambiar el modelo de embeddings de un sistema RAG implica re-embedir todo el corpus — la mecánica de canary es distinta. Ver RAG corpus curation.
Feature flags para LLM: granularidad por tenant o por feature dentro del mismo modelo.
Continuous deployment end-to-end: integración con el retrain pipeline para que un nuevo adapter se promocione automáticamente tras pasar evals.

Ver también

Autoscaling LLM en Kubernetes — el autoscaler convive con el canary y debe respetar las particiones de tráfico.
Observabilidad GPU para inferencia LLM — las métricas que actúan como gate vienen de aquí.
Capacity planning — define el head-room necesario para rollouts.
Evals para LLMs — la eval offline que valida v2 antes de empezar el canary.
LLM-as-judge — la técnica de quality score como gate offline.
Retrain: cerrar el bucle — de donde sale el modelo nuevo que entra al canary.
Cinco niveles de madurez — Argo Rollouts es pieza del nivel 4–5.
El router de inferencia LLM — la pieza que en este post llamamos “LoadBalancer” desmontada como capa de pleno derecho: catálogo de modelos, traffic splitting L7, política transversal, failover y prefix-aware routing. El reparto 1 % → 5 % → 25 % → 100 % se materializa allí.
Runbooks de incident response para LLM con Keep + Kafka — el rollback automático del canary cuando ttft_p95(v2)/ttft_p95(v1) > 1.30 es el runbook RB-06; allí está el workflow Keep YAML completo y el encaje en compliance.

Referencias

Argo Rollouts project — argoproj.io/argo-rollouts (CRD Rollout y AnalysisTemplate).
Flagger project — fluxcd.io/flagger (alternativa con progresión automática).
Istio — Traffic Mirroring (mirror configurable a nivel VirtualService).
NGINX Ingress — Canary annotations (nginx.ingress.kubernetes.io/canary-*).
vLLM project — issue tracker sobre hot model swap (estado a mayo 2026: en diseño, no production-ready).
Hou et al. — DistServe: Disaggregating Prefill and Decoding for Goodput-optimized LLM Serving (OSDI 2024) — referencia sobre métricas de goodput aplicables a gates de canary.
Bürkner et al. — Statistical methods for detecting model drift in production (artículos varios sobre Wasserstein y KL en monitoring ML).

Autoscaling de inferencia LLM en Kubernetes: HPA con custom metrics y KEDA para vLLM

Mon, 01 Jun 2026 16:00:00 +0200

Este post complementa los de Observabilidad GPU para inferencia LLM (de donde vienen las métricas que alimentan al HPA), Capacity planning (qué techo y qué head-room presupone el autoscaler) y Continuous batching (lo que explica por qué num_requests_waiting es la métrica primaria).

TL;DR

El autoscaling clásico de Kubernetes —HPA sobre cpu o memory— no sirve para inferencia LLM. Razón: el pod vLLM consume poco CPU (el trabajo lo hace la GPU) y la memoria RSS del proceso es plana; ambas métricas pueden quedarse al 30 % mientras la GPU está saturada y la cola de requests crece sin freno. Las cuatro señales viables que sí responden a la carga real son: vllm:num_requests_waiting (la cola, la métrica primaria), vllm:gpu_cache_usage_perc (presión sobre el KV cache pool), TTFT P95 vía histogram de vllm:time_to_first_token_seconds_bucket (la garantía del SLO) y el batch fill ratio num_requests_running / max_num_seqs (utilización del techo de concurrencia). Para que un HPA pueda consumir métricas Prometheus hace falta un adaptador; en mayo 2026 hay dos opciones maduras: prometheus-adapter (sigma de cluster, configuración estática, output external.metrics.k8s.io) y KEDA (ScaledObject con trigger Prometheus, polling configurable, escalado a cero opcional, integración con cron). KEDA es la opción dominante para LLM en cluster genérico porque resuelve el patrón “warm pool + cron + métrica del motor” en un solo CRD. El reto operacional dominante no es la lógica de escalado sino el cold start: un pod vLLM con Llama 70B BF16 (140 GB) tarda entre 90 segundos (modelo precacheado en PV local) y 6 minutos (image pull + descarga del modelo desde object store) hasta servir el primer token. Las cinco palancas que lo recortan son imagen pre-pulled vía DaemonSet, modelo cacheado en PV o tmpfs regional, warm pool con minReplicaCount > 0, predictive scaling vía KEDA cron cuando el patrón de tráfico es predecible (oficinas 9–18 h), y descarga paralela del modelo. Los tres pitfalls específicos del scale-down LLM: cortar conexiones SSE de streaming a media respuesta (drain elegante con terminationGracePeriodSeconds ≥ 60 s), oscilación de scale-out/in por stabilization window mal calibrada, y olvidar que el HPA solo escala pods — los nodos GPU se escalan con cluster-autoscaler sobre nodepools etiquetados. Este post incluye los manifests YAML mínimos.

Estás aquí: DEPLOY

La analogía: la panadería con hornos de leña

Una panadería artesanal tiene tres hornos de leña. Cada horno tarda 25 minutos en alcanzar temperatura desde frío. Una vez caliente, hornea pan continuamente con una tirada de 18 minutos por hornada. La encargada quiere maximizar pan vendido por día sin gastar leña inútil, y sabe tres cosas: que hay un pico de demanda a las 7:30 cada mañana, que los lunes no se vende casi nada, y que cuando se acaba el pan en mostrador los clientes se van al supermercado de al lado.

La estrategia barata —encender hornos cuando hay cola en la tienda— no funciona. Para cuando la cola crece y la encargada enciende el segundo horno, ese horno no estará listo hasta 25 minutos después; los clientes de esa ventana se perdieron. La señal “cola en mostrador” llega tarde.

La estrategia inteligente: encender el segundo horno a las 6:55, antes del pico previsible de las 7:30, y dejarlo activo hasta las 10:00 aunque la cola baje a las 8:15. Mantener el tercer horno apagado entre lunes y miércoles porque la demanda no llega; encenderlo proactivamente los jueves a las 12:00 porque históricamente sube. Tener una bolsa de masa cruda pre-fermentada en cámara para que cuando el horno esté listo, el pan entre en 30 segundos y no haya que esperar dos horas de fermentación.

El autoscaling de un cluster de inferencia LLM funciona igual:

Encender hornos en frío = scale-out reactivo cuando la cola crece (lento, pierde clientes).
Cron proactivo = predictive scaling cuando el patrón es conocido (horario laboral, picos previstos).
Masa pre-fermentada = warm pool de réplicas con modelo cargado pero a 0 carga.
Apagar hornos sin pan en curso = scale-down respetando las streamings activas (no se cierra el horno con pan dentro).

La métrica clave —“cuántos clientes hay en cola”— se llama num_requests_waiting. La métrica que dice “el horno se va a quedar sin masa para nuevos panes” se llama gpu_cache_usage_perc. Y la métrica de calidad de servicio —“cuánto tarda el primer pan en salir cuando un cliente nuevo entra”— se llama TTFT.

Por qué HPA sobre CPU no sirve

El HPA clásico de Kubernetes mira resource.cpu del pod. Para un servicio HTTP convencional —Node.js, una API REST— la CPU se mueve linealmente con el tráfico y el HPA escala con razonable acierto. Para un pod vLLM o SGLang sobre GPU, la CPU del pod típicamente vive entre 5 % y 15 % independientemente de si la GPU está al 30 % o al 99 % de carga: el trabajo real lo hace el dispositivo, no el proceso. Resultado: el HPA basado en CPU nunca dispara scale-out aunque la GPU esté reventando, y los clientes acumulan en la cola hasta que TTFT P95 cruza el SLO. El operador descubre el problema por la alerta de TTFT, no por el HPA.

memory tampoco sirve: la RSS del proceso vLLM es plana después del arranque (modelo + buffers cargados de una vez); no refleja la presión real sobre la GPU. Lo único que crece y baja con la carga útil de inferencia son métricas que el motor publica explícitamente: cola de requests, KV cache pool, latencias del SLO. Sin un adaptador que las haga visibles al HPA, el autoscaling es ciego.

Las cuatro señales viables

Señal 1 — vllm:num_requests_waiting (cola). Es la métrica más directa: cuántas requests esperan entrar al batch. Reacciona en el instante en que la concurrencia objetivo se satura. Es robusta frente a cambios de modelo (el número de requests es el mismo concepto sea Llama 7B o 70B). Es la métrica primaria del HPA LLM. Umbral típico: target = 5 requests waiting de media; si la cola crece por encima de 5 sostenido durante 2 minutos, scale-out.

Señal 2 — vllm:gpu_cache_usage_perc (KV pool). Se mueve antes que la cola: el KV pool se va llenando mientras los slots del batch aún están libres, hasta que el motor empieza a rechazar nuevas requests por OOM-prevention y se forma la cola. Por tanto es predictiva: dispara scale-out antes de que el cliente note degradación. Umbral típico: target = 0.85 (85 % de pool usado).

Señal 3 — TTFT P95. La garantía contractual. Si TTFT P95 sale del SLO, scale-out aunque cola y KV pool parezcan razonables (puede haber un pico de prompts largos). Es reactiva —sale del SLO antes de que tu HPA reaccione— pero sirve de guardrail final.

Señal 4 — batch fill ratio. El cociente num_requests_running / max_num_seqs (este último es config del motor, no métrica). Útil para scale-down: si el ratio queda por debajo de 0.4 durante 10 minutos, sobra capacidad y se puede reducir réplicas con seguridad.

La política recomendada combina las cuatro: la cola y el KV pool disparan scale-out (lo que llegue antes), TTFT lo confirma como guardrail, y el batch fill ratio gestiona scale-down. Implementarlo en un único HPA exige métricas externas; KEDA hace esto manejable.

El cableado: KEDA como adaptador Prometheus

KEDA introduce dos CRDs principales: TriggerAuthentication (cómo autenticarse contra la fuente) y ScaledObject (qué deployment escalar con qué triggers). Para un deployment vLLM con Prometheus como fuente:

apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
 name: vllm-llama70b-scaler
 namespace: inference
spec:
 scaleTargetRef:
 name: vllm-llama70b
 minReplicaCount: 2 # warm pool
 maxReplicaCount: 20
 pollingInterval: 15
 cooldownPeriod: 300 # 5 min antes de scale-down
 advanced:
 horizontalPodAutoscalerConfig:
 behavior:
 scaleDown:
 stabilizationWindowSeconds: 600 # ventana grande para evitar oscilación
 policies:
 - type: Pods
 value: 1
 periodSeconds: 120
 scaleUp:
 stabilizationWindowSeconds: 30
 policies:
 - type: Pods
 value: 2
 periodSeconds: 60
 triggers:
 - type: prometheus
 metadata:
 serverAddress: http://prometheus.observability.svc:9090
 metricName: vllm_queue_depth
 threshold: "5"
 query: |
 avg(vllm:num_requests_waiting{deployment="vllm-llama70b"})
 - type: prometheus
 metadata:
 serverAddress: http://prometheus.observability.svc:9090
 metricName: vllm_kv_cache
 threshold: "0.85"
 query: |
 avg(vllm:gpu_cache_usage_perc{deployment="vllm-llama70b"})
 - type: prometheus
 metadata:
 serverAddress: http://prometheus.observability.svc:9090
 metricName: vllm_ttft_p95
 threshold: "1.5"
 query: |
 histogram_quantile(0.95,
 sum by(le)(rate(vllm:time_to_first_token_seconds_bucket{deployment="vllm-llama70b"}[5m])))

Tres detalles operativos no obvios:

minReplicaCount: 2. Es el warm pool. Mantener al menos dos réplicas garantiza disponibilidad ante pérdida de un nodo y absorbe spikes sin esperar al cold start del primer escalado. Bajarlo a 0 ahorra GPU en off-peak pero introduce 90 s–6 min de latencia al primer cliente nuevo.

stabilizationWindowSeconds: 600 en scale-down. Diez minutos. Los modelos no son nginx: si una réplica se cierra prematuramente y a los dos minutos hay otro pico, el cold start de un nuevo pod tarda lo que el cliente espera. Mejor mantener réplicas extra el doble de lo que mantendrías para un servicio web normal.

scaleUp: stabilizationWindowSeconds: 30. Treinta segundos. El scale-out tiene que ser rápido — el cold start del nuevo pod añade su propio retraso, y si encima el HPA espera otros minutos antes de disparar, el SLO ya está roto.

El gran problema operativo: cold start

Un pod vLLM cargando Llama 70B pasa por estas fases antes de servir el primer token:

Fase	Tiempo típico	Acelerable con
Image pull (4–6 GB)	30–90 s	DaemonSet pre-pull
Descarga del modelo (140 GB BF16)	60–300 s	PV regional cacheado, S3 + multi-thread
Carga del modelo a HBM	30–90 s	tmpfs o NVMe local
Capture de CUDA graphs	20–60 s	`--enforce-eager` (más lento en runtime pero arranque rápido)
Warmup de PagedAttention	5–15 s	—
Health check ready	10–30 s	tuning de probe

Total sin optimización: 4–10 minutos. Una réplica nueva tarda eso en absorber tráfico. Con todas las palancas combinadas: 45–90 segundos. La diferencia entre los dos números es el principal trabajo de plataforma para autoscaling LLM.

Las cinco palancas

Palanca 1 — imagen pre-pulled. Un DaemonSet trivial corre ctr image pull (o crictl pull) sobre los nodos GPU en cuanto se incorporan al cluster. La imagen del motor de inferencia queda en disco; los nuevos pods saltan los 30–90 s de pull. Coste: ~6 GB de disco por nodo.

apiVersion: apps/v1
kind: DaemonSet
metadata: { name: vllm-image-warmer }
spec:
 selector: { matchLabels: { app: vllm-warmer } }
 template:
 metadata: { labels: { app: vllm-warmer } }
 spec:
 nodeSelector: { workload: gpu }
 initContainers:
 - name: pull
 image: vllm/vllm-openai:v0.10.0
 command: ["/bin/true"]
 containers:
 - name: pause
 image: registry.k8s.io/pause:3.10

Palanca 2 — modelo en PV regional. El download del modelo (140 GB BF16 o 35 GB FP8) desde object storage central es el componente dominante del cold start. Cachear el modelo en un PV de zona/rack —Rook-Ceph RBD, o NVMe local provisionado por el operador— recorta 60–300 s a 5–15 s. El antipatrón: descargar el modelo en cada arranque desde S3 externo.

volumeMounts:
 - name: model-cache
 mountPath: /models
 readOnly: true
volumes:
 - name: model-cache
 persistentVolumeClaim:
 claimName: llama70b-fp8-pvc  # RWX shared, llenado offline

Palanca 3 — warm pool. minReplicaCount > 0 mantiene réplicas pre-cargadas en idle. El coste es GPU ociosa; el beneficio es 0 s de cold start para el primer cliente de un pico. Para clusters productivos con tráfico continuo: warm pool de 2–3 réplicas. Para clusters batch nocturnos con tráfico 0: warm pool 0 y aceptar el cold start, o KEDA con cron que pre-encienda 10 minutos antes.

Palanca 4 — predictive scaling con cron. Cuando el patrón es predecible (oficinas 9–18 h):

triggers:
 - type: cron
 metadata:
 timezone: Europe/Madrid
 start: "30 8 * * 1-5" # 8:30 lunes–viernes
 end: "0 19 * * 1-5" # 19:00
 desiredReplicas: "6"

Combinado con triggers reactivos. El HPA escala según el máximo de las señales: si la cron pide 6 y la cola pide 10, el resultado es 10.

Palanca 5 — descarga paralela y formato eficiente. Para PVs no pre-cargados, herramientas como nvidia-modelmanager, s5cmd o aria2c paralelizan la descarga del modelo. Pasar de descarga serial (~150 MB/s) a paralela 8 threads (~1.2 GB/s) divide entre 8 el tiempo. Y formatos como safetensors se cargan en HBM más rápido que PyTorch pickle original.

Cuándo escalar nodos, no solo pods

El HPA escala pods. Si el cluster no tiene nodos GPU libres, el nuevo pod se queda en Pending por falta de recursos. Para escalar nodos, hace falta cluster-autoscaler con un nodepool GPU específico, etiquetado:

# nodepool config (Karpenter o cluster-autoscaler equivalent)
labels:
 workload: gpu
 gpu-model: h100-sxm-80gb
taints:
 - key: nvidia.com/gpu
 effect: NoSchedule
limits:
 min: 2 nodes
 max: 8 nodes

Sin esto, el HPA puede pedir 10 réplicas pero el cluster solo entrega las que caben en nodos ya levantados. El cold start de un nodo nuevo (provisioning bare metal o cloud, PXE, OS boot, drivers NVIDIA, join del cluster) es mucho mayor que el cold start de un pod: típicamente 5–15 minutos en bare metal preconfigurado, 30–60 minutos en provisioning real. Para clusters on-premise, el nodepool debe estar siempre dimensionado al máximo previsto, y el “scaling” es solo del lado de pods. El concepto de scale-out reactivo de nodos solo aplica a clouds; en on-premise hay que comprar para el pico.

Tres pitfalls específicos del scale-down LLM

Pitfall 1 — cortar conexiones SSE de streaming. Cuando una réplica entra en Terminating, Kubernetes envía SIGTERM al pod y, por defecto, lo mata 30 segundos después. Para vLLM eso significa cortar conexiones SSE de streaming a la mitad de la respuesta. El cliente recibe un error 502 con el output parcial perdido. Solución: terminationGracePeriodSeconds: 120 + un preStop hook que avise al motor de no aceptar nuevas requests pero terminar las en curso:

spec:
 terminationGracePeriodSeconds: 120
 containers:
 - name: vllm
 lifecycle:
 preStop:
 httpGet:
 path: /shutdown
 port: 8000

Esto requiere que el motor exponga un endpoint de shutdown elegante; vLLM v1 lo soporta vía --enable-graceful-shutdown. Sin esto, el scale-down rompe SLO aunque las métricas no lo capturen (las requests cortadas no entran al histograma de TTFT).

Pitfall 2 — oscilación scale-up/scale-down. Si la stabilizationWindowSeconds del scale-down es corta (~60 s default), la siguiente bajada de cola dispara scale-down, y dos minutos después el siguiente pico dispara scale-up. El sistema oscila, paga cold starts repetidos, y nunca alcanza un régimen estable. Solución: scale-down con ventana de 10 minutos como mínimo y políticas conservadoras (type: Pods, value: 1, periodSeconds: 120 — máximo una réplica menos cada 2 minutos).

Pitfall 3 — vllm:num_requests_waiting con avg cuando hay rebalanceo. Si dos réplicas están desbalanceadas (una con cola 20, otra con cola 0), avg da 10 — el HPA dispara scale-out cuando lo correcto sería rebalancear vía el load balancer. Para detectarlo: añadir una alerta sobre stddev(vllm:num_requests_waiting) por deployment. Si la dispersión es alta, el problema no es de capacidad sino de routing.

Manifest completo de ejemplo

Para un deployment vLLM con Llama 70B FP8 en 4×H100 SXM por réplica, KEDA con warm pool 2:

apiVersion: apps/v1
kind: Deployment
metadata:
 name: vllm-llama70b
 namespace: inference
spec:
 replicas: 2 # gestionado por KEDA después
 selector: { matchLabels: { app: vllm-llama70b } }
 template:
 metadata:
 labels: { app: vllm-llama70b, deployment: vllm-llama70b }
 spec:
 terminationGracePeriodSeconds: 120
 nodeSelector: { workload: gpu, gpu-model: h100-sxm-80gb }
 tolerations:
 - key: nvidia.com/gpu
 operator: Exists
 effect: NoSchedule
 containers:
 - name: vllm
 image: vllm/vllm-openai:v0.10.0
 args:
 - --model=/models/llama-3.3-70b-fp8
 - --tensor-parallel-size=4
 - --max-num-seqs=64
 - --enable-prefix-caching
 - --enable-graceful-shutdown
 ports:
 - { name: http, containerPort: 8000 }
 - { name: metrics, containerPort: 8000 }
 resources:
 limits:
 nvidia.com/gpu: "4"
 memory: 200Gi
 readinessProbe:
 httpGet: { path: /health, port: 8000 }
 initialDelaySeconds: 60
 periodSeconds: 10
 failureThreshold: 30 # tolera el warmup
 lifecycle:
 preStop:
 httpGet: { path: /shutdown, port: 8000 }
 volumeMounts:
 - { name: model-cache, mountPath: /models, readOnly: true }
 - { name: dshm, mountPath: /dev/shm }
 volumes:
 - name: model-cache
 persistentVolumeClaim: { claimName: llama70b-fp8-pvc }
 - name: dshm
 emptyDir: { medium: Memory, sizeLimit: 16Gi }
---
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata: { name: vllm-llama70b-metrics, namespace: inference }
spec:
 selector: { matchLabels: { app: vllm-llama70b } }
 podMetricsEndpoints:
 - port: metrics
 path: /metrics
 interval: 15s
---
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata: { name: vllm-llama70b-scaler, namespace: inference }
spec:
 scaleTargetRef: { name: vllm-llama70b }
 minReplicaCount: 2
 maxReplicaCount: 20
 pollingInterval: 15
 cooldownPeriod: 300
 advanced:
 horizontalPodAutoscalerConfig:
 behavior:
 scaleDown:
 stabilizationWindowSeconds: 600
 policies:
 - { type: Pods, value: 1, periodSeconds: 120 }
 scaleUp:
 stabilizationWindowSeconds: 30
 policies:
 - { type: Pods, value: 2, periodSeconds: 60 }
 triggers:
 - type: prometheus
 metadata:
 serverAddress: http://prometheus.observability.svc:9090
 metricName: vllm_queue
 threshold: "5"
 query: avg(vllm:num_requests_waiting{deployment="vllm-llama70b"})
 - type: prometheus
 metadata:
 serverAddress: http://prometheus.observability.svc:9090
 metricName: vllm_kv
 threshold: "0.85"
 query: avg(vllm:gpu_cache_usage_perc{deployment="vllm-llama70b"})
 - type: cron
 metadata:
 timezone: Europe/Madrid
 start: "30 8 * * 1-5"
 end: "0 19 * * 1-5"
 desiredReplicas: "6"

Este conjunto es el mínimo viable para autoscaling LLM en cluster genérico con NVIDIA GPU Operator. Cada equipo lo adapta a su SLO concreto.

Aplicado a hardware on-premise típico

Para un cluster genérico de 4×H100 SXM 80 GB por nodo, 4 nodos GPU:

Cada nodo aloja una réplica vLLM TP=4 con Llama 70B FP8 (un modelo por nodo, no se comparten).
Warm pool de 2 réplicas en off-peak; KEDA cron eleva a 4 en horario laboral.
Cluster-autoscaler no aplica (4 nodos físicos comprados; el escalado es solo de pods). El número de réplicas concurrentes es como máximo el número de nodos disponibles (si cada réplica usa los 4 GPUs del nodo entero).
Si el dimensionamiento requiere más réplicas simultáneas que nodos, hay dos vías: (a) bajar el TP de cada réplica para que entren dos por nodo, (b) ampliar el nodepool físico. La decisión la dicta el capacity planning —ver Capacity planning para inferencia LLM on-premise—.

Volumen de eventos KEDA: ~5 evaluations/min por ScaledObject. Para 10 modelos servidos en paralelo, 3 000 evaluations/h. Manejable con un KEDA operator por cluster.

Lo que no hemos cubierto (próximos artículos)

Cluster-autoscaler para nodos GPU on-premise: cómo orquestar provisioning bare metal (Tinkerbell, Metal³) en función de demanda.
Multi-cluster autoscaling: escalar entre clusters de DCs distintos para resiliencia geográfica.
Cost-aware autoscaling: priorizar nodos según coste energético horario (en clusters con tarifa indexada).
Predictive ML-based scaling: en lugar de cron estático, entrenar un modelo que prediga demanda con 30 minutos de antelación.
Quotas y fairness multi-tenant: KEDA con namespace quotas para que un tenant no acapare el HPA.

Ver también

Observabilidad GPU para inferencia LLM — fuente de las métricas que alimentan al HPA.
Capacity planning para inferencia LLM on-premise — qué techo y qué head-room presupone el autoscaler.
Continuous batching — explica num_requests_running, num_requests_waiting y gpu_cache_usage_perc.
KV cache — domina el KV pool y por tanto los thresholds.
Cinco niveles de madurez — KEDA es pieza del nivel 4.
Canary, blue-green y shadow — el autoscaler convive con la estrategia de despliegue.
El router de inferencia LLM — el router consume vllm:num_requests_running y vllm:gpu_cache_usage_perc (mismas métricas que el autoscaler) para decidir réplica con token-aware LB y prefix-aware routing; los dos componentes comparten cabina pero deciden cosas distintas.
Runbooks de incident response para LLM con Keep + Kafka — los runbooks RB-01 (GpuHbmNearOom) y RB-05 (VllmKvCachePoolNearFull) usan el autoscaler como palanca de mitigación inmediata.
Resource managers de RKE2: CPU, Memory y Topology Manager — cada réplica que el autoscaler crea pasa por la admisión del Topology Manager; si el nodo no tiene una “mesa” NUMA libre, el pod queda pendiente. El autoscaling tiene que contar con la granularidad NUMA, no solo con CPU/memoria agregada.
Del disco a la HBM: cold start y carga del modelo — el techo real de la elasticidad no es la GPU disponible, es cuánto tarda cada réplica nueva en cargar el modelo: 40 s de cold start hacen inviable el scale-to-zero con SLO de latencia.

Referencias

KEDA project — keda.sh (documentación oficial de triggers Prometheus y cron).
Kubernetes — Horizontal Pod Autoscaler walkthrough (kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale).
NVIDIA — GPU Operator on Kubernetes (Helm chart oficial con DaemonSet de drivers y DCGM).
vLLM project — production_monitoring/ (métricas Prometheus expuestas por el servidor).
Karpenter — NodePool spec (etiquetado y taints para nodepools GPU).
Cluster Autoscaler — Scaling GPU nodes (caveats de descubrimiento de recursos GPU).
Kubernetes — Pod lifecycle and termination (preStop, terminationGracePeriodSeconds).

Observabilidad GPU para inferencia LLM: las doce métricas DCGM y vLLM que dictan la salud de tu producción

Mon, 01 Jun 2026 15:30:00 +0200

Este post complementa los de Tracing LLM con OpenTelemetry GenAI (la capa de tracing por encima de las métricas), Capacity planning (qué se dimensionó y qué se debe vigilar) y Continuous batching (el mecanismo que explica varias de las métricas del motor).

TL;DR

La observabilidad de un cluster de inferencia LLM se construye sobre dos fuentes complementarias: las métricas del hardware GPU expuestas por DCGM (Data Center GPU Manager) Exporter —parte del NVIDIA GPU Operator— y las métricas del motor de inferencia (vLLM, SGLang, TensorRT-LLM) expuestas en /metrics Prometheus-compatibles. Ninguna de las dos basta sola. La métrica clásica de nvidia-smi llamada GPU utilization es engañosa para LLMs: marca alto cuando hay cualquier kernel ejecutándose, sin distinguir tensor cores ardiendo de SMs esperando por HBM. La cabina de pilotaje completa tiene doce métricas DCGM en cuatro familias (compute: DCGM_FI_PROF_SM_OCCUPANCY, DCGM_FI_PROF_PIPE_TENSOR_ACTIVE, DCGM_FI_PROF_DRAM_ACTIVE; memoria: DCGM_FI_DEV_FB_USED, DCGM_FI_DEV_FB_FREE, DCGM_FI_DEV_NVLINK_BANDWIDTH_TOTAL; térmico-energético: DCGM_FI_DEV_GPU_TEMP, DCGM_FI_DEV_POWER_USAGE, DCGM_FI_DEV_CLOCK_THROTTLE_REASONS; salud: DCGM_FI_DEV_XID_ERRORS, DCGM_FI_DEV_ECC_DBE_VOL_TOTAL, DCGM_FI_DEV_RETIRED_DBE) y cinco métricas del motor vLLM (vllm:num_requests_running, vllm:num_requests_waiting, vllm:gpu_cache_usage_perc, vllm:time_to_first_token_seconds, vllm:time_per_output_token_seconds). Cada una tiene un umbral verde/ámbar/rojo defendible, una PromQL para alerta, y al menos una falsa lectura habitual que confunde al operador junior. Las seis alertas críticas que cualquier cluster productivo debe disparar son: HBM > 92 %, throttle por térmico o por power, XID error, ECC double-bit, KV cache pool > 95 %, y TTFT P95 fuera de SLO durante 5 minutos. El objetivo de tener este panel: que el operador de turno diagnostique el origen de una degradación en menos de cinco minutos, sin abrir consola SSH a las GPUs. Cuando esto se cumple, el cluster ha pasado a operación profesional; mientras no, se opera por intuición.

Estás aquí: OBSERVE (la otra mitad del tracing)

El tracing —ya cubierto en Tracing LLM con OpenTelemetry GenAI— responde qué pasó en esta request concreta. Las métricas responden qué está pasando en el cluster en agregado. Son complementarias: una alerta del lado de métricas te dice “el clúster está degradando”, el tracing te dice “y esta es la traza concreta que te lo demuestra”. Un cluster sin tracing pero con métricas opera; un cluster sin métricas pero con tracing no opera, debuggea.

La analogía: la cabina de un avión moderno

En un avión comercial moderno, el panel de instrumentos del piloto tiene más de 70 indicadores activos. Si solo hubiese uno —el altímetro, por ejemplo— el avión volaría hacia el suelo en el primer momento de baja visibilidad. Hace falta el altímetro y el indicador de actitud, y el de velocidad, y el de viraje, y el de combustible, y los de presión de aceite de cada motor, y las temperaturas de salida de turbina. Cada uno responde una pregunta distinta. Y todos juntos cubren la pregunta operacional: ¿está el avión sano, está donde debe, y va donde queremos?

La observabilidad de un cluster de inferencia LLM funciona igual. Una sola métrica —“GPU utilization 99 %"— no responde nada útil. Es como mirar solo el cuentakilómetros del coche para diagnosticar por qué hace ruido el motor. La cabina completa es doce instrumentos del lado de hardware más cinco del lado del motor de inferencia, organizados en familias que responden preguntas distintas:

Compute y eficiencia: ¿están los tensor cores haciendo el trabajo que esperamos o están esperando?
Memoria: ¿queda VRAM para nuevas requests o estamos al borde del OOM?
Térmico y energético: ¿el hardware está sano o está limitando el throughput silenciosamente?
Salud y errores: ¿hay degradación del hardware en curso (ECC, XID, NVLink)?
Motor de inferencia: ¿la cola crece, el KV pool está saturado, el SLO se está cumpliendo?

Las cuatro primeras responden a “¿la GPU está bien?”. La quinta responde a “¿está dando el servicio que prometimos?”. Las dos preguntas son distintas y ambas deben tener respuesta a un golpe de vista.

Por qué `nvidia-smi` `GPU-Util` engaña en LLMs

La métrica clásica que aparece en nvidia-smi como GPU-Util corresponde a DCGM_FI_DEV_GPU_UTIL. Su definición oficial: “porcentaje del tiempo durante el cual uno o más kernels estuvieron ejecutándose en la GPU”. El problema en LLMs: la fase de decode es memory-bound, no compute-bound. Cuando el motor de inferencia hace decode token a token, la GPU pasa el 90 % del tiempo esperando que la HBM termine de entregar los pesos del modelo y el KV cache. Hay un kernel corriendo (lectura de HBM); por tanto GPU-Util reporta valores cercanos al 100 %. Pero los tensor cores están parados — el cuello de botella es la memoria, no el compute.

Resultado práctico: el operador ve “GPU-Util 99 %” en Grafana y asume “GPU saturada, no se puede meter más carga”. Pero la realidad puede ser “compute al 25 %, HBM saturada al 95 %”, lo que cambia las decisiones operativas (quantization, batch size, paralelismo). La métrica clásica miente por simplificación.

Lo correcto es mirar las tres métricas de profiling DCGM del subsistema _FI_PROF_*:

DCGM_FI_PROF_SM_OCCUPANCY — ratio de warps activos sobre máximos por SM. ¿Hay trabajo paralelo?
DCGM_FI_PROF_PIPE_TENSOR_ACTIVE — % de ciclos con tensor cores efectivamente activos. ¿Está el compute trabajando?
DCGM_FI_PROF_DRAM_ACTIVE — % de ciclos con la HBM transfiriendo. ¿Está la memoria saturada?

Una decode-bound GPU típica de Llama 70B en H100 muestra: SM occupancy 35–55 %, tensor active 15–30 %, DRAM active 80–95 %. Esa es la “GPU saturada” real para LLMs. Las tres juntas distinguen los regímenes; cada una sola no dice nada accionable.

Cómo se montan en producción

La parte de plataforma se cubre en Cinco niveles de madurez (nivel 4 — GPU plane) y Siete fases de despliegue (fase F5). Para el observador, las piezas clave son:

NVIDIA GPU Operator. Manifiestos Helm que despliegan en cada nodo GPU: drivers, container toolkit, MIG manager y DCGM Exporter. Este último expone /metrics en formato Prometheus con todos los DCGM_FI_* listados arriba. Se scrapea desde el Prometheus interno del cluster.

Motor de inferencia. vLLM expone /metrics en el puerto 8000 (default) con métricas vllm:*. SGLang lo expone también con prefijo sglang:. TensorRT-LLM lo expone vía Triton Inference Server con prefijo nv_inference:. La convención básica de nombres es similar entre los tres motores; los umbrales y queries de este post asumen vLLM, pero se traducen.

ServiceMonitor / PodMonitor. Recurso del operador de Prometheus que indica qué scrapear. Ejemplo mínimo:

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
 name: vllm-inference
spec:
 selector:
 matchLabels: { app: vllm }
 podMetricsEndpoints:
 - port: metrics
 interval: 15s

Dashboards. El operador de NVIDIA publica dashboards Grafana de referencia para DCGM en nvidia/dcgm-exporter (repo oficial). vLLM publica uno en vllm-project/vllm (carpeta examples/). Ambos sirven como base; cada equipo añade los paneles propios de su SLO.

Las doce métricas DCGM organizadas por familia

Familia 1 — Compute

DCGM_FI_PROF_SM_OCCUPANCY — Ratio de warps activos por SM sobre el máximo posible. Valor entre 0 y 1.

Verde: 0.30–0.70 (régimen típico LLM en decode).
Ámbar: < 0.20 sostenido (batch demasiado pequeño, GPU infrautilizada en paralelismo).
Rojo: 0.95 sostenido con DRAM_ACTIVE bajo (kernel patológico saturando SMs).

DCGM_FI_PROF_PIPE_TENSOR_ACTIVE — % de ciclos con tensor cores ejecutando. La métrica clave de “¿el compute está produciendo?”.

Verde en prefill: 50–80 %.
Verde en decode: 15–30 % (decode es memory-bound, no es síntoma de problema).
Rojo: < 5 % sostenido en prefill o el motor no usa los tensor cores (mala config, formato incompatible).

DCGM_FI_PROF_DRAM_ACTIVE — % de ciclos con HBM transfiriendo datos. Métrica clave para detectar saturación de memoria.

Verde en decode: 60–85 %.
Ámbar: > 90 % sostenido (HBM cuello de botella firme — explica la TPOT alta).
Rojo: > 95 % sostenido con KV cache pool < 70 % (algo está pidiendo HBM que no es el motor; investigar leaks).

Familia 2 — Memoria

DCGM_FI_DEV_FB_USED — Frame Buffer (HBM) usado en MiB.

Verde: 70–85 % del total.
Ámbar: 86–92 %.
Rojo: > 92 % (riesgo de OOM en el siguiente paged-attention allocation).

PromQL para porcentaje sobre cluster: 100 * sum(DCGM_FI_DEV_FB_USED) / sum(DCGM_FI_DEV_FB_TOTAL).

DCGM_FI_DEV_FB_FREE — Frame Buffer libre. Complementaria de la anterior; útil para alertas absolutas (< 4096 MiB libres).

DCGM_FI_DEV_NVLINK_BANDWIDTH_TOTAL — Bandwidth NVLink agregado en MB/s. Para topologías TP (tensor parallel) que cruzan GPUs vía NVLink, esta métrica revela si el reparto de paralelismo está saturando el bus.

Verde: variable según topología. En 4×H100 SXM con NVLink 4.0, capacidad teórica 450 GB/s por GPU. Régimen TP=4 típico: 50–150 GB/s sostenido.
Rojo: > 90 % capacidad sostenido (revisar si el modelo cabría con TP menor o pipeline parallel).

Familia 3 — Térmico y energético

DCGM_FI_DEV_GPU_TEMP — Temperatura del die en °C.

Verde: < 75 °C.
Ámbar: 75–82 °C.
Rojo: > 83 °C (cerca del thermal throttle automático de H100; revisar ventilación, caudal de aire, temperatura de entrada al rack).

DCGM_FI_DEV_POWER_USAGE — Consumo en watts. Para H100 SXM, TDP nominal 700 W. Útil para tres cosas: detectar workload inusualmente bajo (sospechar idle o stall), facturar coste energético real, y disparar alertas si el draw se acerca al límite de la PDU.

DCGM_FI_DEV_CLOCK_THROTTLE_REASONS — Bitmap codificado con las razones de throttle activas. Es la métrica que silenciosamente explica las degradaciones de TPOT.

Bits relevantes:

0x0000000000000001 — Idle (no es problema).
0x0000000000000002 — App clocks setting.
0x0000000000000004 — SW Power Cap (límite de software, p. ej. por nvidia-smi -pl).
0x0000000000000008 — HW Slowdown.
0x0000000000000010 — Sync Boost (NVIDIA Sync).
0x0000000000000020 — SW Thermal Slowdown (límite térmico de software).
0x0000000000000040 — HW Thermal Slowdown (límite térmico de hardware — emergencia).
0x0000000000000080 — HW Power Brake Slowdown (caída de tensión PSU).
0x0000000000000100 — Display Clock Setting.

Cualquier throttle salvo Idle con valor > 0 sostenido es alerta. La degradación de TPOT con DRAM_ACTIVE ya alto y throttle térmico activo es el clásico “el rack está mal ventilado, no es problema del motor”.

Familia 4 — Salud

DCGM_FI_DEV_XID_ERRORS — Contador acumulado de XID errors del driver. Los XID son códigos de evento crítico que NVIDIA documenta exhaustivamente (XID 13: graphics engine exception; XID 31: GPU memory page fault; XID 43: reset channel verif error; XID 79: GPU has fallen off the bus; XID 95: uncontained ECC error; etc.). Cualquier incremento es alerta inmediata: muchos XID requieren reset del nodo o RMA de la GPU.

DCGM_FI_DEV_ECC_DBE_VOL_TOTAL — Errores ECC double-bit volátiles (no corregibles). A diferencia de los single-bit (que ECC corrige silenciosamente y se contabilizan en DCGM_FI_DEV_ECC_SBE_*), los double-bit corrompen datos. Cualquier valor > 0 es alerta crítica: la GPU debe ser drenada y revisada.

DCGM_FI_DEV_RETIRED_DBE — Páginas físicas de HBM retiradas por double-bit errors acumulados. NVIDIA retira páginas defectuosas automáticamente para prevenir corrupción futura. Más de 4–8 páginas retiradas en una GPU sugiere degradación del silicio: documentar y planificar reemplazo en próxima ventana de mantenimiento.

Las cinco métricas del motor de inferencia (vLLM)

Las métricas DCGM responden “¿está sana la GPU?”. Las del motor responden “¿está el servicio cumpliendo el SLO?”. Sin ellas, sabes que el hardware funciona pero no sabes si los clientes están contentos.

vllm:num_requests_running — Requests actualmente en el batch. Si llega al --max-num-seqs configurado y no baja, el motor está saturado en concurrencia (revisar VRAM y rebalancear vía autoscaler — ver Autoscaling LLM en Kubernetes).

vllm:num_requests_waiting — Requests en cola, sin entrar al batch. Cualquier valor > 0 sostenido durante minutos indica que el cluster no escala con la carga. Esta es la métrica primaria para HPA.

vllm:gpu_cache_usage_perc — % del KV cache pool usado.

Verde: 50–80 %.
Ámbar: 80–92 %.
Rojo: > 92 % (riesgo de preempt-on-OOM: vLLM tirará requests para liberar memoria, lo que aumenta TTFT visiblemente).

vllm:time_to_first_token_seconds — Histograma de TTFT por request. Se consume como histogram_quantile(0.95, sum by(le)(rate(vllm:time_to_first_token_seconds_bucket[5m]))). Comparado contra el SLO de TTFT P95 dispara la alerta primaria de servicio.

vllm:time_per_output_token_seconds — Histograma de TPOT. Equivalente al anterior pero para fluidez de streaming. Comparado contra el SLO de TPOT P95 dispara la alerta secundaria.

Las seis alertas que deben pagear en producción

Cualquier cluster productivo serio dispara estas seis alertas a un canal con rotación de guardia. Sin estas, el SLO se cumple por suerte, no por proceso.

groups:
 - name: gpu-llm-critical
 rules:
 - alert: GpuHbmNearOom
 expr: 100 * (DCGM_FI_DEV_FB_USED / DCGM_FI_DEV_FB_TOTAL) > 92
 for: 2m
 labels: { severity: critical }
 annotations:
 summary: "HBM de {{ $labels.gpu }} en {{ $value }}% — riesgo OOM"

 - alert: GpuThermalOrPowerThrottle
 expr: (DCGM_FI_DEV_CLOCK_THROTTLE_REASONS != 0) and ignoring(reason) (DCGM_FI_DEV_CLOCK_THROTTLE_REASONS != 1)
 for: 1m
 labels: { severity: warning }
 annotations:
 summary: "GPU {{ $labels.gpu }} en throttle (reasons={{ $value }})"

 - alert: GpuXidErrorDetected
 expr: increase(DCGM_FI_DEV_XID_ERRORS[5m]) > 0
 labels: { severity: critical }
 annotations:
 summary: "XID error en GPU {{ $labels.gpu }} — investigar inmediatamente"

 - alert: GpuEccDoubleBit
 expr: DCGM_FI_DEV_ECC_DBE_VOL_TOTAL > 0
 labels: { severity: critical }
 annotations:
 summary: "ECC double-bit en GPU {{ $labels.gpu }} — drenar nodo"

 - alert: VllmKvCachePoolNearFull
 expr: vllm:gpu_cache_usage_perc > 0.95
 for: 3m
 labels: { severity: warning }
 annotations:
 summary: "KV cache pool > 95% en {{ $labels.instance }}"

 - alert: VllmTtftP95OutOfSlo
 expr: histogram_quantile(0.95, sum by(le, instance)(rate(vllm:time_to_first_token_seconds_bucket[5m]))) > 1.5
 for: 5m
 labels: { severity: warning }
 annotations:
 summary: "TTFT P95 sobre SLO ({{ $value }}s > 1.5s)"

Estas seis cubren el 80 % de los incidentes que afectan a SLO. El 20 % restante exige investigación con tracing (ver Tracing LLM con OpenTelemetry GenAI).

Tabla maestra: umbrales y queries

Métrica	Verde	Ámbar	Rojo	Query base (PromQL)
SM occupancy	0.30–0.70	0.15–0.30	< 0.10 sostenido	`DCGM_FI_PROF_SM_OCCUPANCY`
Tensor active (decode)	15–30 %	< 10 %	< 3 %	`DCGM_FI_PROF_PIPE_TENSOR_ACTIVE`
DRAM active	60–85 %	85–95 %	> 95 % con KV bajo	`DCGM_FI_PROF_DRAM_ACTIVE`
FB used	70–85 %	86–92 %	> 92 %	`100 * DCGM_FI_DEV_FB_USED / DCGM_FI_DEV_FB_TOTAL`
NVLink BW	< 70 % cap	70–90 % cap	> 90 % cap	`DCGM_FI_DEV_NVLINK_BANDWIDTH_TOTAL`
GPU temp	< 75 °C	75–82 °C	> 83 °C	`DCGM_FI_DEV_GPU_TEMP`
Power usage	< 90% TDP	90–98 % TDP	> 98 % TDP	`DCGM_FI_DEV_POWER_USAGE`
Throttle reasons	0 o Idle	App/SW	HW Therm/Power	`DCGM_FI_DEV_CLOCK_THROTTLE_REASONS`
XID errors	sin cambio	—	cualquier delta	`increase(DCGM_FI_DEV_XID_ERRORS[5m])`
ECC DBE	0	—	> 0	`DCGM_FI_DEV_ECC_DBE_VOL_TOTAL`
Retired pages	< 4	4–8	> 8	`DCGM_FI_DEV_RETIRED_DBE`
KV cache used	50–80 %	80–92 %	> 92 %	`vllm:gpu_cache_usage_perc`
Requests waiting	0	1–5 sostenido	> 10 sostenido	`vllm:num_requests_waiting`
TTFT P95	< SLO	80–100 % SLO	> SLO	ver query alerta arriba
TPOT P95	< SLO	80–100 % SLO	> SLO	`histogram_quantile(0.95, sum by(le)(rate(vllm:time_per_output_token_seconds_bucket[5m])))`

Tres pitfalls que confunden al operador junior

Pitfall 1 — “GPU-Util al 99 % = saturada”. Como se explicó al inicio: DCGM_FI_DEV_GPU_UTIL se enciende con cualquier kernel. Lo correcto es mirar las tres _PROF_* (SM occupancy, tensor active, DRAM active) juntas. GPU util 99 % + tensor active 8 % + DRAM active 92 % = “saturada por memoria, no compute”; GPU util 99 % + tensor active 75 % + DRAM active 50 % = “saturada por compute, prefill heavy”. Las dos situaciones piden palancas distintas.

Pitfall 2 — confundir ECC single-bit (SBE) con double-bit (DBE). Los single-bit se corrigen silenciosamente y son inevitables en cualquier HBM bajo carga (radiación cósmica, fluctuaciones de tensión). Un contador SBE creciendo lentamente no es alerta — es física. El DBE sí: corrompe datos. Distinguir las dos métricas evita falsas alarmas y falsos negativos a partes iguales.

Pitfall 3 — alertar sobre num_requests_waiting > 0 sin contexto. Un valor instantáneo de 1 o 2 durante un pico es normal. Lo que importa es la cola sostenida: usar for: 5m con umbral 3–5. Sin esa ventana, el sistema satura el canal de alertas con ruido.

Aplicado a hardware on-premise típico

Para un cluster genérico de 4×H100 SXM 80 GB con NVLink intra-nodo:

DCGM Exporter desplegado vía NVIDIA GPU Operator, un DaemonSet por nodo GPU.
Prometheus interno con retención 30 días para métricas de alta frecuencia, 1 año para downsampled (Thanos/Mimir si el volumen lo justifica).
Grafana con tres dashboards estándar: hardware GPU (DCGM), motor (vLLM), SLO (TTFT/TPOT/RPS contra objetivos escritos).
Alertmanager con rotación de guardia y rate-limiting por silencio agrupado por nodo.
Cardinalidad controlada: gpu (id local), node, pod, model — no añadir request_id ni labels de alta cardinalidad a métricas (eso es trabajo del tracing).

Volumen estimado para un cluster de 16 GPUs con scraping cada 15 s: ~2 millones de samples/min, ~25 GB/día de Prometheus crudo. Manejable con un Prometheus por cluster + retention; si el equipo escala a > 64 GPUs, considerar Thanos sidecar o VictoriaMetrics. Ver Catálogo de herramientas OSS LLMOps para alternativas equivalentes.

Lo que no hemos cubierto (próximos artículos)

Tracing de cargas LLM: ya cubierto en Tracing LLM con OpenTelemetry GenAI.
Autoscaling basado en estas métricas: ver Autoscaling LLM en Kubernetes.
Runbooks de incident response: cómo cada una de estas alertas se traduce a acción concreta (drain, restart, RMA, escalado, rollback).
Cost accounting: usar DCGM_FI_DEV_POWER_USAGE y vllm:request_success_total para showback de coste por tenant.
Monitorización de fairness multi-tenant: cuando varios tenants comparten cluster, qué métricas detectan que uno está acaparando el KV cache.

Ver también

Tracing LLM con OpenTelemetry GenAI — la otra mitad de la observabilidad.
Capacity planning para inferencia LLM on-premise — qué se dimensionó y, por tanto, qué umbrales son defendibles aquí.
Continuous batching — explica por qué num_requests_running, num_requests_waiting y gpu_cache_usage_perc son las métricas operativas del motor.
Cinco niveles de madurez — la observabilidad LLM-aware vive en el nivel 4.
Siete capas del stack de inferencia LLM on-premise — DCGM Exporter es pieza de la capa de plataforma.
Autoscaling LLM en Kubernetes — usa estas métricas como input.
Anatomía de las doce métricas DCGM y cinco vLLM — profundización con analogía y anomalía documentada en producción para cada métrica, con cifras de incidentes públicos (Meta Llama 3, Story of Two GPUs, issues vLLM, KBs Dell/Lenovo).
Runbooks de incident response para LLM con Keep + Kafka — la traducción de cada alerta crítica a acción concreta (drain, reset, RMA, rollback) con workflow YAML, schema Kafka WORM y encaje en ISO 27035, ENS, NIS2, EU AI Act art. 73.
NVLink, NVSwitch y NCCL: el cable por el que pasa cada token — los contadores NVLink (nvidia-smi nvlink -e, bytes TX/RX por enlace, errores CRC) que estas métricas DCGM exponen: un all-reduce lento se ve antes en un contador de errores del cable que en la latencia de la API.

Referencias

NVIDIA — DCGM Exporter (repo nvidia/dcgm-exporter, métricas y unidades documentadas).
NVIDIA — DCGM Field Identifiers reference (lista completa de DCGM_FI_*).
NVIDIA — XID Errors documentation (catálogo de códigos XID y procedimientos de remediación).
NVIDIA — NVIDIA GPU Operator (Helm chart oficial).
vLLM project — examples/production_monitoring/ (PromQL y dashboards Grafana de referencia).
Prometheus — Histogram and summary best practices (para construir queries de percentiles defendibles).
NVIDIA — H100 Tensor Core GPU datasheet (TDP, HBM bandwidth, NVLink capacities).

Capacity planning para inferencia LLM on-premise: cómo dimensionar GPUs a partir de un SLO

Mon, 01 Jun 2026 15:00:00 +0200

Este post complementa los de KV cache (la pieza que domina el presupuesto de VRAM), Continuous batching (lo que define la utilización efectiva del compute) y Siete capas del stack (las piezas que el sizing presupone). Antes de leer este, asegúrate de que tu equipo tiene escritos los SLOs que va a perseguir; sin esa entrada el cálculo no es defendible.

TL;DR

El capacity planning de inferencia LLM no responde a “cuántos tokens/segundo da una GPU” — esa pregunta carece de respuesta universal porque el throughput depende de la concurrencia, el reparto prefill/decode, la longitud de contexto, el motor de inferencia y la quantization. La pregunta correcta tiene tres entradas (SLO: TTFT P95, TPOT P95, RPS sostenidos), una referencia de hardware (modelo de GPU, VRAM, ancho HBM, FLOPs efectivos) y un modelo (parámetros, arquitectura GQA/MHA/MoE, formato de pesos). El cálculo se resuelve en dos presupuestos acoplados que se cruzan. Presupuesto de VRAM: del total de la GPU restas pesos del modelo y activaciones, lo que queda es KV cache budget, y de ahí derivas la concurrencia máxima posible al contexto promedio que esperas. Presupuesto de tiempo: el motor (vLLM, SGLang, TensorRT-LLM) tiene un techo de tokens/s en decode dado por el ancho de HBM y otro en prefill dado por el FLOP útil; de ahí derivas la TPOT esperada y, dividiendo prefill_tokens entre el throughput de prefill, la TTFT esperada. Ambos presupuestos deben cumplir el SLO simultáneamente: el que esté más ajustado dicta el dimensionamiento. Sobre el ejemplo Llama 70B BF16 con tensor parallel 4 en 4×H100 SXM, una sola réplica satura a ~28 requests concurrentes y entrega ~3 200 tokens/s de decode agregado con TPOT mediano de 35 ms; para 200 RPS sostenidos a un perfil de 800 tokens de prompt + 250 de output, hacen falta entre 4 y 5 réplicas con un colchón del 25 % sobre el pico observado. La quantization (FP8 → INT4) divide entre 1.5 y 4× el coste de VRAM y de tiempo de decode, pero degrada calidad de forma medible — no se asume gratis, se valida con evals. Las cinco trampas habituales: confundir media con P95, ignorar el reparto prefill/decode del workload real, dimensionar sin head-room para retrain ni rollback, olvidar que la GPU al 100 % de SM util no significa nada si la HBM está saturada, y no documentar los supuestos del cálculo (un sizing sin supuestos escritos es un cálculo desechable).

Estás aquí: DEPLOY (con un pie en OBSERVE)

El capacity planning es una pieza con doble residencia. Vive en DEPLOY porque sin un sizing válido no se compra hardware ni se configura el motor de inferencia. Pero su input son las observaciones reales: distribución de longitudes de prompt y output, mezcla prefill/decode del workload, P95 reales que ya se están viendo en preproducción. Sin esos datos el cálculo es una servilleta — defendible solo hasta que llegue el primer cliente que no encaja en la media asumida.

La analogía: el hotel con habitaciones de tamaño variable

Imagina un hotel donde las habitaciones no tienen tamaño fijo: cada huésped paga por los metros cuadrados que necesita, y la planta del edificio se reorganiza dinámicamente para acomodar a quien llega. La dirección quiere maximizar ocupación, pero tiene dos restricciones reales y una métrica de calidad.

Restricción 1 — espacio físico. La planta tiene 1 000 m² totales. Si entra una familia que necesita 200 m², esa familia ocupa esa superficie y no se puede entregar al siguiente huésped. La habitación más grande limita cuántos huéspedes simultáneos caben.

Restricción 2 — personal de servicio. Hay 10 recepcionistas. Cada uno puede gestionar el check-in de un huésped cada dos minutos. Cuando llegan 60 huéspedes en una hora, los últimos esperan en cola; el tiempo desde que entran a recepción hasta que reciben su llave depende de cuántos hay delante.

Métrica de calidad — promesa de tiempo. La carta dice “check-in en menos de 15 minutos”. Si llegan demasiados huéspedes a la vez, esa promesa se rompe aunque haya espacio físico libre.

El espacio físico es la VRAM de la GPU. Cada habitación es una request con su KV cache (más grande cuanto más larga la conversación). Los recepcionistas son los compute units (Streaming Multiprocessors + Tensor Cores). El check-in es la fase de prefill; las noches que el huésped pasa después son los pasos de decode. La promesa de 15 minutos es el SLO de TTFT P95.

El capacity planning del hotel es exactamente este: dado el perfil esperado de huéspedes (cuántos llegan por hora, cuánto espacio piden de media, cuántos minutos toleran de espera), calcular cuántas plantas y cuántos recepcionistas hace falta. No se hace estimando “habitaciones por hora” en abstracto — se hace cruzando los dos presupuestos con la promesa de tiempo. La analogía sostiene el cálculo hasta el final.

Las tres entradas del SLO

Antes de poner un solo número en la hoja, hay que escribir las tres dimensiones del SLO. Sin esto el cálculo es estética, no ingeniería.

TTFT P95 (Time-To-First-Token). El tiempo desde que el cliente envía la request hasta que recibe el primer token. Está dominado por la fase de prefill (procesar el prompt entero de una vez) más la cola del scheduler. Para chat conversacional, un objetivo razonable está entre 0.5 y 2 segundos P95. Para asistentes de programación con prompts grandes (5–10 K tokens de contexto), entre 2 y 4 s P95. Por debajo de 500 ms entra en regla de UX para conversaciones tipo voz, pero exige compromisos serios de arquitectura.

TPOT P95 (Time-Per-Output-Token). El tiempo entre tokens consecutivos durante decode. Domina la “fluidez percibida” del streaming. Por encima de 80 ms/token el lector humano percibe pausas; por debajo de 30 ms/token la salida fluye más rápido de lo que se lee. Objetivo industrial habitual: 40–60 ms P95.

RPS sostenidos cumpliendo SLO. El throughput que el sistema debe soportar sin violar TTFT ni TPOT. Esto es la métrica clave de DistServe llamada goodput —ver Continuous batching—. “200 RPS pico” no es lo mismo que “200 RPS con TTFT P95 ≤ 1.5 s”. Sin la condición de SLO, el número de RPS no significa nada.

Estas tres dimensiones se acompañan de un perfil de workload: distribución de longitudes de prompt y de output. Las medianas no bastan; hace falta P50, P95, P99. Un perfil mal medido es el principal motivo de sizing fallido.

La fórmula central: dos presupuestos que se cruzan

El cálculo se resuelve en dos cuentas independientes que después se cruzan. La menor de las dos manda.

Presupuesto de VRAM

Para una GPU con VRAM total $V$, el espacio disponible para KV cache es:

$$V_{\text{kv}} = V - V_{\text{model}} - V_{\text{activations}} - V_{\text{overhead}}$$

donde:

$V_{\text{model}}$ es el tamaño de los pesos: para un modelo de $P$ parámetros en formato $b$ bytes/parámetro, $V_{\text{model}} = P \cdot b$. Llama 70B BF16 = $70 \times 10^9 \times 2 = 140$ GB. En tensor parallel TP=4, cada GPU lleva $140 / 4 = 35$ GB.
$V_{\text{activations}}$ son los buffers intermedios del forward pass. Para vLLM con batch razonable, entre 2 y 6 GB por GPU dependiendo de batch size y longitud máxima.
$V_{\text{overhead}}$ son CUDA context, NCCL buffers, pool de PagedAttention, paged blocks reservados. 2–4 GB típicos.

El KV cache budget por GPU queda como el residuo. Para H100 SXM 80 GB con Llama 70B TP=4 BF16:

$$V_{\text{kv}} = 80 - 35 - 4 - 3 = 38 \text{ GB por GPU} = 152 \text{ GB agregados sobre TP=4}$$

El coste por token de KV cache para un modelo con $L$ capas, $H_{\text{kv}}$ heads KV (GQA), dimensión por head $d_h$, en formato $b$ bytes:

$$\text{kv_per_token} = 2 \cdot L \cdot H_{\text{kv}} \cdot d_h \cdot b$$

El factor 2 es porque se guardan K y V. Para Llama 70B (L=80, $H_{\text{kv}}$=8 con GQA, $d_h$=128, BF16 = 2 bytes):

$$\text{kv_per_token} = 2 \cdot 80 \cdot 8 \cdot 128 \cdot 2 = 327,680 \text{ bytes} = 320 \text{ KB/token}$$

Y la concurrencia máxima al contexto promedio $C$:

$$N_{\text{max}} = \frac{V_{\text{kv}}}{C \cdot \text{kv_per_token}}$$

Con $V_{\text{kv}}$ agregado de 152 GB y un contexto promedio de 1 500 tokens (800 prompt + 700 generados en el peor instante de la conversación):

$$N_{\text{max}} = \frac{152 \times 10^9}{1,500 \cdot 320 \times 10^3} \approx 316 \text{ requests concurrentes}$$

Este es el techo físico de concurrencia para esa réplica. No es lo que vas a usar — es lo que no puedes superar sin OOM. El número operativo está bastante por debajo (head-room para spikes).

Presupuesto de tiempo

Aquí entran dos sub-cálculos: el de decode (memory-bound) y el de prefill (compute-bound).

Decode TPOT. Por cada token que se genera, hay que pasear los pesos del modelo (relevantes para esa request) y leer el KV cache acumulado. El cuello de botella es el ancho de banda HBM. Para una GPU con ancho $B$ GB/s y un modelo de $V_{\text{model_per_gpu}}$ GB de pesos:

$$\text{tpot}{\text{teórico}} \approx \frac{V{\text{model_per_gpu}}}{B}$$

Para H100 SXM con HBM3 a 3.35 TB/s y Llama 70B TP=4 BF16 (35 GB/GPU):

$$\text{tpot}_{\text{teórico}} \approx \frac{35}{3,350} \approx 10.4 \text{ ms/token}$$

Este es el mejor caso teórico con batch=1 y eficiencia HBM al 100 %. En la práctica vLLM en H100 con Llama 70B TP=4 alcanza 12–18 ms/token a batch bajo y 30–45 ms/token a batch alto (con concurrencia 32, los tokens compiten por la HBM compartida). El número operacional defendible: 35 ms/token en concurrencia 24–32.

Prefill throughput. El prefill procesa N tokens de prompt en un único forward pass. Es compute-bound: cuello en FLOPs. Para H100 SXM con 989 TFLOPs BF16 sostenidos y Llama 70B (cada forward pass cuesta aproximadamente $2 \cdot P \cdot N$ FLOPs por sequence de longitud N):

$$\text{prefill_tps} = \frac{4 \cdot \text{TFLOPs} \cdot \eta}{2 \cdot P} = \frac{4 \cdot 989 \times 10^{12} \cdot 0.5}{2 \cdot 70 \times 10^9} \approx 14,000 \text{ tokens/s}$$

(el factor 4 son las GPUs en TP, $\eta$ es eficiencia real entre 0.4 y 0.6 en H100). Un prompt de 800 tokens tarda en prefill:

$$\text{prefill_time} = \frac{800}{14,000} \approx 57 \text{ ms}$$

Sumando una cola típica de 100–300 ms a concurrencia alta, TTFT P95 ≈ 350–500 ms para ese perfil. Muy por debajo del objetivo de 1.5 s — hay margen.

El cruce

La concurrencia operativa real $N_{\text{op}}$ es el mínimo entre el techo de VRAM, la concurrencia a la que el TPOT empieza a degradar por encima del SLO, y la concurrencia a la que el TTFT empieza a degradar por encima del SLO (cola de prefill). Para el ejemplo:

VRAM techo: 316.
TPOT degrada a 80 ms (SLO) alrededor de concurrencia ~80–100 (medido empíricamente con benchmark, no fórmula cerrada).
TTFT degrada a 1.5 s alrededor de concurrencia ~40–60 por cola de prefill.

La concurrencia operativa de la réplica es ~50. Aplicando un 25 % de head-room para spikes y rebalanceos, concurrencia objetivo por réplica ≈ 35–40.

Hoja de cálculo paso a paso: Llama 70B BF16 en 4×H100 SXM

Entrada del ejercicio:

SLO: TTFT P95 ≤ 1.5 s; TPOT P95 ≤ 60 ms; 200 RPS sostenidos.
Workload: prompt P50=600, P95=1 200, P99=2 500; output P50=180, P95=500, P99=900. Promedio prompt 800, output 250.
Hardware genérico: 4×H100 SXM 80 GB con NVLink, motor vLLM v1, tensor parallel 4, BF16.

Paso 1 — VRAM por GPU. Pesos 35 GB, activaciones 4 GB, overhead 3 GB → KV budget 38 GB/GPU = 152 GB agregados. KV/token a Llama 70B GQA = 320 KB. Techo de tokens vivos en cache: $152 \times 10^9 / 320 \times 10^3 \approx 475,000$ tokens. Al contexto promedio operacional (800 prompt + 200 ya generados = 1 000 tokens vivos por request), techo de concurrencia $\approx 475$.

Paso 2 — duración media de una request. Prefill 800 tokens / 14 000 tps = 57 ms. Decode 250 tokens × 35 ms/token = 8 750 ms. Total $\approx 8.8$ s por request.

Paso 3 — throughput de la réplica. Si la réplica sostiene concurrencia operativa 40 y cada request dura 8.8 s, la réplica entrega aproximadamente $40 / 8.8 \approx 4.5$ requests/s en régimen estacionario.

Paso 4 — número de réplicas. Para 200 RPS objetivo: $200 / 4.5 \approx 45$ réplicas. Eso son 45 × 4 = 180 GPUs. Demasiado: este sizing no funciona porque el coste por request es alto.

Paso 5 — revisar palancas. Antes de comprar más hardware, hay tres palancas que se exploran en este orden:

Quantization. Bajar a FP8 reduce pesos a 17.5 GB/GPU (queda más VRAM para KV cache → más concurrencia), aproximadamente duplica tokens/s en decode (HBM saturada por la mitad), y degrada calidad MMLU típicamente 0.5–1.5 puntos en modelos como Llama 70B. Reescribiendo el cálculo en FP8: TPOT baja a ~18 ms, tiempo total por request a 4.7 s, RPS por réplica sube a ~8.5, réplicas necesarias ≈ 24, equivalente a 96 GPUs.
Speculative decoding. Con un drafter pequeño y aceptación del 60–70 %, TPOT efectivo cae 30–40 %. RPS por réplica sube a ~12, réplicas ≈ 17 = 68 GPUs.
Disaggregated serving. Separar prefill workers y decode workers permite escalar cada uno a la mezcla real del workload —ver Disaggregated serving—. Suele recortar otro 20–40 % bajo workloads asimétricos.

Paso 6 — sizing recomendado. Para el ejemplo, con FP8 + speculative decoding y un head-room del 25 %: 20 réplicas vLLM TP=4 sobre 80 H100 SXM. Si el equipo no quiere depender de quantization agresiva (BF16 puro para máxima fidelidad), el cálculo sube a 30 réplicas = 120 GPUs y obliga a renegociar SLO o presupuesto.

Paso 7 — escribir los supuestos. Esta es la parte que ningún sizing válido se salta. En el repo del equipo, junto al cálculo:

# sizing/llama70b-prod.yaml
fecha: 2026-06-01
slo:
 ttft_p95_ms: 1500
 tpot_p95_ms: 60
 rps_target: 200
workload:
 prompt_tokens_p50: 600
 prompt_tokens_p95: 1200
 output_tokens_p50: 180
 output_tokens_p95: 500
 asunto: chat productivo con RAG ligero
modelo:
 arquitectura: llama-70b-instruct
 formato_pesos: fp8
 motor: vllm-v1
hardware:
 gpu: H100-SXM-80GB
 topologia: TP=4 con NVLink intra-nodo
 red_inter_replica: 25 GbE
optimizaciones:
 - paged_attention
 - chunked_prefill
 - speculative_decoding (drafter llama-1.1b, aceptación esperada 65%)
asunciones_criticas:
 - utilizacion_hbm_eficiente: 0.55
 - head_room_pico_sobre_p95: 0.25
 - aceptacion_speculative_min: 0.55
plan_validacion:
 - benchmark vllm bench serve antes de procurement
 - canary 10% durante 7 días post-deploy

Sin este YAML, el cálculo no es reproducible un mes después.

Caso MoE: Mixtral 8×22B (~141 B totales, 39 B activos)

Los MoE cambian el cálculo en una dimensión clave: los pesos totales son grandes pero los pesos activos por token son pequeños. Para Mixtral 8×22B con top-2 routing:

VRAM de pesos: $141 \times 2 = 282$ GB BF16. Con TP=4 → 70 GB/GPU. No cabe en H100 80 GB con KV cache + activaciones. Hace falta TP=8 (~35 GB/GPU) o FP8 con TP=4 (~35 GB/GPU).
Decode TPOT: dominado por los pesos leídos por token, que son $\sim 39 / 8 \cdot 2 \approx 9.75$ GB/GPU con TP=4 (un experto top-2 por token, dividido entre 4 GPUs). En H100 con HBM 3.35 TB/s, TPOT teórico ≈ 3 ms/token. En la práctica, 10–20 ms a concurrencia razonable.
Prefill: similar al modelo denso de los pesos activos, ~39 B FLOPs/token.

El sizing MoE suele entregar más RPS por GPU que un denso equivalente — el coste por token bajo compensa el extra de VRAM. Ver MoE inference para el detalle del routing y por qué el batch alto es decisivo para que cada experto vea suficientes tokens.

Tabla de sensibilidad: contexto y quantization

Para Llama 70B sobre 4×H100 SXM (TP=4), concurrencia operativa por réplica con SLO TTFT 1.5 s / TPOT 60 ms:

Contexto promedio	BF16	FP8	INT4 (AWQ)
500 tokens	55	110	180
1 000 tokens	40	80	130
2 000 tokens	24	50	85
4 000 tokens	12	26	48
8 000 tokens	6	13	25

Números aproximados de benchmark vLLM público a junio 2026, con variación ±20 % según versión del motor y headroom adoptado. Para validar en tu hardware: vllm bench serve con tu perfil de prompts reales.

Las cinco trampas habituales

Trampa 1 — confundir media con P95. El throughput medio de una hora puede ser 50 RPS pero el pico de 5 minutos llegar a 180 RPS. Dimensionar contra la media garantiza romper SLO en cada pico. Regla: dimensionar contra P95 horario, con head-room del 20–30 % sobre P95.

Trampa 2 — no medir el reparto prefill/decode real. Un workload de “RAG con respuestas cortas” tiene 70–80 % del tiempo de GPU en prefill; un “writing assistant que genera ensayos” tiene 80 % en decode. Las optimizaciones útiles (chunked prefill vs speculative decoding) cambian radicalmente. Sin medirlo, se compra hardware mal balanceado.

Trampa 3 — dimensionar sin head-room para retrain ni rollback. El cluster productivo no es solo el motor de inferencia: hay batch de re-embeddings cuando cambia el modelo de embeddings, eval continuo de canary —ver Canary, blue-green y shadow—, fine-tune ligero, hot stand-by para rollback. Reservar 15–25 % de capacidad para esos workloads no negociables.

Trampa 4 — “GPU al 100 % de SM utilization” como objetivo. SM occupancy del 95 % con HBM saturada produce el mismo throughput que SM al 60 % con HBM saturada. El cuello de botella en decode es la HBM. Optimizar para “GPU usage 100 %” sin mirar HBM utilization y arithmetic intensity hace gastar más en GPU sin ganar throughput. Ver Observabilidad GPU para inferencia LLM para qué métricas mirar realmente.

Trampa 5 — no documentar los supuestos. Un sizing sin YAML reproducible (workload, modelo, motor, head-room, asunciones críticas) deja al equipo sin manera de saber qué cambió cuando el cluster ya no llega a SLO seis meses después. Documentar es barato; perder un trimestre depurando, no.

Aplicado a hardware on-premise típico

Para un cluster genérico de 4×H100 SXM 80 GB con NVLink intra-nodo y 25 GbE entre nodos, las configuraciones recurrentes en mayo 2026 son:

Modelo	Formato	TP	Réplicas que caben	RPS típico por nodo (ctx 1K)
Llama 8B	BF16	1	4 (una por GPU)	240–320
Llama 8B	FP8	1	4	450–600
Llama 70B	BF16	4	1	30–45
Llama 70B	FP8	4	1	60–90
Llama 70B	INT4 AWQ	2	2	90–130
Mixtral 8×22B	FP8	4	1	90–140
Qwen 72B	BF16	4	1	28–42

Estos números son órdenes de magnitud para empezar la conversación, no compromisos. El sizing definitivo se valida con vllm bench serve o genai-perf (NVIDIA) usando el perfil de prompts/outputs reales del cliente. La asimetría prefill/decode del workload de cada caso puede mover estos números un 30–50 % arriba o abajo.

Para clusters de 8×H100 SXM (típico de servidores DGX o réplicas equivalentes), las opciones se abren a TP=8 para modelos clase 405B o multi-réplica TP=2 para modelos 70B con mayor densidad. La métrica que decide es siempre la misma: tokens cumpliendo SLO por kW y por euro de hardware amortizado.

Cómo se valida el sizing antes de comprar

El sizing en hoja de cálculo es la primera mitad. La segunda es el benchmark de validación.

Stage 1 — sizing servilleta. Las fórmulas de este post sobre el SLO y el workload esperado. Salida: número aproximado de réplicas y topología.

Stage 2 — micro-benchmark sintético. En una GPU prestada o alquilada por días, levantar el motor con el modelo elegido y correr vllm bench serve con prompts de longitudes representativas. Validar TPOT, prefill TPS y techo de concurrencia. Calibrar el factor de eficiencia HBM ($\eta$) usado en las fórmulas.

Stage 3 — load test con tráfico realista. Generar tráfico siguiendo la distribución real del workload del cliente (no Poisson, no constante: la traza real). Medir P50/P95/P99 de TTFT, TPOT, throughput. Confirmar el head-room.

Stage 4 — canary en producción. Con el cluster dimensionado, encaminar el 5–10 % del tráfico real durante 7–14 días antes de cerrar el procurement de hardware adicional. Ver Canary, blue-green y shadow para la mecánica.

Saltar de Stage 1 a procurement total es la causa más frecuente de cluster sobredimensionado en el 40 % y subdimensionado en el 60 % al mismo tiempo, en regiones distintas del workload. Cuatro semanas de validación bien hechas ahorran cuatro meses de refactor.

Lo que no hemos cubierto (próximos artículos)

Las métricas de observabilidad que cierran el bucle del sizing en producción — ver Observabilidad GPU para inferencia LLM.
El autoscaling que ajusta réplicas a la curva real de tráfico — ver Autoscaling LLM en Kubernetes.
El cost accounting detallado por tenant (showback / chargeback) sobre el hardware dimensionado.
El sizing para fine-tuning continuo (PEFT y entrenamiento ligero) que comparte cluster con la inferencia.

Ver también

KV cache: la memoria de trabajo que sostiene la inferencia LLM — el componente que domina el presupuesto de VRAM.
Continuous batching — qué define la utilización efectiva del compute y la métrica goodput.
Disaggregated serving prefill/decode — palanca avanzada para workloads asimétricos.
MoE inference — cómo cambian las cuentas con modelos MoE.
Quantization para inferencia — qué cuesta y qué ahorra cada formato.
Siete capas del stack de inferencia LLM on-premise — las piezas que el sizing presupone.
Entornos mixtos NVIDIA + Intel para inferencia LLM — el sizing cierra mejor cuando se acepta heterogeneidad: embeddings y reranker en Intel Xeon AMX liberan H100 para el LLM grande, sin comprar más GPU.
NUMA, hugepages y aislamiento de CPU y Resource managers de RKE2 — por qué el sizing pasa a razonarse por NUMA node y no por nodo: hay que descontar los cores housekeeping reservados y comprobar que el pod cabe en una sola “mesa” NUMA.

Referencias

Kwon et al. — vLLM: Easy, Fast, and Cheap LLM Serving with PagedAttention (SOSP 2023).
Zhong et al. — DistServe: Disaggregating Prefill and Decoding for Goodput-optimized LLM Serving (OSDI 2024).
Agrawal et al. — Taming Throughput-Latency Tradeoff in LLM Inference with Sarathi-Serve (OSDI 2024).
NVIDIA — H100 Tensor Core GPU Architecture Whitepaper (memoria HBM3, bandwidth, FLOPs sostenidos).
vLLM project — vllm bench serve reference (CLI de benchmarking incluida en el repo).
NVIDIA — genai-perf (herramienta oficial para benchmark de servicios LLM).

Controles técnicos: el mapeo cruzado ENS × ISO 42001 × EU AI Act sobre la arquitectura LLM on-premise

Mon, 01 Jun 2026 06:30:00 +0200

Tercer post de la trilogía de gobernanza IA del blog. El primero — ISO/IEC 42001 — descompuso el sistema de gestión certificable. El segundo — EU AI Act — descompuso el reglamento legal directamente aplicable. Este cubre el tercer marco que aparece cuando el cliente es Administración Pública española o entidad de servicios esenciales: el ENS (Esquema Nacional de Seguridad, Real Decreto 311/2022). El reto editorial: el cumplimiento triple no es la suma aritmética de los tres trabajos; es un solo conjunto de evidencias técnicas etiquetadas para tres lentes. Este post desmonta cómo se construyen esas evidencias por medida ENS.

TL;DR

El Real Decreto 311/2022 actualizó el Esquema Nacional de Seguridad (ENS) español alineándolo con NIS2 y con el panorama de ciberamenazas moderno. Aplica obligatoriamente a todo el sector público español (administración general, autonómica, local, universidades, organismos autónomos) y a proveedores que les presten servicios IT. La norma define 74 medidas de seguridad organizadas en tres bloques (marco organizativo org, marco operacional op, medidas de protección mp), tres categorías de aplicación (Básica / Media / Alta) según valoración de las cinco dimensiones (Confidencialidad, Integridad, Trazabilidad, Autenticidad, Disponibilidad), y un anexo II con la matriz medida × categoría que dicta qué se exige en cada nivel. Este post mapea las medidas técnicas relevantes para sistemas LLM (las del bloque op planificación / control acceso / explotación / servicios externos / continuidad / monitorización, y las del bloque mp comunicaciones / aplicaciones / información / servicios) contra el Annex A de ISO/IEC 42001 y los artículos operativos del EU AI Act (Arts. 9 a 15, 17, 72 y 73), y muestra que el solapamiento es masivo: un único artefacto técnico del stack OSS del blog —los spans OTel del tracing, los datasets versionados con DVC, los scanners de LLM Guard, las decisiones de guardrail, los incidentes del retrain— satisface simultáneamente medidas ENS, controles 42001 y artículos del AI Act, siempre que se etiquete con los códigos correctos desde su captura. La tesis editorial: la diferencia entre un sistema que pasa los tres audits y uno que sufre tres certificaciones separadas no es presupuesto, es etiquetado disciplinado y vocabulario común. El post construye la tabla maestra de cumplimiento triple, recorre el caso del chatbot multi-tenant para Administración Pública Categoría Alta como checklist vivo, y cierra con las cinco trampas del cumplimiento triple.

La analogía: la inspección triple del edificio crítico

Un edificio crítico —el centro de control de la red eléctrica de una autonomía, un hospital de referencia, un centro de respuesta de emergencias 112— pasa tres inspecciones distintas sobre los mismos elementos físicos:

La inspección autonómica revisa licencia urbanística, normativa contra incendios local, accesibilidad según legislación regional.
La inspección europea revisa marcado CE de equipamiento, conformidad con directivas EU sobre eficiencia energética.
La inspección de calidad ISO revisa procesos y mantenimiento bajo norma de gestión.

Los tres inspectores miran el mismo detector de incendios colgado del techo. La autonómica quiere ver el certificado de instalación con número de empresa instaladora; la europea quiere ver la marca CE estampada en la carcasa; la ISO quiere ver el registro de mantenimiento mensual con firmas. El detector es uno solo. La evidencia que cada inspector necesita es distinta. Si el equipo de gestión del edificio guardara una carpeta por inspector, el certificado de instalación, la foto de la marca CE y la hoja de mantenimiento vivirían en tres sitios y el día de la auditoría se descubrirían inconsistencias entre las tres carpetas. La forma profesional de operar: un solo expediente por activo, con etiquetas que apuntan a las tres legislaciones.

El sistema LLM on-premise es ese edificio crítico. Los spans OTel del tracing son el detector de incendios: una sola pieza técnica que satisface la medida ENS op.exp.8 (registro de actividad), el control 42001 A.8.2 (información a partes interesadas), y el artículo EU AI Act 12 (record-keeping) si los spans llevan la metadata correcta: traceparent propagado, gen_ai.* semantic conventions, retención WORM, PII redactada por LLM Guard Vault. Sin etiquetado consistente desde la captura, el día de la auditoría hay tres carpetas que no cuadran.

La analogía importa porque acota una decisión arquitectónica: el etiquetado de evidencia no es un tema de compliance, es un tema de diseño técnico. Se decide cuando se monta el OTel Collector, cuando se diseña el schema del Vault, cuando se acuerda el formato de los incidentes de retrain. Si se posterga, la deuda compounds.

ENS en 15 segundos

Marco regulatorio: Real Decreto 311/2022, de 3 de mayo, vigente desde el 5 de mayo de 2022. Sustituye al RD 3/2010. Implementa la actualización del Esquema con NIS2, NCS (Estrategia Nacional de Ciberseguridad) y la realidad post-2020.
Ámbito obligatorio: sector público español (administración general, autonómica, local, universidades, organismos autónomos), entidades del sector público con personalidad jurídica propia, proveedores privados que les presten servicios IT (cláusula muy importante en consultoría: si tu cliente es Junta de Andalucía, Comunidad de Madrid o Ayuntamiento de Bilbao, tú estás bajo ENS por extensión contractual).
Aplicabilidad operativa 2026: cualquier proyecto IA financiado con fondos europeos NextGenerationEU + cualquier proyecto con datos públicos + cualquier integración con sistemas administrativos electrónicos.
Categorización: tres categorías Básica / Media / Alta según valoración de las cinco dimensiones (C, I, T, A, D). La categoría dicta qué medidas se exigen y con qué profundidad.
Certificación: para Categoría Media y Alta, auditoría formal por entidad acreditada. Para Categoría Básica, autoevaluación. Ciclo de certificación bienal.
Autoridad: Centro Criptológico Nacional (CCN-CERT), dependiente del CNI. Mantiene el portal ens.ccn.cni.es con guías STIC (Series 800).
Número total de medidas: 74 organizadas en tres bloques + anexo II con matriz medida × categoría que define qué aplica en cada nivel.

Las cinco dimensiones de seguridad y su mapeo IA

Para clasificar el sistema en categoría Básica / Media / Alta, el ENS pide valorar cada dimensión en una escala (no aplicable / bajo / medio / alto). La categoría final es la más alta de las cinco. Para sistemas LLM, la valoración típica:

Dimensión	Significado	Valoración típica LLM	Razón
C Confidencialidad	Información protegida de divulgación	Media-Alta	PII en prompts, secretos en context, propiedad intelectual del corpus RAG
I Integridad	Información protegida de modificación	Media-Alta	RAG corpus alterado → respuestas falsas; modelo manipulado → bias dirigido
T Trazabilidad	Acciones imputables a usuarios	Alta	Auditoría: ¿quién pidió qué, cuándo, qué se le respondió, qué dataset entrenó el modelo?
A Autenticidad	Identidad de usuarios y origen de información	Media	Autenticación robusta + identificación de chunks por fuente
D Disponibilidad	Servicio disponible cuando se necesita	Media	SLA típico, recovery time conocido

Resultado típico: Categoría Media para sistemas LLM internos sin datos sensibles, Alta si manejan PII o datos sectoriales regulados (sanidad, fiscal, judicial). La categoría dispara controles distintos.

Los tres bloques de medidas

Marco organizativo (org) — 4 medidas que aplican siempre, transversales:

org.1 Política de seguridad
org.2 Normativa de seguridad
org.3 Procedimientos de seguridad
org.4 Proceso de autorización

Marco operacional (op) — 31 medidas en 6 subgrupos, son el cómo se opera:

op.pl Planificación (5)
op.acc Control de acceso (6)
op.exp Explotación (10)
op.ext Servicios externos (4)
op.cont Continuidad del servicio (4)
op.mon Monitorización del sistema (2)

Medidas de protección (mp) — 39 medidas en 7 subgrupos, son qué se protege:

mp.if Protección instalaciones (7)
mp.per Gestión personal (4)
mp.eq Protección equipos (4)
mp.com Protección comunicaciones (4)
mp.si Protección soportes información (5)
mp.sw Protección aplicaciones (2)
mp.info Protección información (6)
mp.s Protección servicios (4)

De estas 74, las que importan operativamente para sistemas LLM son aproximadamente 25. Las restantes son bien transversales (políticas, gestión personal, instalaciones físicas), bien específicas de otras capas (telefonía, soportes físicos en sentido literal). El resto del post baja a las 25 relevantes.

Mapeo técnico: medidas ENS clave × controles 42001 × artículos EU AI Act

A continuación, por subgrupo ENS, las medidas relevantes para LLM con su mapeo cruzado. La columna Evidencia técnica del blog apunta al artefacto operativo que materializa la medida.

Marco operacional — planificación (`op.pl`)

Medida ENS	Exigencia	Control 42001	Artículo AI Act	Evidencia técnica
`op.pl.1` Análisis de riesgos	Análisis formal periódico, metodología MAGERIT u OCTAVE	A.5.4 (alignment with AI risk treatment)	Art. 9 Risk management	Documento riesgos vinculado a pipeline LLMOps + evals métricas
`op.pl.2` Arquitectura de seguridad	Documentación de arquitectura, segregación de capas	A.4.2 documented info	Art. 15 (technical robustness)	Siete capas stack + siete fases despliegue
`op.pl.3` Adquisición	Criterios de adquisición que incluyen seguridad	A.10.3 suppliers	Art. 53 (GPAI obligations)	OSS vs hyperscalers análisis lock-in + análisis copyright
`op.pl.4` Dimensionamiento	Capacidad para soportar carga prevista	A.4.5 system resources	Art. 15 (consistent performance)	Cinco niveles madurez + estudio capacidad GPU
`op.pl.5` Componentes certificados	Preferencia por componentes con certificación	A.10.5 third parties	Art. 53 + Art. 15	Inventario OSS con análisis licencia + auditoría supply chain (cosign + SLSA)

Marco operacional — control de acceso (`op.acc`)

Medida ENS	Exigencia	Control 42001	Artículo AI Act	Evidencia técnica
`op.acc.1` Identificación	Identificación única usuarios y procesos	A.3.2 roles	Art. 14 (human oversight)	Keycloak / OIDC + JWT con `sub` único + `user_id_hashed` en spans OTel
`op.acc.2` Requisitos de acceso	Necesidad de saber, autorización	A.9.4 intended use	Art. 14 + Art. 26 (deployer)	Allowlist por tenant en AI Gateway + RBAC sobre adapters
`op.acc.3` Segregación de funciones	Sin acumulación incompatible	A.3.2 + A.3.3	Art. 17 (QMS)	Roles separados: AI lead / data steward / SRE / DPO
`op.acc.5` Autenticación	Mecanismo proporcional, MFA en Alta	A.4.4 tooling	Art. 14	Keycloak + WebAuthn + MFA obligatorio Cat. Alta
`op.acc.6` Acceso local	Protección contra acceso físico	mp.if + A.4.5	Art. 15 (cybersec)	Cluster en CPD con control físico (fuera del scope del blog en sentido estricto)
`op.acc.7` Acceso remoto	VPN, cifrado, control endpoint	A.4.5 + mp.com	Art. 15	WireGuard / Defguard + mTLS para acceso administrativo al cluster

Marco operacional — explotación (`op.exp`)

Es el subgrupo más denso y el que más solapa con la arquitectura LLM.

Medida ENS	Exigencia	Control 42001	Artículo AI Act	Evidencia técnica
`op.exp.1` Inventario activos	CMDB con todos los componentes del sistema	A.4 resources	Art. 49 (EU DB registration)	Inventario de modelos, adapters, datasets en CMDB + tags Helm + lineage OpenLineage
`op.exp.2` Configuración seguridad	Configuración endurecida documentada	mp.eq + A.4	Art. 15	Configuraciones vLLM, KServe, Cilium documentadas en GitOps + CIS Benchmarks K8s
`op.exp.3` Gestión de configuración	Cambios trazables y autorizados	A.6.2 + A.4.2	Art. 9 + Art. 15	GitOps con Argo CD / Flux + PR review obligatoria + immutable tags
`op.exp.5` Gestión de cambios	Cambios planificados, autorizados, registrados	A.6.2.6 + cláusula 8	Art. 9 (lifecycle) + Art. 72 (post-market)	Pipeline CI/CD del post LLMOps + change advisory board
`op.exp.6` Protección código dañino	Antivirus, EDR, control malware	mp.eq	Art. 15 (cybersec)	Image scanning (Trivy / Grype) + container runtime security (Falco / Tetragon)
`op.exp.7` Gestión de incidentes	Procedimiento detección → respuesta → recuperación	A.3.3 + cláusula 10	Art. 73 (serious incidents reporting)	Retrain incident-driven + canal CCN-CERT + plantilla notificación
`op.exp.8` Registro de actividad	Logs auditables, retención mínima 2 años Cat. Alta	A.8.2	Art. 12 + Art. 19	Tracing OTel GenAI + Tempo / Jaeger + Loki
`op.exp.9` Registro gestión incidentes	Bitácora de incidentes con causa raíz, acción correctiva	cláusula 10	Art. 73	Sistema ticketing + retrain incident events estructurados
`op.exp.10` Protección registros	Logs inmutables, integridad criptográfica, retención garantizada	A.8.2 + A.4.2	Art. 12	Storage WORM (Ceph + immutable bucket) + firma de logs (sigstore) + retención 24-36 meses
`op.exp.11` Claves criptográficas	Gestión ciclo vida claves, HSM en Cat. Alta	mp.info.4	Art. 15	HashiCorp Vault / SOPS + HSM (Yubico, AWS KMS on-prem) para Cat. Alta

Marco operacional — servicios externos (`op.ext`)

Crítico cuando el sistema integra GPAI (Llama, Mistral) hospedado fuera o cuando el deployer es tercero.

Medida ENS	Exigencia	Control 42001	Artículo AI Act	Evidencia técnica
`op.ext.1` Contratación de servicios externos	Contrato con cláusulas seguridad, SLA, derecho auditoría	A.10.3 suppliers	Art. 25 + Art. 53	Contrato con cláusulas ENS + revisión auditoría anual + análisis Cloud Act
`op.ext.2` Medios alternativos	Plan B ante caída del proveedor	A.4.5 + cláusula 6	Art. 15 (resilience)	Multi-cluster con failover + GPAI alternativos calificados (Llama→Mistral→Qwen)
`op.ext.3` Protección cadena suministro	Evaluación de proveedores y subproveedores	A.10 + cláusula 6	Art. 53 + NIS2 supply chain	SBOM + cosign + SLSA + vulnerability scanning continuo
`op.ext.4` Interconexión sistemas	Acuerdos de interconexión, gateways seguros	mp.com + A.4.5	Art. 15	API Gateway con mTLS + JWT signing + rate limiting + WAF

Marco operacional — continuidad (`op.cont`)

Medida ENS	Exigencia	Control 42001	Artículo AI Act	Evidencia técnica
`op.cont.1` Análisis de impacto	BIA por sistema	A.5.5 (impacts on individuals)	Art. 9 (risk management)	BIA documentado con RPO / RTO por sistema
`op.cont.2` Plan de continuidad	DRP documentado, RTO/RPO	cláusula 6 + A.4	Art. 15 (resilience)	DRP + Velero backups K8s + datasets DVC en bucket secundario
`op.cont.3` Pruebas periódicas	Simulacros con frecuencia (anual Cat. Alta)	cláusula 9 (evaluation)	Art. 15	Game-day anual con desastre simulado + cronos de recuperación
`op.cont.4` Medios alternativos	Capacidad de continuar con medios degradados	cláusula 6 + A.4.5	Art. 15	Cluster secundario en CPD distinto + GPU pool reservado + datasets replicados

Marco operacional — monitorización (`op.mon`)

Medida ENS	Exigencia	Control 42001	Artículo AI Act	Evidencia técnica
`op.mon.1` Detección de intrusión	IDS/IPS sobre red y aplicaciones	A.9.2 use	Art. 15 (cybersec)	Guardrails como WAF semántico + LLM Guard PromptInjection + Tetragon eBPF runtime
`op.mon.2` Sistema de métricas	Métricas operativas medibles, dashboard auditable	cláusula 9 (performance evaluation)	Art. 72 (post-market monitoring)	Prometheus + VictoriaMetrics + Grafana + Langfuse dashboards
`op.mon.3` Vigilancia (Cat. Alta)	Monitorización 24×7 con alertado	cláusula 9 + cláusula 10	Art. 72 + Art. 73	SOC con alertas SIEM (Wazuh, OpenSearch, Vector + custom) + on-call rotation

Medidas de protección — comunicaciones (`mp.com`)

Medida ENS	Exigencia	Control 42001	Artículo AI Act	Evidencia técnica
`mp.com.1` Perímetro seguro	Firewall, segmentación, DMZ	A.4.5	Art. 15	Cilium NetworkPolicy + Calico + ingress controllers con WAF (mod_security)
`mp.com.2` Protección confidencialidad	Cifrado en tránsito (TLS 1.2+ obligatorio, 1.3 recomendado)	A.4.5	Art. 15	TLS 1.3 obligatorio + cert-manager + Let’s Encrypt o CA interna
`mp.com.3` Protección integridad y autenticidad	Cifrado + autenticación de origen	A.4.5 + A.4.4	Art. 15	mTLS intra-cluster + JWT signing en gateway + checksums en artifacts
`mp.com.4` Separación de flujos	Segmentación tráfico mgmt vs producción vs externo	A.4.5	Art. 15	Cilium policies + Network Namespaces + east-west / north-south segregation

Medidas de protección — aplicaciones (`mp.sw`)

Medida ENS	Exigencia	Control 42001	Artículo AI Act	Evidencia técnica
`mp.sw.1` Desarrollo aplicaciones	SDLC seguro, code review, SAST/SCA	A.6.2.3 design responsable	Art. 9 + Art. 15	Forgejo CI con SAST (Semgrep, CodeQL) + SCA (Trivy, Grype) + revisión PR obligatoria
`mp.sw.2` Aceptación y puesta en servicio	Tests de aceptación, eval gates antes producción	A.6.2.5 V&V	Art. 9 + Art. 15	Eval gates del post evals + canary deploy + métricas pre-go-live

Medidas de protección — información (`mp.info`)

Medida ENS	Exigencia	Control 42001	Artículo AI Act	Evidencia técnica
`mp.info.1` Datos de carácter personal	Cumplimiento RGPD + medidas técnicas y organizativas	A.5.5 + A.7.6	Art. 10 + Art. 26	LLM Guard Vault + Presidio + minimización en RAG corpus curation
`mp.info.2` Calificación información	Etiquetado por nivel (público / interno / confidencial / restringido)	A.7.2 data	Art. 10	Schema contracts del data versioning con campo `classification`
`mp.info.3` Cifrado	At-rest mínimo Cat. Media, Cat. Alta con HSM	A.4.5 + mp.eq	Art. 15	LUKS / dm-crypt en discos + cifrado en bucket Ceph + claves en Vault
`mp.info.4` Firma electrónica	Documentos firmados con certificado válido (Cat. Media+)	A.8.2	Art. 12	Firma de logs con sigstore + firma de modelos publicados con cosign
`mp.info.5` Sellos de tiempo	Sello cualificado para integridad temporal (Cat. Alta)	A.8.2	Art. 12	Timestamping con TSA cualificada + RFC 3161 en eventos críticos
`mp.info.6` Limpieza de documentos	Eliminación de metadatos no autorizados, anonimización	A.7.6 + A.5.5	Art. 10	LLM Guard Anonymize (input) + Sensitive (output) + Vault con TTL

Medidas de protección — servicios (`mp.s`)

Medida ENS	Exigencia	Control 42001	Artículo AI Act	Evidencia técnica
`mp.s.1` Correo electrónico	Anti-spam, anti-malware, cifrado opcional	A.4.5	—	Fuera del scope LLM directo
`mp.s.2` Protección servicios y aplicaciones web	WAF, hardening, gestión vulnerabilidades	A.9.2 + mp.com	Art. 15 (cybersec)	AI Gateway (LiteLLM / Envoy AI / Kong AI) con políticas + ModSecurity + Cloudflare-like
`mp.s.3` Protección frente a denegación de servicio	Rate limiting, anti-DDoS, capacity planning	A.4.5 + A.9.2	Art. 15	Rate limiting en gateway + token quotas + circuit breakers
`mp.s.4` Protección frente a amenazas exteriores (Cat. Alta)	Monitorización avanzada, threat intel	A.9.2 + cláusula 9	Art. 15 + Art. 72	Guardrails 4 líneas + LLM Guard scanners avanzados + threat intel feed (CCN-CERT MISP)

Tabla maestra de cumplimiento triple — los 25 controles relevantes consolidados

La lectura clave del cuadro: una sola fila por capacidad técnica. La organización no construye tres soluciones para “log de actividad” (ENS) + “información partes interesadas” (42001) + “record-keeping” (AI Act). Construye una sola pieza de tracing OTel con la metadata correcta y la presenta etiquetada según el inspector.

El etiquetado se materializa típicamente en tres mecanismos:

Tags en los pipelines CI/CD: cada artefacto producido lleva tags ens:op.exp.8, iso42001:A.8.2, aia:art.12 en su metadata Helm / Argo CD.
Atributos OTel semánticos: gen_ai.compliance.ens = "op.exp.8", gen_ai.compliance.iso42001 = "A.8.2" como custom attributes en los spans relevantes (no estándar todavía, pero útil interno).
Mapping table en wiki: documento vivo medida ENS → control 42001 → artículo AI Act → runbook técnico + dueño + última verificación. Es el artefacto que el auditor consulta.

Caso aplicado: chatbot multi-tenant para Administración Pública

Variante del chatbot multi-tenant del post forense — ahora el cliente es una Junta autonómica española que ofrece asistencia ciudadana sobre trámites administrativos. Las tres miradas:

ENS: aplica obligatoriamente por ser sector público + servicio a ciudadanos. Categoría Alta (PII de ciudadanos + servicio crítico).
ISO 42001: la Junta solicita certificación al proveedor como requisito contractual.
EU AI Act: si el chatbot informa sobre trámites pero no decide nada por el ciudadano, riesgo limitado (Art. 50 transparencia). Si automatiza decisiones (admisión a programa, denegación de ayuda), alto riesgo.

Asumimos alto riesgo para el recorrido más exigente.

Las 25 capacidades técnicas clave del chatbot consolidadas

Capacidad técnica	ENS	42001	AI Act	Estado
Autenticación robusta ciudadanos	`op.acc.5` (MFA Cat. Alta)	A.4.4	Art. 14	Cl@ve + Cert. digital + WebAuthn
Identificación única tenant + usuario	`op.acc.1`	A.3.2	Art. 14 + 26	JWT con `tenant_id` + `user_id_hashed`
Allowlist por tenant	`op.acc.2`	A.9.4	Art. 14	LiteLLM Proxy con policies + Envoy filter
Cifrado en tránsito mTLS	`mp.com.2-3`	A.4.5	Art. 15	TLS 1.3 + cert-manager + mTLS intra-mesh
Cifrado en reposo + claves HSM	`mp.info.3` + `op.exp.11`	A.4.5	Art. 15	LUKS + Vault + HSM Yubikey o nCipher
Anonimización PII input/output	`mp.info.1 + .6`	A.7.6	Art. 10	LLM Guard Vault + Presidio + Llama Guard 4
Logging trazable + WORM	`op.exp.8 + .10`	A.8.2	Arts. 12 + 19	OTel + Tempo + Loki + Ceph WORM 36 meses
Firma de logs + sellos tiempo	`mp.info.4 + .5`	A.8.2	Art. 12	sigstore + TSA cualificada (FNMT)
Detección amenazas runtime	`op.mon.1 + mp.s.4`	A.9.2	Art. 15	Guardrails 4 líneas + Tetragon + Falco
Métricas operativas dashboard	`op.mon.2`	cláusula 9	Art. 72	Prometheus + Grafana + Langfuse
Vigilancia 24×7 SOC	`op.mon.3` (Cat. Alta)	cláusula 9	Art. 72	SOC con SIEM + on-call rotation
Gestión incidentes con notificación	`op.exp.7 + .9`	cláusula 10	Art. 73	Retrain incident-driven + canal CCN-CERT
Pipeline CI/CD con eval gates	`mp.sw.1 + .2`	A.6.2.3-5	Arts. 9 + 15	Forgejo CI + Semgrep + Trivy + DeepEval gates
Backups + DRP	`op.cont.1-4`	cláusula 6 + A.4	Art. 15	Velero + datasets DVC en bucket secundario + game-day anual
Análisis riesgos sistemático	`op.pl.1`	A.5 + cl.6	Art. 9	MAGERIT + FRIA + impact assessment ISO/IEC 23894
Arquitectura segura documentada	`op.pl.2`	A.4.2	Art. 15	Siete capas + siete fases
Gestión proveedores	`op.ext.1 + .3`	A.10.3	Art. 53	Contratos con cláusulas ENS + SBOM + análisis Cloud Act por GPAI
Componentes certificados	`op.pl.5`	A.10.5	Art. 53	Inventario con licencia + auditoría supply chain
Hardening configuración	`op.exp.2 + .3`	A.4 + A.6	Art. 15	CIS Benchmarks K8s + GitOps + immutable tags
Protección código dañino	`op.exp.6`	mp.eq	Art. 15	Image scanning + runtime security
Inventario activos	`op.exp.1`	A.4	Art. 49	CMDB + tags Helm + OpenLineage
Segmentación red	`mp.com.4`	A.4.5	Art. 15	Cilium NetworkPolicy + namespaces
Rate limiting + anti-DoS	`mp.s.3`	A.4 + A.9	Art. 15	LiteLLM rate limit + token quotas
Calificación información	`mp.info.2`	A.7.2	Art. 10	Schema contracts con campo `classification`
Transparencia hacia usuario	—	A.9.4	Art. 50	Banner UI + disclaimer en respuestas

Resultado: las 25 capacidades técnicas son comunes a los tres marcos. Solo dos exigen evidencia de un solo marco aisladamente: mp.info.4-5 (firma y sello cualificados — ENS-específico, no exigido tan literalmente por 42001 o AI Act) y Art. 50 (transparencia banner — AI Act-específico). El resto son la misma pieza técnica con tres etiquetas. Un equipo bien organizado certifica los tres en serie con incremento marginal de trabajo entre el segundo y el tercero.

Las cinco trampas del cumplimiento triple

Trampa 1 — Medir tres veces lo mismo. Equipos novatos crean tres dashboards distintos (uno para ENS, otro para 42001, otro para AI Act) con las mismas métricas duplicadas. Resultado: tres fuentes de verdad que divergen, tres equipos auditores con cifras distintas, tres correcciones para resolver una misma desviación. La regla: una métrica, tres etiquetas.

Trampa 2 — Perder el control que solo cubre una norma. El mp.info.4 (firma electrónica) es ENS-específico y se olvida cuando el equipo está concentrado en 42001 + AI Act. El día del audit ENS aparece el hueco. Solución: la tabla maestra mantiene visibles todos los controles, incluidos los huérfanos.

Trampa 3 — Sesgo hacia la norma más reciente. El equipo dedica el 80% del esfuerzo al AI Act por ser el más nuevo y olvida el rigor del ENS que lleva 14 años en vigor. Las medidas ENS son más prescriptivas técnicamente que el AI Act (que es legalmente más estricto pero deja libertad implementativa). Subir un nivel a Cat. Alta ENS introduce exigencias específicas (HSM, sellos cualificados, vigilancia 24×7) que el AI Act no detalla. Hay que respetar el ENS por su detalle técnico, no por su estatura legal.

Trampa 4 — Mezclar Cat. Media y Alta del ENS. La matriz del Anexo II del RD 311/2022 dicta qué medidas se exigen y con qué profundidad por categoría. Subir de Media a Alta cambia 15-20 controles (no es marginal). La categoría se decide al inicio del proyecto y se documenta; cambiarla a mitad fuerza reauditoría completa.

Trampa 5 — Audit fatigue dentro del equipo técnico. Tres auditorías al año (ENS bienal + 42001 anual seguimiento + AI Act ad-hoc por autoridad) agota al equipo si no se planifican y reutilizan evidencias. La forma profesional: un solo ciclo de auditoría interna trimestral con scope rotativo, que produce evidencia consumible por los tres auditores externos. La diferencia entre 30 días/año y 90 días/año de trabajo perdido en auditorías es la disciplina de evidencia única + etiquetado disciplinado.

Lo que no hemos cubierto (próximos posts)

Las series STIC del CCN-CERT aplicables a sistemas IA: STIC 800-159 (operación servicios web), STIC 800-105 (criptografía), STIC 800-150 (entornos cloud). Cada una añade detalle técnico sobre cómo materializar las medidas ENS.
El RGPD como cuarta lente: privacidad y protección de datos personales. Solapa con mp.info.1 y con A.7.6 de 42001 + Art. 10 del AI Act. Material para una pasada análoga sobre LOPDGDD + RGPD + AEPD vs los tres marcos vistos.
Plantillas concretas de evidencia técnica con campos mínimos: log entry con todos los atributos requeridos por las tres miradas, incident report con todos los campos exigidos por las tres normas, declaración de conformidad ENS / AI Act / 42001 unificada.
Caso fondos NextGenerationEU: requisitos compliance específicos para proyectos IA financiados con fondos europeos, donde el AI Act + ENS son obligatorios contractualmente.
42001 + ENS Categoría Alta combinados con DORA (Digital Operational Resilience Act, Reg. 2022/2554) para entidades financieras españolas que despliegan IA.

Referencias

RD 311/2022 — por el que se regula el Esquema Nacional de Seguridad. https://www.boe.es/buscar/act.php?id=BOE-A-2022-7191.
CCN-CERT — Portal ENS: https://ens.ccn.cni.es/. Guías STIC Series 800.
CCN-STIC 803 — Valoración de los sistemas y de la información. Metodología para asignar categoría ENS.
CCN-STIC 804 — Esquema Nacional de Seguridad. Guía de implantación.
CCN-STIC 824 — Informe del estado de seguridad. Plantilla para auditoría ENS.
MAGERIT v3 — Metodología de Análisis y Gestión de Riesgos del Ministerio de Asuntos Económicos. Insumo de op.pl.1.
ISO/IEC 42001:2023 — Sistema de gestión IA. Norma certificable que solapa con ENS.
Regulation (EU) 2024/1689 (EU AI Act) — texto consolidado.
NIS2 (Dir. 2022/2555) — directiva de ciberseguridad que el ENS implementa parcialmente en su versión 2022.

Ver también

ISO/IEC 42001: el manual de operaciones del sistema de IA — el primer post de la trilogía de gobernanza, sistema de gestión certificable.
EU AI Act: el expediente técnico artículo por artículo — el segundo post, reglamento legal directo UE.
El pipeline LLMOps de seis etapas — la arquitectura operativa de referencia que sostiene los tres marcos.
Tracing LLM con OpenTelemetry GenAI — la pieza canónica que materializa op.exp.8 + .10 ENS + A.8.2 ISO 42001 + Arts. 12 + 19 AI Act simultáneamente.
Guardrails y safety en LLMs — la pieza que materializa op.mon.1 + mp.s.4 ENS + A.9.2 ISO 42001 + Art. 15 AI Act.
LLM Guard: el traductor jurado con cuaderno de equivalencias — la pieza que materializa mp.info.1 + .6 ENS + A.7.6 ISO 42001 + Art. 10 AI Act.
Data versioning con DVC y lakeFS y RAG corpus curation — las piezas que materializan mp.info.1-2 ENS + A.7 ISO 42001 + Art. 10 AI Act.
Retrain: cerrar el bucle feedback → dataset → adapter — la pieza que materializa op.exp.7 + .9 ENS + cláusula 10 ISO 42001 + Art. 73 AI Act.
Evals: la capa después del tracing — la pieza que materializa mp.sw.2 ENS + A.6.2.5 ISO 42001 + Art. 15 AI Act.
Siete capas del stack y siete fases del despliegue — el material directo para op.pl.2 arquitectura.
El catálogo paralelo OSS vs hyperscalers — insumo para op.ext.1 + .3 análisis proveedores + Art. 53 GPAI.
El catálogo OSS para LLMOps — inventario de componentes con licencias para op.exp.1.
Anatomía de una petición LLM en producción — el caso forense recorrido con la triple lente en este post.
Runbooks de incident response para LLM con Keep + Kafka — la pieza concreta que materializa op.exp.7-10 ENS + A.8.2 ISO 42001 + Art. 73 EU AI Act simultáneamente: workflows Keep declarativos + Kafka audit.actions WORM + plazos NIS2 24/72h/1mes.
Aislar agentes de IA: del workstation al cluster y su runbook operativo — el aislamiento de runtime (bubblewrap en el cliente, Tetragon en el cluster) como materialización de op.mon (monitorización) y op.exp (registro de actividad): los eventos eBPF de Tetragon son evidencia técnica de qué ejecutó cada agente y de cada intento de acceso bloqueado.

ISO/IEC 42001: el manual de operaciones del sistema de IA — cómo encaja el AIMS sobre la plataforma LLM on-premise descrita en el blog

Mon, 01 Jun 2026 06:00:00 +0200

Este post cierra una asimetría que el blog acumulaba: hemos descrito en detalle la plataforma técnica (siete capas del stack, siete fases del despliegue, cinco niveles de madurez), el pipeline operativo (seis etapas LLMOps), las piezas data (curación de corpus, versionado), las piezas eval / safety (evals, guardrails, LLM Guard) y las piezas observe (tracing OTel GenAI). Lo que no había aparecido es la capa de gobierno que un cliente regulado pide encima de todo eso. ISO/IEC 42001 es esa capa.

TL;DR

ISO/IEC 42001:2023 es la primera norma internacional certificable que define cómo se gestiona un sistema de IA. No es una norma técnica (no dice “usa este motor de inferencia” ni “este threshold de safety”): es una norma de gestión, prima de ISO 27001 e ISO 9001. Hereda de ambas la estructura Annex SL —siete cláusulas obligatorias que recorren contexto, liderazgo, planificación, soporte, operación, evaluación de desempeño y mejora— y añade un Annex A con 38 controles específicos de IA en 9 secciones: políticas, organización interna, recursos, impact assessment, ciclo de vida, datos, información a partes interesadas, uso, terceros. La tesis del post es que la arquitectura técnica descrita en este blog cubre directamente entre el 60% y el 80% de los controles A sin trabajo adicional —el pipeline LLMOps materializa A.6, el versionado y curación materializan A.7, los guardrails y evals materializan A.9, el tracing OTel materializa A.8—; el resto es disciplina de gobierno que no aparece en el código (política de IA escrita, impact assessments por sistema, registro de stakeholders, decisiones de roles entre provider/producer/customer, documentación obligatoria), y es precisamente lo que diferencia una certificación real de un cumplimiento performativo. El post mapea control a control la correspondencia, cruza con EU AI Act (siete artículos directamente alineados con 42001: 9, 10, 11, 12, 13, 14, 17), con NIS2 (asset register, incident notification, supply chain) y con ENS (RD 311/2022, categorías Básico/Medio/Alto), lista los siete documentos obligatorios mínimos que un auditor pide, presenta el caso del chatbot multi-tenant del blog como checklist 42001 vivo, y cierra con las cinco trampas habituales (confundir 42001 con cumplimiento EU AI Act, sobre-documentar sin medir, ignorar A.5 hasta el audit, asumir que 27001 cubre la parte AI, pensar que la certificación es un proyecto puntual y no un sistema vivo).

La analogía: el manual de operaciones del avión

Un avión moderno —un A350, un Boeing 787, un dron certificado para reparto urbano— no vuela porque tenga buenos motores. Vuela porque la organización que lo opera tiene un Manual de Operaciones aprobado por la autoridad aeronáutica (EASA en Europa, FAA en EEUU, AESA en España como delegada). El manual no contiene los planos del motor —eso lo certifica el fabricante—; contiene los procedimientos: quién es el comandante en cada vuelo, qué checklist se ejecuta antes de cada despegue, qué inspecciones periódicas se hacen a las 100, 500 y 2.000 horas de vuelo, qué proveedores externos están autorizados a tocar qué componentes, qué se documenta tras cada incidente, qué hacer cuando aparece una alerta nueva en el panel. La autoridad no se sienta en cada vuelo: lee el manual, audita aleatoriamente la trazabilidad de los vuelos pasados contra el manual, y si todo cuadra, mantiene la certificación.

Un sistema de IA en producción —el chatbot multi-tenant del post forense, un copiloto para abogados, un sistema de scoring crediticio— es exactamente lo mismo. Vuela porque el modelo es bueno, el pipeline LLMOps está bien montado, los guardrails atrapan los casos malos. Pero certifica porque la organización que lo opera tiene un AIMS (AI Management System) descrito en un manual auditable. ISO/IEC 42001 es ese manual: su índice obligatorio (Annex SL, siete cláusulas) y su catálogo de controles específicos de IA (Annex A, 38 controles). El auditor no se sienta junto al ingeniero MLOps: lee la política de IA, revisa los impact assessments de los últimos sistemas desplegados, comprueba que el retrain de incidentes está documentado, verifica los contratos con terceros, audita una muestra de trazas en Langfuse cruzadas con dataset_hash y prompt_id. Y si todo cuadra, certifica.

La analogía importa porque acota la pregunta correcta: 42001 no certifica el modelo ni el código. Certifica la forma de operar del sistema completo. Un equipo puede tener el mejor stack OSS del mundo y suspender la auditoría porque no tiene una política de IA escrita ni una decisión documentada sobre qué rol (provider vs producer vs customer) ocupa frente a sus clientes. Y viceversa: un equipo con un modelo modesto pero con disciplina de manual de operaciones puede certificar sin acrobacias.

ISO/IEC 42001 en 15 segundos

Publicación: diciembre de 2023, ISO/IEC JTC 1/SC 42 (el subcomité ISO/IEC de AI).
Estado en 2026: norma vigente, certificable por organismos acreditados (BSI, AENOR, TÜV, Bureau Veritas, A-LIGN, Schellman). Aún no reconocida formalmente como norma armonizada del EU AI Act, pero proporciona la base de gestión sobre la que apoyarse.
Compatibilidad: comparte la estructura Annex SL con ISO 9001 (calidad), 27001 (seguridad de la información), 27701 (privacidad), 22301 (continuidad), 20000-1 (servicios IT). Las organizaciones con sistemas de gestión integrados (IMS) la añaden con un esfuerzo del 20-40% del que costaría implantarla desde cero.
Aplicabilidad: cualquier organización que desarrolle, provea, despliegue o use sistemas de IA. No se limita a desarrolladores: una empresa que consume un LLM hospedado y lo integra en un producto propio está dentro del alcance.
Certificación: ciclo de 3 años con auditoría inicial (Stage 1: review documental + Stage 2: auditoría in-situ) y auditorías de seguimiento anuales. Coste típico: 15.000-60.000 € la inicial según tamaño; 6.000-20.000 € por seguimiento anual.

Lo que no hace 42001:

No dice qué modelos usar ni qué thresholds aplicar.
No certifica el modelo individual (eso lo hacen evaluaciones específicas tipo NIST AI RMF profile o EU AI Act technical documentation).
No sustituye al EU AI Act ni al RGPD: es complementaria. Implantarla bien facilita el cumplimiento legal pero no lo garantiza.
No es una norma técnica de explicabilidad ni de robustez (esas son ISO/IEC 25059, 24029, 23894 y otras de la familia SC 42).

Distinción con marcos vecinos

Marco	Naturaleza	Ámbito	Certificable	Solapamiento con 42001
ISO/IEC 42001:2023	Norma de gestión	AIMS para cualquier sistema IA	Sí	—
EU AI Act (Reg. 2024/1689)	Reglamento legal vinculante	Sistemas IA en UE, riesgo-categorizado	No (es ley)	Arts 9, 10, 11, 12, 13, 14, 17
NIS2 (Dir. 2022/2555)	Directiva ciberseguridad	Entidades esenciales/importantes	Vía Esquema Nacional	Asset register, incident, supply chain
ENS (RD 311/2022)	Reglamento español de seguridad	Sector público y sus proveedores	Sí (categorías B/M/A)	Trazabilidad, gestión incidentes
ISO/IEC 27001	Norma de gestión	Seguridad de información	Sí	Estructura Annex SL + Annex A solapan
ISO/IEC 27701	Norma de gestión	Privacidad (extiende 27001)	Sí	PII en datos de entrenamiento
NIST AI RMF 1.0	Marco voluntario	Risk management AI	No	Conceptualmente alineado, no idéntico
ISO/IEC 23894	Norma técnica	Risk management AI	No	Insumo de A.5 (impact assessment)
ISO/IEC 5259	Familia	Data quality for AI	No	Insumo de A.7 (data)

Tres distinciones que importan operativamente y que son fuente de confusión recurrente con clientes:

ISO 42001 ≠ EU AI Act compliance. Tener la certificación 42001 facilita demostrar artículos 9-17 del Reglamento europeo, pero el Reglamento exige más cosas que 42001 no cubre directamente (CE marking de sistemas de alto riesgo, registro en la base de datos europea, declaración de conformidad, post-market monitoring específico). Implantar 42001 primero y luego completar los huecos del AI Act es la ruta estándar.
ISO 27001 no es suficiente. 27001 cubre confidencialidad, integridad y disponibilidad de la información. Falta el lado AI: sesgo, opacidad, deriva del modelo, calidad del corpus de entrenamiento, evaluación humana, impacto sobre afectados. 42001 es complemento, no sustituto. Las organizaciones con 27001 ya implantado tienen ventaja porque comparten la mitad de la documentación.
NIS2 ≠ AI safety. NIS2 obliga a registrar activos críticos, notificar incidentes en 24 h, gestionar la cadena de suministro digital. Los sistemas de IA pueden estar dentro del alcance NIS2 si forman parte del activo crítico (un LLM que sirve atención al cliente en una entidad financiera lo está), pero NIS2 no audita la calidad del modelo. 42001 sí.

Las siete cláusulas (Annex SL): el índice obligatorio

Las siete cláusulas de la cláusula 4 a la 10 son comunes a todas las normas de gestión modernas (Annex SL, también llamado “High Level Structure”). Esto significa que una organización con ISO 9001 o 27001 ya implantada reconoce la estructura. Las cláusulas 1-3 son introductorias (alcance, referencias normativas, términos).

Cláusula 4 — Contexto de la organización

Identificar el contexto externo (regulación aplicable, expectativas de los clientes, riesgos sociales) y el contexto interno (estrategia, cultura, capacidades). Identificar las partes interesadas y sus expectativas: clientes, reguladores, afectados, empleados, proveedores. Definir el alcance del AIMS: qué sistemas de IA están dentro y cuáles fuera.

El gap habitual: organizaciones que dicen “todos nuestros sistemas IA están en el alcance” sin haberlos enumerado. El auditor pide la lista. Sin lista, no hay alcance.

Cláusula 5 — Liderazgo

La dirección debe aprobar y publicar una política de IA (AI policy), asignar roles y responsabilidades (típicamente AI lead, AI risk owner, data officer), y demostrar compromiso con recursos, comunicación y supervisión. La política es documento auditable y debe ser proporcionada al personal y partes interesadas.

El gap habitual: política de IA genérica copiada de internet, sin medibles ni objetivos concretos. El auditor pide cómo se mide su cumplimiento. Sin métricas, la política es teatro.

Cláusula 6 — Planificación

Identificar riesgos y oportunidades del AIMS (no del modelo individual). Definir objetivos de IA medibles, con plazos y responsables. Planificar los cambios al AIMS.

El gap habitual: confundir riesgos del AIMS (¿qué pasa si no documentamos correctamente?) con riesgos del modelo (¿qué pasa si el modelo sesga?). El primero va aquí; el segundo va a A.5.

Cláusula 7 — Soporte

Recursos humanos, técnicos, financieros, infraestructura. Competencia del personal (formación documentada). Conciencia del personal sobre la política. Comunicación interna y externa. Información documentada (la columna vertebral del SI: política, procedimientos, registros, evidencias).

El gap habitual: documentación dispersa en confluence/notion/drive sin control de versiones ni aprobaciones registradas. El auditor pide el último cambio: ¿quién lo aprobó? ¿cuándo? ¿con qué justificación?

Cláusula 8 — Operación

La cláusula más operativa. Exige:

Planificación y control operacional: cómo se gestiona el ciclo de vida del sistema de IA día a día. → Cubierto en el blog por pipeline LLMOps de seis etapas.
Impact assessment (vinculado a A.5).
Gestión del ciclo de vida del sistema de IA (vinculado a A.6).
Datos para sistemas de IA (vinculado a A.7).

Es la cláusula que se materializa en los controles A.5, A.6, A.7. Por sí sola no añade requisitos nuevos: enlaza con el Annex A.

Cláusula 9 — Evaluación del desempeño

Monitoreo, medición, análisis, evaluación. Auditorías internas (planificadas, con criterios, alcance, frecuencia, registro de resultados). Revisión por la dirección (típicamente trimestral o semestral, con agenda obligatoria: inputs, evidencia, decisiones, acciones).

El gap habitual: hay tracing OTel + Langfuse + Grafana y datos de sobra, pero no hay agenda formal de revisión por la dirección con minuta documentada. El auditor pide la minuta. Sin minuta, no hay revisión.

Cláusula 10 — Mejora

No conformidad y acción correctiva: cuando algo falla, se registra, se analiza causa raíz, se acuerda corrección, se verifica eficacia. Mejora continua: el sistema evoluciona deliberadamente.

El gap habitual: tickets de Jira con post-mortems técnicos pero sin registro formal de “no conformidad ISO” que cierra con verificación de eficacia. Son dos artefactos distintos aunque puedan integrarse.

Los 38 controles del Annex A: el catálogo AI-específico

A diferencia del Annex SL (común), el Annex A es la firma AI-específica de la 42001. Los 38 controles se organizan en 9 secciones (A.2 a A.10; A.1 es la introducción) que cubren los riesgos AI-específicos: opacidad, sesgo, deriva, calidad del corpus, impacto sobre afectados, dependencia de terceros. Cada control tiene objetivo (qué se quiere conseguir) y guidance de implementación en el Annex B.

Sección	Foco	# controles
A.2	Políticas relacionadas con IA	2
A.3	Organización interna	3
A.4	Recursos para sistemas IA	6
A.5	Evaluación de impactos	5
A.6	Ciclo de vida del sistema IA	4
A.7	Datos para sistemas IA	5
A.8	Información para partes interesadas	4
A.9	Uso de sistemas IA	3
A.10	Terceros y relaciones con clientes	4
Total	—	38

Lo que sigue es el mapeo control por sección al material que ya hemos cubierto en el blog. La intención editorial es enseñar qué huecos quedan después de tener implementada la arquitectura técnica, para que el camino a certificación no empiece desde cero.

Mapeo cruzado: 38 controles ↔ posts del blog

A.2 — Políticas de IA (2 controles): PARCIAL

A.2.2 AI policy: la organización debe tener una política de IA documentada, aprobada por dirección, revisada periódicamente, comunicada y disponible. Cubre principios, alcance, compromisos.
A.2.3 Alignment with other policies: la política de IA no es huérfana — se alinea con políticas existentes de seguridad, privacidad, calidad, ética.

Hueco: no es asunto del código. La política de IA es un documento que la dirección de la organización aprueba y firma. El blog enseña la postura editorial neutra y técnica (sin hype, soberanía, OSS por defecto en ENS/NIS2) pero esto no es la política IA de una organización concreta. Cada cliente debe redactarla y firmarla.

Plantilla mínima: 1-2 páginas con: principios (transparencia, supervisión humana, fairness, responsabilidad, sostenibilidad), alcance (qué sistemas), compromisos medibles (revisión anual, evaluación de impacto antes de despliegue, formación al equipo), gobierno (quién aprueba qué).

A.3 — Organización interna (3 controles): HUECO

A.3.2 AI roles and responsibilities: roles definidos, no solapados, comunicados. Típicamente: AI lead, AI risk owner, data steward, AI ethics officer (puede ser uno solo en organizaciones pequeñas).
A.3.3 Reporting of AI incidents/concerns: canal para que cualquier persona (interna o externa) reporte un problema con un sistema IA, con seguimiento documentado.
A.3.4 Identification of stakeholders: lista mantenida de stakeholders (clientes, afectados, reguladores, partners) y sus expectativas.

Hueco: tampoco técnico. Decisión organizativa. La forma habitual de cubrirlo es nombrar un AI lead (puede ser el CIO, CTO o un rol nuevo dependiendo del tamaño), reusar el canal de reporting de seguridad (típicamente ya existe por 27001) extendiéndolo a IA, y mantener un registro vivo de stakeholders.

A.4 — Recursos (6 controles): CUBIERTO

A.4.2 Documented information: documentación del AIMS.
A.4.3 Data resources: identificación y gestión de los datos disponibles para entrenamiento, evaluación, operación.
A.4.4 Tooling resources: herramientas de desarrollo, validación, monitoreo.
A.4.5 System resources: hardware, infraestructura, cómputo.
A.4.6 Human resources: personal con competencia.
A.4.7 Financial resources: presupuesto.

Cubierto por el blog en los tres posts arquitectónicos:

Anatomía del stack: siete capas — A.4.5 system resources, A.4.4 tooling.
Siete fases del despliegue — A.4.5 + A.4.7 (presupuesto implícito).
Cinco niveles de madurez — A.4.5 + A.4.6 (madurez del equipo).
Catálogo OSS de herramientas — A.4.4 tooling.
Data versioning con DVC y lakeFS — A.4.3 data resources.

A.5 — Impact assessment (5 controles): PARCIAL

A.5.2 AI impact assessment process: procedimiento documentado de evaluación de impacto.
A.5.3 Documentation of AI impact assessments: registros de las evaluaciones hechas.
A.5.4 Alignment with AI risk treatment: las decisiones del impact assessment alimentan el tratamiento de riesgos.
A.5.5 Impacts on individuals: dimensiones específicas sobre personas afectadas (derechos, discriminación, privacidad).
A.5.6 Societal impacts: dimensiones sobre la sociedad (información, derechos sociales).

Parcial: el método existe en la familia ISO/IEC SC 42 — ISO/IEC 23894:2023 es la norma técnica de risk management para IA y NIST AI RMF 1.0 es el equivalente americano de uso libre. Pero la organización debe escribir su procedimiento y ejecutarlo por sistema antes del despliegue. No es código, es disciplina.

Plantilla mínima del impact assessment (3-5 páginas por sistema):

Descripción del sistema (qué hace, a quién sirve, modelo y stack subyacentes).
Stakeholders identificados.
Impactos potenciales (intencionados + no intencionados) en personas, grupos y sociedad.
Métricas de fairness y robustez aplicadas, con umbrales y resultados.
Mitigaciones aplicadas (guardrails, evals, supervisión humana, rate limiting).
Riesgos residuales aceptados, con justificación firmada.
Cadencia de revisión (típicamente anual o ante cambio sustancial).

A.6 — Ciclo de vida del sistema IA (4 controles): CUBIERTO

A.6.2.2 Objectives for responsible development of AI: objetivos de desarrollo responsable definidos por sistema.
A.6.2.3 Processes for responsible AI design and development: procedimientos de diseño y desarrollo.
A.6.2.4 AI system requirements and specifications: especificación formal del sistema.
A.6.2.5 Verification and validation: V&V antes y durante operación.
A.6.2.6 Deployment: procedimientos de despliegue.
A.6.2.7 Operation and monitoring: operación y monitoreo continuo.
A.6.2.8 Documentation: documentación del ciclo de vida.

Cubierto por el blog:

Pipeline LLMOps de seis etapas — el mapa maestro completo del ciclo de vida.
Anatomía de una petición LLM — la versión forense de cómo se ejecuta en producción.
Fine-tuning continuo en producción — la disciplina A.6.2.3 + A.6.2.5 + A.6.2.6 + A.6.2.7 en operativa real.
Evals: la capa después del tracing — A.6.2.5 verification and validation.
Retrain — A.6.2.7 operación + iteración continua.
Alignment moderno: DPO, KTO, ORPO, SimPO — A.6.2.3 design responsable.
MLOps panorama 2026 — el panorama de herramientas.

A.7 — Datos para sistemas IA (5 controles): CUBIERTO

A.7.2 Data for development and enhancement of AI: política y procedimientos de gestión de datos para desarrollo y mejora.
A.7.3 Acquisition of data: procedimientos de adquisición (origen, autorización, calidad).
A.7.4 Quality of data for AI systems: criterios de calidad medibles.
A.7.5 Data provenance: lineage del dato.
A.7.6 Data preparation: procedimientos de preparación (chunking, anonimización, etiquetado).

Cubierto por el blog:

RAG corpus curation: el bibliotecario activo — A.7.4 + A.7.5 + A.7.6 al detalle (cinco capas: schema, dedup, PII, anti-contaminación, lineage).
Data versioning: DVC y lakeFS — A.7.2 + A.7.5 (los cuatro artefactos data versionados con lineage).
Reranker y hybrid retrieval — A.7.6 preparación + filtrado.
LLM Guard — A.7.6 anonimización en runtime con Vault.

A.8 — Información para partes interesadas (4 controles): CUBIERTO

A.8.2 System documentation and information for users: documentación técnica disponible.
A.8.3 External reporting: capacidad de reportar a autoridades cuando aplique.
A.8.4 Communication of incidents to users: notificación a usuarios cuando hay incidente.
A.8.5 Information for interested parties: información para otros stakeholders.

Cubierto por el blog:

Tracing LLM con OpenTelemetry GenAI — A.8.2 trazabilidad por request, A.8.3 capacidad de extraer reporting forense.
Prompt versioning con Langfuse y MLflow — A.8.2 versionado documentado.
Guardrails y safety en LLMs — A.8.4 spans gen_ai.guardrail.* como base para notificación de incidentes.
LLM Guard — A.8.4 incident events para retrain.

A.9 — Uso de sistemas IA (3 controles): CUBIERTO

A.9.2 Processes for responsible use of AI: procedimientos de uso responsable.
A.9.3 Objectives for responsible use of AI: objetivos.
A.9.4 Intended use of AI systems: documentación del uso previsto.

Cubierto por el blog:

Guardrails y safety en LLMs — A.9.2 + A.9.3 (las cuatro líneas de defensa).
LLM Guard — A.9.2 detalle operativo.
Evals: la capa después del tracing — A.9.3 medición de objetivos.
Retrain — A.9.2 closed loop.

A.10 — Terceros y relaciones con clientes (4 controles): CUBIERTO

A.10.2 Allocation of responsibilities: distribución de responsabilidades entre roles AI.
A.10.3 Suppliers: procedimientos para proveedores AI.
A.10.4 Customers: procedimientos hacia clientes.
A.10.5 Third parties: procedimientos para terceros.

Cubierto por el blog:

El catálogo paralelo: OSS vs hyperscalers — A.10.3 evaluación de proveedores con análisis de lock-in y soberanía contractual.
El catálogo OSS para LLMOps — A.10.5 inventario de terceros (componentes OSS con licencias y gobierno).
Anatomía de una petición LLM — A.10.2 + A.10.4 en el caso multi-tenant.

Los roles definidos por la norma

ISO/IEC 22989:2022 (vocabulario IA, complementaria a 42001) define seis roles. Cada organización debe decidir cuáles ocupa y documentarlo:

Rol	Definición	Responsabilidad principal	Ejemplo
AI provider	Organización que provee el sistema IA a otros	Hace que el sistema esté disponible	OpenAI provee GPT-5 vía API
AI producer	Organización que desarrolla el sistema IA	Diseño, desarrollo, validación	Meta produce Llama 4
AI customer	Organización que adquiere el sistema IA	Selección, integración, supervisión	Una consultora que integra un LLM en un producto propio
AI partner	Organización que colabora con otra rol AI	Compartido	Un fabricante de hardware GPU
AI subject	Persona/grupo afectado por el sistema	Receptora del impacto	El usuario final del chatbot
Relevant authority	Regulador con jurisdicción	Supervisión externa	AEPD, CNMC, autoridades EU AI Act

Una organización puede ocupar varios roles a la vez, lo cual cambia los controles aplicables. Un patrón habitual en consultoría es: producer + customer + provider hacia el cliente final. Las responsabilidades A.10 se modulan según los roles.

Ejemplo de mapeo de roles del chatbot multi-tenant del post forense:

Fabricante del modelo base (Llama 4): AI producer del modelo base.
Operador del stack OSS (consultora): AI producer del adapter LoRA + AI provider del chatbot a sus clientes + AI customer del modelo base de Meta.
Cliente final (aseguradora): AI customer del chatbot + AI provider del servicio de atención al cliente.
Asegurado: AI subject.
AEPD + autoridad EU AI Act: relevant authority.

Cada caja del cuadro genera obligaciones distintas. La consultora, por ser producer del adapter, debe documentar A.6 (ciclo de vida) y A.7 (datos) del adapter. Por ser provider del chatbot, debe documentar A.10.4 (customers). Por ser customer del modelo base, debe documentar A.10.3 (suppliers) y validar que Meta cumple su parte.

Niveles de impacto y proporcionalidad

42001 no obliga el mismo rigor a todos los sistemas. La cláusula 6.1.2 y el control A.5 introducen el concepto de impacto como modulador. La norma no define categorías taxativas (a diferencia del EU AI Act, que sí define “prohibido / alto riesgo / riesgo limitado / mínimo”), pero recomienda usar niveles según severidad y probabilidad.

La práctica industrial 2026 alinea los niveles 42001 con las categorías del EU AI Act:

Nivel 42001	EU AI Act	Ejemplos	Profundidad de controles
Alto	Alto riesgo (Anexo III)	Scoring crediticio, RRHH, salud, infraestructura crítica	Impact assessment exhaustivo, supervisión humana obligatoria, monitoreo continuo, evals adversariales, registro detallado, revisión por dirección semestral
Medio	Riesgo limitado	Chatbots customer service no automatizan decisiones, asistentes de productividad	Impact assessment estándar, guardrails completos, revisión anual
Bajo	Riesgo mínimo	Filtros de spam, recomendaciones de contenido no personalizado	Impact assessment ligero, controles básicos

Esta proporcionalidad es clave operativa: implantar 42001 al máximo rigor para un sistema de bajo riesgo es desperdicio; relajarla en uno de alto riesgo es incumplimiento.

Los siete documentos mínimos del AIMS

Un auditor en Stage 1 (revisión documental) pide entre siete y diez documentos. Los siete imprescindibles:

Política de IA (cláusula 5.2 + A.2.2). 1-2 páginas. Aprobada por dirección, fechada, versionada.
Alcance del AIMS (cláusula 4.3). Lista de sistemas IA dentro del alcance, criterios de inclusión.
Registro de stakeholders (cláusula 4.2 + A.3.4). Lista mantenida con expectativas.
Registro de riesgos AIMS (cláusula 6.1). Riesgos del sistema de gestión, no de cada modelo.
Procedimiento de impact assessment (A.5.2) + registros de assessments ejecutados (A.5.3). Procedimiento + uno o varios assessments hechos.
Procedimiento de ciclo de vida de IA (A.6.2) — puede ser literalmente “consultar el pipeline LLMOps de seis etapas” con referencias a runbooks técnicos.
Procedimiento de gestión de datos (A.7.2) — incluye adquisición, calidad, provenance, preparación, anonimización.

Documentos adicionales habituales:

Política de uso responsable (A.9.2) con tipos de uso permitidos/no permitidos.
Procedimiento de gestión de terceros AI (A.10.3, A.10.5) con criterios de evaluación de proveedores AI.
Plan de auditorías internas + agenda de revisión por dirección (cláusulas 9.2 + 9.3).

Para una organización con stack OSS maduro, los documentos 6 y 7 son referencias a artefactos técnicos ya existentes (runbooks de pipeline, configuraciones de DVC, política de PII en LLM Guard). El esfuerzo documental real está en los documentos 1, 2, 3, 4, 5.

Caso aplicado: el chatbot multi-tenant del blog → checklist 42001

Tomamos el sistema descrito en el post forense —chatbot multi-tenant de atención al cliente para aseguradoras sobre stack OSS on-premise— y lo recorremos como auditor 42001 haría.

Cláusula 4 — Contexto. El alcance del AIMS incluye el chatbot, no incluye el sistema interno de RRHH (otra IA distinta). Stakeholders identificados: aseguradoras cliente, asegurados afectados, AEPD, autoridad EU AI Act (cuando entre en vigor 2 ago 2026), proveedor Meta (modelo base), proveedor de hardware NVIDIA. → Documentado.

Cláusula 5 — Liderazgo. Política de IA firmada por CEO, vigente. Roles asignados: AI lead (CTO), AI risk owner (CISO), data steward (Head of Data), AI ethics committee trimestral. → Documentado.

Cláusula 6 — Planificación. Registro de riesgos AIMS: documentación incompleta, churn del equipo, dependencia de proveedor único de GPU, cambio regulatorio EU AI Act. Objetivos AIMS para 2026: certificación 42001 antes Q4, cumplimiento EU AI Act high-risk antes 2 ago. → Documentado.

Cláusula 7 — Soporte. Recursos: cluster 4×H100 SXM + siete capas del stack. Competencia: 2 MLE + 2 SRE + 1 AI ethics part-time, todos con formación documentada. Comunicación: política de IA en intranet + handbook. → Documentado.

Cláusula 8 — Operación. Procedimientos operativos = pipeline LLMOps de seis etapas. Impact assessment ejecutado antes del despliegue + revisión anual + revisión ante cambio sustancial (definido: cambio de modelo base, cambio de adapter mayor, expansión a nuevo tenant). → Documentado.

Cláusula 9 — Evaluación. Monitoring: Langfuse + Tempo + VictoriaMetrics + Grafana. Métricas obligatorias en dashboard: F1 por categoría guardrail sobre tráfico real, drift estadístico, faithfulness RAG, tasa de refused. Auditoría interna trimestral con criterios escritos. Revisión por dirección semestral con minuta firmada. → Documentado.

Cláusula 10 — Mejora. Tickets de incident-driven retrain mapeados como no-conformidades cuando severity ≥ HIGH. Análisis causa raíz documentado. Eficacia verificada en el siguiente eval gate. → Documentado.

Annex A — Por sección:

A.2 (Políticas): política de IA + política de uso responsable. → Documentado.
A.3 (Organización): roles asignados, canal de reporting, registro de stakeholders. → Documentado.
A.4 (Recursos): siete fases despliegue + catálogo OSS + plan de formación + presupuesto anual. → Documentado.
A.5 (Impact): procedimiento + assessments por sistema + métricas de fairness aplicadas. → Documentado.
A.6 (Ciclo de vida): pipeline LLMOps + fine-tuning continuo + retrain. → Documentado.
A.7 (Datos): data versioning + RAG corpus curation + LLM Guard Vault + Presidio. → Documentado.
A.8 (Información partes): tracing OTel + Langfuse + spans gen_ai.guardrail.* + notificación a tenants en SLA. → Documentado.
A.9 (Uso): guardrails + evals + política de uso responsable. → Documentado.
A.10 (Terceros): OSS vs hyperscalers con análisis de lock-in + contrato Meta para modelo base + contratos con tenants. → Documentado.

Resultado del recorrido: certificable. Los huecos típicos (A.2.2 política escrita, A.3 roles, A.5 procedimiento de impact assessment) están cubiertos como documentos formales. Las cláusulas operativas (8, 9, 10) se apoyan en la arquitectura técnica del blog. La distancia entre “tener la arquitectura” y “tener certificación” se mide en disciplina documental, no en código.

Mapeo cruzado con EU AI Act, NIS2 y ENS

EU AI Act (Reg. 2024/1689) — siete artículos directamente alineados

Artículo EU AI Act	Tema	Control 42001 alineado	Aplicable a
Art. 9	Risk management system	A.5 + cláusula 6	Sistemas alto riesgo
Art. 10	Data and data governance	A.7 (todos)	Sistemas alto riesgo
Art. 11	Technical documentation	A.6 + A.4.2	Sistemas alto riesgo
Art. 12	Record-keeping (logs)	A.8.2 + tracing OTel	Sistemas alto riesgo
Art. 13	Transparency to deployers	A.8.5 + A.10.4	Sistemas alto riesgo
Art. 14	Human oversight	A.9.2 + supervisión documentada	Sistemas alto riesgo
Art. 17	Quality management system	Cláusulas 4-10	Proveedores alto riesgo

Las obligaciones principales para sistemas de alto riesgo entran en aplicación el 2 de agosto de 2026. Implantar 42001 ahora construye la base de gestión que ese deadline exige.

Qué falta para cumplimiento EU AI Act que no cubre 42001:

Conformidad CE de los sistemas de alto riesgo (declaración de conformidad, marcado, registro en EU database).
Post-market monitoring específico exigido por el Art. 72.
Reporting de incidentes graves a autoridades en plazos legales (no sólo a usuarios).
Obligaciones de transparencia a usuarios para sistemas de riesgo limitado (Art. 50): chatbots, deepfakes, contenido generado.
Prohibiciones del Art. 5 (social scoring, manipulación, biometría en tiempo real con excepciones).

NIS2 (Dir. 2022/2555) — tres pilares con solapamiento

Asset register (Art. 21.2.f): los sistemas IA en alcance NIS2 deben estar en el inventario de activos. → Solapa con A.4 + cláusula 4.3 (alcance).
Incident notification (Art. 23): incidentes significativos se notifican en 24 h (alerta inicial) + 72 h (informe detallado). → Solapa con A.3.3 (reporting) + cláusula 10 (improvement).
Supply chain security (Art. 21.2.d): evaluación de seguridad de la cadena de suministro digital. → Solapa con A.10.3 (suppliers).

Para entidades NIS2 esenciales que además usan sistemas IA, 42001 cubre la parte AI-específica que NIS2 exige inferencialmente pero no detalla.

ENS (RD 311/2022)

El Esquema Nacional de Seguridad español ya contempla expresamente IA en su anexo II (controles ENS). Categorías Básico/Medio/Alto se alinean con niveles de impacto 42001. Los controles ENS de trazabilidad (op.exp.8), registro de actividad (op.exp.10) y gestión de incidentes (op.exp.7) se cubren con los mismos artefactos técnicos que A.8 y A.5 de 42001. Una organización certificada en ENS Categoría Alta con sistemas IA está a un esfuerzo razonable de añadir 42001.

Las cinco trampas habituales de la certificación

Trampa 1 — Confundir 42001 con cumplimiento EU AI Act. Pasar la auditoría 42001 no implica conformidad con el Reglamento europeo. Son universos distintos con solapamiento del 60-70%. La trampa se descubre cuando el cliente pide CE marking del sistema de alto riesgo y la organización presenta sólo el certificado 42001.

Trampa 2 — Sobre-documentar. Manuales de 200 páginas con procedimientos copiados de plantillas, sin medibles ni evidencias de aplicación. El auditor pide la última ejecución del procedimiento — si no hay registros, los procedimientos son ornamento. La regla práctica: prefiere documentos cortos referenciando artefactos técnicos vivos a documentos largos auto-contenidos.

Trampa 3 — Sub-medir. Definir objetivos AIMS sin métricas operativas. “Mejorar la calidad del modelo” es objetivo nulo; “F1 por categoría guardrail ≥ 0,85 sobre tráfico real, medido semanalmente, revisado trimestralmente en management review” es objetivo auditable. El blog ha insistido en esto en cada post de evals, guardrails y retrain.

Trampa 4 — Ignorar A.5 hasta el día del audit. El impact assessment es el control más infravalorado y el primero que pide el auditor. Sin assessments por sistema ejecutados antes del despliegue, no hay forma de demostrar A.5. La trampa se descubre cuando ya no hay tiempo de hacer assessments retrospectivos creíbles.

Trampa 5 — Asumir que 27001 cubre lo AI. Las organizaciones con 27001 ya implantado a veces piensan que “tenemos la mitad hecha”. Es verdad para Annex SL (estructura) y para A.5/A.6/A.7 de 27001 (no de 42001) en lo que se refiere a infosec. Es falso para A.5 de 42001 (impact assessment), A.7 de 42001 (data quality AI-específica), A.9 (uso responsable) y A.10.4 (customers AI). Hay que añadir, no asumir.

Lo que no hemos cubierto (próximos posts)

Plantillas concretas de los siete documentos obligatorios, con ejemplos de redacción y métricas. Material para un post tipo “Manual del AIMS en 7 documentos” con frame de referencia.
Mapeo detallado a EU AI Act por artículo con la checklist de evidencias técnicas que se pueden derivar del stack OSS del blog. Especialmente Arts 11 (technical documentation), 14 (human oversight) y 72 (post-market monitoring).
Caso ENS Categoría Alta + 42001 combinados: qué controles ENS se cubren con qué artefactos del AIMS, evitando duplicidades.
Comparativa NIST AI RMF 1.0 vs 42001: muchos clientes internacionales piden ambos. Cómo se reciclan los mismos artefactos para satisfacer los dos frameworks.
42001 para agentes LLM y MCP: dimensiones nuevas que emergen cuando el sistema IA es agéntico (excessive agency, tool use, autonomía graduada). El post de guardrails introdujo la línea 3 (tool GR); 42001 tiene huecos abiertos en este terreno y la SC 42 trabaja en addendums.

Referencias

ISO/IEC 42001:2023 — Information technology — Artificial intelligence — Management system. ISO. https://www.iso.org/standard/81230.html.
ISO/IEC 22989:2022 — Information technology — Artificial intelligence — Artificial intelligence concepts and terminology. Define los roles AI provider/producer/customer/partner/subject.
ISO/IEC 23894:2023 — Information technology — Artificial intelligence — Guidance on risk management. Insumo de A.5.
ISO/IEC 38507:2022 — Governance implications of the use of AI by organizations. Complemento de gobierno.
ISO/IEC 5259 — Data quality for analytics and machine learning (familia). Insumo de A.7.
EU AI Act (Regulation 2024/1689) — texto consolidado en EUR-Lex. Entrada en vigor de obligaciones de alto riesgo: 2 ago 2026.
NIS2 (Directive 2022/2555) — texto consolidado en EUR-Lex.
ENS — Real Decreto 311/2022 — Esquema Nacional de Seguridad, BOE-A-2022-7191.
NIST AI RMF 1.0 (2023) — https://www.nist.gov/itl/ai-risk-management-framework.
EUR-Lex EU AI Act consolidated text — https://eur-lex.europa.eu/eli/reg/2024/1689.
A-LIGN / BSI / Schellman — blogs sobre experiencia de auditoría 42001 con casos reales 2024-2025.

Ver también

El pipeline LLMOps de seis etapas — el procedimiento operativo que materializa A.6 ciclo de vida sin trabajo adicional.
Anatomía de una petición LLM en producción — el caso forense recorrido como checklist 42001 en la sección “caso aplicado” de este post.
Siete capas del stack de inferencia LLM on-premise y siete fases del despliegue — material directo para A.4 recursos.
Cinco niveles de madurez de la plataforma — cómo justificar la proporcionalidad de los controles según el nivel de madurez existente.
Data versioning con DVC y lakeFS y RAG corpus curation — A.7 datos cubierto al detalle.
Tracing LLM con OpenTelemetry GenAI — A.8 información a partes interesadas a través de trazabilidad estandarizada.
Guardrails y safety en LLMs y LLM Guard — A.9 uso responsable.
Evals: la capa después del tracing y LLM-as-judge — A.6.2.5 verification and validation.
Retrain: cerrar el bucle feedback → dataset → adapter — cláusula 10 mejora continua + bucle incident-driven que alimenta no-conformidades formales.
El catálogo paralelo: OSS vs hyperscalers — A.10.3 evaluación de proveedores con análisis estructural de lock-in y soberanía contractual; insumo directo del registro de proveedores AI.
El catálogo OSS para LLMOps — A.10.5 inventario de terceros OSS con licencia, gobierno y madurez documentados.
MLOps específico para LLMs en 2026: panorama — contexto operativo en el que el AIMS opera y se audita.
EU AI Act: el expediente técnico artículo por artículo — el post hermano sobre el Reglamento UE 2024/1689; baja del sistema de gestión a las obligaciones legales directamente aplicables, con plazos, sanciones y mapeo control-a-artículo.
Controles técnicos: el mapeo cruzado ENS × ISO 42001 × EU AI Act — el tercer post de la trilogía de gobernanza; baja al detalle de los 25 controles técnicos comunes a los tres marcos con la tabla maestra de cumplimiento triple y el etiquetado de evidencia.
Runbooks de incident response para LLM con Keep + Kafka — la materialización operativa de la cláusula 10 (mejora continua) y la traza WORM que A.8.2 exige: cada incidente abre no-conformidad, dispara postmortem, actualiza el runbook y queda registrado en audit.actions Kafka.

Posts on lo0 — Blog Técnico

Anatomía de una petición LLM en producción, mayo 2026: tour por las seis etapas siguiendo una sola request

TL;DR

Estás aquí: todas las etapas a la vez

La analogía: análisis forense de una request

El escenario: chatbot de soporte multi-tenant para clientes regulados

Paso 0 — El frame: la respuesta que el usuario ve

Rebobinando hacia atrás: lo que ya estaba en su sitio antes de la request

t = −90 días — Etapa Retrain anterior cierra el ciclo previo

t = −60 días — Etapa Data: el dataset enriquecido se versiona y entra a circulación

t = −45 días — Etapa Tune: el adapter customer_support_v7 se entrena

t = −38 días — Etapa Eval: el adapter v7 pasa por eval gates

t = −31 días — Etapa Deploy: el adapter v7 entra a serving

Avanzando: la request del usuario atraviesa el sistema

t = 0 ms — Ingreso por el gateway

t = 8 ms — Pull del prompt versionado

t = 12 ms — Retrieval RAG

t = 40 ms — Construcción del payload final

t = 45 ms — Prefill

t = 580 ms — Decode (streaming)

t = 4 200 ms — Respuesta completa, span raíz cerrado

En paralelo: Observe está mirando

El feedback: el bucle se cierra

Inserción en feedback_signals

Triage por causa raíz

El siguiente ciclo lo recoge

Lo que va en cada trace: identidad y trazabilidad

Diagrama síntesis: cómo encajan las piezas

El stack on-premise aplicado

Diez puentes entre etapas donde se rompe el sistema

Cómo recorrer el blog

Lo que no hemos cubierto (todavía)

Ver también

Referencias

Runbook: enjaular al agente de IA — bubblewrap en el cliente, Tetragon en el cluster

TL;DR

El flujo de los dos tracks

Track A — Cliente (workstation del desarrollador)

A0 — Instalar ai-jail y bubblewrap

A1 — El fichero .ai-jail por proyecto

A2 — Las allowlists de permisos con –bootstrap

A3 — Lockdown para lo que no te fíes

A4 — La red de seguridad: git sin push

Track B — Cluster (RKE2 con Cilium + Tetragon)

B0 — El baseline del pod

B1 — RuntimeClass Kata: el pod no confiable en su propia microVM

B2 — Tetragon, fase observación (Post)

B3 — Tetragon, fase enforcement (Sigkill)

La tabla de equivalencias cliente ↔ cluster

Checklist de gotchas

Ver también

Referencias

El contratista con la llave maestra: aislar agentes de IA del workstation al cluster

TL;DR

La analogía: el contratista con la llave maestra

El modelo de amenaza: qué puede hacer un agente desbocado

Dos dominios, una política

El cliente: aislar al agente en el workstation

El cluster: aislar al agente en producción

La tabla del panorama

Extrapolar, no copiar

Lo que ningún sandbox resuelve

Ver también

Referencias

Runbook QLoRA: del dataset al adapter servido en multi-LoRA (procedimiento operativo)

TL;DR

El flujo de extremo a extremo

Fase 0 — Entorno y versiones

Fase 1 — Preparar el dataset

Fase 2 — El script de entrenamiento

BitsAndBytesConfig — cómo se cuantiza el base

LoraConfig — la forma del adapter

SFTConfig — el presupuesto de memoria y el bucle

Fase 3 — Lanzar y monitorizar

Fase 4 — Validar el adapter

Fase 5 — Versionar el adapter como artefacto

Fase 6 — Servir en multi-LoRA con vLLM

Servir multi-adapter vs fusionar por tarea

Checklist de gotchas operativos

Aplicado a la infraestructura on-premise

`BitsAndBytesConfig` — cómo se cuantiza el base

`LoraConfig` — la forma del adapter

`SFTConfig` — el presupuesto de memoria y el bucle