Facsímil 04 · Completo

La caja de herramientas

APIs, modelos locales, RAG, laboratorios, despliegue y herramientas de trabajo para convertir modelos en soluciones utilizables.

Empezar lectura Ver índice

Contenido disponible: 14 de 14 capítulos listos
Estado editorial: Completo

Sobre esta edición

Esta página se genera desde capítulos Markdown propios del facsímil. Las fórmulas se renderizan con KaTeX, los mapas con Mermaid y las notas al pie se mantienen junto al texto para leer el facsímil como una pieza autónoma, no como una exportación del taller.

Capítulo 01

Facsímil 4 · La caja de herramientas

Capítulo 01: Elegir la intervención correcta: prompt, RAG, tool o ajuste

La herramienta no es el punto de partida

El error más fácil en IA aplicada es empezar por la herramienta. “Hagamos RAG”, “probemos fine-tuning”, “pongamos un agente”, “lo llevo a local”, “metamos una base vectorial”. Suena activo, pero puede ser una forma elegante de no diagnosticar.

Este facsímil va de herramientas, sí. Pero las herramientas no son trofeos. Son respuestas a síntomas concretos. Si el modelo no respeta un formato, quizá necesitas salida estructurada. Si no conoce normativa interna, quizá necesitas RAG. Si debe consultar stock real, quizá necesita una tool. Si responde bien pero con tono inestable en miles de casos repetidos, quizá tiene sentido ajustar. Si los datos no pueden salir de una máquina, quizá toca local.

La caja de herramientas empieza con una pregunta humilde: ¿qué parte del sistema falla y qué cambio mínimo la arregla mejor?

Estado del arte con fecha de corte

Fecha de corte: 25 de mayo de 2026.
Fuentes consultadas ese día: documentación oficial de Anthropic sobre prompt engineering, OpenAI sobre salidas estructuradas y function calling, Hugging Face PEFT/LoRA, documentación de Ollama API y Cloud, y el paper original de RAG.

Esta foto cambia rápido. Lo estable no es el nombre de una herramienta concreta, sino el patrón de decisión: contexto, evidencia, schema, tool, ajuste, local, evaluación y coste.

En 2026, las plataformas de modelos ya no ofrecen solo “texto dentro, texto fuera”. Las APIs modernas permiten schemas, tool calls, streaming, batch, cache y distintos modelos para coste o calidad. OpenAI documenta salidas estructuradas para forzar que una respuesta siga un schema.¹ Anthropic mantiene guías de prompt engineering como primera capa de control antes de añadir arquitectura.²

También se consolidó una separación práctica: RAG para conocimiento externo, PEFT/LoRA para adaptar comportamiento con pocos parámetros y modelos locales o cloud local-compatible cuando la restricción está en privacidad, coste, portabilidad o experimentación.³ Ollama documenta una API local y una variante cloud con una experiencia parecida para modelos que no caben en hardware personal.⁴⁵

Qué no es una caja de herramientas de IA

Una caja de herramientas no es una lista de marcas. Si no sabes qué síntoma resuelve cada pieza, el catálogo solo añade ruido. La persona que sabe usar herramientas no es quien instala más librerías, sino quien simplifica antes de complicar.

Tampoco es una escalera de prestigio. Prompt no es “poco serio” y fine-tuning no es “más profesional” por defecto. RAG no es superior a una consulta SQL si la pregunta exige datos exactos. Un modelo local no es mejor que una API si no cumple calidad o mantenimiento. Cada elección compra algo y paga algo.

Y una caja de herramientas no sustituye a evaluación. Puedes montar RAG, tool calling, LoRA y modelo local; si no tienes casos de prueba, no sabes si has mejorado o solo has construido una máquina más difícil de entender.

La pregunta correcta: qué quieres cambiar

Antes de elegir intervención, separa cuatro planos. El primero es entrada: quizá el modelo ya puede hacer la tarea si le das mejores instrucciones, ejemplos y formato esperado. El segundo es contexto: quizá necesita documentos, datos o memoria externa. El tercero es acción: quizá debe consultar una API, calcular algo o escribir en un sistema. El cuarto es comportamiento aprendido: quizá quieres que responda de una forma estable en una tarea repetida.

Esa separación evita mezclar herramientas:

Si el problema es...	Primera intervención razonable	Por qué
Formato irregular	Prompt claro y salida estructurada	El modelo sabe responder, pero falta contrato de salida.
Conocimiento vivo	RAG o consulta a fuente externa	El dato cambia y debe poder citarse o verificarse.
Cálculo, estado o acción	Tool con schema y permisos	El modelo no debe inventar resultados de sistemas externos.
Tono o taxonomía repetida	Ejemplos, luego fine-tuning si escala	Cambias comportamiento estable, no conocimiento vivo.
Privacidad u offline	Modelo local o entorno privado	La restricción vive en dónde se ejecuta.
Coste o latencia	Modelo más pequeño, cache, batch o local	El problema puede estar en serving, no en “inteligencia”.

Para verlo con un caso cercano: una universidad quiere contestar dudas de matrícula. Si las reglas cambian cada curso, RAG o consulta a la base oficial. Si el problema es devolver siempre JSON para integrarlo en una app, salida estructurada. Si debe comprobar si una persona ya pagó, tool contra el sistema de pagos. Si cada respuesta debe tener tono institucional, ejemplos y quizá ajuste más adelante.

La fórmula mental del diagnóstico

No hace falta una ecuación para decidir, pero ayuda tener una forma compacta de pensar.

Ejemplo de fórmula. Como regla pedagógica de decisión, no como métrica universal, una intervención merece la pena cuando la mejora esperada supera su coste, su complejidad y su riesgo operativo:

U(\text{intervención}) \approx \Delta Q \cdot C - K - M - R

Símbolo	Significado	Ejemplo
$\Delta Q$	Mejora esperada de calidad útil.	Más respuestas con cita correcta.
$C$	Confianza en que la mejora se mantenga.	Eval con 100 casos reales.
$K$	Coste económico y de latencia.	Tokens, GPU, vector DB, reintentos.
$M$	Mantenimiento añadido.	Índices, adapters, schemas, versiones.
$R$	Riesgo operativo.	Datos, permisos, acciones, regresiones.

La fórmula no pretende dar una verdad exacta. Pretende impedir una mala costumbre: contar solo la mejora y olvidar todo lo que tendrás que operar después.

Las cinco intervenciones básicas

Primero hay que explicar el síntoma. Luego la herramienta empieza a tener sentido. Estas cinco piezas vuelven durante todo el facsímil.

La tabla siguiente es una síntesis didáctica, no una taxonomía oficial única. Se apoya en prompt engineering⁶ para controlar tarea, contexto y ejemplos; en salidas estructuradas⁷ para imponer contratos de respuesta; en RAG⁸ para añadir evidencia recuperada; en function calling⁹ para conectar el modelo con funciones externas; y en LoRA/PEFT¹⁰ para adaptar comportamiento mediante pocos parámetros entrenables.

Intervención	Cambia	Sirve cuando	No sirve para
Prompt y ejemplos	La entrada	Falta claridad, formato o criterio de respuesta.	Datos vivos grandes o acciones externas.
Salida estructurada	El contrato de salida	Necesitas JSON, campos obligatorios o validación automática.	Saber más contenido.
RAG	El contexto recuperado	Hay documentos, políticas o conocimiento cambiante.	Cambiar el estilo profundo del modelo.
Tool	La capacidad de consultar o actuar	Hay estado real, cálculo, base de datos o sistema externo.	Sustituir permisos o validación.
Fine-tuning/LoRA	Algunos pesos o adaptadores	Tarea repetida, estable y medible.	Actualizar información que cambia cada día.

RAG nació como una forma de combinar memoria paramétrica con recuperación externa en tareas intensivas en conocimiento.¹¹ LoRA propuso adaptar modelos grandes entrenando matrices pequeñas de bajo rango.¹² QLoRA redujo aún más memoria al ajustar sobre modelos cuantizados.¹³

Para entenderlo antes de tocar código

Antes de escribir una línea de código conviene hacer una prueba mental muy simple: describe el fallo como lo vería una persona usuaria, no como lo nombraría una librería. Después tradúcelo a una capa del sistema. Esa traducción es el músculo que queremos entrenar en este capítulo.

La misma frase “el modelo falla” puede significar cinco cosas distintas. Puede fallar porque no recibió instrucciones claras, porque le falta evidencia, porque necesita consultar un sistema externo, porque debe repetir un criterio muy específico o porque el entorno de despliegue impone límites. Si llamas a todo “modelo malo”, acabarás cambiando piezas equivocadas.

Caso	Señal observable	Diagnóstico	Primera intervención	Qué medir
Asesoría con normativa cambiante	Responde bien hasta que cambia una norma.	Falta evidencia viva y trazable.	RAG o consulta a fuente oficial con cita.	Porcentaje de respuestas con documento correcto y fecha vigente.
CRM que necesita campos exactos	El texto es bueno, pero el backend rompe al parsear.	Falta contrato de salida.	Salida estructurada con schema y validación.	Campos válidos, errores de schema y casos que requieren revisión.
Tienda con stock real	Preguntan por talla, precio o disponibilidad.	Hace falta estado externo.	Tool pequeña contra inventario o pedidos.	Exactitud del dato, latencia de consulta y manejo de “no disponible”.
Soporte con miles de tickets parecidos	Responde con criterio parecido, pero formato y tono varían.	Conducta repetida poco estable.	Prompt con ejemplos; si escala, SFT, LoRA o adapter.	Consistencia de rúbrica, coste por ticket y regresiones.
Equipo con documentos sensibles	La mejor API externa no puede recibir ciertos textos.	Restricción de entorno.	Modelo local, entorno privado o arquitectura híbrida.	Calidad mínima aceptable, latencia, coste operativo y trazabilidad.

Fíjate en el tercer caso. Si una persona pregunta “¿quedan zapatillas talla 42?”, el modelo puede escribir una respuesta convincente, pero no conoce el almacén. La intervención correcta no es pedirle que “razone mejor”. Es darle una función con un contrato estrecho: consultar_stock(producto, talla, tienda). La inteligencia del sistema no está solo en el modelo; está en saber cuándo el modelo debe dejar de completar texto y pedir un dato.

Ahora mira el primer caso. Si la asesoría trabaja con normas que cambian, ajustar pesos puede incluso empeorar la situación: convierte conocimiento vivo en memoria opaca. RAG no entra porque sea una palabra de moda, sino porque necesitamos tres cosas muy concretas: recuperar el fragmento vigente, citarlo y poder actualizarlo sin entrenar de nuevo.

El caso del CRM enseña otra lección. A veces el modelo “entiende” perfectamente la tarea, pero el producto necesita datos que se puedan validar. Ahí no queremos literatura: queremos {categoria, prioridad, siguiente_paso, confianza} y una regla clara para rechazar respuestas inválidas. La salida estructurada no mejora el mundo interno del modelo; mejora el contrato entre el modelo y el software que lo rodea.

Y el equipo de soporte muestra cuándo empieza a tener sentido ajustar. Si el conocimiento ya está resuelto, los documentos aparecen bien y el schema se cumple, pero la respuesta no respeta una rúbrica interna en miles de ejemplos parecidos, entonces sí: quizá toca entrenar una adaptación pequeña. Pero esa decisión llega después de medir, no antes.

Una regla útil: si puedes arreglarlo cambiando entrada, contexto o contrato, no empieces cambiando pesos. Los pesos se tocan cuando quieres estabilizar una conducta repetida, tienes ejemplos buenos, sabes medir el resultado y aceptas mantener otra versión del sistema.

Criterios de elección: la matriz que decide contigo

Si esto fuera una asignatura universitaria, aquí no bastaría con decir “depende”. El “depende” tiene que descomponerse en variables observables. Una buena decisión técnica no es la que suena más moderna, sino la que explica qué restricción pesa más y qué evidencia aceptaríamos para cambiar de opinión.

La siguiente matriz sirve para discutir una intervención en clase, en un equipo o en una revisión de arquitectura. No da una respuesta automática, pero obliga a justificarla.

Criterio	Pregunta que debes hacer	Si pesa mucho, suele empujar hacia...	Evidencia mínima
Conocimiento cambiante	¿La respuesta depende de datos que cambian con frecuencia?	RAG, base de datos o tool.	Documentos con fecha, fuente y casos donde el dato cambia.
Necesidad de cita	¿La persona debe poder revisar de dónde sale la respuesta?	RAG con citas o consulta verificable.	Porcentaje de respuestas con evidencia correcta.
Estado real	¿Hace falta mirar inventario, pagos, agenda, expediente o cálculo externo?	Tool con schema estrecho.	Función definida, entrada validada y salida comprobable.
Formato estricto	¿Otro software consume la respuesta?	Salida estructurada.	JSON válido, campos obligatorios y tests de schema.
Conducta repetida	¿La misma tarea aparece miles de veces con criterios estables?	Prompt con ejemplos; si no basta, SFT, LoRA o adapter.	Dataset pequeño pero limpio, rúbrica y comparación contra baseline.
Privacidad o despliegue	¿Dónde puede ejecutarse el sistema y dónde pueden vivir los datos?	Modelo local, entorno privado o arquitectura híbrida.	Política de datos, latencia aceptable y calidad mínima medida.
Coste y latencia	¿El problema es calidad o servirlo sin arruinar la experiencia?	Modelo menor, cache, batch, cuantización o local.	Coste por consulta, TTFT, tokens/s y percentiles de latencia.
Reversibilidad	¿Podemos deshacer el cambio si empeora?	Prompt, schema, RAG o tool antes que ajuste de pesos.	Plan de rollback y comparación antes/después.

Esta matriz también evita discusiones tramposas. Si alguien propone fine-tuning para un problema de stock, puedes preguntar: “¿qué criterio de la tabla justifica cambiar pesos?”. Si nadie puede responder, todavía no hay diagnóstico.

Un mismo caso, cinco soluciones posibles

Tomemos un caso único para no perdernos: una universidad quiere un asistente de matrícula. El objetivo superficial parece uno solo, “responder dudas”, pero debajo hay varios problemas distintos. Según cuál duela, la intervención cambia.

Lectura del problema	Solución razonable	Qué mejora	Qué no arregla
El alumnado pregunta de formas muy distintas y el sistema responde desordenado.	Prompt con ejemplos y criterios de estilo.	Claridad, tono, estructura inicial.	Normativa nueva o datos personales.
La app necesita guardar la respuesta en una ficha.	Salida estructurada con campos como `tema`, `respuesta`, `fuente`, `confianza`.	Integración con software y validación.	Saber si la norma está vigente.
Las normas de matrícula cambian cada curso.	RAG sobre normativa oficial, con fecha y cita.	Respuestas trazables y actualizables.	Consultar si una persona concreta pagó.
El alumno pregunta “¿me falta pagar algo?”.	Tool contra el sistema académico o de pagos.	Estado real de esa persona.	Explicar bien una norma general.
El equipo responde miles de tickets con una rúbrica estable.	Ajuste ligero si prompt, schema y RAG ya no bastan.	Consistencia en una tarea repetida.	Conocimiento que cambia cada semana.

Lo importante es que ninguna fila “gana” siempre. En un producto real quizá uses varias: RAG para normativa, tool para expediente, salida estructurada para integrar y prompt para tono. Pero las añades por capas, no por entusiasmo.

Cómo evaluar cada intervención

Una intervención no está terminada cuando funciona en la demo. Está terminada cuando puedes repetir una prueba y decidir si mejoró. Si no sabes qué medir, la arquitectura se convierte en opinión.

Intervención	Métrica principal	Prueba mínima	Señal de que no basta
Prompt y ejemplos	Tasa de respuestas útiles según rúbrica.	30 casos reales antes/después.	Mejora solo en ejemplos vistos o se rompe con variaciones simples.
Salida estructurada	Validez de schema y tasa de campos correctos.	Tests con campos obligatorios, tipos y casos incompletos.	El JSON es válido pero el contenido sigue siendo incorrecto.
RAG	Evidencia correcta, cobertura y abstención cuando falta fuente.	Preguntas con documento esperado y preguntas sin respuesta en corpus.	Recupera texto parecido pero no el fragmento que justifica la respuesta.
Tool	Exactitud de llamada, validación de argumentos y latencia.	Casos con entradas válidas, incompletas y ambiguas.	La tool se invoca cuando no toca o con parámetros mal formados.
Fine-tuning/LoRA	Mejora contra baseline sin perder casos importantes.	Eval fija antes/después y revisión de regresiones.	Mejora el formato pero empeora factualidad o flexibilidad.
Modelo local o privado	Calidad mínima, latencia, coste y mantenimiento.	Misma eval que la API base, con medición de recursos.	Cumple privacidad pero no alcanza la calidad necesaria.

En clase, yo pediría siempre tres números antes de aceptar una propuesta: calidad, coste y reversibilidad. Calidad sin coste puede ser inviable. Coste sin calidad no sirve. Y una mejora que no puedes revertir exige mucha más evidencia.

Errores de diagnóstico que conviene detectar

Estos errores parecen razonables cuando tienes prisa, por eso conviene nombrarlos. No son fallos de principiante: aparecen en equipos buenos cuando el problema se describe demasiado pronto con el nombre de una herramienta.

Error de diagnóstico	Cómo se ve	Cómo corregirlo
Confundir conocimiento con comportamiento	“Ajustemos el modelo para que sepa la normativa nueva”.	Si cambia con frecuencia, sácalo a documentos, base de datos o tool.
Confundir formato con inteligencia	“El modelo no entiende”, cuando lo único que falla es el JSON.	Primero schema, validación y ejemplos de salida.
Confundir búsqueda con respuesta	El retrieval trae documentos parecidos, pero no justifican la conclusión.	Evaluar recuperación por fragmento correcto, no solo por similitud.
Confundir acción con texto	El modelo “dice” que ha comprobado algo, pero no ha consultado ningún sistema.	Tool real, logs y permisos mínimos.
Confundir benchmark con caso propio	Se elige modelo por ranking general.	Eval con idioma, dominio, coste y latencia del proyecto.
Confundir privacidad con peor producto	“Local” se acepta sin medir calidad.	Comparar local, privado y API con la misma rúbrica.

El antídoto común es escribir una frase de diagnóstico antes de escribir una frase de solución: “El sistema falla porque...”. Si esa frase ya contiene el nombre de una herramienta, sospecha un poco.

Mini práctica de decisión

Para entrenar el criterio, resuelve estos cuatro casos sin programar. En cada uno escribe: síntoma, intervención principal, alternativa descartada y métrica de aceptación. Después compara con la solución modelo.

Caso	Síntoma	Intervención principal	Alternativa descartada	Métrica de aceptación
Biblioteca universitaria con horarios cambiantes.	Responde horarios antiguos.	RAG o consulta a fuente oficial.	Fine-tuning.	Respuestas con horario vigente y fuente correcta.
App médica que necesita clasificar mensajes en tres colas internas.	El texto es bueno, pero la integración falla.	Salida estructurada.	RAG.	JSON válido y cola correcta según rúbrica humana.
Ecommerce con preguntas de disponibilidad por tienda.	El modelo estima stock.	Tool de inventario.	Prompt más insistente.	Stock correcto, latencia aceptable y manejo de ausencia de dato.
Equipo legal con contratos sensibles en portátiles sin conexión.	No puede enviar documentos fuera y necesita asistencia básica.	Modelo local cuantizado o entorno privado.	API externa directa.	Calidad mínima en una eval interna y tiempo de respuesta usable.

La solución modelo no pretende cerrar todos los matices. Pretende mostrar el razonamiento: cada respuesta identifica la capa que falla. Si cambias el enunciado, puede cambiar la intervención. Si la biblioteca también necesita guardar campos exactos, añadirías salida estructurada. Si el ecommerce además debe explicar políticas de devolución, quizá combinarías tool con RAG. La arquitectura final puede tener varias piezas; el diagnóstico inicial decide cuál entra primero.

Mapa visual de diagnóstico

En el día a día

En un equipo real, este capítulo se usa antes de abrir el editor. Pones encima de la mesa tres cosas: el caso de uso, diez ejemplos reales y una forma de medir. Solo entonces eliges herramienta.

Si un jefe de producto pide “un chatbot con todos los documentos”, tradúcelo: quizá quiere búsqueda con citas, quizá quiere navegación guiada, quizá quiere reducir tickets, quizá quiere extraer campos. Cada objetivo produce una arquitectura distinta.

Si un equipo técnico dice “hagamos RAG”, pregunta por el corpus, el tipo de preguntas, el criterio de cita, los permisos por documento y cómo sabremos que el retrieval encontró evidencia. Si esas respuestas no existen, todavía no hay arquitectura: hay deseo.

Por qué debería importarte

Porque cada intervención mal elegida deja deuda. Un RAG innecesario añade índices, chunks y evals. Un fine-tuning prematuro añade dataset, entrenamiento y versiones. Una tool amplia añade permisos y validación. Un modelo local añade soporte, hardware y medición de calidad.

La buena noticia es que una intervención bien elegida suele simplificar. Un schema puede eliminar cientos de líneas de parsing frágil. Una tool puede evitar que el modelo invente un dato. Un RAG con citas puede convertir una respuesta bonita en una respuesta revisable.

Dónde volverá a aparecer

Este capítulo es la brújula del facsímil. Cada capítulo posterior toma una rama del diagnóstico y la desarrolla.

Rama del diagnóstico	Dónde vuelve	Qué resolveremos allí
Salida estructurada	Capítulo 02.	Mensajes, schemas, streaming y contratos de API.
Coste y contexto	Capítulo 03.	Tokens, cache, batch y presupuestos.
Modelos y licencias	Capítulo 04.	Leer model cards sin dejarse llevar por rankings.
Local y cloud	Capítulos 05 y 06.	Ollama, LM Studio, GGUF, privacidad y despliegue.
RAG y vector DB	Capítulos 07 a 11.	Embeddings, bases vectoriales, RAG, evaluación y GraphRAG.
Herramientas de datos	Capítulo 12.	Text-to-SQL y consultas con validación.
Laboratorio mínimo	Capítulo 13.	Notebooks, casos, evals, trazas y decisión escrita.

Dónde solía tropezar yo

Estos tropiezos aparecen mucho al empezar proyectos con IA. Casi todos nacen de confundir síntoma con solución.

Error	Por qué es un error	Antídoto
Empezar por RAG sin corpus claro	Si no sabes qué documentos, preguntas y citas necesitas, el índice será decoración cara.	Definir 30 preguntas reales antes de indexar.
Ajustar pesos para datos vivos	El dato que cambia mañana no debería quedar escondido en un adapter.	Usar RAG, base de datos o tool para conocimiento cambiante.
Pedir formato con súplicas	“Responde en JSON” no es contrato suficiente si el backend depende de campos exactos.	Usar salida estructurada y validación.
Usar una tool para todo	Una función gigante es difícil de validar y fácil de usar mal.	Tools pequeñas, schemas claros y permisos mínimos.
Comparar modelos sin tarea	Un ranking genérico no sabe qué coste, idioma, latencia o riesgo tiene tu producto.	Comparar con tus casos, tus métricas y tus límites.

Manos a la obra

Kit ejecutable y descargable: kit descargable. Ejecuta python3 ops/run_f4_practices.py --all --write --fail-on-invalid para correr todas las prácticas del facsímil, o python3 ops/run_f4_practices.py --chapter c01 --write --fail-on-invalid cambiando c01 por el capítulo que quieras aislar.

Vamos a convertir el diagnóstico en una matriz pequeña. El objetivo no es automatizar la decisión final. Es obligarte a escribir qué importa en tu caso antes de enamorarte de una herramienta.

intervenciones = {
    "prompt_schema": {
        "conocimiento_vivo": 0,
        "accion_externa": 0,
        "formato": 5,
        "conducta_repetida": 2,
        "privacidad_local": 1,
        "coste": 5,
    },
    "rag": {
        "conocimiento_vivo": 5,
        "accion_externa": 1,
        "formato": 2,
        "conducta_repetida": 2,
        "privacidad_local": 3,
        "coste": 3,
    },
    "tool": {
        "conocimiento_vivo": 4,
        "accion_externa": 5,
        "formato": 3,
        "conducta_repetida": 1,
        "privacidad_local": 3,
        "coste": 3,
    },
    "ajuste_lora": {
        "conocimiento_vivo": 1,
        "accion_externa": 0,
        "formato": 4,
        "conducta_repetida": 5,
        "privacidad_local": 3,
        "coste": 2,
    },
    "modelo_local": {
        "conocimiento_vivo": 1,
        "accion_externa": 0,
        "formato": 2,
        "conducta_repetida": 2,
        "privacidad_local": 5,
        "coste": 4,
    },
}

caso = {
    "conocimiento_vivo": 5,
    "accion_externa": 0,
    "formato": 3,
    "conducta_repetida": 2,
    "privacidad_local": 4,
    "coste": 3,
}

def score(intervencion, pesos):
    return sum(intervencion[criterio] * importancia for criterio, importancia in pesos.items())

ranking = sorted(
    ((nombre, score(valores, caso)) for nombre, valores in intervenciones.items()),
    key=lambda item: item[1],
    reverse=True,
)

for nombre, puntos in ranking:
    print(f"{nombre}: {puntos}")

Salida esperada:

rag: 56
tool: 52
modelo_local: 47
ajuste_lora: 45
prompt_schema: 38

Este caso favorece RAG porque hemos dicho que el conocimiento vivo pesa mucho y no necesitamos actuar sobre sistemas externos. Cambia accion_externa a 5 y verás subir tool. Cambia formato a 5 y conocimiento_vivo a 0, y verás que prompt/schema se vuelve competitivo. La matriz no decide por ti: te obliga a explicar tus prioridades.

Cómo encaja todo

graph TD
    subgraph "Capítulo 1: Elegir intervención"
        SINTOMA["Síntoma"]
        DIAG["Diagnóstico"]
        MATRIZ["Matriz de criterios"]
        PROMPT["Prompt y ejemplos"]
        SCHEMA["Salida estructurada"]
        RAG["RAG"]
        TOOL["Tool"]
        AJUSTE["Ajuste"]
        LOCAL["Local o cloud"]
        EVAL["Eval y coste"]
        RUBRICA["Métrica de aceptación"]
    end
    subgraph "Viene del facsímil 3"
        LLM["LLM, tokens y contexto"]
        SAMPLING["Logits y sampling"]
        FT["LoRA, QLoRA<br/>cuantización"]
        SERVING["Inferencia y hardware"]
    end
    subgraph "Resto del facsímil 4"
        API["APIs y schemas"]
        COSTE["Tokens y coste"]
        MODELOS["Model cards"]
        VECTOR["Embeddings y vector DB"]
        RAGCAP["RAG y evaluación"]
        DATA["Text-to-SQL"]
        LAB["Laboratorio mínimo"]
    end

    SINTOMA --> DIAG
    DIAG --> MATRIZ
    MATRIZ --> PROMPT
    MATRIZ --> SCHEMA
    MATRIZ --> RAG
    MATRIZ --> TOOL
    MATRIZ --> AJUSTE
    MATRIZ --> LOCAL
    PROMPT --> EVAL
    SCHEMA --> EVAL
    RAG --> EVAL
    TOOL --> EVAL
    AJUSTE --> EVAL
    LOCAL --> EVAL
    EVAL --> RUBRICA
    LLM --> DIAG
    SAMPLING --> PROMPT
    FT --> AJUSTE
    SERVING --> LOCAL
    SCHEMA --> API
    EVAL --> COSTE
    LOCAL --> MODELOS
    RAG --> VECTOR
    VECTOR --> RAGCAP
    TOOL --> DATA
    EVAL --> LAB

    style SINTOMA fill:#F5F5F5,stroke:#000000,stroke-width:2
    style DIAG fill:#F5F5F5,stroke:#000000,stroke-width:2
    style MATRIZ fill:#F5F5F5,stroke:#000000,stroke-width:2
    style PROMPT fill:#F5F5F5,stroke:#000000,stroke-width:2
    style SCHEMA fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RAG fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TOOL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style AJUSTE fill:#F5F5F5,stroke:#000000,stroke-width:2
    style LOCAL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style EVAL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RUBRICA fill:#F5F5F5,stroke:#000000,stroke-width:2
    style LLM stroke-dasharray: 5 5
    style SAMPLING stroke-dasharray: 5 5
    style FT stroke-dasharray: 5 5
    style SERVING stroke-dasharray: 5 5
    style API stroke-dasharray: 5 5
    style COSTE stroke-dasharray: 5 5
    style MODELOS stroke-dasharray: 5 5
    style VECTOR stroke-dasharray: 5 5
    style RAGCAP stroke-dasharray: 5 5
    style DATA stroke-dasharray: 5 5
    style LAB stroke-dasharray: 5 5

Vocabulario aprendido

Estas palabras aparecerán en todo el facsímil. Conviene que queden limpias desde el principio.

Término	Definición
Intervención	Cambio concreto en el sistema para mejorar un síntoma medible.
Prompt	Entrada que define tarea, contexto, ejemplos y criterio.
Schema	Estructura esperada de una salida o una tool.
Salida estructurada	Respuesta obligada a cumplir un formato validable.
RAG	Recuperar evidencia externa y pasarla al modelo como contexto.
Tool	Función externa que consulta, calcula o modifica algo bajo reglas.
Fine-tuning	Ajustar pesos de un modelo con datos propios.
LoRA	Ajuste eficiente con matrices pequeñas de bajo rango.
Modelo local	Modelo ejecutado en una máquina o infraestructura controlada.
Baseline	Comparación mínima antes de añadir complejidad.
Eval	Prueba repetible que mide calidad, coste, latencia o seguridad del sistema.
Matriz de decisión	Tabla que obliga a justificar una elección con criterios observables.
Reversibilidad	Facilidad para volver atrás si una intervención empeora el sistema.
Abstención	Capacidad de reconocer que falta evidencia suficiente para responder.

Antes de pasar página

En resumen

La caja de herramientas empieza por diagnóstico. Si eliges bien el problema, la herramienta suele volverse evidente.

Idea fuerza	Detalle
La herramienta no es el punto de partida.	Primero síntoma, casos reales y baseline.
Prompt/schema arreglan contrato de entrada y salida.	No hacen que el modelo sepa datos vivos.
RAG aporta evidencia externa.	Sirve para documentos cambiantes y respuestas citables.
Tool conecta con estado real.	Sirve para consultar, calcular o actuar sin inventar.
Ajustar pesos cambia comportamiento.	Tiene sentido en tareas repetidas, estables y medibles.
Local/cloud son decisiones de entorno.	Privacidad, coste, latencia y mantenimiento mandan.
Eval decide si la intervención se queda.	Sin medición, solo hay impresión.
Una buena decisión debe poder explicarse.	Criterio, alternativa descartada, métrica y rollback forman parte de la respuesta.

Para saber más

Anthropic. (2026). Prompt engineering overview. https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview

Dettmers, T. et al. (2023). QLoRA: Efficient Finetuning of Quantized LLMs. Advances in Neural Information Processing Systems 36. https://arxiv.org/abs/2305.14314

Hugging Face. (2026). PEFT: LoRA developer guide. https://huggingface.co/docs/peft/developer_guides/lora

Hu, E. J. et al. (2022). LoRA: Low-Rank Adaptation of Large Language Models. International Conference on Learning Representations. https://arxiv.org/abs/2106.09685

Lewis, P. et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. Advances in Neural Information Processing Systems 33, 9459-9474. https://papers.nips.cc/paper/2020/hash/6b493230205f780e1bc26945df7481e5-Abstract.html

Ollama. (2026). Introduction to the Ollama API. https://docs.ollama.com/api/introduction

Ollama. (2026). Ollama Cloud. https://docs.ollama.com/cloud

OpenAI. (2026). Function calling. https://developers.openai.com/api/docs/guides/function-calling

OpenAI. (2026). Structured model outputs. https://developers.openai.com/api/docs/guides/structured-outputs

Notas

OpenAI. (2026). Structured model outputs. https://developers.openai.com/api/docs/guides/structured-outputs. Consultado el 25 de mayo de 2026. La guía distingue entre salidas estructuradas para respuesta final y function calling cuando el modelo se conecta a herramientas o datos. ↩
Anthropic. (2026). Prompt engineering overview. https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview. Consultado el 25 de mayo de 2026. La guía trata el prompt como mecanismo de especificación de tarea, contexto, ejemplos y restricciones. ↩
Hugging Face. (2026). PEFT: LoRA developer guide. https://huggingface.co/docs/peft/developer_guides/lora. Consultado el 25 de mayo de 2026. PEFT documenta LoRA y variantes para entrenar adaptadores pequeños sobre modelos base. ↩
Ollama. (2026). Introduction to the Ollama API. https://docs.ollama.com/api/introduction. Consultado el 25 de mayo de 2026. La documentación indica la URL local por defecto y la URL cloud compatible. ↩
Ollama. (2026). Ollama Cloud. https://docs.ollama.com/cloud. Consultado el 25 de mayo de 2026. La guía describe modelos cloud que se ejecutan sin requerir una GPU local potente. ↩
Anthropic. (2026). Prompt engineering overview. https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview. Consultado el 25 de mayo de 2026. ↩
OpenAI. (2026). Structured model outputs. https://developers.openai.com/api/docs/guides/structured-outputs. Consultado el 25 de mayo de 2026. ↩
Lewis, P. et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. Advances in Neural Information Processing Systems 33, 9459-9474. https://papers.nips.cc/paper/2020/hash/6b493230205f780e1bc26945df7481e5-Abstract.html. ↩
OpenAI. (2026). Function calling. https://developers.openai.com/api/docs/guides/function-calling. Consultado el 25 de mayo de 2026. ↩
Hu, E. J. et al. (2022). LoRA: Low-Rank Adaptation of Large Language Models. International Conference on Learning Representations. https://arxiv.org/abs/2106.09685. Hugging Face. (2026). PEFT: LoRA developer guide. https://huggingface.co/docs/peft/developer_guides/lora. Consultado el 25 de mayo de 2026. ↩
Lewis, P. et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. Advances in Neural Information Processing Systems 33, 9459-9474. https://papers.nips.cc/paper/2020/hash/6b493230205f780e1bc26945df7481e5-Abstract.html. El trabajo formuló modelos que recuperan documentos y los combinan con generación. ↩
Hu, E. J. et al. (2022). LoRA: Low-Rank Adaptation of Large Language Models. International Conference on Learning Representations. https://arxiv.org/abs/2106.09685. ↩
Dettmers, T. et al. (2023). QLoRA: Efficient Finetuning of Quantized LLMs. Advances in Neural Information Processing Systems 36. https://arxiv.org/abs/2305.14314. ↩

Capítulo 02

Facsímil 4 · La caja de herramientas

Capítulo 02: APIs de modelos: mensajes, streaming y salidas estructuradas

El modelo no vive solo en una caja de texto

Cuando usamos un chat en el navegador, parece que el sistema funciona así: escribes una pregunta y aparece una respuesta. Para aprender a construir productos con IA, esa imagen se queda corta. Entre tu aplicación y el modelo hay un contrato: qué modelo llamas, qué mensajes envías, qué herramientas están disponibles, qué formato esperas, si quieres streaming, qué harás si la salida no valida y cómo guardarás la traza.

Este capítulo baja un escalón desde el criterio del capítulo 01. Allí decidimos cuándo tiene sentido usar prompt, schema, RAG, tool o ajuste. Aquí aprendemos a convertir esa decisión en una petición concreta a una API de modelos.

La idea central es sencilla: una API de modelos no es un buzón de texto; es una frontera entre software probabilístico y software verificable.

Estado del arte con fecha de corte

Fecha de corte: 10 de junio de 2026.
Fuentes consultadas ese día: documentación oficial de OpenAI sobre Responses API, generación de texto, archivos, visión, salidas estructuradas, function calling, streaming, SDKs y Agents SDK; documentación de Anthropic sobre Messages API, visión, PDF, streaming y structured outputs; documentación de Google sobre Gemini API, documentos, visión, structured outputs, ADK, MCP y A2A; documentación oficial del protocolo A2A; JSON Schema; y la especificación WHATWG de Server-Sent Events.

La parte estable es el patrón: enviar una petición con modelo, instrucciones, entrada, herramientas opcionales, formato esperado y opciones de ejecución. La parte cambiante son los nombres exactos de endpoints, SDKs, modelos, campos y límites. Por eso conviene aprender la arquitectura mental antes que memorizar una firma de cliente.

OpenAI documenta la generación de texto y el uso de salidas estructuradas para pedir respuestas que cumplan un schema.¹² También documenta function calling para que el modelo solicite llamadas a funciones definidas por la aplicación.³ Anthropic organiza su API alrededor de mensajes y documenta streaming y salidas estructuradas como patrones de construcción.⁴⁵⁶ Google documenta Gemini como una API de generación de contenido con entrada textual y multimodal, además de structured outputs basadas en schema.⁷⁸

La revisión del 10 de junio no cambia la tesis del capítulo, pero sí refuerza una decisión de ingeniería: no acoples tu dominio al JSON exacto de un proveedor. OpenAI mantiene como piezas centrales Responses, structured outputs, function calling y streaming; Anthropic conserva Messages API, streaming y patrones de salida estructurada; Google añade además superficies recientes alrededor de Interactions API, ADK y protocolos de agentes.⁹¹⁰¹¹ La conclusión práctica es aburrida y muy importante: escribe un adaptador por proveedor, valida la salida en tu código, guarda trazas comparables y deja que tu aplicación hable en objetos propios, no en campos de moda.

Qué no es una API de modelos

Una API de modelos no es “el prompt por HTTP”. Si la tratas así, acabarás pegando instrucciones, datos, historial, formato esperado y lógica de negocio en una sola cadena. Eso funciona en una demo; se vuelve frágil cuando hay usuarios reales.

Tampoco es una promesa de verdad. La API puede devolver texto muy convincente, pero tu aplicación sigue necesitando validación, métricas, trazas y reglas de producto. Si pides JSON y no validas JSON, no tienes contrato: tienes esperanza.

Y no es una interfaz idéntica entre proveedores. Muchos conceptos se parecen, pero los detalles cambian: roles disponibles, nombre del campo de entrada, eventos de streaming, formato de tools, límites, modelos, errores y objetos de respuesta. Por eso el diseño de tu aplicación debería tener una capa propia que traduzca “lo que necesita mi producto” a “lo que espera este proveedor”.

Qué sí es: un contrato entre capas

Una API de modelos es un contrato entre tres mundos. El primero es tu aplicación: usuarios, permisos, pantallas, flujos y datos. El segundo es el proveedor del modelo: endpoint, modelo, tokens, eventos, herramientas y respuesta. El tercero es tu código de integración: validadores, retries, logs, evals y transformación a objetos de dominio.

Ejemplo de fórmula. Una petición mínima puede pensarse así:

r=(m,\ I,\ C,\ F,\ T,\ S)

Símbolo	Significado	Ejemplo
$r$	Request o petición completa.	Una llamada para clasificar una solicitud.
$m$	Modelo elegido.	Un modelo rápido para clasificación.
$I$	Instrucciones y mensajes.	Rol del sistema, contexto y pregunta del usuario.
$C$	Contexto externo.	Fragmentos RAG, datos de producto o historial relevante.
$F$	Formato de salida.	JSON con `categoria`, `prioridad` y `siguiente_paso`.
$T$	Tools disponibles.	`consultar_expediente(id_alumno)`.
$S$	Opciones de servicio.	Streaming, límite de salida, metadata o timeout.

Esta forma de verlo ayuda a no mezclar piezas. Si falla $F$ , quizá necesitas schema. Si falla $C$ , quizá necesitas retrieval. Si falta $T$ , el modelo no debería inventar estado externo. Si falla $S$ , puede que el problema sea latencia, no inteligencia.

Qué APIs se usan hoy y quién las usa

A 10 de junio de 2026, cuando una empresa dice “vamos a llamar a un LLM desde nuestra app”, normalmente está hablando de una de estas familias. No son las únicas, pero sí sirven para entender el mercado: APIs directas de laboratorios, APIs cloud que empaquetan varios modelos, gateways que unifican proveedores y runtimes locales que imitan una interfaz remota.

OpenAI organiza gran parte de su construcción moderna alrededor de la Responses API: una llamada que puede recibir entrada multimodal, instrucciones, tools, formato de salida, streaming y opciones de ejecución.¹² La usan equipos que quieren construir asistentes, clasificadores, flujos con herramientas, extracción estructurada, análisis de documentos, experiencias con visión o productos donde una respuesta textual debe convertirse en objeto de software.

Anthropic expone Claude principalmente mediante Messages API para conversaciones y turnos sin estado: envías una lista estructurada de mensajes y el modelo genera el siguiente mensaje.¹³ Es habitual en productos que necesitan lectura y escritura largas, análisis documental, asistentes internos, ayuda a programación, tutoría o flujos donde interesa controlar muy bien el historial enviado.

Google ofrece la Gemini API alrededor de generateContent, con entradas que pueden combinar texto, imágenes, vídeo y audio, además de configuración de generación y salidas estructuradas.¹⁴ Encaja especialmente en productos multimodales, prototipos integrados con el ecosistema Google, procesamiento de documentos y aplicaciones que quieren aprovechar modelos con ventanas largas o capacidades visuales.

Además existen plataformas como Amazon Bedrock, Vertex AI, Azure AI Foundry, Mistral, Cohere, Groq, Together, Fireworks, OpenRouter o Vercel AI SDK. La lección no es aprenderlas todas de memoria. La lección es que casi todas terminan pidiendo lo mismo con nombres distintos: modelo, entrada, instrucciones, parámetros de generación, herramientas, schema, streaming, límites y metadatos.

Los parámetros: no memorizar nombres, entender familias

Cuando un alumno ve por primera vez una referencia de API, se pierde porque parece una lista interminable de campos. La forma útil de estudiarla es agrupar parámetros por intención. Unos campos dicen qué modelo usamos; otros dicen qué entra; otros controlan cuánto y cómo responde; otros definen qué herramientas puede pedir; otros describen qué forma debe tener la salida; y otros sirven para operar el sistema.

Ejemplo de fórmula. La petición completa puede verse así:

r=(p,\ x,\ g,\ o,\ q)

Símbolo	Significado	Ejemplo
$p$	Proveedor y modelo.	OpenAI con Responses API, Claude con Messages API o Gemini con `generateContent`.
$x$	Entrada del usuario y contexto.	Texto, historial, documentos, imagen o fragmentos recuperados.
$g$	Parámetros de generación.	Límite de salida, temperatura, `top_p`, `top_k` o secuencias de parada.
$o$	Contrato operativo.	Streaming, tools, tool choice, metadata, traza y timeout.
$q$	Contrato de calidad.	Schema, validador, evals y reglas de producto.

La tabla siguiente no pretende congelar una API que cambia. Sirve para reconocer equivalencias:

Familia	OpenAI Responses API	Anthropic Messages API	Gemini API
Modelo	`model`	`model`	modelo en `models.generateContent` o ruta REST.
Entrada	`input` con mensajes y bloques de contenido.	`messages` con contenido por turnos.	`contents` con `parts`.
Instrucciones estables	`instructions` o mensajes equivalentes según SDK.	`system` como campo superior.	`systemInstruction` o configuración equivalente.
Límite de salida	`max_output_tokens` según modelo y endpoint.	`max_tokens`.	`maxOutputTokens` dentro de configuración.
Aleatoriedad	`temperature`, `top_p` cuando el modelo lo permita.	`temperature`, `top_p`, `top_k` según modelo.	`temperature`, `topP`, `topK`.
Parada	secuencias de parada si están disponibles.	`stop_sequences`.	`stopSequences`.
Salida estructurada	formato de texto/schema o Structured Outputs.	`output_config.format` o tool estricta, según caso.	`responseMimeType` y `responseJsonSchema`.
Tools	`tools` y `tool_choice`.	`tools` y `tool_choice`.	`tools` y function calling.
Streaming	`stream` y eventos.	`stream` con eventos SSE.	métodos de streaming del SDK o REST.
Metadatos y operación	`metadata`, trazas, `user` o campos de servicio cuando existan.	`metadata`, uso de tokens y estado de parada.	`usageMetadata`, configuración y metadatos del entorno.

El parámetro más peligroso no es siempre el más técnico. Muchas integraciones fallan por no fijar bien max_tokens o max_output_tokens, por mezclar instrucciones con datos del usuario, por no versionar el schema o por asumir que temperature=0 convierte una salida probabilística en una función matemática.

Entradas y salidas: qué ocurre en cada caso

Una API de modelos no devuelve siempre “texto”. Puede devolver texto, JSON, una petición de tool, eventos parciales o una combinación de bloques. Por eso conviene diseñar el flujo antes de escribir el cliente.

Caso	Entra	Sale	Qué debe hacer tu aplicación
Texto a texto	Pregunta, instrucciones y contexto breve.	Respuesta natural.	Mostrar, registrar y quizá evaluar calidad.
Texto a JSON	Texto y schema.	Objeto estructurado.	Parsear, validar y transformar a objeto de dominio.
Documento a resumen	Archivo, páginas o fragmentos.	Resumen, citas o extracción.	Conservar referencia a página, versión y documento original.
Imagen a explicación	Imagen más pregunta.	Descripción, clasificación o lectura visual.	Revisar límites visuales y pedir evidencia cuando importe.
Texto a tool call	Petición y definición de función.	Nombre de tool y argumentos.	Validar argumentos, comprobar permisos y ejecutar código.
Tool result a respuesta	Resultado externo.	Explicación final.	Separar dato consultado de redacción generada.
Streaming	Petición normal con `stream`.	Eventos parciales.	Acumular, cancelar, manejar errores y cerrar estado.

La salida estructurada y las tool calls se parecen porque usan schemas, pero no cumplen la misma misión. Una salida estructurada es el resultado final con forma de dato. Una tool call es una solicitud intermedia para que el sistema consulte, calcule o actúe. Si confundes ambas cosas, tu app termina ejecutando texto como si fuera una decisión cerrada.

Documentos e imágenes: multimodal no significa comprensión automática

Enviar una imagen o un PDF a un modelo multimodal no equivale a “el modelo lo sabe todo sobre ese archivo”. Equivale a darle una entrada rica que el modelo puede procesar dentro de sus límites. OpenAI documenta bloques como input_file para archivos y input_image para imágenes dentro de la entrada.¹⁵¹⁶ Anthropic documenta visión y soporte de PDF para Claude.¹⁷¹⁸ Gemini permite pasar imágenes como datos inline o mediante Files API, y documenta límites específicos para PDF.¹⁹²⁰

Para una sola imagen, suele bastar con enviar la imagen y una pregunta clara: “lee esta factura y extrae fecha, proveedor e importe”. Para muchas imágenes o archivos repetidos, conviene subirlos una vez y referenciarlos. Para un PDF largo, hay que decidir si se manda entero, si se divide por páginas, si se indexa en un sistema RAG o si se usa una combinación: retrieval para localizar fragmentos y modelo multimodal para interpretar tablas, figuras o páginas concretas.

Hay cuatro cosas que no deberíamos olvidar:

Cuidado	Por qué importa	Buena práctica
Tamaño y coste	Imágenes y documentos consumen contexto y pueden aumentar latencia.	Medir tokens, páginas, resolución y tiempo de respuesta.
Referencias	Una respuesta sin página o fragmento es difícil de revisar.	Pedir `pagina`, `fragmento` o `evidencia` en el schema.
Privacidad	Los documentos pueden contener datos personales o internos.	Minimizar, redactar cuando sea posible y revisar política del proveedor.
Lectura visual	Un modelo puede interpretar mal tablas, sellos o capturas pequeñas.	Comprobar con OCR, reglas o revisión humana cuando importe.

La regla práctica: si el documento es fuente de verdad, no lo trates como “contexto decorativo”. Guárdalo con identificador, versión, fecha de carga y forma de recuperación. Si mañana alguien pregunta por qué la app contestó eso, debes poder reconstruir qué archivo vio, qué páginas entraron y qué schema validó la salida.

Mensajes: separar instrucciones, contexto y petición

La mayoría de APIs modernas no reciben solo una cadena. Reciben mensajes o una estructura equivalente. El objetivo no es teatralizar una conversación, sino separar responsabilidades: qué reglas gobiernan la tarea, qué dijo la persona usuaria, qué contestó antes el modelo y qué resultados devolvieron herramientas.

Pieza	Qué representa	Riesgo si se mezcla
Instrucciones de sistema o desarrollador	Comportamiento estable que quieres mantener.	El usuario puede pisar reglas importantes con texto accidental.
Mensaje de usuario	La petición concreta de esta interacción.	El sistema no distingue objetivo de contexto.
Contexto recuperado	Evidencia externa añadida por la aplicación.	El modelo no sabe qué parte citar o priorizar.
Mensaje del asistente	Respuesta anterior o salida actual.	Se pierde trazabilidad en conversaciones largas.
Resultado de tool	Dato externo obtenido por código.	Se confunde texto generado con dato comprobado.

Un patrón robusto consiste en construir la petición desde piezas separadas y solo al final traducirlas al formato del proveedor. Así puedes cambiar de modelo sin reescribir la lógica de negocio.

Para entenderlo: si una app universitaria pregunta “¿puede Ana matricularse de Sistemas Inteligentes?”, no deberías mandar solo esa frase. Deberías separar la política académica vigente, el identificador de Ana, las reglas de formato de salida y, si hace falta, la tool que consulta expediente.

Salidas estructuradas: cuando el texto debe convertirse en dato

Pedir “responde en JSON” es una intención. Usar un schema es un contrato. JSON Schema define vocabulario para describir tipos, propiedades, campos requeridos y reglas de validación sobre documentos JSON.²¹ Las APIs de modelos aprovechan esa idea para reducir la distancia entre respuesta natural y objeto que tu software puede consumir.

La métrica mínima de una salida estructurada es la tasa de conformidad:

\operatorname{validez}=\frac{N_{\text{válidas}}}{N_{\text{total}}}

Símbolo	Significado	Ejemplo
$N_{\text{válidas}}$	Respuestas que cumplen schema.	97 de 100 respuestas.
$N_{\text{total}}$	Respuestas evaluadas.	100 casos de prueba.
$\operatorname{validez}$	Proporción de salidas estructuralmente correctas.	$0{,}97$ .

Pero cuidado: una respuesta puede cumplir schema y seguir siendo mala. Si el schema pide prioridad, el valor puede ser válido como texto y estar mal como decisión. Por eso necesitamos dos validaciones:

Validación	Pregunta	Ejemplo
Estructural	¿Cumple tipos, campos y restricciones?	`prioridad` existe y vale `alta`, `media` o `baja`.
Semántica	¿El contenido es correcto para el caso?	El mensaje realmente requiere prioridad alta.

La salida estructurada arregla el contrato con el software. No reemplaza la evaluación del criterio.

Streaming: que la respuesta llegue por partes

Streaming significa que la aplicación no espera a tener toda la respuesta para empezar a recibir fragmentos. En la web moderna suele implementarse con eventos o flujos parecidos a Server-Sent Events, donde el servidor envía datos progresivamente al cliente.²² OpenAI y Anthropic documentan streaming para respuestas de modelos.²³²⁴

La razón no es solo estética. El streaming cambia la experiencia percibida.

Ejemplo de fórmula. Para explicarlo en una revisión de producto, puedes separar primer evento y lectura progresiva:

T_{\text{percibido}} \approx T_{\text{primer\_evento}} + T_{\text{lectura\_progresiva}}

Símbolo	Significado	Ejemplo
$T_{\text{primer\_evento}}$	Tiempo hasta recibir el primer fragmento.	700 ms.
$T_{\text{lectura\_progresiva}}$	Tiempo durante el que se van mostrando fragmentos.	La respuesta aparece mientras se genera.
$T_{\text{percibido}}$	Latencia que siente la persona usuaria.	Menor que esperar todo el texto junto.

Streaming no hace que el modelo “piense mejor”. Hace que el producto pueda mostrar progreso, cancelar, actualizar UI y registrar eventos. También complica: debes ensamblar fragmentos, manejar cortes, distinguir eventos de texto y eventos de tool, y decidir cuándo una salida estructurada está lista para validarse.

Tool calls: cuando responder no basta

Una salida estructurada devuelve datos. Una tool call pide que tu aplicación ejecute algo. Esa diferencia parece pequeña y es enorme.

Necesidad	Salida estructurada	Tool call
Clasificar un mensaje	Devuelve `{categoria, prioridad}`.	Normalmente no hace falta.
Consultar stock	Puede devolver intención de consulta.	Llama `consultar_stock(producto, talla)`.
Calcular una cuota	Puede proponer fórmula.	Llama `calcular_cuota(importe, plazo)`.
Abrir un ticket	Puede redactar el contenido.	Llama `crear_ticket(...)` si el usuario confirma.

La regla práctica: si el dato existe fuera del modelo, no lo conviertas en adivinanza. Define una tool pequeña, valida sus argumentos, ejecuta el código y devuelve el resultado como contexto para que el modelo lo explique.

Para entenderlo antes de tocar código

Pensemos en cuatro productos que parecen parecidos porque todos “usan IA”, pero que piden contratos distintos.

Producto	Qué envía a la API	Qué espera recibir	Pieza crítica
Clasificador de correos internos	Texto del correo e instrucciones.	JSON con cola, prioridad y motivo breve.	Schema y validador.
Tutor universitario	Pregunta, nivel del curso y rúbrica.	Explicación paso a paso.	Mensajes bien separados.
Asistente de matrícula	Pregunta y contexto normativo recuperado.	Respuesta con cita y quizá tool de expediente.	RAG, tool y trazabilidad.
Redactor con respuesta larga	Brief, tono y ejemplos.	Texto progresivo en pantalla.	Streaming y cancelación.

El mismo modelo puede participar en los cuatro, pero la API no se usa igual. En uno importa más el schema; en otro, el streaming; en otro, tools; en otro, trazabilidad del contexto.

Buenas prácticas de integración

Una integración madura no empieza llamando al SDK desde cualquier pantalla. Empieza con un contrato propio de la aplicación. Ese contrato dice: “para clasificar una solicitud necesito estos campos, esta política, este schema, estas tools permitidas y esta forma de guardar trazas”. Después un adaptador traduce ese contrato al proveedor elegido.

El adaptador evita que el resto del producto sepa si por debajo hay OpenAI, Claude, Gemini, un modelo local o un gateway. También te obliga a decidir lo importante en un sitio: versionar prompts, schemas y modelos; convertir errores de proveedor en errores propios; medir coste; registrar identificadores; y probar la misma tarea con casos de evaluación.

Práctica	Qué resuelve	Cómo se ve en código o producto
Adaptador por proveedor	Evita acoplar pantallas a nombres de campos externos.	`crearRespuestaTutor(...)` traduce a OpenAI, Claude o Gemini.
Schema versionado	Permite cambiar formato sin romper consumidores.	`respuesta_matricula.v2.json`.
Validador propio	No delega toda la corrección al proveedor.	Pydantic, Zod, JSON Schema o validación del backend.
Trazas mínimas	Permite reproducir fallos sin guardar más de lo necesario.	`trace_id`, modelo, versión de prompt, schema y resumen de entrada.
Timeouts y reintentos	Evita dejar al usuario esperando sin cierre.	Reintento solo en operaciones idempotentes.
Tools pequeñas	Reduce ambigüedad y facilita permisos.	`consultar_expediente(id)` en vez de `hacer_cosas(datos)`.
Evals antes de publicar	Mide si la integración mejora o empeora.	Conjunto de casos fijos con salida esperada.
Streaming con máquina de estados	Evita UI a medias.	`iniciado`, `parcial`, `tool`, `completo`, `cancelado`, `error`.

Ejemplo de fórmula. La integración más limpia que conozco tiene esta forma mental:

\text{producto} \rightarrow \text{contrato propio} \rightarrow \text{adaptador} \rightarrow \text{proveedor} \rightarrow \text{validador} \rightarrow \text{producto}

Pieza	Pregunta que responde
Producto	¿Qué necesita conseguir la persona usuaria?
Contrato propio	¿Qué datos, formato, tools y reglas exige nuestro flujo?
Adaptador	¿Cómo se expresa eso en la API concreta?
Proveedor	¿Qué modelo genera, pide tool o devuelve eventos?
Validador	¿La salida cumple estructura y criterio mínimo?
Producto	¿Mostramos, pedimos confirmación, guardamos o repetimos?

Cómo sería una API perfecta para integrar

Una API perfecta no sería “la que siempre acierta”. Eso no existe. Sería la que hace fácil construir software fiable alrededor de una capacidad probabilística. Si diseñáramos una interfaz ideal para una app profesional, tendría estas propiedades:

Rasgo	Por qué importa
Entrada multimodal tipada	Texto, imágenes y documentos no llegan como una cadena opaca.
Instrucciones separadas	Las reglas estables no se mezclan con lo que escribe la persona usuaria.
Salida schema-first	El contrato de datos se declara antes de generar.
Tools tipadas y pequeñas	La API distingue pedir una acción de ejecutar una acción.
Eventos normalizados	Streaming, tool calls y errores siguen una secuencia predecible.
Uso y coste visibles	La respuesta trae tokens, latencia y modelo usado.
Versionado explícito	Prompt, schema, modelo y toolset se pueden congelar y comparar.
Errores tipados	La app sabe si hubo límite, timeout, validación fallida o contenido incompleto.
Idempotencia	Reintentar no duplica acciones sensibles ni crea registros repetidos.
Privacidad configurable	Puedes decidir qué se guarda, qué se omite y durante cuánto tiempo.
Evals integradas	El mismo contrato puede probarse con casos antes de publicarse.

En pseudocódigo, una llamada ideal se parecería menos a “envía este texto” y más a esto:

respuesta = modelo.generar({
  tarea: "clasificar_solicitud_matricula",
  contrato: "solicitud_matricula.v2",
  entrada: {texto, documentos, usuario_contexto},
  salida: schema_respuesta,
  tools: [consultar_expediente],
  ejecucion: {stream: true, timeout_ms: 12000, trace_id},
  politica: {confirmar_antes_de_crear_ticket: true}
})

La clave no es que todos los proveedores adopten exactamente ese formato. La clave es que tu aplicación sí tenga esa claridad interna. Si tu dominio está bien modelado, cambiar de proveedor es una migración. Si tu dominio vive pegado al prompt, cambiar de proveedor es cirugía.

Mapa visual de una petición robusta

El diagrama resume la idea práctica del capítulo: la aplicación no debería hablar con el modelo como quien manda una frase suelta, sino como quien prepara un contrato que luego valida.

Mapa Mermaid: todo lo que viaja en una API

El SVG anterior da la intuición editorial. Ahora conviene ver la llamada como arquitectura técnica: qué construye tu aplicación, qué transforma el SDK o adaptador, qué recibe el proveedor y qué vuelve a tu sistema.

flowchart TD
    subgraph "Aplicación propia"
        UI["UI o backend"]
        DOMINIO["Objeto de dominio"]
        TRAZA_APP["Trace id y evals"]
    end

    subgraph "Contrato interno"
        REQ["Request canónica"]
        INSTR["Instrucciones"]
        ENTRADA["Texto, historial<br/>multimodal"]
        PARAMS["Parámetros de generación"]
        SCHEMA["Schema de salida"]
        TOOLS["Tools permitidas"]
    end

    subgraph "Adaptador o SDK"
        SDK["SDK: auth, tipos<br/>streaming"]
        MAPEO["Mapeo a proveedor"]
        ERRORES["Errores normalizados"]
    end

    subgraph "API del proveedor"
        OAI["OpenAI Responses"]
        CLAUDE["Claude Messages"]
        GEMINI["Gemini generateContent"]
    end

    subgraph "Ejecución"
        EVENTOS["Eventos stream"]
        TOOLCALL["Tool call"]
        MCP["MCP: tools y recursos"]
        VALIDAR["Validación estructural<br/>y semántica"]
    end

    subgraph "Capa agente opcional"
        AGENTSDK["Agents SDK o ADK"]
        A2A["A2A: Agent Card<br/>Task, Message, Artifact"]
    end

    UI --> DOMINIO
    DOMINIO --> REQ
    REQ --> INSTR
    REQ --> ENTRADA
    REQ --> PARAMS
    REQ --> SCHEMA
    REQ --> TOOLS
    REQ --> SDK
    SDK --> MAPEO
    MAPEO --> OAI
    MAPEO --> CLAUDE
    MAPEO --> GEMINI
    OAI --> EVENTOS
    CLAUDE --> EVENTOS
    GEMINI --> EVENTOS
    EVENTOS --> TOOLCALL
    TOOLCALL --> MCP
    MCP --> EVENTOS
    EVENTOS --> VALIDAR
    VALIDAR --> TRAZA_APP
    TRAZA_APP --> UI
    AGENTSDK --> REQ
    AGENTSDK --> MCP
    AGENTSDK --> A2A
    A2A --> AGENTSDK
    ERRORES --> TRAZA_APP
    SDK --> ERRORES

    classDef own fill:#F5F5F5,stroke:#000000,stroke-width:2,color:#111111
    classDef external fill:#FFFFFF,stroke:#000000,stroke-width:1.4,color:#111111,stroke-dasharray:5 5
    class UI,DOMINIO,TRAZA_APP,REQ,INSTR,ENTRADA,PARAMS,SCHEMA,TOOLS,SDK,MAPEO,ERRORES,EVENTOS,TOOLCALL,VALIDAR own
    class OAI,CLAUDE,GEMINI,MCP,AGENTSDK,A2A external

En el día a día

En un proyecto real, este capítulo aparece cuando alguien dice: “ya tenemos el prompt, vamos a integrarlo”. Ahí empieza el trabajo serio. Hay que decidir qué parte será configuración, qué parte será código, qué parte será schema y qué parte quedará en logs para poder depurar.

Si una respuesta alimenta otra pantalla, no basta con que “se lea bien”. Debe llegar como objeto fiable. Si una respuesta se muestra mientras se genera, debes pensar en streaming y cancelación. Si el modelo pide una tool, debes decidir quién ejecuta, con qué permisos, cómo se registra y qué ocurre si faltan argumentos.

La integración buena suele tener una capa intermedia: tu aplicación habla en términos de dominio, y esa capa traduce a la API concreta. Así evitas que cada pantalla dependa de detalles de un proveedor.

Por qué debería importarte

Porque una mala integración convierte una capacidad potente en un sistema difícil de mantener. Si guardas texto sin estructura, mañana no podrás medir. Si no validas schema, el backend se rompe tarde. Si no separas mensajes, no sabrás qué instrucción produjo qué comportamiento. Si no registras eventos de streaming y tools, no podrás explicar por qué una respuesta salió como salió.

La buena noticia: una API bien tratada como contrato permite cambiar modelos, añadir RAG, introducir tools y medir calidad sin rehacer todo el producto.

SDKs, ADK, MCP y A2A: cada cosa en su capa

Aquí suele nacer mucha confusión porque todo parece “la API”. No lo es. Una API es el contrato de red y datos. Un SDK es una biblioteca en tu lenguaje que envuelve esa API. Un framework de agentes es una capa que orquesta pasos, estado, tools y decisiones. Y un protocolo de interoperabilidad define cómo se comunican sistemas que quizá ni comparten proveedor ni framework.

OpenAI documenta SDKs oficiales para lenguajes como JavaScript/TypeScript y Python, pensados para llamar a la API desde código de aplicación.²⁵ El SDK no cambia la semántica: si el endpoint espera input, tools, stream o un schema, el SDK lo expresa con tipos, métodos, helpers de streaming, subida de archivos y manejo de errores. Es cómodo, pero no sustituye al diseño del contrato.

OpenAI también documenta Agents SDK para casos donde tu servidor posee la orquestación, la ejecución de tools, el estado y las aprobaciones del flujo.²⁶ Google ADK va en esa misma familia de herramientas de construcción de agentes: su documentación organiza piezas como agentes, equipos de agentes, workflows, ejecución, observabilidad, evaluación, tools, sesiones, memoria, artefactos, MCP y A2A.²⁷ La propia documentación de ADK incluye guías para exponer agentes a otros sistemas y consumir agentes remotos mediante A2A.²⁸

MCP y A2A resuelven problemas distintos. ADK describe MCP como un estándar para que LLMs y agentes se comuniquen con aplicaciones externas, fuentes de datos y herramientas mediante recursos, prompts y tools.²⁹ A2A, en cambio, es para comunicación entre agentes: la documentación oficial lo presenta como un estándar abierto para interoperabilidad entre agentes construidos con distintos frameworks o proveedores.³⁰

Técnicamente, A2A introduce piezas que no aparecen en una simple llamada a un modelo: AgentCard, Message, Part, Task, TaskStatus, Artifact, métodos para enviar mensajes, consultar tareas, cancelar, suscribirse a eventos y entregar resultados por streaming o notificaciones.³¹ La AgentCard dice qué agente hay al otro lado, qué capacidades ofrece y cómo se accede. Un Message lleva partes de contenido; una Task representa trabajo con estado; un Artifact es una salida producida por el agente remoto.

Capa	Objeto principal	Quién controla el estado	Para qué sirve
API de modelos	Request y response.	Tu aplicación y el proveedor.	Generar, estructurar, llamar tools o recibir eventos.
SDK	Cliente tipado del lenguaje.	Tu aplicación.	Autenticación, tipos, helpers, streaming y errores.
Agents SDK / ADK	Run, sesión, agente, workflow, tool context.	Tu servidor o runtime de agentes.	Orquestar pasos, tools, memoria, evaluación y observabilidad.
MCP	Tool, recurso, prompt.	Host de IA y servidor MCP.	Conectar agentes o apps a herramientas y datos externos.
A2A	Agent Card, Message, Task, Part, Artifact.	Agente cliente y agente remoto.	Delegar tareas entre agentes independientes y recibir progreso o resultados.

Para entenderlo con una situación concreta: si una app de la universidad pregunta a un modelo “clasifica esta solicitud”, quizá basta la API y un SDK. Si necesita consultar expediente, el modelo puede pedir una tool; esa tool puede venir de tu backend o de un servidor MCP. Si además hay un agente remoto especializado en normativa académica, tu agente podría descubrirlo mediante una AgentCard, enviarle un Message, recibir una Task en estado working, escuchar eventos y recoger un Artifact final. Ahí ya no estás “llamando a un modelo”: estás coordinando sistemas.

Dónde volverá a aparecer

Este capítulo es el puente entre diagnóstico y construcción. Lo usaremos varias veces:

Concepto	Dónde vuelve	Para qué
Tokens y contexto	Capítulo 03.	Calcular coste, límites y tamaño de entrada/salida.
Model cards	Capítulo 04.	Elegir modelo según capacidades reales.
Modelos locales	Capítulos 05 y 06.	Traducir la misma idea de API a entornos locales o privados.
Embeddings y RAG	Capítulos 07 a 10.	Añadir contexto externo y evaluar si fundamenta la respuesta.
Multimodalidad	Capítulo 11.	Enviar documentos, imágenes o capturas con criterio técnico.
Text-to-SQL	Capítulo 12.	Convertir lenguaje natural en consultas validadas.
Agentes, MCP y A2A	Facsímil 05.	Pasar de llamadas aisladas a workflows con tools, agentes remotos y protocolos.

Dónde solía tropezar yo

Estos tropiezos aparecen cuando uno pasa de probar prompts a construir una aplicación que tiene que vivir.

Error	Por qué es un error	Antídoto
Meter todo en un único prompt	Instrucción, contexto, formato y datos se vuelven inseparables.	Construir mensajes y contexto por capas.
Validar solo que haya JSON	Un objeto puede estar bien formado y contener una decisión mala.	Separar validación estructural y semántica.
Confundir tool call con ejecución	Que el modelo pida una función no significa que deba ejecutarse sin más.	Validar argumentos y aplicar reglas de negocio antes de ejecutar.
Usar streaming sin estado claro	Si se corta el flujo, puedes dejar la UI o la traza a medias.	Diseñar estados: iniciado, parcial, completo, cancelado y error.
Mandar documentos sin referencia	La respuesta queda desligada del archivo, página o versión que la produjo.	Guardar identificador, páginas usadas y schema de extracción.
Acoplarse al proveedor demasiado pronto	Cada pantalla acaba hablando el dialecto de una API concreta.	Usar un contrato propio y adaptadores por proveedor.
Confundir SDK con arquitectura	El SDK facilita la llamada, pero no decide schemas, permisos, trazas ni evaluación.	Diseñar primero contrato y flujo; elegir SDK después.
Mezclar MCP y A2A	MCP conecta tools y recursos; A2A conecta agentes completos con tareas y artefactos.	Dibujar qué sistema habla con qué sistema antes de integrar.
No guardar trazas mínimas	Sin request, respuesta, schema y versión de modelo no puedes reproducir fallos.	Registrar lo necesario para depurar sin guardar datos innecesarios.

Manos a la obra

Vamos a construir una petición de API completa sin llamar a Internet. Es decir: no necesitamos clave, pero sí vamos a ver la forma mental correcta de una integración real. Prepararemos un contrato de producto, lo traduciremos a un payload de OpenAI Responses API y dejaremos equivalentes para Claude Messages API y Gemini API. El objetivo no es memorizar cada nombre de campo, sino ver dónde vive cada decisión.

Fíjate en algo importante: timeout, retry_policy e idempotency_key no son parámetros del modelo; son parte de tu cliente HTTP o SDK. En una integración seria también deben estar configurados, aunque no viajen dentro del JSON del proveedor.

import json
from copy import deepcopy

RESPUESTA_SCHEMA = {
    "type": "object",
    "additionalProperties": False,
    "required": [
        "categoria",
        "prioridad",
        "siguiente_paso",
        "confianza",
        "evidencias",
        "necesita_tool",
    ],
    "properties": {
        "categoria": {
            "type": "string",
            "enum": ["matricula", "pagos", "beca", "soporte", "otro"],
        },
        "prioridad": {
            "type": "string",
            "enum": ["baja", "media", "alta"],
        },
        "siguiente_paso": {"type": "string"},
        "confianza": {"type": "number", "minimum": 0, "maximum": 1},
        "evidencias": {
            "type": "array",
            "items": {
                "type": "object",
                "additionalProperties": False,
                "required": ["fuente", "detalle"],
                "properties": {
                    "fuente": {"type": "string"},
                    "detalle": {"type": "string"},
                },
            },
        },
        "necesita_tool": {"type": "boolean"},
    },
}

TOOL_CONSULTAR_EXPEDIENTE = {
    "type": "function",
    "name": "consultar_expediente",
    "description": "Consulta datos mínimos de matrícula para un alumno.",
    "parameters": {
        "type": "object",
        "additionalProperties": False,
        "required": ["id_alumno", "curso"],
        "properties": {
            "id_alumno": {"type": "string"},
            "curso": {"type": "string"},
        },
    },
}

contrato_producto = {
    "trace_id": "trc_matricula_2026_00042",
    "schema_version": "clasificacion_matricula.v2",
    "feature": "asistente_matricula",
    "usuario_hash": "usr_anon_8f31",
    "modelo": "modelo-multimodal-vigente",
    "temperatura": 0.2,
    "top_p": 0.9,
    "max_salida": 900,
    "stream": True,
    "timeout_segundos": 12,
    "reintentos": 2,
}

openai_responses_request = {
    "model": contrato_producto["modelo"],
    "instructions": (
        "Eres un asistente de matrícula. Clasifica la solicitud, "
        "usa herramientas solo si faltan datos de expediente y responde "
        "siempre con el schema indicado."
    ),
    "input": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": (
                        "Ana dice: he pagado la matrícula, pero el campus "
                        "sigue marcando la asignatura como pendiente."
                    ),
                },
                {
                    "type": "input_file",
                    "file_id": "file_normativa_matricula_2026",
                },
                {
                    "type": "input_image",
                    "image_url": "https://example.edu/captura-campus.png",
                },
            ],
        }
    ],
    "text": {
        "format": {
            "type": "json_schema",
            "name": "clasificacion_matricula",
            "strict": True,
            "schema": RESPUESTA_SCHEMA,
        }
    },
    "tools": [TOOL_CONSULTAR_EXPEDIENTE],
    "tool_choice": "auto",
    "temperature": contrato_producto["temperatura"],
    "top_p": contrato_producto["top_p"],
    "max_output_tokens": contrato_producto["max_salida"],
    "parallel_tool_calls": False,
    "stream": contrato_producto["stream"],
    "store": False,
    "metadata": {
        "trace_id": contrato_producto["trace_id"],
        "feature": contrato_producto["feature"],
        "schema_version": contrato_producto["schema_version"],
    },
}

cliente_http = {
    "method": "POST",
    "url": "https://api.openai.com/v1/responses",
    "headers": {
        "Authorization": "Bearer $OPENAI_API_KEY",
        "Content-Type": "application/json",
    },
    "json": openai_responses_request,
    "timeout_seconds": contrato_producto["timeout_segundos"],
    "retry_policy": {
        "max_attempts": contrato_producto["reintentos"],
        "retry_on_status": [429, 500, 502, 503, 504],
        "idempotency_key": contrato_producto["trace_id"],
    },
}

# Con un SDK real, esta sería la idea:
# client.responses.create(**openai_responses_request)

anthropic_messages_request = {
    "model": "claude-modelo-vigente",
    "max_tokens": contrato_producto["max_salida"],
    "system": openai_responses_request["instructions"],
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": openai_responses_request["input"][0]["content"][0]["text"]},
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": "<pdf_base64>",
                    },
                },
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": "<png_base64>",
                    },
                },
            ],
        }
    ],
    "tools": [
        {
            "name": TOOL_CONSULTAR_EXPEDIENTE["name"],
            "description": TOOL_CONSULTAR_EXPEDIENTE["description"],
            "input_schema": TOOL_CONSULTAR_EXPEDIENTE["parameters"],
        }
    ],
    "tool_choice": {"type": "auto"},
    "temperature": contrato_producto["temperatura"],
    "top_p": contrato_producto["top_p"],
    "top_k": 40,
    "stop_sequences": [],
    "stream": contrato_producto["stream"],
    "metadata": {"user_id": contrato_producto["usuario_hash"]},
}

gemini_generate_content_request = {
    "systemInstruction": {
        "parts": [{"text": openai_responses_request["instructions"]}]
    },
    "contents": [
        {
            "role": "user",
            "parts": [
                {"text": openai_responses_request["input"][0]["content"][0]["text"]},
                {
                    "fileData": {
                        "mimeType": "application/pdf",
                        "fileUri": "files/normativa_matricula_2026",
                    }
                },
                {
                    "inlineData": {
                        "mimeType": "image/png",
                        "data": "<png_base64>",
                    }
                },
            ],
        }
    ],
    "generationConfig": {
        "temperature": contrato_producto["temperatura"],
        "topP": contrato_producto["top_p"],
        "topK": 40,
        "maxOutputTokens": contrato_producto["max_salida"],
        "responseMimeType": "application/json",
        "responseJsonSchema": RESPUESTA_SCHEMA,
        "stopSequences": [],
    },
    "tools": [
        {
            "functionDeclarations": [
                {
                    "name": TOOL_CONSULTAR_EXPEDIENTE["name"],
                    "description": TOOL_CONSULTAR_EXPEDIENTE["description"],
                    "parameters": TOOL_CONSULTAR_EXPEDIENTE["parameters"],
                }
            ]
        }
    ],
    "safetySettings": [],
}

respuesta_simulada = {
    "categoria": "matricula",
    "prioridad": "alta",
    "siguiente_paso": "Consultar expediente y comprobar conciliación del pago.",
    "confianza": 0.82,
    "evidencias": [
        {
            "fuente": "normativa_matricula_2026",
            "detalle": "La matrícula queda activa cuando pago y expediente coinciden.",
        }
    ],
    "necesita_tool": True,
}

def validar_schema_minimo(objeto, schema):
    faltan = sorted(set(schema["required"]) - set(objeto))
    sobran = sorted(set(objeto) - set(schema["properties"]))
    return {"faltan": faltan, "sobran": sobran, "valido": not faltan and not sobran}

print("endpoint:", cliente_http["method"], cliente_http["url"])
print("timeout:", cliente_http["timeout_seconds"])
print("reintentos:", cliente_http["retry_policy"]["max_attempts"])
print("openai_params:", sorted(openai_responses_request.keys()))
print("anthropic_params:", sorted(anthropic_messages_request.keys()))
print("gemini_params:", sorted(gemini_generate_content_request.keys()))
print("tool:", openai_responses_request["tools"][0]["name"])
print("schema_required:", RESPUESTA_SCHEMA["required"])
print("validacion:", validar_schema_minimo(deepcopy(respuesta_simulada), RESPUESTA_SCHEMA))

Salida esperada:

endpoint: POST https://api.openai.com/v1/responses
timeout: 12
reintentos: 2
openai_params: ['input', 'instructions', 'max_output_tokens', 'metadata', 'model', 'parallel_tool_calls', 'store', 'stream', 'temperature', 'text', 'tool_choice', 'tools', 'top_p']
anthropic_params: ['max_tokens', 'messages', 'metadata', 'model', 'stop_sequences', 'stream', 'system', 'temperature', 'tool_choice', 'tools', 'top_k', 'top_p']
gemini_params: ['contents', 'generationConfig', 'safetySettings', 'systemInstruction', 'tools']
tool: consultar_expediente
schema_required: ['categoria', 'prioridad', 'siguiente_paso', 'confianza', 'evidencias', 'necesita_tool']
validacion: {'faltan': [], 'sobran': [], 'valido': True}

Ahora quita evidencias de respuesta_simulada y vuelve a ejecutar. La API podría haber devuelto texto convincente, pero tu contrato dirá que falta una pieza obligatoria. Ese es el salto que buscábamos: no solo “recibir JSON”, sino diseñar una llamada con parámetros, operación, tools y validación.

Cómo encaja todo

Este mapa sitúa el capítulo dentro del facsímil. El capítulo anterior decide qué intervención toca; este convierte esa decisión en contrato de API.

graph TD
    subgraph "Capítulo 2: Contratos de API"
        APP["Aplicación"]
        ADAPTADOR["Adaptador de proveedor"]
        SDK["SDK"]
        MSG["Mensajes"]
        MULTI["Contenido multimodal"]
        PARAMS["Parámetros de generación"]
        SCHEMA["Schema"]
        STREAM["Streaming"]
        TOOL["Tool call"]
        VALIDAR["Validación"]
        TRAZA["Traza"]
    end
    subgraph "Viene de capítulos anteriores"
        DIAG["Diagnóstico<br/>de intervención<br/>(F4C1)"]
        LLM["LLM y contexto (F3)"]
        LOGITS["Salida probabilística<br/>(F3C4)"]
    end
    subgraph "Continuidad del facsímil 4"
        TOKENS["Tokens y coste (F4C3)"]
        MODELOS["Model cards (F4C4)"]
        LOCAL["Modelos locales<br/>(F4C5-06)"]
        RAG["RAG y evaluación<br/>(F4C7-10)"]
        MULTIFUT["Multimodalidad<br/>aplicada (F4C11)"]
        SQL["Text-to-SQL (F4C12)"]
    end
    subgraph "Continuidad en agentes"
        ADK["ADK y Agents SDK (F5)"]
        MCPNODE["MCP: tools y recursos (F5)"]
        A2ANODE["A2A: agentes remotos (F5)"]
    end

    DIAG --> APP
    LLM --> MSG
    LOGITS --> VALIDAR
    APP --> ADAPTADOR
    ADAPTADOR --> SDK
    SDK --> MSG
    SDK --> MULTI
    SDK --> PARAMS
    MSG --> SCHEMA
    MSG --> STREAM
    MSG --> TOOL
    MULTI --> SCHEMA
    PARAMS --> STREAM
    SCHEMA --> VALIDAR
    TOOL --> VALIDAR
    STREAM --> TRAZA
    VALIDAR --> TRAZA
    MSG --> TOKENS
    SCHEMA --> MODELOS
    ADAPTADOR --> LOCAL
    MSG --> RAG
    MULTI --> MULTIFUT
    TOOL --> SQL
    TOOL --> MCPNODE
    SDK --> ADK
    ADK --> A2ANODE

    style APP fill:#F5F5F5,stroke:#000000,stroke-width:2
    style ADAPTADOR fill:#F5F5F5,stroke:#000000,stroke-width:2
    style SDK fill:#F5F5F5,stroke:#000000,stroke-width:2
    style MSG fill:#F5F5F5,stroke:#000000,stroke-width:2
    style MULTI fill:#F5F5F5,stroke:#000000,stroke-width:2
    style PARAMS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style SCHEMA fill:#F5F5F5,stroke:#000000,stroke-width:2
    style STREAM fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TOOL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style VALIDAR fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TRAZA fill:#F5F5F5,stroke:#000000,stroke-width:2
    style DIAG stroke-dasharray: 5 5
    style LLM stroke-dasharray: 5 5
    style LOGITS stroke-dasharray: 5 5
    style TOKENS stroke-dasharray: 5 5
    style MODELOS stroke-dasharray: 5 5
    style LOCAL stroke-dasharray: 5 5
    style RAG stroke-dasharray: 5 5
    style MULTIFUT stroke-dasharray: 5 5
    style SQL stroke-dasharray: 5 5
    style ADK stroke-dasharray: 5 5
    style MCPNODE stroke-dasharray: 5 5
    style A2ANODE stroke-dasharray: 5 5

Vocabulario aprendido

Estos términos nos permiten hablar de integración sin mezclarlo todo en “el prompt”.

Término	Definición
API de modelos	Interfaz para enviar entradas a un modelo y recibir salidas bajo un contrato técnico.
Mensaje	Pieza de conversación con rol y contenido.
Rol	Etiqueta que indica qué función cumple un mensaje dentro de la petición.
Streaming	Entrega progresiva de la respuesta por eventos o fragmentos.
Salida estructurada	Respuesta obligada a cumplir un schema.
Schema	Contrato que define campos, tipos y restricciones de una salida.
Tool call	Petición del modelo para que el sistema ejecute una función externa.
Validador	Código que comprueba si una salida cumple el contrato esperado.
Contenido multimodal	Entrada formada por texto, imágenes, documentos, audio o vídeo según lo permita el modelo.
Adaptador de proveedor	Capa que traduce el contrato propio de la aplicación al formato de una API concreta.
Tool choice	Opción que limita o fuerza qué herramienta puede pedir el modelo durante una llamada.
Idempotencia	Propiedad de repetir una operación sin duplicar efectos cuando hay reintentos.
SDK	Biblioteca cliente que envuelve una API desde un lenguaje concreto.
ADK	Framework para construir agentes con tools, sesiones, memoria, workflows y observabilidad.
MCP	Protocolo para conectar aplicaciones de IA con herramientas, recursos y contexto externos.
A2A	Protocolo para que agentes independientes se descubran, se envíen mensajes y coordinen tareas.
Agent Card	Documento de metadatos que publica identidad, endpoint, capacidades y requisitos de acceso de un agente.
Traza	Registro mínimo de lo enviado, recibido y validado para poder depurar.

Antes de pasar página

En resumen

Una buena integración trata la API como contrato. El modelo produce una salida; tu aplicación decide cómo construir la petición, validar la respuesta y registrar lo necesario.

Idea fuerza	Detalle
La API no es una caja de texto.	Es una frontera entre software probabilístico y software verificable.
Los proveedores cambian de dialecto, no de problema.	OpenAI, Claude y Gemini piden piezas parecidas con nombres y límites distintos.
Los mensajes separan responsabilidades.	Instrucciones, usuario, contexto y tools no deberían vivir en una sola cadena.
La multimodalidad exige trazabilidad.	Si entran documentos o imágenes, guarda fuente, versión, página y criterio de validación.
El schema convierte texto en dato.	Pero aún necesitas validar si el contenido tiene sentido.
Streaming mejora la experiencia percibida.	También obliga a manejar estados parciales y cancelación.
Una tool call no es ejecución automática.	La aplicación valida argumentos y decide qué hacer.
El adaptador protege tu producto.	Tu dominio debería hablar su propio contrato y traducirlo al proveedor.
SDK y ADK no son lo mismo.	El SDK llama APIs; ADK o Agents SDK orquestan agentes, tools, sesiones y workflows.
MCP y A2A resuelven fronteras distintas.	MCP conecta herramientas y recursos; A2A conecta agentes completos mediante tareas y artefactos.
Sin trazas no hay depuración seria.	Guardar contrato, versión y resultado ayuda a reproducir problemas.

Para saber más

Anthropic. (2026). Messages API. https://platform.claude.com/docs/en/api/messages

Anthropic. (2026). PDF support. https://platform.claude.com/docs/en/build-with-claude/pdf-support

Anthropic. (2026). Streaming messages. https://platform.claude.com/docs/en/build-with-claude/streaming

Anthropic. (2026). Structured outputs. https://platform.claude.com/docs/en/build-with-claude/structured-outputs

Anthropic. (2026). Vision. https://platform.claude.com/docs/en/build-with-claude/vision

A2A Protocol. (2026). Agent2Agent (A2A) Protocol. https://a2a-protocol.org/latest/

A2A Protocol. (2026). Overview specification. https://a2a-protocol.org/latest/specification/

Google. (2026). ADK with Agent2Agent (A2A) Protocol. https://adk.dev/a2a/

Google. (2026). Agent Development Kit. https://adk.dev/

Google. (2026). Document understanding. https://ai.google.dev/gemini-api/docs/document-processing

Google. (2026). Image understanding. https://ai.google.dev/gemini-api/docs/image-understanding

Google. (2026). Model Context Protocol (MCP). https://adk.dev/mcp/

Google. (2026). Structured outputs. https://ai.google.dev/gemini-api/docs/structured-output

Google. (2026). Text generation. https://ai.google.dev/gemini-api/docs/text-generation

JSON Schema. (2020). JSON Schema Validation: A Vocabulary for Structural Validation of JSON. https://json-schema.org/draft/2020-12/json-schema-validation

OpenAI. (2026). Create a model response. https://developers.openai.com/api/docs/api-reference/responses/create

OpenAI. (2026). File inputs. https://developers.openai.com/api/docs/guides/file-inputs

OpenAI. (2026). Function calling. https://developers.openai.com/api/docs/guides/function-calling

OpenAI. (2026). Images and vision. https://developers.openai.com/api/docs/guides/images-vision

OpenAI. (2026). Agents SDK. https://developers.openai.com/api/docs/guides/agents

OpenAI. (2026). SDKs and CLI. https://developers.openai.com/api/docs/libraries

OpenAI. (2026). Streaming API responses. https://developers.openai.com/api/docs/guides/streaming-responses

OpenAI. (2026). Structured model outputs. https://developers.openai.com/api/docs/guides/structured-outputs

OpenAI. (2026). Text generation. https://developers.openai.com/api/docs/guides/text

WHATWG. (2026). Server-sent events. https://html.spec.whatwg.org/multipage/server-sent-events.html

Notas

OpenAI. (2026). Text generation. https://developers.openai.com/api/docs/guides/text. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). Structured model outputs. https://developers.openai.com/api/docs/guides/structured-outputs. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). Function calling. https://developers.openai.com/api/docs/guides/function-calling. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). Messages API. https://platform.claude.com/docs/en/api/messages. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). Streaming messages. https://platform.claude.com/docs/en/build-with-claude/streaming. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). Structured outputs. https://platform.claude.com/docs/en/build-with-claude/structured-outputs. Consultado el 10 de junio de 2026. ↩
Google. (2026). Text generation. https://ai.google.dev/gemini-api/docs/text-generation. Consultado el 10 de junio de 2026. ↩
Google. (2026). Structured outputs. https://ai.google.dev/gemini-api/docs/structured-output. Consultado el 10 de junio de 2026. ↩
Google. (2026). Interactions API overview. https://ai.google.dev/gemini-api/docs/interactions/interactions-overview. Consultado el 10 de junio de 2026. ↩
Google. (2026). Agent Development Kit. https://adk.dev/. Consultado el 10 de junio de 2026. ↩
A2A Protocol. (2026). Agent2Agent Protocol. https://a2a-protocol.org/latest/. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). Create a model response. https://developers.openai.com/api/docs/api-reference/responses/create. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). Messages API. https://platform.claude.com/docs/en/api/messages. Consultado el 10 de junio de 2026. ↩
Google. (2026). Text generation. https://ai.google.dev/gemini-api/docs/text-generation. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). File inputs. https://developers.openai.com/api/docs/guides/file-inputs. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). Images and vision. https://developers.openai.com/api/docs/guides/images-vision. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). Vision. https://platform.claude.com/docs/en/build-with-claude/vision. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). PDF support. https://platform.claude.com/docs/en/build-with-claude/pdf-support. Consultado el 10 de junio de 2026. ↩
Google. (2026). Image understanding. https://ai.google.dev/gemini-api/docs/image-understanding. Consultado el 10 de junio de 2026. ↩
Google. (2026). Document understanding. https://ai.google.dev/gemini-api/docs/document-processing. Consultado el 10 de junio de 2026. ↩
JSON Schema. (2020). JSON Schema Validation: A Vocabulary for Structural Validation of JSON. https://json-schema.org/draft/2020-12/json-schema-validation. ↩
WHATWG. (2026). Server-sent events. https://html.spec.whatwg.org/multipage/server-sent-events.html. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). Streaming API responses. https://developers.openai.com/api/docs/guides/streaming-responses. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). Streaming messages. https://platform.claude.com/docs/en/build-with-claude/streaming. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). SDKs and CLI. https://developers.openai.com/api/docs/libraries. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). Agents SDK. https://developers.openai.com/api/docs/guides/agents. Consultado el 10 de junio de 2026. ↩
Google. (2026). Agent Development Kit. https://adk.dev/. Consultado el 10 de junio de 2026. ↩
Google. (2026). ADK with Agent2Agent (A2A) Protocol. https://adk.dev/a2a/. Consultado el 10 de junio de 2026. ↩
Google. (2026). Model Context Protocol (MCP). https://adk.dev/mcp/. Consultado el 10 de junio de 2026. ↩
A2A Protocol. (2026). Agent2Agent (A2A) Protocol. https://a2a-protocol.org/latest/. Consultado el 10 de junio de 2026. ↩
A2A Protocol. (2026). Overview specification. https://a2a-protocol.org/latest/specification/. Consultado el 10 de junio de 2026. ↩

Capítulo 03

Facsímil 4 · La caja de herramientas

Capítulo 03: Tokens, coste, contexto y caché

El presupuesto invisible de cada pregunta

Cuando una persona escribe “resúmeme este PDF” parece que está enviando una frase. En realidad puede estar enviando miles de tokens: instrucciones, historial, documento, herramientas disponibles, schema de salida y la propia pregunta. La factura no mira si la frase sonaba sencilla. Mira lo que entró, lo que salió, lo que se pudo cachear, el modelo elegido y cómo se sirvió la petición.

Este capítulo continúa el capítulo 02. Allí aprendimos a construir una llamada de API completa. Aquí hacemos la cuenta que decide si esa llamada cabe, cuánto cuesta, cuánto tarda y qué podemos reutilizar.

La idea central es esta: un sistema con IA no solo se diseña con prompts; se diseña con presupuestos de tokens.

Estado del arte con fecha de corte

Fecha de corte: 25 de mayo de 2026.
Fuentes consultadas ese día: documentación oficial de OpenAI sobre conteo de tokens, prompt caching, coste, Batch API, latencia y precios; documentación de Anthropic sobre token counting, prompt caching y ventanas de contexto; documentación de Google sobre token counting, long context, context caching y precios de Gemini API; el repositorio oficial de tiktoken; y artículos primarios sobre MoE, Switch Transformer, GShard y Mixtral.

Lo estable es el mecanismo: los modelos procesan tokens, la ventana de contexto es finita, la entrada y la salida se cobran de forma distinta, el streaming mejora la espera percibida, el batch puede abaratar trabajos diferidos y la caché solo ayuda cuando repites prefijos de forma reconocible.

Lo cambiante son los precios, modelos, nombres de campos, ventanas máximas, umbrales de cache, descuentos y límites. Para que las notas no aparezcan como una ristra de números pegados, las dejamos ordenadas por tema y proveedor:

Proveedor	Nota que conviene revisar	Por qué importa
OpenAI	Conteo de tokens.¹	Estimar entrada, salida y compatibilidad de tokenizador.
OpenAI	Prompt caching.²	Diseñar prefijos repetibles y medir cache hit.
OpenAI	Optimización de coste.³	Separar coste de entrada, salida, cache y modelo.
OpenAI	Batch API.⁴	Pasar trabajos no interactivos a procesamiento diferido.
OpenAI	Optimización de latencia.⁵	Distinguir prefill, decode, streaming y tiempo percibido.
Anthropic	Token counting.⁶	Comparar conteos antes de migrar prompts.
Anthropic	Prompt caching.⁷	Pensar qué prefijos se reutilizan y durante cuánto tiempo.
Anthropic	Context windows.⁸	Saber qué entra, qué sale y qué se queda fuera.
Google	Conteo de tokens.⁹	Medir prompts, archivos y respuestas antes de desplegar.
Google	Long context.¹⁰	Evaluar cuándo una ventana larga ayuda y cuándo añade ruido.
Google	Context caching.¹¹	Revisar TTL, prefijos y reutilización de contexto.
Google	Pricing de Gemini API.¹²	Presupuestar con tarifas vigentes.
MoE	Capa sparsely-gated MoE.¹³	Entender expertos, router y cómputo condicional.
MoE	Switch Transformer.¹⁴	Ver por qué top-1 simplifica routing, comunicación y entrenamiento.
MoE	GShard.¹⁵	Conectar MoE con sharding y entrenamiento distribuido.
MoE	Mixtral of Experts.¹⁶	Ver un LLM sparse MoE moderno con routing top-2 por token.

Qué no es un token

Un token no es una palabra. “Universidad” puede ocupar un token o varios, según el tokenizer. Un emoji puede ocupar más de uno. Un espacio, una coma o una tilde pueden cambiar la cuenta. Por eso contar palabras en un documento no sirve para estimar coste con precisión.

Tampoco es una unidad humana de significado. Para el modelo, un token es una pieza de codificación aprendida para representar texto de forma eficiente. A veces coincide con algo que reconocemos; a veces es una sílaba, una terminación, un símbolo o un fragmento raro.

Y no es igual en todos los modelos. Cada familia puede usar tokenizer, reglas multimodales y contabilidad distinta. OpenAI mantiene tiktoken como tokenizador rápido para sus modelos, pero eso no implica que el mismo conteo valga para Claude, Gemini o un modelo local.¹⁷

Cómo se construye un tokenizador

Un tokenizador, o constructor de tokens, no es una lista escrita a mano con todas las palabras posibles. Es una pieza entrenada sobre un corpus: mira mucho texto, aprende piezas frecuentes y produce una tabla estable de texto -> id. El modelo se entrena después con esos ids. Por eso no puedes cambiar el tokenizador de un modelo ya entrenado como quien cambia una fuente tipográfica: cambiarías el idioma interno con el que ese modelo aprendió.

La familia más intuitiva para empezar es BPE, Byte Pair Encoding. En NLP moderno se popularizó para manejar palabras raras y vocabularios abiertos en traducción neuronal.¹⁸ La idea es sencilla: empezar con unidades pequeñas y fusionar pares frecuentes hasta construir piezas útiles.

El paso a paso mental es este:

Paso	Qué haces	Decisión de ingeniería
1	Reúnes un corpus representativo.	Si entrenas con textos legales, contarán mucho las piezas legales; si entrenas con código, contarán símbolos y nombres técnicos.
2	Normalizas lo mínimo necesario.	Minúsculas, Unicode, espacios y acentos cambian el vocabulario. No lo improvises.
3	Partes el texto en unidades pequeñas.	Caracteres, bytes o piezas iniciales. Los tokenizadores modernos suelen preferir variantes robustas a bytes.
4	Cuentas pares vecinos.	`("c", "a")`, `("a", "s")`, `("s", "a")`, etc.
5	Fusionas el par más frecuente.	Ese par pasa a ser una pieza nueva del vocabulario.
6	Repites hasta llegar al tamaño de vocabulario.	8 000, 32 000, 100 000 o lo que pida el modelo y el dominio.
7	Guardas vocabulario y reglas de merge.	Es un artefacto versionado, igual que pesos, configuración y model card.
8	Codificas texto nuevo aplicando esas reglas.	El resultado son ids numéricos que entran al modelo.

La regla de fusión se puede escribir así:

(u^\*,v^\*)=\arg\max_{(u,v)} \operatorname{freq}(u,v)

Símbolo	Significado	Ejemplo
$u, v$	Dos piezas vecinas candidatas.	`c` y `a`.
$\operatorname{freq}(u,v)$	Frecuencia del par en el corpus.	`ca` aparece 28 000 veces.
$(u^\,v^\)$	Par ganador que se fusiona.	`c` + `a` pasa a ser `ca`.
$\arg\max$	Elige el candidato con mayor frecuencia.	No devuelve la frecuencia, devuelve el par.

SentencePiece añade una idea muy útil para ingeniería multilingüe: puede entrenarse directamente sobre texto crudo y tratar los espacios como parte de la segmentación, en lugar de depender de un preprocesado específico de cada idioma.¹⁹ Esto importa porque “separar por espacios” funciona regular en inglés y español, pero se vuelve frágil con japonés, chino, emojis, código, nombres propios y formatos raros.

Detalles que un ingeniero debe tener muy presentes:

Decisión	Qué rompe si se decide mal
Normalización Unicode	Dos textos visualmente iguales pueden tokenizar distinto.
Tamaño de vocabulario	Vocabulario pequeño alarga secuencias; vocabulario enorme aumenta tabla y puede memorizar rarezas inútiles.
Tratamiento de espacios	Cambia la cuenta de tokens y la reversibilidad del decode.
Tokens especiales	`system`, `tool`, separadores, imágenes o fin de texto deben tener ids reservados y documentados.
Dominio del corpus	Un tokenizador entrenado en conversación puede ser torpe con código o biomedicina.
Versionado	Modelo, tokenizer y plantilla de mensajes forman un paquete; si uno cambia, se revalida todo.

Qué sí es: la unidad que paga, cabe y tarda

Un token es la unidad que conecta tres preguntas de ingeniería:

Pregunta	Qué mide	Por qué importa
¿Cabe?	Tokens de entrada más salida esperada frente a ventana de contexto.	Si no cabe, tienes que resumir, trocear, recuperar o rechazar.
¿Cuesta?	Tokens de entrada, salida, cache, batch y modelo.	Dos prompts parecidos pueden tener facturas muy distintas.
¿Tarda?	Tokens procesados en prefill y generados en decode.	Una entrada enorme tarda antes de empezar; una salida larga tarda mientras se genera.

La llamada que hicimos en el capítulo anterior no estaba completa hasta mirar tokens. input, tools, schema, documentos e imágenes ocupan presupuesto. La respuesta también. Si pides “razona mucho y dame una respuesta larga”, no solo estás pidiendo calidad: estás comprando tokens de salida y tiempo de generación.

La cuenta mínima: entrada, salida y ventana

La primera fórmula es sencilla:

T_{\text{total}}=T_{\text{entrada}}+T_{\text{salida}}

Símbolo	Significado	Ejemplo
$T_{\text{entrada}}$	Tokens enviados al modelo.	Instrucciones, historial, PDF, schema y pregunta suman 18 000 tokens.
$T_{\text{salida}}$	Tokens generados por el modelo.	El resumen y el JSON final ocupan 900 tokens.
$T_{\text{total}}$	Tokens de la llamada completa.	$18\,000+900=18\,900$ .

Pero que el total exista no significa que quepa. Cada modelo tiene una ventana de contexto:

T_{\text{entrada}}+T_{\text{salida\_max}} \leq W

Símbolo	Significado	Ejemplo
$T_{\text{salida\_max}}$	Máximo de salida reservado.	Reservas 1 500 tokens para contestar.
$W$	Ventana de contexto del modelo elegido.	Un modelo con 32 000 tokens de ventana.
$\leq$	Restricción de cabida.	$18\,000+1\,500 \leq 32\,000$ .

El detalle importante: reservar salida también consume ventana. Si llenas toda la ventana con documentos, quizá el modelo no tiene espacio para responder. Por eso el presupuesto de contexto debe decidir cuánto se queda cada pieza.

Pieza	Qué suele ocupar	Decisión práctica
Instrucciones	Poco, pero se repite siempre.	Mantenerlas cortas, estables y cacheables.
Historial	Crece sin pedir permiso.	Resumir, compactar o guardar solo turnos relevantes.
Documentos	Puede dominar toda la llamada.	Usar RAG, citas, páginas o troceo.
Tools y schemas	No parecen contenido, pero cuentan.	Versionar y no inflar campos innecesarios.
Salida	Se paga y tarda.	Limitar `max_output_tokens` con criterio.

Coste: la factura no mira la dificultad, mira el uso

Los proveedores suelen separar precio de entrada y precio de salida. Algunos añaden categorías para cache writes, cache reads, batch, prioridad, procesamiento flexible, audio, imagen o razonamiento. Por eso la fórmula útil no es “precio por pregunta”, sino “precio por componentes”.

Ejemplo de fórmula. Una forma general de estimarlo es:

C=\frac{T_iP_i+T_oP_o+T_{cr}P_{cr}+T_{cw}P_{cw}}{1\,000\,000}

Símbolo	Significado	Ejemplo
$C$	Coste estimado de la llamada.	0,0068 euros o dólares, según tarifa.
$T_i$	Tokens de entrada frescos.	8 000 tokens no cacheados.
$P_i$	Precio por millón de tokens de entrada.	2,00 por millón en un ejemplo inventado.
$T_o$	Tokens de salida.	700 tokens generados.
$P_o$	Precio por millón de tokens de salida.	8,00 por millón en el ejemplo.
$T_{cr}$	Tokens leídos desde caché.	12 000 tokens reutilizados.
$P_{cr}$	Precio por millón de tokens cacheados leídos.	Menor que $P_i$ si el proveedor descuenta cache read.
$T_{cw}$	Tokens escritos en caché.	12 000 tokens de prefijo guardado.
$P_{cw}$	Precio por millón de cache write.	Puede ser igual, mayor o no aplicar según proveedor.

No uses los números del ejemplo para presupuestar un producto real. Usa la fórmula y consulta la página oficial de precios el día que diseñes el sistema.²⁰ Lo profesional no es saberse una tarifa de memoria; es guardar en configuración qué modelo, proveedor, fecha y precio estás usando para cada estimación.

Contexto: meter más no siempre ayuda

La ventana larga es una bendición cuando necesitas leer un expediente grande, comparar documentos o mantener una conversación compleja. Pero más contexto también compra coste, latencia y ruido. Un documento irrelevante dentro del prompt no es gratis: ocupa presupuesto y puede distraer.

Ejemplo de fórmula. El presupuesto de contexto puede pensarse así:

W = B_{\text{instrucciones}} + B_{\text{historial}} + B_{\text{documentos}} + B_{\text{tools}} + B_{\text{salida}}

Símbolo	Significado	Ejemplo
$B_{\text{instrucciones}}$	Presupuesto reservado a reglas estables.	600 tokens.
$B_{\text{historial}}$	Presupuesto de conversación previa.	2 000 tokens.
$B_{\text{documentos}}$	Presupuesto para evidencia externa.	20 000 tokens.
$B_{\text{tools}}$	Presupuesto para definiciones de herramientas y schemas.	1 400 tokens.
$B_{\text{salida}}$	Presupuesto reservado para responder.	1 500 tokens.

El error típico es decidir el contexto al final. En realidad conviene decidirlo antes de llamar a la API: “para esta tarea, el modelo puede ver tres fragmentos, no veinte; debe citar página; y si no cabe, se resume o se pregunta de nuevo”.

Contexto, memoria y KV cache no son lo mismo

En producto solemos llamar “contexto” a todo lo que acompaña a la pregunta: instrucciones del sistema, mensajes anteriores, documentos recuperados, resultados de herramientas, imágenes, tablas, preferencias del usuario y formato esperado. Para el modelo, eso no llega como recuerdos. Llega como una secuencia de ids de token en una llamada concreta.

El recorrido real es más técnico:

Etapa	Qué ocurre	Qué queda guardado
Texto a tokens	El tokenizador convierte texto y partes estructuradas en ids.	La lista de ids de entrada.
Tokens a vectores	Cada id se convierte en embedding y se combina con información de posición.	Tensores de entrada para el transformer.
Atención	Cada capa calcula consultas, claves y valores: $Q$ , $K$ , $V$ .	Activaciones temporales de la llamada.
Prefill	El servidor procesa todo el prefijo de entrada.	Claves y valores listos para generar.
Decode	El modelo genera un token, lo añade a la secuencia y repite.	La KV cache crece token a token.
Fin de llamada	Se devuelve texto, JSON o eventos de streaming.	Nada queda en los pesos del modelo por defecto.

La atención original del transformer compara cada consulta con claves y usa valores para mezclar información relevante.²¹ En inferencia autoregresiva, no queremos recalcular las claves y valores de todos los tokens anteriores cada vez que generamos uno nuevo. Por eso los servidores guardan una KV cache temporal.

La fórmula conceptual de atención es:

\operatorname{Attention}(Q,K,V)=\operatorname{softmax}\left(\frac{QK^\top}{\sqrt{d_k}}\right)V

Símbolo	Qué significa	Intuición
$Q$	Queries o consultas.	Qué está buscando el token actual.
$K$	Keys o claves.	Qué ofrece cada token anterior para ser encontrado.
$V$	Values o valores.	Información que se mezcla si la atención la considera útil.
$d_k$	Dimensión de las claves.	Factor de escala para estabilizar el producto.

La KV cache guarda $K$ y $V$ ya calculados. No es memoria del usuario. Es memoria de cálculo durante la inferencia. Si una conversación tiene 20 000 tokens de entrada y genera 800 tokens de salida, el servidor va manteniendo claves y valores para evitar rehacer todo el prefijo en cada paso.

Ejemplo de fórmula. Una aproximación de memoria para KV cache es:

M_{\text{KV}}\approx 2 \cdot L \cdot B \cdot S \cdot H_{\text{kv}} \cdot d_{\text{head}} \cdot \text{bytes}

Símbolo	Significado	Qué mueve en la práctica
$2$	Guardamos claves y valores.	K y V, no solo una matriz.
$L$	Número de capas.	Modelos más profundos consumen más cache.
$B$	Batch o secuencias simultáneas.	Más usuarios concurrentes, más memoria.
$S$	Longitud de secuencia.	Contexto largo y salida larga hacen crecer la cache.
$H_{\text{kv}}$	Cabezas KV.	MQA/GQA reducen cabezas KV frente a atención multi-head clásica.²²
$d_{\text{head}}$	Dimensión por cabeza.	Depende de arquitectura.
$\text{bytes}$	Precisión usada.	FP16, BF16, INT8 o variantes cuantizadas cambian memoria.

Esta fórmula explica por qué el contexto largo no es solo “más texto”. Es memoria de GPU, planificación de batch, colas y throughput. Sistemas como vLLM investigan precisamente cómo gestionar esa memoria de KV cache con menos desperdicio mediante PagedAttention.²³

Ahora sí podemos separar conceptos que a menudo se mezclan:

Concepto	Vive dónde	Dura cuánto	Lo controla quién	Para qué sirve
Contexto de llamada	En el payload enviado al modelo.	Una petición.	Tu aplicación.	Dar instrucciones, evidencia y formato de salida.
Historial	En tu base de datos o en el cliente.	Hasta que lo borres o resumas.	Tu producto.	Reconstruir conversación útil.
Memoria de producto	En una base de datos, perfil, resumen o vector store.	Persistente o con política de expiración.	Tu producto y sus permisos.	Recordar preferencias o hechos útiles entre sesiones.
KV cache	En memoria del servidor de inferencia.	Durante una secuencia o sesión gestionada por el runtime.	El proveedor o tu servidor local.	Acelerar decode y evitar recomputar prefijos.
Prompt cache	En la infraestructura del proveedor o runtime.	Según reglas, TTL y coincidencia de prefijo.	Proveedor más diseño de prompt.	Reutilizar trabajo de prefijos repetidos entre llamadas.

La frase correcta sería: “nuestro producto recuerda algo porque lo guardamos y lo volvemos a meter en el contexto”. El modelo base no actualiza sus pesos por leer un mensaje de un usuario. Para que “recuerde” en otra llamada, alguien tiene que almacenar, recuperar, filtrar y reinyectar esa información.

Un MoE capa a capa dentro de este proceso

Ahora metamos una arquitectura MoE en la misma película. No cambia la idea básica de este capítulo: entran tokens, se procesan dentro de una ventana, se genera salida y se mide coste/latencia. Lo que cambia está dentro de algunas capas del Transformer: en lugar de que todos los tokens pasen por el mismo MLP denso, un router aprende a mandar cada token a uno o varios expertos.

En un bloque Transformer denso simplificado suele pasar esto:

u_t^{(\ell)}=h_t^{(\ell)}+\operatorname{Attention}^{(\ell)}(\operatorname{LN}(h_t^{(\ell)}))

h_t^{(\ell+1)}=u_t^{(\ell)}+\operatorname{MLP}^{(\ell)}(\operatorname{LN}(u_t^{(\ell)}))

Símbolo	Significado	Ejemplo
$h_t^{(\ell)}$	Estado del token $t$ al entrar en la capa $\ell$ .	Vector del token “cache” en la capa 12.
$\operatorname{Attention}$	Parte que mezcla información del contexto mediante $Q$ , $K$ y $V$ .	Lee tokens anteriores y usa la KV cache.
$\operatorname{MLP}$	Red feed-forward densa del bloque.	La misma red para todos los tokens de esa capa.
$\operatorname{LN}$	LayerNorm.	Normaliza antes de atención o MLP.
$u_t^{(\ell)}$	Estado tras atención y residual.	El token ya trae información del contexto.

En un MoE, la parte que se suele sustituir es el MLP. La atención sigue mezclando contexto; después entra el router:

s_t^{(\ell)}=W_r^{(\ell)}\operatorname{LN}(u_t^{(\ell)})

p_t^{(\ell)}=\operatorname{softmax}(s_t^{(\ell)})

C_t^{(\ell)}=\operatorname{TopK}(p_t^{(\ell)}, k)

\operatorname{MoE}^{(\ell)}(u_t)=\sum_{i \in C_t^{(\ell)}}\alpha_i E_i^{(\ell)}(\operatorname{LN}(u_t^{(\ell)}))

h_t^{(\ell+1)}=u_t^{(\ell)}+\operatorname{MoE}^{(\ell)}(u_t)

Símbolo	Significado	Ejemplo
$W_r^{(\ell)}$	Matriz aprendida del router en la capa $\ell$ .	Produce una puntuación por experto.
$s_t^{(\ell)}$	Logits del router para el token $t$ .	Ocho puntuaciones si hay ocho expertos.
$p_t^{(\ell)}$	Probabilidades de routing tras softmax.	`[0.02, 0.61, 0.04, 0.21, ...]`.
$k$	Número de expertos activados por token.	Switch usa top-1; Mixtral usa top-2.
$C_t^{(\ell)}$	Conjunto de expertos elegidos para ese token y esa capa.	Expertos 2 y 4 en la capa 18.
$E_i^{(\ell)}$	Experto $i$ , normalmente una red feed-forward.	Un MLP independiente dentro de la capa.
$\alpha_i$	Peso normalizado con el que se combina cada experto seleccionado.	Si top-2, cada experto aporta una parte.

La película layer a layer queda así:

Paso	Qué le pasa al token	Qué importa para coste, contexto y caché
1	El texto ya fue tokenizado y convertido en embeddings.	El MoE no cambia el conteo de tokens de entrada.
2	El token entra en la capa $\ell$ con un vector $h_t^{(\ell)}$ .	La secuencia sigue teniendo longitud $S$ .
3	La atención calcula $Q$ , $K$ , $V$ y mezcla contexto.	La KV cache sigue siendo de atención, no de “memoria del experto”.
4	El resultado pasa por residual y normalización.	El token ya trae información de tokens anteriores.
5	El router calcula puntuaciones para expertos.	Aparece cómputo extra pequeño: routing.
6	Se eligen $k$ expertos.	Cambian los parámetros activos por token.
7	El runtime agrupa tokens por experto.	En GPU distribuida puede haber comunicación entre dispositivos.
8	Cada experto procesa los tokens que le tocaron.	No se ejecutan todos los expertos para cada token.
9	Se combinan las salidas de los expertos elegidos.	En top-2 hay mezcla; en top-1 se simplifica.
10	Se suma residual y el token pasa a la siguiente capa.	En la capa siguiente puede elegir expertos distintos.

Visualmente, una capa MoE se entiende mejor si la dibujamos como una cinta de procesamiento: el token pasa por atención, el router decide, solo algunos expertos trabajan y sus salidas se recombinan.

Esto explica una frase que en fichas técnicas suele confundirse: parámetros totales no son parámetros activos. Un MoE puede tener muchos parámetros almacenados porque tiene muchos expertos, pero cada token usa solo una parte. Mixtral, citado en el bloque de estado del arte, describe capas con ocho bloques feed-forward y selección de dos expertos por token y por capa; el propio artículo distingue entre parámetros accesibles y parámetros activos durante inferencia.

En serving, la parte delicada no es solo matemática. Es logística:

Problema operativo	Qué ocurre
Balanceo de carga	Si demasiados tokens van al mismo experto, ese experto se convierte en cuello de botella.
Capacidad por experto	Los runtimes suelen limitar cuántos tokens procesa cada experto por lote.
Comunicación	Si los expertos viven en dispositivos distintos, los tokens o activaciones tienen que moverse.
Batch irregular	Dos peticiones con los mismos tokens de entrada no tienen por qué activar exactamente la misma distribución de expertos.
Métrica de coste	El usuario paga tokens, pero el proveedor opera con parámetros activos, routing, memoria y comunicación.

Por eso MoE es muy relevante para este capítulo: te obliga a leer “coste por token” con más finura. Desde fuera sigues viendo tokens de entrada, tokens de salida, ventana y precio. Por dentro, cada token atraviesa todas las capas, pero en las capas MoE solo activa una ruta dispersa. El contexto no se “guarda en los expertos”; la memoria temporal de contexto sigue estando en la atención y su KV cache. Los expertos transforman representaciones, no almacenan recuerdos de usuario.

Caché: repetir bien para pagar y esperar menos

Prompt caching aprovecha un hecho simple: muchas llamadas repiten prefijos. Las instrucciones del sistema, las herramientas, el schema, una normativa larga o un conjunto de ejemplos pueden ser iguales durante muchas peticiones. Si el proveedor reconoce ese prefijo, puede reutilizar trabajo ya hecho.

En las guías citadas al inicio, OpenAI describe caché para mensajes, imágenes, tool use y structured outputs, y recomienda colocar el contenido estático o repetido al principio y lo dinámico al final. Anthropic explica breakpoints explícitos y automáticos, con especial atención al orden tools, system y messages en el prefijo cacheable. Gemini distingue caché implícita y caché explícita con TTL configurable.

Hay dos cachés que se confunden mucho:

Caché	Qué reutiliza	Cuándo la notas	Qué mirar
KV cache	$K$ y $V$ ya calculados dentro de una secuencia.	En decode, porque cada token nuevo no recalcula todo el prefijo.	Memoria, longitud de secuencia, batch, throughput.
Prompt cache o context cache	Un prefijo repetido entre llamadas.	En coste, latencia o campos de usage del proveedor.	Orden estable del prompt, TTL, cache hit y contenido dinámico al final.

El diseño de prompt cache es casi diseño de APIs: si serializas un JSON con claves en orden aleatorio, metes timestamps arriba o cambias ejemplos sin necesidad, rompes coincidencias. Si colocas primero instrucciones, tools, schema y documentos estables, y dejas al final la pregunta concreta del usuario, aumentas la probabilidad de reutilización.

La métrica que queremos mirar es:

H=\frac{T_{\text{cache\_hit}}}{T_{\text{entrada}}}

Símbolo	Significado	Ejemplo
$H$	Proporción de entrada servida desde caché.	$0{,}72$ , es decir, 72 %.
$T_{\text{cache\_hit}}$	Tokens de entrada que fueron cache hit.	14 400 tokens.
$T_{\text{entrada}}$	Tokens de entrada totales.	20 000 tokens.

Para entenderlo: si cada petición incluye una normativa de 15 000 tokens y solo cambia la pregunta final, la caché puede tener sentido. Si cada petición mete documentos distintos, timestamps dentro del prefijo y orden aleatorio de fragmentos, la caché probablemente no ayudará.

Latencia: prefill, decode y espera percibida

La latencia no es una sola cosa. Hay tiempo de red, cola, prefill, generación y renderizado. En modelos de lenguaje, una intuición útil es separar entrada y salida:

L \approx L_0 + \alpha T_{\text{entrada\_fresca}} + \beta T_{\text{salida}}

Símbolo	Significado	Ejemplo
$L$	Latencia total aproximada.	4,8 segundos.
$L_0$	Coste fijo de red, cola y preparación.	350 ms.
$\alpha$	Coste medio por token de entrada fresca.	Depende de modelo y hardware.
$T_{\text{entrada\_fresca}}$	Entrada no cubierta por caché.	3 000 tokens.
$\beta$	Coste medio por token generado.	Depende de decode.
$T_{\text{salida}}$	Tokens generados.	900 tokens.

El streaming no reduce necesariamente el tiempo total, pero reduce el tiempo hasta ver el primer fragmento. Batch puede reducir coste o mejorar operación cuando no necesitas respuesta inmediata. La caché puede reducir prefill si el prefijo se reutiliza. Elegir un modelo menor puede reducir coste y latencia, pero quizá empeora calidad. Todo vuelve al triángulo: calidad, coste y tiempo.

Para entenderlo antes de tocar código

Pensemos en cuatro casos cercanos:

Caso	Qué pesa	Qué haría
Tutor que corrige respuestas cortas	Salida estructurada y muchas llamadas.	Modelo menor, schema corto, batch si no es interactivo.
Asistente de normativa universitaria	Documento largo repetido.	Prefijo estable, cache, RAG si la normativa es grande.
Chat de soporte con historial largo	Historial que crece cada turno.	Compactar, resumir y guardar solo lo útil.
Analizador de facturas con imágenes	Imagen, OCR, schema y salida JSON.	Medir tokens/latencia multimodal y limitar campos.
Copiloto interno con preferencias	Memoria de producto y contexto recuperado.	Guardar preferencias fuera del modelo y reinyectar solo las relevantes.
Servicio con muchas sesiones simultáneas	KV cache, batch y cola.	Vigilar memoria de inferencia, longitud media y tokens por segundo.
Modelo MoE en producción	Routing, expertos y parámetros activos.	Medir latencia real; no comparar solo parámetros totales.

La pregunta útil no es “¿cuántos tokens acepta el modelo más grande?”. La pregunta útil es “¿cuántos tokens necesita esta tarea para dar una respuesta fiable sin pagar ruido?”.

Mapa visual de presupuesto de tokens

En el día a día

En un proyecto real, este capítulo aparece cuando alguien pregunta: “¿por qué esto cuesta tanto?” o “¿por qué tarda tanto?”. Muchas veces la respuesta no está en cambiar de modelo, sino en mirar el payload completo.

Si cada llamada manda el mismo documento largo, quizá toca cache. Si cada llamada manda veinte fragmentos RAG y solo dos eran relevantes, toca mejorar retrieval. Si el usuario necesita respuesta inmediata, quizá no puedes batchar. Si el proceso es nocturno, batch puede ser perfecto. Si la salida siempre se alarga, limita tokens de salida y cambia el contrato.

Si eliges un modelo MoE, añade una pregunta más: ¿cuántos parámetros son totales y cuántos activos por token? No necesitas ver el router interno para operar una API comercial, pero sí necesitas entender que “47B parámetros” y “13B activos” no significan lo mismo, y que la latencia real dependerá también de routing, expertos, batch y hardware.

Una integración madura registra al menos: tokens de entrada, tokens de salida, tokens cacheados si el proveedor los devuelve, modelo, arquitectura si se conoce, latencia, coste estimado, schema y motivo de selección del modelo. Sin esos datos, optimizar es opinar con cara seria.

Por qué debería importarte

Porque los tokens convierten decisiones aparentemente literarias en decisiones de producto. “Añadamos más contexto” puede duplicar coste. “Respondamos con más detalle” puede multiplicar salida. “Metamos todos los documentos” puede romper ventana o empeorar la respuesta. “Usemos el modelo grande siempre” puede ser innecesario.

MoE añade otra trampa sana: un modelo puede ser enorme en parámetros totales y, aun así, activar solo una fracción por token. Eso puede mejorar capacidad sin multiplicar igual el cómputo, pero también complica serving, balanceo y lectura de fichas técnicas.

También importa para enseñar y aprender. Cuando entiendes tokens, dejas de pensar en la IA como una caja opaca y empiezas a verla como un sistema con restricciones medibles.

Dónde volverá a aparecer

Este capítulo será una pieza recurrente del facsímil:

Concepto	Dónde vuelve	Para qué
Tokenizadores	Capítulo 07 del facsímil 3.	Entender por qué decode, throughput y límites dependen de tokens, no de palabras.
KV cache	Capítulo 07 del facsímil 3.	Relacionar contexto largo con memoria de inferencia y serving.
MoE y parámetros activos	Capítulo 05 del facsímil 3.	Leer arquitectura, expertos y routing sin confundirlos con memoria o herramientas.
Model cards	Capítulo 04.	Comparar modelos por ventana, precio, latencia y capacidades.
Modelos locales	Capítulos 05 y 06.	Traducir tokens a VRAM, cuantización y throughput.
Embeddings y RAG	Capítulos 07 a 10.	Decidir chunking, top-k y presupuesto de evidencia.
Multimodalidad aplicada	Capítulo 11.	Entender cómo archivos, imágenes y audio afectan coste y contexto.
Laboratorio mínimo	Capítulo 13.	Registrar trazas, evals, latencia y coste por caso.

Dónde solía tropezar yo

Estos tropiezos son muy comunes cuando se pasa de una demo a una aplicación con usuarios.

Error	Por qué es un error	Antídoto
Contar palabras y no tokens	La factura y la ventana no entienden palabras humanas.	Usar el contador del proveedor o tokenizer compatible.
Pensar que todos los tokenizadores son equivalentes	Un mismo texto puede producir ids y longitudes distintas según modelo.	Versionar tokenizer, plantilla de mensajes y modelo como un conjunto.
Llenar la ventana hasta el borde	Si no reservas salida, el modelo no tiene espacio para contestar.	Separar presupuesto de entrada y salida máxima.
Meter contexto por tranquilidad	El contexto irrelevante cuesta, tarda y puede confundir.	Recuperar menos, citar mejor y medir calidad.
Confundir contexto con memoria	El modelo no recuerda por defecto lo que no le vuelves a enviar.	Guardar memoria en producto y reinyectarla con permisos y criterio.
Leer parámetros totales como coste por token	En MoE, muchos parámetros existen, pero solo algunos expertos se activan por token.	Mirar parámetros activos, routing y latencia medida.
Pensar que el experto MoE guarda conocimiento humano etiquetado	Un experto es una subred aprendida, no “el experto de matemáticas” de forma garantizada.	Hablar de rutas internas y medir comportamiento, no inventar etiquetas humanas.
Esperar demasiado de la caché	La caché solo ayuda si repites prefijos estables.	Ordenar prompt: estable primero, dinámico al final.
Mezclar prompt cache y KV cache	Una ahorra trabajo entre llamadas; la otra acelera el decode dentro de una secuencia.	Medir ambas con métricas distintas.
No registrar usage	Sin tokens reales no puedes explicar coste ni latencia.	Guardar usage, cache hit, modelo y traza por llamada.

Manos a la obra

Vamos a hacer dos prácticas pequeñas. La primera construye un tokenizador BPE mínimo para que se vea el mecanismo. La segunda usa esos tokens como unidad de presupuesto para estimar cabida, coste y caché. No son librerías de producción; son maquetas para entender qué está pasando debajo.

1. Construir un tokenizador mínimo

Este ejemplo aprende ocho fusiones sobre un corpus diminuto. Sustituye los espacios por ▁ para que el espacio sea visible y reversible. En un tokenizador real habría más normalización, más corpus, más pruebas y artefactos versionados.

from collections import Counter

corpus = [
    "la casa es clara",
    "la causa es clara",
    "casa clara",
    "cazar cuesta",
]

def preparar(texto):
    return list(texto.replace(" ", "▁")) + ["</w>"]

def contar_pares(vocab):
    pares = Counter()
    for secuencia in vocab:
        pares.update(zip(secuencia, secuencia[1:]))
    return pares

def fusionar(secuencia, par):
    fusion = "".join(par)
    salida = []
    i = 0
    while i < len(secuencia):
        if i < len(secuencia) - 1 and (secuencia[i], secuencia[i + 1]) == par:
            salida.append(fusion)
            i += 2
        else:
            salida.append(secuencia[i])
            i += 1
    return salida

vocab = [preparar(texto) for texto in corpus]
merges = []

for _ in range(8):
    par, frecuencia = contar_pares(vocab).most_common(1)[0]
    merges.append((par, "".join(par), frecuencia))
    vocab = [fusionar(secuencia, par) for secuencia in vocab]

piezas = sorted({pieza for secuencia in vocab for pieza in secuencia})
ids = {pieza: i for i, pieza in enumerate(piezas)}

def encode(texto):
    secuencia = preparar(texto)
    for par, _, _ in merges:
        secuencia = fusionar(secuencia, par)
    return secuencia

ejemplo = encode("la casa cuesta")
ejemplo_ids = [ids.get(pieza, "<unk>") for pieza in ejemplo]

print("merges_aprendidos:")
for paso, (_, pieza, frecuencia) in enumerate(merges, start=1):
    print(paso, pieza, frecuencia)
print("vocabulario:", ids)
print("tokens:", ejemplo)
print("ids:", ejemplo_ids)

Salida esperada:

merges_aprendidos:
1 ▁c 6
2 la 5
3 a</w> 4
4 sa 3
5 es 3
6 ▁cla 3
7 ▁clar 3
8 ▁clara</w> 3
vocabulario: {'a': 0, 'a</w>': 1, 'c': 2, 'es': 3, 'la': 4, 'r': 5, 'sa': 6, 't': 7, 'u': 8, 'z': 9, '▁': 10, '▁c': 11, '▁clara</w>': 12}
tokens: ['la', '▁c', 'a', 'sa', '▁c', 'u', 'es', 't', 'a</w>']
ids: [4, 11, 0, 6, 11, 8, 3, 7, 1]

Lo importante no es que el corpus sea ridículamente pequeño, sino el patrón: corpus, normalización, pares frecuentes, merges, vocabulario, ids y encode. Si entrenas con otros textos, cambia el vocabulario. Si cambias el tokenizador, cambian los ids. Si cambian los ids, el modelo ya no está leyendo el mismo idioma interno.

2. Calcular presupuesto de una llamada

Ahora simulamos una calculadora de presupuesto. Usaremos precios inventados por millón de tokens para no depender de tarifas reales. Lo importante es la estructura: entrada fresca, entrada cacheada, salida, ventana, coste, cache hit y decisión de optimización.

from dataclasses import dataclass

@dataclass
class Tarifa:
    entrada: float
    salida: float
    cache_read: float
    cache_write: float

@dataclass
class Llamada:
    instrucciones: int
    historial: int
    documentos: int
    tools_schema: int
    salida_max: int
    salida_real: int
    cache_hit: int
    cache_write: int
    ventana: int

tarifa = Tarifa(
    entrada=2.00,
    salida=8.00,
    cache_read=0.20,
    cache_write=2.50,
)

llamada = Llamada(
    instrucciones=700,
    historial=1800,
    documentos=14000,
    tools_schema=1200,
    salida_max=1500,
    salida_real=650,
    cache_hit=12000,
    cache_write=0,
    ventana=32000,
)

entrada_total = (
    llamada.instrucciones
    + llamada.historial
    + llamada.documentos
    + llamada.tools_schema
)
entrada_fresca = max(entrada_total - llamada.cache_hit, 0)
tokens_reservados = entrada_total + llamada.salida_max
tokens_reales = entrada_total + llamada.salida_real

coste = (
    entrada_fresca * tarifa.entrada
    + llamada.cache_hit * tarifa.cache_read
    + llamada.cache_write * tarifa.cache_write
    + llamada.salida_real * tarifa.salida
) / 1_000_000

cache_ratio = llamada.cache_hit / entrada_total if entrada_total else 0
margen_ventana = llamada.ventana - tokens_reservados

print("entrada_total:", entrada_total)
print("entrada_fresca:", entrada_fresca)
print("tokens_reservados:", tokens_reservados)
print("tokens_reales:", tokens_reales)
print("margen_ventana:", margen_ventana)
print("cache_hit_ratio:", round(cache_ratio, 3))
print("coste_estimado:", round(coste, 6))

if margen_ventana < 0:
    print("decision: no cabe; resume, reduce documentos o usa RAG")
elif cache_ratio < 0.3 and llamada.documentos > 5000:
    print("decision: revisar cache o retrieval; hay mucho contexto fresco")
else:
    print("decision: cabe; medir calidad y latencia antes de cambiar modelo")

Salida esperada:

entrada_total: 17700
entrada_fresca: 5700
tokens_reservados: 19200
tokens_reales: 18350
margen_ventana: 12800
cache_hit_ratio: 0.678
coste_estimado: 0.019
decision: cabe; medir calidad y latencia antes de cambiar modelo

Ahora cambia cache_hit a 0. Verás que la llamada sigue cabiendo, pero cuesta más. Luego sube documentos a 35_000. Verás que el problema ya no es solo dinero: la llamada deja de caber. Esa diferencia es el corazón del capítulo.

Cómo encaja todo

Este mapa conecta tokens con las decisiones que ya venimos construyendo: APIs, schemas, RAG, elección de modelo y operación.

graph TD
    subgraph "Capítulo 3: Tokens, coste, contexto y caché"
        TOKENIZER["Tokenizador"]
        TOK["Tokens"]
        WIN["Ventana de contexto"]
        CONTEXT["Contexto de llamada"]
        MEMORY["Memoria de producto"]
        KVCACHE["KV cache"]
        ACTIVE["Parámetros activos"]
        COST["Coste"]
        CACHE["Prompt caching"]
        LAT["Latencia"]
        BATCH["Batch"]
        BUDGET["Presupuesto de tokens"]
        USAGE["Usage y trazas"]
    end
    subgraph "Viene de capítulos anteriores"
        API["Contrato de API (F4C2)"]
        SCHEMA["Schema y tools (F4C2)"]
        ATT["QKV y atención (F3C3)"]
        MOE["MoE y router (F3C5)"]
        LLM["LLM y decode (F3C7)"]
    end
    subgraph "Continuidad del facsímil 4"
        MODELCARD["Model cards (F4C4)"]
        LOCAL["Modelos locales<br/>(F4C5-06)"]
        RAG["RAG y chunking (F4C7-10)"]
        MULTI["Multimodalidad (F4C11)"]
        EVALS["Evals y trazas (F4C13)"]
    end

    API --> BUDGET
    SCHEMA --> CONTEXT
    TOKENIZER --> TOK
    LLM --> LAT
    ATT --> KVCACHE
    MOE --> ACTIVE
    MOE --> LAT
    TOK --> WIN
    TOK --> COST
    TOK --> LAT
    CONTEXT --> TOKENIZER
    CONTEXT --> WIN
    MEMORY --> CONTEXT
    WIN --> BUDGET
    KVCACHE --> LAT
    KVCACHE --> LOCAL
    ACTIVE --> COST
    ACTIVE --> MODELCARD
    CACHE --> COST
    CACHE --> LAT
    BATCH --> COST
    BUDGET --> USAGE
    USAGE --> MODELCARD
    COST --> MODELCARD
    WIN --> RAG
    TOK --> LOCAL
    TOK --> MULTI
    USAGE --> EVALS

    style TOKENIZER fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TOK fill:#F5F5F5,stroke:#000000,stroke-width:2
    style WIN fill:#F5F5F5,stroke:#000000,stroke-width:2
    style CONTEXT fill:#F5F5F5,stroke:#000000,stroke-width:2
    style MEMORY fill:#F5F5F5,stroke:#000000,stroke-width:2
    style KVCACHE fill:#F5F5F5,stroke:#000000,stroke-width:2
    style ACTIVE fill:#F5F5F5,stroke:#000000,stroke-width:2
    style COST fill:#F5F5F5,stroke:#000000,stroke-width:2
    style CACHE fill:#F5F5F5,stroke:#000000,stroke-width:2
    style LAT fill:#F5F5F5,stroke:#000000,stroke-width:2
    style BATCH fill:#F5F5F5,stroke:#000000,stroke-width:2
    style BUDGET fill:#F5F5F5,stroke:#000000,stroke-width:2
    style USAGE fill:#F5F5F5,stroke:#000000,stroke-width:2
    style API stroke-dasharray: 5 5
    style SCHEMA stroke-dasharray: 5 5
    style ATT stroke-dasharray: 5 5
    style MOE stroke-dasharray: 5 5
    style LLM stroke-dasharray: 5 5
    style MODELCARD stroke-dasharray: 5 5
    style LOCAL stroke-dasharray: 5 5
    style RAG stroke-dasharray: 5 5
    style MULTI stroke-dasharray: 5 5
    style EVALS stroke-dasharray: 5 5

Vocabulario aprendido

Estos términos nos permiten hablar de coste y contexto sin quedarnos en “el prompt es largo”.

Término	Definición
Token	Unidad mínima que el modelo procesa; puede ser una palabra, fragmento, signo o espacio.
Tokenizador	Software que convierte texto en ids de tokens y reconstruye texto desde esos ids.
Vocabulario de tokens	Tabla versionada que asigna piezas a identificadores numéricos.
BPE	Técnica que aprende subpalabras fusionando pares frecuentes.
SentencePiece	Enfoque de tokenización de subpalabras que puede aprender desde texto crudo y tratar espacios explícitamente.
Ventana de contexto	Límite de tokens que pueden viajar juntos en una llamada.
Token de entrada	Token enviado al modelo antes de generar.
Token de salida	Token producido por el modelo durante la respuesta.
Prefill	Procesamiento inicial de la entrada.
Decode	Generación de salida token a token.
KV cache	Claves y valores de atención guardados temporalmente para acelerar inferencia.
Memoria de producto	Información persistida por la aplicación y reinyectada en contexto cuando toca.
MoE	Arquitectura con varios expertos donde cada token activa solo algunos en ciertas capas.
Router MoE	Módulo aprendido que puntúa expertos y elige top-k para cada token y capa.
Parámetros activos	Parámetros usados realmente por un token, distintos de todos los parámetros almacenados.
Prompt caching	Reutilización de un prefijo repetido cuando el proveedor lo soporta.
Cache hit	Tokens que coinciden con contenido cacheado.
Batch	Procesamiento diferido de muchas peticiones.
Presupuesto de tokens	Reparto planificado entre instrucciones, historial, documentos, tools y salida.

Antes de pasar página

En resumen

Los tokens son la contabilidad básica de una integración con modelos. No son solo un detalle técnico: determinan cabida, coste, latencia, diseño de contexto, selección de modelo y estrategia de operación.

Idea fuerza	Detalle
El token es la unidad que paga, cabe y tarda.	Palabras, documentos y herramientas se traducen a tokens.
El tokenizador es parte del modelo.	Si cambias tokenizer, vocabulario o plantilla de mensajes, cambias la entrada real.
La ventana de contexto se reparte.	Instrucciones, historial, documentos, tools y salida compiten por el mismo espacio.
El modelo no recuerda por defecto.	La memoria útil vive en producto y se vuelve a meter en contexto.
La KV cache no es memoria de usuario.	Es memoria temporal de inferencia para no recalcular claves y valores.
MoE cambia el MLP, no la naturaleza de los tokens.	Cada token sigue atravesando capas, pero activa solo algunos expertos en las capas MoE.
Parámetros totales no son parámetros activos.	En un MoE hay que preguntar cuántos expertos se activan por token y cómo afecta a latencia.
El coste es por componentes.	Entrada, salida, cache y batch pueden tener precios distintos.
La caché necesita prefijos estables.	Lo repetido va al principio; lo dinámico al final.
Más contexto no siempre mejora.	Puede aumentar ruido, coste y latencia.
Sin usage no hay optimización seria.	Hay que registrar tokens, cache hit, modelo, coste y latencia.

Para saber más

Ainslie, J. et al. (2023). GQA: Training Generalized Multi-Query Transformer Models from Multi-Head Checkpoints. https://arxiv.org/abs/2305.13245

Anthropic. (2026). Context windows. https://platform.claude.com/docs/en/build-with-claude/context-windows

Anthropic. (2026). Prompt caching. https://platform.claude.com/docs/en/build-with-claude/prompt-caching

Anthropic. (2026). Token counting. https://platform.claude.com/docs/en/build-with-claude/token-counting

Fedus, W., Zoph, B. y Shazeer, N. (2022). Switch Transformers: Scaling to Trillion Parameter Models with Simple and Efficient Sparsity. https://jmlr.org/papers/v23/21-0998.html

Google. (2026). Context caching. https://ai.google.dev/gemini-api/docs/caching

Google. (2026). Gemini Developer API pricing. https://ai.google.dev/gemini-api/docs/pricing

Google. (2026). Long context. https://ai.google.dev/gemini-api/docs/long-context

Google. (2026). Token counting. https://ai.google.dev/gemini-api/docs/tokens

Jiang, A. Q. et al. (2024). Mixtral of Experts. https://arxiv.org/abs/2401.04088

Kudo, T. y Richardson, J. (2018). SentencePiece: A simple and language independent subword tokenizer and detokenizer for Neural Text Processing. https://aclanthology.org/D18-2012/

Kwon, W. et al. (2023). Efficient Memory Management for Large Language Model Serving with PagedAttention. https://arxiv.org/abs/2309.06180

Lepikhin, D. et al. (2021). GShard: Scaling Giant Models with Conditional Computation and Automatic Sharding. https://arxiv.org/abs/2006.16668

OpenAI. (2026). Batch API. https://developers.openai.com/api/docs/guides/batch

OpenAI. (2026). Cost optimization. https://developers.openai.com/api/docs/guides/cost-optimization

OpenAI. (2026). Counting tokens. https://developers.openai.com/api/docs/guides/token-counting

OpenAI. (2026). Latency optimization. https://developers.openai.com/api/docs/guides/latency-optimization

OpenAI. (2026). Pricing. https://developers.openai.com/api/docs/pricing

OpenAI. (2026). Prompt caching. https://developers.openai.com/api/docs/guides/prompt-caching

OpenAI. (2026). tiktoken. https://github.com/openai/tiktoken

Sennrich, R., Haddow, B. y Birch, A. (2016). Neural Machine Translation of Rare Words with Subword Units. https://aclanthology.org/P16-1162/

Shazeer, N. et al. (2017). Outrageously Large Neural Networks: The Sparsely-Gated Mixture-of-Experts Layer. https://arxiv.org/abs/1701.06538

Vaswani, A. et al. (2017). Attention Is All You Need. https://papers.nips.cc/paper/7181-attention-is-all-you-need

Notas

OpenAI. (2026). Counting tokens. https://developers.openai.com/api/docs/guides/token-counting. Consultado el 25 de mayo de 2026. ↩
OpenAI. (2026). Prompt caching. https://developers.openai.com/api/docs/guides/prompt-caching. Consultado el 25 de mayo de 2026. ↩
OpenAI. (2026). Cost optimization. https://developers.openai.com/api/docs/guides/cost-optimization. Consultado el 25 de mayo de 2026. ↩
OpenAI. (2026). Batch API. https://developers.openai.com/api/docs/guides/batch. Consultado el 25 de mayo de 2026. ↩
OpenAI. (2026). Latency optimization. https://developers.openai.com/api/docs/guides/latency-optimization. Consultado el 25 de mayo de 2026. ↩
Anthropic. (2026). Token counting. https://platform.claude.com/docs/en/build-with-claude/token-counting. Consultado el 25 de mayo de 2026. ↩
Anthropic. (2026). Prompt caching. https://platform.claude.com/docs/en/build-with-claude/prompt-caching. Consultado el 25 de mayo de 2026. ↩
Anthropic. (2026). Context windows. https://platform.claude.com/docs/en/build-with-claude/context-windows. Consultado el 25 de mayo de 2026. ↩
Google. (2026). Token counting. https://ai.google.dev/gemini-api/docs/tokens. Consultado el 25 de mayo de 2026. ↩
Google. (2026). Long context. https://ai.google.dev/gemini-api/docs/long-context. Consultado el 25 de mayo de 2026. ↩
Google. (2026). Context caching. https://ai.google.dev/gemini-api/docs/caching. Consultado el 25 de mayo de 2026. ↩
Google. (2026). Gemini Developer API pricing. https://ai.google.dev/gemini-api/docs/pricing. Consultado el 25 de mayo de 2026. ↩
Noam Shazeer et al. (2017). Outrageously Large Neural Networks: The Sparsely-Gated Mixture-of-Experts Layer. ICLR. https://arxiv.org/abs/1701.06538. ↩
William Fedus, Barret Zoph y Noam Shazeer. (2022). Switch Transformers: Scaling to Trillion Parameter Models with Simple and Efficient Sparsity. Journal of Machine Learning Research, 23(120), 1-39. https://jmlr.org/papers/v23/21-0998.html. ↩
Dmitry Lepikhin et al. (2021). GShard: Scaling Giant Models with Conditional Computation and Automatic Sharding. ICLR. https://arxiv.org/abs/2006.16668. ↩
Albert Q. Jiang et al. (2024). Mixtral of Experts. https://arxiv.org/abs/2401.04088. ↩
OpenAI. (2026). tiktoken. https://github.com/openai/tiktoken. Consultado el 25 de mayo de 2026. ↩
Rico Sennrich, Barry Haddow y Alexandra Birch. (2016). Neural Machine Translation of Rare Words with Subword Units. ACL. https://aclanthology.org/P16-1162/. ↩
Taku Kudo y John Richardson. (2018). SentencePiece: A simple and language independent subword tokenizer and detokenizer for Neural Text Processing. EMNLP. https://aclanthology.org/D18-2012/. ↩
OpenAI. (2026). Pricing. https://developers.openai.com/api/docs/pricing. Consultado el 25 de mayo de 2026. ↩
Ashish Vaswani et al. (2017). Attention Is All You Need. NeurIPS. https://papers.nips.cc/paper/7181-attention-is-all-you-need. ↩
Joshua Ainslie et al. (2023). GQA: Training Generalized Multi-Query Transformer Models from Multi-Head Checkpoints. EMNLP. https://arxiv.org/abs/2305.13245. ↩
Woosuk Kwon et al. (2023). Efficient Memory Management for Large Language Model Serving with PagedAttention. SOSP. https://arxiv.org/abs/2309.06180. ↩

Capítulo 04

Facsímil 4 · La caja de herramientas

Capítulo 04: Model cards y elección de modelos

Elegir modelo sin dejarse arrastrar por el escaparate

Elegir modelo parece una decisión de catálogo: abres una tabla, miras cuál aparece arriba y lo usas. En proyectos reales casi nunca funciona así. El modelo que gana un benchmark general puede ser caro, lento, excesivo, poco conveniente por licencia, incómodo para tu runtime o flojo justo en el idioma, formato y dominio que necesitas.

Venimos del capítulo 03, donde vimos que tokens, coste, contexto y caché convierten una llamada aparentemente sencilla en una decisión de ingeniería. Aquí añadimos la siguiente capa: cómo leer la ficha de un modelo y decidir con criterio.

La idea central es esta: no eliges el mejor modelo en abstracto; eliges el modelo que cumple una tarea, bajo restricciones, con evidencia suficiente.

Estado del arte con fecha de corte

Fecha de corte: 14 de junio de 2026.
Fuentes consultadas: documentación oficial de modelos y precios de OpenAI, Anthropic y Google Gemini API; documentación de Hugging Face sobre model cards; definición de Open Source AI y Open Weights de la Open Source Initiative; fichas/licencias de gpt-oss, Qwen, Mistral, DeepSeek, Gemma y Llama; artículos académicos sobre model cards, datasheets y evaluación holística; y benchmarks de sistemas de inferencia.

Lo estable es el método: documentar el modelo, leer uso previsto, capacidades, límites, datos, licencia, coste, contexto, evaluación y condiciones de despliegue. Lo cambiante son los nombres de modelos, ventanas máximas, precios, disponibilidad regional, versiones preview, modelos retirados, rate limits y capacidades por API.

Actualización de apertura de modelos: el 14 de junio de 2026 se revisó además la distinción entre modelos cerrados, pesos abiertos, código abierto y Open Source AI. Es una parte especialmente cambiante porque los proveedores publican nuevas familias, licencias y repositorios con mucha frecuencia. Por eso en esta sección no basta con decir “modelo abierto”: hay que decir qué está abierto, bajo qué licencia, qué puedes modificar, qué no puedes reproducir y qué KPI vas a medir.

Para no convertir el capítulo en una lista que caduca, dejamos las fuentes ordenadas por función:

Fuente	Qué aporta	Cómo usarla
Model Cards for Model Reporting.¹	Marco original para documentar modelos, usos, métricas y límites.	Como plantilla mental de lectura.
Datasheets for Datasets.²	Documentación de datos, motivación, composición, recogida y mantenimiento.	Para no leer una model card sin preguntar por datos.
Hugging Face Model Cards.³	Implementación práctica: README con metadatos, licencia, datasets, evaluación y texto explicativo.	Para leer modelos abiertos o open weights.
OpenAI Models.⁴	Catálogo vivo de modelos, modalidades y usos previstos.	Como foto actual, no como verdad permanente.
OpenAI Pricing.⁵	Precios por modalidad, entrada, salida, cache, batch y variantes de servicio.	Para calcular coste por tarea, no solo coste por token.
Anthropic Models.⁶	Comparación de modelos Claude, ventanas y capacidades declaradas.	Para contrastar familia, contexto y capacidades.
Anthropic Pricing.⁷	Coste de entrada, salida, cache y operaciones por lote.	Para no confundir modelo potente con solución asumible.
Google Gemini Models.⁸	Modelos Gemini, estados estable/preview/experimental y modalidades.	Para vigilar estabilidad de versión y API concreta.
Google Gemini Pricing.⁹	Precios por modelo, modalidad, contexto y uso de API.	Para revisar el coste justo el día de la decisión.
HELM.¹⁰	Evaluación amplia con múltiples escenarios, métricas y transparencia de resultados.	Para desconfiar de rankings de una sola métrica.
MLPerf Inference.¹¹	Benchmark de sistemas completos de inferencia.	Para recordar que modelo, runtime y hardware van juntos.

Modelo cerrado, pesos abiertos y código abierto no son lo mismo

Aquí conviene ir despacio, porque esta confusión aparece muchísimo. En software tradicional, “código abierto” suele significar que puedes inspeccionar, modificar, compilar y redistribuir el código bajo ciertas condiciones. En IA generativa, el objeto que usamos no es solo código. Hay arquitectura, pesos, tokenizer, datos de entrenamiento, filtros, scripts de entrenamiento, receta de post-training, evaluaciones, plantillas de chat, runtime y, a veces, una API gestionada que no expone nada de eso.

Por eso decir “este modelo es abierto” sin apellido es demasiado vago. Puede significar una de varias cosas:

El modelo está disponible por API, pero los pesos son cerrados.
Los pesos se pueden descargar, pero no se publican los datos ni la receta completa de entrenamiento.
Hay código de inferencia abierto, pero los pesos o datos no lo son.
Hay pesos, código y suficiente información de datos/proceso para estudiar y modificar el sistema de forma profunda.

La Open Source Initiative formaliza una definición de Open Source AI basada en libertades de uso, estudio, modificación y compartición. Además, exige acceso a la forma preferida para modificar el sistema: información suficientemente detallada de datos, código usado para procesar y entrenar, y parámetros o pesos bajo términos adecuados.¹² Esa definición es más exigente que “puedo descargar un checkpoint”.

La propia OSI distingue también los open weights: publicar los pesos finales ayuda mucho, pero normalmente no incluye el código de entrenamiento completo, los datos, los filtros, los checkpoints intermedios ni la receta suficiente para reproducir el modelo.¹³ Dicho de forma cercana: tener los pesos es como tener el edificio terminado; ayuda a vivir dentro, reformar algunas habitaciones y medir su consumo, pero no te da necesariamente los planos completos, el origen de todos los materiales ni el diario de obra.

Qué son exactamente los pesos

Los pesos son los números aprendidos durante el entrenamiento. En una red neuronal, cada capa transforma vectores usando matrices y funciones no lineales. Esas matrices contienen parámetros. Después de entrenar, esos parámetros quedan fijados en archivos: safetensors, gguf, checkpoints de PyTorch, formatos optimizados o variantes cuantizadas. Cuando alguien dice “pesos abiertos”, normalmente quiere decir: “puedes obtener esos números y cargarlos en un runtime compatible”.

Pero los pesos no son el modelo completo en sentido práctico. Para usarlos bien necesitas, como mínimo:

Pieza	Por qué importa
Arquitectura	Define cómo se conectan los pesos: capas, atención, MoE, normalización, activaciones.
Configuración	Define dimensiones, número de capas, vocabulario, contexto, precisión y detalles de carga.
Tokenizer	Convierte texto en tokens. Si cambias tokenizer, cambias la entrada real.
Chat template	Convierte roles y mensajes en el formato que el modelo espera.
Runtime	Ejecuta el modelo: Transformers, vLLM, SGLang, llama.cpp, Ollama, TensorRT-LLM, etc.
Licencia	Decide qué puedes hacer legalmente: usar, modificar, vender, redistribuir, servir.
Evals	Te dicen si ese modelo, con esa configuración, sirve para tu caso.

Por eso un modelo con pesos abiertos puede ser tremendamente útil y, aun así, no ser “Open Source AI” en sentido estricto. Puede que no puedas reproducir su entrenamiento, auditar todos sus datos, conocer sus filtros o verificar por qué aprendió ciertos sesgos. En ingeniería, eso cambia cómo lo documentas: no lo vendes como sistema transparente total, sino como artefacto ejecutable con más control operativo que una API cerrada.

Las cuatro categorías que conviene enseñar al alumno

Categoría	Qué tienes	Qué no tienes necesariamente	Ejemplos a 14 de junio de 2026	Decisión de ingeniería
Modelo cerrado por API	Endpoint, documentación, precios, SLA o contrato, herramientas del proveedor.	Pesos, datos, receta de entrenamiento, capacidad de servirlo tú.	GPT-5.5/GPT-5.4 en OpenAI API, Claude en Anthropic API, Gemini en Gemini API.¹⁴	Útil si necesitas capacidad alta, menor operación propia, herramientas integradas y contrato de servicio. Mide dependencia, coste, privacidad y plan de salida.
Pesos abiertos permisivos	Pesos descargables y licencia amplia, normalmente compatible con uso comercial.	Datos completos, receta reproducible, garantías de seguridad o coste operativo bajo.	`gpt-oss-120b/20b` bajo Apache 2.0; Qwen3.6 open-weight Apache 2.0; Mistral Large 3 bajo Apache 2.0; DeepSeek-R1 con licencia MIT.¹⁵	Bueno para control, despliegue propio, fine-tuning, privacidad y coste a escala. Mide VRAM, throughput, equipo de operación y calidad en tu eval.
Pesos abiertos con licencia propia	Pesos accesibles, documentación y permiso condicionado.	Libertad tipo MIT/Apache. Puede haber restricciones de escala, uso, redistribución o política aceptable.	Llama 4 bajo Llama 4 Community License; Gemma con open weights y términos propios de Google.¹⁶	Técnicamente puede ser muy atractivo, pero legalmente no lo trates como “open source clásico”. Revisa licencia con el caso de uso concreto.
Open Source AI estricto	Libertades de uso, estudio, modificación y compartición, más forma preferida de modificación: datos/información de datos, código y parámetros.	No siempre existe en modelos frontier modernos.	La OSI define el criterio; muchos modelos llamados “abiertos” solo cumplen parte.	Útil como vara conceptual y de auditoría. Pregunta siempre: ¿qué falta para reproducir, auditar y modificar de verdad?

La tabla ayuda, pero el cuerpo de la idea es este: cada nivel de apertura compra una libertad distinta y deja una deuda distinta. Una API cerrada compra velocidad de adopción, pero deja dependencia. Un open weight compra control, pero deja operación. Un open weight permisivo compra posibilidad de modificar y servir, pero no necesariamente transparencia científica. Un Open Source AI completo compraría auditabilidad profunda, pero todavía no es la norma en modelos frontier.

KPIs para decidir entre cerrado, pesos abiertos y open source

Una discusión madura no pregunta “¿abierto o cerrado?” como si fuera una preferencia moral. Pregunta qué KPI importa para el sistema. KPI aquí no significa poner números por ponerlos; significa elegir indicadores que cambian la decisión.

KPI	Qué mide	Cómo se calcula o se observa	Qué valor sería razonable
Calidad propia	Si resuelve tus casos, no el benchmark general.	Eval con casos de tu dominio: exactitud, rúbrica, tasa de formato válido, revisión humana.	Se fija por tarea: por ejemplo, >95 % JSON válido y >85 % acierto en casos críticos.
Coste por tarea completada	Coste real por respuesta útil, no por token aislado.	Tokens de entrada + salida + cache + batch + repeticiones + fallos.	El modelo barato que repite tres veces puede salir caro; mide coste por caso aprobado.
Latencia p95	Tiempo que sufre el 5 % más lento de usuarios.	Medición bajo carga con red, runtime, batch y contexto reales.	Interactivo: quizá <2-5 s; batch: puede ser minutos si está justificado.
Throughput	Cuántas peticiones o tokens procesas por segundo.	Requests/s, tokens/s, concurrencia y cola.	Importa mucho en open weights: una GPU infrautilizada destruye el TCO.
Coste de operación	Trabajo humano y técnico de mantener el sistema.	Horas de SRE/ML, actualizaciones, incidentes, monitorización, GPUs, parches.	API cerrada suele bajar operación propia; self-hosting la sube.
Riesgo de licencia	Probabilidad de que el uso viole términos o bloquee producto.	Revisión de licencia, restricciones de uso, redistribución, derivados, atribución.	Si el caso es comercial o regulado, licencia dudosa es filtro duro, no penalización pequeña.
Control de datos	Qué ocurre con prompts, documentos, logs y salidas.	Retención, región, entrenamiento con datos, cifrado, contratos, despliegue on-prem.	Datos sensibles pueden empujar a self-hosting o contrato enterprise fuerte.
Reproducibilidad	Capacidad de repetir la misma evaluación y volver a la misma versión.	Versión exacta, commit, hash de pesos, configuración, seeds, prompt, dataset.	En producción: modelo y configuración fijados; alias `latest` solo si aceptas cambio.
Capacidad de adaptación	Facilidad para fine-tuning, LoRA, cuantización o routing.	Acceso a pesos, licencia, tooling PEFT, soporte runtime.	Open weights gana aquí si el equipo sabe medir degradación.
Portabilidad	Facilidad de cambiar proveedor o mover despliegue.	Compatibilidad OpenAI-like, vLLM/SGLang, formatos, prompts, schemas, evals.	Cuanto más crítica la app, más importante mantener segundo candidato.
Observabilidad	Capacidad de ver fallos, costes y comportamiento.	Logs, trazas, métricas, prompts, outputs, tokens, latencia, errores por slice.	No uses un modelo que no puedes medir en el nivel que exige el riesgo.
Gobernanza	Capacidad de auditar qué se usa, por qué y bajo qué condiciones.	Model card interna, fecha, licencia, DPIA si aplica, evals, aprobaciones.	En entornos profesionales, una decisión sin ficha interna es memoria frágil.

Estos KPIs no pesan igual siempre. Para un prototipo de clase, calidad y facilidad de ejecución pueden bastar. Para un asistente con expedientes privados, privacidad, región, trazas y licencia pesan mucho más. Para una herramienta de código interna, quizá throughput, coste por tarea y capacidad de adaptación sean los criterios principales.

Ejemplo de lectura. Si una organización compara GPT-5.5 por API, Claude por API, Gemini por API, gpt-oss-120b, Qwen3.6 y Mistral Large 3, no debería empezar por “cuál es más inteligente”. Debería construir una matriz:

Filtros duros: privacidad, modalidad, licencia, región, presupuesto máximo.
Eval propia: 100 casos reales con salida esperada o rúbrica.
Medición operativa: p50/p95, tokens/s, coste por caso, tasa de retry.
Riesgo: dependencia de proveedor, licencia, plan de salida, estabilidad de versión.
Decisión: modelo principal, modelo alternativo, fecha de revisión y condiciones de cambio.

La conclusión puede ser híbrida. Por ejemplo: API cerrada para razonamiento difícil y multimodalidad; open weights para tareas repetitivas, datos sensibles o coste a escala; modelo pequeño local para clasificación barata; RAG para conocimiento vivo. Eso no es indecisión. Es arquitectura.

Qué significa “abierto” en una model card

Hugging Face permite declarar licencia en los metadatos de la model card y enlazar archivos LICENSE; también permite especificar datasets, pipeline_tag y resultados de evaluación estructurados.¹⁷ Eso está muy bien, pero hay que leerlo con cuidado.

Cuando veas una model card, separa estas preguntas:

Pregunta	Dónde mirar	Decisión que cambia
¿Puedo descargar pesos?	`Files and versions`, tamaño, formato, gated access.	Self-hosting, fine-tuning, cuantización.
¿Qué licencia tiene?	Metadata `license`, archivo `LICENSE`, términos externos.	Uso comercial, redistribución, derivados.
¿Hay código de inferencia?	README, ejemplos, `config.json`, runtime recomendado.	Facilidad de ejecución y compatibilidad.
¿Hay código de entrenamiento?	Paper, repo, scripts, argumentos, filtros.	Reproducibilidad y auditoría profunda.
¿Hay datos o información de datos?	Dataset card, README, paper, datasheets.	Riesgo de sesgo, cumplimiento, trazabilidad.
¿Hay evals comparables?	`model-index`, benchmark, paper, harness.	Calidad relativa y gaps de evaluación.
¿Hay política de uso?	Model card, terms, acceptable use policy.	Riesgo de producto y cumplimiento interno.

Un ejemplo típico: un repo puede tener pesos Apache 2.0 y ser muy útil para producción, pero no publicar dataset completo ni receta reproducible. En el libro lo llamaríamos “pesos abiertos permisivos”, no “open source completo”. No es un desprecio; es precisión.

Cómo lo explicaría en una revisión técnica

Una frase mala sería: “usamos un modelo open source porque es gratis”.

Una frase profesional sería: “para esta tarea usamos un modelo con pesos abiertos bajo licencia Apache 2.0, servido con vLLM en infraestructura propia, porque necesitamos control de datos y coste estable a volumen. No afirmamos que sea Open Source AI completo: no tenemos todos los datos de entrenamiento ni la receta reproducible. Lo compensamos con eval propia, model card interna, revisión de licencia, medición de p95 y alternativa API si la calidad cae”.

Y otra frase igualmente profesional sería: “para esta tarea usamos un modelo cerrado por API porque la calidad multimodal y las herramientas integradas superan el coste operativo de servir pesos abiertos. Lo documentamos como dependencia de proveedor, fijamos versión cuando el proveedor lo permite, medimos coste por tarea completada y mantenemos una eval de regresión para migrar”.

La madurez no está en elegir siempre abierto o siempre cerrado. Está en poder explicar qué libertad compras, qué deuda aceptas y qué KPI vigila que la decisión siga siendo buena.

Qué no es una model card

Una model card no es marketing. Puede estar mejor o peor escrita, pero su función no es decir “este modelo es increíble”. Su función es permitir una decisión responsable: qué es, para qué se pensó, dónde se evaluó, qué límites declara, qué licencia tiene y qué condiciones debes revisar antes de usarlo.

Tampoco es una garantía. Que una ficha diga “razonamiento”, “multimodal”, “contexto largo” o “excelente en código” no te dice automáticamente si funcionará en tu flujo. Te da pistas para construir pruebas.

Y no es un benchmark suelto. Una tabla de MMLU, SWE-bench, HumanEval, MMMU o cualquier otra métrica puede ser útil, pero solo mide lo que mide. Si tu producto clasifica incidencias en castellano, resume expedientes internos o genera SQL contra tu esquema, el ranking general es una señal débil.

La trampa más común es leer una model card como si fuera un menú. En realidad hay que leerla como una ficha de compatibilidad: “¿encaja con mi problema, mis datos, mi latencia, mi presupuesto, mis permisos y mi forma de evaluar?”.

Qué sí es: una ficha para decidir sin autoengaño

Una buena model card responde a seis bloques de preguntas:

Bloque	Preguntas que debe responder
Identidad	¿Qué modelo es, qué versión, qué familia, qué arquitectura y qué modalidad?
Uso previsto	¿Para qué fue diseñado? ¿Qué usos desaconseja?
Entrada y salida	¿Texto, imagen, audio, vídeo, tools, JSON, embeddings? ¿Qué límites tiene?
Evaluación	¿Con qué benchmarks, datasets, idiomas y condiciones se midió?
Operación	¿Contexto, coste, latencia, rate limits, runtime, hardware, versiones estables?
Condiciones	¿Licencia, privacidad, retención de datos, restricciones y obligaciones de atribución?

La palabra “modelo” además puede esconder capas distintas:

Nivel	Qué miras	Ejemplo de pregunta
Modelo base	Arquitectura y preentrenamiento.	¿Es base, instruct, MoE, multimodal o de embeddings?
Modelo servido por API	Capacidades y contrato del proveedor.	¿Acepta documentos? ¿Devuelve JSON validable? ¿Tiene tools?
Modelo local	Pesos, formato, cuantización y runtime.	¿GGUF, safetensors, vLLM, Ollama, TensorRT-LLM?
Sistema completo	RAG, tools, memoria, permisos y evals.	¿El fallo viene del modelo o del contexto que le damos?

Una elección madura empieza separando esos niveles. Cambiar de modelo no arregla una mala recuperación de documentos. Un modelo con contexto enorme no sustituye una política de permisos. Un benchmark alto no te exonera de evaluar tus casos.

El tamaño tampoco decide solo. Las leyes de escala ayudaron a entender cómo bajaba la pérdida al aumentar parámetros, datos y cómputo durante el entrenamiento.¹⁸ Después, el trabajo conocido como Chinchilla puso el foco en el equilibrio entre tamaño de modelo y cantidad de datos de entrenamiento.¹⁹ Para elegir en un producto, esa lección se traduce así: no preguntes solo “cuántos parámetros tiene”, pregunta si el modelo resuelve tu tarea con el coste, la latencia y la trazabilidad que puedes sostener.

La matriz mínima de decisión

Elegir con criterio exige convertir preferencias vagas en criterios comparables. No hace falta convertirlo todo en una hoja de cálculo infinita, pero sí conviene explicitar qué pesa más.

Ejemplo de fórmula. Una forma simple es puntuar cada modelo candidato con criterios normalizados:

S(m)=\sum_{j=1}^{n} w_j \cdot q_j(m)-\sum_{k=1}^{r} \lambda_k \cdot p_k(m)

Símbolo	Significado	Ejemplo
$S(m)$	Puntuación final del modelo $m$ .	0,78 para el candidato A.
$w_j$	Peso del criterio positivo $j$ .	Calidad vale 0,35; coste vale 0,20.
$q_j(m)$	Valor normalizado del criterio para el modelo.	Calidad propia 0,86; latencia 0,72.
$\lambda_k$	Peso de una penalización.	Penalizar licencia incompatible con 1,0.
$p_k(m)$	Penalización activada.	1 si no cumple privacidad; 0 si cumple.

Esta fórmula no pretende aparentar precisión. Pretende obligarte a declarar tus prioridades. Si privacidad es obligatoria, no debe ser “un criterio más”: debe ser un filtro. Si latencia p95 tiene que ser menor de 2 segundos, el modelo que no lo cumple queda fuera aunque gane un benchmark.

El flujo práctico suele ser:

Fase	Qué haces	Resultado
1. Requisitos	Defines tarea, entrada, salida, usuarios, idioma, latencia y presupuesto.	Lista de restricciones.
2. Filtros duros	Eliminas modelos que no cumplen licencia, modalidad, región, privacidad o contexto.	Lista corta inicial.
3. Lectura de fichas	Revisas model cards, docs de proveedor y versiones.	Hipótesis de encaje.
4. Eval propia	Pruebas casos representativos con salida esperada o rúbrica.	Evidencia en tu tarea.
5. Coste y operación	Mides tokens, p50/p95, fallos, rate limits y mantenimiento.	Coste total razonable.
6. Decisión	Documentas modelo elegido, alternativa y fecha de revisión.	Decisión trazable.

También conviene separar “calidad” de “fiabilidad”. Calidad es que responda bien cuando todo va bien. Fiabilidad es que falle de forma manejable cuando el caso es raro, falta contexto, la entrada está sucia o el formato de salida importa.

La ficha que yo leería antes de elegir

Cuando abras una model card o una página de modelos, no empieces por la frase grande. Empieza por esta lista:

Dato	Pregunta incómoda
Nombre exacto y versión	¿Estoy usando una versión estable o un alias que puede cambiar?
Modalidades	¿Texto solo, imagen, audio, vídeo, embeddings, tools?
Contexto	¿Cuánto entra realmente y cuánto debo reservar para salida?
Salida máxima	¿Puede devolver la respuesta completa o tengo que trocear?
Precio	¿Entrada, salida, cache, batch, imágenes, audio, razonamiento?
Latencia esperada	¿Me importa tiempo total o tiempo hasta primer token?
Datos y fecha de entrenamiento	¿Hay conocimiento que no puede saber sin RAG?
Evaluación	¿Los benchmarks se parecen a mi tarea?
Idiomas	¿Se evaluó de verdad en castellano o solo se declara soporte?
Formato de chat	¿Tiene plantilla de mensajes, system, tools, JSON, function calling?
Licencia	¿Puedo usarlo en mi producto, modificarlo, redistribuirlo o servirlo?
Retención y privacidad	¿Qué ocurre con los datos que envío?
Deprecación	¿Hay fecha de retirada, migración o versión recomendada?

Google, por ejemplo, distingue modelos estables, preview, latest y experimentales en su documentación de modelos. Esa clasificación importa porque latest o preview puede ser útil para explorar, pero no siempre es lo que quieres fijar en producción. OpenAI y Anthropic mantienen páginas vivas de modelos y precios; por eso una decisión profesional debería guardar fecha de consulta y versión exacta, no solo “usamos el modelo bueno”.

Anatomía de una model card en Hugging Face

Hugging Face convierte una model card en una página viva: parte README, parte ficha técnica, parte repositorio de archivos y parte panel operativo. Por eso conviene leerla en capas. Primero miras la identidad del modelo. Después los metadatos. Después los archivos. Después cómo se ejecuta. Y solo al final miras los benchmarks.

La idea no es aprender un ritual de botones. Es saber qué pregunta de ingeniería hay detrás de cada etiqueta.

Zona de la página	Qué estás mirando	Pregunta que debes hacer
`owner/model`	Organización y nombre exacto del repositorio.	¿Estoy mirando el modelo oficial, una copia, un fine-tune o una cuantización?
Tarea visible	Etiqueta como `Text Generation`, `Image-Text-to-Text` o `Feature Extraction`.	¿La tarea coincide con mi caso o estoy forzando el modelo?
Biblioteca	`Transformers`, `Diffusers`, `Sentence Transformers`, `timm` u otra.	¿Con qué librería se espera cargar o servir?
Formato	`Safetensors`, `GGUF`, `ONNX`, `PyTorch`, `TensorRT` u otros.	¿Es el formato que mi runtime puede abrir?
Licencia	MIT, Apache-2.0, llama, custom, research-only u otra.	¿Puedo usarlo, modificarlo, servirlo o redistribuirlo en mi contexto?
Tags	Palabras como `conversational`, `fp8`, `eval results`, `long-context`.	¿Son metadatos útiles o solo señales que debo comprobar?
Downloads y likes	Popularidad y uso reciente.	¿Hay adopción o solo ruido? Nunca es una prueba de calidad.
Model tree	Relación con fine-tunes, adapters y cuantizaciones.	¿Estoy viendo el tronco principal o una rama derivada?
Files and versions	Archivos, commits, pesos, config, tokenizer, licencia e historial.	¿Puedo auditar qué estoy descargando y cuándo cambió?
Inference Providers	Empresas que lo sirven desde la nube.	¿La calidad y el coste vienen del modelo o del proveedor que lo sirve?
Spaces	Demos o aplicaciones que usan el modelo.	¿Es una demo útil o una evidencia técnica? Normalmente es lo primero.
Evaluation results	Resultados integrados desde `model-index` o evaluaciones enlazadas.	¿Qué métrica, dataset, configuración y fuente produjo ese número?

La parte superior suele incluir metadatos que Hugging Face usa para buscar, filtrar y mostrar modelos. Algunos aparecen escritos en YAML dentro del README, otros se infieren desde archivos como config.json o desde la integración de la librería.

Término	Traducción práctica	Qué no debes asumir
`pipeline_tag`	Tarea principal del modelo. Decide filtros, widget y parte de la experiencia de inferencia.	Que el modelo sea bueno en todas las tareas parecidas.
`library_name`	Librería esperada para usarlo.	Que otra librería lo cargue igual sin conversión.
`license`	Condiciones de uso declaradas.	Que todo lo derivado tenga automáticamente la misma licencia sin revisar.
`language`	Idiomas declarados o detectados.	Que haya evaluación seria en todos esos idiomas.
`datasets`	Datasets de entrenamiento o evaluación que el autor declara.	Que conozcas todo el corpus real de entrenamiento.
`base_model`	Modelo del que parte un fine-tune, adapter o destilación.	Que conserve exactamente las capacidades del modelo base.
`new_version`	Repositorio recomendado como versión posterior.	Que puedas migrar sin repetir evals.
`tags`	Señales de búsqueda: modalidad, precisión, dominio, familia, técnica.	Que sean una especificación formal.
`model-index`	Resultados de evaluación estructurados.	Que el benchmark represente tu producto.
`widget`	Ejemplo interactivo en la página.	Que el prompt del widget sea tu contrato de producción.
`extra_gated_fields`	Campos que el usuario acepta antes de acceder a un modelo restringido.	Que aceptar la pantalla baste para resolver privacidad o permisos internos.

Ahora leamos un caso real. El 25 de mayo de 2026, la card de deepseek-ai/DeepSeek-V4-Pro aparece en Hugging Face como modelo de generación de texto, con etiquetas de Transformers, Safetensors, deepseek_v4, conversational, resultados de evaluación y precisión fp8; declara licencia MIT; y describe DeepSeek-V4-Pro como un modelo MoE de 1,6T parámetros totales, 49B parámetros activados y contexto de 1M tokens.²⁰

Lo importante no es memorizar esos números. Lo importante es saber leerlos. Para no convertirlo en una pared, vamos término a término, con el ejemplo de DeepSeek-V4-Pro como caso de lectura. Cuando una ficha técnica menciona DeepSeek-V4, también conviene contrastar con la documentación de Transformers, porque ahí aparecen detalles de arquitectura como tipos de atención, max_position_embeddings y clases de carga.²¹

La regla de esta sección es: ningún término se queda en definición de diccionario. Para cada dato preguntamos qué mide, qué recurso toca, con qué se compara, qué sería razonable y qué prueba haría antes de creerlo.

Identidad, tarea y repositorio

Estos términos responden a una pregunta básica: “¿qué estoy mirando exactamente?”. Parece trivial, pero muchísimos errores empiezan por usar una variante distinta de la que se quería evaluar.

Término en la card	Explicación completa	Ejemplo con DeepSeek-V4-Pro	Decisión práctica
`deepseek-ai/DeepSeek-V4-Pro`	Es el identificador completo del repositorio: organización o usuario antes de `/`, nombre del modelo después. En Hugging Face no basta con decir “DeepSeek V4”; puede haber forks, quantizations, fine-tunes y mirrors.	`deepseek-ai` indica la organización; `DeepSeek-V4-Pro` indica el repo concreto.	Guarda este valor exacto en documentación, evals y configuración. Si pruebas `Rooc/DeepSeek-V4-Pro`, ya no estás probando el mismo repositorio.
Namespace	Es la parte izquierda del identificador. Puede ser una empresa, una comunidad, una persona o una organización académica.	`deepseek-ai` no es lo mismo que `nvidia`, `unsloth`, `mlx-community` o una cuenta personal.	Antes de descargar pesos, mira si el repo es oficial, derivado o una adaptación para otro formato.
Repositorio	Es la carpeta pública del modelo: README, pesos, tokenizer, configuración, licencia, historial y discusiones.	En un repo grande encontrarás `README`, archivos `safetensors`, configuración, tokenizer, licencia, scripts y carpetas auxiliares.	Trata el repo como expediente técnico, no como una tarjeta de marketing.
`Text Generation`	Es la tarea principal declarada. Significa que el modelo genera texto token a token a partir de un contexto. No significa automáticamente “buen chat”, “buen agente” o “buen programador”.	DeepSeek-V4-Pro se muestra como generación de texto.	Si quieres embeddings, clasificación o visión, esta etiqueta por sí sola no basta. Busca el `pipeline_tag` correcto y evalúa tu tarea.
`conversational`	Tag que sugiere uso conversacional. Normalmente indica que el modelo está pensado para turnos de usuario/asistente.	Puede aparecer junto a `Text Generation`.	Revisa la plantilla de chat. Un modelo conversacional mal formateado puede fallar por entrada, no por capacidad.
`Eval Results`	Señal de que Hugging Face puede mostrar resultados de evaluación asociados al modelo.	La card puede enseñar métricas como GSM8K, SWE-bench, GPQA o benchmarks de contexto.	Lee dataset, métrica, configuración y fuente. El número sin protocolo vale poco.

Ejemplo cercano: si en un proyecto interno dices “vamos a usar DeepSeek”, esa frase no basta. Una decisión trazable diría algo como: “probamos deepseek-ai/DeepSeek-V4-Pro, consultado el 25 de mayo de 2026, frente a una alternativa local cuantizada y una API comercial, con estos 80 casos de evaluación”.

Librería, formato y archivos

La siguiente capa responde a: “¿cómo se carga y qué estoy descargando?”. Aquí aparecen términos que parecen de infraestructura, pero deciden si el modelo se puede probar hoy o si necesitas una semana de entorno.

Término en la card	Explicación completa	Ejemplo con DeepSeek-V4-Pro	Decisión práctica
`Transformers`	Indica integración con la librería de Hugging Face para tokenizers, configuración y modelos. No garantiza que tu portátil pueda cargarlo ni que tu versión instalada tenga soporte completo.	La card enseña ejemplos con `AutoTokenizer` y `AutoModelForCausalLM`.	Comprueba versión de `transformers`, memoria, `trust_remote_code` si aplica y soporte de arquitectura.
`Safetensors`	Formato de pesos basado en tensores, diseñado para ser simple, rápido y evitar dependencias de carga como `pickle`.²²	La zona lateral puede mostrar `Safetensors`.	Bien para distribuir pesos; no implica que el modelo quepa en GPU ni que tu runtime soporte todas sus capas.
`Files and versions`	Pestaña donde están los archivos reales y su historial. Es donde miras pesos, `config.json`, tokenizer, licencia, scripts y commits.	Si ves una carpeta `encoding`, no la ignores: puede explicar cómo convertir mensajes en texto para el modelo.	Para producción, fija commit o versión. No dependas solo del nombre del repo.
`config.json`	Archivo que describe arquitectura, dimensiones, vocabulario, contexto, tipos de capas y parámetros de inferencia.	Puede incluir `max_position_embeddings` o `layer_types`.	Si un número de la card no cuadra, abre la configuración antes de asumir que la card está mal o bien.
Tokenizer	Componente que parte texto en tokens y reconstruye texto desde tokens.	El mismo prompt puede convertirse en secuencias distintas según tokenizer.	No cambies tokenizer entre evals salvo que quieras medir otra cosa.
`Tensor type`	Tipos numéricos presentes en archivos: BF16, F32, FP8, enteros u otros.	La zona lateral puede listar varios tipos a la vez.	No leas “tensor type” como precisión única de inferencia. Puede mezclar pesos, escalas, índices y archivos auxiliares.
`License: mit`	Licencia declarada para repo y pesos, según la card. MIT suele ser permisiva, pero debes leer el archivo de licencia.	DeepSeek-V4-Pro declara MIT en la card.	Comprueba `LICENSE`, condiciones internas de tu organización y si usas derivados con otra licencia.

Ejemplo cercano: si un compañero dice “está en Safetensors, lo cargamos fácil”, la respuesta de ingeniería es: “formato de archivo sí; ahora dime tamaño, precisión, runtime, memoria, tokenizer, plantilla y licencia”.

Tamaño, precisión, contexto y memoria

Esta parte responde a: “¿cuánto pesa operar esto?”. Aquí se confunden mucho los términos porque parecen números comparables, pero no todos miden lo mismo. Un número útil debe decirte tres cosas: qué recurso toca, contra qué lo comparas y qué decisión cambia.

La cuenta mínima que debe tener un ingeniero en la cabeza es esta:

M_{\text{pesos}} \approx N_{\text{parametros}} \cdot \frac{b}{8}

Símbolo	Qué significa	Ejemplo
$M_{\text{pesos}}$	Memoria aproximada solo de pesos.	No incluye KV cache, activaciones, runtime ni fragmentación.
$N_{\text{parametros}}$	Número de parámetros almacenados.	7B, 70B, 1.6T.
$b$	Bits por parámetro.	F32 usa 32; BF16/F16 usa 16; FP8/I8 usa 8; FP4/I4 usa 4.

Regla de bolsillo: 1B parámetros ocupa unos 4 GB en F32, 2 GB en BF16/F16, 1 GB en FP8/INT8 y 0,5 GB en FP4/INT4, antes de sobrecostes. En producción añade memoria para KV cache, buffers, escalas de cuantización, runtime y margen de seguridad. Por eso “70B en 4-bit son 35 GB” es solo el principio de la conversación, no el dimensionamiento completo.

Comparación rápida	BF16/F16	FP8/INT8	FP4/INT4	Lectura de ingeniería
Modelo denso 7B	~14 GB	~7 GB	~3,5 GB	En local, 4-bit suele ser el punto de entrada; BF16 pide GPU más holgada.
Modelo denso 70B	~140 GB	~70 GB	~35 GB	Normalmente necesitas varias GPUs, servidor grande o cuantización fuerte.
MoE 1.6T con 49B activados	Pesos totales enormes	Menos memoria por peso	Menos memoria por peso	El cómputo por token se parece más a los activados, pero tienes que almacenar y servir el total o repartirlo.

Lo “adecuado” no es universal. Para entrenamiento o referencia científica, BF16/F16 suele ser base razonable; F32 queda para partes sensibles, depuración o cálculos concretos. Para inferencia de producción en hardware moderno, FP8/INT8 puede ser un buen compromiso si el runtime lo soporta. Para local, demos y coste bajo, INT4/FP4/GGUF puede ser aceptable, pero solo después de eval propia. NVIDIA documenta el uso de BF16, FP8 y formatos más bajos como parte de entrenamiento e inferencia de baja precisión; Hugging Face y vLLM mantienen documentación específica para cuantización en inferencia.²³

Término en la card	Explicación completa	Ejemplo con DeepSeek-V4-Pro	Decisión práctica
`1.6T total params`	Mide cuántos parámetros hay almacenados. Aporta una idea de memoria total, descarga, reparto entre GPUs y complejidad operativa. En MoE no equivale al cómputo por token.	Si fueran 1,6T en BF16, solo pesos serían ~3,2 TB; con FP8/FP4 mixto baja, pero sigue siendo infraestructura seria.	Compáralo con modelos densos 7B/70B. Si no tienes plan de serving distribuido o provider, este número ya te dice que no es “modelo local normal”.
`49B activated params`	Mide la parte aproximada que participa por token. Aporta una pista de coste de cómputo, no de memoria total.	49B activados se parece más a servir un modelo grande denso por token, pero con pesos totales mucho mayores detrás.	Úsalo para estimar latencia y throughput, pero no para decidir memoria de GPU. Memoria y cómputo son dos columnas distintas.
`Model size`	Estimación que muestra el Hub. Aporta una lectura rápida, pero puede mezclar detección automática, ficheros publicados y metadatos.	La UI puede resumir algo que el README detalla de otra manera.	Si hay discrepancia, abre `config.json`, README y archivos. El valor adecuado es el que puedes reproducir desde el repo.
`1M context length`	Mide ventana máxima teórica. Aporta capacidad para meter muchos tokens, pero también presión sobre KV cache, latencia y calidad de recuperación.	DeepSeek-V4-Pro declara contexto de 1M tokens.	Adecuado solo si tu tarea necesita contexto largo y lo evalúas. Para muchos productos, RAG con buenos fragmentos gana a meter todo.
`max_position_embeddings`	Mide posiciones máximas soportadas por la arquitectura/configuración. Aporta el límite estructural, no la promesa de experiencia barata.	En DeepSeek-V4 la documentación de Transformers menciona `1048576`, aproximadamente 1M posiciones.	Compáralo con tu longitud real: si tus casos tienen 8K-32K tokens, 1M quizá no aporta nada salvo coste.
`FP4 + FP8 Mixed`	Indica precisión mixta: algunas partes usan 4 bits y otras 8 bits. Aporta reducción de memoria/ancho de banda manteniendo más precisión donde conviene.	DeepSeek-V4-Pro declara expertos MoE en FP4 y la mayoría del resto en FP8.	Adecuado cuando el modelo fue entrenado/publicado para ese formato y tu runtime lo soporta. No lo equipares a una cuantización casera hecha después.
BF16	Flotante de 16 bits con rango amplio parecido a F32 y menos precisión fina. Aporta buena estabilidad con mitad de memoria que F32.	7B en BF16 son ~14 GB solo en pesos; 70B son ~140 GB.	Buen baseline de calidad para inferencia seria si tienes memoria. Si BF16 no cabe, cuantizas; si cabe, úsalo como referencia de comparación.
F32	Flotante de 32 bits. Aporta máxima comodidad numérica, pero cuesta el doble que BF16 y cuatro veces más que FP8/INT8 en memoria.	7B en F32 son ~28 GB solo pesos; 70B son ~280 GB.	No suele ser adecuado para servir LLM grandes completos. Útil para partes sensibles, depuración, entrenamiento clásico o modelos pequeños.
FP8	Flotante de 8 bits. Aporta ahorro de memoria y ancho de banda manteniendo comportamiento mejor que muchos enteros si está bien calibrado y soportado.	70B en FP8 son ~70 GB de pesos, antes de sobrecostes.	Adecuado en GPUs/runtimes modernos con soporte real. Evalúa porque FP8 no garantiza calidad: depende de escalas, kernels y arquitectura.
I8 / INT8	Entero de 8 bits. Aporta compresión y aceleración si el runtime tiene kernels adecuados. Suele necesitar escalas para reconstruir valores.	Un modelo de 70B en INT8 ronda ~70 GB de pesos más escalas y sobrecostes.	Adecuado para inferencia cuando la degradación medida es pequeña. No asumas que todo INT8 conserva igual matemáticas, código o formato JSON.
FP4 / INT4	4 bits por peso. Aporta gran reducción de memoria, a costa de mayor riesgo de pérdida de calidad.	Un 70B en 4-bit ronda ~35 GB de pesos más sobrecostes.	Adecuado para local, coste bajo o prototipos cuando la eval propia lo confirma. Para extracción exacta, SQL, código o razonamiento duro, compara contra BF16/FP8.
`Tensor type`	Lista tipos numéricos presentes en archivos. Aporta pistas, pero no dice por sí sola la precisión principal de inferencia.	Puede aparecer BF16, F32, FP8, I64 o I8 porque hay pesos, escalas, índices y metadatos.	No tomes el primer tipo como “el modelo corre en eso”. Pregunta: qué tensors son pesos, cuáles escalas, cuáles índices y qué usa el runtime.
Cuantización	Técnica para representar pesos o activaciones con menos bits. Aporta reducción de memoria y coste, pero puede cambiar calidad, velocidad y compatibilidad.	Puede aparecer como GGUF, GPTQ, AWQ, bitsandbytes, FP8, INT8, INT4 o repo derivado.	Lo adecuado depende de tu restricción: BF16 para referencia, FP8/INT8 para producción eficiente, 4-bit para local/coste bajo si pasa evals.

Ejemplo cercano: si tienes un asistente que responde a documentos de 40 páginas, un contexto de 1M tokens quizá no es la primera solución. Puede ser mejor recuperar 10 fragmentos bien citados con RAG, como veremos en capítulos 09 y 10.

Arquitectura: MoE, atención y conexiones internas

Estos términos explican cómo está construido el modelo. No siempre necesitas dominarlos para usar una API, pero sí para entender por qué un modelo tiene ciertas necesidades de runtime.

Término en la card	Explicación completa	Ejemplo con DeepSeek-V4-Pro	Decisión práctica
MoE	Mixture of Experts. El modelo tiene varios expertos y un mecanismo de enrutamiento decide cuáles se usan para cada token.	DeepSeek-V4-Pro es MoE: total enorme, activación parcial.	Necesitas servir expertos, routing y paralelismo con cuidado. Un runtime pobre puede arruinar la ventaja.
Expertos	Subredes especializadas dentro de un MoE. No son “personas”; son bloques de parámetros.	Un token puede activar ciertos expertos y no otros.	En inferencia distribuida importa dónde vive cada experto y cuánto tráfico genera.
Routing	Decisión interna de qué expertos se activan.	Cada token se enruta a una parte del modelo.	Puede afectar latencia, balanceo de carga y reproducibilidad de rendimiento.
CSA	Compressed Sparse Attention. Atención comprimida y dispersa para manejar contexto largo de forma más eficiente.	DeepSeek-V4 menciona CSA como parte de su atención híbrida.	No basta con leer “1M tokens”; mide si recupera bien información lejana en tu tarea.
HCA	Heavily Compressed Attention. Otra rama de atención comprimida orientada a señales de largo alcance.	La documentación describe capas HCA y CSA intercaladas.	Útil para contexto largo, pero exige pruebas de latencia, memoria y calidad.
mHC	Manifold-Constrained Hyper-Connections. Conexiones internas que sustituyen o refuerzan conexiones residuales tradicionales.	Aparece como cambio arquitectónico de DeepSeek-V4.	Interesa para entender estabilidad y diseño, pero no decide por sí solo si te sirve.
Sliding attention	Atención en ventana local. Mira solo un tramo cercano del contexto.	En algunos bloques se usa una ventana local.	Buena para eficiencia local; no sustituye por sí sola recuperación global.
KV cache	Memoria de claves y valores de atención durante generación. Ya la vimos en capítulo 03.	Contexto largo puede disparar KV cache si no hay compresión.	Para producto, KV cache es coste real: GPU, batch, latencia y throughput.

Ejemplo cercano: imagina una biblioteca. Un modelo denso abre todas las salas para cada consulta. Un MoE intenta abrir solo algunas salas especializadas. Eso ahorra trabajo por consulta, pero obliga a tener un edificio enorme disponible y un sistema de pasillos muy bien organizado.

Entrenamiento, ajuste y modos de razonamiento

Esta capa responde a: “¿qué se hizo para que el modelo se comporte así?”. Son términos de entrenamiento, no botones de producto.

Término en la card	Explicación completa	Ejemplo con DeepSeek-V4-Pro	Decisión práctica
Pretraining	Entrenamiento base sobre grandes cantidades de texto, código u otros datos. Aprende patrones generales.	La familia V4 declara preentrenamiento a gran escala antes del post-training.	No esperes que pretraining conozca tus documentos privados. Para eso entra RAG o fine-tuning.
Post-training	Fase posterior para ajustar instrucciones, formato, razonamiento, preferencias o herramientas.	La card habla de un pipeline posterior al pretraining.	Afecta cómo responde, no solo cuánto sabe. Evalúa estilo, obediencia de formato y consistencia.
SFT	Supervised fine-tuning: ajuste con pares entrada-salida. Enseña formato y comportamiento deseado.	“Si el usuario pregunta X, responde con Y” en muchos ejemplos.	Muy útil para tono y patrón de respuesta; no es buena vía para información que cambia cada día.
RL	Reinforcement learning. El modelo mejora usando señales de recompensa sobre sus respuestas.	Se usa en modelos de razonamiento para reforzar soluciones mejores.	Puede mejorar resolución, pero debes medir longitud, coste, formato y estabilidad.
GRPO	Group Relative Policy Optimization, variante usada en trabajos de DeepSeekMath para mejorar razonamiento con menor coste de memoria que PPO.²⁴	DeepSeek-V4 menciona RL con GRPO en su post-training.	Interpreta “GRPO” como pista de entrenamiento, no como garantía de que tu problema saldrá bien.
on-policy distillation	Destilación usando salidas generadas bajo la propia política del sistema durante el proceso de mejora.	La card lo describe como consolidación de capacidades.	Es relevante para entender la receta; tu aplicación sigue necesitando eval propia.
Muon optimizer	Optimizador usado durante entrenamiento para estabilidad o convergencia.	DeepSeek-V4 lo menciona como parte de sus mejoras.	No cambia tu llamada API. Sirve para leer el informe técnico, no para configurar un chatbot.
Non-think	Modo de respuesta más directa, sin gran presupuesto de razonamiento.	Útil para tareas rutinarias.	Si la tarea es simple, evita pagar latencia extra por razonamiento largo.
Think	Modo con más análisis interno y respuesta más cuidadosa.	Útil para planificación, código o problemas con varias restricciones.	Mide coste y tiempo. No lo actives por defecto en todo.
Think Max	Modo de esfuerzo máximo.	Pensado para problemas difíciles o evaluación de frontera.	Reserva para casos donde el coste adicional compense.

Ejemplo cercano: para clasificar tickets de soporte, Non-think puede bastar. Para revisar una migración de base de datos, quizá Think tenga sentido. Para explorar una demostración matemática o un problema de programación complejo, Think Max puede ser una prueba, no necesariamente el modo de producción.

Plantilla de chat, encoding y parámetros de generación

Aquí aparece una de las causas más tontas y más caras de errores: usar bien el modelo, pero formatear mal la entrada. Hugging Face documenta las chat templates como la forma de convertir mensajes en el formato exacto que el modelo vio durante entrenamiento.²⁵

Término en la card	Explicación completa	Ejemplo con DeepSeek-V4-Pro	Decisión práctica
Chat Template	Plantilla que convierte mensajes `system`, `user` y `assistant` en texto/tokens con separadores especiales.	Algunas familias usan Jinja; DeepSeek-V4-Pro indica una carpeta `encoding` en lugar de una plantilla Jinja clásica.	Si ignoras la plantilla, puedes convertir un buen modelo en un mal modelo.
`encoding` folder	Carpeta con scripts para codificar mensajes y parsear salidas.	Puede incluir funciones tipo “mensajes a string” y “texto generado a respuesta”.	Señal de contrato de entrada. No improvises el prompt final sin leerla.
Roles	Estructura de conversación: sistema, usuario, asistente y a veces herramientas.	Un mensaje de sistema puede fijar comportamiento; uno de usuario contiene la tarea.	Mantén roles consistentes entre eval y producción.
`temperature`	Controla aleatoriedad de muestreo. Valores bajos suelen ser más conservadores; altos, más variados.	La card puede recomendar `temperature = 1.0`.	Para extracción JSON o clasificación, baja variación. Para ideación, quizá más variación.
`top_p`	Muestreo por núcleo: limita candidatos a una masa de probabilidad acumulada.	La card puede recomendar `top_p = 1.0`.	No cambies `temperature` y `top_p` a ciegas; registra configuración en tus evals.
`max_new_tokens`	Máximo de tokens que puede generar la respuesta.	Si pides resumen largo con límite bajo, cortará la salida.	Reserva salida suficiente. Contexto total no es solo entrada.
Stop tokens	Secuencias que detienen generación.	Un token especial puede cerrar un bloque de razonamiento o respuesta.	Útiles para formato; peligrosos si cortan respuestas válidas.

Ejemplo cercano: dos equipos pueden “usar el mismo modelo” y obtener resultados distintos si uno aplica bien la plantilla de chat y otro manda un string plano. La diferencia no está en inteligencia; está en protocolo.

Runtimes, proveedores y despliegue

Esta parte responde a: “¿dónde corre y con qué contrato?”. El modelo no vive en el aire: necesita runtime, hardware, límites, observabilidad y presupuesto. vLLM y SGLang, por ejemplo, exponen servidores compatibles con APIs tipo OpenAI para servir modelos grandes.²⁶

Término en la card	Explicación completa	Ejemplo con DeepSeek-V4-Pro	Decisión práctica
vLLM	Runtime de inferencia orientado a throughput, batch, KV cache y API compatible con OpenAI.	La card puede enseñar cómo servir el modelo con `vllm serve`.	Mide p50, p95, tokens por segundo, memoria y límites de contexto.
SGLang	Framework de serving para modelos de lenguaje y multimodales, con foco en baja latencia, throughput, cache y paralelismo.	La card puede dar comandos `sglang.launch_server`.	Útil si necesitas exprimir serving, paralelismo o flujos estructurados.
Docker Model Runner	Forma de ejecutar modelos desde Docker usando comandos familiares y un endpoint gestionado por Model Runner.²⁷	La card puede mostrar `docker model run hf.co/...`.	Muy cómodo para probar; en producción revisa memoria, logs, versiones y despliegue real.
Inference Providers	Proveedores integrados en Hugging Face que sirven modelos alojados.²⁸	Puede aparecer Novita u otros proveedores para un modelo.	Compara proveedor concreto, región, precio, latencia, privacidad y versión servida.
OpenAI-compatible API	API que imita contratos de OpenAI, normalmente `/v1/chat/completions` u otros endpoints parecidos.	vLLM y SGLang pueden exponer endpoints compatibles.	Compatible no significa idéntico: revisa streaming, tools, JSON, errores y parámetros soportados.
Throughput	Cantidad de tokens o peticiones procesadas por unidad de tiempo.	Un modelo puede ser bueno para batch y peor para chat interactivo.	Si tienes muchos usuarios, throughput importa tanto como calidad.
Latencia p95	Tiempo por debajo del cual acaba el 95 por ciento de peticiones.	Una demo rápida puede esconder colas lentas.	Decide con p95, no solo con “a mí me respondió rápido”.
Batch	Agrupar peticiones para aprovechar hardware.	Muy útil en procesos nocturnos o clasificación masiva.	Puede mejorar coste, pero empeorar tiempo de espera interactivo.
Observabilidad	Logs, métricas, trazas, errores, coste y calidad en producción.	Necesitas saber cuándo falla, cuánto cuesta y qué versión respondió.	Sin observabilidad, elegir modelo es solo el inicio de una caja negra.

Ejemplo cercano: “lo sirve un provider” no responde a “¿me sirve a mí?”. Si tu aplicación trata documentos internos, necesitas saber retención, región, contrato, trazas, límites y cómo se comporta el proveedor cuando hay picos.

Evaluación y resultados

Las cards enseñan números porque necesitamos señales, pero cada número tiene una historia. Un benchmark sin protocolo es como una nota sin examen.

Término en la card	Explicación completa	Ejemplo con DeepSeek-V4-Pro	Decisión práctica
`Evaluation Results`	Bloque de resultados visibles en el Hub o enlazados desde la ficha.	Puede mostrar GSM8K, SWE-bench, GPQA, Terminal Bench u otros.	Úsalo para orientar, nunca para decidir sin eval propia.
Benchmark	Prueba estandarizada sobre un conjunto de tareas.	HumanEval mide programación; MMLU conocimiento general; GPQA razonamiento científico.	Pregunta si se parece a tu caso real.
Dataset	Conjunto de datos usado para medir.	GSM8K contiene problemas matemáticos de primaria/secundaria.	Si tu tarea es legal, médica o administrativa, GSM8K no te la resuelve.
Metric	Regla que convierte respuestas en puntuación.	`Pass@1`, `EM`, `ACC`, `F1`.	La métrica define qué cuenta como acierto. Léela antes de comparar.
Shots	Número de ejemplos que se dan en el prompt.	`0-shot`, `3-shot`, `5-shot`, `25-shot`.	Más ejemplos consumen tokens y pueden cambiar mucho el resultado.
Harness	Código y protocolo que ejecutan la evaluación.	Puede controlar prompts, herramientas, timeouts y validación.	Dos resultados en el mismo benchmark pueden no ser comparables si cambia el harness.
`tools enabled`	La evaluación permite usar herramientas externas, como terminal, navegador, ejecución de código o buscador.	Algunos benchmarks de agentes lo indican explícitamente.	No compares contra resultados sin herramientas como si fueran la misma prueba.
Source	Origen del resultado: autor del modelo, leaderboard externo, paper o tercero.	Hugging Face puede enlazar fuente de evaluación.	Prefiere resultados reproducibles o, como mínimo, con protocolo claro.

Ejemplo cercano: si un modelo saca muy buena nota en SWE-bench, eso no significa que clasifique bien incidencias de alumnos. Significa que merece pasar a tu lista corta para tareas de código, si tus restricciones de coste y privacidad encajan.

Hay un detalle muy de ingenieros: las cards grandes a veces muestran números que no parecen encajar a primera vista. En DeepSeek-V4-Pro puedes ver una tabla del README con parámetros totales, activados, contexto y precisión, y también una zona lateral generada por Hugging Face con “model size” y “tensor type”. Si algo no cuadra, no lo ignores: abre Files and versions, busca config.json, README, LICENSE, tokenizer, scripts de encoding y notas del repositorio. La card no es un oráculo; es la entrada al expediente.

Las métricas también tienen vocabulario propio. Conviene leerlas como leerías un contrato: una palabra pequeña cambia lo que realmente se está midiendo.

Métrica	Qué mide aproximadamente	Ejemplo sencillo	Cuidado
`EM`	Exact match: la respuesta generada debe coincidir exactamente con la esperada.	Esperado: `Madrid`. Generado: `Madrid`. Acierta. Generado: `La respuesta es Madrid`. Puede fallar si el evaluador es estricto.	Penaliza respuestas correctas con formato distinto. Es buena para respuestas cerradas, mala para explicaciones.
`F1`	Solapamiento entre partes de la respuesta esperada y generada. Se usa mucho cuando hay varias palabras relevantes.	Esperado: `revisar matrícula y pago`. Generado: `revisar el pago de matrícula`. Tiene bastante solapamiento.	Puede dar buena nota aunque falte un detalle crítico. En tareas sensibles, mira también errores cualitativos.
`Pass@1`	Si la primera solución generada pasa la prueba. Es común en código y problemas con verificador automático.	El modelo escribe una función; los tests se ejecutan una vez; si pasan, cuenta como acierto.	Depende muchísimo del harness, tests, timeout y formato esperado. No es “calidad general”.
`ACC`	Accuracy: porcentaje de aciertos sobre el total.	Clasifica 100 tickets; acierta 87; `ACC = 0.87`.	No dice qué clase falla. Si la clase rara es la importante, accuracy puede engañar.
`MMR`	Acrónimo que debes definir en el benchmark concreto. En recuperación suele ser Maximal Marginal Relevance; en algunas tablas puede aparecer con otro significado operacional.	En búsqueda semántica puede premiar resultados relevantes pero no repetidos.	Nunca asumas el significado por las siglas. Abre la ficha del benchmark.
`Elo`	Puntuación relativa por comparaciones entre modelos. Suele venir de duelos: respuesta A frente a respuesta B.	Un evaluador humano o automático prefiere una respuesta; el ranking se actualiza.	Depende de participantes, prompts, evaluador y protocolo. No es una unidad absoluta de inteligencia.
`0-shot`	El modelo responde sin ejemplos dentro del prompt.	“Clasifica este ticket” sin mostrar tickets anteriores resueltos.	Si tu producto sí usa ejemplos, este resultado quizá subestima tu caso.
`few-shot`	El prompt incluye algunos ejemplos antes de la tarea.	Das 3 tickets con categoría correcta y luego pides clasificar uno nuevo.	Puede mejorar mucho, pero consume contexto y puede sobreajustarse al formato de los ejemplos.
`tools enabled`	La evaluación permite usar herramientas externas: ejecución de código, terminal, buscador, base de datos o navegación controlada.	Para resolver un bug, el sistema puede ejecutar tests en vez de responder solo de memoria.	No compares con un resultado sin herramientas. Es otro sistema, no solo otro modelo.

Mi lectura práctica de una card de Hugging Face siempre termina con siete preguntas:

Pregunta	Dónde buscarla
¿Qué modelo exacto es?	Nombre del repo, organización, commits y versiones.
¿Qué tarea dice resolver?	`pipeline_tag`, tags, README y ejemplos.
¿Cómo se ejecuta bien?	`Use this model`, runtime, chat template, tokenizer y scripts.
¿Qué coste operativo tendrá?	Tamaño, precisión, contexto, parámetros activados, runtime y proveedores.
¿Qué evidencia trae?	`model-index`, tablas de evaluación, paper y fuente del benchmark.
¿Qué condiciones tiene?	Licencia, privacidad del proveedor, gating y restricciones internas.
¿Qué no me está diciendo?	Datos de entrenamiento, idiomas evaluados, fallos conocidos, prompts exactos y límites reales.

Si una card no responde a varias de estas preguntas, no significa que el modelo sea malo. Significa que tu decisión tiene más incertidumbre. Y la incertidumbre se compensa con pruebas propias, límites claros y una alternativa preparada.

Benchmarks: útiles, pero no soberanos

Los benchmarks son necesarios porque evitan discutir solo con impresiones. Pero no todos los benchmarks sirven para todas las decisiones. HELM nació precisamente para evaluar modelos de lenguaje de forma más holística: no solo exactitud, también escenarios, métricas y transparencia de resultados. Esa idea es más importante que cualquier posición concreta en una tabla.

Tres preguntas ayudan:

Pregunta	Por qué importa
¿Qué tarea mide?	Matemáticas, código, lectura, conversación, visión, SQL o seguridad no son lo mismo.
¿Cómo se evaluó?	Prompt, few-shot, temperatura, herramientas, idioma y versión pueden cambiar resultados.
¿Qué coste tuvo acertar?	Un modelo puede ganar usando más tokens, más tiempo o más cómputo de inferencia.

El capítulo anterior nos da el antídoto: mide tokens, coste y latencia además de calidad. Una respuesta que mejora un 2 % en exactitud pero triplica coste y p95 quizá no es mejor para tu producto.

Y hay otra capa: benchmark de modelo no es benchmark de sistema. MLPerf Inference, por ejemplo, mide sistemas completos bajo escenarios definidos. En aplicaciones con IA, el sistema incluye modelo, runtime, hardware, batch, cache, red, RAG, herramientas, validadores y observabilidad. Si solo miras el modelo, te faltan piezas.

Coste total: no solo precio por millón de tokens

El precio público es una parte, no toda la decisión. En una API pagas tokens, modalidades, cache, batch o prioridad según proveedor. En local pagas GPUs, electricidad, memoria, mantenimiento, actualización y tiempo del equipo. En ambos casos pagas también integración, evaluación y cambios de versión.

Ejemplo de fórmula. Una estimación útil es:

TCO = C_{\text{tokens}} + C_{\text{infra}} + C_{\text{operacion}} + C_{\text{cambio}}

Símbolo	Significado	Ejemplo
$TCO$	Coste total de propiedad.	Coste mensual real de servir una función.
$C_{\text{tokens}}$	Coste de entrada, salida, cache y batch.	Factura del proveedor.
$C_{\text{infra}}$	Infraestructura propia o gestionada.	GPU, CPU, memoria, almacenamiento, red.
$C_{\text{operacion}}$	Monitorización, fallos, evals y soporte.	Tiempo del equipo y alertas.
$C_{\text{cambio}}$	Migración entre versiones o proveedores.	Adaptar prompts, schemas y evals.

Este coste cambia según el patrón de uso. Un asistente interactivo necesita p95 bajo. Un proceso nocturno puede aceptar batch. Una tarea con normativa fija puede aprovechar caché. Una tarea con documentos privados puede empujar hacia local o hacia una API con garantías contractuales concretas.

Para entenderlo: tres elecciones distintas

Pensemos en situaciones concretas:

Caso	Modelo tentador	Decisión más sensata
Chat de orientación universitaria	El modelo más capaz disponible.	Modelo fiable, barato, con RAG, citas y buena evaluación en castellano.
Clasificador de tickets internos	Un LLM grande generalista.	Modelo menor con salida estructurada, eval propia y batch si no es interactivo.
Análisis de contratos extensos	El modelo con más contexto.	Contexto largo si aporta valor; si no, RAG con citas y control de fragmentos.
Generación de SQL	Modelo de código muy alto en benchmark.	Eval con tu esquema, permisos, consultas esperadas y validación antes de ejecutar.
Asistente local para datos sensibles	API más cómoda.	Revisar privacidad, modelo local, cuantización y coste operativo real.

La pregunta no es “¿cuál es mejor?”. La pregunta es “¿qué falla si me equivoco?”. Si el fallo cuesta poco, puedes experimentar. Si el fallo rompe una decisión importante, necesitas más evaluación, trazas y límites.

Mapa visual de la decisión

En el día a día

En un proyecto real, este capítulo aparece cuando alguien dice: “probemos con el modelo más potente”. A veces tiene sentido. Muchas otras veces la decisión correcta es un modelo más barato, una salida estructurada, RAG mejor hecho, caché, batch o una evaluación más honesta.

El trabajo profesional no es enamorarse de una familia de modelos. Es mantener una lista corta con versión exacta, fecha de consulta, coste estimado, eval propia y plan de salida si el proveedor cambia una versión o retira un endpoint.

Un equipo maduro guarda, junto al prompt y el código, una pequeña ficha interna: modelo elegido, alternativas descartadas, motivo, dataset de evaluación, resultados, costes, límites y próxima revisión. Esa ficha evita discusiones circulares cuando tres meses después alguien pregunta por qué no usamos “el nuevo”.

Por qué debería importarte

Porque la elección de modelo decide coste, experiencia de usuario, privacidad, mantenimiento y calidad. Si eliges solo por capacidad máxima, puedes construir un sistema que funciona en demo y duele en producción. Si eliges solo por precio, puedes ahorrar justo en la parte que sostenía la calidad.

También importa para aprender. Leer model cards te entrena a pensar como ingeniero: cada número pide una pregunta, cada benchmark pide contexto y cada promesa pide verificación.

Dónde volverá a aparecer

Este capítulo conecta la caja de herramientas con casi todo lo que viene después:

Concepto	Dónde vuelve	Para qué
Modelos locales	Capítulo 05.	Leer pesos, formato, cuantización, memoria y runtime.
Cloud frente a local	Capítulo 06.	Convertir elección de modelo en decisión de arquitectura.
Embeddings	Capítulo 07.	Elegir modelos de representación, no solo generativos.
RAG	Capítulos 09 y 10.	Decidir cuándo contexto externo pesa más que modelo mayor.
Evals	Facsímil 7.	Convertir criterios en pruebas reproducibles.
Operación	Facsímil 6.	Medir p95, coste, fallos y cambios de versión.

Dónde solía tropezar yo

Estos errores aparecen mucho cuando la conversación se queda en nombres de modelos.

Error	Por qué es un error	Antídoto
Elegir por ranking general	Un benchmark amplio no mide tu flujo, tus datos ni tu coste.	Crear una eval propia pequeña antes de decidir.
No fijar versión exacta	Un alias puede cambiar y romper comparabilidad.	Guardar modelo, fecha, proveedor y configuración.
Comparar precio sin salida	Un modelo barato puede generar más tokens o fallar más.	Medir coste por tarea completada, no solo por millón de tokens.
Confundir contexto largo con calidad	Más ventana puede añadir ruido y latencia.	Medir qué fragmentos son realmente necesarios.
Olvidar licencia o privacidad	El modelo puede funcionar técnicamente y no encajar legalmente.	Revisar condiciones antes de hacer pruebas profundas.
No tener alternativa	Cuando cambia una versión, el producto queda atado.	Mantener segundo candidato y eval de regresión.

Manos a la obra

Vamos a construir una matriz de decisión mínima. Usaremos datos inventados para evitar convertir el capítulo en una tabla de precios que caduca. Lo importante es la mecánica: filtros duros, criterios ponderados, penalizaciones y explicación de la decisión.

modelos = [
    {
        "nombre": "closed_api_frontier",
        "calidad": 0.94,
        "latencia": 0.62,
        "coste": 0.40,
        "contexto": 0.95,
        "control_datos": 0.55,
        "reproducibilidad": 0.50,
        "apertura": 0.10,
        "encaje_operativo": 0.90,
        "privacidad": True,
        "json": True,
        "licencia": True,
    },
    {
        "nombre": "closed_api_mini",
        "calidad": 0.84,
        "latencia": 0.86,
        "coste": 0.78,
        "contexto": 0.70,
        "control_datos": 0.55,
        "reproducibilidad": 0.55,
        "apertura": 0.10,
        "encaje_operativo": 0.95,
        "privacidad": True,
        "json": True,
        "licencia": True,
    },
    {
        "nombre": "open_weight_permissive",
        "calidad": 0.80,
        "latencia": 0.70,
        "coste": 0.82,
        "contexto": 0.68,
        "control_datos": 0.90,
        "reproducibilidad": 0.82,
        "apertura": 0.85,
        "encaje_operativo": 0.55,
        "privacidad": True,
        "json": True,
        "licencia": True,
    },
    {
        "nombre": "open_weight_license_propia",
        "calidad": 0.86,
        "latencia": 0.67,
        "coste": 0.75,
        "contexto": 0.82,
        "control_datos": 0.85,
        "reproducibilidad": 0.72,
        "apertura": 0.55,
        "encaje_operativo": 0.55,
        "privacidad": True,
        "json": True,
        "licencia": False,
    },
    {
        "nombre": "open_weight_quantized_no_json",
        "calidad": 0.72,
        "latencia": 0.80,
        "coste": 0.92,
        "contexto": 0.55,
        "control_datos": 0.95,
        "reproducibilidad": 0.75,
        "apertura": 0.75,
        "encaje_operativo": 0.62,
        "privacidad": True,
        "json": False,
        "licencia": True,
    },
]

filtros_duros = {
    "privacidad": True,
    "json": True,
    "licencia": True,
}

pesos = {
    "calidad": 0.22,
    "latencia": 0.12,
    "coste": 0.14,
    "contexto": 0.08,
    "control_datos": 0.16,
    "reproducibilidad": 0.12,
    "apertura": 0.10,
    "encaje_operativo": 0.06,
}

def cumple_filtros(modelo):
    return all(modelo[campo] == esperado for campo, esperado in filtros_duros.items())

def puntuacion(modelo):
    return sum(modelo[criterio] * peso for criterio, peso in pesos.items())

candidatos = [m for m in modelos if cumple_filtros(m)]
ordenados = sorted(candidatos, key=puntuacion, reverse=True)

for modelo in ordenados:
    print(modelo["nombre"], round(puntuacion(modelo), 3))

ganador = ordenados[0]
print("decision:", ganador["nombre"])

descartados = [m["nombre"] for m in modelos if not cumple_filtros(m)]
print("descartados_por_filtro:", descartados)

Salida esperada:

open_weight_permissive 0.79
closed_api_mini 0.674
closed_api_frontier 0.625
decision: open_weight_permissive
descartados_por_filtro: ['open_weight_license_propia', 'open_weight_quantized_no_json']

Ahora cambia el peso de calidad a 0.60 y reduce control_datos o apertura. Verás que puede ganar una API cerrada. Ese es el punto: la matriz no “descubre la verdad”; revela tus prioridades. Si cambias prioridades, cambia la decisión. Lo honesto es dejarlo escrito.

Cómo encaja todo

Este mapa conecta la elección de modelos con lo que ya vimos y con lo que viene en el facsímil.

graph TD
    subgraph "Capítulo 4: Model cards y elección"
        CARD["Model card"]
        HF["Card real en Hugging Face"]
        OPENNESS["Apertura real:<br/>API, pesos, código, datos"]
        KPIS["KPIs de selección"]
        FILTERS["Filtros duros"]
        MATRIX["Matriz de decisión"]
        EVAL["Eval propia"]
        COST["Coste total"]
        VERSION["Versión exacta"]
        DECISION["Decisión trazable"]
    end
    subgraph "Viene de capítulos anteriores"
        INTERV["Intervención correcta<br/>(F4C1)"]
        API["Contrato API (F4C2)"]
        TOKENS["Tokens y caché (F4C3)"]
        ARCH["Arquitecturas (F3)"]
    end
    subgraph "Continuidad"
        LOCAL["Modelos locales (F4C5)"]
        CLOUD["Cloud frente a local<br/>(F4C6)"]
        RAG["RAG y embeddings<br/>(F4C7-10)"]
        EVALS["Evals formales (F7)"]
        OPS["Operación (F6)"]
    end

    INTERV --> FILTERS
    API --> CARD
    TOKENS --> COST
    ARCH --> CARD
    CARD --> HF
    HF --> OPENNESS
    OPENNESS --> KPIS
    KPIS --> FILTERS
    HF --> FILTERS
    HF --> EVAL
    FILTERS --> MATRIX
    MATRIX --> EVAL
    EVAL --> DECISION
    COST --> DECISION
    VERSION --> DECISION
    DECISION --> LOCAL
    DECISION --> CLOUD
    DECISION --> RAG
    EVAL --> EVALS
    COST --> OPS

    style CARD fill:#F5F5F5,stroke:#000000,stroke-width:2
    style HF fill:#F5F5F5,stroke:#000000,stroke-width:2
    style OPENNESS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style KPIS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style FILTERS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style MATRIX fill:#F5F5F5,stroke:#000000,stroke-width:2
    style EVAL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style COST fill:#F5F5F5,stroke:#000000,stroke-width:2
    style VERSION fill:#F5F5F5,stroke:#000000,stroke-width:2
    style DECISION fill:#F5F5F5,stroke:#000000,stroke-width:2
    style INTERV stroke-dasharray: 5 5
    style API stroke-dasharray: 5 5
    style TOKENS stroke-dasharray: 5 5
    style ARCH stroke-dasharray: 5 5
    style LOCAL stroke-dasharray: 5 5
    style CLOUD stroke-dasharray: 5 5
    style RAG stroke-dasharray: 5 5
    style EVALS stroke-dasharray: 5 5
    style OPS stroke-dasharray: 5 5

Vocabulario aprendido

Estos términos convierten “me gusta este modelo” en una conversación técnica.

Término	Definición
Model card	Ficha técnica que documenta uso previsto, datos, evaluación, límites y condiciones.
System card	Documento que describe un sistema completo, no solo el modelo aislado.
Benchmark	Prueba estandarizada bajo una metodología concreta.
Eval propia	Conjunto de casos representativos de tu proyecto.
Latencia p95	Tiempo que cubre el 95 por ciento de peticiones.
TCO	Coste total de propiedad: tokens, infraestructura, operación y cambios.
Modelo estable	Versión concreta pensada para producción.
Modelo preview	Versión de avance rápido que puede cambiar antes.
Matriz de decisión	Comparación ponderada de modelos según criterios explícitos.
pipeline_tag	Tarea principal declarada en Hugging Face.
Safetensors	Formato de pesos basado en tensores.
Parámetros activados	Parte del modelo MoE usada para cada token.
Chat template	Plantilla que convierte mensajes en tokens.
model-index	Metadatos de evaluación que Hugging Face puede mostrar de forma estructurada.
Cuantización	Uso de menos bits para reducir memoria y coste operativo.
Namespace	Organización o usuario propietario del repositorio en Hugging Face.
Tokenizer	Componente que convierte texto en tokens y tokens en texto.
Tensor type	Tipo numérico de los tensores publicados o auxiliares.
BF16	Formato de 16 bits usado como baseline de buena calidad cuando cabe en memoria.
F32	Formato de 32 bits, cómodo numéricamente pero caro para servir LLM grandes.
FP8 / INT8	Formatos de 8 bits para reducir memoria y ancho de banda con evaluación obligatoria.
FP4 / INT4	Formatos de 4 bits para local o coste bajo, con mayor riesgo de pérdida de calidad.
MoE	Arquitectura con expertos y enrutamiento por token.
Modelo cerrado	Modelo usado como servicio o producto sin acceso a pesos ni receta completa de entrenamiento.
Pesos abiertos	Pesos descargables o accesibles para servir, ajustar o cuantizar un modelo según licencia.
Código abierto	Código disponible bajo licencia abierta; en IA no implica automáticamente datos, pesos y entrenamiento abiertos.
Open Source AI	Sistema que ofrece libertades de uso, estudio, modificación y compartición junto con la forma preferida para modificarlo.
KPI de selección	Indicador que cambia una decisión de modelo: calidad propia, coste por tarea, p95, licencia, reproducibilidad o control de datos.
GRPO	Variante de optimización por refuerzo usada en trabajos de razonamiento.
temperature	Parámetro que controla variación en la generación.
top_p	Muestreo que limita candidatos por probabilidad acumulada.
Throughput	Capacidad de procesar tokens o peticiones por unidad de tiempo.
Pass@1	Métrica que cuenta si la primera solución pasa el verificador.
0-shot	Evaluación sin ejemplos dentro del prompt.
few-shot	Evaluación con ejemplos dentro del prompt.

Antes de pasar página

En resumen

Elegir modelo es una decisión de ingeniería, producto y operación. La model card no te da una respuesta automática, pero sí una lista de preguntas que evitan elegir por entusiasmo.

Idea fuerza	Detalle
No existe “el mejor modelo” sin contexto.	Existe el modelo adecuado para una tarea, restricciones y evidencia.
La model card se lee como ficha de compatibilidad.	Uso previsto, límites, datos, evaluación, licencia y operación importan.
“Abierto” necesita apellido.	Modelo cerrado, pesos abiertos, licencia propia y Open Source AI no significan lo mismo.
Los pesos abiertos compran control, no magia.	Puedes servir, adaptar o cuantizar según licencia, pero quizá no tienes datos ni receta reproducible.
Los KPIs mandan sobre las etiquetas.	Calidad propia, p95, coste por tarea, licencia, privacidad y reproducibilidad pesan más que el eslogan.
Los benchmarks orientan, no deciden.	Tu eval propia decide si el modelo funciona en tu caso.
La versión exacta importa.	Aliases, previews y modelos retirados pueden romper comparaciones.
El coste real no es solo precio por token.	Latencia, cache, batch, operación y migración entran en la cuenta.
La decisión debe quedar escrita.	Modelo elegido, alternativas, fecha y próxima revisión evitan memoria frágil.

Para saber más

Anthropic. (2026). Models overview. https://platform.claude.com/docs/en/about-claude/models/overview

Anthropic. (2026). Pricing. https://platform.claude.com/docs/en/about-claude/pricing

Gebru, T. et al. (2021). Datasheets for Datasets. https://doi.org/10.1145/3458723

DeepSeek-AI. (2025). DeepSeek-R1. https://huggingface.co/deepseek-ai/DeepSeek-R1

DeepSeek-AI. (2026). deepseek-ai/DeepSeek-V4-Pro. https://huggingface.co/deepseek-ai/DeepSeek-V4-Pro

Docker. (2026). docker model run. https://docs.docker.com/reference/cli/docker/model/run/

Google. (2026). Gemma 4 model overview. https://ai.google.dev/gemma/docs/core

Google. (2026). Gemini API: Models. https://ai.google.dev/gemini-api/docs/models

Google. (2026). Gemini Developer API pricing. https://ai.google.dev/gemini-api/docs/pricing

Hugging Face. (2026). Chat templates. https://huggingface.co/docs/transformers/chat_templating

Hugging Face. (2026). DeepSeek-V4. https://huggingface.co/docs/transformers/model_doc/deepseek_v4

Hugging Face. (2026). Inference Providers. https://huggingface.co/docs/inference-providers/en/index

Hugging Face. (2026). Model Cards. https://huggingface.co/docs/hub/model-cards

Hugging Face. (2026). Quantization. https://huggingface.co/docs/transformers/main_classes/quantization

Hugging Face. (2026). Safetensors. https://huggingface.co/docs/safetensors/en/index

Hoffmann, J. et al. (2022). Training Compute-Optimal Large Language Models. https://doi.org/10.48550/arXiv.2203.15556

Kaplan, J. et al. (2020). Scaling Laws for Neural Language Models. https://doi.org/10.48550/arXiv.2001.08361

Liang, P. et al. (2022). Holistic Evaluation of Language Models. https://arxiv.org/abs/2211.09110

Mitchell, M. et al. (2019). Model Cards for Model Reporting. https://doi.org/10.1145/3287560.3287596

Meta. (2025). Llama 4 Community License Agreement. https://github.com/meta-llama/llama-models/blob/main/models/llama4/LICENSE

Mistral AI. (2025). Introducing Mistral 3. https://mistral.ai/news/mistral-3/

MLCommons. (2026). MLPerf Inference: Datacenter benchmark. https://mlcommons.org/benchmarks/inference-datacenter/

NVIDIA. (2026). Transformer Engine: Low Precision Training. https://docs.nvidia.com/deeplearning/transformer-engine/user-guide/features/low_precision_training/introduction/introduction.html

OpenAI. (2025). Introducing gpt-oss. https://openai.com/index/introducing-gpt-oss/

OpenAI. (2026). Models. https://developers.openai.com/api/docs/models

OpenAI. (2026). OpenAI open-weight models (gpt-oss). https://help.openai.com/en/articles/11870455-openai-open-weight-models-gpt-oss

OpenAI. (2026). Pricing. https://developers.openai.com/api/docs/pricing

Open Source Initiative. (2024). The Open Source AI Definition 1.0. https://opensource.org/ai/open-source-ai-definition

Open Source Initiative. (2026). Open Weights: not quite what you’ve been told. https://opensource.org/ai/open-weights

Qwen Team. (2026). Qwen3.6. https://github.com/QwenLM/Qwen3.6

SGLang. (2026). Welcome to SGLang. https://docs.sglang.io/index.html

Shao, Z. et al. (2024). DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models. https://arxiv.org/abs/2402.03300

vLLM. (2026). OpenAI-Compatible Server. https://docs.vllm.ai/en/latest/serving/openai_compatible_server/

vLLM. (2026). Quantization. https://docs.vllm.ai/en/stable/features/quantization/

Notas

Margaret Mitchell et al. (2019). Model Cards for Model Reporting. Proceedings of the Conference on Fairness, Accountability, and Transparency, 220-229. https://doi.org/10.1145/3287560.3287596. ↩
Timnit Gebru et al. (2021). Datasheets for Datasets. Communications of the ACM, 64(12), 86-92. https://doi.org/10.1145/3458723. ↩
Hugging Face. (2026). Model Cards. https://huggingface.co/docs/hub/model-cards. Consultado el 25 de mayo de 2026. ↩
OpenAI. (2026). Models. https://developers.openai.com/api/docs/models. Consultado el 25 de mayo de 2026. ↩
OpenAI. (2026). Pricing. https://developers.openai.com/api/docs/pricing. Consultado el 25 de mayo de 2026. ↩
Anthropic. (2026). Models overview. https://platform.claude.com/docs/en/about-claude/models/overview. Consultado el 25 de mayo de 2026. ↩
Anthropic. (2026). Pricing. https://platform.claude.com/docs/en/about-claude/pricing. Consultado el 25 de mayo de 2026. ↩
Google. (2026). Gemini API: Models. https://ai.google.dev/gemini-api/docs/models. Consultado el 25 de mayo de 2026. ↩
Google. (2026). Gemini Developer API pricing. https://ai.google.dev/gemini-api/docs/pricing. Consultado el 25 de mayo de 2026. ↩
Percy Liang et al. (2022). Holistic Evaluation of Language Models. https://arxiv.org/abs/2211.09110. ↩
MLCommons. (2026). MLPerf Inference: Datacenter benchmark. https://mlcommons.org/benchmarks/inference-datacenter/. Consultado el 25 de mayo de 2026. ↩
Open Source Initiative. (2024). The Open Source AI Definition 1.0. https://opensource.org/ai/open-source-ai-definition. Consultado el 14 de junio de 2026. ↩
Open Source Initiative. (2026). Open Weights: not quite what you’ve been told. https://opensource.org/ai/open-weights. Consultado el 14 de junio de 2026. ↩
OpenAI. (2026). Models. https://developers.openai.com/api/docs/models. Consultado el 14 de junio de 2026. Anthropic. (2026). Models overview. https://platform.claude.com/docs/en/about-claude/models/overview. Consultado el 14 de junio de 2026. Google. (2026). Gemini API: Models. https://ai.google.dev/gemini-api/docs/models. Consultado el 14 de junio de 2026. ↩
OpenAI. (2025). Introducing gpt-oss. https://openai.com/index/introducing-gpt-oss/. Consultado el 14 de junio de 2026. OpenAI. (2026). OpenAI open-weight models (gpt-oss). https://help.openai.com/en/articles/11870455-openai-open-weight-models-gpt-oss. Consultado el 14 de junio de 2026. Qwen Team. (2026). Qwen3.6. https://github.com/QwenLM/Qwen3.6. Consultado el 14 de junio de 2026. Mistral AI. (2025). Introducing Mistral 3. https://mistral.ai/news/mistral-3/. Consultado el 14 de junio de 2026. DeepSeek-AI. (2025). DeepSeek-R1. https://huggingface.co/deepseek-ai/DeepSeek-R1. Consultado el 14 de junio de 2026. ↩
Meta. (2025). Llama 4 Community License Agreement. https://github.com/meta-llama/llama-models/blob/main/models/llama4/LICENSE. Consultado el 14 de junio de 2026. Google. (2026). Gemma 4 model overview. https://ai.google.dev/gemma/docs/core. Consultado el 14 de junio de 2026. ↩
Hugging Face. (2026). Model Cards. https://huggingface.co/docs/hub/model-cards. Consultado el 14 de junio de 2026. ↩
Jared Kaplan et al. (2020). Scaling Laws for Neural Language Models. https://doi.org/10.48550/arXiv.2001.08361. ↩
Jordan Hoffmann et al. (2022). Training Compute-Optimal Large Language Models. https://doi.org/10.48550/arXiv.2203.15556. ↩
DeepSeek-AI. (2026). deepseek-ai/DeepSeek-V4-Pro. https://huggingface.co/deepseek-ai/DeepSeek-V4-Pro. Consultado el 25 de mayo de 2026. ↩
Hugging Face. (2026). DeepSeek-V4. https://huggingface.co/docs/transformers/model_doc/deepseek_v4. Consultado el 25 de mayo de 2026. ↩
Hugging Face. (2026). Safetensors. https://huggingface.co/docs/safetensors/en/index. Consultado el 25 de mayo de 2026. ↩
NVIDIA. (2026). Transformer Engine: Low Precision Training. https://docs.nvidia.com/deeplearning/transformer-engine/user-guide/features/low_precision_training/introduction/introduction.html. Hugging Face. (2026). Quantization. https://huggingface.co/docs/transformers/main_classes/quantization. vLLM. (2026). Quantization. https://docs.vllm.ai/en/stable/features/quantization/. Consultados el 25 de mayo de 2026. ↩
Zhihong Shao et al. (2024). DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models. https://arxiv.org/abs/2402.03300. ↩
Hugging Face. (2026). Chat templates. https://huggingface.co/docs/transformers/chat_templating. Consultado el 25 de mayo de 2026. ↩
vLLM. (2026). OpenAI-Compatible Server. https://docs.vllm.ai/en/latest/serving/openai_compatible_server/. Consultado el 25 de mayo de 2026. SGLang. (2026). Welcome to SGLang. https://docs.sglang.io/index.html. Consultado el 25 de mayo de 2026. ↩
Docker. (2026). docker model run. https://docs.docker.com/reference/cli/docker/model/run/. Consultado el 25 de mayo de 2026. ↩
Hugging Face. (2026). Inference Providers. https://huggingface.co/docs/inference-providers/en/index. Consultado el 25 de mayo de 2026. ↩

Capítulo 05

Facsímil 4 · La caja de herramientas

Capítulo 05: Modelos locales: Ollama, LM Studio, GGUF y cuantización

Cuando el modelo se queda en tu máquina

Hay una frase que suena sencilla: “lo corremos en local”. Parece que significa privacidad, control, coste bajo y ausencia de dependencias externas. A veces es verdad. Otras veces significa otra cosa: descargar un fichero enorme, pelear con memoria, descubrir que el contexto no cabe, que el modelo responde lento, que la cuantización cambia el comportamiento o que la API local está expuesta de una forma que nadie revisó.

Venimos del capítulo 04, donde aprendimos a leer model cards. Ahora bajamos un nivel: qué ocurre cuando eliges un modelo descargable y quieres ejecutarlo tú. Ya no basta con preguntar si el modelo es bueno. Hay que preguntar si cabe, si responde a tiempo, si el runtime entiende su formato, si la licencia encaja, si la calidad tras cuantizar sigue siendo suficiente y si puedes medirlo sin engañarte.

La idea central es esta: un modelo local no es solo un modelo; es la suma de pesos, formato, runtime, hardware, configuración, API, licencia y evaluación.

Estado del arte con fecha de corte

Fecha de corte: 10 de junio de 2026.
Fuentes consultadas ese día: documentación oficial de Ollama, LM Studio, Hugging Face Hub sobre GGUF, repositorio de llama.cpp y papers de cuantización LLM.int8, SmoothQuant, GPTQ, AWQ, QLoRA y cuantización entera clásica.

Lo estable es el mecanismo: descargar pesos, elegir formato, cargar en un runtime, repartir memoria entre CPU/GPU, configurar contexto y generación, exponer una API si hace falta, medir calidad y latencia. Lo cambiante son nombres de modelos, soporte de GPU, formatos concretos, variantes de cuantización, límites de contexto y compatibilidad de cada aplicación.

Fuente	Qué aporta	Qué decisión permite tomar
Ollama API.¹	API local por defecto, endpoints, librerías y compatibilidad básica.	Saber si tu app puede llamar al modelo como servicio local.
Ollama Modelfile.²	`FROM`, `PARAMETER`, `TEMPLATE`, `SYSTEM`, `ADAPTER`, `LICENSE` y `MESSAGE`.	Saber qué parte de la conducta se fija en la definición del modelo.
Ollama context length.³	Relación entre VRAM, contexto por defecto y memoria necesaria.	No subir contexto sin calcular memoria.
Ollama hardware support.⁴	Soporte de NVIDIA, AMD, Metal y Vulkan.	Comprobar si tu máquina acelera o cae a CPU.
Ollama OpenAI compatibility.⁵	Compatibilidad con parte de la API de OpenAI.	Reutilizar clientes existentes sabiendo que “compatible” no significa idéntico.
LM Studio basics.⁶	Flujo de descarga y ejecución local de modelos con pesos accesibles.	Entender qué se descarga y qué significa correr un modelo desde una UI.
LM Studio REST API.⁷	API nativa local y endpoints compatibles con OpenAI y Anthropic.	Decidir si LM Studio será UI, servidor local o ambas cosas.
LM Studio load.⁸	Carga con contexto, GPU offload, TTL y estimación de memoria.	Probar si un modelo cabe antes de cargarlo.
Hugging Face GGUF.⁹	GGUF como formato con tensores y metadatos; visor de metadata y tipos de cuantización.	Leer un `.gguf` como fichero técnico, no como etiqueta comercial.
llama.cpp.¹⁰	Runtime C/C++ base del ecosistema GGUF.	Entender de dónde vienen muchas piezas de Ollama, LM Studio y herramientas locales.
LLM.int8.¹¹	Cuantización 8-bit cuidando valores atípicos en LLMs grandes.	Entender por qué bajar bits no es solo redondear números.
SmoothQuant.¹²	Reescalado de pesos y activaciones para cuantización post-entrenamiento.	Entender por qué activaciones y pesos se tratan juntos en algunos despliegues.
GPTQ.¹³	Cuantización post-entrenamiento de pesos usando información aproximada de segundo orden.	Leer GPTQ como método de compresión medible, no como sufijo decorativo.
AWQ.¹⁴	Cuantización orientada a pesos importantes según activaciones.	Saber por qué algunas cuantizaciones conservan mejor calidad que otras.
QLoRA.¹⁵	Fine-tuning eficiente sobre modelos cuantizados de 4 bits.	Separar servir un modelo cuantizado de ajustar adaptadores sobre una base cuantizada.
Cuantización entera clásica.¹⁶	Base de cuantización para inferencia eficiente con enteros.	Recordar que cuantizar es aproximar cálculo, no comprimir un ZIP.

La revisión del 10 de junio añade un matiz importante: “uso Ollama” ya no equivale necesariamente a “todo corre en mi portátil”. Ollama documenta Cloud como una forma de usar modelos remotos grandes con herramientas locales, mientras que la API local sigue viviendo por defecto en localhost:11434.¹⁷ LM Studio documenta un servidor local que puede exponerse en la máquina o en red y que ofrece API nativa, compatibilidad OpenAI y compatibilidad Anthropic.¹⁸ llama.cpp, por su parte, documenta llama-server con endpoints compatibles, batching, métricas y salidas restringidas por schema.¹⁹

La consecuencia práctica es clara: cuando digas “modelo local”, documenta dónde se ejecuta realmente, qué puerto abre, si acepta tráfico de red, qué autenticación tiene, qué contexto reserva, qué cuantización usa, qué plantilla de chat aplica y qué versión del runtime lo sirve. La diferencia entre una práctica de clase y un incidente de seguridad puede ser una bandera de host mal puesta.

Qué no es correr un modelo en local

Correr un modelo en local no significa automáticamente que sea privado en sentido fuerte. Si descargas pesos desde un repositorio externo, ejecutas una app, expones un puerto, instalas extensiones o conectas herramientas, sigues teniendo superficie técnica que revisar. Local reduce ciertos problemas de envío de datos a un proveedor remoto, pero no elimina los problemas de licencia, procedencia de ficheros, logs, permisos, backups o red.

Tampoco significa “gratis”. Dejas de pagar por token a una API, pero pagas en hardware, electricidad, tiempo de instalación, memoria, mantenimiento, actualizaciones y evaluación. Si un portátil tarda 40 segundos en responder a una tarea que una API resuelve en 2 segundos por céntimos, puede que local no sea más barato para ese flujo.

Y no significa “igual que el modelo original, pero comprimido”. Un GGUF Q4 no es el mismo objeto operativo que un checkpoint BF16. Puede ser suficientemente bueno, pero hay que demostrarlo con casos propios. Si no mides, no has elegido cuantización; has elegido esperanza.

Qué sí es un modelo local

Un modelo local es un sistema de inferencia donde tú controlas la máquina que carga los pesos. Esa frase es más precisa que “lo tengo en mi ordenador”. Controlar la máquina implica decidir formato, runtime, memoria, configuración, API, permisos y actualización.

Pieza	Qué es	Qué pregunta responde
Pesos	Ficheros con matrices aprendidas durante entrenamiento o ajuste.	¿Qué modelo estoy ejecutando realmente?
Formato	GGUF, safetensors, ONNX, TensorRT u otro contenedor.	¿Qué runtime puede abrirlo?
Runtime	Ollama, LM Studio, llama.cpp, vLLM, SGLang, Transformers u otro.	¿Quién gestiona memoria y generación?
Hardware	CPU, GPU, NPU, VRAM, RAM, memoria unificada.	¿Cabe y a qué velocidad responde?
Configuración	Contexto, cuantización, GPU offload, temperatura, top-p, stops.	¿Cómo se comporta en cada llamada?
API local	Endpoint HTTP o SDK para llamarlo desde una app.	¿Cómo lo integro en un producto o notebook?
Evaluación	Casos propios con calidad, latencia y memoria.	¿Sirve para mi tarea, no solo para una demo?

La pregunta profesional no es “¿puedo ejecutarlo?”. Es: ¿puedo ejecutarlo con calidad, latencia, memoria, licencia y mantenimiento aceptables?

La pila local por dentro

Un modelo local atraviesa una pila. Si una pieza falla, el resultado final falla aunque el modelo sea bueno.

Capa	Qué mide	Qué aporta	Qué sería razonable
Licencia	Permisos de uso, modificación y redistribución.	Reduce riesgo jurídico y de producto.	Leer licencia del modelo y de variantes derivadas antes de automatizar.
Procedencia	Quién publicó el fichero y con qué historial.	Evita comparar copias, forks o variantes sin saberlo.	Guardar repo, archivo exacto, hash o commit cuando sea posible.
Formato	Cómo están empaquetados pesos y metadatos.	Determina runtime compatible.	GGUF para llama.cpp/Ollama/LM Studio; safetensors para ecosistema Transformers.
Bits por peso	Memoria aproximada de pesos.	Estima si cabe y cuánta calidad podrías perder.	BF16 como referencia; Q4/Q5 si necesitas local barato; Q8 si tienes memoria.
Contexto	Tokens que entran en memoria.	Permite tareas largas, pero aumenta KV cache.	No subir contexto sin medir VRAM/RAM y TTFT.
GPU offload	Capas o partes movidas a GPU.	Reduce latencia si cabe en VRAM.	Usar GPU para capas máximas sin expulsar KV cache ni forzar intercambio lento.
API	Contrato de integración.	Permite usarlo desde una app.	Probar streaming, errores, JSON y límites antes de cambiar proveedor.
Observabilidad	Logs, tiempo, tokens/s, memoria, errores.	Permite saber qué pasa cuando algo va lento.	Medir p50/p95, TTFT, tokens/s y memoria por caso.

La segunda pasada obligatoria es preguntarse qué falta. En un primer intento solemos mirar solo “modelo y cuantización”. Falta comprobar licencia, procedencia, hash, contexto real, plantilla de chat, memoria de KV cache, parámetros de muestreo, endpoint, exposición de red, eval propia y plan de actualización. Si no está escrito, no existe.

La tercera pasada es rehacer la decisión como si tuviera que explicarse en una reunión: “elegimos este modelo local porque cabe con esta cuantización, responde en este p95, conserva esta calidad frente al baseline, usa esta licencia, se integra por esta API y tiene esta alternativa si falla”.

Memoria: la cuenta que evita la fantasía

Antes de descargar nada, haz una estimación. No será perfecta, pero evita decisiones imposibles.

La memoria mínima de pesos se aproxima así:

M_{\text{pesos}} \approx N_{\text{parametros}} \cdot \frac{b_{\text{peso}}}{8}

Símbolo	Significado	Ejemplo
$M_{\text{pesos}}$	Memoria aproximada ocupada solo por pesos.	Un 7B Q4 ronda 3,5 GB antes de sobrecostes.
$N_{\text{parametros}}$	Número de parámetros del modelo.	7B, 14B, 32B, 70B.
$b_{\text{peso}}$	Bits por peso tras cuantizar.	16, 8, 5, 4, 3.

Pero un modelo cargado no son solo pesos.

Ejemplo de fórmula. Una cuenta más honesta es:

M_{\text{total}} \approx M_{\text{pesos}} + M_{\text{KV}} + M_{\text{runtime}} + M_{\text{margen}}

Símbolo	Significado	Por qué importa
$M_{\text{KV}}$	Memoria de la KV cache.	Crece con contexto, capas, batch y dimensiones de atención.
$M_{\text{runtime}}$	Memoria del programa, buffers y kernels.	No aparece en el tamaño del fichero.
$M_{\text{margen}}$	Colchón para sistema operativo, UI, navegador, otros procesos y picos.	Si no hay margen, el sistema intercambia memoria y se vuelve lento.

Regla de bolsillo para pesos:

Modelo denso	BF16/F16	Q8/INT8	Q5 aprox.	Q4 aprox.	Lectura práctica
3B	~6 GB	~3 GB	~1,9 GB	~1,5 GB	Buen candidato para portátiles modestos.
7B	~14 GB	~7 GB	~4,4 GB	~3,5 GB	Punto de entrada local serio.
14B	~28 GB	~14 GB	~8,8 GB	~7 GB	Empieza a exigir GPU/RAM holgada.
32B	~64 GB	~32 GB	~20 GB	~16 GB	Normalmente workstation o servidor.
70B	~140 GB	~70 GB	~44 GB	~35 GB	Multi-GPU, mucha RAM o paciencia.

Lo adecuado depende de la tarea:

Situación	Punto de partida razonable	Por qué
Notebook, aprendizaje, privacidad personal	3B-8B en Q4/Q5.	Cabe mejor y permite experimentar.
Clasificación o extracción sencilla	7B-14B Q4/Q5 con salida estructurada.	Calidad suficiente si la tarea está bien acotada.
Código, razonamiento o agente local	14B-32B si cabe, comparado contra API.	Estos casos sufren más con modelos pequeños.
Producción con usuarios simultáneos	Runtime de servidor, medición p95 y modelo alternativo.	El problema ya no es una conversación aislada.
Datos sensibles con restricción fuerte	Local o entorno privado con auditoría.	El criterio principal es control, no solo calidad.

La frase “este modelo cabe” debe significar algo concreto: cabe con este contexto, esta cuantización, este batch, esta GPU offload, este margen de memoria y esta calidad medida.

Ollama: cómodo no significa invisible

Ollama es una forma práctica de ejecutar modelos y hablar con ellos por CLI, app o API. La documentación oficial indica que su API local se sirve por defecto en http://localhost:11434/api, y que también ofrece librerías oficiales para Python y JavaScript. Esa comodidad es valiosa porque permite convertir un modelo local en un servicio consumible por scripts, notebooks o aplicaciones.

Lo importante es no tratar Ollama como una caja opaca. Ollama decide cómo cargar el modelo, qué contexto usar, qué parámetros aplicar y cómo exponer endpoints. Debes saber leer esas decisiones.

Término	Qué mide o controla	Ejemplo	Decisión práctica
`ollama run`	Conversación rápida por terminal.	`ollama run gemma3`	Bien para probar; no basta para evaluar producto.
API local	Contrato HTTP local.	`POST /api/generate` o `POST /api/chat`.	Útil para integrar en Python, JS o una app interna.
OpenAI compatibility	Adaptación parcial a clientes existentes.	`/v1/chat/completions`.	Reutiliza SDKs, pero valida parámetros soportados y errores.
`Modelfile`	Receta reproducible de modelo, plantilla y parámetros.	`FROM llama3.2`, `PARAMETER num_ctx 4096`, `SYSTEM ...`.	No guardes solo “uso llama”; guarda el Modelfile.
`FROM`	Modelo base o fichero GGUF/safetensors.	`FROM ./modelo.gguf`.	Define qué pesos cargas realmente.
`PARAMETER num_ctx`	Tamaño de contexto.	`num_ctx 4096`.	Más contexto usa más memoria; no es gratis.
`TEMPLATE`	Plantilla de prompt.	Formato de roles y separadores.	Si está mal, el modelo parece peor.
`ADAPTER`	Adaptador LoRA/QLoRA.	`ADAPTER ./adapter.gguf`.	Solo encaja si base y adaptador corresponden.
`LICENSE`	Texto legal asociado.	Licencia incluida en el Modelfile.	Necesario si empaquetas o compartes.
`ollama ps`	Modelos cargados, procesador y contexto.	`100% GPU`, `CONTEXT 65536`.	Comprueba si de verdad está en GPU y qué contexto usa.

Ollama documenta valores por defecto de contexto según VRAM: por debajo de 24 GiB, 4k; entre 24 y 48 GiB, 32k; desde 48 GiB, 256k. También recomienda contextos altos para tareas como web search, agentes y herramientas de código. La lectura correcta no es “sube contexto a 64k siempre”, sino “si la tarea lo requiere, calcula memoria y verifica ollama ps”.

Situación concreta: quieres usar un modelo local para revisar un repositorio. Si el agente mete muchos ficheros en contexto, 4k no alcanza. Pero subir a 64k puede llenar VRAM. La solución profesional no es elegir al azar: mide cuántos tokens entran, decide qué se recupera, sube contexto solo si aporta y comprueba TTFT y p95.

LM Studio: visual, local y medible

LM Studio entra por otro camino: hace cómoda la experiencia visual de buscar, descargar, cargar y probar modelos locales. Su documentación recuerda una distinción importante: para correr local necesitas acceso a los pesos, normalmente en formatos como .gguf o .safetensors.

Además de UI, LM Studio ofrece API REST local, endpoints compatibles con OpenAI y Anthropic, y CLI. En su REST API v1 aparecen endpoints como /api/v1/chat, /api/v1/models, /api/v1/models/load, /api/v1/models/unload y /api/v1/models/download. Eso convierte LM Studio en algo más que una app de chat: puede ser un servidor local de desarrollo.

Término	Qué mide o controla	Ejemplo	Decisión práctica
Modelo descargado	Fichero local con pesos.	Un `.gguf` de Qwen, Mistral o Gemma.	Comprueba licencia, tamaño, cuantización y procedencia.
`lms load`	Cargar un modelo en memoria.	`lms load <model_key>`.	Separa descargar de cargar; no todo lo descargado está activo.
`--context-length`	Tokens de contexto al cargar.	`--context-length 8192`.	Mide memoria y calidad con ese contexto, no con el máximo teórico.
`--gpu`	Proporción de offload a GPU.	`--gpu 0.5`, `--gpu max`, `--gpu off`.	Si no usas GPU, la experiencia puede cambiar mucho.
`--estimate-only`	Estimar memoria sin cargar.	`lms load --estimate-only <model_key>`.	Úsalo antes de romper la sesión por falta de memoria.
TTL	Descargar de memoria tras inactividad.	`--ttl 3600`.	Evita dejar modelos ocupando RAM/VRAM todo el día.
API nativa	Endpoint local propio.	`/api/v1/chat`.	Útil si quieres capacidades específicas de LM Studio.
OpenAI-compatible	Endpoint familiar para clientes existentes.	`/v1/chat/completions`.	Valida streaming, structured output y parámetros.

LM Studio también permite configurar parámetros de inferencia, como temperature, maxTokens y topP, y parámetros de carga, como longitud de contexto y GPU offload. La separación es crucial: temperature cambia cómo se elige el siguiente token; contextLength cambia cuánta memoria reserva el sistema al cargar.

Situación concreta: en una clase o equipo, LM Studio es excelente para enseñar porque el lector ve el modelo, el fichero, la carga, la conversación y el servidor. En un backend repetible, quizá prefieras Ollama o llama.cpp directamente. La decisión no es “cuál mola más”, sino qué necesitas: UI, script, servidor, compatibilidad, trazabilidad o control fino.

Una prueba local que sí se puede repetir

Una prueba local no debería consistir en abrir una ventana, hacer una pregunta y decidir por impresión. Eso sirve para orientarse, pero no para elegir. Una prueba mínima debe dejar huella: qué modelo era, qué fichero, qué cuantización, qué runtime, qué contexto, qué máquina, qué prompt, qué salida y qué métricas.

Con Ollama, una llamada mínima a la API local puede parecer así:

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [
      {"role": "system", "content": "Responde en español claro y devuelve JSON válido."},
      {"role": "user", "content": "Clasifica esta incidencia: no puedo entrar al campus virtual."}
    ],
    "stream": false,
    "options": {
      "temperature": 0.2,
      "num_ctx": 4096
    }
  }'

Con LM Studio en modo compatible con OpenAI, una llamada de integración puede tener esta forma:

curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "modelo-local-cargado",
    "messages": [
      {"role": "system", "content": "Extrae campos con precisión. Si falta un dato, usa null."},
      {"role": "user", "content": "Factura 2026-05: total 184,30 EUR; proveedor Norte S.L."}
    ],
    "temperature": 0.1,
    "max_tokens": 300
  }'

Lo importante no es copiar esos comandos tal cual, sino entender qué contrato crean:

Campo	Qué controla	Qué anotar
`model`	Identificador que el runtime resuelve a pesos concretos.	Nombre exacto, origen y, si es posible, hash o ruta.
`messages`	Plantilla de conversación convertida a tokens.	System prompt, user prompt y versión del caso de prueba.
`temperature`	Aleatoriedad de muestreo.	Valor fijo durante eval; si cambia, cambia la comparación.
`num_ctx` / contexto	Ventana que reserva memoria.	Contexto usado, no el máximo anunciado.
`max_tokens`	Límite de salida.	Evita comparar respuestas truncadas con completas.
`stream`	Si la salida llega por partes.	Afecta percepción de latencia y forma de medir TTFT.

Una tabla de evaluación mínima tendría estas columnas:

Columna	Qué significa	Por qué importa
`fecha`	Día de la prueba.	Los modelos, runtimes y drivers cambian.
`runtime`	Ollama, LM Studio, llama.cpp, vLLM, etc.	El mismo fichero puede rendir distinto.
`version_runtime`	Versión instalada.	Una actualización puede cambiar memoria o salida.
`modelo_origen`	Repositorio o proveedor de pesos.	Evita comparar copias distintas.
`fichero`	Nombre exacto del GGUF/safetensors.	Incluye cuantización y variante.
`contexto`	Tokens de contexto configurados.	Cambia memoria y a veces calidad.
`caso_id`	Identificador del caso de prueba.	Permite repetir y depurar.
`ok_formato`	Si cumple contrato de salida.	Importa tanto como “suena bien”.
`ok_contenido`	Si la respuesta es correcta.	Métrica principal de utilidad.
`ttft_s`	Tiempo hasta primer token.	Mide sensación inicial de respuesta.
`tokens_s`	Tokens de salida por segundo.	Mide velocidad de generación.
`memoria_pico_gb`	Pico observado de RAM/VRAM.	Detecta candidatos que caben sin margen real.
`observacion`	Fallo o matiz concreto.	Ayuda a saber qué mejorar.

La regla profesional es comparar siempre contra algo: contra una API fuerte, contra Q8, contra otro runtime o contra el mismo modelo con menos contexto. Un resultado aislado no dice si el sistema es bueno; solo dice que funcionó una vez.

Medir latencia y velocidad sin engañarse

En local se habla mucho de “va rápido” o “va lento”. Para que esa frase sirva, hay que separarla en métricas.

TTFT = t_{\text{primer\ token}} - t_{\text{envio}}

\text{tokens/s} = \frac{N_{\text{tokens\ salida}}}{t_{\text{fin}} - t_{\text{primer\ token}}}

p95 = \text{percentil}_{95}(\text{latencias})

Métrica	Qué aporta	Qué valor es adecuado
TTFT	Cuánto espera la persona hasta ver que algo empieza.	Bajo si hay interacción humana; menos crítico en batch.
Tokens/s	Ritmo de generación una vez arrancó.	Depende de longitud de salida; compáralo en los mismos casos.
Latencia total	Tiempo desde petición hasta respuesta completa.	Importa cuando la salida debe estar cerrada para continuar.
p95	Cómo se comporta el sistema en casos lentos.	Más útil que el promedio si hay usuarios reales.
Memoria pico	Máximo de RAM/VRAM observado.	Debe dejar margen; si va al límite, el sistema será frágil.
Tasa de formato válido	Porcentaje de salidas parseables.	Crucial en JSON, SQL, extracción o agentes.

Ejemplo: un modelo que da 35 tokens/s puede parecer mejor que otro de 22 tokens/s. Pero si el primero falla JSON en 8 de cada 100 casos y el segundo falla en 1, el segundo puede ser mejor para una integración. La métrica adecuada depende de qué duele más: espera, coste, errores de formato, memoria o mantenimiento.

GGUF: el fichero no es el modelo, es el contenedor operativo

GGUF aparece en muchas páginas de modelos y causa una confusión frecuente. No es una arquitectura. No es una familia. No es una licencia. Es un formato de fichero pensado para guardar pesos y metadatos de forma útil para runtimes como llama.cpp.

Hugging Face describe GGUF como un formato binario optimizado para carga y guardado eficiente de modelos; a diferencia de formatos solo de tensores, GGUF incorpora tensores y metadatos estandarizados. Además, el Hub ofrece visor de metadatos y tipos de tensor para archivos GGUF.

Dato en un GGUF	Qué mide	Qué aporta	Qué sería razonable
Arquitectura	Familia que espera el runtime.	Saber si puede cargarse.	No forzar un runtime que no soporta esa arquitectura.
Contexto declarado	Longitud máxima o recomendada.	Límite operativo inicial.	Probar contexto real, no solo máximo.
Tipo de cuantización	Bits y método de aproximación.	Memoria y calidad esperada.	Q4/Q5 para equilibrio, Q8 para calidad si cabe, Q2/Q3 solo con eval fuerte.
Tensor info	Nombre, forma y precisión de tensores.	Auditar qué hay dentro.	Revisar si algo no cuadra entre card y fichero.
Tokenizer metadata	Cómo partir texto.	Evitar prompts mal codificados.	No mezclar tokenizer de otro modelo.
Chat template	Formato de conversación.	Convertir roles a tokens correctos.	Probar con plantilla del modelo, no inventarla.

Nombres como Q4_K_M, Q5_K_M o Q8_0 no son decoración. Indican una estrategia de cuantización. Aun así, no hay que tratarlos como una escala universal de calidad. Dos modelos distintos pueden perder capacidades distintas al pasar a Q4. Una tarea de resumen puede sobrevivir bien; una tarea de código o extracción exacta puede sufrir más.

Variante orientativa	Qué aporta	Cuándo probarla	Qué comparar
F16/BF16	Referencia de más calidad y más memoria.	Si tienes RAM/VRAM suficiente.	Sirve como baseline contra cuantizadas.
Q8	Cerca de calidad alta con menos memoria.	Si Q4 falla o la tarea es delicada.	Calidad frente a F16/BF16 y latencia.
Q5	Equilibrio entre memoria y calidad.	Buen primer candidato si Q4 queda justo.	Errores en casos difíciles.
Q4	Mucho ahorro de memoria.	Portátiles, demos, prototipos y tareas acotadas.	Formato, razonamiento, código y alucinaciones.
Q2/Q3	Ahorro agresivo.	Solo si la restricción de memoria manda.	Degradación fuerte con eval propia.

La pregunta “¿qué cuantización uso?” debería reformularse así: “¿cuál es la menor cuantización que mantiene calidad suficiente en mis casos, con latencia y memoria aceptables?”.

Cuantizar no es comprimir un archivo

Cuantizar significa aproximar números. En un modelo, los pesos son valores numéricos. Si los representas con menos bits, ocupan menos y pueden moverse más rápido, pero pierdes resolución. La cuestión es dónde se pierde, cuánto se pierde y si tu tarea lo nota.

La idea matemática mínima es esta. Un peso real $x$ , que antes vivía como FP16, BF16 o FP32, se guarda como un entero pequeño $q$ . Para volver a usarlo, el runtime reconstruye una aproximación $\hat{x}$ :

q = \operatorname{clip}\left(\operatorname{round}\left(\frac{x}{s}\right) + z,\ q_{\min},\ q_{\max}\right)

\hat{x} = s \cdot (q - z)

Símbolo	Qué significa	Qué aporta
$x$	Valor original del peso o activación.	Referencia de calidad.
$q$	Entero almacenado con pocos bits.	Ahorro de memoria y movimiento de datos.
$s$	Escala de cuantización.	Dice cuánto vale un paso entero en el mundo real.
$z$	Zero-point.	Permite desplazar el cero en cuantización asimétrica.
$q_{\min}, q_{\max}$	Rango posible del entero.	En 4 bits hay muchos menos valores que en 8 o 16.
$\hat{x}$	Valor reconstruido.	Lo que realmente usa el cálculo tras cuantizar.

Si cuantizas a 4 bits, cada valor no puede tomar infinitos matices: solo hay 16 códigos posibles por grupo. El truco está en elegir bien la escala, el grupo y qué tensores reciben más precisión. Por eso dos ficheros Q4 pueden comportarse diferente aunque ambos “sean Q4”.

La pérdida local de información se puede mirar así:

\epsilon_W = \frac{\lVert W - \hat{W} \rVert_2}{\lVert W \rVert_2}

Pero esa fórmula no basta para decidir. Un error pequeño en una matriz puede afectar mucho a una tarea de código, y un error mayor puede ser tolerable en una tarea de clasificación sencilla. La calidad final no se certifica mirando solo el error de pesos; se certifica con casos de uso.

Qué se puede cuantizar

No todo se cuantiza igual. Esta distinción evita muchas confusiones:

Qué se cuantiza	Qué cambia	Qué aporta	Riesgo
Pesos	Se guardan matrices del modelo con menos bits.	Reduce tamaño del fichero y memoria de carga.	Puede degradar razonamiento, código o extracción fina.
Activaciones	Se aproximan valores intermedios durante inferencia.	Puede acelerar cálculo si el hardware lo aprovecha.	Más delicado: cambia señales que dependen de cada entrada.
KV cache	Se guarda la memoria de atención con menos precisión.	Ahorra mucho en contextos largos.	Puede empeorar recuperación de detalles lejanos.
Adaptadores	Se ajustan piezas pequeñas sobre una base cuantizada.	Permite fine-tuning barato con QLoRA.	No convierte una base pobre en una buena por sí solo.
Embeddings	Se reducen vectores de representación.	Ahorra almacenamiento y búsqueda.	Puede afectar ranking semántico y vecinos cercanos.

En modelos locales de escritorio, muchas veces estás usando cuantización de pesos. Eso no significa que todas las operaciones internas sean enteras, ni que las activaciones estén cuantizadas, ni que el runtime use la GPU de la misma forma que un servidor optimizado. Esta frase es importante: peso cuantizado no significa inferencia entera de punta a punta.

Granularidad: dónde se decide el daño

Una misma cuantización de 4 bits puede ser muy distinta según cuántos pesos comparten escala.

Granularidad	Qué ocurre	Ventaja	Coste
Por tensor	Toda la matriz comparte escala.	Muy simple y pocos metadatos.	Mala si hay valores con rangos muy distintos.
Por canal o fila	Cada fila/canal tiene su escala.	Mejor preservación de matrices grandes.	Más metadatos.
Por grupo o bloque	Grupos de 32, 64, 128 u otro tamaño comparten escala.	Buen equilibrio en LLMs locales.	Más complejo; cada formato lo concreta distinto.
Mixta por tensor	Algunos tensores reciben más bits que otros.	Protege partes sensibles del modelo.	El nombre del fichero ya no cuenta toda la historia.

La regla práctica: grupos más pequeños suelen conservar mejor la señal, pero añaden metadatos y complejidad. En GGUF, los sufijos como Q4_K_M resumen una receta; no sustituyen leer metadata, card del cuantizador y evaluación.

Familias importantes

LLM.int8 mostró que en LLMs grandes no basta con pasar todo a 8 bits de forma ingenua: hay valores atípicos que conviene tratar con cuidado. SmoothQuant redistribuye dificultad entre activaciones y pesos para hacer más viable la cuantización de activaciones. GPTQ propuso una ruta de cuantización post-entrenamiento para modelos generativos usando información aproximada de segundo orden. AWQ se fijó en qué pesos importan más según activaciones para preservar mejor comportamiento. QLoRA popularizó ajustar modelos usando una base cuantizada de 4 bits con adaptadores entrenables. La cuantización clásica de redes ya venía de antes, pero los LLMs hicieron visible que no todos los pesos duelen igual.

Método o familia	Qué cambia	Qué aporta	Qué prueba haría
INT8 / LLM.int8	Baja a 8 bits cuidando valores atípicos.	Menos memoria con pérdida pequeña si se hace bien.	Comparar exactitud y formato contra BF16.
SmoothQuant	Reescala pesos y activaciones antes de cuantizar.	Hace más manejable cuantizar activaciones.	Medir latencia real en el runtime elegido.
GPTQ	Cuantización post-entrenamiento de pesos.	Ficheros pequeños y rápidos en ciertos runtimes.	Probar código, matemáticas y extracción.
AWQ	Conserva pesos relevantes según activaciones.	Buen equilibrio para despliegue eficiente.	Comparar frente a GPTQ/GGUF de mismo tamaño.
GGUF Q4/Q5/Q8	Recetas prácticas para llama.cpp y derivados.	Uso local amplio y sencillo.	Medir calidad por tarea, no por sufijo.
QLoRA / NF4	Fine-tuning eficiente sobre base cuantizada.	Ajustar comportamiento con mucha menos memoria.	No confundir ajustar con servir un modelo cuantizado.

Qué significa elegir Q4, Q5 o Q8

Los bits por peso reducen memoria, pero no de forma aislada. Hay metadatos, escalas, grupos y tensores con formatos distintos. Aun así, como intuición:

Opción	Lectura técnica	Cuándo suele encajar	Cuándo sospechar
BF16/F16	Baseline de alta fidelidad.	Evaluación de referencia y tareas delicadas.	Si no cabe o la latencia es inaceptable.
Q8	Aproximación conservadora.	Cuando quieres ahorrar memoria sin perder demasiado.	Si el ahorro no basta para tu máquina.
Q6/Q5	Punto intermedio.	Código, extracción y razonamiento moderado si Q4 falla.	Si el modelo sigue quedando lento o justo de memoria.
Q4	Compromiso local popular.	Chat, resumen, clasificación acotada, aprendizaje y prototipos.	Si hay errores de formato, cálculo, SQL o instrucciones largas.
Q3/Q2	Compromiso agresivo.	Solo cuando la máquina manda y la tarea tolera pérdida.	En casi todo lo que requiera precisión sostenida.

Un ejemplo concreto: si un 7B Q4 cabe y responde fluido, puede ser buena elección para resumir tickets internos. Si el mismo modelo debe devolver JSON contractual con importes, fechas y campos obligatorios, Q5, Q8 o una API fuerte pueden ser más razonables. No porque Q4 sea “malo”, sino porque el coste del error cambió.

Cómo evaluar una cuantización

Ejemplo de fórmula. Una evaluación mínima compara al menos dos candidatos sobre los mismos casos:

\Delta_{\text{calidad}} = \text{score}_{\text{baseline}} - \text{score}_{\text{cuantizado}}

\text{ahorro} = 1 - \frac{M_{\text{cuantizado}}}{M_{\text{baseline}}}

Prueba	Qué detecta	Señal de alarma
Formato exacto	Si respeta JSON, CSV, SQL o campos obligatorios.	Respuestas bonitas pero no parseables.
Casos largos	Si conserva información al crecer el contexto.	Olvida restricciones del principio.
Cálculo simple	Si degrada operaciones numéricas.	Errores en sumas, importes o comparaciones.
Código	Si mantiene sintaxis y pruebas.	Soluciones que parecen plausibles pero no ejecutan.
Recuperación de datos	Si extrae hechos sin inventar.	Cambia nombres, fechas o cantidades.
Latencia	Si el ahorro de memoria mejora la experiencia.	Menos memoria, pero más lentitud por ruta de runtime.

La decisión final debería escribirse así: “frente a BF16/Q8, esta cuantización ahorra X GB, mantiene Y de calidad en nuestros casos, empeora Z, y aun así compensa porque la tarea tolera ese error”. Si no puedes completar esa frase, todavía no has elegido; solo has descargado un fichero.

Ejemplo cercano: si el modelo debe escribir primeras versiones de correos, Q4 puede ser suficiente. Si debe extraer importes exactos de contratos, Q4 puede fallar de forma cara. Si debe generar SQL, un pequeño error puede romper la consulta. La cuantización adecuada depende del coste del error.

El criterio de elección local

Antes de instalar nada, escribe la decisión como una matriz. No hace falta que sea perfecta; hace falta que obligue a pensar.

Pregunta	Si la respuesta es sí	Si la respuesta es no
¿Necesito que los datos no salgan de mi máquina o red?	Local gana peso.	API puede ser más simple.
¿La tarea tolera algo menos de calidad?	Cuantización agresiva puede valer.	Baseline fuerte o API.
¿Necesito baja latencia interactiva?	Mide TTFT y tokens/s local.	Batch o API pueden bastar.
¿Tengo VRAM/RAM suficiente?	Prueba Q5/Q8 o modelos mayores.	Baja tamaño, baja contexto o usa cloud.
¿Necesito integrar en app?	Ollama/LM Studio API/local server.	UI puede ser suficiente para aprendizaje.
¿Necesito control fino de runtime?	llama.cpp/vLLM/SGLang.	Ollama o LM Studio simplifican.
¿Puedo mantener actualizaciones?	Local es viable.	API gestionada reduce carga.

Fíjate en que ninguna pregunta dice “¿qué modelo está de moda?”. El orden correcto es restricción, memoria, calidad, latencia, integración y mantenimiento.

Qué ocurre cuando cargas un modelo local

“Cargar un modelo” no es abrir un archivo. Es convertir un conjunto de ficheros en un proceso de inferencia que ocupa memoria, reserva contexto, aplica una plantilla de chat y queda disponible para recibir peticiones.

El recorrido real suele ser este:

Paso	Qué pasa	Qué puede fallar
1. Resolver el identificador	`gemma3`, `llama3.2`, un GGUF concreto o un modelo importado se traducen a ficheros locales.	Creer que dos nombres parecidos son el mismo modelo.
2. Leer metadatos	El runtime mira arquitectura, tokenizer, cuantización, contexto y plantilla.	Usar plantilla o tokenizer incorrectos.
3. Mapear pesos	Los tensores se leen desde disco y se preparan para CPU, GPU o memoria unificada.	El fichero cabe en disco, pero no en memoria.
4. Decidir offload	Algunas capas o cálculos pasan a GPU si hay VRAM o memoria unificada suficiente.	Parte cae a CPU y la latencia se dispara.
5. Reservar KV cache	El runtime reserva memoria para claves y valores de atención según contexto.	Subir contexto llena memoria aunque el modelo pese lo mismo.
6. Aplicar plantilla	Los mensajes `system`, `user` y `assistant` se convierten a tokens con el formato esperado.	El modelo “parece malo” porque se le habla con formato equivocado.
7. Generar tokens	El modelo predice token a token usando sampling, stops, temperatura y límites.	La salida no respeta formato, tarda demasiado o consume más memoria de la prevista.

En Ollama, el servidor local expone una API en localhost:11434 y permite comprobar modelos cargados con ollama ps. En LM Studio, la app permite cargar desde interfaz y el CLI lms permite listar, cargar, descargar, iniciar servidor y ver qué está en memoria. En ambos casos hay una idea común: descargar no es cargar, cargar no es evaluar, evaluar no es integrar.

Hardware y dependencias que sí importan

El hardware no se resume en “tengo GPU”. Para modelos locales, importan memoria, ancho de banda, drivers, disco, sistema operativo y puerto de servicio.

Recurso	Qué mirar	Lectura práctica
Disco	Espacio para modelos, duplicados, cachés y versiones.	Un proyecto local puede ocupar decenas o cientos de GB. No lo metas sin pensar en el disco del sistema.
RAM	Memoria principal para CPU, buffers, runtime y partes no aceleradas.	Si no hay margen, el sistema intercambia memoria y todo parece roto.
VRAM o memoria unificada	Pesos, KV cache y buffers en GPU o Apple Silicon.	Un modelo Q4 pequeño puede ir fluido; uno grande con contexto alto puede dejar de caber.
CPU	Fallback y preparación de datos.	Sirve para ejecutar, pero puede ser demasiado lento para uso interactivo.
GPU y drivers	NVIDIA, AMD, Metal, ROCm, Vulkan o CPU.	Asegura soporte antes de prometer latencia. Ollama documenta NVIDIA, AMD, Metal y Vulkan.
Contexto	Tokens máximos disponibles en memoria.	Más contexto aumenta memoria; no es una barra “gratis”.
Puerto local	`11434` para Ollama, `1234` habitual en LM Studio.	Revisa si escucha solo en localhost o si lo expones en red.
Herramientas de trabajo	Terminal, `curl`, Python 3, runtime elegido y drivers.	Sin medición por terminal, todo queda en sensación visual.

Dónde se guardan los modelos también importa. Ollama documenta rutas por defecto: macOS usa ~/.ollama/models, Linux usa /usr/share/ollama/.ollama/models y Windows usa C:\Users\%username%\.ollama\models; si necesitas moverlos, OLLAMA_MODELS define otra ubicación. LM Studio lo gestiona desde “My Models” y lms ls refleja el directorio de modelos configurado en la app.

Una instalación local mínima tiene estas dependencias conceptuales:

Dependencia	Para qué sirve	Señal de que está bien
Runtime	Cargar y ejecutar el modelo.	`ollama -v` o `lms --help` responden.
Modelo descargado	Tener pesos reales en disco.	`ollama list` o `lms ls` muestran el modelo.
Modelo cargado	Ocupar memoria para inferencia.	`ollama ps` o `lms ps` muestran un modelo activo.
API local	Integrar con scripts o apps.	`curl localhost:11434` o `curl localhost:1234` responde.
Driver GPU	Acelerar inferencia.	`ollama ps` indica GPU o `lms load --estimate-only` estima uso razonable.
Prueba propia	Ver si el sistema sirve para tu tarea.	Tienes métricas de latencia, memoria y formato válido.

Mi recomendación para clase o primer montaje: empieza con un modelo pequeño o mediano, una cuantización conservadora (Q4_K_M, Q5_K_M o equivalente), contexto 4096 u 8192, y una tarea concreta. Luego sube tamaño o contexto solo si puedes explicar qué ganaste.

Mapa visual del sistema local

En el día a día

En un proyecto real, los modelos locales aparecen en cinco situaciones: prototipado rápido, privacidad, trabajo offline, coste por volumen y aprendizaje técnico. Cada una exige una lectura distinta.

Si prototipas, quieres fricción baja. Ollama o LM Studio te permiten probar rápido. Si el objetivo es privacidad, ya no basta con “local”: revisa qué app abre red, dónde quedan logs, qué permisos tiene el servidor y si el puerto escucha solo en localhost. Si el objetivo es coste, calcula coste de hardware y tiempo del equipo. Si el objetivo es aprendizaje, acepta modelos pequeños y mide para entender.

La señal de madurez no es correr el modelo más grande posible. Es poder decir: “en esta máquina, con este modelo, esta cuantización y este contexto, obtenemos esta calidad, este TTFT, estos tokens/s y esta memoria”.

Por qué debería importarte

Porque local cambia el equilibrio del sistema. En una API externa, pagas por uso y delegas hardware. En local, controlas pesos y datos, pero compras complejidad: memoria, runtime, temperatura, contexto, actualizaciones y fallos.

También importa porque los próximos capítulos dependen de esto. RAG local, embeddings, text-to-SQL, agentes y herramientas internas pueden apoyarse en modelos locales, pero solo si sabes cuándo local es suficiente y cuándo estás intentando ahorrar en el sitio equivocado.

Dónde volverá a aparecer

Concepto	Dónde vuelve	Para qué
Cloud frente a local	Capítulo 06.	Comparar privacidad, latencia, coste y operación.
Embeddings locales	Capítulo 07.	Ejecutar modelos de representación en tu máquina.
RAG	Capítulos 09 y 10.	Decidir si generación y recuperación corren local o por API.
Text-to-SQL	Capítulo 12.	Evaluar si un modelo local genera consultas fiables.
Laboratorio mínimo	Capítulo 13.	Registrar evals, trazas y métricas de cada candidato.
Operación	Facsímil 6.	Servir, monitorizar y actualizar modelos de forma responsable.

Dónde solía tropezar yo

Error	Por qué es un error	Antídoto
Confundir local con privado absoluto	Local reduce envío remoto, pero no elimina permisos, logs, red ni procedencia.	Revisar puerto, logs, permisos, licencia y origen de pesos.
Elegir por tamaño descargado	El fichero no incluye KV cache, runtime ni margen de memoria.	Estimar pesos + KV + runtime + margen.
Subir contexto sin medir	Más contexto puede llenar memoria y empeorar TTFT.	Probar contexto real y mirar memoria durante la carga.
Comparar Q4 contra API sin baseline	Quizá el fallo viene de la cuantización, no del modelo.	Comparar contra Q8/BF16 o una API fuerte en los mismos casos.
Pensar que OpenAI-compatible significa igual	Puede haber diferencias en herramientas, JSON, streaming, errores y parámetros.	Ejecutar tests de contrato antes de cambiar backend.
No guardar configuración	No puedes reproducir un resultado si no sabes contexto, temperatura, offload y fichero.	Guardar Modelfile, modelo exacto, cuantización y métricas.

Manos a la obra

La práctica útil no es estimar de oído. La práctica útil es montar un sistema local pequeño, comprobar que el modelo se descarga, se carga, responde por API y devuelve una salida que una aplicación podría validar.

Paso 0: elegir ruta de montaje

Tienes dos rutas razonables para empezar:

Ruta	Cuándo usarla	Qué aprendes
Ollama	Quieres CLI sencilla, API local rápida y un flujo fácil de automatizar.	Modelo como servicio local en `localhost:11434`.
LM Studio	Quieres UI, exploración de modelos, carga visual y servidor local.	Modelo como app, servidor y CLI con `lms`.

No hace falta instalar las dos para aprender. Sí conviene conocer ambas porque aparecen mucho en equipos reales: una persona prototipa en LM Studio, otra integra con Ollama, y el problema profesional es que las dos decisiones sean trazables.

Paso 1: instalar y comprobar runtime

En macOS y Windows, Ollama se instala desde la app oficial. En Linux, la documentación oficial propone:

curl -fsSL https://ollama.com/install.sh | sh

Después comprueba que existe el binario y que el servidor responde:

ollama -v
ollama
curl http://localhost:11434/api/version

Para LM Studio, instala la app, ábrela una vez y comprueba el CLI:

lms --help
lms ls
lms ps

Si vas sin interfaz gráfica en Mac o Linux, LM Studio documenta instalación headless con:

curl -fsSL https://lmstudio.ai/install.sh | bash
lms daemon up

Paso 2: descargar y cargar un modelo pequeño

Empieza con un modelo pequeño o medio. No empieces por el más grande: primero quieres comprobar que el circuito funciona.

Con Ollama:

ollama pull gemma3
ollama run gemma3
ollama ps

Con LM Studio por CLI:

lms get <modelo>
lms load <modelo> --context-length=4096 --gpu=auto --identifier=local-lab
lms server start --port 1234
lms ps

Si usas la app de LM Studio, el equivalente es: buscar modelo, descargar, cargar en memoria, abrir el servidor local y fijarte en el identificador que usará la API.

Paso 3: registrar lo que montaste

Antes de programar, deja escrito esto:

Campo	Ejemplo	Por qué importa
Runtime	Ollama o LM Studio	Cambia API, carga y memoria.
Versión	salida de `ollama -v` o `lms --help`	Una actualización puede cambiar resultados.
Modelo	`gemma3` o identificador exacto de LM Studio	Es lo que llamarás desde código.
Fichero o variante	Q4, Q5, Q8, GGUF, MLX, safetensors	Cambia memoria y calidad.
Contexto	4096, 8192, 32768	Cambia KV cache y latencia.
Offload	CPU, GPU, auto, max	Cambia velocidad y consumo.
Puerto	11434 o 1234	Cambia integración y exposición local.

Paso 4: probar por API con código real

Este script no simula un modelo. Busca runtimes instalados, intenta llamar a Ollama y LM Studio, mide latencia, extrae el texto y comprueba si la respuesta es JSON válido. Si no tienes uno de los servidores levantado, te dice qué falta.

Guárdalo como local_llm_smoke_test.py y ejecútalo con python3 local_llm_smoke_test.py.

import json
import os
import platform
import shutil
import subprocess
import time
import urllib.error
import urllib.request


PROMPT = (
    "Devuelve solo JSON valido con estos campos: "
    "categoria, prioridad, siguiente_paso, confianza. "
    "Caso: un alumno no puede acceder al campus virtual antes de entregar una practica."
)


def command_exists(name):
    return shutil.which(name) is not None


def run_command(command):
    try:
        completed = subprocess.run(
            command,
            text=True,
            capture_output=True,
            timeout=8,
            check=False,
        )
        output = (completed.stdout or completed.stderr).strip()
        return completed.returncode, output[:600]
    except Exception as exc:
        return 1, str(exc)


def post_json(url, payload, token=None, timeout=60):
    body = json.dumps(payload).encode("utf-8")
    headers = {"Content-Type": "application/json"}
    if token:
        headers["Authorization"] = f"Bearer {token}"

    request = urllib.request.Request(url, data=body, headers=headers, method="POST")
    started = time.perf_counter()
    with urllib.request.urlopen(request, timeout=timeout) as response:
        raw = response.read().decode("utf-8")
    elapsed = time.perf_counter() - started
    return json.loads(raw), elapsed


def parse_model_json(text):
    cleaned = text.strip()
    if cleaned.startswith("```"):
        cleaned = cleaned.strip("`").strip()
        if cleaned.startswith("json"):
            cleaned = cleaned[4:].strip()

    try:
        return json.loads(cleaned), True
    except json.JSONDecodeError:
        start = cleaned.find("{")
        end = cleaned.rfind("}")
        if start >= 0 and end > start:
            return json.loads(cleaned[start : end + 1]), False
        raise


def ollama_check():
    model = os.getenv("OLLAMA_MODEL", "gemma3")
    payload = {
        "model": model,
        "stream": False,
        "messages": [
            {
                "role": "system",
                "content": "Responde solo con JSON valido. Sin texto adicional.",
            },
            {"role": "user", "content": PROMPT},
        ],
        "options": {"temperature": 0.1, "num_ctx": 4096},
    }
    data, elapsed = post_json("http://localhost:11434/api/chat", payload)
    text = data["message"]["content"]
    parsed, exact = parse_model_json(text)
    return {
        "backend": "ollama",
        "model": model,
        "latency_s": round(elapsed, 3),
        "exact_json": exact,
        "parsed": parsed,
    }


def lm_studio_check():
    model = os.getenv("LMSTUDIO_MODEL", "local-lab")
    token = os.getenv("LM_API_TOKEN")
    payload = {
        "model": model,
        "messages": [
            {
                "role": "system",
                "content": "Responde solo con JSON valido. Sin texto adicional.",
            },
            {"role": "user", "content": PROMPT},
        ],
        "temperature": 0.1,
        "max_tokens": 220,
        "stream": False,
    }
    data, elapsed = post_json(
        "http://localhost:1234/v1/chat/completions",
        payload,
        token=token,
    )
    text = data["choices"][0]["message"]["content"]
    parsed, exact = parse_model_json(text)
    return {
        "backend": "lm-studio",
        "model": model,
        "latency_s": round(elapsed, 3),
        "exact_json": exact,
        "parsed": parsed,
    }


def print_preflight():
    print("sistema:", platform.platform())
    print("python:", platform.python_version())
    print("ollama_cli:", command_exists("ollama"))
    print("lms_cli:", command_exists("lms"))

    if command_exists("ollama"):
        code, output = run_command(["ollama", "ps"])
        print("ollama_ps:", code, output or "(sin modelos cargados)")

    if command_exists("lms"):
        code, output = run_command(["lms", "ps"])
        print("lms_ps:", code, output or "(sin modelos cargados)")


def try_backend(name, check):
    print(f"\n== {name} ==")
    try:
        result = check()
        print(json.dumps(result, ensure_ascii=False, indent=2))
    except urllib.error.URLError as exc:
        print("no responde la API local:", exc)
    except Exception as exc:
        print("la API respondio, pero la prueba no paso:", exc)


if __name__ == "__main__":
    print_preflight()
    try_backend("ollama", ollama_check)
    try_backend("lm-studio", lm_studio_check)

Una salida sana no es que el texto “suene bien”. Una salida sana es algo así:

ollama_cli: True
lms_cli: True

== ollama ==
{
  "backend": "ollama",
  "model": "gemma3",
  "latency_s": 1.842,
  "exact_json": true,
  "parsed": {
    "categoria": "acceso",
    "prioridad": "alta",
    "siguiente_paso": "Revisar credenciales y estado del campus virtual",
    "confianza": 0.82
  }
}

Si exact_json sale false, el modelo produjo texto extra y el script tuvo que rescatar el objeto. Eso no es un detalle menor: para una aplicación real, significa que tu contrato de salida todavía es débil. Puedes probar a bajar temperature, cambiar modelo, usar salida estructurada si el runtime la soporta o ajustar el prompt de sistema.

Paso 5: interpretar el resultado

Después de ejecutar la prueba, contesta:

Pregunta	Qué te dice
¿El servidor local responde sin exponer red externa?	La integración básica está controlada.
¿El modelo aparece en `ollama ps` o `lms ps`?	Está cargado en memoria, no solo descargado.
¿La latencia es tolerable para una persona?	Sirve o no para interacción.
¿El JSON es exacto?	Sirve o no para integración automática.
¿Qué contexto configuraste?	Sabes cuánta KV cache estás provocando.
¿Qué cambiarías primero?	Modelo, cuantización, contexto, prompt, runtime o hardware.

Este ejercicio deja una base real: un runtime local, un modelo cargado, una API comprobada, una métrica y un contrato de salida. A partir de ahí sí tiene sentido comparar cuantizaciones, subir contexto o pasar al capítulo de cloud frente a local.

Cómo encaja todo

Este mapa muestra dónde se coloca el capítulo dentro del facsímil. No intenta repetir todas las siglas; separa decisión, ejecución y evaluación.

graph TD
    subgraph "Capítulo 5: modelos locales"
        CARD["Model card"]
        WEIGHTS["Pesos descargables"]
        FORMAT["Formato GGUF o safetensors"]
        QUANT["Cuantización"]
        RUNTIME["Runtime local"]
        MEMORY["Memoria y contexto"]
        API["API local"]
        EVAL["Eval propia"]
        DECISION["Decisión local trazable"]
    end
    subgraph "Viene de antes"
        TOKENS["Tokens y KV cache (F4C3)"]
        MODELSEL["Elección de modelos (F4C4)"]
        INFER["Inferencia optimizada (F3C7)"]
    end
    subgraph "Sigue después"
        CLOUD["Cloud frente a local<br/>(F4C6)"]
        EMB["Embeddings (F4C7)"]
        RAG["RAG (F4C9-10)"]
        OPS["Operación (F6)"]
    end

    MODELSEL --> CARD
    CARD --> WEIGHTS
    WEIGHTS --> FORMAT
    FORMAT --> QUANT
    QUANT --> RUNTIME
    TOKENS --> MEMORY
    INFER --> MEMORY
    RUNTIME --> MEMORY
    RUNTIME --> API
    MEMORY --> EVAL
    API --> EVAL
    EVAL --> DECISION
    DECISION --> CLOUD
    DECISION --> EMB
    DECISION --> RAG
    DECISION --> OPS

    style CARD fill:#F5F5F5,stroke:#000000,stroke-width:2
    style WEIGHTS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style FORMAT fill:#F5F5F5,stroke:#000000,stroke-width:2
    style QUANT fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RUNTIME fill:#F5F5F5,stroke:#000000,stroke-width:2
    style MEMORY fill:#F5F5F5,stroke:#000000,stroke-width:2
    style API fill:#F5F5F5,stroke:#000000,stroke-width:2
    style EVAL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style DECISION fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TOKENS stroke-dasharray: 5 5
    style MODELSEL stroke-dasharray: 5 5
    style INFER stroke-dasharray: 5 5
    style CLOUD stroke-dasharray: 5 5
    style EMB stroke-dasharray: 5 5
    style RAG stroke-dasharray: 5 5
    style OPS stroke-dasharray: 5 5

Vocabulario aprendido

Término	Definición
Modelo local	Modelo que se carga y ejecuta en una máquina controlada por ti.
Open weights	Pesos descargables bajo licencia concreta.
Runtime	Programa que ejecuta la inferencia y gestiona memoria.
GGUF	Formato que guarda tensores y metadatos para runtimes como llama.cpp.
GPU offload	Movimiento de capas o trabajo a GPU para acelerar inferencia.
VRAM	Memoria de GPU usada por pesos, KV cache y buffers.
KV cache	Memoria que crece con contexto y generación autoregresiva.
Cuantización	Representar pesos con menos bits para ahorrar memoria.
Escala de cuantización	Factor que convierte un entero pequeño en una aproximación del valor real.
Zero-point	Desplazamiento entero usado para representar el cero en cuantización asimétrica.
Granularidad	Tamaño del tensor, fila o bloque que comparte escala y metadatos.
PTQ	Cuantización aplicada después de entrenar, sin reentrenar todo el modelo.
Q4_K_M	Variante GGUF de 4 bits usada como equilibrio frecuente.
Modelfile	Receta de Ollama para modelo, parámetros, plantilla y licencia.
Local API	Endpoint HTTP para llamar al modelo desde una app local.
TTFT	Tiempo hasta recibir el primer token.
Tokens por segundo	Velocidad de generación durante la salida.

Antes de pasar página

En resumen

Idea fuerza	Detalle
Local es una pila completa.	Pesos, formato, runtime, memoria, API, licencia y eval trabajan juntos.
El tamaño del fichero no basta.	Hay que sumar KV cache, runtime, margen y contexto real.
GGUF es un contenedor operativo.	Guarda tensores y metadatos para runtimes locales, no una garantía de calidad.
Cuantizar cambia el sistema.	Puede ahorrar memoria y coste, pero debe medirse contra un baseline.
Ollama y LM Studio resuelven problemas distintos.	Uno favorece flujo simple y API; el otro añade UI, gestión visual y servidor local.
Instalar no es integrar.	Debes probar descarga, carga, API, latencia y contrato de salida.
La decisión local debe quedar escrita.	Modelo, cuantización, contexto, hardware, métricas y alternativa.

Para saber más

Dettmers, T. et al. (2022). LLM.int8(): 8-bit Matrix Multiplication for Transformers at Scale. https://doi.org/10.52202/068431-2198

Frantar, E. et al. (2022). GPTQ: Accurate Post-Training Quantization for Generative Pre-trained Transformers. https://arxiv.org/abs/2210.17323

ggml-org. (2026). llama.cpp: LLM inference in C/C++. https://github.com/ggml-org/llama.cpp

Hugging Face. (2026). GGUF. https://huggingface.co/docs/hub/en/gguf

Jacob, B. et al. (2018). Quantization and Training of Neural Networks for Efficient Integer-Arithmetic-Only Inference. https://doi.org/10.1109/CVPR.2018.00286

Lin, J. et al. (2024). AWQ: Activation-aware Weight Quantization for LLM Compression and Acceleration. https://arxiv.org/abs/2306.00978

Dettmers, T. et al. (2023). QLoRA: Efficient Finetuning of Quantized LLMs. https://arxiv.org/abs/2305.14314

LM Studio. (2026). Configuring the Model. https://lmstudio.ai/docs/typescript/llm-prediction/parameters

LM Studio. (2026). Get started with LM Studio. https://lmstudio.ai/docs/app/basics

LM Studio. (2026). LM Studio API. https://lmstudio.ai/docs/developer/rest

LM Studio. (2026). LM Studio Developer Docs. https://lmstudio.ai/docs/developer

LM Studio. (2026). lms: LM Studio's CLI. https://lmstudio.ai/docs/cli

LM Studio. (2026). lms load. https://lmstudio.ai/docs/cli/local-models/load

Ollama. (2026). FAQ. https://docs.ollama.com/faq

Ollama. (2026). Linux. https://docs.ollama.com/linux

Ollama. (2026). macOS. https://docs.ollama.com/macos

Ollama. (2026). Quickstart. https://docs.ollama.com/quickstart

Ollama. (2026). Windows. https://docs.ollama.com/windows

Ollama. (2026). Context length. https://docs.ollama.com/context-length

Ollama. (2026). Hardware support. https://docs.ollama.com/gpu

Ollama. (2026). Introduction to the Ollama API. https://docs.ollama.com/api/introduction

Ollama. (2026). Modelfile Reference. https://docs.ollama.com/modelfile

Ollama. (2026). OpenAI compatibility. https://docs.ollama.com/api/openai-compatibility

Xiao, G. et al. (2023). SmoothQuant: Accurate and Efficient Post-Training Quantization for Large Language Models. https://arxiv.org/abs/2211.10438

Notas

Ollama. (2026). Introduction to the Ollama API. https://docs.ollama.com/api/introduction. Consultado el 10 de junio de 2026. ↩
Ollama. (2026). Modelfile Reference. https://docs.ollama.com/modelfile. Consultado el 10 de junio de 2026. ↩
Ollama. (2026). Context length. https://docs.ollama.com/context-length. Consultado el 10 de junio de 2026. ↩
Ollama. (2026). Hardware support. https://docs.ollama.com/gpu. Consultado el 10 de junio de 2026. ↩
Ollama. (2026). OpenAI compatibility. https://docs.ollama.com/api/openai-compatibility. Consultado el 10 de junio de 2026. ↩
LM Studio. (2026). Get started with LM Studio. https://lmstudio.ai/docs/app/basics. Consultado el 10 de junio de 2026. ↩
LM Studio. (2026). LM Studio API. https://lmstudio.ai/docs/developer/rest. Consultado el 10 de junio de 2026. ↩
LM Studio. (2026). lms load. https://lmstudio.ai/docs/cli/local-models/load. Consultado el 10 de junio de 2026. ↩
Hugging Face. (2026). GGUF. https://huggingface.co/docs/hub/en/gguf. Consultado el 10 de junio de 2026. ↩
ggml-org. (2026). llama.cpp: LLM inference in C/C++. https://github.com/ggml-org/llama.cpp. Consultado el 10 de junio de 2026. ↩
Dettmers, T., Lewis, M., Belkada, Y. y Zettlemoyer, L. (2022). LLM.int8(): 8-bit Matrix Multiplication for Transformers at Scale. Advances in Neural Information Processing Systems 35. https://doi.org/10.52202/068431-2198. ↩
Xiao, G. et al. (2023). SmoothQuant: Accurate and Efficient Post-Training Quantization for Large Language Models. Proceedings of ICML. https://arxiv.org/abs/2211.10438. ↩
Frantar, E., Ashkboos, S., Hoefler, T. y Alistarh, D. (2022). GPTQ: Accurate Post-Training Quantization for Generative Pre-trained Transformers. https://arxiv.org/abs/2210.17323. ↩
Lin, J. et al. (2024). AWQ: Activation-aware Weight Quantization for LLM Compression and Acceleration. Proceedings of Machine Learning and Systems. https://arxiv.org/abs/2306.00978. ↩
Dettmers, T., Pagnoni, A., Holtzman, A. y Zettlemoyer, L. (2023). QLoRA: Efficient Finetuning of Quantized LLMs. Advances in Neural Information Processing Systems 36. https://arxiv.org/abs/2305.14314. ↩
Jacob, B. et al. (2018). Quantization and Training of Neural Networks for Efficient Integer-Arithmetic-Only Inference. Proceedings of CVPR, 2704-2713. https://doi.org/10.1109/CVPR.2018.00286. ↩
Ollama. (2026). Cloud. https://docs.ollama.com/cloud. Consultado el 10 de junio de 2026. ↩
LM Studio. (2026). Local Server. https://lmstudio.ai/docs/developer/core/server. Consultado el 10 de junio de 2026. ↩
ggml-org. (2026). llama-server. https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md. Consultado el 10 de junio de 2026. ↩

Capítulo 06

Facsímil 4 · La caja de herramientas

Capítulo 06: Cloud frente a local: privacidad, latencia y coste

La decisión que no cabe en un eslogan

Después de montar un modelo local, aparece una tentación muy humana: convertirlo en bandera. “Local es privado”. “Cloud es escalable”. “Local es barato”. “Cloud es caro”. Ninguna de esas frases aguanta mucho si la llevas a producción.

Venimos del capítulo 05, donde vimos que un modelo local es una pila: pesos, runtime, memoria, API, configuración y evaluación. Ahora comparamos esa pila con una API gestionada o una plataforma cloud. No para escoger por ideología, sino para responder una pregunta de ingeniería: dónde debe ejecutarse esta inferencia, con estos datos, este volumen, esta latencia, este presupuesto y este nivel de operación.

La idea central es esta: local y cloud no son bandos; son posiciones distintas dentro de una arquitectura.

Estado del arte con fecha de corte

Fecha de corte: 10 de junio de 2026.
Fuentes consultadas ese día: documentación oficial de controles de datos y precios de OpenAI, Anthropic, Google Cloud Vertex AI y Amazon Bedrock; documentación oficial de latencia; y artículos académicos sobre latencia de cola y edge computing.

Lo estable es el método: mirar frontera de confianza, retención, región, latencia, coste total, elasticidad, operación y plan de salida. Lo cambiante son precios, modelos disponibles, regiones, controles de retención, límites de API, multiplicadores por residencia, descuentos y disponibilidad de hardware.

Fuente	Qué aporta	Cómo usarla
OpenAI data controls.¹	Explica uso de datos, retención por endpoint y controles como retención cero o monitorización modificada cuando aplica.	Para no decir “API” sin revisar qué se guarda y durante cuánto tiempo.
OpenAI models API.²	Devuelve modelos disponibles para una clave y metadatos básicos como `id`, `created` y `owned_by`.	Para no usar identificadores copiados de ejemplos viejos.
OpenAI pricing.³	Precios por tokens, cache, batch y modalidades.	Para calcular coste por flujo real, no por intuición.
OpenAI latency optimization.⁴	Criterios para reducir latencia de aplicaciones con modelos.	Para separar tokens, streaming, modelo y arquitectura.
Anthropic data retention.⁵	Diferencia arreglos de retención, alcance de ZDR y funciones que necesitan almacenamiento.	Para preguntar qué modo contractual tienes, no qué marca usas.
Anthropic models API.⁶	Lista modelos disponibles con paginación y fechas de creación.	Para separar “familia Claude” de identificador concreto de API.
Anthropic pricing.⁷	Precios por entrada, salida, cache y geografía.	Para ver que cache y residencia también cambian coste.
Gemini models.⁸	Lista modelos, modalidades y patrones de versión estable, preview, latest y experimental.	Para fijar versiones estables y no depender de alias que cambian.
Vertex AI data governance.⁹	Controles de gobernanza, retención y condiciones de servicios generativos.	Para tratar cloud como contrato de datos, no solo endpoint.
Vertex AI pricing.¹⁰	Precios por modelo, tokens, herramientas y modalidades.	Para revisar token, imagen, vídeo, grounding y extras.
Amazon Bedrock data protection.¹¹	Modelo de responsabilidad compartida, cifrado, IAM, logs y separación con proveedores de modelos.	Para entender qué controla AWS y qué sigues controlando tú.
Amazon Bedrock pricing.¹²	Precios por modelo y modo de inferencia.	Para comparar marketplaces, regiones y modalidades.
OpenRouter models API.¹³	Expone modelos de muchos proveedores con `context_length`, modalidades, precios, parámetros soportados y enlaces a endpoints.	Para construir inventario técnico de modelos cloud comparables.
OpenRouter routing.¹⁴	Permite controlar proveedores, preferencias, rutas y sustitución cuando un proveedor no encaja.	Para entender un gateway como capa de selección, no como “un modelo más”.
Ollama Cloud y API.¹⁵	Mantiene herramientas locales mientras ejecuta modelos grandes en el servicio cloud de Ollama; la API local usa `localhost:11434/api`, cloud `https://ollama.com/api` y compatibilidad parcial OpenAI en `/v1`.	Para distinguir “uso Ollama” de “la inferencia está en mi máquina”.
vLLM, llama.cpp, TGI y SGLang.¹⁶	Runtimes para servir modelos propios con APIs compatibles, batching, plantillas de chat, GPU/CPU y opciones de producción.	Para montar servidor local con parámetros, observabilidad y contrato, no solo “ejecutar un modelo”.
Alquiler de GPU.¹⁷	Permite alquilar VM o instancia con acelerador, pagar por tiempo, reservar capacidad o usar capacidad con descuento bajo condiciones.	Para separar coste de API de coste de infraestructura propia en cloud.
GPU clouds y VM GPU.¹⁸	Documentan familias GPU, billing, almacenamiento, pods dedicados, contenedores y disponibilidad.	Para entender que alquilar GPU incluye storage, imagen, datos, arranque y operación.
The Tail at Scale.¹⁹	Explica por qué p95 y p99 importan más que el promedio en servicios interactivos.	Para medir latencia como experiencia real, no media bonita.
Edge Computing: Vision and Challenges.²⁰	Sitúa edge/local como forma de acercar cómputo a datos y usuarios.	Para entender local como ubicación arquitectónica, no como capricho.

La revisión del 10 de junio refuerza que cloud frente a local no se decide solo con precio por millón de tokens. OpenAI separa controles de datos, optimización de coste, optimización de latencia y selección de modelos; Anthropic documenta retención, residencia, uso/coste y límites de tasa; AWS Bedrock presenta la protección de datos desde responsabilidad compartida; y Vertex AI publica capacidades, release notes y SLA por servicio.²¹²²²³²⁴²⁵²⁶²⁷

La pregunta de ingeniería queda así: ¿puedo medir coste, latencia, retención, región, límites, errores y salida por proveedor con la misma rúbrica? Si no puedes, todavía no estás comparando local y cloud; estás comparando sensaciones. Un diseño serio incluye inventario de modelos, contrato de datos, presupuesto por flujo, p95/p99, plan de degradación, logs filtrados y salida de emergencia si un proveedor cambia modelo, precio o disponibilidad.

Qué no significa “privado”

Privado no significa “no usa internet”. Un portátil con un modelo local puede tener logs, copias de seguridad, extensiones, puertos abiertos, carpetas sincronizadas y usuarios con permisos amplios. Cloud no significa automáticamente “lo ve todo el proveedor”: puede haber contratos, controles de retención, cifrado, regiones, IAM, redes privadas y auditoría. La pregunta correcta no es si algo suena local o remoto; es dónde existe texto claro, quién puede acceder, cuánto tiempo queda guardado y qué contrato lo gobierna.

Tampoco conviene confundir privacidad con cumplimiento. Puedes proteger datos en local y aun así incumplir una política interna por falta de trazabilidad. Puedes usar cloud y cumplir mejor porque tienes auditoría, control de accesos y residencia definida. Depende del caso.

Y privacidad tampoco equivale a calidad. El modelo local más controlado puede no servir para la tarea. El modelo cloud más potente puede no encajar con los datos. La decisión empieza por la frontera de confianza, pero no termina ahí.

La frontera de confianza

Antes de hablar de coste, dibuja por dónde viajan los datos.

Lugar donde existe el dato	Pregunta que debes hacer	Señal de control
Navegador o app cliente	¿El usuario escribe datos sensibles?	Minimización antes de enviar.
Backend propio	¿Qué se loguea antes de llamar al modelo?	Logs filtrados, cifrado y permisos.
Proveedor cloud	¿Qué retiene el endpoint usado?	Contrato, región, DPA/BAA cuando aplique, controles de retención.
Runtime local	¿Quién puede leer disco, memoria, logs y puerto?	Usuario dedicado, permisos, `localhost`, rutas controladas.
Herramientas conectadas	¿El modelo llama sistemas externos?	Scopes mínimos, auditoría y validación de salida.
Caché o vector store	¿Se guardan prompts, fragmentos o embeddings?	TTL, borrado, cifrado y separación por cliente.

La frontera no es un punto; es una cadena. Si haces RAG local pero subes la respuesta completa a una API cloud para “mejorarla”, la frontera cambió. Si usas cloud pero anonimizas antes, haces hashing de identificadores y evitas enviar documentos completos, también cambió.

Latencia: no mires solo el promedio

Ejemplo de fórmula. La latencia total de una llamada a modelo puede descomponerse así:

L_{\text{total}} = L_{\text{red}} + L_{\text{cola}} + L_{\text{prefill}}(T_{\text{entrada}}) + L_{\text{decode}}(T_{\text{salida}}) + L_{\text{herramientas}} + L_{\text{postproceso}}

Término	Qué significa	Qué cambia local/cloud
$L_{\text{red}}$	Viaje entre cliente, backend y modelo.	Local puede reducirlo; cloud depende de región y red.
$L_{\text{cola}}$	Espera antes de ejecutar.	Cloud puede absorber picos; local se satura antes.
$L_{\text{prefill}}$	Procesar tokens de entrada.	Crece con contexto. RAG y documentos largos lo disparan.
$L_{\text{decode}}$	Generar tokens de salida.	Depende de modelo, hardware, cuantización y runtime.
$L_{\text{herramientas}}$	Consultas a bases de datos, APIs o buscadores.	A veces domina más que el modelo.
$L_{\text{postproceso}}$	Validar JSON, guardar, renderizar o reintentar.	Suele olvidarse en demos.

El promedio engaña. Si una app tiene 1000 usuarios y el 5 por ciento sufre esperas largas, ese 5 por ciento puede ser el que abandona. Dean y Barroso explican por qué la cola de latencias importa en sistemas a escala: no basta con que “normalmente vaya bien”.

Métrica	Qué mide	Decisión
p50	Experiencia típica.	Sirve para ver sensación normal.
p95	Casos lentos frecuentes.	Útil para producto.
p99	Cola larga.	Útil para flujos críticos o muchos usuarios.
TTFT	Tiempo hasta ver el primer token.	Mejora percepción si usas streaming.
tokens/s	Velocidad de salida.	Importa en respuestas largas.
timeouts	Peticiones que no terminan a tiempo.	Marcan límites de arquitectura.

Local puede ganar si el usuario y los datos están cerca del modelo y el modelo cabe bien. Cloud puede ganar si necesita hardware optimizado, batch, escalado, modelos grandes, alta concurrencia o regiones específicas. La única forma seria de decidir es medir el mismo caso en ambas rutas.

Coste: token barato no significa sistema barato

Ejemplo de fórmula. La cuenta cloud mínima es:

C_{\text{cloud}} = N \cdot \left( \frac{T_{\text{entrada}}}{10^6} P_{\text{entrada}} + \frac{T_{\text{salida}}}{10^6} P_{\text{salida}} \right) + C_{\text{cache}} + C_{\text{herramientas}} + C_{\text{almacenamiento}} + C_{\text{observabilidad}}

Ejemplo de fórmula. La cuenta local mínima es:

C_{\text{local}} = \frac{C_{\text{hardware}}}{M_{\text{amortizacion}}} + C_{\text{energia}} + C_{\text{operacion}} + C_{\text{mantenimiento}} + C_{\text{fallos}}

Coste	Cloud	Local
Tokens	Visible y variable.	No se paga por token, pero sí por capacidad.
Hardware	Incluido en precio o instancia.	Compra, alquiler o servidor propio.
Picos	Elasticidad bajo demanda.	Necesitas sobredimensionar o aceptar cola.
Mantenimiento	Delegado en gran parte.	Drivers, runtime, modelos, disco, seguridad, monitorización.
Fallos	SLA, regiones, límites y dependencia externa.	Tú operas la pila.
Privacidad	Contratos y controles del proveedor.	Control físico/lógico, pero también responsabilidad propia.
Cambio de modelo	Más fácil si la API lo ofrece.	Depende de pesos, runtime y hardware disponible.

Ejemplo de fórmula. El punto de equilibrio aparece cuando ambas cuentas se igualan:

N_{\text{equilibrio}} = \frac{C_{\text{local mensual}}} { \frac{T_{\text{entrada}}}{10^6} P_{\text{entrada}} + \frac{T_{\text{salida}}}{10^6} P_{\text{salida}} }

Ese número no decide solo, pero baja la conversación a tierra. Si necesitas 3000 peticiones al mes, quizá cloud sea más barato que comprar y mantener una GPU. Si necesitas 30 millones de peticiones homogéneas al mes, quizá local o infraestructura propia empiece a tener sentido. Si necesitas el mejor modelo para pocos casos delicados, cloud puede ser obvio aunque sea más caro por token.

Tres decisiones que se confunden

Cuando alguien dice “lo hacemos local o cloud”, en realidad hay tres decisiones mezcladas:

Decisión	Opciones	Qué pregunta responde
Dónde corre la generación	API cloud, servidor propio, portátil, edge, híbrido.	¿Dónde se ejecuta el modelo que genera texto?
Dónde viven los datos	Base propia, documentos locales, vector store cloud, almacenamiento regional.	¿Dónde están los documentos antes y después de inferir?
Dónde se opera el producto	App local, backend propio, cloud gestionado, marketplace.	¿Quién escala, observa, actualiza y responde cuando falla?

Puedes tener generación cloud con datos minimizados localmente. Puedes tener generación local con logs sincronizados a una nube corporativa. Puedes tener embeddings locales y generación cloud. Puedes tener RAG cloud y clasificación local. Lo profesional es nombrar la arquitectura exacta.

Estrategias reales de despliegue

No hay dos caminos; hay una familia de estrategias. La pregunta no es “¿cloud o local?”, sino qué capa quieres delegar y qué capa quieres controlar.

Estrategia	Qué controlas	Qué delegas	Cuándo encaja	Cuidado principal
API directa a un laboratorio	Prompt, contrato de salida, observabilidad de tu app.	Modelo, servidor, escalado, optimizaciones de inferencia.	Necesitas calidad alta, velocidad de desarrollo y modelos actuales.	Dependencia de precios, límites, región y política de datos.
Plataforma cloud gestionada	Región, IAM, redes, trazabilidad cloud, despliegue corporativo.	Servir el modelo y actualizar infraestructura base.	Empresa con cloud ya gobernada, auditoría y compras centralizadas.	El contrato cloud no elimina tu responsabilidad de diseño.
Gateway de modelos	Un endpoint común, selección de modelo, fallback, comparación rápida.	Relación con muchos proveedores y normalización parcial de APIs.	Quieres probar modelos o tener plan B sin reescribir toda la app.	No todos los parámetros significan lo mismo en todos los modelos.
Ollama Cloud	Herramienta local, CLI/API Ollama, cambio suave desde modelos pequeños.	Ejecución de modelos cloud de Ollama cuando no caben en tu equipo.	Quieres seguir usando flujo Ollama con modelos más grandes.	“Uso Ollama” no siempre significa “el cálculo ocurre localmente”.
Servidor propio de inferencia	Runtime, modelo exacto, hardware, red, logs, versionado y costes fijos.	Poco: tú operas casi todo.	Volumen estable, datos cerca, requisitos offline o control fino.	Operación, capacidad, actualizaciones y degradación bajo carga.
Híbrida por flujo	Qué parte va local, qué parte va cloud, qué se cachea y qué se deriva.	Solo las piezas elegidas.	La mayoría de productos reales con distintas sensibilidades y costes.	Sin reglas explícitas se convierte en una mezcla difícil de depurar.

OpenRouter entra en la tercera categoría: no es un modelo, es un router/gateway con una API compatible en la que eliges modelos de distintos proveedores. Su endpoint de modelos publica campos como id, context_length, modalidades, precios y parámetros soportados. Eso sirve para hacer inventario, pero no sustituye tu evaluación: dos modelos con la misma ventana de contexto pueden comportarse distinto con JSON, herramientas, español, razonamiento o latencia.

Ollama Cloud es otra cosa. Ollama puede seguir pareciendo local desde tu terminal, pero los modelos marcados como cloud se ejecutan en Ollama Cloud para poder usar modelos que no caben en tu GPU. Esto es cómodo para probar, pero cambia la frontera de confianza y el coste: la interfaz local no garantiza inferencia local.

Cómo saber qué modelos cloud tienes de verdad

Nunca elijas un modelo copiando un nombre de una entrada antigua, una captura o una demo. El identificador de modelo es una dependencia de producción. Tiene versión, fecha, capacidades, precio, modalidad, límites y, a veces, política de retirada.

Proveedor o gateway	Cómo inventariarlo	Qué mirar antes de usarlo
OpenAI	`GET https://api.openai.com/v1/models` con tu clave.	`id`, familia, endpoint soportado, precio actual, entrada multimodal, herramientas, structured outputs y modelo recomendado para tu tarea.
Anthropic	`GET https://api.anthropic.com/v1/models` con `anthropic-version`.	`id`, `display_name`, fecha de creación, ventana de contexto, coste, soporte de tools y modo de pensamiento si aplica.
Gemini API	Página de modelos y API de listado cuando trabajas con clave.	Si el nombre es estable, preview, latest o experimental; modalidades, herramientas, contexto, rate limits y fecha de retirada.
Bedrock o Vertex AI	Catálogo de modelos dentro de la región y cuenta.	Modelo disponible por región, precio por modalidad, IAM, logging, residencia y quotas.
OpenRouter	`GET https://openrouter.ai/api/v1/models`.	`id`, proveedor, `context_length`, `pricing`, `supported_parameters`, modalidades y endpoints concretos.
Ollama local	`GET http://localhost:11434/api/tags` o `ollama list`.	Modelo descargado, tamaño, cuantización, fecha, template y si responde bien a tu contrato.
Ollama Cloud	Catálogo de modelos cloud y base URL `https://ollama.com/api`.	Si el modelo se ejecuta cloud, cuenta/API key, precio, límites y qué datos salen de tu máquina.
Servidor local OpenAI-compatible	`GET http://host:puerto/v1/models` si el runtime lo expone.	Nombre servido, plantilla de chat, límites de contexto, dtype, cuantización y parámetros aceptados.

Un inventario mínimo debería quedar así, aunque lo guardes en una hoja o en JSON:

Campo	Ejemplo	Por qué importa
`provider`	`openai`, `anthropic`, `openrouter`, `local-vllm`	Te dice quién opera la inferencia.
`model_id`	`gpt-...`, `claude-...`, `meta-llama/...`	Es la dependencia exacta de código.
`endpoint`	`/v1/chat/completions`, `/v1/responses`, `/api/chat`	No todos los modelos sirven en todos los endpoints.
`context_tokens`	`128000`, `1000000`, `4096`	Define cuánto texto puedes meter sin partir.
`input_price` y `output_price`	USD por millón de tokens	El coste de salida suele ser más alto que el de entrada.
`modalities`	texto, imagen, audio, embeddings	Evita elegir texto para un problema multimodal.
`tools_json_schema`	sí/no/parcial	Afecta agentes, validación y salidas estructuradas.
`retention_region`	política y región	Afecta cumplimiento y arquitectura.
`version_policy`	estable, preview, latest	Afecta reproducibilidad.
`checked_at`	`2026-06-10`	Hace explícito cuándo era verdad.

Comandos de inventario, no de producción:

# OpenAI: modelos accesibles por tu clave
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# Anthropic: modelos accesibles por tu workspace
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

# OpenRouter: modelos, contexto, precios y parámetros soportados
curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

# Ollama local: modelos descargados en tu máquina
curl http://localhost:11434/api/tags

# Servidor local compatible con OpenAI, si lo expone
curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer $LOCAL_API_KEY"

Lo importante es no mezclar “modelo que existe”, “modelo que mi cuenta puede usar”, “modelo que mi endpoint acepta” y “modelo que mi evaluación aprueba”. Son cuatro filtros distintos.

Servir inferencia local en serio

Bajar un GGUF, escribir ollama run y ver una respuesta es una prueba de vida. Un servidor de inferencia es otra cosa: es una pieza de infraestructura que debe cargar pesos, reservar memoria, aceptar peticiones, encolar trabajo, generar tokens, devolver errores comprensibles, medir latencia y sobrevivir a usos repetidos.

Ejemplo de fórmula. La memoria mínima no es solo el tamaño del archivo:

\text{memoria}_{\text{total}} \approx \text{pesos}_{\text{cuantizados}} + \text{KV cache}(L, T, B) + \text{runtime} + \text{margen}

Donde $L$ son capas, $T$ tokens de contexto, $B$ peticiones simultáneas y la KV cache guarda claves y valores de atención para no recalcular todo en cada token. Por eso un modelo puede “caber” con una conversación corta y romperse cuando subes contexto, batch o concurrencia. En MoE tampoco basta mirar parámetros totales: importan parámetros activados por token, memoria de pesos, comunicación entre GPUs y eficiencia del runtime.

Capa	Decisión técnica	Qué mirar
Hardware	CPU, GPU, VRAM, RAM, disco NVMe, red.	VRAM útil, ancho de banda, drivers, consumo, refrigeración y margen.
Artefacto	GGUF, safetensors, AWQ/GPTQ/FP8/BF16, revisión exacta.	Licencia, checksum, tokenizer, chat template y versión fija.
Runtime	Ollama, llama.cpp, vLLM, SGLang, TGI, LM Studio.	Batching, KV cache, cuantización, multi-GPU, tools, JSON y compatibilidad OpenAI.
Configuración	`max_model_len`, dtype, batch, concurrencia, tensor parallel, cache.	Que el límite declarado sea sostenible con tus usuarios reales.
API	`/v1/chat/completions`, `/v1/embeddings`, `/api/chat`, streaming.	Contrato estable, errores, timeouts y parámetros aceptados.
Entrada	Plantilla de chat, system prompt, roles, documentos, imágenes.	Si la plantilla es incorrecta, el modelo parece peor de lo que es.
Operación	proceso, reinicio, logs, métricas, health checks, despliegue.	p50/p95/p99, TTFT, tokens/s, cola, VRAM, errores de JSON y coste eléctrico.
Acceso	bind de red, autenticación, TLS, rate limits, CORS.	No publiques `0.0.0.0` sin proxy, clave, límites y logs útiles.
Evolución	canary, rollback, evals, cambio de modelo.	Cambiar cuantización o template puede cambiar respuestas aunque el nombre parezca igual.

Runtimes habituales:

Runtime	Mejor para	Puntos técnicos
Ollama	Desarrollo local, demos, herramientas personales, API sencilla.	Muy cómodo; distingue local de cloud cuando uses modelos cloud.
LM Studio	Exploración visual, pruebas con modelos descargados, endpoint local.	Bueno para aprender; no lo confundas con una plataforma multiusuario.
llama.cpp `llama-server`	GGUF, CPU/edge, GPU modesta, despliegues ligeros.	Expone servidor HTTP compatible, opciones de host/puerto, GPU offload y endpoints de chat/embeddings.
vLLM	Alto throughput en GPU, servicio multiusuario, OpenAI-compatible.	Continuous batching, KV cache eficiente, tensor parallel, cuantización y `--api-key`.
SGLang	Baja latencia, alto throughput, modelos grandes/multimodales.	Runtime optimizado, OpenAI API, RadixAttention, prefix caching y gateway.
Hugging Face TGI	Servir modelos HF con API REST y Messages API.	Streaming, tensor parallel, Prometheus/Grafana, despliegue cloud o propio.

Un arranque local mínimo con vLLM no debería terminar en “funciona”. Debería fijar modelo, dtype, contexto, nombre servido y clave:

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3-8B-Instruct \
  --served-model-name local-qwen3-8b \
  --host 127.0.0.1 \
  --port 8000 \
  --dtype auto \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.86 \
  --api-key "$LOCAL_API_KEY"

Y una prueba de vida técnica debería medir contrato, streaming y coste aproximado de tokens, no solo leer una respuesta bonita:

URL="http://127.0.0.1:8000/v1"

curl "$URL/chat/completions" \
  -H "Authorization: Bearer $LOCAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-qwen3-8b",
    "messages": [
      {"role": "system", "content": "Devuelve solo JSON valido."},
      {"role": "user", "content": "Clasifica: acceso al campus virtual."}
    ],
    "temperature": 0.1,
    "max_tokens": 160,
    "stream": false
  }'

Si esa llamada falla, no has “fallado con IA”; has descubierto una capa concreta: modelo no cargado, plantilla incorrecta, falta de VRAM, endpoint mal expuesto, clave ausente, límite de contexto, JSON inestable o timeout. Eso es mucho más útil que una demo.

Alquilar GPUs para inferencia

Entre una API gestionada y una GPU en tu mesa existe una opción muy usada: alquilar GPU en cloud y servir tú el modelo. Es cloud en infraestructura, pero local en responsabilidad técnica: eliges artefacto, runtime, contenedor, plantilla, métricas, límites y política de despliegue.

Hay tres formas habituales:

Forma	Qué alquilas	Qué controlas	Cuándo encaja	Riesgo principal
VM GPU clásica	Una máquina con GPU, CPU, RAM, disco y red.	Sistema operativo, Docker, runtime, modelo, API y logs.	Servicio propio estable, pruebas serias, fine-tuning ligero o inferencia dedicada.	Pagas mientras está asignada, aunque esté esperando peticiones.
Pod GPU especializado	Una instancia GPU más directa, a menudo con plantillas o contenedor propio.	Imagen, volumen, librerías, runtime y arranque.	Probar modelos abiertos, levantar endpoints rápidos, trabajos por horas.	Disponibilidad por región/GPU y coste de almacenamiento persistente.
Serverless GPU o endpoint dedicado	Workers que arrancan bajo demanda o endpoint gestionado con GPU detrás.	Menos infraestructura; normalmente controlas imagen y escalado.	Tráfico irregular, demos, colas batch, picos previsibles.	Cold start, límites de ejecución, cola y menor control fino.

AWS EC2, Google Compute Engine y Azure permiten VMs con familias aceleradas por GPU. Runpod y proveedores similares simplifican el alquiler de pods con GPU y contenedores propios. Esto no sustituye a Bedrock, Vertex AI u OpenAI: es otra capa. En vez de comprar tokens de un modelo servido por otro, alquilas capacidad y corres tu pila de inferencia.

Ejemplo de fórmula. El coste mensual de una GPU alquilada se parece más a esto:

C_{\text{gpu}} = H_{\text{activa}} P_{\text{hora}} + H_{\text{idle}} P_{\text{hora}} + C_{\text{volumen}} + C_{\text{egress}} + C_{\text{imagenes}} + C_{\text{operacion}}

Ejemplo de fórmula. Y el coste aproximado por millón de tokens generados se estima así:

C_{1M} \approx \frac{P_{\text{hora}}}{3600 \cdot R_{\text{tokens/s}} \cdot U} \cdot 10^6

Donde $R_{\text{tokens/s}}$ es la velocidad útil del servidor y $U$ es la utilización real. Si la GPU solo está ocupada el 10 por ciento del tiempo, el coste efectivo por token se multiplica. Este es el punto que más se olvida: una GPU barata por hora puede ser cara por token si está casi vacía.

Para inferencia, la GPU no se elige por nombre bonito:

Necesidad	GPU o acelerador típico	Por qué
Modelo 7B-13B cuantizado, baja concurrencia	L4, A10, RTX 4090/5090, RTX 6000, T4 si aceptas menor margen.	Suele bastar para pilotos, herramientas internas y modelos pequeños.
Modelo 30B-70B, contexto mayor o más usuarios	A100 80GB, H100, H200, B200 o multi-GPU.	Más VRAM, ancho de banda y margen para KV cache.
Inferencia muy optimizada en AWS	Inf2 u otros aceleradores específicos.	Pueden ser eficientes, pero exigen stack y compilación propios.
Tráfico irregular	Serverless GPU o workers autoscalados.	Pagas menos espera, pero introduces arranque en frío.
Tráfico estable	GPU dedicada con reserva o compromiso.	Mejora disponibilidad y coste si sabes que la usarás muchas horas.

El tamaño de modelo no basta. Para servir bien necesitas medir:

Señal	Qué mide	Decisión
VRAM libre tras cargar pesos	Margen para KV cache y batch.	Si queda poco margen, baja contexto, cuantización o concurrencia.
TTFT	Tiempo hasta primer token.	Si es alto, revisa cola, prefill, cold start o modelo demasiado grande.
tokens/s por petición	Velocidad de generación.	Compara runtime, cuantización y GPU.
throughput agregado	Tokens/s o peticiones/s con concurrencia.	Sirve para decidir batch, réplicas y autoscaling.
utilización de GPU	Porcentaje real de uso.	Si es baja, estás pagando idle; si es alta, aparecerá cola.
errores por memoria	Peticiones que fallan por VRAM/contexto.	Define límites de entrada y concurrencia.
tiempo de arranque	Descargar imagen, montar volumen, cargar pesos.	Crítico en serverless y pods efímeros.

Checklist mínimo antes de usar GPU alquilada para una API de inferencia:

Imagen Docker reproducible con CUDA, runtime, versión de Python y dependencias fijadas.
Modelo y tokenizer en volumen persistente o cache precalentada; no descargar 80 GB en cada arranque.
Health check que no diga “vivo” hasta haber cargado el modelo.
Warmup con una petición corta para inicializar kernels, plantilla y cache.
Límite de contexto y max_tokens por endpoint, no solo por buena voluntad del cliente.
Autenticación delante del runtime, aunque sea interno.
Métricas de p50, p95, p99, TTFT, tokens/s, cola, VRAM y errores.
Política de apagado: deallocated/delete cuando no se usa; “stopped” no siempre significa coste cero según proveedor.
Plan de fallback: otro modelo, otra región, API gestionada o cola de espera.

La regla práctica: si vas a usar una GPU alquilada como API, trátala como producto en producción desde el minuto uno. Si solo la enciendes para experimentar, trátala como laboratorio caro y pon alarma de apagado.

Cuándo elegir cada ruta

Situación	Ruta probable	Por qué
Prototipo rápido con usuarios internos	Cloud o LM Studio local.	Aprendes rápido sin comprar infraestructura.
Datos sensibles y flujo simple	Local o cloud con controles contractuales fuertes.	La decisión depende de política, no de marca.
Mucha concurrencia variable	Cloud.	La elasticidad suele compensar.
Volumen estable y tarea acotada	Local/propio puede competir.	Puedes amortizar hardware y optimizar.
Necesitas modelo frontera	Cloud.	Los mejores modelos no suelen estar todos como pesos descargables.
Offline, aula, demo, entorno cerrado	Local.	Funciona sin depender de red externa.
Latencia de milisegundos cerca del usuario	Local/edge si el modelo cabe.	La distancia de red importa.
Cumplimiento con región definida	Cloud regional o local controlado.	Se decide por residencia, auditoría y contrato.
Comparar muchos modelos sin reescribir clientes	Gateway como OpenRouter.	Normaliza entrada y permite inventariar precios, contexto y parámetros.
Usar herramientas Ollama con modelos que no caben	Ollama Cloud.	Mantienes flujo Ollama pero cambias la ubicación real de inferencia.
Servir modelos abiertos con control técnico	GPU alquilada con vLLM, SGLang, TGI o llama.cpp.	Controlas artefacto, runtime y API sin comprar hardware.
Tráfico con picos y largas pausas	Serverless GPU o endpoint autoscalado.	Puede reducir idle, a cambio de cold start y menos control fino.

La ruta híbrida es común: clasificación local, RAG con datos propios, generación cloud para casos difíciles, cache de respuestas frecuentes y fallback local si la API externa no está disponible. Híbrido no significa improvisado; significa que cada pieza tiene una razón.

Mapa visual de decisión

En el día a día

Imagina una universidad que quiere clasificar incidencias de estudiantes. Si el texto contiene solo categorías generales, una API cloud puede dar calidad alta y mantenimiento bajo. Si el texto incluye expedientes, datos médicos o información contractual, quizá convenga anonimizar, resumir localmente o ejecutar todo en un entorno controlado.

Imagina una asesoría que analiza miles de facturas al mes. Si el volumen es bajo, una API potente evita comprar hardware. Si el volumen es constante, el modelo local puede ahorrar coste. Pero si cada error de extracción cuesta una llamada humana, el coste real no está en tokens: está en fallos.

Imagina una app de escritorio que debe funcionar en una fábrica sin red estable. Local gana por disponibilidad. Pero si el modelo debe razonar sobre documentos complejos y actualizados, quizá necesites sincronizar, cachear o derivar algunos casos a cloud. La arquitectura buena suele ser menos épica y más concreta.

Por qué debería importarte

Porque la elección local/cloud afecta a producto, privacidad, presupuesto, operación y experiencia de usuario. No es una decisión que pueda tomar solo compras, solo legal o solo ingeniería. Hay que poner a todos mirando la misma tabla.

También importa porque los próximos capítulos del facsímil se apoyan en esta decisión. Los embeddings, las bases vectoriales, el RAG y las herramientas de datos pueden correr local, cloud o híbrido. Si no sabes elegir ubicación, cada capítulo posterior se convierte en una colección de piezas sin arquitectura.

Dónde volverá a aparecer

Concepto	Dónde vuelve	Para qué
Embeddings locales o gestionados	Capítulo 07.	Decidir dónde convertir texto en vectores.
Bases vectoriales	Capítulo 08.	Elegir almacenamiento local, servicio gestionado o híbrido.
RAG	Capítulos 09 y 10.	Separar documentos, recuperación y generación.
Agentes con herramientas	Facsímil 05.	Decidir qué herramientas pueden llamarse y desde dónde.
Operación	Facsímil 06.	Monitorizar coste, latencia, errores y cambios de modelo.

Dónde solía tropezar yo

Error	Por qué es un error	Antídoto
Decir “local” como sinónimo de seguro	Local también tiene logs, backups, puertos y permisos.	Dibujar la frontera de confianza completa.
Decir “cloud” como sinónimo de caro	Pocas peticiones o modelos frontera pueden ser más baratos por API que operar hardware.	Calcular coste mensual, no coste emocional.
Comparar latencia media	El promedio oculta esperas largas.	Medir p50, p95, p99 y timeouts.
Olvidar el coste de operación local	Drivers, actualizaciones, disco, monitorización y guardias cuestan tiempo.	Incluir horas humanas y mantenimiento en el TCO.
No mirar la retención por endpoint	Distintas funciones pueden guardar estado de forma distinta.	Revisar documentación y contrato antes de enviar datos reales.
Construir sin plan de salida	Cambiar de proveedor o runtime tarde puede doler mucho.	Mantener pruebas comunes y contrato de API propio.
Creer que un gateway es un modelo	OpenRouter, por ejemplo, puede enrutar a modelos y proveedores distintos.	Guardar modelo, proveedor, endpoint, precio, fecha y parámetros soportados.
Confundir Ollama con inferencia local siempre	Ollama Cloud mantiene la experiencia de herramienta local, pero ejecuta modelos cloud.	Mirar si el modelo está descargado localmente o se ejecuta en cloud.
Montar servidor local sin contrato operativo	Una respuesta en terminal no mide colas, contexto, JSON, p95 ni reinicios.	Definir runtime, API, clave, métricas, límites, salud y rollback.
Alquilar GPU y olvidar el idle	Una GPU por hora puede salir cara si espera vacía.	Calcular coste por token útil con utilización real.
Confundir stopped con deallocated	En algunos clouds parar una VM no libera todo el coste asignado.	Revisar estado facturable, discos, IPs, snapshots y volúmenes.

Manos a la obra

Vamos a comparar dos backends con el mismo caso: uno local y uno cloud, ambos con contrato OpenAI-compatible cuando sea posible. No hace falta que tengas todos para aprender. Lo importante es repetir el mismo caso, registrar el endpoint exacto, guardar fecha de comprobación y no mezclar resultados de modelos distintos.

Primero decide qué backend vas a probar:

Backend	`BASE_URL` típico	Modelo de ejemplo	Qué estás midiendo
LM Studio local	`http://localhost:1234/v1`	alias cargado en LM Studio	Modelo local con interfaz cómoda.
Ollama local OpenAI-compatible	`http://localhost:11434/v1`	`gemma3` o `qwen3:8b`	Modelo descargado y servido por tu máquina.
vLLM local	`http://localhost:8000/v1`	`local-qwen3-8b`	Servidor de inferencia multiusuario más cercano a producción.
llama.cpp local	`http://localhost:8080/v1`	nombre servido por `llama-server`	GGUF ligero, CPU/edge o GPU modesta.
OpenAI	`https://api.openai.com/v1`	modelo disponible por `/v1/models`	API directa de laboratorio.
OpenRouter	`https://openrouter.ai/api/v1`	`proveedor/modelo`	Gateway con varios proveedores detrás.

Si usas servidor local, arranca una opción concreta y anota parámetros. No basta con “modelo cargado”; necesitas saber contexto, cuantización, nombre servido y clave.

# LM Studio
lms load <modelo> --context-length=4096 --gpu=auto --identifier=local-lab
lms server start --port 1234

# Ollama local compatible con partes de OpenAI
ollama pull gemma3
ollama serve

# vLLM local con contrato OpenAI-compatible
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3-8B-Instruct \
  --served-model-name local-qwen3-8b \
  --host 127.0.0.1 \
  --port 8000 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.86 \
  --api-key "$LOCAL_API_KEY"

# llama.cpp con GGUF
llama-server \
  -m ./models/modelo.gguf \
  --host 127.0.0.1 \
  --port 8080

Luego configura variables. Ajusta precios con la tabla oficial del proveedor el día de la prueba. Para local puedes poner precio por token a cero y un coste fijo mensual estimado; para cloud, usa precio de entrada y salida por millón de tokens.

export LOCAL_BASE_URL="http://localhost:8000/v1"
export LOCAL_API_KEY="local-dev-key"
export LOCAL_MODEL="local-qwen3-8b"
export LOCAL_INPUT_USD_PER_MTOK="0"
export LOCAL_OUTPUT_USD_PER_MTOK="0"
export LOCAL_FIXED_MONTHLY_USD="80"

export CLOUD_BASE_URL="https://api.openai.com/v1"
export CLOUD_API_KEY="..."
export CLOUD_MODEL="modelo-cloud"
export CLOUD_INPUT_USD_PER_MTOK="1.25"
export CLOUD_OUTPUT_USD_PER_MTOK="10"

Para OpenRouter cambia solo la base, la clave, el modelo y los precios:

export CLOUD_BASE_URL="https://openrouter.ai/api/v1"
export CLOUD_API_KEY="$OPENROUTER_API_KEY"
export CLOUD_MODEL="<id_devuelto_por_openrouter>"
# OpenRouter publica pricing.prompt y pricing.completion por token.
# Para este script multiplícalos por 1_000_000.
export CLOUD_INPUT_USD_PER_MTOK="<pricing.prompt * 1000000>"
export CLOUD_OUTPUT_USD_PER_MTOK="<pricing.completion * 1000000>"

Para Ollama local compatible con OpenAI:

export LOCAL_BASE_URL="http://localhost:11434/v1"
export LOCAL_API_KEY="ollama"
export LOCAL_MODEL="gemma3"

Guarda esto como comparar_local_cloud.py:

import json
import os
import time
import urllib.error
import urllib.request


PROMPT = (
    "Devuelve solo JSON valido con categoria, prioridad, "
    "siguiente_paso y confianza. "
    "Caso: clasificar 1200 incidencias mensuales con datos internos."
)


def env_float(name, default):
    try:
        return float(os.getenv(name, default))
    except ValueError:
        return float(default)


def post_chat(base_url, api_key, model):
    payload = {
        "model": model,
        "messages": [
            {
                "role": "system",
                "content": "Responde solo JSON valido.",
            },
            {"role": "user", "content": PROMPT},
        ],
        "temperature": 0.1,
        "max_tokens": 220,
        "stream": False,
    }
    headers = {"Content-Type": "application/json"}
    if api_key:
        headers["Authorization"] = f"Bearer {api_key}"

    request = urllib.request.Request(
        base_url.rstrip("/") + "/chat/completions",
        data=json.dumps(payload).encode("utf-8"),
        headers=headers,
        method="POST",
    )
    started = time.perf_counter()
    with urllib.request.urlopen(request, timeout=90) as response:
        data = json.loads(response.read().decode("utf-8"))
    elapsed = time.perf_counter() - started
    return data, elapsed


def extract_text(data):
    return data["choices"][0]["message"]["content"]


def usage_tokens(data, fallback_input=80, fallback_output=80):
    usage = data.get("usage") or {}
    input_tokens = (
        usage.get("prompt_tokens")
        or usage.get("input_tokens")
        or fallback_input
    )
    output_tokens = (
        usage.get("completion_tokens")
        or usage.get("output_tokens")
        or fallback_output
    )
    return int(input_tokens), int(output_tokens)


def parse_json(text):
    cleaned = text.strip()
    try:
        return json.loads(cleaned), True
    except json.JSONDecodeError:
        start = cleaned.find("{")
        end = cleaned.rfind("}")
        if start >= 0 and end > start:
            return json.loads(cleaned[start : end + 1]), False
        raise


def estimate_request_cost(
    input_tokens,
    output_tokens,
    input_price,
    output_price,
):
    return (input_tokens / 1_000_000 * input_price) + (
        output_tokens / 1_000_000 * output_price
    )


def measure_backend(prefix):
    base_url = os.getenv(f"{prefix}_BASE_URL")
    model = os.getenv(f"{prefix}_MODEL")
    api_key = os.getenv(f"{prefix}_API_KEY", "")

    if not base_url or not model:
        return {"backend": prefix.lower(), "status": "skipped"}

    input_price = env_float(f"{prefix}_INPUT_USD_PER_MTOK", "0")
    output_price = env_float(f"{prefix}_OUTPUT_USD_PER_MTOK", "0")

    data, elapsed = post_chat(base_url, api_key, model)
    text = extract_text(data)
    parsed, exact_json = parse_json(text)
    input_tokens, output_tokens = usage_tokens(data)
    request_cost = estimate_request_cost(
        input_tokens,
        output_tokens,
        input_price,
        output_price,
    )

    return {
        "backend": prefix.lower(),
        "status": "ok",
        "model": model,
        "latency_s": round(elapsed, 3),
        "input_tokens": input_tokens,
        "output_tokens": output_tokens,
        "request_cost_usd": round(request_cost, 6),
        "exact_json": exact_json,
        "parsed": parsed,
    }


def monthly_projection(result, monthly_requests, fixed_monthly):
    if result["status"] != "ok":
        return None
    variable = result["request_cost_usd"] * monthly_requests
    return round(variable + fixed_monthly, 2)


def main():
    monthly_requests = int(os.getenv("MONTHLY_REQUESTS", "1200"))
    local_fixed = env_float("LOCAL_FIXED_MONTHLY_USD", "0")
    cloud_fixed = env_float("CLOUD_FIXED_MONTHLY_USD", "0")

    results = []
    for prefix in ("LOCAL", "CLOUD"):
        try:
            results.append(measure_backend(prefix))
        except urllib.error.URLError as exc:
            results.append({
                "backend": prefix.lower(),
                "status": "unreachable",
                "error": str(exc),
            })
        except Exception as exc:
            results.append({
                "backend": prefix.lower(),
                "status": "failed",
                "error": str(exc),
            })

    for result in results:
        fixed = local_fixed if result["backend"] == "local" else cloud_fixed
        monthly_cost = monthly_projection(result, monthly_requests, fixed)
        result["monthly_cost_usd"] = monthly_cost

    print(json.dumps(
        {
            "monthly_requests": monthly_requests,
            "results": results,
            "decision_hint": (
                "elige despues de mirar coste, latencia, "
                "JSON exacto y frontera de datos"
            ),
        },
        ensure_ascii=False,
        indent=2,
    ))


if __name__ == "__main__":
    main()

La salida útil se parece a esto:

{
  "monthly_requests": 1200,
  "results": [
    {
      "backend": "local",
      "status": "ok",
      "model": "local-lab",
      "latency_s": 2.41,
      "input_tokens": 85,
      "output_tokens": 74,
      "request_cost_usd": 0.0,
      "exact_json": true,
      "monthly_cost_usd": 80.0
    },
    {
      "backend": "cloud",
      "status": "ok",
      "model": "modelo-cloud",
      "latency_s": 0.92,
      "input_tokens": 85,
      "output_tokens": 74,
      "request_cost_usd": 0.000846,
      "exact_json": true,
      "monthly_cost_usd": 1.02
    }
  ]
}

La interpretación no es “cloud gana porque cuesta 1,02” ni “local gana porque no manda datos”. La interpretación correcta es: para 1200 peticiones mensuales, si esos datos pueden salir bajo contrato, cloud parece más barato y rápido; si esos datos no pueden salir o la app debe funcionar sin red, local tiene sentido aunque el coste fijo sea mayor.

Cómo encaja todo

Este mapa conecta la decisión cloud/local con lo que ya vimos y con lo que viene. Fíjate en que no sale de “gusto por herramientas”, sino de restricciones medibles.

graph TD
    subgraph "Capítulo 6: cloud frente a local"
        DATA["Frontera de confianza"]
        INVENTORY["Inventario de modelos"]
        RETENTION["Retención y región"]
        LAT["Latencia p95"]
        COST["TCO y punto de equilibrio"]
        SERVER["Servidor de inferencia local"]
        ROUTER["Gateway o router de modelos"]
        RENTGPU["GPU alquilada"]
        OPS["Operación y mantenimiento"]
        ARCH["Arquitectura local, cloud o híbrida"]
    end
    subgraph "Viene de antes"
        TOKENS["Tokens, coste y caché (F4C3)"]
        MODELCARD["Elección de modelos (F4C4)"]
        LOCAL["Modelos locales (F4C5)"]
    end
    subgraph "Sigue después"
        EMB["Embeddings (F4C7)"]
        VECTOR["Bases vectoriales (F4C8)"]
        RAG["RAG (F4C9-10)"]
        AGENTS["Agentes con herramientas (F5)"]
        OPERATE["Construir y operar (F6)"]
    end

    TOKENS --> COST
    TOKENS --> LAT
    MODELCARD --> INVENTORY
    INVENTORY --> RETENTION
    INVENTORY --> ROUTER
    INVENTORY --> SERVER
    INVENTORY --> RENTGPU
    LOCAL --> OPS
    LOCAL --> SERVER
    SERVER --> OPS
    ROUTER --> COST
    RENTGPU --> SERVER
    RENTGPU --> COST
    RENTGPU --> OPS
    DATA --> RETENTION
    RETENTION --> ARCH
    LAT --> ARCH
    COST --> ARCH
    SERVER --> ARCH
    ROUTER --> ARCH
    RENTGPU --> ARCH
    OPS --> ARCH
    ARCH --> EMB
    ARCH --> VECTOR
    ARCH --> RAG
    ARCH --> AGENTS
    ARCH --> OPERATE

    style DATA fill:#F5F5F5,stroke:#000000,stroke-width:2
    style INVENTORY fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RETENTION fill:#F5F5F5,stroke:#000000,stroke-width:2
    style LAT fill:#F5F5F5,stroke:#000000,stroke-width:2
    style COST fill:#F5F5F5,stroke:#000000,stroke-width:2
    style SERVER fill:#F5F5F5,stroke:#000000,stroke-width:2
    style ROUTER fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RENTGPU fill:#F5F5F5,stroke:#000000,stroke-width:2
    style OPS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style ARCH fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TOKENS stroke-dasharray: 5 5
    style MODELCARD stroke-dasharray: 5 5
    style LOCAL stroke-dasharray: 5 5
    style EMB stroke-dasharray: 5 5
    style VECTOR stroke-dasharray: 5 5
    style RAG stroke-dasharray: 5 5
    style AGENTS stroke-dasharray: 5 5
    style OPERATE stroke-dasharray: 5 5

Vocabulario aprendido

Término	Definición
Frontera de confianza	Punto o cadena donde los datos pasan a otro dominio técnico o contractual.
TCO	Coste total de propiedad, incluyendo uso, infraestructura, operación y mantenimiento.
Latencia p95	Tiempo por debajo del cual termina el 95 por ciento de peticiones.
TTFT	Tiempo hasta recibir el primer token.
Throughput	Capacidad de procesar peticiones o tokens por unidad de tiempo.
Región	Ubicación geográfica donde se procesa o guarda una carga.
Retención	Tiempo durante el que se conservan datos, logs o estado.
Residencia de datos	Restricción sobre dónde deben vivir o procesarse los datos.
Capacidad elástica	Capacidad de escalar recursos bajo demanda.
Punto de equilibrio	Volumen donde coste local y cloud se igualan bajo hipótesis dadas.
Gateway de modelos	Capa que ofrece un endpoint común y enruta peticiones a distintos proveedores o modelos.
Servidor de inferencia	Servicio que carga pesos, gestiona memoria, cola peticiones y expone una API para generar salidas.
GPU alquilada	Acelerador en cloud que pagas por tiempo para ejecutar tu propio runtime o contenedor.
KV cache	Memoria usada para guardar claves y valores de atención ya calculados durante la generación.
Modelo servido	Nombre de modelo que expone tu API; puede ser distinto del repositorio o archivo interno.

Antes de pasar página

En resumen

Idea fuerza	Detalle
Local y cloud son posiciones arquitectónicas.	No son bandos; responden a restricciones distintas.
Privacidad exige dibujar la frontera de confianza.	Hay que saber dónde existe el dato, quién accede y cuánto se retiene.
La latencia útil se mide en p95 y p99.	El promedio no captura la experiencia de usuarios lentos.
El coste real es TCO.	Tokens, hardware, operación, mantenimiento, cache y herramientas cuentan.
Un gateway no es un modelo.	OpenRouter u otros routers pueden cambiar proveedor, parámetros y precio detrás de un endpoint común.
Ollama Cloud no equivale a inferencia local.	Conserva la experiencia Ollama, pero cambia ubicación, coste y frontera de datos.
Servir local en serio requiere infraestructura.	Modelo, runtime, KV cache, API, claves, métricas, colas, límites y rollback forman parte del sistema.
Alquilar GPU es cloud con responsabilidad propia.	Pagas tiempo, storage e idle; tú sirves, mides, actualizas y apagas.
La ruta híbrida suele ser la más realista.	Minimiza datos localmente, escala cloud cuando aporta y mantiene una eval común.

Para saber más

Amazon Web Services. (2026). Amazon Bedrock pricing. https://aws.amazon.com/bedrock/pricing/

Amazon Web Services. (2026). Data protection in Amazon Bedrock. https://docs.aws.amazon.com/bedrock/latest/userguide/data-protection.html

Amazon Web Services. (2026). Amazon EC2 Pricing. https://aws.amazon.com/ec2/pricing/

Amazon Web Services. (2026). Specifications for Amazon EC2 accelerated computing instances. https://docs.aws.amazon.com/ec2/latest/instancetypes/ac.html

Anthropic. (2026). API and data retention. https://platform.claude.com/docs/en/manage-claude/api-and-data-retention

Anthropic. (2026). List Models. https://platform.claude.com/docs/en/api/models/list

Anthropic. (2026). Pricing. https://platform.claude.com/docs/en/about-claude/pricing

Dean, J. y Barroso, L. A. (2013). The Tail at Scale. Communications of the ACM, 56(2), 74-80. https://doi.org/10.1145/2408776.2408794

Google. (2026). Gemini API models. https://ai.google.dev/gemini-api/docs/models

Google Cloud. (2026). About GPU instances. https://docs.cloud.google.com/compute/docs/gpus/about-gpus

Google Cloud. (2026). GPU machine types. https://docs.cloud.google.com/compute/docs/gpus

Google Cloud. (2026). Vertex AI and zero data retention. https://cloud.google.com/vertex-ai/generative-ai/docs/data-governance

Google Cloud. (2026). Vertex AI pricing. https://cloud.google.com/vertex-ai/generative-ai/pricing

Hugging Face. (2026). Text Generation Inference: HTTP API Reference. https://huggingface.co/docs/text-generation-inference/reference/api_reference

llama.cpp. (2026). llama-server. https://www.mintlify.com/ggml-org/llama.cpp/api/tools/llama-server

Microsoft Azure. (2026). Linux Virtual Machines Pricing. https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/

Microsoft Azure. (2026). Virtual machine sizes overview. https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/overview

Ollama. (2026). API introduction. https://docs.ollama.com/api/introduction

Ollama. (2026). Cloud. https://docs.ollama.com/cloud

Ollama. (2026). OpenAI compatibility. https://docs.ollama.com/api/openai-compatibility

OpenAI. (2026). Data controls in the OpenAI platform. https://developers.openai.com/api/docs/guides/your-data

OpenAI. (2026). Latency optimization. https://developers.openai.com/api/docs/guides/latency-optimization

OpenAI. (2026). List models. https://developers.openai.com/api/reference/resources/models/methods/list

OpenAI. (2026). Pricing. https://developers.openai.com/api/docs/pricing

OpenRouter. (2026). List all models and their properties. https://openrouter.ai/docs/api/api-reference/models/get-models

OpenRouter. (2026). Provider routing. https://openrouter.ai/docs/guides/routing/provider-selection

Runpod. (2026). Cloud GPU Instances for AI Workloads. https://www.runpod.io/product/cloud-gpus

Runpod. (2026). Pods pricing. https://docs.runpod.io/pods/pricing

Shi, W., Cao, J., Zhang, Q., Li, Y. y Xu, L. (2016). Edge Computing: Vision and Challenges. IEEE Internet of Things Journal, 3(5), 637-646. https://doi.org/10.1109/JIOT.2016.2579198

SGLang. (2026). Welcome to SGLang. https://docs.sglang.io/index.html

vLLM. (2026). OpenAI-Compatible Server. https://docs.vllm.ai/en/stable/serving/openai_compatible_server/

Notas

OpenAI. (2026). Data controls in the OpenAI platform. https://developers.openai.com/api/docs/guides/your-data. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). List models. https://developers.openai.com/api/reference/resources/models/methods/list. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). Pricing. https://developers.openai.com/api/docs/pricing. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). Latency optimization. https://developers.openai.com/api/docs/guides/latency-optimization. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). API and data retention. https://platform.claude.com/docs/en/manage-claude/api-and-data-retention. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). List Models. https://platform.claude.com/docs/en/api/models/list. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). Pricing. https://platform.claude.com/docs/en/about-claude/pricing. Consultado el 10 de junio de 2026. ↩
Google. (2026). Gemini API models. https://ai.google.dev/gemini-api/docs/models. Consultado el 10 de junio de 2026. ↩
Google Cloud. (2026). Vertex AI and zero data retention. https://cloud.google.com/vertex-ai/generative-ai/docs/data-governance. Consultado el 10 de junio de 2026. ↩
Google Cloud. (2026). Vertex AI pricing. https://cloud.google.com/vertex-ai/generative-ai/pricing. Consultado el 10 de junio de 2026. ↩
Amazon Web Services. (2026). Data protection in Amazon Bedrock. https://docs.aws.amazon.com/bedrock/latest/userguide/data-protection.html. Consultado el 10 de junio de 2026. ↩
Amazon Web Services. (2026). Amazon Bedrock pricing. https://aws.amazon.com/bedrock/pricing/. Consultado el 10 de junio de 2026. ↩
OpenRouter. (2026). List all models and their properties. https://openrouter.ai/docs/api/api-reference/models/get-models. Consultado el 10 de junio de 2026. ↩
OpenRouter. (2026). Provider routing. https://openrouter.ai/docs/guides/routing/provider-selection. Consultado el 10 de junio de 2026. ↩
Ollama. (2026). Cloud. https://docs.ollama.com/cloud. Consultado el 10 de junio de 2026. Véase también API introduction: https://docs.ollama.com/api/introduction y OpenAI compatibility: https://docs.ollama.com/api/openai-compatibility. ↩
vLLM. (2026). OpenAI-Compatible Server. https://docs.vllm.ai/en/stable/serving/openai_compatible_server/. Consultado el 10 de junio de 2026. llama.cpp. (2026). llama-server. https://www.mintlify.com/ggml-org/llama.cpp/api/tools/llama-server. Hugging Face. (2026). TGI HTTP API Reference. https://huggingface.co/docs/text-generation-inference/reference/api_reference. SGLang. (2026). Welcome to SGLang. https://docs.sglang.io/index.html. ↩
AWS. (2026). Amazon EC2 Pricing. https://aws.amazon.com/ec2/pricing/. Consultado el 10 de junio de 2026. AWS. (2026). Specifications for Amazon EC2 accelerated computing instances. https://docs.aws.amazon.com/ec2/latest/instancetypes/ac.html. Google Cloud. (2026). GPU machine types. https://docs.cloud.google.com/compute/docs/gpus. Google Cloud. (2026). About GPU instances. https://docs.cloud.google.com/compute/docs/gpus/about-gpus. ↩
Microsoft Azure. (2026). Virtual machine sizes overview. https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/overview. Microsoft Azure. (2026). Linux Virtual Machines Pricing. https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/. Runpod. (2026). Pods pricing. https://docs.runpod.io/pods/pricing. Runpod. (2026). Cloud GPU Instances for AI Workloads. https://www.runpod.io/product/cloud-gpus. Consultado el 10 de junio de 2026. ↩
Jeffrey Dean y Luiz André Barroso. (2013). The Tail at Scale. Communications of the ACM, 56(2), 74-80. https://doi.org/10.1145/2408776.2408794. ↩
Weisong Shi et al. (2016). Edge Computing: Vision and Challenges. IEEE Internet of Things Journal, 3(5), 637-646. https://doi.org/10.1109/JIOT.2016.2579198. ↩
OpenAI. (2026). Cost optimization. https://developers.openai.com/api/docs/guides/cost-optimization. Consultado el 10 de junio de 2026. ↩
OpenAI. (2026). Model selection. https://developers.openai.com/api/docs/guides/model-selection. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). Usage and Cost Admin API. https://platform.claude.com/docs/en/manage-claude/usage-cost-api. Consultado el 10 de junio de 2026. ↩
Anthropic. (2026). Data residency. https://platform.claude.com/docs/en/manage-claude/data-residency. Consultado el 10 de junio de 2026. ↩
Amazon Web Services. (2026). Data protection in Amazon Bedrock. https://docs.aws.amazon.com/bedrock/latest/userguide/data-protection.html. Consultado el 10 de junio de 2026. ↩
Google Cloud. (2026). Vertex AI Generative AI release notes. https://docs.cloud.google.com/vertex-ai/generative-ai/docs/release-notes. Consultado el 10 de junio de 2026. ↩
Google Cloud. (2026). Vertex AI Generative AI SLA. https://cloud.google.com/vertex-ai/generative-ai/sla. Consultado el 10 de junio de 2026. ↩

Capítulo 07

Facsímil 4 · La caja de herramientas

Capítulo 07: Embeddings aplicados y búsqueda semántica

Cuando las palabras exactas no bastan

Imagina que alguien busca en una intranet: “no puedo entrar al campus virtual”. El documento que resuelve el problema quizá se titula “Restablecer acceso a Moodle con doble factor”. No comparte demasiadas palabras con la consulta, pero para una persona está claro que hablan de lo mismo.

La búsqueda clásica por palabras exactas funciona muy bien cuando el usuario sabe cómo se llama algo. Falla más cuando el usuario describe una necesidad, usa sinónimos, escribe con otro registro o mezcla conceptos. Aquí entran los embeddings: convertir textos en vectores para poder buscar por cercanía aproximada de significado.

Venimos del capítulo 03, donde hablamos de tokens, contexto y coste, y del capítulo 06, donde decidimos dónde ejecutar modelos. Ahora usamos esa base para montar la pieza que alimenta RAG, memoria de producto, recomendadores y buscadores internos.

Estado del arte con fecha de corte

Fecha de corte: 25 de mayo de 2026.
Fuentes consultadas ese día: documentación oficial de embeddings de OpenAI, Gemini, Cohere, Voyage AI y Sentence Transformers; y trabajos académicos sobre sentence embeddings, búsqueda vectorial, HNSW, FAISS y evaluación de recuperación.

Lo estable es el mecanismo: un modelo convierte entradas en vectores, esos vectores se comparan con una métrica y el sistema devuelve un ranking. Lo cambiante son modelos disponibles, dimensiones, precios, límites de contexto, soporte multimodal, compresión, tipos de salida, librerías y benchmarks.

Fuente	Qué aporta	Cómo usarla
OpenAI embeddings.¹	Explica embeddings como vectores de números y enumera usos como búsqueda, clustering, recomendaciones y clasificación.	Para entender el contrato básico: texto entra, vector sale, distancia mide relación.
`text-embedding-3-large`.²	Documenta un modelo de embedding concreto y su ficha de modelo.	Para no hablar de “OpenAI embeddings” como si fuera un único artefacto.
Gemini embeddings.³	Muestra cómo generar embeddings en Gemini API y usar salida vectorial para recuperación.	Para comparar API, dimensiones, tareas y límites.
Cohere embeddings.⁴	Introduce `input_type`, soporte multilingüe, embeddings de imagen, contenido mixto, Matryoshka y compresión.	Para recordar que query y documento pueden tratarse de forma distinta.
Voyage embeddings.⁵	Lista modelos, dimensiones, contexto e `input_type` para query/document.	Para elegir modelos orientados a retrieval, código, legal, finanzas o uso general.
Sentence Transformers.⁶	Ofrece una forma local y reproducible de generar embeddings y hacer búsqueda semántica.	Para aprender el mecanismo sin depender de una API externa.
Sentence-BERT.⁷	Populariza embeddings de frases eficientes para similitud semántica.	Para ver por qué no basta usar cualquier vector interno de un modelo.
FAISS.⁸	Muestra técnicas de búsqueda eficiente de vectores a gran escala, especialmente en GPU.	Para entender por qué una base vectorial no compara siempre todo contra todo.
HNSW.⁹	Describe un índice por grafo muy usado para vecinos aproximados.	Para entender el intercambio entre rapidez, memoria y exactitud.
BEIR.¹⁰	Propone evaluar retrieval en tareas diversas, no solo en un dataset cómodo.	Para no validar un buscador con tres ejemplos elegidos a mano.

Qué no es un embedding

Un embedding no es una traducción secreta del texto. No contiene una definición legible de cada palabra. No es una base de datos comprimida con todos los documentos. Tampoco es una garantía de verdad: dos textos pueden estar cerca en el espacio vectorial y aun así no responder la pregunta correcta.

Tampoco es “memoria” por sí mismo. Guardar embeddings de documentos permite recuperar fragmentos parecidos, pero el sistema no entiende permisos, vigencia, autoría ni contexto de negocio a menos que tú lo diseñes. Un vector no sabe si un reglamento está derogado.

Y un embedding no sustituye a la búsqueda por filtros. Si el usuario pregunta por “normativa de matrícula 2025” y tu sistema devuelve un documento semánticamente parecido de 2021, el vector ha hecho parte del trabajo; falta metadata, filtros y evaluación.

Qué sí es: una coordenada útil

Un modelo de embeddings es una función:

e = f_{\theta}(x) \in \mathbb{R}^{d}

Símbolo	Significado	Ejemplo
$x$	Entrada que queremos representar.	“Restablecer acceso al campus virtual”.
$f_{\theta}$	Modelo de embeddings con parámetros aprendidos.	Un modelo de Sentence Transformers o una API de embeddings.
$e$	Vector resultante.	$[0{,}12,\,-0{,}03,\,0{,}44,\,...]$ .
$d$	Número de dimensiones del vector.	384, 768, 1024, 1536 o 3072 según modelo.
$\mathbb{R}^{d}$	Espacio de vectores reales de dimensión $d$ .	Una tabla con $d$ columnas numéricas.

La intuición: textos que el modelo considera parecidos quedan cerca. Textos que el modelo considera distintos quedan lejos. Esa cercanía no aparece porque el modelo “sepa” como una persona; aparece porque durante entrenamiento aprendió a colocar ejemplos relacionados cerca y ejemplos no relacionados más lejos.

En búsqueda semántica hacemos lo mismo con documentos y consultas:

q = f_{\theta}(\text{consulta})

d_i = f_{\theta}(\text{documento}_i)

Después comparamos $q$ con cada $d_i$ y ordenamos.

Qué significa la dimensión

La dimensión de un embedding es el número de componentes del vector. Si un modelo devuelve un embedding de dimensión 384, cada texto se convierte en 384 números. Si devuelve 3072, cada texto se convierte en 3072 números. No es una “nota de inteligencia”; es el ancho de la representación.

Piensa en una tabla. Cada fila es un texto y cada columna es una coordenada aprendida por el modelo:

e = [e_1, e_2, e_3, \dots, e_d]

Pieza	Qué significa	Ejemplo
$e$	Embedding completo de un texto.	El vector de “no puedo entrar al campus”.
$e_1, e_2, e_3$	Primeras coordenadas del vector.	`0.12`, `-0.31`, `0.08`.
$d$	Número total de coordenadas.	384 columnas numéricas.

En un ejemplo pequeño de cuatro dimensiones, dos textos podrían quedar así:

Texto	$e_1$	$e_2$	$e_3$	$e_4$
“acceso al campus”	0,20	0,81	-0,10	0,33
“entrar en Moodle”	0,18	0,77	-0,08	0,29
“calendario de matrícula”	-0,42	0,05	0,71	-0,11

Los dos primeros textos se parecen porque sus coordenadas apuntan en una dirección parecida. El tercero queda más lejos porque su patrón numérico es distinto.

Conviene decirlo con cuidado: una dimensión no suele significar “Moodle”, “matrícula” o “problema técnico” de forma aislada. En embeddings modernos, el significado aparece distribuido entre muchas coordenadas a la vez. Una coordenada puede participar en varios patrones; un patrón puede necesitar cientos o miles de coordenadas. Por eso no miramos una dimensión suelta para interpretar el texto: comparamos el vector completo.

La dimensión importa por cuatro razones:

Razón	Qué cambia	Consecuencia práctica
Memoria	Cada vector ocupa $d$ números.	Más dimensión implica más RAM, disco, backup y red.
Latencia	Comparar vectores cuesta más si $d$ crece.	El ranking exacto y el índice trabajan más.
Señal	El vector tiene más espacio para codificar matices.	Puede mejorar retrieval, pero no siempre en tu dominio.
Compatibilidad	Todos los vectores del índice deben tener la misma dimensión.	Cambiar modelo o dimensión suele exigir reindexar.

La memoria bruta se calcula así:

M_{\text{vectores}} = N \cdot d \cdot b

Símbolo	Significado	Ejemplo
$M_{\text{vectores}}$	Memoria bruta para guardar vectores.	Bytes antes de índice y metadata.
$N$	Número de vectores guardados.	1.000.000 chunks.
$d$	Dimensión de cada vector.	384, 1024 o 3072.
$b$	Bytes por número.	4 bytes para `float32`, 2 para `float16`.

Para 1 millón de vectores en float32:

Dimensión	Memoria bruta	Lectura de ingeniería
384	1,54 GB	Cómodo para prototipos y muchos casos internos.
768	3,07 GB	Dobla memoria y cómputo respecto a 384.
1536	6,14 GB	Empieza a exigir pensar en índice, RAM y backups.
3072	12,29 GB	Puede tener más señal, pero no sale gratis.

El coste de comparación exacta crece igual:

C_{\text{comparar}} = O(N \cdot d)

Si duplicas $d$ , duplicas el trabajo bruto de comparar una consulta contra todos los vectores. Un índice aproximado reduce el número de comparaciones, pero no elimina que cada comparación tenga $d$ componentes.

Algunos modelos y proveedores permiten reducir dimensión de salida o usar representaciones tipo Matryoshka, donde los primeros bloques del vector intentan conservar señal útil al truncar dimensiones.¹¹ Cohere, por ejemplo, documenta embeddings con Matryoshka y compresión para equilibrar calidad, memoria y coste.¹² Eso no significa que puedas cortar cualquier vector arbitrariamente y esperar el mismo resultado: hay que evaluarlo.

Dimensión, coste y calidad en una sola imagen

La métrica que decide el ranking

La similitud coseno compara dirección, no tamaño bruto:

\operatorname{cos}(q, d_i) = \frac{q \cdot d_i}{\|q\|\,\|d_i\|}

Símbolo	Significado	Ejemplo
$q$	Vector de la consulta.	$[0{,}2, 0{,}8]$ .
$d_i$	Vector del documento $i$ .	$[0{,}1, 0{,}9]$ .
$q \cdot d_i$	Producto punto: suma de productos componente a componente.	$0{,}2\cdot0{,}1 + 0{,}8\cdot0{,}9 = 0{,}74$ .
$\\|q\\|$	Norma o longitud del vector de consulta.	$\sqrt{0{,}2^2+0{,}8^2}=0{,}824$ .
$\\|d_i\\|$	Norma del vector de documento.	$\sqrt{0{,}1^2+0{,}9^2}=0{,}906$ .
$\operatorname{cos}(q,d_i)$	Similitud final.	$0{,}74/(0{,}824\cdot0{,}906)=0{,}992$ .

Si normalizas todos los vectores para que tengan norma 1, el coseno se convierte en producto punto:

\hat{q} = \frac{q}{\|q\|}, \qquad \hat{d_i} = \frac{d_i}{\|d_i\|}

\operatorname{cos}(q,d_i)=\hat{q}\cdot\hat{d_i}

Eso importa en producción porque muchas bases vectoriales trabajan más rápido con producto punto si tus vectores ya están normalizados.

El ranking top-k se expresa así:

\operatorname{TopK}(q, D, k) = \{d_{(1)},\dots,d_{(k)}\}, \quad s(q,d_{(1)}) \ge \dots \ge s(q,d_{(k)})

Símbolo	Significado	Ejemplo
$D$	Colección de documentos vectorizados.	50.000 fragmentos de una intranet.
$k$	Número de resultados que queremos devolver.	5.
$s(q,d_i)$	Función de puntuación.	Coseno, producto punto o distancia negativa.
$\operatorname{TopK}$	Devuelve los identificadores con mayor puntuación.	Documentos 17, 42, 8, 91 y 3.

El proceso completo

Una búsqueda semántica mínima tiene dos fases: indexación y consulta. En indexación conviertes documentos en vectores y guardas esos vectores con sus metadatos. En consulta conviertes la pregunta en otro vector, buscas vecinos cercanos y devuelves resultados.

Paso	Qué ocurre	Decisión técnica
1. Preparar documentos	Limpias, separas, titulas o partes contenido.	Qué unidad se busca: documento entero, sección, párrafo o chunk.
2. Generar embeddings	Cada unidad pasa por el modelo.	Modelo, dimensión, idioma, coste, privacidad y batch.
3. Normalizar	Opcionalmente reescalas vectores.	Coseno/producto punto y compatibilidad con el índice.
4. Guardar	Vector + texto + metadata + versión.	Base vectorial, tabla propia o índice en memoria.
5. Embedding de consulta	La pregunta se transforma con el mismo modelo o modelo compatible.	`input_type=query` si el proveedor lo usa.
6. Recuperar top-k	Buscas vecinos exactos o aproximados.	Exactitud, latencia, memoria y filtros.
7. Reordenar	Puedes aplicar reranking, filtros o MMR.	Mejorar precisión y diversidad.
8. Usar resultados	Mostrar documentos o pasarlos a un LLM.	Búsqueda, RAG, recomendación o clasificación.

La unidad de búsqueda es decisiva. Si indexas documentos enormes, el resultado puede ser “parecido” pero poco accionable. Si indexas frases demasiado cortas, pierdes contexto. Si indexas chunks sin título, una frase como “plazo máximo” puede quedar huérfana.

Una imagen mental del pipeline

Exacto, aproximado y lo que cuesta

Si tienes pocos documentos, puedes comparar la consulta con todos los vectores. Eso se llama búsqueda exacta por fuerza directa. Si tienes millones de vectores, comparar contra todos puede ser caro y lento; entonces aparecen índices aproximados.

El coste de comparar una consulta contra $N$ documentos de dimensión $d$ es aproximadamente:

C_{\text{exacto}} = O(N \cdot d)

Símbolo	Significado	Ejemplo
$N$	Número de vectores guardados.	1.000.000 chunks.
$d$	Dimensión de cada vector.	1024.
$O(N\cdot d)$	Trabajo proporcional a comparar $N$ vectores de $d$ números.	Unos 1.024 millones de multiplicaciones/sumas por consulta.

Los índices ANN reducen latencia buscando candidatos probables, no revisando todo. HNSW lo hace con un grafo de vecinos navegable; FAISS agrupa varias técnicas como índices planos, cuantización y búsqueda en GPU. La palabra aproximado no significa “malo”: significa que aceptas una probabilidad de no encontrar exactamente el vecino más cercano a cambio de velocidad.

La memoria también importa:

M_{\text{vectores}} = N \cdot d \cdot b

Símbolo	Significado	Ejemplo
$M_{\text{vectores}}$	Memoria bruta para guardar vectores.	Bytes antes de índice y metadata.
$N$	Número de vectores.	1.000.000.
$d$	Dimensión.	1536.
$b$	Bytes por número.	4 bytes si usas `float32`.

Con $N=1.000.000$ , $d=1536$ y float32, solo los vectores ocupan:

1.000.000 \cdot 1536 \cdot 4 = 6.144.000.000\ \text{bytes}

Eso son unos 6,1 GB antes de contar índices, texto, metadata, réplicas y backups. Si además guardas 10 millones de chunks, el problema deja de ser “llamar a embeddings” y pasa a ser arquitectura de almacenamiento.

Elegir modelo de embedding

Elegir un modelo de embeddings no es elegir “el más grande”. Es elegir el que recupera mejor tus documentos con tu idioma, tu dominio, tu latencia y tu presupuesto.

Criterio	Qué mirar	Por qué
Idioma	Español, multilingüe, mezcla de idiomas.	Un modelo fuerte en inglés puede perder matices en español.
Dominio	General, código, legal, financiero, médico, soporte.	El vocabulario y las relaciones cambian.
Dimensión	384, 768, 1024, 1536, 3072...	Afecta memoria, coste y velocidad de búsqueda.
Contexto	Tokens máximos por entrada.	Documentos largos se truncarán o habrá que trocearlos.
`input_type`	Query/document si el proveedor lo distingue.	Algunas APIs optimizan consultas y documentos de forma distinta.
Modalidad	Texto, imagen, documentos mixtos.	Para PDFs visuales o capturas quizá no baste texto plano.
Local o cloud	Privacidad, latencia, coste y operación.	Conecta directamente con el capítulo 06.
Evaluación	Recall@k, MRR, precisión, nDCG.	El benchmark externo orienta; tu caso decide.

Un detalle importante: si reindexas con otro modelo, los vectores antiguos y nuevos normalmente no son comparables. Cambiar de embedding model puede implicar recalcular todo el índice. Por eso conviene guardar embedding_model, embedding_version, dimension, normalization, created_at y source_hash junto a cada vector.

Cómo trabajar con embeddings sin romper producción

Trabajar con embeddings no es solo llamar una API y guardar un array. Es construir una cadena reproducible: preparar texto, generar vectores, versionarlos, guardarlos, consultarlos y evaluar si siguen sirviendo cuando cambian documentos, modelos o permisos.

Tarea	Cómo hacerlo	Qué comprobar
Preparar entrada	Añadir título, sección, ruta y texto limpio.	Que el fragmento sea entendible fuera del documento original.
Generar por lotes	Enviar batches razonables y controlar reintentos.	Coste, rate limits, errores parciales y orden de resultados.
Versionar	Guardar modelo, dimensión, normalización y hash de fuente.	Poder saber qué vector corresponde a qué texto exacto.
Normalizar	Reescalar si usarás coseno como producto punto.	No mezclar vectores normalizados y sin normalizar.
Guardar metadata	Curso, cliente, permiso, fecha, idioma, tipo de documento.	Poder filtrar antes o después de recuperar.
Reindexar	Planificar jobs idempotentes y reanudables.	No duplicar vectores ni mezclar versiones.
Evaluar	Mantener consultas reales con positivos y hard negatives.	Que cambios de modelo o dimensión no degraden el ranking.
Monitorizar	Medir latencia, top-k vacío, drift y feedback.	Detectar documentos obsoletos o consultas nuevas.

Una regla sencilla: el texto que guardas junto al vector debe ser suficiente para explicar por qué salió ese resultado. Si solo guardas el vector y un identificador, depurar será una tortura tranquila.

Búsqueda semántica no es RAG

Búsqueda semántica recupera candidatos. RAG usa candidatos para construir una respuesta generada. Esta diferencia parece pequeña, pero cambia cómo evalúas.

Sistema	Salida	Qué evalúas
Búsqueda semántica	Lista de documentos o fragmentos.	Si el resultado correcto aparece arriba.
RAG	Respuesta generada con contexto.	Si la respuesta está fundamentada en los fragmentos correctos.
Recomendador	Elementos parecidos o útiles.	Si el usuario acepta, compra, lee o resuelve.
Clasificación por similitud	Etiqueta más cercana.	Si la etiqueta elegida es correcta.

Si el retrieval falla, el generador no puede arreglarlo de forma fiable. Puede escribir una respuesta bonita con evidencia equivocada. Por eso los próximos capítulos separan bases vectoriales, RAG y evaluación de RAG.

En el día a día

En una universidad, embeddings pueden servir para que una persona encuentre normativa aunque no conozca el nombre exacto del trámite. En soporte interno, pueden agrupar tickets parecidos y detectar respuestas repetidas. En producto, pueden recomendar documentación relacionada. En una base de conocimiento, pueden recuperar fragmentos para que un LLM responda con contexto.

La parte delicada es que una búsqueda semántica buena no depende solo del modelo. Depende de cómo partes documentos, qué metadata guardas, si filtras por permisos, si separas versiones antiguas, si reordenas resultados y si mides con preguntas reales.

Un caso cercano: tienes 800 artículos de ayuda. Si alguien pregunta “me han bloqueado la cuenta”, un buscador por palabra puede priorizar artículos que contienen “bloqueado”. Un embedding puede recuperar “Restablecer acceso tras demasiados intentos”. Pero si el artículo correcto está obsoleto y falta metadata de versión, el sistema seguirá pareciendo inteligente mientras devuelve una respuesta mala.

Por qué debería importarte

Embeddings son la puerta de entrada a casi todo lo que se vende como “IA con tus datos”. Si no entiendes esta pieza, no sabes si tu RAG falla por el modelo generativo, por el chunking, por la base vectorial, por la métrica o por la evaluación.

También importan por coste. Embeddings se calculan al indexar, se guardan durante meses, se consultan muchas veces y ocupan memoria. Una mala decisión de dimensión, chunking o modelo puede multiplicar almacenamiento y latencia sin mejorar recuperación.

Medir si recupera bien

Un buscador semántico debe evaluarse con consultas y respuestas esperadas. No hace falta empezar con un benchmark gigante: puedes crear 30 consultas reales, marcar qué documento debería aparecer y medir.

Recall@k:

\operatorname{Recall@k} = \frac{\text{consultas con al menos un resultado correcto en top-k}} {\text{total de consultas}}

Símbolo	Significado	Ejemplo
$k$	Número de resultados que miras.	3.
Top-k	Primeros $k$ documentos devueltos.	Los tres primeros resultados.
Resultado correcto	Documento marcado como relevante.	El artículo que resuelve el problema.

MRR mide en qué posición aparece el primer resultado correcto:

\operatorname{MRR} = \frac{1}{Q} \sum_{j=1}^{Q} \frac{1}{\operatorname{rank}_j}

Símbolo	Significado	Ejemplo
$Q$	Número de consultas evaluadas.	30.
$\operatorname{rank}_j$	Posición del primer resultado correcto para la consulta $j$ .	1 si sale primero, 3 si sale tercero.
$1/\operatorname{rank}_j$	Penalización por aparecer más abajo.	1, 0,5, 0,333...

Si el documento correcto aparece siempre en posición 8 y tú solo pasas top-3 al LLM, tu RAG no verá la evidencia aunque “el buscador la tenía”. Ese detalle es muy de ingeniería y muy poco de demo.

Evaluar embeddings, no solo el buscador

Evaluar embeddings no es preguntar “¿me gusta el primer resultado?”. Hay que separar varias preguntas:

Pregunta	Métrica útil	Qué detecta
¿Aparece algún documento correcto entre los primeros?	Recall@k	Si el sistema encuentra evidencia suficiente.
¿Aparece arriba o enterrado?	MRR	Si el primer resultado útil llega pronto.
¿Ordena bien varios relevantes?	nDCG@k	Si documentos muy relevantes suben más que los medianos.
¿Se degrada al reducir dimensión?	Curva dimensión-métrica	Si puedes ahorrar memoria sin perder calidad.
¿Funciona en todos los grupos?	Métricas por idioma, dominio, tipo de consulta.	Si el promedio oculta fallos por segmento.
¿Distingue parecidos peligrosos?	Hard negatives	Si confunde textos casi iguales pero incorrectos.

BEIR y MTEB existen porque un embedding puede ir bien en una tarea y flojo en otra.¹³ Para un proyecto real, el benchmark externo sirve para elegir candidatos, pero tu evaluación interna decide.

nDCG@k se usa cuando no todos los documentos relevantes valen lo mismo:

\operatorname{DCG@k} = \sum_{i=1}^{k} \frac{2^{rel_i}-1}{\log_2(i+1)}

\operatorname{nDCG@k} = \frac{\operatorname{DCG@k}}{\operatorname{IDCG@k}}

Símbolo	Significado	Ejemplo
$rel_i$	Relevancia del resultado en posición $i$ .	2 si responde, 1 si ayuda, 0 si no sirve.
$\operatorname{DCG@k}$	Ganancia acumulada con descuento por posición.	Premia relevancia arriba.
$\operatorname{IDCG@k}$	DCG ideal si el ranking fuera perfecto.	Mejor orden posible para esa consulta.
$\operatorname{nDCG@k}$	DCG normalizado entre 0 y 1.	1 significa orden ideal.

Una evaluación seria de embeddings debería guardar:

Campo	Ejemplo	Por qué
`query_id`	`q-014`	Permite repetir y auditar resultados.
`query_text`	“no puedo entrar al campus”	La consulta real que hizo una persona o un caso diseñado.
`positive_ids`	`["doc-01"]`	Documentos que deben aparecer.
`graded_relevance`	`{"doc-01": 2, "doc-05": 1}`	Diferencia evidencia principal de apoyo parcial.
`hard_negative_ids`	`["doc-03"]`	Documentos parecidos que no responden.
`filters`	`{"curso": "2026"}`	Condiciones de producto o permisos.
`embedding_model`	`all-MiniLM-L6-v2`	La evaluación depende del modelo.
`dimension`	`384`	Cambiar dimensión puede cambiar ranking.
`top_k`	`3`, `5`, `10`	Define qué ve usuario o LLM.

La parte más útil suele ser mirar errores, no solo el número final. Si una consulta falla porque el documento está mal troceado, el embedding no era el problema. Si falla porque hay dos documentos casi idénticos y uno está obsoleto, necesitas metadata y filtros. Si falla solo al bajar de 384 a 64 dimensiones, quizá encontraste el límite de compresión de tu caso.

Dónde volverá a aparecer

Concepto	Dónde vuelve	Para qué
Índices vectoriales	Capítulo 08.	Guardar y buscar millones de vectores con filtros.
Chunking	Capítulo 09.	Elegir la unidad que recupera el RAG.
Groundedness	Capítulo 10.	Ver si la respuesta se apoya en fragmentos correctos.
Memoria de agentes	Facsímil 05.	Recuperar recuerdos útiles sin meter todo en contexto.
Evaluación	Facsímil 07.	Medir ranking, calibración y calidad real.

Dónde solía tropezar yo

Error	Por qué es un error	Antídoto
Pensar que más similitud siempre significa mejor respuesta	La similitud mide cercanía aproximada, no utilidad ni vigencia.	Mirar documento, fecha, permisos y pregunta concreta.
Indexar documentos enormes	Recuperas un bloque parecido pero poco accionable.	Probar secciones o chunks con título y metadata.
Cambiar modelo sin reindexar	Los vectores nuevos pueden no ser compatibles con los antiguos.	Versionar modelo, dimensión, normalización y fecha.
Elegir dimensión por tamaño aparente	3072 dimensiones no garantizan mejor producto que 768 en tu corpus.	Comparar dimensión contra Recall@k, MRR, nDCG, coste y latencia.
Evaluar con tres consultas bonitas	El sistema parece bueno solo porque las pruebas eran fáciles.	Crear un set de consultas reales con respuestas esperadas.
Olvidar filtros	Un resultado semánticamente cercano puede ser de otro curso, cliente o versión.	Combinar similitud con metadata y permisos.
Subir top-k sin pensar	Más resultados pueden meter ruido en el LLM y subir coste.	Medir recall@k y calidad de respuesta final.

Manos a la obra

Vamos a construir un buscador semántico mínimo con sentence-transformers. El objetivo no es montar una base vectorial todavía; eso viene en el capítulo 08. Aquí queremos ver el mecanismo: documentos, embeddings, normalización, coseno, top-k, MMR, evaluación y comparación de dimensiones.

La práctica recorta el vector a 32, 64, 128 y 384 dimensiones para enseñar el intercambio entre memoria y calidad. En producción solo deberías reducir dimensión si el modelo o el proveedor lo soporta, o si tu evaluación demuestra que el recorte no rompe tu caso.

Instalación:

python -m pip install -U sentence-transformers numpy

Guarda esto como buscar_semanticamente.py:

from sentence_transformers import SentenceTransformer
import numpy as np


DOCUMENTOS = [
    {
        "id": "doc-01",
        "titulo": "Restablecer acceso al campus virtual",
        "texto": (
            "Si no puedes entrar, revisa doble factor "
            "y recupera contraseña."
        ),
        "curso": "2026",
    },
    {
        "id": "doc-02",
        "titulo": "Solicitar certificado académico",
        "texto": "El certificado se descarga desde secretaría virtual.",
        "curso": "2026",
    },
    {
        "id": "doc-03",
        "titulo": "Problemas con el correo institucional",
        "texto": (
            "Para recuperar el correo, actualiza contraseña "
            "y verifica MFA."
        ),
        "curso": "2026",
    },
    {
        "id": "doc-04",
        "titulo": "Calendario de matrícula",
        "texto": (
            "La matrícula ordinaria se abre en julio "
            "y la ampliación en septiembre."
        ),
        "curso": "2025",
    },
    {
        "id": "doc-05",
        "titulo": "Activar cuenta de estudiante",
        "texto": (
            "La cuenta se activa con DNI, código de admisión "
            "y teléfono."
        ),
        "curso": "2026",
    },
]

EVAL = [
    {
        "consulta": "no puedo entrar al campus",
        "relevantes": {"doc-01"},
    },
    {
        "consulta": "necesito el certificado de notas",
        "relevantes": {"doc-02"},
    },
    {
        "consulta": "se me ha bloqueado el correo",
        "relevantes": {"doc-03"},
    },
]

DIMENSIONES = [32, 64, 128, 384]


def normalizar(matriz):
    normas = np.linalg.norm(matriz, axis=1, keepdims=True)
    return matriz / np.maximum(normas, 1e-12)


def top_k(consulta_vec, documento_vecs, k):
    scores = documento_vecs @ consulta_vec
    orden = np.argsort(-scores)[:k]
    return [(int(i), float(scores[i])) for i in orden]


def mmr(consulta_vec, documento_vecs, candidatos, k, lambda_igualdad=0.75):
    elegidos = []
    candidatos = list(candidatos)

    while candidatos and len(elegidos) < k:
        mejor = None
        mejor_score = -10**9

        for idx in candidatos:
            relevancia = float(documento_vecs[idx] @ consulta_vec)
            diversidad = 0.0
            if elegidos:
                diversidad = max(
                    float(documento_vecs[idx] @ documento_vecs[j])
                    for j in elegidos
                )
            score = (
                lambda_igualdad * relevancia
                - (1 - lambda_igualdad) * diversidad
            )
            if score > mejor_score:
                mejor = idx
                mejor_score = score

        elegidos.append(mejor)
        candidatos.remove(mejor)

    return elegidos


def recall_at_k(resultados, relevantes, k):
    recuperados = {doc_id for doc_id, _score in resultados[:k]}
    return bool(recuperados & relevantes)


def reciprocal_rank(resultados, relevantes):
    for posicion, (doc_id, _score) in enumerate(resultados, start=1):
        if doc_id in relevantes:
            return 1 / posicion
    return 0.0


def limitar_dimension(matriz, dimension):
    recortada = matriz[:, :dimension]
    return normalizar(recortada)


def memoria_gb(num_vectores, dimension, bytes_por_numero=4):
    bytes_totales = num_vectores * dimension * bytes_por_numero
    return bytes_totales / 1_000_000_000


def evaluar_dimension(modelo, doc_vecs_full, dimension):
    doc_vecs = limitar_dimension(doc_vecs_full, dimension)
    recalls = []
    reciprocal_ranks = []

    for caso in EVAL:
        consulta_full = modelo.encode(
            [caso["consulta"]],
            convert_to_numpy=True,
        )
        consulta_vec = limitar_dimension(consulta_full, dimension)[0]
        ranking = top_k(consulta_vec, doc_vecs, k=3)
        resultados = [
            (DOCUMENTOS[idx]["id"], score)
            for idx, score in ranking
        ]
        recalls.append(recall_at_k(resultados, caso["relevantes"], k=3))
        reciprocal_ranks.append(
            reciprocal_rank(resultados, caso["relevantes"])
        )

    return {
        "dimension": dimension,
        "recall@3": sum(recalls) / len(recalls),
        "mrr": sum(reciprocal_ranks) / len(reciprocal_ranks),
        "gb_1m_float32": memoria_gb(1_000_000, dimension),
    }


def main():
    modelo = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
    textos = [f"{d['titulo']}. {d['texto']}" for d in DOCUMENTOS]

    doc_vecs = modelo.encode(textos, convert_to_numpy=True)
    doc_vecs = normalizar(doc_vecs)

    print("Dimensión:", doc_vecs.shape[1])
    print()

    aciertos = 0
    for caso in EVAL:
        consulta_vec = modelo.encode(
            [caso["consulta"]],
            convert_to_numpy=True,
        )
        consulta_vec = normalizar(consulta_vec)[0]

        ranking = top_k(consulta_vec, doc_vecs, k=4)
        reranked = mmr(
            consulta_vec,
            doc_vecs,
            [idx for idx, _score in ranking],
            k=3,
        )

        resultados = [
            (DOCUMENTOS[idx]["id"], score)
            for idx, score in ranking
        ]
        aciertos += recall_at_k(resultados, caso["relevantes"], k=3)

        print("Consulta:", caso["consulta"])
        print("Top por coseno:")
        for idx, score in ranking[:3]:
            doc = DOCUMENTOS[idx]
            print(" ", round(score, 3), doc["id"], doc["titulo"])

        print("Top con MMR:")
        for idx in reranked:
            doc = DOCUMENTOS[idx]
            print(" ", doc["id"], doc["titulo"])
        print()

    print("Recall@3:", round(aciertos / len(EVAL), 3))
    print()
    print("Comparación por dimensión")

    for fila in [
        evaluar_dimension(modelo, doc_vecs, dimension)
        for dimension in DIMENSIONES
    ]:
        print(
            fila["dimension"],
            "dims",
            "recall@3=",
            round(fila["recall@3"], 3),
            "mrr=",
            round(fila["mrr"], 3),
            "GB/1M=",
            round(fila["gb_1m_float32"], 3),
        )


if __name__ == "__main__":
    main()

Salida esperada aproximada:

Dimensión: 384

Consulta: no puedo entrar al campus
Top por coseno:
  0.62 doc-01 Restablecer acceso al campus virtual
  0.39 doc-05 Activar cuenta de estudiante
  0.27 doc-03 Problemas con el correo institucional
Top con MMR:
  doc-01 Restablecer acceso al campus virtual
  doc-05 Activar cuenta de estudiante
  doc-03 Problemas con el correo institucional

Recall@3: 1.0

Comparación por dimensión
32 dims recall@3= 1.0 mrr= 0.833 GB/1M= 0.128
64 dims recall@3= 1.0 mrr= 1.0 GB/1M= 0.256
128 dims recall@3= 1.0 mrr= 1.0 GB/1M= 0.512
384 dims recall@3= 1.0 mrr= 1.0 GB/1M= 1.536

Los números exactos pueden variar según versión de modelo y librería. Lo que no debe variar es la lectura: si 64 dimensiones mantienen recall y MRR para tu caso, quizá no necesitas guardar 384; si al bajar aparecen errores con documentos parecidos, el ahorro no compensa.

Prueba cuatro cambios: filtra curso == "2026", sube k de 3 a 5, añade un documento obsoleto muy parecido y cambia DIMENSIONES para incluir 16 o 256. Si el ranking mejora pero la respuesta de producto empeora, acabas de ver por qué búsqueda semántica, dimensión y gobernanza de datos tienen que ir juntas.

Cómo encaja todo

graph TD
    subgraph "Capítulo 7: embeddings y búsqueda semántica"
        INPUT["Texto, consulta<br/>o documento"]
        MODEL["Modelo de embeddings"]
        DIM["Dimensión d"]
        VECTOR["Vector en R^d"]
        METRIC["Coseno o producto punto"]
        TOPK["Ranking top-k"]
        EVAL["Recall@k, MRR y nDCG"]
        MMR["Diversidad y MMR"]
    end
    subgraph "Viene de antes"
        TOKENS["Tokens y coste (F4C3)"]
        CARDS["Model cards (F4C4)"]
        CLOUD["Local, cloud o GPU (F4C6)"]
        TRANS["Embeddings internos<br/>(F3C2)"]
    end
    subgraph "Sigue después"
        VECTORDB["Bases vectoriales (F4C8)"]
        RAG["RAG básico (F4C9)"]
        RAGEVAL["Evaluar RAG (F4C10)"]
        AGMEM["Memoria de agentes (F5)"]
    end

    TOKENS -->|"limitar contexto y coste de"| INPUT
    CARDS -->|"ayudar a elegir"| MODEL
    CLOUD -->|"decidir dónde ejecutar"| MODEL
    TRANS -->|"explicar origen de"| VECTOR
    INPUT -->|"se transforma con"| MODEL
    MODEL -->|"fija"| DIM
    DIM -->|"determina ancho de"| VECTOR
    VECTOR -->|"se compara mediante"| METRIC
    METRIC -->|"ordena en"| TOPK
    TOPK -->|"se mide con"| EVAL
    TOPK -->|"puede diversificarse con"| MMR
    TOPK -->|"alimenta"| VECTORDB
    TOPK -->|"aporta contexto a"| RAG
    EVAL -->|"prepara"| RAGEVAL
    VECTOR -->|"puede ser memoria de"| AGMEM

    style INPUT fill:#F5F5F5,stroke:#000000,stroke-width:2
    style MODEL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style DIM fill:#F5F5F5,stroke:#000000,stroke-width:2
    style VECTOR fill:#F5F5F5,stroke:#000000,stroke-width:2
    style METRIC fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TOPK fill:#F5F5F5,stroke:#000000,stroke-width:2
    style EVAL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style MMR fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TOKENS stroke-dasharray: 5 5
    style CARDS stroke-dasharray: 5 5
    style CLOUD stroke-dasharray: 5 5
    style TRANS stroke-dasharray: 5 5
    style VECTORDB stroke-dasharray: 5 5
    style RAG stroke-dasharray: 5 5
    style RAGEVAL stroke-dasharray: 5 5
    style AGMEM stroke-dasharray: 5 5

Vocabulario aprendido

Término	Definición
Embedding	Vector que representa una entrada para compararla con otras.
Búsqueda semántica	Búsqueda que recupera por cercanía aproximada de significado.
Similitud coseno	Medida de alineación entre dos vectores.
Dimensión de embedding	Número de componentes numéricos que tiene cada vector.
Top-k	Primeros $k$ resultados según una puntuación.
Vector normalizado	Vector reescalado para tener norma 1.
ANN	Búsqueda aproximada de vecinos cercanos.
HNSW	Índice por grafo usado para búsqueda vectorial aproximada.
FAISS	Biblioteca de Meta para búsqueda y clustering de vectores.
Recall@k	Métrica que mira si aparece un resultado correcto entre los $k$ primeros.
MRR	Métrica que premia que el primer resultado correcto aparezca arriba.
nDCG@k	Métrica que evalúa orden y grados de relevancia en los primeros $k$ resultados.
Hard negative	Documento parecido pero incorrecto que prueba si el embedding discrimina bien.
MMR	Técnica para equilibrar relevancia y diversidad.

Antes de pasar página

En resumen

Idea fuerza	Detalle
Un embedding es una coordenada útil.	Convierte texto u otros objetos en vectores comparables, no en verdad garantizada.
La dimensión tiene coste de ingeniería.	Más dimensiones implican más memoria, cómputo, latencia e índice; solo compensan si mejoran métricas reales.
La búsqueda semántica es ranking.	Consulta y documentos se vectorizan, se comparan y se ordenan por una métrica.
La unidad indexada decide mucho.	Documento, sección, párrafo o chunk cambian la calidad del resultado.
La escala obliga a elegir índice.	Exacto es simple; ANN reduce latencia a cambio de aproximación.
Sin evaluación solo hay intuición.	Recall@k, MRR, nDCG y hard negatives separan demo bonita de sistema útil.

Para saber más

Cohere. (2026). Introduction to Embeddings at Cohere. https://docs.cohere.com/v2/docs/embeddings

Google. (2026). Gemini API: Embeddings. https://ai.google.dev/gemini-api/docs/embeddings

Johnson, J., Douze, M. y Jégou, H. (2019). Billion-Scale Similarity Search with GPUs. IEEE Transactions on Big Data, 7(3), 535-547. https://doi.org/10.1109/TBDATA.2019.2921572

Kusupati, A. et al. (2022). Matryoshka Representation Learning. https://arxiv.org/abs/2205.13147

Malkov, Y. A. y Yashunin, D. A. (2020). Efficient and Robust Approximate Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs. IEEE TPAMI, 42(4), 824-836. https://doi.org/10.1109/TPAMI.2018.2889473

Muennighoff, N., Tazi, N., Magne, L. y Reimers, N. (2023). MTEB: Massive Text Embedding Benchmark. https://arxiv.org/abs/2210.07316

OpenAI. (2026). text-embedding-3-large. https://developers.openai.com/api/docs/models/text-embedding-3-large

OpenAI. (2026). Vector embeddings. https://platform.openai.com/docs/guides/embeddings

Reimers, N. y Gurevych, I. (2019). Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks. Proceedings of EMNLP, 3982-3992. https://doi.org/10.18653/v1/D19-1410

Sentence Transformers. (2026). Semantic Search. https://sbert.net/examples/applications/semantic-search/README.html

Thakur, N., Reimers, N., Rücklé, A., Srivastava, A. y Gurevych, I. (2021). BEIR: A Heterogeneous Benchmark for Zero-shot Evaluation of Information Retrieval Models. NeurIPS Datasets and Benchmarks. https://arxiv.org/abs/2104.08663

Voyage AI. (2026). Text Embeddings. https://docs.voyageai.com/docs/embeddings

Notas

OpenAI. (2026). Vector embeddings. https://platform.openai.com/docs/guides/embeddings. Consultado el 25 de mayo de 2026. ↩
OpenAI. (2026). text-embedding-3-large. https://developers.openai.com/api/docs/models/text-embedding-3-large. Consultado el 25 de mayo de 2026. ↩
Google. (2026). Gemini API: Embeddings. https://ai.google.dev/gemini-api/docs/embeddings. Consultado el 25 de mayo de 2026. ↩
Cohere. (2026). Introduction to Embeddings at Cohere. https://docs.cohere.com/v2/docs/embeddings. Consultado el 25 de mayo de 2026. ↩
Voyage AI. (2026). Text Embeddings. https://docs.voyageai.com/docs/embeddings. Consultado el 25 de mayo de 2026. ↩
Sentence Transformers. (2026). Semantic Search. https://sbert.net/examples/applications/semantic-search/README.html. Consultado el 25 de mayo de 2026. ↩
Reimers, N. y Gurevych, I. (2019). Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks. Proceedings of EMNLP, 3982-3992. https://doi.org/10.18653/v1/D19-1410. ↩
Johnson, J., Douze, M. y Jégou, H. (2019). Billion-Scale Similarity Search with GPUs. IEEE Transactions on Big Data, 7(3), 535-547. https://doi.org/10.1109/TBDATA.2019.2921572. ↩
Malkov, Y. A. y Yashunin, D. A. (2020). Efficient and Robust Approximate Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs. IEEE TPAMI, 42(4), 824-836. https://doi.org/10.1109/TPAMI.2018.2889473. ↩
Thakur, N., Reimers, N., Rücklé, A., Srivastava, A. y Gurevych, I. (2021). BEIR: A Heterogeneous Benchmark for Zero-shot Evaluation of Information Retrieval Models. NeurIPS Datasets and Benchmarks. https://arxiv.org/abs/2104.08663. ↩
Kusupati, A. et al. (2022). Matryoshka Representation Learning. https://arxiv.org/abs/2205.13147. El trabajo propone aprender representaciones que funcionan a varias longitudes anidadas. ↩
Cohere (2026), documentación de embeddings citada en la tabla de estado del arte. ↩
Thakur et al. (2021) proponen BEIR para evaluar recuperación en tareas heterogéneas. Muennighoff, N., Tazi, N., Magne, L. y Reimers, N. (2023). MTEB: Massive Text Embedding Benchmark. https://arxiv.org/abs/2210.07316. MTEB compara embeddings en clasificación, clustering, retrieval, reranking, similitud semántica y otras tareas. ↩

Capítulo 08

Facsímil 4 · La caja de herramientas

Capítulo 08: Bases vectoriales, filtros y búsqueda híbrida

Cuando el vector deja de ser el problema

En el capítulo 07 construimos la pieza básica: convertir textos en vectores, compararlos y ordenar resultados. Eso ya permite hacer una búsqueda semántica pequeña. Pero en cuanto el sistema deja de ser una demo, aparece otra pregunta: dónde viven esos vectores, cómo se filtran, cómo se actualizan, cómo se borran y cómo sabemos que el índice no está devolviendo resultados bonitos pero equivocados.

Imagina una universidad con miles de documentos internos. Hay normativa de 2024, 2025 y 2026; manuales para estudiantes y profesorado; documentos públicos y documentos solo visibles para equipos concretos. La consulta "no puedo entrar a Moodle con doble factor" no puede devolver cualquier texto parecido. Debe devolver documentos vigentes, del curso correcto y visibles para la persona que pregunta.

Una base vectorial no es "una carpeta de embeddings". Es el lugar donde se cruzan similitud, filtros, permisos, versiones, índices, latencia, borrado y evaluación. Si esta pieza está mal diseñada, el RAG del capítulo 09 heredará el problema aunque el modelo generativo sea excelente.

Estado del arte con fecha de corte

Fecha de corte: 25 de mayo de 2026.
Fuentes consultadas ese día: documentación oficial de Qdrant, pgvector, Weaviate, Milvus y Pinecone; y trabajos académicos sobre FAISS, HNSW, cuantización de producto, BM25 y fusión de rankings.

Lo estable es la arquitectura: guardar vectores con identificadores, texto y metadata; construir índices; filtrar candidatos; combinar señales densas y léxicas; medir recall y latencia. Lo cambiante son APIs concretas, parámetros, límites por plan, soporte de filtros, algoritmos de índice, modelos integrados y costes de almacenamiento.

Fuente	Qué aporta	Cómo usarla
FAISS.¹	Muestra técnicas de búsqueda eficiente de vectores a gran escala.	Para entender por qué no basta hacer producto punto contra todo cuando crece el corpus.
HNSW.²	Formaliza un índice por grafo usado por muchas bases vectoriales.	Para entender el intercambio entre memoria, construcción, rapidez y recall.
Qdrant.³	Explica que índice vectorial e índice de payload resuelven partes distintas del problema.	Para no confundir "tengo HNSW" con "mis filtros ya van bien".
pgvector.⁴	Integra búsqueda vectorial dentro de PostgreSQL con operadores de distancia e índices HNSW e IVFFlat.	Para proyectos donde transacciones, SQL, joins y vectores conviven en la misma base.
Weaviate.⁵	Documenta búsqueda híbrida que combina vector y BM25F mediante fusión configurable.	Para ver el patrón denso + léxico sin construir todo a mano.
Milvus.⁶	Distingue filtrado estándar e iterativo en búsqueda vectorial con metadata.	Para razonar sobre filtros complejos y latencia.
Pinecone.⁷	Compara usar un índice híbrido único frente a índices densos y dispersos separados.	Para entender que "híbrido" también es una decisión de arquitectura.

Qué no es una base vectorial

Una base vectorial no arregla embeddings malos. Si el modelo coloca cerca documentos que no deberían estarlo, el índice solo acelerará ese error. Tampoco arregla un mal troceado: si guardas párrafos sin título, sin sección y sin fecha, recuperarás fragmentos pobres con mucha rapidez.

Tampoco es una base de conocimiento completa. El vector no sustituye al texto original, a las citas, a las reglas de acceso, al historial de versiones ni al sistema que decide si un documento está vigente. La base vectorial guarda una representación para buscar; la verdad documental sigue viviendo en el contenido y en la metadata.

Y no es siempre la herramienta adecuada. Para cien documentos, una búsqueda exacta en memoria puede bastar. Para datos relacionales con filtros complejos, PostgreSQL con pgvector puede ser suficiente. Para millones de fragmentos, alta concurrencia, filtros frecuentes o múltiples señales de ranking, conviene pensar en una base vectorial dedicada o en un buscador que combine índice invertido y vectores.

Qué sí es: un contrato de recuperación

Ejemplo de fórmula. Un registro vectorial debería parecerse a esto:

r_i = (id_i,\; v_i,\; texto_i,\; m_i,\; version_i)

Símbolo	Significado	Ejemplo
$r_i$	Registro número $i$ .	Fragmento de una normativa.
$id_i$	Identificador estable.	`normativa-2026#sec-04`.
$v_i$	Vector del fragmento.	768 números `float32`.
$texto_i$	Texto recuperable o puntero al texto.	Párrafo que se pasará al RAG.
$m_i$	Metadata o payload.	`curso=2026`, `rol=estudiante`, `vigente=true`.
$version_i$	Versión de embedding y documento.	`embed-v3-large@2026-05-25`.

La búsqueda con filtro se expresa así:

\operatorname{TopK}(q, C, F, k) = \{r_{(1)}, \dots, r_{(k)}\}

r_{(j)} \in C,\quad F(m_{(j)}) = 1,\quad s(q, v_{(1)}) \ge \dots \ge s(q, v_{(k)})

Símbolo	Significado	Ejemplo
$q$	Vector de la consulta.	Embedding de "acceso a Moodle".
$C$	Colección donde buscamos.	Fragmentos de documentación interna.
$F$	Función de filtro sobre metadata.	`curso == 2026 and vigente == true`.
$m_{(j)}$	Metadata del resultado en posición $j$ .	Curso, idioma, rol, fuente.
$s(q,v)$	Puntuación de similitud.	Coseno o producto punto.
$k$	Número de resultados devueltos.	8 fragmentos para un RAG.

Esta fórmula tiene una lección importante: el filtro no es decoración posterior. Forma parte de lo que significa "resultado válido". Si el sistema encuentra el fragmento más parecido del mundo pero no cumple F, ese resultado no debería existir para la consulta.

El coste real: vectores, índices y payload

En el capítulo anterior calculamos el coste bruto de guardar vectores.

Ejemplo de fórmula. Ahora añadimos lo que suele olvidarse:

M_{\text{total}} \approx N \cdot d \cdot b + M_{\text{índice}} + M_{\text{payload}} + M_{\text{réplicas}}

Símbolo	Significado	Ejemplo
$N$	Número de registros vectoriales.	10 millones de chunks.
$d$	Dimensión del vector.	768 dimensiones.
$b$	Bytes por componente.	4 bytes en `float32`, 2 en `float16`.
$M_{\text{índice}}$	Memoria del índice ANN.	Grafo HNSW o listas IVF.
$M_{\text{payload}}$	Metadata, texto corto, ids y estructuras auxiliares.	Fechas, permisos, fuente, idioma.
$M_{\text{réplicas}}$	Copias por disponibilidad o rendimiento.	Dos réplicas duplican parte del coste.

Con 10 millones de vectores de 768 dimensiones en float32, solo el bloque vectorial ocupa alrededor de 30,72 GB. Eso no incluye índice, payload, logs, réplicas, snapshots ni espacio temporal para reconstruir índices. Por eso la dimensión del capítulo 07 y la operación del capítulo 06 vuelven aquí con fuerza.

La selectividad del filtro también importa:

\sigma(F) = \frac{|\{r_i \in C : F(m_i)=1\}|}{|C|}

Símbolo	Significado	Ejemplo
$\sigma(F)$	Fracción de la colección que pasa el filtro.	0,02 si quedan 2 de cada 100.
$	C	$
$	{...}	$

Un filtro con $\sigma=0{,}9$ apenas reduce el problema. Uno con $\sigma=0{,}001$ puede romper supuestos del índice aproximado si no está bien planificado. Las bases vectoriales serias dedican mucha ingeniería a combinar índice vectorial e índice de metadata porque las dos piezas tiran en direcciones distintas.

Cómo funciona por dentro

Una base vectorial tiene dos rutas principales: ingesta y consulta. En ingesta recibe texto, genera o recibe embeddings, valida el esquema, guarda payload y actualiza índices. En consulta recibe una pregunta, genera el vector de consulta, aplica filtros, busca candidatos, fusiona señales si hay búsqueda híbrida y devuelve resultados con puntuaciones y metadata.

La imagen resume el punto central: una consulta real atraviesa dos mundos. Por un lado está la cercania semántica; por otro, el contrato operativo que decide si ese resultado se puede usar. El producto final no debería aceptar un resultado solo porque su vector está cerca.

Índices: exacto, HNSW, IVFFlat y compresión

La búsqueda exacta compara la consulta con todos los vectores. Es fácil de razonar y sirve como referencia de calidad, pero su coste crece con $N \cdot d$ . A partir de cierto tamaño, necesitamos índices aproximados de vecinos cercanos.

Opción	Idea	Parámetros típicos	Qué se mide
Exacta	Comparar contra todos los vectores que pasan el filtro.	Sin índice ANN.	Calidad máxima, latencia base.
HNSW	Navegar un grafo de vecinos por capas.	`M`, `ef_construction`, `ef_search`.	Recall frente a memoria y p95.
IVFFlat	Dividir vectores en listas y buscar solo algunas.	`lists`, `probes`.	Recall frente a velocidad y coste de build.
PQ	Comprimir vectores por subespacios.	Número de subcuantizadores y bits.	Ahorro de memoria frente a pérdida de precisión.

HNSW suele dar buen equilibrio de recall y latencia, pero no es gratis: guarda conexiones entre vectores y consume memoria adicional.⁸ IVFFlat puede construir más rápido y ocupar menos, pero requiere elegir listas y probes con cuidado; la documentación de pgvector lo explica como un intercambio entre rendimiento y recall.⁹ La cuantización de producto reduce memoria representando subespacios con códigos compactos, pero introduce aproximación adicional.¹⁰

Un criterio práctico: conserva siempre un modo de evaluación exacta, aunque sea sobre una muestra. Si no puedes comparar el índice aproximado contra el ranking exacto, no sabes si ganar latencia te está costando evidencias importantes.

Filtros: dónde se gana o se rompe la recuperación

Los filtros parecen sencillos hasta que crece el corpus. Filtrar por curso=2026 es fácil; filtrar por tenant, rol, vigente, idioma, producto, region, tipo_documento y fecha ya obliga a planificar.

Hay tres patrones frecuentes:

Patrón	Cómo funciona	Riesgo
Filtrar antes	Primero reduce candidatos por metadata y luego busca vectores.	Si queda muy poco, el índice ANN puede no aportar mucho.
Buscar antes	Primero recupera muchos vecinos y luego descarta por metadata.	Puede perder resultados válidos si estaban fuera del primer lote.
Filtrado integrado	El índice combina metadata y navegación vectorial.	Requiere crear buenos índices de payload y entender selectividad.

Qdrant lo dice de forma muy clara: el índice vectorial acelera la búsqueda vectorial y los índices de payload aceleran filtros; hacen trabajos distintos.¹¹ Milvus también separa filtrado estándar e iterativo porque filtros complejos pueden cambiar mucho la latencia.¹²

Para entenderlo, piensa en una biblioteca. Si buscas "reglamento de prácticas" en toda la biblioteca y luego tiras los libros antiguos, quizá no veas el reglamento correcto porque no entró en el primer top-k. Si primero entras en la estantería "2026" y después buscas por significado, reduces ruido. Pero si la estantería tiene solo tres documentos, un recorrido exacto puede ser mejor que un índice sofisticado.

Búsqueda híbrida: cuando exactitud léxica y semántica se necesitan

Los embeddings son fuertes con sinónimos e intención. BM25 es fuerte con palabras raras, siglas, códigos, nombres propios y errores donde la palabra exacta importa. La búsqueda híbrida combina ambas señales.

BM25, simplificado, puntúa una consulta $Q$ sobre un documento $D$ así:

\operatorname{BM25}(D,Q) = \sum_{t \in Q} \operatorname{IDF}(t) \frac{f(t,D)(k_1 + 1)} {f(t,D) + k_1(1-b+b\frac{|D|}{avgdl})}

Símbolo	Significado	Ejemplo
$t$	Término de la consulta.	`MFA`, `Moodle`, `matrícula`.
$f(t,D)$	Veces que aparece el término en el documento.	3 apariciones de `Moodle`.
$\operatorname{IDF}(t)$	Peso de rareza del término en la colección.	`MFA` pesa más que `el`.
$	D	$
$avgdl$	Longitud media de documentos.	220 tokens.
$k_1, b$	Parámetros de saturación y longitud.	Valores habituales: $k_1=1{,}2$ , $b=0{,}75$ .

BM25 viene de la familia probabilística de recuperación de información y sigue siendo una base fuerte para búsqueda léxica.¹³ La parte densa recupera significado; la parte léxica protege términos que no deberían diluirse.

Una forma sencilla de fusionar rankings es RRF:

\operatorname{RRF}(d) = \sum_{j=1}^{S} \frac{1}{k_0 + \operatorname{rank}_j(d)}

Símbolo	Significado	Ejemplo
$d$	Documento candidato.	`doc-01`.
$S$	Número de sistemas que devuelven ranking.	Vectorial y BM25: $S=2$ .
$\operatorname{rank}_j(d)$	Posicion del documento en el sistema $j$ .	1 en BM25, 5 en vectorial.
$k_0$	Constante que suaviza el peso de la posición.	60 es un valor comun en RRF.

RRF funciona bien porque no exige que las puntuaciones de BM25 y embeddings estén en la misma escala.¹⁴ Eso es práctico: un coseno de 0,72 y un BM25 de 11,4 no son directamente comparables, pero sus posiciones en rankings sí pueden combinarse.

Consulta	Vector denso ayuda	BM25 ayuda	Hibrido evita
"no puedo entrar al campus"	Encuentra "restablecer acceso a Moodle".	Poco, si no comparte palabras.	Quedarse solo con sinónimos.
"error SAML 403 Moodle"	Puede entender "login".	Protege `SAML` y `403`.	Perder códigos exactos.
"matrícula 2026 septiembre"	Relaciona matrícula con calendario.	Protege `2026` y `septiembre`.	Devolver normativa antigua.
"API pagos webhook reintentos"	Relaciona integración y eventos.	Protege `webhook`.	Mezclar artículos de producto.

Weaviate expone búsqueda híbrida como combinacion de resultados vectoriales y BM25F por fusión configurable.¹⁵ Pinecone documenta dos caminos: índice híbrido único o índices densos y dispersos separados, cada uno con sus ventajas operativas.¹⁶ La idea pedagógica es la misma: no hay que elegir religión entre vector y palabras exactas; hay que medir cuál combina mejor en tu corpus.

Diseñar el esquema de una colección

Antes de indexar, conviene escribir el contrato. Una colección debería responder estas preguntas:

Decisión	Pregunta técnica	Mala señal
Identificador	Qué id estable permite reindexar sin duplicar?	IDs aleatorios sin relación con fuente y sección.
Texto	Guardamos texto completo o puntero?	Resultados sin cita recuperable.
Metadata	Qué campos se filtran de verdad?	Guardar metadata bonita que nunca se indexa.
Versión	Qué modelo, dimensión y fecha genero el vector?	Mezclar embeddings incompatibles.
Permisos	El filtro de acceso vive en la consulta?	Filtrar después de mostrar candidatos.
Vigencia	Cómo caduca o se reemplaza un documento?	Resultados de años anteriores en top-k.
Borrado	Qué significa borrar: vector, payload, texto y cache?	Quedan fragmentos recuperables por accidente.

Si usas PostgreSQL con pgvector, el esquema puede ser explícito:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE chunks (
  id text PRIMARY KEY,
  source_id text NOT NULL,
  chunk_text text NOT NULL,
  embedding vector(768) NOT NULL,
  curso integer NOT NULL,
  rol text NOT NULL,
  vigente boolean NOT NULL,
  embedding_model text NOT NULL,
  indexed_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX chunks_embedding_hnsw
ON chunks USING hnsw (embedding vector_cosine_ops);

CREATE INDEX chunks_metadata
ON chunks (curso, rol, vigente);

SELECT id, chunk_text
FROM chunks
WHERE curso = 2026
  AND rol IN ('estudiante', 'publico')
  AND vigente = true
ORDER BY embedding <=> $1
LIMIT 8;

El detalle importante no es memorizar esta sintaxis. El detalle es que el campo vectorial, los filtros y la versión viven juntos. Si cambias el modelo de embedding o la dimensión, no estás "actualizando una columna"; estás cambiando el espacio de búsqueda.

Cómo trabajar con bases vectoriales con criterio

Una base vectorial en producción necesita disciplina operativa. La parte difícil no es insertar el primer vector; es mantener el sistema correcto cuando cambian documentos, permisos, modelos y volumen.

Práctica	Qué haces	Por qué importa
IDs deterministas	Derivas el id de fuente, sección y versión.	Permite `upsert` idempotente y evita duplicados.
Versionado de embeddings	Guardas modelo, dimensión, normalización y fecha.	Permite reindexar y comparar variantes.
Doble índice temporal	Construyes el nuevo índice junto al anterior.	Evita cortar servicio mientras migras.
Borrado verificable	Compruebas que ids borrados no vuelven en top-k.	Evita respuestas con contenido retirado.
Filtros obligatorios	El backend añade filtros de permisos siempre.	El cliente no decide qué puede ver.
Evaluación continua	Mides recall, p95, coste y errores por segmento.	Detecta degradación antes que usuarios y usuarias.
Trazas de retrieval	Guardas consulta, filtros, ids, scores y versión.	Permite explicar por qué se recuperó algo.

Una buena pregunta de ingeniería: si mañana cambiamos de all-MiniLM-L6-v2 a otro modelo de 1024 dimensiones, ¿qué pasos exactos hay que hacer? Si la respuesta no incluye reindexado, evaluación, cambio de versión y plan de retirada del índice anterior, falta diseño.

Evaluar una base vectorial

Aquí evaluamos dos capas: la calidad de recuperación y la calidad operativa. La primera pregunta es "encuentro lo correcto?". La segunda es "lo encuentro dentro del contrato de producto?".

Métrica	Qué mide	Cómo se calcula
Recall ANN@k	Cuánto se parece el índice aproximado al exacto.	Resultados ANN frente a búsqueda exacta.
Recall con filtro@k	Si aparecen documentos correctos cumpliendo metadata.	Casos con filtros obligatorios.
nDCG@k	Si los documentos más útiles suben arriba.	Relevancia graduada por posición.
p50, p95, p99	Latencia normal y de cola.	Tiempos por consulta real.
Tasa de resultados retirados	Cuántos resultados ya no deberían aparecer.	Hits con `vigente=false` o versión antigua.
Cobertura de permisos	Si cada consulta aplica el filtro correcto.	Trazas con usuario, rol y condición.
Coste por consulta	CPU, memoria, GPU o precio cloud.	Coste mensual dividido por consultas útiles.

Una prueba mínima compara tres rankings para las mismas consultas: exacto filtrado, ANN filtrado e híbrido filtrado. Si el ANN pierde documentos que el exacto encuentra, ajustas parámetros o cambias índice. Si el híbrido mejora consultas con siglas pero empeora consultas naturales, ajustas fusión o decides cuándo activarlo.

Dónde volverá a aparecer

Concepto	Dónde vuelve	Para qué
Chunking	Capítulo 09.	Elegir qué unidades guardamos en la base vectorial.
Citas y abstención	Capítulo 09.	No basta recuperar; hay que responder con evidencia.
Evaluación de RAG	Capítulo 10.	Conectar retrieval con calidad final de respuesta.
Agentic RAG	Capítulo 11.	Decidir cuándo hacer varias búsquedas o rutas.
Memoria de agentes	Facsímil 05.	Guardar recuerdos recuperables con filtros y caducidad.

Dónde solía tropezar yo

Error	Por qué es un error	Antídoto
Creer que vector DB equivale a RAG	La base recupera candidatos; no decide chunking, citas, abstención ni respuesta final.	Separar retrieval, contexto y generación.
Filtrar después de recuperar poco	Si pides top-10 global y luego descartas por permisos, puedes quedarte sin el resultado correcto.	Aplicar filtros como parte del plan de búsqueda.
No versionar embeddings	Mezclar modelos o dimensiones hace que las distancias dejen de significar lo mismo.	Guardar `embedding_model`, dimensión y fecha en cada registro.
Olvidar términos exactos	Siglas, códigos, IDs y nombres propios pueden perderse en búsqueda solo densa.	Probar búsqueda híbrida con BM25 o sparse vectors.
Medir solo latencia media	p95 o p99 pueden ser malos aunque la media parezca aceptable.	Medir percentiles y separar consultas con filtros complejos.
No probar borrados	Un índice puede seguir devolviendo contenido retirado si el flujo de borrado falla.	Crear tests de ids retirados y verificar que no aparecen.
Elegir herramienta por moda	Cada base cambia filtros, operación, costes, backup y SQL disponible.	Comparar con una matriz de requisitos reales.

Manos a la obra

Vamos a construir una mini base vectorial en memoria. No pretende competir con Qdrant, pgvector o Milvus; sirve para entender el contrato: documentos, metadata, filtros, ranking denso, BM25, fusión RRF y evaluación.

La práctica usa embeddings deterministas muy simples para no depender de una API externa. En un proyecto real, sustituirías vector_de_texto por el modelo de embeddings del capítulo 07, y el almacenamiento en memoria por una base vectorial real.

Guarda esto como mini_base_vectorial.py:

from collections import Counter, defaultdict
import hashlib
import math
import re
import unicodedata


DIM = 32
K_RRF = 60

DOCUMENTOS = [
    {
        "id": "doc-01",
        "titulo": "Acceso al campus virtual con doble factor",
        "texto": "Moodle requiere MFA y recuperacion de contraseña.",
        "curso": 2026,
        "rol": "estudiante",
        "vigente": True,
    },
    {
        "id": "doc-02",
        "titulo": "Calendario de matricula 2026",
        "texto": "La ampliacion de matricula se abre en septiembre.",
        "curso": 2026,
        "rol": "publico",
        "vigente": True,
    },
    {
        "id": "doc-03",
        "titulo": "Correo institucional y doble factor",
        "texto": "El correo se desbloquea revisando MFA y contraseña.",
        "curso": 2026,
        "rol": "estudiante",
        "vigente": True,
    },
    {
        "id": "doc-04",
        "titulo": "Acceso antiguo al campus virtual",
        "texto": "Procedimiento obsoleto para Moodle en 2024.",
        "curso": 2024,
        "rol": "estudiante",
        "vigente": False,
    },
    {
        "id": "doc-05",
        "titulo": "Manual de Moodle para profesorado",
        "texto": "Crear cuestionarios, bancos de preguntas y rubricas.",
        "curso": 2026,
        "rol": "profesorado",
        "vigente": True,
    },
]

CASOS = [
    {
        "consulta": "no puedo entrar a moodle con mfa",
        "filtro": {"curso": 2026, "vigente": True},
        "esperado": {"doc-01"},
    },
    {
        "consulta": "fechas de matricula septiembre",
        "filtro": {"curso": 2026, "vigente": True},
        "esperado": {"doc-02"},
    },
    {
        "consulta": "correo bloqueado doble factor",
        "filtro": {"curso": 2026, "vigente": True},
        "esperado": {"doc-03"},
    },
]

SINONIMOS = {
    "moodle": "campus",
    "aula": "campus",
    "virtual": "campus",
    "mfa": "doble_factor",
    "factor": "doble_factor",
    "2fa": "doble_factor",
    "entrar": "acceso",
    "acceder": "acceso",
    "bloqueado": "desbloqueo",
    "desbloquear": "desbloqueo",
}


def normalizar_texto(texto):
    texto = texto.lower()
    texto = unicodedata.normalize("NFD", texto)
    texto = "".join(c for c in texto if unicodedata.category(c) != "Mn")
    tokens = re.findall(r"[a-z0-9_]+", texto)
    return [SINONIMOS.get(t, t) for t in tokens]


def vector_token(token):
    digest = hashlib.sha256(token.encode("utf-8")).digest()
    valores = []
    for i in range(DIM):
        byte = digest[i % len(digest)]
        valores.append((byte / 255.0) * 2 - 1)
    return valores


def normalizar_vector(vector):
    norma = math.sqrt(sum(x * x for x in vector)) or 1.0
    return [x / norma for x in vector]


def vector_de_texto(texto):
    vector = [0.0] * DIM
    for token in normalizar_texto(texto):
        base = vector_token(token)
        vector = [a + b for a, b in zip(vector, base)]
    return normalizar_vector(vector)


def producto_punto(a, b):
    return sum(x * y for x, y in zip(a, b))


def cumple_filtro(doc, filtro):
    return all(doc.get(campo) == valor for campo, valor in filtro.items())


def construir_indice(documentos):
    textos = [d["titulo"] + ". " + d["texto"] for d in documentos]
    tokens_por_doc = [normalizar_texto(t) for t in textos]
    df = defaultdict(int)
    for tokens in tokens_por_doc:
        for token in set(tokens):
            df[token] += 1
    return {
        "vectores": [vector_de_texto(t) for t in textos],
        "tokens": tokens_por_doc,
        "df": df,
        "avgdl": sum(len(t) for t in tokens_por_doc) / len(tokens_por_doc),
    }


def bm25_score(query_tokens, doc_tokens, df, avgdl):
    k1 = 1.2
    b = 0.75
    total_docs = len(DOCUMENTOS)
    frecuencias = Counter(doc_tokens)
    score = 0.0

    for token in query_tokens:
        if token not in frecuencias:
            continue
        numerador = total_docs - df[token] + 0.5
        denominador_idf = df[token] + 0.5
        idf = math.log(1 + numerador / denominador_idf)
        tf = frecuencias[token]
        longitud = len(doc_tokens)
        denominador = tf + k1 * (1 - b + b * longitud / avgdl)
        score += idf * (tf * (k1 + 1)) / denominador

    return score


def ranking_denso(consulta, documentos, indice, filtro):
    consulta_vec = vector_de_texto(consulta)
    filas = []
    for pos, doc in enumerate(documentos):
        if not cumple_filtro(doc, filtro):
            continue
        score = producto_punto(consulta_vec, indice["vectores"][pos])
        filas.append((doc["id"], score))
    return sorted(
        filas,
        key=lambda fila: fila[1],
        reverse=True,
    )


def ranking_bm25(consulta, documentos, indice, filtro):
    query_tokens = normalizar_texto(consulta)
    filas = []
    for pos, doc in enumerate(documentos):
        if not cumple_filtro(doc, filtro):
            continue
        score = bm25_score(
            query_tokens,
            indice["tokens"][pos],
            indice["df"],
            indice["avgdl"],
        )
        filas.append((doc["id"], score))
    return sorted(
        filas,
        key=lambda fila: fila[1],
        reverse=True,
    )


def rrf(rankings):
    acumulado = defaultdict(float)
    for ranking in rankings:
        for posicion, (doc_id, _score) in enumerate(ranking, start=1):
            acumulado[doc_id] += 1 / (K_RRF + posicion)
    return sorted(
        acumulado.items(),
        key=lambda fila: fila[1],
        reverse=True,
    )


def recall_at_k(ranking, esperados, k):
    recuperados = {doc_id for doc_id, _score in ranking[:k]}
    return bool(recuperados & esperados)


def main():
    indice = construir_indice(DOCUMENTOS)
    aciertos = 0

    for caso in CASOS:
        denso = ranking_denso(
            caso["consulta"],
            DOCUMENTOS,
            indice,
            caso["filtro"],
        )
        lexico = ranking_bm25(
            caso["consulta"],
            DOCUMENTOS,
            indice,
            caso["filtro"],
        )
        hibrido = rrf([denso, lexico])
        aciertos += recall_at_k(hibrido, caso["esperado"], k=3)

        print("Consulta:", caso["consulta"])
        print("Filtro:", caso["filtro"])
        print("Top denso:", denso[:3])
        print("Top BM25:", lexico[:3])
        print("Top hibrido:", hibrido[:3])
        print()

    print("Recall hibrido@3:", round(aciertos / len(CASOS), 3))

    sin_filtro = ranking_denso(
        "entrar a moodle",
        DOCUMENTOS,
        indice,
        filtro={},
    )
    print("Sin filtro de vigencia:", sin_filtro[:3])


if __name__ == "__main__":
    main()

Salida esperada aproximada:

Consulta: no puedo entrar a moodle con mfa
Filtro: {'curso': 2026, 'vigente': True}
Top denso: [('doc-01', ...), ('doc-03', ...), ...]
Top BM25: [('doc-01', ...), ...]
Top hibrido: [('doc-01', ...), ...]

Recall hibrido@3: 1.0
Sin filtro de vigencia: [('doc-01', ...), ('doc-04', ...), ...]

La última línea es el aprendizaje. El documento antiguo puede parecer cercano porque habla de Moodle y acceso. Sin filtro de vigencia, el sistema puede recuperar algo semánticamente razonable y funcionalmente incorrecto.

Prueba tres cambios: añade rol="profesorado" al filtro, cambia K_RRF, y crea un documento con el código exacto SAML 403. Verás cuándo BM25 salva una consulta y cuándo el filtro cambia el ranking más que el embedding.

Cómo encaja todo

graph TD
    subgraph "Capítulo 8: bases vectoriales"
        COLLECTION["Colección"]
        RECORD["Registro: id, vector<br/>texto, payload"]
        VINDEX["Índice vectorial"]
        PINDEX["Índice de payload"]
        SPARSE["Índice léxico<br/>o sparse"]
        FILTER["Filtro obligatorio"]
        HYBRID["Búsqueda híbrida"]
        FUSION["Fusión RRF<br/>o pesos"]
        OPS["Upsert, borrado<br/>reindexado"]
        EVAL["Recall, nDCG<br/>p95 y coste"]
    end
    subgraph "Viene de antes"
        EMB["Embeddings (F4C7)"]
        DIM["Dimensión y coste (F4C7)"]
        API["APIs y contratos (F4C2)"]
        LOCAL["Cloud o local (F4C6)"]
    end
    subgraph "Sigue después"
        CHUNK["Chunking (F4C9)"]
        RAG["RAG básico (F4C9)"]
        RAGEVAL["Evaluar RAG (F4C10)"]
        AGMEM["Memoria de agentes (F5)"]
    end

    EMB -->|"generar"| RECORD
    DIM -->|"dimensionar"| VINDEX
    API -->|"definir contrato de"| OPS
    LOCAL -->|"decidir despliegue de"| COLLECTION
    COLLECTION -->|"contener"| RECORD
    RECORD -->|"alimentar"| VINDEX
    RECORD -->|"alimentar"| PINDEX
    RECORD -->|"alimentar"| SPARSE
    PINDEX -->|"aplicar"| FILTER
    VINDEX -->|"devolver candidatos"| HYBRID
    SPARSE -->|"aportar señales exactas"| HYBRID
    FILTER -->|"limitar candidatos"| HYBRID
    HYBRID -->|"combinar con"| FUSION
    FUSION -->|"medir con"| EVAL
    OPS -->|"mantener"| COLLECTION
    COLLECTION -->|"guardar unidades de"| CHUNK
    FUSION -->|"proveer contexto a"| RAG
    EVAL -->|"preparar"| RAGEVAL
    RECORD -->|"servir como memoria para"| AGMEM

    style COLLECTION fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RECORD fill:#F5F5F5,stroke:#000000,stroke-width:2
    style VINDEX fill:#F5F5F5,stroke:#000000,stroke-width:2
    style PINDEX fill:#F5F5F5,stroke:#000000,stroke-width:2
    style SPARSE fill:#F5F5F5,stroke:#000000,stroke-width:2
    style FILTER fill:#F5F5F5,stroke:#000000,stroke-width:2
    style HYBRID fill:#F5F5F5,stroke:#000000,stroke-width:2
    style FUSION fill:#F5F5F5,stroke:#000000,stroke-width:2
    style OPS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style EVAL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style EMB stroke-dasharray: 5 5
    style DIM stroke-dasharray: 5 5
    style API stroke-dasharray: 5 5
    style LOCAL stroke-dasharray: 5 5
    style CHUNK stroke-dasharray: 5 5
    style RAG stroke-dasharray: 5 5
    style RAGEVAL stroke-dasharray: 5 5
    style AGMEM stroke-dasharray: 5 5

Vocabulario aprendido

Término	Definición
Base vectorial	Sistema que guarda vectores y permite recuperarlos por similitud.
Colección	Conjunto de registros con el mismo contrato de vector y metadata.
Payload	Metadata asociada al vector, usada para filtrar y explicar resultados.
Índice vectorial	Estructura que acelera la búsqueda de vecinos cercanos.
HNSW	Índice por grafo navegable para búsqueda aproximada.
IVFFlat	Índice que divide el espacio en listas y busca solo algunas.
Filtro	Condición que limita qué registros pueden entrar en el ranking.
BM25	Ranking léxico basado en frecuencia, rareza y longitud de documento.
Búsqueda híbrida	Combinación de ranking vectorial y ranking léxico.
RRF	Fusión de rankings basada en posiciones.
Upsert	Inserción o actualización idempotente de un registro.

Antes de pasar página

En resumen

Idea fuerza	Detalle
Una base vectorial es un contrato operativo.	Guarda vectores, texto, ids, metadata, versiones e índices.
El filtro forma parte de la respuesta correcta.	Un resultado cercano pero fuera de curso, rol o vigencia no es válido.
El índice aproximado debe compararse con exacto.	Sin baseline exacto, no sabes cuánto recall pierdes por ganar latencia.
La búsqueda híbrida une dos señales.	Embeddings capturan significado; BM25 protege términos exactos.
Operar importa tanto como buscar.	Upsert, borrado, snapshots, reindexado y trazas deciden si el sistema aguanta.
La evaluación debe incluir producto.	Recall, nDCG, filtros, p95, coste y documentos retirados cuentan juntos.

Para saber más

Cormack, G. V., Clarke, C. L. A. y Buettcher, S. (2009). Reciprocal Rank Fusion Outperforms Condorcet and Individual Rank Learning Methods. SIGIR, 758-759. https://doi.org/10.1145/1571941.1572114

Jégou, H., Douze, M. y Schmid, C. (2011). Product Quantization for Nearest Neighbor Search. IEEE Transactions on Pattern Analysis and Machine Intelligence, 33(1), 117-128. https://doi.org/10.1109/TPAMI.2010.57

Johnson, J., Douze, M. y Jégou, H. (2019). Billion-Scale Similarity Search with GPUs. IEEE Transactions on Big Data, 7(3), 535-547. https://doi.org/10.1109/TBDATA.2019.2921572

Milvus. (2026). Filtered Search. https://milvus.io/docs/filtered-search.md

pgvector. (2026). pgvector: Open-source vector similarity search for Postgres. https://github.com/pgvector/pgvector

Pinecone. (2026). Hybrid search. https://docs.pinecone.io/docs/hybrid-search-and-sparse-vectors

Qdrant. (2026). Indexing. https://qdrant.tech/documentation/manage-data/indexing/

Robertson, S. y Zaragoza, H. (2009). The Probabilistic Relevance Framework: BM25 and Beyond. Foundations and Trends in Information Retrieval, 3(4), 333-389. https://doi.org/10.1561/1500000019

Weaviate. (2026). Hybrid search. https://docs.weaviate.io/weaviate/search/hybrid

Notas

Johnson, J., Douze, M. y Jégou, H. (2019). Billion-Scale Similarity Search with GPUs. IEEE Transactions on Big Data, 7(3), 535-547. https://doi.org/10.1109/TBDATA.2019.2921572. ↩
Malkov, Y. A. y Yashunin, D. A. (2020). Efficient and Robust Approximate Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs. IEEE TPAMI, 42(4), 824-836. https://doi.org/10.1109/TPAMI.2018.2889473. ↩
Qdrant. (2026). Indexing. https://qdrant.tech/documentation/manage-data/indexing/. Consultado el 25 de mayo de 2026. ↩
pgvector. (2026). pgvector: Open-source vector similarity search for Postgres. https://github.com/pgvector/pgvector. Consultado el 25 de mayo de 2026. ↩
Weaviate. (2026). Hybrid search. https://docs.weaviate.io/weaviate/search/hybrid. Consultado el 25 de mayo de 2026. ↩
Milvus. (2026). Filtered Search. https://milvus.io/docs/filtered-search.md. Consultado el 25 de mayo de 2026. ↩
Pinecone. (2026). Hybrid search. https://docs.pinecone.io/docs/hybrid-search-and-sparse-vectors. Consultado el 25 de mayo de 2026. ↩
Malkov y Yashunin, 2020. ↩
pgvector, 2026. ↩
Jégou, H., Douze, M. y Schmid, C. (2011). Product Quantization for Nearest Neighbor Search. IEEE TPAMI, 33(1), 117-128. https://doi.org/10.1109/TPAMI.2010.57. ↩
Qdrant, 2026. ↩
Milvus, 2026. ↩
Robertson, S. y Zaragoza, H. (2009). The Probabilistic Relevance Framework: BM25 and Beyond. Foundations and Trends in Information Retrieval, 3(4), 333-389. https://doi.org/10.1561/1500000019. ↩
Cormack, G. V., Clarke, C. L. A. y Buettcher, S. (2009). Reciprocal Rank Fusion Outperforms Condorcet and Individual Rank Learning Methods. SIGIR, 758-759. https://doi.org/10.1145/1571941.1572114. ↩
Weaviate, 2026. ↩
Pinecone, 2026. ↩

Capítulo 09

Facsímil 4 · La caja de herramientas

Capítulo 09: RAG básico: chunking, retrieval, citas y abstención

El momento en que buscar ya no basta

En el capítulo 08 aprendimos a guardar fragmentos, buscarlos con vectores, filtrarlos por metadata y combinar señal densa con BM25. Eso devuelve candidatos. Un RAG hace algo más delicado: convierte esos candidatos en una respuesta útil, citada y capaz de decir “no tengo evidencia suficiente”.

Imagina un asistente para alumnado. La persona pregunta: “¿puedo ampliar matrícula en septiembre si tengo pagos pendientes?”. El sistema no debería inventar una política general. Debe recuperar normativa vigente, decidir qué fragmentos entran en contexto, responder solo con lo que esos fragmentos sostienen y enseñar las fuentes.

RAG significa retrieval-augmented generation: generación aumentada por recuperación. La idea fue formulada como una forma de combinar modelos generativos con memoria no paramétrica recuperada desde un índice externo.¹ En producto, RAG no es una palabra bonita para “chat con PDFs”. Es una arquitectura para que el modelo responda con información que no tiene por entrenamiento, que cambia con el tiempo o que pertenece a una organización concreta.

Cuando decimos “memoria no paramétrica” estamos diciendo algo muy concreto: el conocimiento no está guardado dentro de los pesos del modelo. Está fuera, en documentos, tablas, índices, bases de datos o sistemas que podemos actualizar sin volver a entrenar el modelo.

Estado del arte con fecha de corte

Fecha de corte: 25 de mayo de 2026.
Fuentes consultadas ese día: documentación oficial de OpenAI File Search, LangChain, LlamaIndex, Haystack, Google Vertex AI RAG Engine, Azure AI Search, Pinecone, Weaviate, Qdrant y pgvector; y trabajos académicos sobre RAG, BM25 y fusión de rankings.

Lo estable es el patrón: ingestión, partición, indexado, recuperación, construcción de contexto, generación, citas y evaluación. Lo cambiante son proveedores, límites, APIs, modelos de embeddings, formatos soportados, coste, residencia de datos, rerankers y herramientas gestionadas.

Fuente	Qué aporta	Cómo usarla
RAG original.²	Formaliza el uso de documentos recuperados como memoria externa para generación.	Para entender que RAG no es solo “meter documentos en un prompt”.
OpenAI File Search.³	Herramienta gestionada de la Responses API para buscar archivos en vector stores y devolver contexto al modelo.	Para montar rápido un RAG alojado sin programar todo el retrieval.
LangChain Retrieval.⁴	Describe loaders, splitters, embeddings, vector stores, retrievers y arquitecturas 2-step, agentic e híbridas.	Para componer aplicaciones RAG con piezas intercambiables.
LlamaIndex RAG.⁵	Ordena RAG en loading, indexing, storing, querying y evaluation; introduce Documents, Nodes y retrievers.	Para proyectos centrados en ingestión de datos y gestión de índices.
Haystack pipelines.⁶	Modela RAG como grafo de componentes con ramas, validación y flujos de indexado/consulta.	Para equipos que quieren pipelines explícitos y desplegables.
Vertex AI RAG Engine.⁷	Servicio gestionado de RAG dentro de Vertex AI.	Para entornos Google Cloud donde operación, permisos y plataforma pesan.
Azure AI Search.⁸	Combina búsqueda tradicional, vectorial, semántica, filtros e integración con escenarios generativos.	Para organizaciones ya montadas sobre Azure y Microsoft Learn.
Pinecone y Weaviate.⁹	Bases vectoriales gestionadas con patrones RAG, búsqueda semántica, filtros y opciones híbridas.	Para delegar índice y escalado sin entregar el diseño del sistema.
BM25 y RRF.¹⁰	Dan bases sólidas para retrieval léxico y fusión de rankings.	Para no construir RAG solo con embeddings.

Qué no es RAG

RAG no es subir un PDF a un chat y confiar. Si el PDF se trocea mal, si la búsqueda trae el fragmento equivocado o si el prompt permite responder sin evidencia, el sistema puede fallar con mucha seguridad aparente.

Tampoco es fine-tuning. Ajustar un modelo puede enseñar formato, tono o una tarea repetida; RAG aporta contexto externo en tiempo de consulta. Si la información cambia cada semana, suele ser mejor actualizar documentos e índice que reentrenar.

RAG tampoco elimina la necesidad de permisos. Recuperar un fragmento privado y luego pedir al modelo que “no lo mencione” es una mala frontera. El filtrado debe ocurrir antes de que el texto entre en contexto.

RAG, memoria y entrenamiento no son lo mismo

Esta diferencia es fundamental. Si la mezclamos, acabamos usando RAG para lo que pide entrenamiento, fine-tuning para lo que pide documentos, o “memoria” para cosas que deberían ser permisos, trazas o contexto recuperado.

El modelo base tiene conocimiento en sus pesos. Eso viene del entrenamiento: grandes cantidades de datos, mucho cálculo y una actualización difícil de repetir para una aplicación pequeña. Cuando haces fine-tuning o LoRA, sigues tocando comportamiento aprendido: formato, estilo, patrones de respuesta, especialización en una tarea repetida. RAG, en cambio, no cambia los pesos. Recupera evidencia externa en el momento de la pregunta.

Mecanismo	Dónde vive la información	Cuándo cambia	Para qué sirve
Entrenamiento base	En los pesos del modelo.	Antes de que tú uses el modelo.	Capacidades generales: lenguaje, razonamiento, código, patrones del mundo.
Fine-tuning / LoRA	En pesos ajustados o adaptadores.	Cuando entrenas con ejemplos.	Formato, tono, clasificación estable, tareas repetidas y medibles.
RAG	En un corpus externo recuperable.	Cuando cambian documentos o índices.	Conocimiento privado, vigente, citable o cambiante.
Memoria de conversación	En mensajes previos o resúmenes guardados.	Durante una sesión o entre sesiones si se persiste.	Preferencias, contexto personal y continuidad conversacional.
Caché	En una capa técnica de reutilización.	Mientras sea válida.	Ahorrar coste o latencia; no añade conocimiento nuevo.
Tool	En un sistema externo consultado o ejecutado.	En tiempo real.	Calcular, buscar estado vivo, escribir en sistemas o consultar APIs.

Ejemplo sencillo: si una universidad cambia la normativa de matrícula, no quieres reentrenar un modelo. Quieres actualizar el documento, reindexar y que las respuestas citen la normativa nueva. Si, en cambio, el problema es que el modelo siempre devuelve un JSON con campos mal nombrados, RAG no lo arregla por sí solo: quizá necesitas mejor contrato de salida, ejemplos, validación o ajuste.

La memoria conversacional tampoco equivale a RAG. Si el usuario dice “soy estudiante de segundo”, eso puede vivir como memoria o como contexto de sesión. Pero si pregunta “¿qué dice la normativa vigente sobre ampliación?”, eso debe salir del corpus, con fecha y cita. La memoria puede ayudar a formular la consulta; no debe sustituir la fuente.

Por qué usar un RAG

Usamos RAG cuando responder bien exige recuperar evidencia externa. No es una moda de arquitectura; es una respuesta a una limitación práctica: los modelos no traen dentro todos tus documentos, no conocen todos los cambios recientes y no pueden demostrar por sí solos de dónde sale una afirmación.

Motivo	Qué problema resuelve	Señal de que RAG encaja
Información cambiante	El conocimiento se actualiza sin tocar pesos.	Normativas, catálogos, precios internos, políticas y manuales vivos.
Conocimiento privado	El modelo no vio tus documentos durante entrenamiento.	Intranets, tickets, expedientes, documentación de producto.
Citas y auditoría	La respuesta puede revisarse contra fuentes.	Necesitas enseñar página, sección, fecha o documento.
Permisos	Cada persona puede recuperar solo lo que le corresponde.	Hay roles, grupos, tenants, cursos, clientes o áreas.
Coste de actualización	Reindexar suele ser más barato que reentrenar.	El corpus cambia más que el comportamiento deseado.
Especialización ligera	El modelo general se apoya en contexto de dominio.	La tarea pide lenguaje natural más conocimiento concreto.
Depuración	Puedes ver qué documentos entraron en la respuesta.	Necesitas saber si falló búsqueda, contexto o generación.

También hay casos donde RAG no es la primera respuesta.

Situación	Mejor primera herramienta
El modelo no sigue el formato.	Prompt, ejemplos, salida estructurada o fine-tuning.
La respuesta depende de cálculo exacto.	Tool o código, no solo documentos.
La información vive en una base de datos transaccional.	SQL, API o tool; quizá luego RAG para explicar resultados.
La tarea es siempre igual y estable.	Fine-tuning/LoRA puede ser más eficiente.
El corpus está desordenado o sin dueño.	Gobernanza documental antes de RAG.

Qué sí es: una cadena verificable

Un RAG mínimo tiene dos procesos separados. El primero prepara el conocimiento; el segundo responde una pregunta.

Proceso	Ocurre cuándo	Qué produce
Indexación	Antes de la consulta, cuando entran o cambian documentos.	Chunks con embeddings, texto, metadata y versión.
Consulta	Cuando una persona pregunta.	Respuesta con citas, o abstención si no hay evidencia suficiente.

Ejemplo de fórmula. La consulta completa puede expresarse así:

q = f_{\theta}(x)

R_k = \operatorname{TopK}(q, C, F, k)

y = g_{\phi}(x, \operatorname{Contexto}(R_k))

Símbolo	Significado	Ejemplo
$x$	Pregunta original.	“¿puedo ampliar matrícula en septiembre?”.
$f_{\theta}$	Modelo de embeddings.	Convierte la pregunta en vector.
$q$	Vector de la pregunta.	768 números.
$C$	Colección de chunks indexados.	Normativa, FAQs y manuales.
$F$	Filtros obligatorios.	`curso=2026`, `vigente=true`, `rol=estudiante`.
$R_k$	Fragmentos recuperados.	Top 6 chunks después de filtros.
$g_{\phi}$	Modelo generativo.	LLM que redacta la respuesta.
$y$	Respuesta final.	Texto con citas o abstención.

La parte peligrosa está en $\operatorname{Contexto}(R_k)$ . No todos los chunks recuperados deben entrar en el prompt. Hay que ordenar, recortar, quitar duplicados, proteger permisos, preservar citas y dejar hueco para instrucciones y respuesta.

Términos que no podemos dar por sabidos

La jerga de RAG engaña porque muchas palabras parecen pequeñas y en realidad esconden decisiones de sistema. “Chunk”, “metadata” o “top-k” no son etiquetas académicas: son puntos donde puedes ganar o perder calidad, coste, privacidad y capacidad de depuración.

La primera familia de términos aparece antes de preguntar nada. Es la parte de preparación del conocimiento.

Término	Qué significa de verdad	En el ejemplo de matrícula
Corpus	Conjunto de fuentes que el sistema tiene permiso para consultar. No es “todo lo que existe”; es lo que has decidido meter en el sistema.	Normativa 2026, FAQ de secretaría, calendario académico y manual de trámites.
Fuente	Documento o sistema original del que sale la información. Puede ser un PDF, una web, una tabla o una base de datos.	`normativa_matricula_2026.pdf`.
Documento	Representación interna de una fuente. Suele incluir texto, título, fecha, URL, propietario y versión.	La normativa convertida a texto con su fecha de publicación.
Parser	Programa que extrae texto y estructura. Si el parser lee mal una tabla, el RAG recuperará texto defectuoso.	Sacar de un PDF el artículo, el título y los apartados en orden correcto.
OCR	Reconocimiento óptico de caracteres. Convierte una imagen o escaneo en texto.	Una normativa escaneada que no permite seleccionar texto.
Chunk	Fragmento recuperable. Debe ser suficientemente pequeño para buscar bien y suficientemente completo para citarlo.	Un artículo completo sobre ampliación de matrícula.
Token	Unidad interna aproximada de texto que usan modelos y muchos contadores de coste. No siempre coincide con palabra.	“matrícula” puede ocupar más de un token según el tokenizador.
Solape	Parte repetida entre dos chunks consecutivos para no cortar ideas.	Repetir el encabezado y la frase anterior cuando un artículo pasa de una ventana a otra.
Metadata	Datos sobre el chunk, no necesariamente contenido para responder. Sirve para filtrar, citar y operar.	`curso=2026`, `vigente=true`, `seccion=matricula`, `pagina=12`.
ACL	Reglas de acceso. Indican quién puede recuperar un chunk antes de que llegue al modelo.	Alumnado ve normativa pública; personal interno ve notas de gestión.
Hash	Huella calculada del texto. Si el documento cambia, cambia el hash.	Detectar que se subió una normativa nueva aunque mantenga el mismo nombre de archivo.
Versión de corpus	Identificador de qué conjunto de documentos e índices se usó. Es clave para reproducir una respuesta.	`matricula-2026-v3`, usado el 25 de mayo de 2026.

La segunda familia aparece cuando alguien pregunta. Aquí conviene separar “buscar parecido” de “encontrar evidencia”.

Término	Qué significa de verdad	Qué decisión exige
Query	Consulta que entra al retrieval. Puede ser la pregunta original o una versión reescrita.	Decidir si buscas literalmente “pagos pendientes” o reformulas con sinónimos.
Query rewrite	Reescritura de la pregunta para recuperar mejor. Es útil, pero debe registrarse.	Convertir “¿puedo ampliar?” en “ampliación de matrícula septiembre pagos pendientes”.
Embedding	Vector numérico que representa un texto para comparar significado aproximado.	Elegir modelo, dimensión, coste y cuándo recalcular vectores.
Dimensión	Número de coordenadas del embedding. Más dimensión no garantiza mejor resultado; cambia memoria, coste e índice.	Un embedding de 768 dimensiones ocupa menos que uno de 3.072, pero puede rendir distinto.
Índice	Estructura que permite buscar rápido. Sin índice, compararías contra todo el corpus en cada pregunta.	Crear índice vectorial, índice léxico o ambos.
Vector store	Almacén que guarda vectores, texto y metadata para buscar por similitud y filtros.	Qdrant, pgvector, Pinecone, Weaviate o File Search.
FTS	Full-text search: búsqueda textual clásica por palabras, operadores y relevancia.	Encontrar “artículo 14” o “pagos pendientes” aunque el embedding no lo priorice.
BM25	Fórmula de ranking léxico. Premia términos relevantes y penaliza documentos donde una palabra aparece por aparecer.	Si la pregunta dice “septiembre”, BM25 ayuda a subir chunks que contienen esa palabra exacta.
ANN	Approximate nearest neighbors. Técnica para buscar vectores parecidos sin comparar todos contra todos.	Acelerar búsqueda en miles o millones de chunks aceptando una aproximación controlada.
Top-k	Número de candidatos devueltos. `k=5` trae cinco chunks antes de rerank o contexto.	Si `k` es bajo, quizá pierdes evidencia; si es alto, sube ruido y coste.
Score	Puntuación de similitud o relevancia. No siempre es comparable entre métodos.	No comparar sin más un coseno `0,78` con un BM25 `12,4`.
RRF	Fusión por posiciones. Combina rankings usando el puesto de cada documento, no su score bruto.	Mezclar búsqueda vectorial y BM25 sin calibrar escalas distintas.
Reranker	Modelo o regla que reordena candidatos después de una primera búsqueda rápida.	Pasar de 50 candidatos baratos a 6 fragmentos buenos para el prompt.
Filtro	Restricción obligatoria antes o durante la búsqueda. No es una preferencia.	`vigente=true`, `curso=2026`, `rol=estudiante`.

La tercera familia aparece cuando ya hay candidatos y el sistema debe responder. Aquí es donde un RAG deja de ser buscador y se convierte en producto.

Término	Qué significa de verdad	Qué se revisa en producción
Context builder	Pieza que decide qué chunks entran en el prompt y con qué formato.	Deduplicación, orden, citas, presupuesto y prioridad de fuentes.
Presupuesto de contexto	Límite de tokens disponible para instrucciones, pregunta, evidencia y respuesta.	No gastar 90% del contexto en fragmentos repetidos.
Cita	Enlace entre una afirmación y el fragmento que la sostiene.	Que `[F1]` apunte a `source_id`, página, sección y hash.
Grounding	Grado en que la respuesta está apoyada en la evidencia recuperada.	Si la frase importante se puede subrayar en una fuente.
Abstención	Respuesta correcta cuando falta evidencia suficiente.	Decir qué dato falta en vez de rellenarlo con probabilidad.
Umbral $\tau$	Valor mínimo de soporte para responder. No se elige a ojo; se calibra con evaluación.	Responder si `soporte >= 0,65` y abstenerse si queda por debajo.
Traza	Registro completo de una consulta. Sin traza, no sabes dónde falló.	Pregunta, filtros, top-k, scores, prompt, respuesta, modelo y coste.
Recall@k	Métrica: si la evidencia necesaria aparece entre los `k` primeros resultados.	Si la respuesta correcta necesitaba un artículo y no aparece en top 10, falló retrieval.
nDCG	Métrica que premia que los resultados más útiles aparezcan arriba.	No basta con traer el chunk correcto; conviene que llegue en primeras posiciones.

Una forma sencilla de recordarlo: el corpus decide qué puede saber el sistema; el retrieval decide qué encuentra; el context builder decide qué lee el modelo; y la abstención decide qué no debe fingir.

Elementos importantes de un RAG

Un RAG no es una sola pieza. Es una cadena. Si una parte falla, el resultado final puede parecer correcto y estar mal apoyado. Por eso conviene nombrar los elementos con precisión.

Elemento	Pregunta que responde	Error típico
Corpus	¿Qué fuentes entran y cuáles quedan fuera?	Indexar documentos sin vigencia, duplicados o sin propietario.
Ingesta	¿Cómo entran los documentos al sistema?	Subir archivos manualmente sin versiones ni borrado.
Parsing	¿El texto extraído conserva estructura?	Perder tablas, encabezados, notas o páginas.
Chunking	¿Cuál es la unidad recuperable?	Cortar ideas por tamaño fijo sin respetar secciones.
Metadata	¿Cómo filtro, cito y opero cada chunk?	Guardar solo texto y no poder filtrar por fecha, rol o fuente.
Embeddings	¿Cómo busco por significado aproximado?	Usar un modelo sin evaluar idioma, dominio, dimensión y coste.
Índice léxico	¿Cómo busco palabras exactas?	Confiar solo en vectores y perder códigos, fechas o términos raros.
Retrieval híbrido	¿Cómo combino significado, palabras y filtros?	Mezclar scores incompatibles sin fusión ni trazas.
Reranking	¿Cómo reordeno candidatos prometedores?	Meter al prompt los primeros resultados sin segunda revisión.
Context builder	¿Qué evidencia entra al prompt?	Pasar demasiados chunks, repetidos o sin citas.
Generación	¿Cómo redacta el modelo con restricciones?	Permitir respuesta sin evidencia o sin formato de cita.
Abstención	¿Cuándo no se responde?	Contestar siempre aunque el corpus no contenga la respuesta.
Evaluación	¿Cómo sé si mejora?	Medir solo “me gusta” y no recall, groundedness, coste o latencia.
Observabilidad	¿Cómo depuro cada consulta?	No guardar query, filtros, ranking, contexto y respuesta.

El orden importa. No tiene sentido discutir modelos grandes si el parser rompe tablas. No tiene sentido ajustar el prompt si el retrieval no trae el artículo correcto. No tiene sentido comprar una base vectorial si nadie sabe qué documentos están vigentes.

Dimensiones en un RAG

En RAG, “dimensión” puede significar dos cosas. La primera es matemática: la dimensión del embedding. La segunda es de diseño: las dimensiones que debes controlar para que el sistema funcione.

La dimensión matemática es el número de coordenadas del vector. Si un chunk se convierte en un embedding de $d$ dimensiones, queda así:

e(c) = [e_1, e_2, e_3, \dots, e_d]

Símbolo	Significado	Ejemplo
$c$	Chunk que queremos representar.	Artículo sobre ampliación de matrícula.
$e(c)$	Embedding del chunk.	Vector guardado en el índice.
$d$	Número de dimensiones.	768, 1.024, 1.536 o 3.072, según modelo.
$e_i$	Valor de una coordenada.	Un número flotante aprendido por el modelo.

Estas dimensiones no son columnas humanas como “matrícula”, “pago” o “septiembre”. Son coordenadas aprendidas. El significado está distribuido por muchas posiciones a la vez. Por eso no se interpreta una dimensión aislada como si fuera una etiqueta; se compara el vector completo con otros vectores.

La similitud suele medirse con coseno:

\operatorname{sim}(a,b)= \frac{a \cdot b}{\lVert a \rVert \lVert b \rVert}

Idea	Qué implica
Más dimensiones no significa automáticamente mejor RAG.	Puede mejorar representación, pero también memoria, latencia y coste.
No mezcles modelos de embeddings en el mismo índice sin control.	Dos modelos pueden tener dimensiones y geometrías incompatibles.
Si cambias de modelo de embeddings, normalmente reindexas.	Los vectores antiguos ya no viven en el mismo espacio.
La dimensión afecta almacenamiento.	Más coordenadas por chunk implica más bytes y más trabajo para el índice.
La dimensión afecta recuperación, no generación directamente.	Ayuda a encontrar evidencia; no hace que el LLM razone mejor por sí sola.

El coste bruto de guardar vectores puede aproximarse así:

\operatorname{bytes} \approx N \times d \times b

Símbolo	Significado	Ejemplo
$N$	Número de chunks.	100.000 chunks.
$d$	Dimensiones por embedding.	1.536 dimensiones.
$b$	Bytes por valor.	4 bytes en float32, 2 bytes en float16.

Con 100.000 chunks, 1.536 dimensiones y float32, solo los vectores ocupan aproximadamente 614 MB antes de contar metadata, texto, índices auxiliares y réplicas. Esta cuenta no decide la arquitectura, pero te obliga a pensar como ingeniero: dimensión, volumen, tipo numérico, latencia y presupuesto van juntos.

La segunda lectura de “dimensiones” es de diseño. Un RAG se optimiza mirando varias dimensiones a la vez:

Dimensión de diseño	Pregunta
Calidad del corpus	¿Los documentos son correctos, vigentes y no duplicados?
Recuperación	¿La evidencia necesaria aparece en top-k?
Contexto	¿El prompt recibe lo justo, ordenado y citado?
Generación	¿El modelo responde con contrato, citas y abstención?
Evaluación	¿Sabemos medir si mejora o empeora?
Operación	¿Podemos actualizar, borrar, auditar y controlar coste?

Chunking: partir sin romper el significado

Un chunk es la unidad que el sistema puede recuperar. Si es demasiado pequeño, pierde contexto. Si es demasiado grande, arrastra ruido y ocupa mucho prompt. La unidad correcta depende del documento y de la pregunta.

Ejemplo de fórmula. Si partimos un documento de $L$ tokens en ventanas de tamaño $w$ con solape $o$ , una aproximación del número de chunks es:

n \approx 1 + \left\lceil \frac{\max(0, L-w)}{w-o} \right\rceil

Símbolo	Significado	Ejemplo
$L$	Longitud del documento.	2.400 tokens.
$w$	Tamaño de chunk.	350 tokens.
$o$	Solape entre chunks.	60 tokens.
$w-o$	Avance real de cada ventana.	290 tokens.
$n$	Número aproximado de chunks.	9 chunks.

El solape evita cortar una idea justo en la frontera. Pero el solape también duplica texto, embeddings y coste. Si todo solapa demasiado, el índice se llena de fragmentos casi iguales y el top-k pierde diversidad.

Tipo de documento	Chunk inicial razonable	Qué cuidar
FAQ corta	Una pregunta-respuesta por chunk.	Mantener la pregunta original en el texto.
Normativa	Artículo, sección o bloque con título.	Guardar fecha, versión, capítulo y vigencia.
Manual técnico	Sección con pasos completos.	No separar requisito, comando y salida esperada.
Contrato o política	Cláusula completa con encabezado.	Preservar definiciones y excepciones.
Código	Función, clase o bloque lógico.	Mantener ruta, lenguaje y dependencias cercanas.

Un buen chunk no es “350 tokens”. Un buen chunk es una pieza que, leída sola, todavía puede sostener una respuesta concreta.

Soluciones de terceros: qué comprar, qué montar y qué no delegar

Hay varias formas de montar RAG. La decisión no es “framework sí o no”. La decisión es qué parte quieres delegar y qué parte necesitas controlar.

Familia	Ejemplos	Te quita trabajo en	Te deja responsable de
RAG gestionado por proveedor	OpenAI File Search, Vertex AI RAG Engine.	Vector store, búsqueda, integración con modelo, parte de la operación.	Calidad de documentos, permisos, evaluación, costes y trazabilidad.
Framework de orquestación	LangChain, LlamaIndex, Haystack.	Loaders, splitters, retrievers, pipelines, integraciones.	Diseño del flujo, selección de componentes y despliegue.
Base vectorial / buscador	Qdrant, pgvector, Pinecone, Weaviate, Milvus, Elasticsearch/OpenSearch.	Almacenamiento, índice, filtros, latencia de búsqueda.	Chunking, generación, citas, abstención y evaluación final.
Parsing y preparación	Extractores PDF, OCR, conversores HTML, pipelines ETL.	Sacar texto de documentos difíciles.	Validar tablas, orden de lectura, duplicados y metadatos.
Observabilidad y evaluación	LangSmith, evaluadores propios, trazas internas.	Registro, comparación y análisis de runs.	Definir qué significa “respuesta correcta” en tu dominio.

OpenAI File Search es útil si quieres empezar rápido con archivos y vector stores gestionados dentro de la Responses API.¹¹ LangChain encaja cuando quieres componer loaders, splitters, retrievers, vector stores y varios estilos de RAG.¹² LlamaIndex brilla cuando el centro del problema es ingestión, nodos, índices y consulta sobre datos propios.¹³ Haystack es especialmente claro si quieres pensar en pipelines como grafos de componentes conectados y validables.¹⁴

La regla práctica: compra o usa framework para acelerar, pero no delegues el criterio. Ninguna herramienta sabe por defecto qué documentos están vigentes, qué permiso tiene cada persona, qué cita es suficiente o cuándo conviene abstenerse.

Antes de elegir una solución de terceros, conviene escribir una pequeña ADR técnica. No hace falta una novela; hace falta que nadie confunda “funciona en demo” con “lo podemos operar”.

Pregunta de ingeniería	Por qué importa	Señal de buena respuesta
¿Cómo actualiza y borra documentos?	RAG falla mucho cuando el índice conserva versiones antiguas.	Hay `upsert`, borrado por documento, reindexado y versión de corpus.
¿Dónde aplico permisos?	El texto no autorizado no debe entrar al contexto.	Filtros por usuario, grupo, tenant, vigencia y clasificación antes del top-k.
¿Puedo combinar vector, BM25 y filtros?	Muchas preguntas reales mezclan significado, palabras exactas y metadata.	Retrieval híbrido con scores visibles y filtros que no rompen latencia.
¿Qué devuelve como cita?	Sin `source_id`, página, sección o hash, revisar una respuesta es difícil.	Cada fragmento trae identificador estable, título, fecha y localización.
¿Puedo ver trazas?	Si no ves chunks, scores y prompt, no puedes depurar.	Logs por query, ranking, contexto final, coste y respuesta.
¿Puedo cambiar de modelo?	El embedding de hoy puede no ser el de mañana.	Índices versionados por modelo y dimensión; migración repetible.
¿Qué pasa con tablas e imágenes?	Mucha documentación útil no es texto plano.	Parsing verificable, OCR cuando toca y preservación de estructura.
¿Cómo se evalúa?	Una demo bonita no mide recall ni groundedness.	Set de preguntas, respuestas esperadas, citas esperadas y regresión automática.
¿Cómo salgo de la herramienta?	El bloqueo aparece cuando tus datos solo viven en su formato.	Exportación de chunks, metadata, vectores y trazas.

Una ruta razonable para empezar es esta:

Contexto del equipo	Ruta inicial	Cuándo cambiar
Quieres validar una idea en días.	File Search o RAG gestionado equivalente.	Cuando necesites permisos complejos, índices propios o trazas más finas.
Tienes app Python/TypeScript y datos variados.	LangChain, LlamaIndex o Haystack con Qdrant, pgvector, Pinecone o Weaviate.	Cuando el framework esconda demasiado o el flujo ya sea estable.
Ya estás en Google Cloud o Azure.	Vertex AI RAG Engine o Azure AI Search.	Cuando residencia, permisos, facturación y operación sean prioridad.
Necesitas control total y bajo coste.	pgvector/Qdrant autogestionado, pipeline propio y evaluación propia.	Cuando el volumen o el equipo pidan servicio gestionado.

Arquitectura mínima de un primer RAG

El diagrama separa lo que suele mezclarse. Indexar es preparar el material. Consultar es decidir qué evidencia entra. Responder es redactar, citar y abstenerse si el material no basta.

Cómo montar un primer RAG de verdad

Un primer RAG serio no empieza por el modelo. Empieza por el contrato de respuesta.

Paso	Decisión	Salida verificable
1. Elegir corpus	Qué documentos entran y cuáles no.	Lista de fuentes, versiones y propietarios.
2. Extraer texto	Cómo leer PDF, HTML, Markdown o base de datos.	Texto limpio con orden de lectura revisado.
3. Partir en chunks	Unidad recuperable y citable.	Chunks con `source_id`, sección, fecha y hash.
4. Indexar	Embeddings, BM25, filtros y vector store.	Índice versionado y reproducible.
5. Recuperar	Top-k, filtros y búsqueda híbrida.	Lista de chunks con scores y metadata.
6. Construir contexto	Qué entra al prompt y con qué formato.	Contexto numerado con fuentes.
7. Generar	Instrucciones para responder con evidencia.	Respuesta con citas o abstención.
8. Registrar	Guardar query, chunks, respuesta y versión.	Traza para depurar y evaluar.

Un prompt mínimo de RAG debe separar instrucciones y contexto. El modelo no debe tratar los documentos como órdenes, sino como material de consulta:

Responde usando solo el contexto incluido.
Si el contexto no contiene evidencia suficiente, responde:
"No tengo evidencia suficiente en las fuentes disponibles."

Pregunta:
{pregunta}

Contexto:
[F1] {fragmento_1}
[F2] {fragmento_2}

Formato:
- Respuesta breve.
- Citas entre corchetes, por ejemplo [F1].
- Si hay duda, explica qué dato falta.

La cita no es decoración. Es una interfaz de confianza: permite revisar si la frase que el modelo escribió está realmente en las fuentes.

Citas y abstención

Ejemplo de fórmula. Podemos definir una regla simple:

\operatorname{responder}(x)= \begin{cases} g_{\phi}(x, R_k), & \text{si } soporte(R_k, x) \ge \tau \ \operatorname{abstenerse}, & \text{si } soporte(R_k, x) < \tau \end{cases}

Símbolo	Significado	Ejemplo
$x$	Pregunta.	“¿Puedo ampliar matrícula con pagos pendientes?”.
$R_k$	Fragmentos recuperados.	Seis chunks tras filtros.
$soporte(R_k,x)$	Evidencia disponible para responder.	0,82 si hay fragmentos claros.
$\tau$	Umbral mínimo para responder.	0,65 en una primera prueba.
$g_{\phi}$	Modelo que redacta.	LLM con prompt de citas.

Ese soporte puede empezar siendo una regla: top score mínimo, al menos una fuente vigente y presencia de términos críticos. Más adelante puede ser un evaluador aprendido o un evaluador con rúbrica. Lo importante es que la abstención no sea una vergüenza; es una conducta correcta cuando falta evidencia.

Situación	Qué debe hacer el RAG	Por qué
Hay una fuente vigente y clara.	Responder y citar.	La evidencia sostiene la respuesta.
Hay fuentes parecidas pero de años distintos.	Responder solo si el filtro de vigencia lo resuelve.	El parecido semántico no basta.
Hay dos fuentes que se contradicen.	Mostrar conflicto o abstenerse.	Elegir una en silencio rompe confianza.
No aparece evidencia directa.	Abstenerse y decir qué falta.	Mejor que rellenar huecos con probabilidad.
La pregunta pide acción externa.	Recuperar contexto, pero delegar la acción a una tool.	RAG informa; no ejecuta trámites por sí mismo.

Cómo optimizar bien un RAG

Optimizar RAG no significa tocar un parámetro al azar hasta que una demo parezca mejor. Significa separar dónde falla el sistema y medir cada etapa. Si una respuesta sale mal, la causa puede estar en el corpus, el parser, el chunking, el embedding, el índice, el reranker, el contexto, el prompt o la ausencia de una regla de abstención.

La primera regla es crear un pequeño conjunto de evaluación antes de optimizar. No hace falta empezar con mil preguntas. Puedes empezar con 30 o 50 preguntas reales, cada una con la fuente esperada y una explicación de qué debería responder el sistema. Sin ese conjunto, cada cambio se evalúa con intuición y la intuición se cansa rápido.

Capa	Qué optimizar	Cómo medirlo
Corpus	Fuentes vigentes, sin duplicados y con propietario.	Porcentaje de documentos con fecha, versión, dueño y estado.
Parsing	Texto correcto, tablas preservadas, orden de lectura.	Revisión manual de muestras y errores por tipo de documento.
Chunking	Unidad completa, citable y no demasiado ruidosa.	Recall@k por tamaño de chunk y tasa de chunks duplicados.
Metadata	Filtros útiles y citas revisables.	Porcentaje de chunks con `source_id`, página, sección, fecha y ACL.
Embeddings	Modelo adecuado a idioma, dominio y coste.	Recall@k, latencia, coste por millón de chunks y memoria.
Retrieval híbrido	Combinar significado, palabras exactas y filtros.	Comparar vector solo, BM25 solo, híbrido y RRF.
Reranking	Subir la evidencia buena antes del prompt.	nDCG@k, MRR y coste añadido por consulta.
Context builder	Meter evidencia suficiente sin ruido.	Precisión de citas, tokens de contexto y duplicados.
Prompt	Responder con contrato, citas y abstención.	Groundedness, formato válido y tasa de abstención correcta.
Operación	Actualizar, borrar, trazar y controlar coste.	Tiempo de reindexado, errores, latencia p95 y coste por respuesta.

Una receta práctica para optimizar sería:

Congela un corpus pequeño y versionado.
Escribe preguntas de evaluación con sus fuentes esperadas.
Mide retrieval antes de mirar la respuesta del LLM.
Ajusta chunking y metadata hasta que la evidencia aparezca arriba.
Añade BM25 o búsqueda híbrida si pierdes términos exactos.
Añade reranker si recuperas bien pero ordenas mal.
Recorta contexto y deduplica antes de tocar el prompt.
Obliga a citar y abstenerse con un contrato de salida.
Guarda trazas de cada consulta para comparar versiones.
Cambia una cosa cada vez; si cambias cinco, no sabes qué funcionó.

Hay una trampa frecuente: intentar arreglar con prompt lo que es un fallo de retrieval. Si el chunk correcto no entra en contexto, el modelo no puede citarlo. Otra trampa es subir top-k sin control. Traer más chunks puede mejorar recall, pero también mete ruido, sube coste y aumenta la probabilidad de mezclar fuentes.

Síntoma	Diagnóstico probable	Primer ajuste
La respuesta suena bien pero no cita la fuente correcta.	Retrieval o context builder fallan.	Revisar top-k, filtros, metadata y orden de contexto.
Recupera documentos antiguos.	Falta filtro de vigencia o borrado.	Añadir `vigente=true`, versión de corpus y política de retirada.
Pierde códigos, nombres propios o fechas.	Vector solo no basta.	Añadir BM25/FTS y fusión RRF.
Recupera muchos chunks parecidos.	Solape excesivo o duplicados.	Deduplicar por hash, sección o similitud entre chunks.
Responde cuando no sabe.	Falta abstención o umbral.	Definir soporte mínimo y respuesta de insuficiencia.
Es lento.	Índice, reranker o contexto demasiado grandes.	Medir p95, reducir candidatos, cachear embeddings y ajustar ANN.

¿Solo texto? Qué más puede entrar en un RAG

Texto es el punto de partida porque el LLM consume tokens y porque muchos documentos terminan convertidos a texto. Pero RAG no tiene por qué limitarse a texto plano. Lo importante es convertir cada fuente en una representación recuperable, filtrable y citable.

Tipo de información	Cómo entra al RAG	Qué hay que cuidar
PDF y documentos	Texto extraído, páginas, títulos y chunks.	Orden de lectura, notas, tablas, encabezados y versión.
Tablas	Filas, columnas, celdas relevantes o resumen estructurado.	No perder unidades, claves, fechas ni relación fila-columna.
Bases de datos	Resultados de SQL o vistas preparadas.	Permisos, frescura, consultas reproducibles y explicación del resultado.
Imágenes	OCR, descripciones, embeddings multimodales o regiones anotadas.	Distinguir texto visible, objetos, gráficos y metadatos.
Audio	Transcripción, marcas de tiempo y hablantes.	Errores de transcripción, idioma, ruido y citas por minuto/segundo.
Vídeo	Transcripción, fotogramas clave, escenas y marcas temporales.	Recuperar el momento exacto, no solo un resumen genérico.
Código	Funciones, clases, rutas, tests y documentación cercana.	Mantener dependencias, imports, versión y lenguaje.
Logs y tickets	Eventos normalizados, campos, tiempos y etiquetas.	Ruido, duplicados, retención y datos sensibles.
Grafos u ontologías	Nodos, relaciones, triples y consultas de grafo.	No convertir relaciones precisas en texto ambiguo.
Resultados de tools	Salidas de APIs, cálculos o búsquedas vivas.	Separar evidencia recuperada de acciones ejecutadas.

Cuando una fuente no es texto, tienes dos estrategias. La primera es traducirla a texto fiel: OCR, transcripción, descripción de imagen, explicación de tabla. La segunda es usar embeddings específicos: embeddings de imagen, multimodales, de audio o de código. En sistemas reales se mezclan ambas: una imagen puede tener OCR, una descripción y un vector multimodal; una tabla puede tener filas indexadas y, además, una consulta SQL cuando hace falta precisión.

La pregunta de ingeniería no es “¿puedo meterlo en RAG?”, sino “¿puedo recuperar la parte correcta, respetar permisos, citarla y comprobarla?”. Si no puedes citar una celda, una página, una región de imagen, un minuto de audio o una fila de base de datos, todavía no tienes una evidencia robusta.

Ruta rápida con una solución gestionada

Si quieres montar algo rápido sobre archivos, una opción es usar File Search con vector stores gestionados. La idea es: crear vector store, subir archivos y dejar que la herramienta de búsqueda recupere contexto para la llamada al modelo.¹⁵

from openai import OpenAI

client = OpenAI()

store = client.vector_stores.create(name="normativa-universidad")

client.vector_stores.files.upload_and_poll(
    vector_store_id=store.id,
    file=open("normativa_matricula_2026.pdf", "rb"),
)

respuesta = client.responses.create(
    model="gpt-4.1-mini",
    input=(
        "¿Puedo ampliar matrícula en septiembre "
        "si tengo pagos pendientes? Cita las fuentes."
    ),
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": [store.id],
            "max_num_results": 6,
        }
    ],
)

print(respuesta.output_text)

Esto sirve para prototipar o para casos donde te compensa delegar infraestructura. Pero incluso aquí quedan decisiones tuyas: qué archivos subes, cómo versionas, cómo retiras documentos antiguos, qué permisos aplicas, cómo revisas citas y cómo evalúas si la respuesta es correcta.

Manos a la obra

Ahora montamos un primer RAG local, sin depender de APIs. No será un LLM completo: el generador será extractivo para que puedas verificar cada paso. A cambio, verás lo esencial: chunking, retrieval híbrido, contexto, citas y abstención.

Guarda esto como rag_minimo_citado.py:

from collections import Counter, defaultdict
import hashlib
import math
import re
import unicodedata


DIM = 32
K_RRF = 60
TOP_K = 4
SIN_EVIDENCIA = (
    "No tengo evidencia suficiente en las fuentes disponibles."
)

DOCUMENTOS = [
    {
        "id": "norm-2026",
        "titulo": "Normativa de matrícula 2026",
        "texto": (
            "La ampliación de matrícula se abre en septiembre. "
            "El estudiante puede solicitar ampliación si no mantiene "
            "pagos pendientes vencidos. La solicitud se revisa desde "
            "secretaría virtual."
        ),
        "curso": 2026,
        "vigente": True,
    },
    {
        "id": "faq-campus",
        "titulo": "Acceso al campus virtual",
        "texto": (
            "Si no puedes entrar al campus virtual, revisa el doble "
            "factor y restablece la contraseña desde la página "
            "de acceso."
        ),
        "curso": 2026,
        "vigente": True,
    },
    {
        "id": "norm-2024",
        "titulo": "Normativa antigua de matrícula",
        "texto": (
            "En 2024 la ampliación de matrícula no revisaba pagos "
            "pendientes antes de enviar la solicitud."
        ),
        "curso": 2024,
        "vigente": False,
    },
]

SINONIMOS = {
    "moodle": "campus",
    "virtual": "campus",
    "entrar": "acceso",
    "ampliar": "ampliacion",
    "matricula": "matricula",
    "matrícula": "matricula",
    "pago": "pagos",
    "pendiente": "pendientes",
}

STOPWORDS = {
    "a",
    "al",
    "como",
    "con",
    "cual",
    "cuando",
    "de",
    "del",
    "desde",
    "el",
    "en",
    "es",
    "la",
    "las",
    "lo",
    "los",
    "me",
    "no",
    "o",
    "para",
    "por",
    "puedo",
    "que",
    "se",
    "si",
    "un",
    "una",
    "y",
}


def normalizar(texto):
    texto = texto.lower()
    texto = unicodedata.normalize("NFD", texto)
    texto = "".join(
        c for c in texto if unicodedata.category(c) != "Mn"
    )
    tokens = re.findall(r"[a-z0-9_]+", texto)
    return [SINONIMOS.get(t, t) for t in tokens]


def tokens_de_contenido(texto):
    return [t for t in normalizar(texto) if t not in STOPWORDS]


def partir_en_chunks(documento, max_palabras=42, solape=8):
    palabras = documento["texto"].split()
    avance = max_palabras - solape
    chunks = []

    for inicio in range(0, len(palabras), avance):
        bloque = palabras[inicio: inicio + max_palabras]
        if not bloque:
            continue
        chunk_id = f"{documento['id']}#c{len(chunks) + 1}"
        chunks.append(
            {
                "id": chunk_id,
                "source_id": documento["id"],
                "titulo": documento["titulo"],
                "texto": " ".join(bloque),
                "curso": documento["curso"],
                "vigente": documento["vigente"],
            }
        )
    return chunks


def vector_token(token):
    digest = hashlib.sha256(token.encode("utf-8")).digest()
    return [
        ((digest[i % len(digest)] / 255.0) * 2 - 1)
        for i in range(DIM)
    ]


def normalizar_vector(vector):
    norma = math.sqrt(sum(x * x for x in vector)) or 1.0
    return [x / norma for x in vector]


def vector_texto(texto):
    vector = [0.0] * DIM
    for token in normalizar(texto):
        base = vector_token(token)
        vector = [a + b for a, b in zip(vector, base)]
    return normalizar_vector(vector)


def producto_punto(a, b):
    return sum(x * y for x, y in zip(a, b))


def construir_indice(documentos):
    chunks = []
    for doc in documentos:
        chunks.extend(partir_en_chunks(doc))

    tokens = [
        normalizar(c["titulo"] + " " + c["texto"])
        for c in chunks
    ]
    df = defaultdict(int)
    for fila in tokens:
        for token in set(fila):
            df[token] += 1

    return {
        "chunks": chunks,
        "tokens": tokens,
        "vectores": [
            vector_texto(c["titulo"] + " " + c["texto"])
            for c in chunks
        ],
        "df": df,
        "avgdl": sum(len(t) for t in tokens) / len(tokens),
    }


def bm25(query_tokens, doc_tokens, df, avgdl, total):
    frecuencias = Counter(doc_tokens)
    score = 0.0
    k1 = 1.2
    b = 0.75

    for token in query_tokens:
        if token not in frecuencias:
            continue
        numerador = total - df[token] + 0.5
        denominador = df[token] + 0.5
        idf = math.log(1 + numerador / denominador)
        tf = frecuencias[token]
        largo = len(doc_tokens)
        denom = tf + k1 * (1 - b + b * largo / avgdl)
        score += idf * (tf * (k1 + 1)) / denom
    return score


def cumple_filtro(chunk, filtro):
    return all(
        chunk.get(campo) == valor
        for campo, valor in filtro.items()
    )


def ranking_vectorial(pregunta, indice, filtro):
    q = vector_texto(pregunta)
    filas = []
    for i, chunk in enumerate(indice["chunks"]):
        if cumple_filtro(chunk, filtro):
            score = producto_punto(q, indice["vectores"][i])
            filas.append((chunk["id"], score))
    return sorted(filas, key=lambda x: x[1], reverse=True)


def ranking_lexico(pregunta, indice, filtro):
    query_tokens = normalizar(pregunta)
    filas = []
    for i, chunk in enumerate(indice["chunks"]):
        if cumple_filtro(chunk, filtro):
            score = bm25(
                query_tokens,
                indice["tokens"][i],
                indice["df"],
                indice["avgdl"],
                len(indice["tokens"]),
            )
            filas.append((chunk["id"], score))
    return sorted(filas, key=lambda x: x[1], reverse=True)


def fusion_rrf(rankings):
    scores = defaultdict(float)
    for ranking in rankings:
        for pos, (chunk_id, _score) in enumerate(ranking, start=1):
            scores[chunk_id] += 1 / (K_RRF + pos)
    return sorted(scores.items(), key=lambda x: x[1], reverse=True)


def recuperar(pregunta, indice, filtro):
    vectorial = ranking_vectorial(pregunta, indice, filtro)
    lexico = ranking_lexico(pregunta, indice, filtro)
    ranking = fusion_rrf([vectorial, lexico])[:TOP_K]
    por_id = {c["id"]: c for c in indice["chunks"]}
    return [(por_id[chunk_id], score) for chunk_id, score in ranking]


def generar_respuesta(pregunta, evidencias):
    if not evidencias:
        return SIN_EVIDENCIA

    mejor_chunk, mejor_score = evidencias[0]
    tokens_pregunta = set(tokens_de_contenido(pregunta))
    tokens_texto = set(tokens_de_contenido(mejor_chunk["texto"]))
    cobertura = len(tokens_pregunta & tokens_texto)

    if mejor_score < 0.02 or cobertura < 2:
        return SIN_EVIDENCIA

    cita = f"[{mejor_chunk['id']}]"
    return (
        f"{mejor_chunk['texto']} {cita}\n\n"
        f"Fuente: {mejor_chunk['titulo']}."
    )


def preguntar(pregunta, filtro):
    indice = construir_indice(DOCUMENTOS)
    evidencias = recuperar(pregunta, indice, filtro)

    print("Pregunta:", pregunta)
    print("Evidencias:")
    for chunk, score in evidencias:
        print(" ", chunk["id"], round(score, 4), chunk["titulo"])
    print()
    print(generar_respuesta(pregunta, evidencias))


if __name__ == "__main__":
    preguntar(
        "¿Puedo ampliar matrícula en septiembre con pagos pendientes?",
        {"curso": 2026, "vigente": True},
    )
    print("\n---\n")
    preguntar(
        "¿Cuál es el horario de cafetería?",
        {"curso": 2026, "vigente": True},
    )

Salida esperada aproximada:

Pregunta: ¿Puedo ampliar matrícula en septiembre con pagos pendientes?
Evidencias:
  norm-2026#c1 0.0328 Normativa de matrícula 2026
  faq-campus#c1 0.0317 Acceso al campus virtual

La ampliación de matrícula se abre en septiembre...
[norm-2026#c1]

Fuente: Normativa de matrícula 2026.

---

Pregunta: ¿Cuál es el horario de cafetería?
Evidencias:
  faq-campus#c1 0.0323 Acceso al campus virtual
  norm-2026#c1 0.0317 Normativa de matrícula 2026

No tengo evidencia suficiente en las fuentes disponibles.

Este código no pretende ser el RAG final. Pretende que puedas señalar cada pieza. Si sustituyes vector_texto por un modelo real de embeddings, generar_respuesta por una llamada a un LLM y construir_indice por Qdrant, pgvector o File Search, la arquitectura sigue siendo la misma.

Cómo encaja todo

graph TD
    subgraph "Capítulo 9: primer RAG"
        DOCS["Fuentes documentales"]
        CHUNK["Chunking"]
        INDEX["Índice"]
        RET["Retrieval"]
        CTX["Context builder"]
        GEN["Generación"]
        CITES["Citas"]
        ABST["Abstención"]
        TRACE["Trazas"]
    end
    subgraph "Viene de antes"
        API["APIs y schemas (F4C2)"]
        EMB["Embeddings (F4C7)"]
        VECTORDB["Base vectorial (F4C8)"]
        HYBRID["Búsqueda híbrida (F4C8)"]
    end
    subgraph "Sigue después"
        EVAL["Evaluar RAG (F4C10)"]
        AGENTIC["Agentic RAG (F4C11)"]
        SQL["Text-to-SQL (F4C12)"]
        MEMORY["Memoria de agentes (F5)"]
    end

    DOCS -->|"partir en"| CHUNK
    CHUNK -->|"vectorizar y guardar"| INDEX
    INDEX -->|"consultar mediante"| RET
    RET -->|"seleccionar para"| CTX
    CTX -->|"alimentar"| GEN
    GEN -->|"producir"| CITES
    GEN -->|"decidir"| ABST
    CITES -->|"registrar en"| TRACE
    ABST -->|"registrar en"| TRACE
    API -->|"definir contrato de"| GEN
    EMB -->|"crear vectores para"| INDEX
    VECTORDB -->|"almacenar"| INDEX
    HYBRID -->|"mejorar"| RET
    TRACE -->|"preparar"| EVAL
    RET -->|"puede iterar en"| AGENTIC
    CTX -->|"puede incluir resultados de"| SQL
    CHUNK -->|"puede alimentar"| MEMORY

    style DOCS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style CHUNK fill:#F5F5F5,stroke:#000000,stroke-width:2
    style INDEX fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RET fill:#F5F5F5,stroke:#000000,stroke-width:2
    style CTX fill:#F5F5F5,stroke:#000000,stroke-width:2
    style GEN fill:#F5F5F5,stroke:#000000,stroke-width:2
    style CITES fill:#F5F5F5,stroke:#000000,stroke-width:2
    style ABST fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TRACE fill:#F5F5F5,stroke:#000000,stroke-width:2
    style API stroke-dasharray: 5 5
    style EMB stroke-dasharray: 5 5
    style VECTORDB stroke-dasharray: 5 5
    style HYBRID stroke-dasharray: 5 5
    style EVAL stroke-dasharray: 5 5
    style AGENTIC stroke-dasharray: 5 5
    style SQL stroke-dasharray: 5 5
    style MEMORY stroke-dasharray: 5 5

Vocabulario aprendido

El vocabulario de este capítulo no conviene memorizarlo como lista. Conviene leerlo como piezas de una máquina: cada término responde a una pregunta concreta.

Término	Responde a	Definición útil
Corpus	¿Qué puede consultar el sistema?	Conjunto de fuentes aceptadas para el RAG, con permisos, versión y propietario.
Fuente	¿De dónde salió la evidencia?	Documento, web, tabla o base de datos original.
Parser	¿Cómo convierto la fuente en texto usable?	Pieza que extrae texto, títulos, tablas y orden de lectura.
OCR	¿Qué hago si el documento es una imagen?	Técnica que convierte escaneos o imágenes en texto recuperable.
Chunk	¿Cuál es la unidad mínima recuperable?	Fragmento que puede buscarse, meterse en contexto y citarse.
Metadata	¿Cómo filtro y explico un chunk?	Datos como curso, vigencia, sección, página, rol, hash y fecha.
ACL	¿Quién puede recuperar cada fragmento?	Regla de acceso aplicada antes de construir contexto.
Hash	¿Cómo sé si cambió una fuente?	Huella calculada del texto o archivo para detectar cambios.
Embedding	¿Cómo comparo significado aproximado?	Vector numérico que representa una pregunta o fragmento.
Vector store	¿Dónde guardo vectores y metadata?	Almacén preparado para buscar por similitud y filtros.
FTS	¿Cómo busco palabras exactas?	Búsqueda textual clásica sobre términos, frases y campos.
BM25	¿Cómo ordeno resultados por relevancia léxica?	Ranking que combina frecuencia de términos y rareza informativa.
ANN	¿Cómo busco vectores a escala?	Búsqueda aproximada de vecinos cercanos para no comparar contra todo.
Top-k	¿Cuántos candidatos saco?	Número de resultados que pasan a rerank, contexto o evaluación.
RRF	¿Cómo mezclo rankings distintos?	Fusión por posiciones; útil para combinar BM25 y embeddings.
Reranker	¿Cómo ordeno mejor candidatos ya encontrados?	Modelo o regla más lenta que reevalúa resultados prometedores.
Context builder	¿Qué lee finalmente el modelo?	Pieza que selecciona, ordena, recorta y etiqueta evidencia.
Cita	¿Qué fuente sostiene esta frase?	Referencia trazable a chunk, documento, página, sección y versión.
Grounding	¿La respuesta está apoyada en evidencia?	Grado en que cada afirmación importante sale de los chunks recuperados.
Abstención	¿Qué hago si no hay evidencia suficiente?	Responder que falta soporte en vez de inventar.
Traza	¿Cómo depuro una respuesta?	Registro de pregunta, filtros, rankings, contexto, modelo, coste y salida.
File Search	¿Qué delego si uso una solución gestionada?	Herramienta alojada para subir archivos, buscar en vector store y pasar contexto al modelo.

Dónde solía tropezar yo

Error	Por qué es un error	Antídoto
Llamar RAG a cualquier chat con documentos	Puede no haber filtros, citas, trazas ni abstención.	Exigir contrato de evidencia desde el principio.
Trocear por tamaño sin mirar estructura	Cortas definiciones, excepciones o pasos completos.	Partir por secciones, títulos y unidades citables.
Meter demasiado contexto	El modelo recibe ruido y puede mezclar fuentes.	Medir top-k, deduplicar y respetar presupuesto.
Confiar en la cita generada sin validarla	El modelo puede citar un fragmento que no sostiene la frase.	Construir citas desde ids recuperados, no desde memoria del modelo.
No abstenerse nunca	El sistema responde incluso cuando no hay evidencia.	Definir umbrales y respuesta estándar de insuficiencia.
Olvidar permisos en retrieval	El texto ya entró al contexto aunque luego no lo muestres.	Aplicar filtros antes de recuperar y antes de construir contexto.
Evaluar solo la respuesta final	No sabes si falló retrieval, chunking o generación.	Guardar trazas por etapa; el capítulo 10 entra ahí.

Antes de pasar página

En resumen

Idea fuerza	Detalle
RAG une recuperación y generación.	El modelo responde con contexto externo recuperado en tiempo de consulta.
RAG no es memoria ni entrenamiento.	No cambia pesos; recupera evidencia externa y actualizable.
Usamos RAG cuando necesitamos fuentes.	Información cambiante, privada, citable o filtrada por permisos.
Las dimensiones importan.	Afectan representación, almacenamiento, latencia, coste y reindexado.
El chunk es la unidad de confianza.	Si no puedes citarlo, no deberías usarlo como evidencia.
Las soluciones de terceros aceleran, no deciden.	Delegan infraestructura o composición, pero no sustituyen evaluación y permisos.
Optimizar exige medir por capas.	Corpus, parsing, chunking, retrieval, rerank, contexto y generación fallan de formas distintas.
RAG no es solo texto plano.	Puede incorporar tablas, imágenes, audio, vídeo, código, grafos, bases de datos y tools si son recuperables y citables.
Citar exige diseño.	La cita debe apuntar a una fuente concreta y vigente.
Abstenerse es parte del producto.	Cuando falta evidencia, responder menos es responder mejor.
El primer RAG debe dejar trazas.	Query, filtros, chunks, scores, prompt y respuesta permiten depurar.

Para saber más

Cormack, G. V., Clarke, C. L. A. y Buettcher, S. (2009). Reciprocal Rank Fusion Outperforms Condorcet and Individual Rank Learning Methods. SIGIR, 758-759. https://doi.org/10.1145/1571941.1572114

deepset. (2026). Pipelines. https://docs.haystack.deepset.ai/docs/pipelines

Google Cloud. (2026). Vertex AI RAG Engine overview. https://docs.cloud.google.com/vertex-ai/generative-ai/docs/rag-engine/rag-overview

LangChain. (2026). Retrieval. https://docs.langchain.com/oss/python/langchain/retrieval

Lewis, P. et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. NeurIPS 33, 9459-9474. https://papers.nips.cc/paper/2020/hash/6b493230205f780e1bc26945df7481e5-Abstract.html

LlamaIndex. (2026). Introduction to RAG. https://docs.llamaindex.ai/en/stable/understanding/rag/

OpenAI. (2026). File search. https://platform.openai.com/docs/guides/tools-file-search/

Qdrant. (2026). Indexing. https://qdrant.tech/documentation/manage-data/indexing/

Robertson, S. y Zaragoza, H. (2009). The Probabilistic Relevance Framework: BM25 and Beyond. Foundations and Trends in Information Retrieval, 3(4), 333-389. https://doi.org/10.1561/1500000019

Notas

Lewis, P. et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. NeurIPS 33, 9459-9474. https://papers.nips.cc/paper/2020/hash/6b493230205f780e1bc26945df7481e5-Abstract.html. ↩
Lewis et al., 2020. ↩
OpenAI. (2026). File search. https://platform.openai.com/docs/guides/tools-file-search/. Consultado el 25 de mayo de 2026. ↩
LangChain. (2026). Retrieval. https://docs.langchain.com/oss/python/langchain/retrieval. Consultado el 25 de mayo de 2026. ↩
LlamaIndex. (2026). Introduction to RAG. https://docs.llamaindex.ai/en/stable/understanding/rag/. Consultado el 25 de mayo de 2026. ↩
deepset. (2026). Pipelines. https://docs.haystack.deepset.ai/docs/pipelines. Consultado el 25 de mayo de 2026. ↩
Google Cloud. (2026). Vertex AI RAG Engine overview. https://docs.cloud.google.com/vertex-ai/generative-ai/docs/rag-engine/rag-overview. Consultado el 25 de mayo de 2026. ↩
Microsoft. (2026). Retrieval-augmented generation in Azure AI Search. https://learn.microsoft.com/en-us/azure/search/retrieval-augmented-generation-overview. Consultado el 25 de mayo de 2026. ↩
Pinecone. (2026). Build a RAG chatbot. https://docs.pinecone.io/guides/get-started/build-a-rag-chatbot. Consultado el 25 de mayo de 2026. Weaviate. (2026). Retrieval Augmented Generation (RAG). https://docs.weaviate.io/weaviate/search/generative. Consultado el 25 de mayo de 2026. ↩
Robertson, S. y Zaragoza, H. (2009). The Probabilistic Relevance Framework: BM25 and Beyond. Foundations and Trends in Information Retrieval, 3(4), 333-389. https://doi.org/10.1561/1500000019. Cormack, G. V., Clarke, C. L. A. y Buettcher, S. (2009). Reciprocal Rank Fusion Outperforms Condorcet and Individual Rank Learning Methods. SIGIR, 758-759. https://doi.org/10.1145/1571941.1572114. ↩
OpenAI, 2026. ↩
LangChain, 2026. ↩
LlamaIndex, 2026. ↩
deepset, 2026. ↩
OpenAI, 2026. ↩

Capítulo 10

Facsímil 4 · La caja de herramientas

Capítulo 10: Evaluar RAG: retrieval, groundedness y abstención

La demo no cuenta como evaluación

En el capítulo 09 montamos el primer RAG serio: corpus, chunks, embeddings, retrieval, contexto, citas y abstención. Ahora viene la parte que separa una demo de un sistema profesional: demostrar que mejora, saber dónde falla y decidir cuándo no debe responder.

Un RAG puede fallar de formas muy distintas. Puede no recuperar el documento correcto. Puede recuperarlo y no meterlo en el contexto final. Puede meterlo y redactar algo que no está sostenido. Puede citar una fuente que no dice eso. Puede contestar cuando debería abstenerse. Si solo miras la respuesta final, llegas tarde: ves el síntoma, pero no el órgano que falló.

Evaluar RAG es medir la cadena completa:

¿La pregunta está en un conjunto de evaluación representativo?
¿El corpus contiene la evidencia necesaria?
¿El retrieval trae esa evidencia entre los primeros resultados?
¿El context builder la mete en el prompt sin ahogarla en ruido?
¿La respuesta está apoyada por el contexto?
¿Las citas apuntan a fragmentos que sostienen lo dicho?
¿El sistema se abstiene cuando no hay evidencia?
¿El coste, la latencia y la operación siguen siendo aceptables?

La evaluación no es una fase final. Es una pieza del producto.

Estado del arte con fecha de corte

Fecha de corte: 25 de mayo de 2026.
Fuentes consultadas ese día: documentación de Ragas, TruLens, LangSmith, LlamaIndex, Phoenix y OpenAI Graders; y referencias académicas sobre RAG, retrieval y benchmarks como BEIR/MTEB.

RAGAS propuso evaluar RAG separando componentes como recuperación, relevancia y fidelidad de la respuesta.¹ La documentación actual de Ragas organiza métricas de RAG como context precision, context recall, response relevancy, faithfulness y métricas multimodales.² TruLens populariza una tríada muy práctica: relevancia del contexto, groundedness y relevancia de la respuesta.³ LangSmith, LlamaIndex y Phoenix empujan una idea parecida desde producto: datasets, experimentos, trazas, evaluadores y comparación entre versiones.⁴

OpenAI Graders documenta la idea de evaluadores configurables con criterios, escalas y umbrales, incluyendo verificaciones de texto, similitud, evaluadores de modelo y ejecución de código.⁵ La lección importante para nuestro libro no es “usa esta herramienta”, sino “define la rúbrica y conserva la traza”.

Familia	Qué mide	Cuándo usarla
Métricas clásicas de retrieval	Si los chunks esperados aparecen y en qué posición.	Antes de mirar la respuesta del LLM.
Métricas de contexto	Si el contexto final es útil, completo y no ruidoso.	Cuando el retrieval trae candidatos pero la respuesta falla.
Métricas de groundedness	Si las afirmaciones están sostenidas por el contexto.	Para respuestas citadas, informes y asistentes de documentación.
Métricas de abstención	Si responde cuando debe y se calla cuando toca.	En dominios donde inventar cuesta confianza.
Métricas de operación	Latencia, coste, errores, cobertura y deriva.	Cuando el RAG ya vive en una aplicación.

Qué significa evaluar por capas

Un RAG se evalúa por capas porque cada capa tiene una pregunta distinta. Si solo mides “respuesta correcta”, no sabes si mejorar embeddings, chunking, prompt, reranker o corpus.

Capa	Pregunta	Evidencia que necesitas
Corpus	¿Existe la fuente correcta?	Documento vigente, versión, propietario y fecha.
Parsing	¿El texto extraído es fiel?	Comparación contra PDF, HTML, tabla o fuente original.
Chunking	¿La unidad recuperable sostiene una respuesta?	Chunks con título, sección, página y hash.
Retrieval	¿Aparece la evidencia en top-k?	Ranking de chunks y qrels.
Reranking	¿Sube la evidencia buena?	Ranking antes/después y relevancia graduada.
Context builder	¿El modelo recibe lo necesario y no demasiado ruido?	Contexto final enviado al LLM.
Generación	¿La respuesta contesta con contrato?	Respuesta, citas, formato y abstención.
Groundedness	¿Cada afirmación está sostenida?	Claims separados y evidencia por claim.
Operación	¿El sistema aguanta uso real?	Trazas, latencia, coste, errores y feedback.

La regla de ingeniería es sencilla: primero evalúa retrieval sin LLM; luego evalúa generación con contexto fijo; después evalúa el sistema completo. Si mezclas todo desde el principio, cada fallo parece misterioso.

Dataset de evaluación: el corazón del sistema

Un dataset de evaluación no es un conjunto de preguntas bonitas. Es un contrato de verdad para comparar versiones. Debe contener preguntas que representen el uso real, preguntas que el sistema debe responder, preguntas que debe rechazar por falta de evidencia y preguntas donde los filtros importan.

Un ejemplo de fila mínima:

Campo	Para qué sirve
`id`	Identificador estable de la pregunta.
`pregunta`	Lo que una persona o sistema preguntaría.
`answerable`	Si el corpus contiene evidencia suficiente.
`gold_chunks`	Chunks esperados o aceptables.
`gold_answer`	Respuesta de referencia, si existe.
`gold_citations`	Citas esperadas.
`filtros`	Curso, rol, vigencia, idioma, cliente o tenant.
`tipo`	Single-hop, multi-hop, tabla, código, imagen, temporal, etc.
`dificultad`	Fácil, media, difícil, o escala propia.
`criterio`	Qué debe ocurrir para considerar la respuesta válida.

No todas las preguntas necesitan una respuesta literal de referencia. Para retrieval basta con qrels: juicios de relevancia entre pregunta y chunks. Para groundedness necesitas contexto y respuesta. Para abstención necesitas casos sin evidencia suficiente.

Tipo de pregunta	Ejemplo	Qué prueba
Directa	“¿Cuándo se abre la ampliación de matrícula?”	Retrieval simple y cita directa.
Con filtro	“¿Qué aplica al curso 2026?”	Metadata y vigencia.
Multi-hop	“¿Puedo ampliar si tengo pagos pendientes y cómo se solicita?”	Recuperar más de un fragmento.
Tabla	“¿Qué plazo corresponde a segunda matrícula?”	Parsing y estructura tabular.
No respondible	“¿Cuál es el horario de cafetería?” si no está en corpus.	Abstención.
Contradicción documental	Dos fuentes con fechas distintas.	Vigencia, prioridad y explicación.
Texto largo	Preguntas que requieren contexto distribuido.	Recall, deduplicación y presupuesto.

Ejemplos de datasets de evaluación que puedes construir en un proyecto real:

Dataset	Qué contiene	Por qué merece existir
FAQ real	Preguntas frecuentes, respuesta esperada y fuente exacta.	Mide si el RAG resuelve lo que más se pregunta.
Normativa vigente	Preguntas con `curso`, `fecha`, `rol` y chunks esperados.	Mide filtros y prioridad documental.
Casos sin evidencia	Preguntas plausibles cuya respuesta no está en el corpus.	Mide abstención correcta.
Multi-hop	Preguntas que exigen dos o más fuentes.	Mide si el contexto compone evidencia sin mezclar.
Tablas	Preguntas sobre filas, columnas, importes, plazos o unidades.	Mide parsing y recuperación estructurada.
Citas difíciles	Respuestas donde una cita parcial no basta.	Mide si la cita sostiene la afirmación completa.
Regresión	Casos que ya fallaron en producción y se corrigieron.	Evita reintroducir errores.
Segmentos críticos	Preguntas por idioma, área, producto, cliente o perfil.	Evita que la media esconda fallos locales.

Si vienes del facsímil 3, capítulo 06, la diferencia es esta: datasets como FLAN, Dolly-15K, HH-RLHF o LAION-5B pueden entrenar o adaptar modelos; este dataset de evaluación no debería entrenar el sistema que estás midiendo. Su trabajo es ponerle un espejo fiable.

El dataset debe crecer desde producción. Las primeras 30 preguntas sirven para empezar. Las siguientes 300 salen de dudas reales, tickets, búsquedas sin respuesta, feedback de usuarios y revisiones de profesorado o equipo de dominio.

Qrels y relevancia graduada

Un qrel es un juicio de relevancia. Dice que una pregunta necesita tal documento o tal chunk. Puede ser binario o graduado.

Relevancia	Significado
0	No ayuda a responder.
1	Relacionado, pero insuficiente.
2	Útil para parte de la respuesta.
3	Evidencia central.

Ejemplo:

Pregunta	Chunk	Relevancia
`q1` ampliación con pagos pendientes	`norm-2026#c1`	3
`q1` ampliación con pagos pendientes	`faq-campus#c1`	0
`q2` acceso al campus	`faq-campus#c1`	3
`q3` horario de cafetería	ningún chunk	no respondible

Esta tabla permite evaluar retrieval sin llamar al LLM. Eso ahorra coste y te dice si la base del sistema funciona.

Métricas de retrieval

Las métricas de retrieval responden a una pregunta: ¿la evidencia correcta aparece en el ranking?

Sea $G_q$ el conjunto de chunks relevantes para una pregunta $q$ , y sea $R_k(q)$ la lista de los $k$ primeros chunks recuperados.

\operatorname{Precision@k}(q)= \frac{|R_k(q) \cap G_q|}{k}

\operatorname{Recall@k}(q)= \frac{|R_k(q) \cap G_q|}{|G_q|}

\operatorname{Hit@k}(q)= \begin{cases} 1, & \text{si } R_k(q) \cap G_q \ne \varnothing \ 0, & \text{si } R_k(q) \cap G_q = \varnothing \end{cases}

Métrica	Qué te dice	Cuidado
Precision@k	De lo que recuperas, cuánto sirve.	Puede ser baja si necesitas traer contexto amplio.
Recall@k	De lo que necesitabas, cuánto aparece.	Puede subir trayendo demasiado ruido.
Hit@k	Si aparece al menos una evidencia.	No mide si aparece toda la evidencia.
MRR	Qué tan pronto aparece la primera evidencia.	No basta para preguntas multi-hop.
nDCG@k	Si lo más relevante aparece arriba.	Requiere relevancia graduada.

MRR se calcula con la posición de la primera evidencia relevante:

\operatorname{RR}(q)= \frac{1}{\operatorname{rank}_q}

Si el primer chunk relevante aparece en posición 1, RR vale 1. Si aparece en posición 5, vale 0,2. Si no aparece, vale 0. El MRR es la media de RR en muchas preguntas.

nDCG usa relevancia graduada:

\operatorname{DCG@k} = \sum_{i=1}^{k} \frac{2^{rel_i}-1}{\log_2(i+1)}

\operatorname{nDCG@k} = \frac{\operatorname{DCG@k}}{\operatorname{IDCG@k}}

Símbolo	Significado
$rel_i$	Relevancia del resultado en posición $i$ .
$DCG$	Ganancia descontada por posición.
$IDCG$	DCG ideal si los mejores resultados estuvieran arriba.

Precision@k y recall@k vienen de la tradición de recuperación de información. BEIR y MTEB son recordatorios útiles: un retriever puede brillar en un benchmark y fallar en tu dominio.⁶ Por eso el benchmark público orienta, pero el dataset interno decide.

Métricas de contexto

El retrieval devuelve candidatos. El contexto final es lo que realmente lee el modelo. Entre una cosa y otra puede haber deduplicación, recorte, reordenación, filtros, prioridad de fuentes y presupuesto de tokens.

Ragas llama context precision y context recall a dos ideas útiles.⁷ Las traduzco de forma operativa:

Métrica	Pregunta
Context precision	¿El contexto incluido es útil o está lleno de ruido?
Context recall	¿El contexto contiene toda la evidencia necesaria?

Ejemplo de fórmula. Puedes empezar con una versión sencilla:

\operatorname{ContextPrecision} = \frac{\text{chunks útiles en contexto}}{\text{chunks en contexto}}

\operatorname{ContextRecall} = \frac{\text{evidencias esperadas presentes}}{\text{evidencias esperadas}}

La diferencia con retrieval es sutil pero importante. Retrieval@k mide el ranking bruto. Context precision/recall mide el paquete de evidencia que llegó al prompt.

Fallo	Retrieval	Contexto
El chunk bueno no aparece en top 20.	Falló retrieval.	No tiene oportunidad.
El chunk bueno aparece en top 5 pero se recorta.	Retrieval bien.	Falló context builder.
Hay cinco chunks repetidos.	Retrieval dudoso.	Falló deduplicación.
Entra una fuente antigua y otra vigente.	Filtros dudosos.	Falló prioridad o explicación.

Groundedness, faithfulness y citas

Groundedness significa que la respuesta está apoyada por el contexto recuperado. Faithfulness suele usarse de forma cercana: la respuesta no añade hechos que no se desprenden del contexto. TruLens lo conecta con la tríada: contexto relevante, respuesta apoyada en el contexto y respuesta relevante para la pregunta.⁸

La forma práctica de evaluarlo es separar la respuesta en afirmaciones.

Respuesta	Claims
“La ampliación se abre en septiembre y no puede haber pagos vencidos.”	1. La ampliación se abre en septiembre. 2. No puede haber pagos vencidos.

Cada claim se evalúa contra el contexto:

Claim	Evidencia	Resultado
La ampliación se abre en septiembre.	Chunk `norm-2026#c1`.	Sostenido.
No puede haber pagos vencidos.	Chunk `norm-2026#c1`.	Sostenido.
Se aprueba automáticamente.	No aparece en contexto.	No sostenido.

Ejemplo de fórmula. Una métrica simple:

\operatorname{Groundedness} = \frac{\text{claims sostenidos}}{\text{claims totales}}

La cita añade otra capa. No basta con que la respuesta sea cierta: debe citar el fragmento correcto.

\operatorname{CitationPrecision} = \frac{\text{citas válidas usadas}}{\text{citas usadas}}

\operatorname{CitationRecall} = \frac{\text{evidencias citadas}}{\text{evidencias necesarias}}

Caso	Groundedness	Citas	Diagnóstico
Respuesta correcta y cita correcta.	Alta.	Alta.	Bien.
Respuesta correcta sin cita.	Alta.	Baja.	Falta trazabilidad.
Respuesta correcta con cita equivocada.	Puede parecer alta.	Baja.	Interfaz de confianza rota.
Respuesta inventada con cita real.	Baja.	Engañosa.	El chunk citado no sostiene la frase.

Un evaluador LLM puede ayudar a evaluar groundedness, pero no es oráculo. Debe recibir rúbrica clara, contexto, respuesta y, si existe, respuesta de referencia. Sus resultados deben compararse con revisión humana en una muestra. OpenAI Graders documenta distintos tipos de evaluadores y la idea de devolver una puntuación numérica contra criterios.⁹

Evaluar abstención

Abstenerse no significa que el sistema sea torpe. En RAG, abstenerse puede ser la respuesta correcta. Hay preguntas que el corpus no cubre, fuentes contradictorias, permisos insuficientes o evidencia demasiado débil.

Podemos modelar la decisión:

d(q)= \begin{cases} \operatorname{responder}, & \text{si } s(q) \ge \tau \ \operatorname{abstenerse}, & \text{si } s(q) < \tau \end{cases}

Símbolo	Significado
$q$	Pregunta.
$s(q)$	Soporte estimado: evidencia, scores, citas, groundedness.
$\tau$	Umbral mínimo para responder.
$d(q)$	Decisión final.

La matriz de abstención:

Realidad	El sistema responde	El sistema se abstiene
Hay evidencia suficiente.	Respuesta evaluable.	Abstención innecesaria.
No hay evidencia suficiente.	Respuesta no sostenida.	Abstención correcta.

Métricas útiles:

\operatorname{Coverage} = \frac{\text{preguntas respondidas}}{\text{preguntas totales}}

\operatorname{CorrectAbstentionRate} = \frac{\text{abstenciones correctas}}{\text{preguntas no respondibles}}

\operatorname{UnsupportedAnswerRate} = \frac{\text{respuestas sin soporte}}{\text{preguntas no respondibles}}

Subir cobertura no siempre es bueno. Si responde más a costa de inventar más, el sistema empeora. El umbral debe calibrarse con curvas: cuánto ganas en cobertura y cuánto pierdes en precisión de respuesta.

Arquitectura de evaluación

El diagrama tiene una idea central: cada experimento debe producir trazas comparables. Si cambias embeddings, chunking o prompt, no basta con ver una respuesta bonita. Comparas contra baseline y miras qué capa se movió.

Gates: decidir si una versión publica

Un gate es una regla de publicación. Evita que un cambio que mejora una métrica rompa otra más importante.

Métrica	Umbral ejemplo	Qué protege
Recall@5	$\ge 0,85$	Que la evidencia aparezca.
nDCG@5	$\ge 0,80$	Que aparezca arriba.
Groundedness	$\ge 0,90$	Que no añada afirmaciones sin soporte.
Citation precision	$\ge 0,95$	Que las citas sean revisables.
Correct abstention	$\ge 0,85$	Que no responda fuera del corpus.
Unsupported answer rate	$\le 0,02$	Que no conteste sin evidencia.
Latencia p95	$\le 2,5s$	Que sea usable.
Coste por respuesta	$\le presupuesto$	Que sea sostenible.

Los umbrales no salen de una tabla universal. Salen del dominio. Un asistente de lectura puede aceptar más incertidumbre que un asistente que orienta trámites administrativos. Lo importante es que el equipo escriba el umbral antes de mirar si su cambio favorito pasa.

Evaluadores LLM y rúbricas

Los evaluadores LLM son útiles para escalar revisión, pero hay que usarlos con cuidado. Un evaluador no sustituye una rúbrica: ejecuta una rúbrica.

Una rúbrica mínima para groundedness:

Evalúa si la respuesta está sostenida por el contexto.

Entrada:
- Pregunta del usuario.
- Contexto recuperado con ids de chunk.
- Respuesta generada.

Devuelve JSON:
{
  "score": 0.0 a 1.0,
  "claims_no_sostenidos": ["..."],
  "citas_invalidas": ["..."],
  "decision": "pasa" | "revisar" | "falla"
}

Criterio:
- 1.0: todas las afirmaciones relevantes están sostenidas.
- 0.5: la respuesta mezcla evidencia con inferencias no citadas.
- 0.0: la respuesta contradice o inventa respecto al contexto.

Buenas prácticas:

Práctica	Motivo
Separar evaluación de retrieval y generación.	Un evaluador de respuesta no descubre por sí solo si faltó un chunk.
Guardar entradas del evaluador.	Sin prompt, contexto y respuesta no puedes auditar el score.
Usar muestras revisadas por personas.	El evaluador debe calibrarse contra criterio humano.
Evaluar con varios tipos de pregunta.	Una métrica media puede esconder fallos en tablas, fechas o multi-hop.
Repetir evaluaciones críticas.	Algunos evaluadores tienen variabilidad; mide estabilidad.
No entrenar el sistema para complacer al evaluador.	El objetivo es utilidad verificable, no ganar una métrica estrecha.

Evaluación offline, online y sombra

Hay tres modos de evaluación que se complementan.

Modo	Qué hace	Cuándo usarlo
Offline	Ejecuta un dataset fijo contra una versión del RAG.	Antes de publicar cambios.
Sombra	Ejecuta una versión candidata con tráfico real sin mostrarla.	Para medir deriva y casos reales sin afectar a usuarios.
Online	Mide interacción real, feedback, coste, latencia y errores.	Cuando el sistema está en uso.

Offline te da repetibilidad. Sombra te da realidad sin exposición directa. Online te da señales de producto. Ninguna sustituye a las otras.

Manos a la obra

Vamos a construir un evaluador local de RAG. No necesita APIs. No pretende reemplazar Ragas, TruLens, LangSmith o Phoenix; pretende que entiendas qué está midiendo cada herramienta por dentro.

Guarda esto como evaluar_rag_minimo.py:

from collections import Counter
import json
import math


K = 3

CHUNKS = {
    "norm-2026#c1": (
        "La ampliación de matrícula se abre en septiembre. "
        "El estudiante puede solicitar ampliación si no mantiene "
        "pagos pendientes vencidos."
    ),
    "faq-campus#c1": (
        "Si no puedes entrar al campus virtual, revisa el doble "
        "factor y restablece la contraseña desde la página de acceso."
    ),
    "norm-2024#c1": (
        "En 2024 la ampliación de matrícula no revisaba pagos "
        "pendientes antes de enviar la solicitud."
    ),
    "becas-2026#c1": (
        "Las becas generales tienen calendario propio y no modifican "
        "la normativa de ampliación de matrícula."
    ),
}

RUNS = [
    {
        "id": "q1",
        "pregunta": "¿Puedo ampliar matrícula con pagos pendientes?",
        "answerable": True,
        "gold_chunks": {"norm-2026#c1"},
        "retrieved": [
            ("norm-2026#c1", 3),
            ("becas-2026#c1", 1),
            ("faq-campus#c1", 0),
        ],
        "answer": (
            "Puedes solicitar ampliación en septiembre si no mantienes "
            "pagos pendientes vencidos. [norm-2026#c1]"
        ),
        "citations": {"norm-2026#c1"},
        "claims": [
            "La ampliación se abre en septiembre",
            "No puede haber pagos pendientes vencidos",
        ],
        "abstained": False,
    },
    {
        "id": "q2",
        "pregunta": "¿Cuál es el horario de cafetería?",
        "answerable": False,
        "gold_chunks": set(),
        "retrieved": [
            ("faq-campus#c1", 0),
            ("becas-2026#c1", 0),
            ("norm-2026#c1", 0),
        ],
        "answer": "No tengo evidencia suficiente.",
        "citations": set(),
        "claims": [],
        "abstained": True,
    },
    {
        "id": "q3",
        "pregunta": "¿Cómo recupero acceso al campus virtual?",
        "answerable": True,
        "gold_chunks": {"faq-campus#c1"},
        "retrieved": [
            ("norm-2026#c1", 0),
            ("faq-campus#c1", 3),
            ("becas-2026#c1", 0),
        ],
        "answer": (
            "Revisa el doble factor y restablece la contraseña desde "
            "la página de acceso. [faq-campus#c1]"
        ),
        "citations": {"faq-campus#c1"},
        "claims": [
            "Revisa el doble factor",
            "La contraseña se restablece desde la página de acceso",
        ],
        "abstained": False,
    },
    {
        "id": "q4",
        "pregunta": "¿La ampliación se aprueba automáticamente?",
        "answerable": False,
        "gold_chunks": set(),
        "retrieved": [
            ("norm-2026#c1", 1),
            ("norm-2024#c1", 0),
            ("becas-2026#c1", 0),
        ],
        "answer": (
            "Sí, la ampliación se aprueba automáticamente. "
            "[norm-2026#c1]"
        ),
        "citations": {"norm-2026#c1"},
        "claims": ["La ampliación se aprueba automáticamente"],
        "abstained": False,
    },
]

STOPWORDS = {
    "a",
    "al",
    "con",
    "de",
    "del",
    "desde",
    "el",
    "en",
    "es",
    "la",
    "las",
    "los",
    "no",
    "por",
    "se",
    "si",
    "y",
}


def tokens(texto):
    limpio = "".join(
        c.lower() if c.isalnum() else " "
        for c in texto
    )
    return {
        token
        for token in limpio.split()
        if token not in STOPWORDS and len(token) > 2
    }


def precision_at_k(run, k):
    top = run["retrieved"][:k]
    if not top:
        return 0.0
    relevantes = sum(1 for _chunk_id, rel in top if rel > 0)
    return relevantes / len(top)


def recall_at_k(run, k):
    gold = run["gold_chunks"]
    if not gold:
        return None
    top_ids = {chunk_id for chunk_id, _rel in run["retrieved"][:k]}
    return len(top_ids & gold) / len(gold)


def hit_at_k(run, k):
    recall = recall_at_k(run, k)
    if recall is None:
        return None
    return 1.0 if recall > 0 else 0.0


def reciprocal_rank(run):
    gold = run["gold_chunks"]
    if not gold:
        return None
    for pos, (chunk_id, _rel) in enumerate(run["retrieved"], start=1):
        if chunk_id in gold:
            return 1 / pos
    return 0.0


def dcg(relevancias, k):
    total = 0.0
    for pos, rel in enumerate(relevancias[:k], start=1):
        total += (2**rel - 1) / math.log2(pos + 1)
    return total


def ndcg_at_k(run, k):
    relevancias = [rel for _chunk_id, rel in run["retrieved"]]
    ideal = sorted(relevancias, reverse=True)
    ideal_dcg = dcg(ideal, k)
    if ideal_dcg == 0:
        return None
    return dcg(relevancias, k) / ideal_dcg


def citation_precision(run):
    if not run["citations"]:
        return None
    validas = run["citations"] & run["gold_chunks"]
    return len(validas) / len(run["citations"])


def citation_recall(run):
    if not run["gold_chunks"]:
        return None
    validas = run["citations"] & run["gold_chunks"]
    return len(validas) / len(run["gold_chunks"])


def claim_supported(claim, cited_chunks):
    claim_tokens = tokens(claim)
    if not claim_tokens:
        return True
    evidence = " ".join(CHUNKS[c] for c in cited_chunks if c in CHUNKS)
    evidence_tokens = tokens(evidence)
    overlap = len(claim_tokens & evidence_tokens)
    return overlap / len(claim_tokens) >= 0.5


def groundedness(run):
    if not run["claims"]:
        return None
    supported = sum(
        1
        for claim in run["claims"]
        if claim_supported(claim, run["citations"])
    )
    return supported / len(run["claims"])


def decision(run):
    if not run["answerable"] and run["abstained"]:
        return "abstencion_correcta"
    if not run["answerable"] and not run["abstained"]:
        return "respuesta_sin_soporte"
    if run["answerable"] and run["abstained"]:
        return "abstencion_innecesaria"

    grounded = groundedness(run) or 0.0
    cit_rec = citation_recall(run) or 0.0
    if grounded >= 0.8 and cit_rec >= 1.0:
        return "respuesta_sostenida"
    return "respuesta_debil"


def media(valores):
    limpios = [v for v in valores if v is not None]
    if not limpios:
        return None
    return sum(limpios) / len(limpios)


def resumen(runs):
    decisiones = Counter(decision(run) for run in runs)
    respondidas = sum(1 for run in runs if not run["abstained"])
    no_respondibles = sum(1 for run in runs if not run["answerable"])
    sin_soporte = decisiones["respuesta_sin_soporte"]

    return {
        "precision@3": media(precision_at_k(run, K) for run in runs),
        "recall@3": media(recall_at_k(run, K) for run in runs),
        "hit@3": media(hit_at_k(run, K) for run in runs),
        "mrr": media(reciprocal_rank(run) for run in runs),
        "ndcg@3": media(ndcg_at_k(run, K) for run in runs),
        "citation_precision": media(citation_precision(r) for r in runs),
        "citation_recall": media(citation_recall(r) for r in runs),
        "groundedness": media(groundedness(run) for run in runs),
        "coverage": respondidas / len(runs),
        "unsupported_answer_rate": sin_soporte / max(no_respondibles, 1),
        "decisiones": dict(decisiones),
    }


if __name__ == "__main__":
    for run in RUNS:
        print(run["id"], decision(run))
    print(json.dumps(resumen(RUNS), indent=2, ensure_ascii=False))

Salida esperada aproximada:

q1 respuesta_sostenida
q2 abstencion_correcta
q3 respuesta_sostenida
q4 respuesta_sin_soporte
{
  "precision@3": 0.3333,
  "recall@3": 1.0,
  "hit@3": 1.0,
  "mrr": 0.75,
  "ndcg@3": 0.877,
  "citation_precision": 0.6667,
  "citation_recall": 1.0,
  "groundedness": 0.6667,
  "coverage": 0.75,
  "unsupported_answer_rate": 0.5,
  "decisiones": {
    "respuesta_sostenida": 2,
    "abstencion_correcta": 1,
    "respuesta_sin_soporte": 1
  }
}

Este ejemplo enseña algo importante: recall@3 puede salir perfecto y, aun así, el sistema puede responder sin soporte en una pregunta no respondible. Por eso evaluar RAG exige retrieval, groundedness, citas y abstención a la vez.

Cómo encaja todo

graph TD
    subgraph "Capítulo 10: evaluación RAG"
        DATASET["Dataset evaluable"]
        QRELS["Qrels y gold chunks"]
        TRACE["Trazas"]
        RETMET["Retrieval metrics"]
        CTXMET["Context metrics"]
        GROUNDED["Groundedness"]
        CITEMET["Citas"]
        ABSTMET["Abstención"]
        GATE["Gate de publicación"]
    end
    subgraph "Viene de antes"
        EMB["Embeddings (F4C7)"]
        VECTORDB["Base vectorial (F4C8)"]
        HYBRID["Búsqueda híbrida (F4C8)"]
        RAG["Primer RAG (F4C9)"]
    end
    subgraph "Sigue después"
        AGENTIC["Agentic RAG (F4C11)"]
        SQL["Text-to-SQL (F4C12)"]
        LAB["Laboratorio mínimo (F4C13)"]
        OPS["Operación y producto (F6)"]
    end

    DATASET -->|"define verdad de prueba"| QRELS
    QRELS -->|"evalúa"| RETMET
    TRACE -->|"permite calcular"| RETMET
    TRACE -->|"permite calcular"| CTXMET
    TRACE -->|"permite revisar"| GROUNDED
    TRACE -->|"permite validar"| CITEMET
    TRACE -->|"permite medir"| ABSTMET
    RETMET -->|"entra en"| GATE
    CTXMET -->|"entra en"| GATE
    GROUNDED -->|"entra en"| GATE
    CITEMET -->|"entra en"| GATE
    ABSTMET -->|"entra en"| GATE
    EMB -->|"afecta a"| RETMET
    VECTORDB -->|"afecta a"| RETMET
    HYBRID -->|"afecta a"| RETMET
    RAG -->|"produce"| TRACE
    GATE -->|"prepara"| AGENTIC
    GATE -->|"prepara"| SQL
    GATE -->|"se practica en"| LAB
    TRACE -->|"alimenta"| OPS

    style DATASET fill:#F5F5F5,stroke:#000000,stroke-width:2
    style QRELS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TRACE fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RETMET fill:#F5F5F5,stroke:#000000,stroke-width:2
    style CTXMET fill:#F5F5F5,stroke:#000000,stroke-width:2
    style GROUNDED fill:#F5F5F5,stroke:#000000,stroke-width:2
    style CITEMET fill:#F5F5F5,stroke:#000000,stroke-width:2
    style ABSTMET fill:#F5F5F5,stroke:#000000,stroke-width:2
    style GATE fill:#111111,stroke:#000000,stroke-width:2,color:#FFFFFF
    style EMB stroke-dasharray: 5 5
    style VECTORDB stroke-dasharray: 5 5
    style HYBRID stroke-dasharray: 5 5
    style RAG stroke-dasharray: 5 5
    style AGENTIC stroke-dasharray: 5 5
    style SQL stroke-dasharray: 5 5
    style LAB stroke-dasharray: 5 5
    style OPS stroke-dasharray: 5 5

Vocabulario aprendido

Término	Responde a	Definición útil
Evaluación offline	¿Mejora antes de publicar?	Prueba repetible sobre dataset fijo.
Evaluación online	¿Qué ocurre en uso real?	Medición con tráfico, feedback, coste y latencia.
Evaluación sombra	¿Cómo pruebo sin mostrar al usuario?	Ejecutar versión candidata en paralelo y registrar resultados.
Qrel	¿Qué chunk debería recuperar?	Juicio de relevancia pregunta-documento.
Precision@k	¿Cuánto ruido hay en top-k?	Proporción de resultados relevantes entre los k primeros.
Recall@k	¿Apareció la evidencia esperada?	Proporción de evidencias recuperadas.
Hit@k	¿Aparece al menos una evidencia?	Indicador binario de recuperación suficiente mínima.
MRR	¿Cuán pronto aparece la primera evidencia?	Media del inverso de la primera posición relevante.
nDCG	¿Lo más útil aparece arriba?	Métrica con relevancia graduada y descuento por posición.
Context precision	¿El contexto final está limpio?	Proporción de chunks útiles dentro del contexto usado.
Context recall	¿El contexto contiene lo necesario?	Proporción de evidencia esperada incluida en el prompt.
Groundedness	¿La respuesta se apoya en contexto?	Claims sostenidos por evidencia recuperada.
Citation precision	¿Las citas usadas son válidas?	Citas que apuntan a evidencia real entre citas usadas.
Citation recall	¿Cité toda la evidencia necesaria?	Evidencias necesarias citadas entre evidencias esperadas.
Coverage	¿Cuánto responde el sistema?	Porcentaje de preguntas no abstendidas.
Gate	¿Publicamos esta versión?	Regla de aceptación con umbrales técnicos y de producto.
Evaluador LLM	¿Quién puntúa respuestas abiertas?	Modelo evaluador guiado por una rúbrica auditable.

Dónde solía tropezar yo

Error	Por qué es un error	Antídoto
Evaluar solo la respuesta final	No sabes si falló retrieval, contexto o generación.	Guardar trazas y medir por capas.
Usar tres preguntas elegidas a mano	La demo se adapta a tus expectativas.	Crear dataset con casos reales y no respondibles.
Optimizar recall subiendo top-k sin límite	Traes más evidencia, pero también más ruido y coste.	Medir recall, precision, nDCG y tokens de contexto.
Confiar ciegamente en un evaluador LLM	El evaluador también se equivoca y depende de la rúbrica.	Calibrarlo con revisión humana y guardar entradas.
No medir abstención	El sistema aprende a contestarlo todo.	Incluir preguntas sin evidencia y umbrales.
No versionar corpus e índice	No puedes reproducir por qué respondió algo.	Guardar versión de corpus, embeddings, chunks y prompt.
Mezclar cambios	Si mejoras o empeoras, no sabes por qué.	Cambiar una variable por experimento.
Mirar solo medias	Un promedio alto oculta fallos graves por tipo de pregunta.	Reportar métricas por segmento: tabla, multi-hop, fecha, rol.

Antes de pasar página

En resumen

Idea fuerza	Detalle
Evaluar RAG es evaluar una cadena.	Corpus, parsing, retrieval, contexto, generación, citas y abstención.
Retrieval se mide antes del LLM.	Si no recuperas la evidencia, la generación no puede arreglarlo.
Groundedness exige claims.	No basta con una sensación global de respuesta correcta.
Citar también se evalúa.	Una cita debe sostener la frase que acompaña.
Abstenerse puede ser correcto.	Coverage alto con respuestas sin soporte es mala señal.
Un evaluador LLM necesita rúbrica.	La herramienta puntúa; el criterio lo diseña el equipo.
Un gate protege producto.	Publicas si la versión candidata supera umbrales críticos.
Sin trazas no hay aprendizaje.	Cada consulta debe dejar ranking, contexto, respuesta, citas y costes.

Para saber más

Arize Phoenix. (2026). Evaluate RAG. https://arize.com/docs/phoenix/cookbook/evaluation/evaluate-rag

Arize Phoenix. (2026). Evaluation concepts. https://arize.com/docs/phoenix/evaluation/concepts-evals/evaluation

Es, S., James, J., Espinosa-Anke, L. y Schockaert, S. (2023). RAGAS: Automated Evaluation of Retrieval Augmented Generation. https://arxiv.org/abs/2309.15217

LangChain. (2026). Evaluate a RAG application. https://docs.langchain.com/langsmith/evaluate-rag-tutorial

LlamaIndex. (2026). Evaluation modules. https://developers.llamaindex.ai/python/framework/module_guides/evaluating/modules/

OpenAI. (2026). Graders. https://developers.openai.com/api/docs/guides/graders

Ragas. (2026). List of available metrics. https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/

Thakur, N. et al. (2021). BEIR: A Heterogeneous Benchmark for Zero-shot Evaluation of Information Retrieval Models. https://arxiv.org/abs/2104.08663

TruLens. (2026). RAG Triad. https://www.trulens.org/getting_started/core_concepts/rag_triad/

Notas

Es, S., James, J., Espinosa-Anke, L. y Schockaert, S. (2023). RAGAS: Automated Evaluation of Retrieval Augmented Generation. https://arxiv.org/abs/2309.15217. ↩
Ragas. (2026). List of available metrics. https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/. Consultado el 25 de mayo de 2026. ↩
TruLens. (2026). RAG Triad. https://www.trulens.org/getting_started/core_concepts/rag_triad/. Consultado el 25 de mayo de 2026. ↩
LangChain. (2026). Evaluate a RAG application. https://docs.langchain.com/langsmith/evaluate-rag-tutorial. LlamaIndex. (2026). Evaluation modules. https://developers.llamaindex.ai/python/framework/module_guides/evaluating/modules/. Arize Phoenix. (2026). Evaluate RAG. https://arize.com/docs/phoenix/cookbook/evaluation/evaluate-rag. Consultado el 25 de mayo de 2026. ↩
OpenAI. (2026). Graders. https://developers.openai.com/api/docs/guides/graders. Consultado el 25 de mayo de 2026. ↩
Thakur, N. et al. (2021). BEIR: A Heterogeneous Benchmark for Zero-shot Evaluation of Information Retrieval Models. https://arxiv.org/abs/2104.08663. Muennighoff, N. et al. (2023). MTEB: Massive Text Embedding Benchmark. https://arxiv.org/abs/2210.07316. ↩
Ragas, 2026. ↩
TruLens, 2026. ↩
OpenAI, 2026. ↩

Capítulo 11

Facsímil 4 · La caja de herramientas

Capítulo 11: Agentic RAG y GraphRAG: cuándo complicar

Cuando un RAG fijo se queda corto

En el capítulo 09 construimos el RAG básico: partir una colección, buscar fragmentos, pasarlos al modelo y responder con citas. En el capítulo 10 aprendimos a medir si la evidencia aparece, si el contexto sostiene la respuesta y si el sistema sabe abstenerse.

Ese patrón funciona muy bien para preguntas directas: “¿qué dice esta normativa sobre X?”, “¿cuál es el plazo?”, “¿dónde se configura este parámetro?”. Pero en proyectos reales aparecen preguntas menos limpias:

“Compara los requisitos de matrícula con los requisitos de beca y dime dónde se contradicen.”
“¿Qué temas se repiten en todas las quejas del alumnado este curso?”
“¿Qué documentos explican por qué cambió esta política?”
“Busca primero en la normativa; si no basta, mira FAQ, calendario y expediente.”
“Esta respuesta cita una fuente floja; revisa si hay otra fuente mejor.”

Aquí ya no basta con una única búsqueda top-k. El sistema necesita planificar, reescribir consultas, dividir la pregunta, escoger fuentes, comprobar si lo recuperado basta, volver a buscar si no basta y quizá consultar un grafo de relaciones. Eso es lo que solemos llamar Agentic RAG y GraphRAG. La pregunta importante no es “¿puedo hacerlo?”, sino “¿merece la pena pagar la complejidad?”.

Estado del arte con fecha de corte

Fecha de corte: 26 de mayo de 2026.
Fuentes consultadas ese día: documentación oficial de LangChain sobre arquitecturas RAG, documentación de LlamaIndex sobre estrategias agentic, documentación de Microsoft GraphRAG, papers de ReAct, Toolformer, HyDE, Self-RAG, Corrective RAG, RAPTOR y GraphRAG, y el capítulo anterior de evaluación del propio libro.

El patrón base sigue siendo RAG: recuperar información externa en tiempo de consulta para responder con contexto específico.¹ Lo que cambia es quién decide los pasos. LangChain distingue entre RAG de dos pasos, Agentic RAG e híbridos con validación; en su documentación, el RAG de dos pasos es más predecible y el agentic gana flexibilidad a costa de latencia variable.² LlamaIndex describe estrategias agentic como routing, query transformations, sub-question query engines y agentes de datos sobre motores RAG existentes.³

La parte “agentic” bebe de trabajos como ReAct, que intercalan razonamiento y acciones para consultar fuentes externas durante la resolución.⁴ Toolformer exploró cómo modelos de lenguaje pueden aprender a usar herramientas externas mediante ejemplos auto-supervisados.⁵ En retrieval avanzado aparecen técnicas como HyDE, que genera un documento hipotético para buscar textos reales cercanos; Self-RAG, que introduce recuperación y crítica/reflexión; y Corrective RAG, que evalúa la calidad de documentos recuperados y activa acciones correctivas si la evidencia es débil.⁶

GraphRAG se volvió relevante porque muchas preguntas no piden “el chunk más parecido”, sino entender relaciones o patrones globales del corpus. El paper de Microsoft GraphRAG plantea un índice basado en grafo de entidades y resúmenes de comunidades para responder preguntas de comprensión global sobre colecciones privadas.⁷ La documentación de GraphRAG separa local search, global search, DRIFT search, basic search y question generation.⁸

Qué no es complicar bien

Complicar un RAG no significa meter un agente delante de todo. Si el sistema siempre hace una pregunta directa sobre un documento vigente, un RAG de dos pasos puede ser mejor: menos latencia, menos coste, menos puntos de fallo y evaluación más sencilla.

Tampoco significa que el modelo “piense libremente” hasta encontrar la respuesta. En ingeniería, un Agentic RAG serio tiene herramientas permitidas, límites de pasos, trazas, umbrales de evidencia y reglas de salida. Si no puedes reconstruir qué buscó, qué encontró, qué descartó y por qué respondió, no has ganado inteligencia: has perdido depuración.

GraphRAG tampoco es “usar una base de grafos porque suena potente”. Un grafo merece la pena cuando las relaciones importan: entidades, dependencias, comunidades, jerarquías, trazabilidad entre documentos, patrones globales o preguntas que no se resuelven con un párrafo aislado. Si tu corpus son veinte FAQs cortas, GraphRAG puede ser una mudanza para cruzar la calle.

Qué sí es Agentic RAG

Agentic RAG es un RAG donde el sistema puede decidir pasos intermedios antes de responder. La palabra clave no es “autonomía”; la palabra clave es control del flujo.

Un RAG fijo hace esto:

pregunta -> retrieval -> contexto -> respuesta

Un Agentic RAG puede hacer esto:

pregunta -> diagnosticar
         -> elegir herramienta
         -> buscar
         -> evaluar evidencia
         -> responder o abstenerse

Ejemplo de fórmula. La forma técnica de verlo:

s_t = (x,\; H_t,\; E_t,\; B_t)

a_t = \pi_{\theta}(s_t)

s_{t+1} = \operatorname{step}(s_t,\; a_t)

Símbolo	Significado	Ejemplo
$x$	Pregunta original.	“Compara normativa y FAQ sobre pagos pendientes”.
$H_t$	Historial de pasos hasta el momento.	Búsqueda en normativa, lectura de FAQ, validación.
$E_t$	Evidencia acumulada.	Chunks, citas, resultados SQL o relaciones de grafo.
$B_t$	Presupuesto restante.	Máximo 4 pasos, 2 búsquedas y 1 consulta externa.
$s_t$	Estado del flujo en el paso $t$ .	Lo que el sistema sabe y puede hacer ahora.
$a_t$	Acción elegida.	`buscar_normativa`, `consultar_grafo`, `responder`.
$\pi_{\theta}$	Política de decisión del modelo o del router.	Decide el siguiente paso.
$\operatorname{step}$	Ejecución controlada de una acción.	Llama a una herramienta y actualiza la traza.

La lista de acciones no debería ser infinita. En un sistema real se define algo así:

Acción	Qué hace	Cuándo tiene sentido	Qué registra
`buscar_texto`	Busca chunks por consulta.	Pregunta directa o evidencia textual.	Query, filtros, top-k, scores y chunks.
`buscar_hibrido`	Combina vector, BM25 y filtros.	Hay términos exactos y significado aproximado.	Rankings de cada señal y fusión.
`descomponer`	Divide una pregunta en subpreguntas.	La respuesta depende de varias fuentes.	Subpreguntas y razón de cada una.
`router`	Elige corpus, índice o herramienta.	Hay normativa, FAQ, SQL, tickets o grafo.	Opción elegida y alternativas descartadas.
`evaluar_evidencia`	Mide si lo recuperado basta.	Antes de redactar o cuando hay duda.	Soporte, citas candidatas y huecos.
`consultar_grafo`	Busca relaciones entre entidades.	Importan dependencias, comunidades o vínculos.	Nodos, aristas, fuente y camino usado.
`consultar_tabla`	Consulta datos estructurados.	Fechas, importes, estados o conteos exactos.	Consulta, resultado y validación.
`responder`	Redacta con citas.	Evidencia suficiente.	Claims, citas y decisión final.
`abstenerse`	No responde por falta de soporte.	Evidencia insuficiente o permisos insuficientes.	Qué faltó y qué fuente sería necesaria.

Ejemplo de fórmula. El presupuesto se puede escribir de forma simple:

C_{\text{total}} = \sum_{t=1}^{T} c(a_t)

T \le T_{\max}

Símbolo	Significado	Ejemplo
$C_{\text{total}}$	Coste total de la ejecución.	Tokens, llamadas, latencia o euros.
$c(a_t)$	Coste de la acción $a_t$ .	Una búsqueda cuesta poco; una llamada LLM cuesta más.
$T$	Número de pasos ejecutados.	3 pasos.
$T_{\max}$	Límite máximo permitido.	5 pasos por pregunta.

La frase que debería quedarse en la cabeza: Agentic RAG no es “hacer más cosas”; es decidir si hace falta hacerlas y dejar rastro de cada decisión.

Tipos de RAG avanzado y casos de uso

Antes de elegir una arquitectura, conviene ponerle nombre a cada patrón. Muchos problemas se arreglan con una pieza pequeña: reescritura, router o validación. No todos necesitan un bucle completo.

Tipo	Qué significa	Caso donde encaja	No sirve para
RAG de dos pasos	Siempre recupera primero y genera después.	FAQ, documentación técnica, normativa directa.	Preguntas que requieren decidir varias rutas.
Multi-query retrieval	Genera varias consultas para una misma pregunta y une resultados.	“doble factor”, “2FA”, “MFA” y “autenticación” pueden aparecer en documentos distintos.	Fuentes con permisos complejos si no filtras antes.
HyDE	Genera un texto hipotético que parece responder y busca documentos reales similares.	Consulta vaga sin etiquetas de relevancia ni ejemplos de entrenamiento.	Dominios donde el texto hipotético puede desviar hacia detalles falsos.
Query decomposition	Divide una pregunta compuesta en subpreguntas.	Comparar beca, matrícula y pagos pendientes.	Preguntas simples donde añade latencia sin necesidad.
Router RAG	Elige corpus, índice, herramienta o flujo.	Normativa en PDFs, estado vivo en SQL y manuales en Markdown.	Sistemas sin fuentes diferenciadas.
Hybrid RAG con validación	Recupera, evalúa evidencia, corrige o regenera si hace falta.	Dominios donde citar mal rompe confianza.	Prototipos donde aún no hay dataset de evaluación.
Corrective RAG	Evalúa la calidad de los documentos recuperados y activa otra búsqueda si no basta.	Corpus incompleto, preguntas ambiguas o retrieval frágil.	Sistemas sin fuente alternativa ni umbral definido.
Self-RAG	Decide cuándo recuperar y critica pasajes/respuestas mediante señales internas o entrenadas.	Respuestas largas donde no siempre hace falta recuperar.	Integraciones donde necesitas flujo totalmente determinista.
RAPTOR	Construye árboles de resúmenes para recuperar a varios niveles de abstracción.	Manuales largos, informes extensos, libros internos.	Corpus pequeño con respuestas puntuales.
GraphRAG local	Usa grafo para preguntas sobre entidades y relaciones concretas.	“¿Qué políticas dependen de este requisito?”	Preguntas puramente textuales sin relaciones útiles.
GraphRAG global	Usa resúmenes de comunidades para preguntas sobre el corpus completo.	“¿Qué patrones aparecen en todas las incidencias?”	Preguntas que solo piden una fecha exacta.
RAG con herramientas	El modelo consulta búsqueda, SQL, APIs o grafo según necesidad.	“Busca la política y comprueba si mi expediente cumple.”	Saltarse permisos o validar por intuición.

La clave práctica: cada fila añade una nueva promesa y una nueva deuda. Multi-query promete más cobertura y paga más búsquedas. Router promete elegir mejor la fuente y paga clasificación. GraphRAG promete visión relacional y paga extracción, grafo, resúmenes y evaluación nueva.

Arquitecturas, una por una

El diagrama enseña la escalera de complejidad. Si una pregunta se resuelve con un RAG de dos pasos, no necesitas un bucle. Si falla por vocabulario, quizá basta multi-query. Si falla por elegir mal la fuente, quizá basta router. Si falla porque el corpus completo tiene patrones, GraphRAG puede tener sentido.

GraphRAG: qué cambia cuando aparece un grafo

Un grafo representa entidades y relaciones. En vez de tratar el corpus solo como chunks sueltos, intentamos extraer una estructura:

G = (V,\; E)

Símbolo	Significado	Ejemplo
$G$	Grafo de conocimiento extraído o curado.	Grafo de normativa, trámites y requisitos.
$V$	Conjunto de nodos o entidades.	“Ampliación de matrícula”, “pagos pendientes”, “beca general”.
$E$	Conjunto de aristas o relaciones.	“requiere”, “contradice”, “se aplica a”, “depende de”.

Ejemplo de fórmula. Cada arista debería guardar procedencia:

e = (v_i,\; r,\; v_j,\; fuente,\; confianza)

Símbolo	Significado	Ejemplo
$v_i$	Entidad origen.	“Ampliación de matrícula”.
$r$	Relación.	“requiere”.
$v_j$	Entidad destino.	“no tener pagos pendientes vencidos”.
`fuente`	Documento o chunk que sostiene la relación.	`norm-2026#art-14`.
`confianza`	Señal de extracción o validación.	0,82.

La diferencia con RAG básico es que GraphRAG puede contestar usando caminos, vecindarios o comunidades:

Modo	Qué busca	Pregunta típica
Local search	Entidades y relaciones cercanas a una entidad.	“¿Qué requisitos dependen de pagos pendientes?”
Global search	Resúmenes de comunidades del grafo.	“¿Qué patrones aparecen en las incidencias del curso?”
DRIFT search	Combina señal comunitaria con seguimiento local más amplio.	“Explora este tema y saca líneas de investigación.”
Question generation	Propone preguntas siguientes para investigar el corpus.	“¿Qué debería revisar ahora?”

La documentación de Microsoft GraphRAG lo expresa así: local search combina datos del grafo con chunks originales; global search busca sobre community reports en estilo map-reduce; DRIFT usa información de comunidades para ampliar el punto de partida local.⁹

GraphRAG encaja cuando la pregunta no vive en un solo fragmento:

Caso cercano	Por qué GraphRAG ayuda
Analizar miles de tickets de soporte.	Las relaciones entre producto, síntoma, versión y solución revelan comunidades.
Revisar normativa dispersa.	Las dependencias entre requisitos importan tanto como cada párrafo.
Explorar literatura académica.	Autores, métodos, datasets y resultados forman un grafo natural.
Mapear incidencias de producto.	Puede mostrar temas recurrentes y relaciones entre módulos.
Entender una organización documental.	Las entidades conectan documentos que no comparten las mismas palabras.

Pero también tiene costes:

Coste	Qué implica
Extracción	El modelo debe detectar entidades y relaciones con calidad suficiente.
Normalización	“doble factor”, “2FA” y “MFA” quizá son la misma entidad.
Actualización	Si cambian documentos, hay que actualizar grafo, resúmenes e índices.
Evaluación	Ya no basta medir top-k; hay que medir caminos, relaciones y resúmenes.
Explicabilidad	Una respuesta global debe enseñar qué comunidades o fuentes la sostienen.

Cómo elegir sin montar una catedral

La pregunta de arquitectura se puede formular como diagnóstico:

Síntoma	Primera mejora razonable	Si no basta
No aparece el documento correcto por vocabulario.	Multi-query o HyDE.	Entrenar o cambiar embeddings; añadir BM25/fusión.
La pregunta mezcla varias cosas.	Query decomposition.	Agentic RAG con subpreguntas y validación.
Hay varias fuentes con reglas distintas.	Router.	Herramientas especializadas por fuente.
El sistema trae contexto flojo.	Retrieval validation y reranker.	Corrective RAG o búsqueda alternativa.
El corpus es largo y jerárquico.	Resúmenes por sección.	RAPTOR o índice jerárquico.
La respuesta depende de relaciones.	Grafo de entidades.	GraphRAG local.
La pregunta pide patrones del corpus entero.	Resúmenes agregados.	GraphRAG global.
Hace falta estado exacto.	Tool o SQL.	Capítulo 12: Text-to-SQL y herramientas de datos.

Regla práctica: añade una sola pieza por experimento. Si incorporas router, multi-query, GraphRAG y validación a la vez, cuando mejore o empeore no sabrás por qué.

Evaluar RAG avanzado

Todo lo que complicas debe medirse. Un Agentic RAG no se evalúa solo por respuesta final: se evalúa por ruta.

Capa	Métrica o revisión	Pregunta
Router	Accuracy de ruta o matriz de confusión.	¿Eligió la fuente correcta?
Multi-query	Recall@k por consulta y unión final.	¿Las variantes trajeron evidencia nueva o solo ruido?
Decomposition	Subpreguntas necesarias y suficientes.	¿Dividió bien el problema?
Corrective RAG	Tasa de corrección útil.	¿Volvió a buscar cuando debía?
Agentic loop	Pasos, coste, latencia y salida.	¿Gastó pasos con sentido?
Graph local	Nodos/aristas correctos y fuentes.	¿El camino usado está sostenido?
Graph global	Cobertura, diversidad y trazabilidad.	¿El resumen global representa el corpus?
Respuesta	Groundedness, citas y abstención.	¿Lo dicho está sostenido?

Ejemplo de fórmula. Un gate mínimo:

G \ge \tau_g

C \le C_{\max}

T \le T_{\max}

Símbolo	Significado	Ejemplo
$G$	Groundedness o soporte mínimo.	0,92.
$\tau_g$	Umbral de soporte.	0,90.
$C$	Coste total de la ejecución.	0,012 euros o 8.000 tokens.
$C_{\max}$	Coste máximo aceptable.	0,02 euros.
$T$	Pasos realizados.	4.
$T_{\max}$	Máximo de pasos.	5.

Para GraphRAG hay una evaluación adicional: no basta con que la respuesta suene bien. Hay que revisar si las entidades, relaciones y comunidades usadas son correctas. Un resumen global puede ser fluido y aun así esconder que una comunidad importante no entró en el mapa.

Casos cercanos

Secretaría académica. Preguntan: “¿Puedo ampliar matrícula si tengo una beca pendiente y pagos vencidos?”. Un RAG básico quizá encuentra solo la normativa de ampliación. Query decomposition separa “ampliación”, “beca pendiente” y “pagos vencidos”. El router decide si mirar normativa, becas y calendario. La respuesta final debe citar cada pieza.

Equipo de soporte técnico. Preguntan: “¿Qué problemas se repiten desde la última versión?”. No quieres una respuesta sobre un ticket concreto. Quieres agrupar incidencias por producto, síntoma, versión y solución. Aquí GraphRAG global o resúmenes jerárquicos pueden mostrar patrones que un top-k no ve.

Documentación de ingeniería. Preguntan: “¿Cómo configuro el conector si uso PostgreSQL y despliegue local?”. El sistema puede necesitar buscar en documentación, consultar ejemplos de configuración y revisar límites de versión. Agentic RAG con herramientas de búsqueda acotadas puede ser útil, siempre que cite y limite dominios.

Compliance documental. Preguntan: “¿Qué políticas dependen de este requisito?”. GraphRAG local encaja porque lo importante es el vecindario de una entidad: requisito, políticas, controles, evidencias y documentos fuente.

Producto con datos vivos. Preguntan: “¿Qué clientes están afectados y qué documento explica la política?”. Aquí no basta RAG. Necesitas tool o SQL para estado vivo y RAG para explicar la política. Este puente prepara el capítulo 12.

Para entenderlo sin perderse

Una forma sencilla de explicarlo: un RAG básico se parece a preguntar a alguien que tiene una estantería y te trae tres páginas parecidas a tu pregunta. Si esas páginas contienen la respuesta, perfecto. Si la pregunta exige comparar, comprobar vigencia, mirar otra fuente o seguir una relación entre documentos, la persona necesita una libreta de trabajo: primero mira dónde buscar, luego consulta, después comprueba si lo encontrado basta y solo entonces responde.

En esa metáfora:

Pieza	Traducción mental	Qué debería quedar claro
RAG básico	Traer páginas parecidas.	Sirve si la pregunta vive en uno o varios fragmentos cercanos.
Router	Decidir en qué estantería mirar.	No es una caja negra: clasifica la pregunta y elige fuente.
Multi-query	Preguntar lo mismo con varias palabras.	Mejora cobertura cuando el vocabulario cambia.
Descomposición	Separar una pregunta grande en preguntas pequeñas.	Ayuda si hay que comparar o juntar varias condiciones.
Validador	Comprobar si las páginas sostienen la respuesta.	Reduce respuestas bonitas pero poco justificadas.
Traza	Libreta de lo que hizo el sistema.	Permite depurar, auditar y evaluar.
Grafo	Mapa de cosas conectadas.	Ayuda cuando la relación importa tanto como el texto.
Comunidad	Barrio dentro del grafo.	Grupo de entidades que aparecen conectadas muchas veces.

El error habitual es imaginar que Agentic RAG “razona más”. En producción me interesa una definición menos romántica: Agentic RAG toma decisiones explícitas entre pasos permitidos y deja evidencia de esas decisiones. Si no hay pasos permitidos, presupuesto y traza, no tienes una arquitectura: tienes una conversación difícil de depurar.

Cómo lo montaría en un sistema real

Si tuviera que construir esto en una empresa, no empezaría por GraphRAG ni por un agente completo. Empezaría por una pregunta incómoda: “¿qué fallo real quiero corregir?”. Si el fallo es vocabulario, multi-query. Si el fallo es escoger mal la fuente, router. Si el fallo es no saber si la evidencia basta, validador. Si el fallo es entender relaciones entre documentos, grafo.

La arquitectura mínima seria tendría estas capas:

Cada caja de la figura debería poder probarse por separado. Un ingeniero no debería preguntar “¿funciona el agente?”, sino cosas más concretas:

¿El router elige bien entre normativa, FAQ, SQL, tickets y grafo?
¿El retriever trae evidencia suficiente con filtros de permisos?
¿La fusión elimina duplicados y mantiene fuentes distintas?
¿El validador detecta falta de soporte, citas flojas o documentos caducados?
¿El generador respeta el formato de salida y no inventa campos?
¿La traza permite reproducir la respuesta cinco días después?

Contratos de herramientas

Una herramienta en un sistema agentic no debería ser “una función que el modelo puede llamar”. Debe ser un contrato. El contrato dice qué recibe, qué devuelve, qué permisos exige, cuánto tarda, cómo falla y cómo se audita.

Ejemplo de contrato de una herramienta de búsqueda documental:

{
  "name": "buscar_normativa",
  "input": {
    "query": "string",
    "filters": {
      "curso": "2026",
      "estado": "vigente"
    },
    "top_k": 8
  },
  "output": {
    "results": [
      {
        "chunk_id": "norm-2026#art-14",
        "score": 0.84,
        "source": "Normativa 2026",
        "valid_from": "2026-01-01",
        "text": "fragmento recuperado"
      }
    ]
  },
  "errors": [
    "permission_denied",
    "source_unavailable",
    "low_recall"
  ],
  "timeout_ms": 1200,
  "audit": true
}

Lo importante no es el JSON, sino la disciplina:

Campo	Qué aporta	Qué se rompe si falta
`name`	Identidad estable de la herramienta.	No puedes comparar ejecuciones ni versionar cambios.
`input`	Qué puede pedir el sistema.	El modelo puede mandar consultas vagas o imposibles.
`filters`	Permisos, vigencia, idioma, cliente o corpus.	Puedes mezclar documentos que no deberían mezclarse.
`top_k`	Límite de resultados.	Coste y contexto crecen sin control.
`score`	Señal de recuperación.	No sabes por qué entró un fragmento.
`source`	Procedencia legible.	No puedes citar ni revisar.
`valid_from`	Vigencia temporal.	Respuestas correctas pueden quedar obsoletas.
`errors`	Fallos esperados.	El sistema trata un fallo como si fuera ausencia de información.
`timeout_ms`	Límite de latencia.	Una herramienta lenta secuestra toda la respuesta.
`audit`	Obligación de guardar traza.	No puedes reproducir ni explicar decisiones.

Un contrato de herramienta también debe declarar qué hacer cuando no basta:

Resultado	Decisión correcta
`permission_denied`	No buscar atajos; responder que no hay permiso suficiente.
`source_unavailable`	Degradar con aviso o pedir reintento, según criticidad.
`low_recall`	Reescribir consulta, usar búsqueda híbrida o abstenerse.
`empty_result`	Distinguir “no existe” de “no he podido encontrarlo”.
`conflicting_sources`	Priorizar vigencia, autoridad y citar el conflicto.

GraphRAG por dentro

GraphRAG no empieza en la query; empieza en la ingesta. Antes de responder hay que convertir documentos en entidades, relaciones, comunidades y resúmenes. Ese proceso tiene mucha ingeniería escondida.

Una tubería razonable:

Paso	Qué hace	Riesgo principal	Control
Ingesta	Lee PDFs, HTML, Markdown, tickets, tablas o transcripciones.	Perder estructura del documento.	Guardar fuente, página, sección y fecha.
Chunking	Parte documentos en unidades recuperables.	Cortar relaciones importantes.	Chunks con solape y metadatos ricos.
Extracción	Detecta entidades y relaciones.	Extraer nombres distintos para lo mismo.	Diccionario, revisión y normalización.
Canonicalización	Une variantes de una entidad.	Mezclar entidades parecidas pero distintas.	Alias, reglas y confianza.
Aristas	Crea relaciones con fuente.	Relación sin prueba documental.	Toda arista guarda chunk, frase y score.
Comunidades	Agrupa zonas densas del grafo.	Comunidades demasiado grandes o pequeñas.	Medir modularidad y revisar muestras.
Resúmenes	Resume comunidades.	Perder excepciones importantes.	Citar nodos y documentos representativos.
Índices	Indexa texto, nodos, aristas y resúmenes.	Recuperar solo una vista parcial.	Búsqueda híbrida y evaluación por tipo.
Actualización	Reprocesa cambios del corpus.	Grafo viejo con documentos nuevos.	Versionado, diffs y caducidad.

Se puede escribir de forma compacta:

V = \operatorname{canon}(\operatorname{entidades}(D))

E = \{(v_i,\; r,\; v_j,\; fuente,\; confianza)\}

R_c = \operatorname{resumen}(C_c,\; fuentes_c)

Símbolo	Significado	Ejemplo
$D$	Documentos de entrada.	Normativa, FAQ, tickets y manuales.
$V$	Entidades normalizadas.	“2FA” y “doble factor” como la misma entidad.
$E$	Relaciones con fuente.	“ampliación requiere no tener pagos vencidos”.
$C_c$	Comunidad del grafo.	Trámites de matrícula y pagos.
$R_c$	Resumen de comunidad.	“Los bloqueos se concentran en pagos y plazos”.

La parte difícil no es dibujar nodos. La parte difícil es saber si el nodo es correcto, si dos nodos son la misma cosa, si la relación tiene fuente, si el resumen no borra excepciones y si el grafo se actualiza cuando cambia el corpus.

Coste, latencia y presupuesto

Un RAG avanzado puede mejorar respuestas y empeorar producto si duplica latencia sin medirlo. Por eso hay que convertir la arquitectura en números.

Si generas $q$ consultas, traes $k$ fragmentos por consulta y cada fragmento tiene $L$ tokens de media:

N_{\text{ctx}} \approx q \cdot k \cdot L

Si además usas reranker y un generador:

T_{\text{total}} = T_{\text{router}} + \max_i(T_{\text{retrieval},i}) + T_{\text{rerank}} + T_{\text{validación}} + T_{\text{generación}}

Y el coste de una respuesta puede aproximarse así:

C_{\text{respuesta}} = C_{\text{emb}} + C_{\text{retrieval}} + C_{\text{rerank}} + C_{\text{LLM}}

Número	Qué significa	Qué mirar en producción
$q$	Número de consultas generadas.	Si sube, suben recall, coste y ruido.
$k$	Fragmentos recuperados por consulta.	Un top-k alto puede tapar la evidencia buena.
$L$	Tokens por fragmento.	Chunks largos llenan contexto rápido.
$T_{\text{total}}$	Latencia total.	Medir P50, P95 y timeouts, no solo media.
$C_{\text{respuesta}}$	Coste por respuesta.	Dividir por respuesta útil, no por llamada.
$C_{\text{index}}$	Coste de indexar.	En GraphRAG puede ser alto antes de la primera query.

Para GraphRAG hay otro coste:

C_{\text{graph-index}} = C_{\text{extracción}} + C_{\text{normalización}} + C_{\text{comunidades}} + C_{\text{resúmenes}}

Este coste se paga al construir o actualizar el índice, no solo al responder. Por eso GraphRAG puede ser brillante en colecciones estables y caro en corpus que cambian cada hora.

Evaluación para ingeniería

La evaluación de RAG avanzado tiene que separar piezas. Si solo miras la respuesta final, no sabes si mejoró el retriever, el router, el grafo o simplemente hubo suerte en una muestra.

Un plan de evaluación serio:

Prueba	Qué compara	Pregunta que responde
Baseline	RAG básico contra sistema nuevo.	¿Complicar mejora algo medible?
Ablation	Quitar una pieza cada vez.	¿Qué aporta router, multi-query, grafo o validador?
Router accuracy	Ruta esperada contra ruta elegida.	¿Va a la fuente correcta?
Recall@k	Evidencia esperada dentro del top-k.	¿Recupera lo necesario?
MRR / nDCG	Orden de documentos relevantes.	¿Lo bueno aparece arriba?
Node precision	Nodos correctos del grafo.	¿Las entidades recuperadas son válidas?
Edge precision	Relaciones correctas del grafo.	¿Las aristas están sostenidas por fuentes?
Citation support	Claims con cita suficiente.	¿Cada afirmación importante está soportada?
Abstention rate	Casos donde no responde.	¿Se abstiene cuando falta evidencia?
Latencia P95	Tiempo para el 95% de consultas.	¿El producto aguanta en uso real?
Coste por respuesta útil	Coste dividido por respuestas aceptables.	¿La mejora compensa?

El ablation test es especialmente sano:

Variante	Qué activa	Qué esperas aprender
A	RAG básico.	Línea base.
B	A + búsqueda híbrida.	Si el problema era vocabulario exacto.
C	B + multi-query.	Si faltaba cobertura semántica.
D	C + router.	Si elegir fuente aporta mejora.
E	D + validador.	Si reduce respuestas sin soporte.
F	E + GraphRAG.	Si las relaciones añaden valor real.

Si F gana solo un 1% pero dobla latencia y coste, quizá no merece producción. Si F gana mucho en preguntas relacionales y pierde en preguntas simples, el router debe activar GraphRAG solo cuando toque.

Caso completo de diseño

Supongamos un sistema con 50.000 documentos internos: normativa, manuales, tickets, FAQs, actas y algunas tablas con estado vivo. El objetivo es responder a equipos internos con citas, permisos y trazas.

Yo lo diseñaría por fases:

Fase	Qué haría	Criterio para avanzar
1. Corpus	Inventario de fuentes, permisos, vigencia y formatos.	Saber qué puede ver cada usuario y qué fuente manda.
2. Baseline	RAG básico con chunking, embeddings y búsqueda híbrida.	Dataset de 100-300 preguntas reales con respuestas esperadas.
3. Evaluación	Medir recall@k, soporte de citas, abstención y latencia.	Detectar el fallo dominante.
4. Router	Separar normativa, FAQ, tickets, manuales, SQL y grafo.	Accuracy de ruta suficiente y trazas legibles.
5. Validación	Añadir groundedness, vigencia y conflicto entre fuentes.	Menos respuestas sin soporte.
6. Grafo local	Entidades y relaciones para normativa y dependencias.	Mejora clara en preguntas relacionales.
7. GraphRAG global	Comunidades para tickets, actas e incidencias.	Mejora clara en preguntas de patrones.
8. Producción	Observabilidad, costes, permisos, caché y regresiones.	Alertas y evaluación continua antes de ampliar uso.

La decisión final no sería “usar GraphRAG sí o no”. Sería una política:

Tipo de pregunta	Flujo recomendado
“¿Dónde dice X?”	RAG básico con búsqueda híbrida y citas.
“¿Cuál es el estado actual de X?”	Tool o SQL, después explicación con RAG.
“Compara X e Y”	Descomposición, router y validación.
“¿Qué depende de este requisito?”	GraphRAG local.
“¿Qué patrones aparecen en todo el corpus?”	GraphRAG global.
“No hay evidencia suficiente”	Abstención con fuente necesaria.

Este diseño también ayuda a una persona curiosa: no hay una herramienta universal. Hay una escalera. Cada peldaño se sube cuando el anterior falla de una forma concreta.

Manos a la obra

Vamos a simular un mini Agentic RAG sin APIs. El objetivo no es crear un agente real, sino entender la traza: router, búsqueda textual, consulta de grafo, evaluación de evidencia y decisión final.

from collections import Counter


CHUNKS = {
    "norm-2026#ampliacion": {
        "titulo": "Normativa 2026: ampliación",
        "texto": (
            "La ampliación de matrícula se solicita en septiembre. "
            "No se admite si existen pagos pendientes vencidos."
        ),
        "tipo": "normativa",
    },
    "becas-2026#calendario": {
        "titulo": "Becas 2026: calendario",
        "texto": (
            "La beca pendiente no bloquea por sí sola la ampliación. "
            "El pago vencido sí requiere revisión previa."
        ),
        "tipo": "becas",
    },
    "faq#doble-factor": {
        "titulo": "FAQ: doble factor",
        "texto": (
            "Si no puedes entrar al campus virtual, revisa el doble "
            "factor y restablece la contraseña."
        ),
        "tipo": "faq",
    },
    "incidencias#version": {
        "titulo": "Incidencias versión 4.2",
        "texto": (
            "Desde la versión 4.2 se repiten incidencias "
            "de doble factor, sesiones caducadas y "
            "permisos de matrícula."
        ),
        "tipo": "ticket",
    },
}

GRAPH = [
    (
        "ampliación de matrícula",
        "requiere",
        "no tener pagos pendientes vencidos",
        "norm-2026#ampliacion",
    ),
    (
        "beca pendiente",
        "no bloquea",
        "ampliación de matrícula",
        "becas-2026#calendario",
    ),
    (
        "versión 4.2",
        "se relaciona con",
        "doble factor",
        "incidencias#version",
    ),
    (
        "versión 4.2",
        "se relaciona con",
        "permisos de matrícula",
        "incidencias#version",
    ),
]

STOPWORDS = {
    "a", "al", "con", "de", "del", "el", "en", "es", "la",
    "las", "lo", "los", "me", "mi", "no", "por", "que",
    "se", "si", "un", "una", "y",
}


def tokens(texto):
    limpio = "".join(c.lower() if c.isalnum() else " " for c in texto)
    return [
        t for t in limpio.split()
        if t not in STOPWORDS and len(t) > 2
    ]


def buscar_texto(query, tipo=None, k=2):
    q = set(tokens(query))
    resultados = []
    for chunk_id, chunk in CHUNKS.items():
        if tipo and chunk["tipo"] != tipo:
            continue
        texto = chunk["texto"] + " " + chunk["titulo"]
        score = len(q & set(tokens(texto)))
        if score:
            resultados.append((score, chunk_id))
    ranking = sorted(resultados, reverse=True)[:k]
    return [chunk_id for score, chunk_id in ranking]


def buscar_grafo(query):
    q = set(tokens(query))
    hallazgos = []
    modo_global = bool({"patrones", "repiten", "temas"} & q)
    minimo = 1 if modo_global else 2
    for origen, relacion, destino, fuente in GRAPH:
        texto = f"{origen} {relacion} {destino}"
        score = len(q & set(tokens(texto)))
        if score >= minimo:
            hallazgos.append((score, origen, relacion, destino, fuente))
    return sorted(hallazgos, reverse=True)


def evaluar_evidencia(ids):
    texto = " ".join(CHUNKS[i]["texto"] for i in ids)
    cobertura = len(set(tokens(texto)))
    return min(cobertura / 18, 1.0)


def elegir_plan(pregunta):
    t = set(tokens(pregunta))
    if {"patrones", "repiten", "temas"} & t:
        return ["buscar_grafo", "buscar_texto", "responder"]
    if {"compara", "beca", "pagos"} & t:
        return [
            "descomponer",
            "buscar_texto",
            "buscar_grafo",
            "evaluar",
            "responder",
        ]
    if {"estado", "clientes", "afectados"} & t:
        return ["consultar_tabla", "buscar_texto", "responder"]
    return ["buscar_texto", "evaluar", "responder"]


def responder(pregunta):
    plan = elegir_plan(pregunta)
    traza = []
    evidencia = []
    relaciones = []

    for paso in plan:
        if paso == "descomponer":
            subpreguntas = [
                "ampliación de matrícula pagos pendientes",
                "beca pendiente ampliación matrícula",
            ]
            traza.append(("descomponer", subpreguntas))
        elif paso == "buscar_texto":
            consultas = [pregunta]
            if "descomponer" in [p for p, _ in traza]:
                consultas = traza[-1][1]
            for consulta in consultas:
                palabras = set(tokens(consulta))
                tipo = None
                if "beca" in palabras:
                    tipo = "becas"
                elif {"normativa", "pagos", "vencidos"} & palabras:
                    tipo = "normativa"
                nuevos = buscar_texto(consulta, tipo=tipo)
                if not nuevos:
                    nuevos = buscar_texto(consulta)
                for chunk_id in nuevos:
                    if chunk_id not in evidencia:
                        evidencia.append(chunk_id)
            traza.append(("buscar_texto", list(evidencia)))
        elif paso == "buscar_grafo":
            relaciones = buscar_grafo(pregunta)
            fuentes = [r[-1] for r in relaciones]
            evidencia.extend(i for i in fuentes if i not in evidencia)
            traza.append(("buscar_grafo", relaciones[:3]))
        elif paso == "consultar_tabla":
            traza.append((
                "consultar_tabla",
                "en este ejemplo no hay tabla viva",
            ))
        elif paso == "evaluar":
            soporte = evaluar_evidencia(evidencia)
            traza.append(("evaluar", round(soporte, 2)))
            if soporte < 0.55:
                extra = buscar_texto(
                    "normativa matrícula beca pagos vencidos",
                    k=3,
                )
                evidencia.extend(i for i in extra if i not in evidencia)
                traza.append(("corregir_busqueda", extra))
        elif paso == "responder":
            citas = sorted(set(evidencia))
            conteo = Counter(CHUNKS[i]["tipo"] for i in citas)
            traza.append((
                "responder",
                {"citas": citas, "tipos": dict(conteo)},
            ))

    return traza


preguntas = [
    "Compara beca pendiente y pagos vencidos para ampliar matrícula",
    "Qué problemas se repiten desde la versión 4.2",
    "Cómo recupero el acceso con doble factor",
]

for pregunta in preguntas:
    print("\\nPREGUNTA:", pregunta)
    for paso, detalle in responder(pregunta):
        print("-", paso, "=>", detalle)

Salida esperada aproximada:

PREGUNTA: Compara beca pendiente y pagos vencidos
- descomponer => 2 subpreguntas
- buscar_texto => norm-2026#ampliacion, becas-2026#calendario
- buscar_grafo => [...]
- evaluar => 1.0
- responder => citas y tipos de fuente

PREGUNTA: Qué problemas se repiten desde la versión 4.2
- buscar_grafo => [...]
- buscar_texto => incidencias#version
- responder => citas y tipos de fuente

PREGUNTA: Cómo recupero el acceso con doble factor
- buscar_texto => faq#doble-factor, incidencias#version
- evaluar => 1.0
- responder => citas y tipos de fuente

Prueba tres cambios:

Baja el umbral de evaluar_evidencia y observa cuándo se corrige menos.
Añade un chunk contradictorio y mira si tu plan debería incluir validación de vigencia.
Añade una fuente sql simulada y prepara el puente hacia el capítulo 12.

Cómo encaja todo

graph TD
    subgraph "Capítulo 11: RAG avanzado"
        BASIC["RAG de dos pasos"]
        MQ["Multi-query / HyDE"]
        DECOMP["Descomposición"]
        ROUTER["Router"]
        VALIDAR["Validar evidencia"]
        LOOP["Bucle agentic"]
        GRAPH["GraphRAG"]
        GLOCAL["Local search"]
        GGLOBAL["Global search"]
        TRACE["Trazas y presupuesto"]
        GATE["Gate de publicación"]
    end
    subgraph "Viene de antes"
        EMB["Embeddings (F4C7)"]
        VECTOR["Bases vectoriales (F4C8)"]
        RAGB["RAG básico (F4C9)"]
        EVAL["Evaluar RAG (F4C10)"]
        CLASICA["Búsqueda y grafos (F2)"]
    end
    subgraph "Sigue después"
        SQL["Text-to-SQL (F4C12)"]
        LAB["Laboratorio mínimo (F4C13)"]
        AGENTES["Agentes (F5)"]
        OPS["Operación (F6)"]
        EVALS["Evaluación avanzada (F7)"]
    end

    EMB -->|"hace posible"| BASIC
    VECTOR -->|"sirve a"| BASIC
    RAGB -->|"se amplía con"| MQ
    RAGB -->|"se amplía con"| DECOMP
    RAGB -->|"se amplía con"| ROUTER
    MQ -->|"aumenta recall"| VALIDAR
    DECOMP -->|"genera subpreguntas"| VALIDAR
    ROUTER -->|"elige fuente"| LOOP
    VALIDAR -->|"decide si repetir"| LOOP
    CLASICA -->|"prepara intuición de grafos"| GRAPH
    GRAPH -->|"usa"| GLOCAL
    GRAPH -->|"usa"| GGLOBAL
    LOOP -->|"debe registrar"| TRACE
    GRAPH -->|"debe registrar"| TRACE
    EVAL -->|"define métricas para"| GATE
    TRACE -->|"alimenta"| GATE
    LOOP -->|"prepara"| AGENTES
    ROUTER -->|"prepara"| SQL
    GATE -->|"se practica en"| LAB
    TRACE -->|"pasa a"| OPS
    GATE -->|"pasa a"| EVALS

    style BASIC fill:#F5F5F5,stroke:#000000,stroke-width:2
    style MQ fill:#F5F5F5,stroke:#000000,stroke-width:2
    style DECOMP fill:#F5F5F5,stroke:#000000,stroke-width:2
    style ROUTER fill:#F5F5F5,stroke:#000000,stroke-width:2
    style VALIDAR fill:#F5F5F5,stroke:#000000,stroke-width:2
    style LOOP fill:#F5F5F5,stroke:#000000,stroke-width:2
    style GRAPH fill:#F5F5F5,stroke:#000000,stroke-width:2
    style GLOCAL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style GGLOBAL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TRACE fill:#F5F5F5,stroke:#000000,stroke-width:2
    style GATE fill:#111111,stroke:#000000,stroke-width:2,color:#FFFFFF
    style EMB stroke-dasharray: 5 5
    style VECTOR stroke-dasharray: 5 5
    style RAGB stroke-dasharray: 5 5
    style EVAL stroke-dasharray: 5 5
    style CLASICA stroke-dasharray: 5 5
    style SQL stroke-dasharray: 5 5
    style LAB stroke-dasharray: 5 5
    style AGENTES stroke-dasharray: 5 5
    style OPS stroke-dasharray: 5 5
    style EVALS stroke-dasharray: 5 5

Vocabulario aprendido

Término	Definición
Agentic RAG	RAG donde un modelo o router decide pasos de búsqueda, herramientas y validación antes de responder.
RAG de dos pasos	Flujo fijo: recuperar contexto y generar respuesta.
Multi-query retrieval	Varias consultas para cubrir vocabularios distintos de una misma necesidad.
HyDE	Generar un documento hipotético para buscar documentos reales parecidos.
Query decomposition	Dividir una pregunta grande en subpreguntas recuperables.
Router	Pieza que decide qué corpus, índice, herramienta o flujo usar.
Corrective RAG	RAG que evalúa si lo recuperado basta y corrige si no basta.
Self-RAG	Enfoque donde la recuperación y la crítica forman parte del comportamiento del modelo.
RAPTOR	Recuperación con árbol de resúmenes a distintos niveles de abstracción.
GraphRAG	RAG basado en grafo de entidades, relaciones y resúmenes.
Local search	Búsqueda centrada en entidades o relaciones concretas del grafo.
Global search	Búsqueda sobre resúmenes de comunidades para preguntas del corpus completo.
Community summary	Resumen de un grupo de nodos relacionados dentro del grafo.
Presupuesto de pasos	Límite de acciones, llamadas, coste o latencia permitido.
Contrato de herramienta	Especificación de entradas, salidas, errores, permisos, timeout y auditoría de una herramienta.
Traza	Registro reproducible de ruta, consultas, resultados, decisiones, costes y citas usadas.
Canonicalización	Unión controlada de variantes que representan la misma entidad.
Ablation test	Prueba donde se quita una pieza del sistema para medir qué aporta realmente.
Latencia P95	Tiempo por debajo del cual responde el 95% de las consultas.
Edge precision	Proporción de relaciones del grafo que son correctas y están sostenidas por fuentes.

Dónde solía tropezar yo

Error	Por qué es un error	Antídoto
Llamar agente a cualquier if	Un router determinista puede ser suficiente; no todo flujo condicional es un agente.	Nombrar la pieza exacta: router, validador, descomposición o bucle.
Añadir bucles sin presupuesto	La latencia y el coste se vuelven impredecibles.	Definir $T_{\max}$ , coste máximo y condición de parada.
Usar GraphRAG sin relaciones útiles	Si no hay entidades ni vínculos relevantes, el grafo añade mantenimiento sin mejorar respuestas.	Probar primero si las preguntas fallan por relaciones, no por retrieval básico.
No guardar la ruta de decisión	Si falla, no sabes qué fuente eligió ni por qué.	Guardar traza: ruta, consultas, resultados, scores, citas y validaciones.
Medir solo groundedness final	Puede responder bien por casualidad aunque haya elegido mal el camino.	Evaluar router, subpreguntas, nodos, aristas, pasos y respuesta.
Mezclar todas las mejoras a la vez	No puedes atribuir la mejora ni depurar el fallo.	Añadir una pieza por experimento y comparar contra baseline.
No definir contratos de herramientas	Cada integración acaba devolviendo lo que quiere y fallando de forma distinta.	Declarar input, output, errores, timeout, permisos y trazas.
Ignorar el coste de indexar GraphRAG	El grafo también cuesta antes de contestar la primera pregunta.	Separar coste de indexación y coste por query.
Mirar solo la media de latencia	La media puede ocultar consultas lentas que rompen la experiencia.	Medir P50, P95, timeouts y coste por respuesta útil.

Antes de pasar página

En resumen

Idea fuerza	Detalle
No empieces por Agentic RAG.	Empieza por RAG básico evaluado; complica solo cuando sabes qué falla.
Agentic RAG decide pasos.	Puede reescribir, dividir, enrutar, consultar herramientas, validar y volver a buscar.
GraphRAG usa relaciones.	Sirve cuando importan entidades, dependencias, comunidades o preguntas globales del corpus.
Producción exige contratos.	Cada herramienta necesita entradas, salidas, errores, permisos, timeout y trazas.
GraphRAG cuesta antes de responder.	Extraer entidades, normalizar, crear comunidades y resumir también forman parte del presupuesto.
Cada pieza nueva exige evaluación propia.	Router, descomposición, grafo, bucle y respuesta final se miden por separado.
El ablation test evita autoengaños.	Compara RAG básico contra mejoras incrementales para saber qué aporta cada pieza.
El coste no es solo dinero.	También pagas latencia, trazabilidad, mantenimiento, permisos y complejidad de depuración.

Para saber más

Asai, A., Wu, Z., Wang, Y., Sil, A. y Hajishirzi, H. (2023). Self-RAG: Learning to Retrieve, Generate, and Critique through Self-Reflection. arXiv

Cormack, G. V., Clarke, C. L. A. y Buettcher, S. (2009). Reciprocal Rank Fusion Outperforms Condorcet and Individual Rank Learning Methods. Proceedings of SIGIR, 758-759. DOI

Edge, D. et al. (2024). From Local to Global: A Graph RAG Approach to Query-Focused Summarization. arXiv

Gao, L., Ma, X., Lin, J. y Callan, J. (2022). Precise Zero-Shot Dense Retrieval without Relevance Labels. arXiv

LangChain. (2026). Retrieval. Documentación oficial

Lewis, P. et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. Advances in Neural Information Processing Systems 33, 9459-9474. NeurIPS

LlamaIndex. (2026). Agentic strategies. Documentación oficial

Microsoft. (2026). GraphRAG Query Engine overview. Documentación oficial

OpenAI. (2026). Graders. Documentación oficial

Sarthi, P. et al. (2024). RAPTOR: Recursive Abstractive Processing for Tree-Organized Retrieval. arXiv

Schick, T. et al. (2023). Toolformer: Language Models Can Teach Themselves to Use Tools. DOI

Yan, S.-Q., Gu, J.-C., Zhu, Y. y Ling, Z.-H. (2024). Corrective Retrieval Augmented Generation. arXiv

Yao, S. et al. (2023). ReAct: Synergizing Reasoning and Acting in Language Models. International Conference on Learning Representations. arXiv

Notas

Lewis, P. et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. Advances in Neural Information Processing Systems 33, 9459-9474. NeurIPS. ↩
LangChain. (2026). Retrieval. Documentación oficial. Consultado el 26 de mayo de 2026. La página compara 2-step RAG, Agentic RAG e Hybrid RAG, y explica que un agente puede decidir cuándo y cómo recuperar mediante herramientas. ↩
LlamaIndex. (2026). Agentic strategies. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
Yao, S. et al. (2023). ReAct: Synergizing Reasoning and Acting in Language Models. International Conference on Learning Representations. arXiv. ↩
Schick, T. et al. (2023). Toolformer: Language Models Can Teach Themselves to Use Tools. DOI. ↩
Gao, L., Ma, X., Lin, J. y Callan, J. (2022). Precise Zero-Shot Dense Retrieval without Relevance Labels. arXiv. Asai, A., Wu, Z., Wang, Y., Sil, A. y Hajishirzi, H. (2023). Self-RAG: Learning to Retrieve, Generate, and Critique through Self-Reflection. arXiv. Yan, S.-Q., Gu, J.-C., Zhu, Y. y Ling, Z.-H. (2024). Corrective Retrieval Augmented Generation. arXiv. ↩
Edge, D. et al. (2024). From Local to Global: A Graph RAG Approach to Query-Focused Summarization. arXiv. ↩
Microsoft. (2026). GraphRAG Query Engine overview. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
Microsoft, 2026. ↩

Capítulo 12

Facsímil 4 · La caja de herramientas

Capítulo 12: Text-to-SQL y herramientas de datos

La pregunta que no está en un documento

En el capítulo 11 vimos que un sistema puede decidir consultar distintas fuentes antes de responder. Algunas fuentes son textos: normativas, manuales, tickets, actas. Otras no son textos en sentido estricto: tablas, bases de datos, métricas, historiales, estados de pedidos, matrículas, pagos, sensores o registros de producto.

Ahí aparece una frontera importante. Un RAG puede explicar “qué dice la política de matrícula”. Pero si preguntas “¿cuántos alumnos tienen pago pendiente y beca en revisión?”, no quieres que el modelo imagine un número a partir de párrafos. Quieres que consulte datos.

Text-to-SQL nace de esa necesidad: convertir una pregunta humana en una consulta SQL controlada. No es “hablar con la base de datos como si fuera una persona”. Es construir un puente auditado entre intención, esquema, permisos, consulta, ejecución, resultado y explicación.

Estado del arte con fecha de corte

Fecha de corte: 26 de mayo de 2026.
Fuentes consultadas ese día: papers de Spider, RAT-SQL, PICARD, BIRD y Spider 2.0; documentación oficial de LangChain SQL Agent, LlamaIndex NL SQL, OpenAI Function Calling y Structured Outputs; documentación de SQLGlot, DuckDB y repositorio público de Vanna.

Text-to-SQL se estudia desde hace años como una tarea de semantic parsing: traducir lenguaje natural a una representación formal ejecutable. Spider marcó un salto porque propuso preguntas y consultas complejas sobre 200 bases de datos, con esquemas distintos entre entrenamiento y prueba; su objetivo era medir generalización a bases nuevas, no memorizar una sola tabla.¹

Después se vio que una parte crítica no era solo generar SQL, sino entender el esquema. RAT-SQL trabajó explícitamente el schema linking: conectar palabras de la pregunta con tablas, columnas y relaciones del esquema mediante atención consciente de relaciones.² PICARD atacó otro problema: incluso un modelo capaz puede producir SQL inválido. Su propuesta restringe la decodificación con parsing incremental para rechazar tokens que romperían la sintaxis formal.³

Los benchmarks más recientes empujaron la tarea hacia condiciones más reales. BIRD introdujo bases de datos grandes, valores sucios, conocimiento externo y eficiencia de consulta; reportó 12.751 pares pregunta-SQL sobre 95 bases de datos y 33,4 GB.⁴ Spider 2.0 fue más allá: problemas de flujo empresarial, más de 1.000 columnas en algunas bases, varios dialectos como BigQuery y Snowflake, metadatos extensos y tareas que pueden requerir múltiples consultas.⁵

En herramientas prácticas, LangChain documenta un flujo de SQL agent que lista tablas, decide cuáles son relevantes, inspecciona esquemas, genera consulta, revisa errores comunes, ejecuta y formula respuesta.⁶ LlamaIndex ofrece componentes NL SQL y advierte que ejecutar consultas generadas requiere especial cuidado con permisos y entorno.⁷ OpenAI documenta function calling como forma de describir herramientas mediante esquemas y recibir argumentos estructurados; Structured Outputs permite exigir que una salida siga un esquema JSON compatible.⁸

Qué no es Text-to-SQL

Text-to-SQL no es “darle acceso libre a la base de datos al modelo”. El modelo no debería decidir por su cuenta qué puede leer, cuántas filas puede sacar, qué tablas puede cruzar o si una consulta es aceptable. Eso lo decide el sistema.

Tampoco es un reemplazo completo de un equipo de datos. Muchas preguntas parecen simples y esconden definiciones de negocio: “cliente activo”, “ingreso neto”, “alumno matriculado”, “churn”, “pedido completado”. Si esas definiciones no viven en una capa semántica o en documentación recuperable, el modelo puede generar una consulta válida que responde a otra pregunta.

Y no es solo una tarea de SQL. En producción intervienen permisos, catálogo, metadatos, documentación de columnas, dialecto, coste, timeouts, límites de filas, validación, trazas y evaluación. La consulta es una pieza. El sistema es todo lo que evita que esa pieza se use mal.

Qué sí es

Text-to-SQL es una tubería controlada:

pregunta -> intención -> esquema relevante -> SQL candidato
         -> validación -> ejecución limitada -> resultado
         -> explicación con trazas

La unidad de trabajo no es “una query”. La unidad de trabajo es una solicitud de datos con contexto:

Pieza	Qué contiene	Ejemplo
Pregunta	Lo que pide la persona.	“Ingresos por campus en marzo”.
Usuario	Identidad, rol y permisos.	`analista_matricula`, campus permitido.
Dominio	Área de datos.	Matrícula, becas, pagos, soporte.
Esquema	Tablas, columnas, claves y tipos.	`pagos`, `alumnos`, `campus`.
Semántica	Definiciones de negocio.	“ingreso neto = importe - devoluciones”.
SQL	Consulta candidata.	`SELECT campus, SUM(...) ...`.
Validación	Reglas antes de ejecutar.	Solo `SELECT`, `LIMIT`, timeout.
Resultado	Filas devueltas.	Tabla agregada.
Explicación	Resumen humano.	“Campus Norte concentra el 42%”.
Traza	Registro completo.	Tablas usadas, SQL, coste, tiempo.

Para entenderlo bien, pensemos en una pregunta sencilla:

“¿Cuáles son los tres campus con más pagos pendientes?”

El sistema no debería saltar directamente a escribir SQL. Primero debe saber qué significa “pagos pendientes”, dónde vive “campus”, si la persona puede ver todos los campus, si hay que excluir pagos anulados, si la moneda importa y si “tres” implica ordenar de mayor a menor.

SQL desde cero, pero sin rebajarlo

SQL es el lenguaje clásico para consultar datos relacionales. Una base relacional organiza información en tablas. Cada tabla tiene filas y columnas. Una fila representa una entidad o evento; una columna representa un atributo.

Una base de datos no es un Excel grande. En una hoja plana es habitual repetir datos para que todo quepa en una misma vista. En una base relacional se separan entidades y eventos para que cada cosa tenga un lugar claro: alumnos por un lado, pagos por otro, becas por otro. Después una consulta une lo que necesita mediante claves.

Ejemplo mínimo:

tabla `pagos`	significado
`pago_id`	identificador del pago.
`alumno_id`	alumno asociado.
`campus`	campus administrativo.
`estado`	`pagado`, `pendiente`, `devuelto`.
`importe`	cantidad.
`fecha`	fecha del movimiento.

Una consulta básica:

SELECT campus, SUM(importe) AS total_pendiente
FROM pagos
WHERE estado = 'pendiente'
GROUP BY campus
ORDER BY total_pendiente DESC
LIMIT 3;

Esto se lee así:

Cláusula	Qué hace	En castellano
`SELECT`	Elige columnas o cálculos.	Quiero campus y suma de importe.
`FROM`	Indica la tabla base.	Usa la tabla de pagos.
`WHERE`	Filtra filas antes de agrupar.	Solo pagos pendientes.
`GROUP BY`	Agrupa filas por una dimensión.	Junta pagos por campus.
`ORDER BY`	Ordena resultados.	Primero los importes mayores.
`LIMIT`	Limita filas devueltas.	Dame solo tres.

La parte que más se suele subestimar es el JOIN: cruzar tablas. Si pagos tiene alumno_id, pero la titulación vive en alumnos, necesitamos unir:

SELECT a.titulacion, SUM(p.importe) AS total_pendiente
FROM pagos AS p
JOIN alumnos AS a ON a.alumno_id = p.alumno_id
WHERE p.estado = 'pendiente'
GROUP BY a.titulacion
ORDER BY total_pendiente DESC
LIMIT 5;

Un JOIN no es decoración. Es una afirmación sobre relación entre tablas. Si la clave es incorrecta, el resultado puede ser válido en SQL y falso en negocio.

Errores SQL que cambian la historia

Para un ingeniero, el peligro no está solo en que el modelo genere SQL inválido. Ese fallo es fácil de detectar. El peligro serio es que genere SQL válido, rápido y aparentemente razonable, pero calcule otra cosa.

Error	SQL que suele aparecer	Qué rompe	Cómo pensarlo
Duplicar filas con un `JOIN`	Unir `alumnos` con varias filas de `pagos`.	`COUNT(*)` sube porque un alumno aparece varias veces.	Cuenta entidades con `COUNT(DISTINCT alumno_id)`.
Confundir evento y entidad	Contar pagos como si fueran alumnos.	Mide movimientos, no personas.	Pregunta si cada fila es “cosa” o “suceso”.
Ignorar `NULL`	`AVG(importe)` sin revisar ausentes.	Algunos cálculos excluyen nulos sin avisar.	Decide si nulo significa desconocido, cero o no aplica.
Filtrar tarde	Usar `HAVING` cuando tocaba `WHERE`.	Agrupa datos que no deberían entrar.	`WHERE` filtra filas; `HAVING` filtra grupos.
Fechas mal cerradas	`fecha <= '2026-03-31'`.	Puede perder horas del último día.	Usa rangos semiabiertos: `>= inicio` y `< fin`.
Moneda mezclada	`SUM(importe)` sin moneda.	Suma euros, dólares o créditos como si fueran iguales.	Agrupa o convierte antes de sumar.
Estado de negocio incompleto	`estado != 'pagado'`.	Incluye anulados, devueltos o pruebas.	Define catálogo permitido, no solo excluido.

Miremos el fallo de duplicación, que aparece mucho en sistemas Text-to-SQL. Si una tabla alumnos tiene una fila por alumno y pagos tiene varias filas por alumno, este SQL cuenta pagos, no alumnos:

SELECT COUNT(*) AS alumnos_con_pago
FROM alumnos AS a
JOIN pagos AS p ON p.alumno_id = a.alumno_id
WHERE p.estado = 'pendiente';

Si un alumno tiene tres pagos pendientes, aparece tres veces. La consulta puede ejecutarse sin quejarse y devolver un número bonito, pero el significado es otro. Para contar alumnos únicos:

SELECT COUNT(DISTINCT a.alumno_id) AS alumnos_con_pago_pendiente
FROM alumnos AS a
JOIN pagos AS p ON p.alumno_id = a.alumno_id
WHERE p.estado = 'pendiente';

La diferencia entre COUNT(*) y COUNT(DISTINCT ...) no es un detalle académico. Es la diferencia entre contar filas y contar entidades. Cuando una persona pregunta “cuántos alumnos”, normalmente quiere entidades. Cuando pregunta “cuántos pagos”, quiere eventos.

También importan las fechas. Si fecha incluye hora, esta condición parece correcta pero puede dejar fuera movimientos del 31 de marzo por la tarde:

WHERE fecha >= '2026-03-01'
  AND fecha <= '2026-03-31'

El patrón más robusto para intervalos suele ser:

WHERE fecha >= '2026-03-01'
  AND fecha < '2026-04-01'

Un buen sistema Text-to-SQL no solo valida sintaxis. También mira estas trampas: cardinalidad de las tablas, tipo de métrica, nulos, moneda, rango temporal, catálogo de estados y claves de unión.

El mecanismo paso a paso

Text-to-SQL funciona bien cuando se separan tareas. Un modelo que recibe “todas las tablas, toda la documentación y genera SQL” puede acertar en una demo pequeña, pero se vuelve frágil con esquemas grandes.

Un sistema así no depende de una única llamada al modelo. Depende de contratos entre piezas. La persona pregunta; el clasificador decide si la pregunta es de datos o de documentos; el selector reduce el esquema; la capa semántica aporta definiciones; el generador propone SQL; el validador inspecciona; la base ejecuta con límites; la respuesta explica y registra.

El problema real: esquema, semántica y valores

Cuando un humano experto escribe SQL, no solo recuerda sintaxis. Recuerda el significado de cada tabla, qué columnas son fiables, qué claves se unen, qué estados se excluyen, qué fechas mandan y qué métricas no se calculan directamente.

Text-to-SQL falla por tres razones principales:

Foco	Qué falla	Ejemplo
Esquema	El modelo elige tabla o columna incorrecta.	Usa `created_at` en vez de `paid_at`.
Semántica	La consulta no respeta definición de negocio.	Cuenta alumnos anulados como activos.
Valores	No sabe cómo están escritos los datos reales.	Busca `pendiente` pero la tabla usa `PENDING`.

El schema linking conecta pregunta y esquema. Si la pregunta dice “campus con pagos pendientes”, el sistema debe vincular:

Palabra de la pregunta	Candidato en datos	Por qué
campus	`alumnos.campus` o `pagos.campus`	Dimensión de agrupación.
pagos	tabla `pagos`	Hecho económico.
pendientes	`pagos.estado = 'pendiente'`	Filtro.
tres	`LIMIT 3`	Tamaño de salida.
más	`ORDER BY total DESC`	Orden descendente.

En bases pequeñas se puede meter todo el esquema en el prompt. En bases grandes no. Hay que recuperar el esquema como se recuperan documentos: por dominio, por nombres, por descripciones, por consultas de ejemplo y por permisos.

La capa semántica como contrato

La capa semántica es el lugar donde una organización deja de discutir cada vez qué significa una métrica. No es una frase bonita en un prompt. Es un contrato versionado entre negocio, ingeniería y análisis.

Una definición mínima de métrica debería responder:

Pregunta	Ejemplo para `ingreso_neto`
¿Qué entidad mide?	Pagos confirmados.
¿Qué columna numérica usa?	`pagos.importe`.
¿Qué estados entran?	Solo `pagado`.
¿Qué estados salen?	`pendiente`, `anulado`, `devuelto`, `prueba`.
¿Qué fecha manda?	`fecha_pago`, no `fecha_creacion`.
¿Qué dimensiones permite?	`campus`, `titulacion`, `mes`.
¿Quién puede verla?	Roles de análisis y dirección académica.
¿Cómo se prueba?	Casos con resultado esperado.

Esa misma definición puede expresarse de muchas formas: YAML, dbt metrics, una tabla de metadatos, una API interna o una vista SQL. Lo importante es que el modelo no invente la definición cada vez.

metric: ingreso_neto
entity: pagos
expression: SUM(importe)
filters:
  - estado = 'pagado'
time_dimension: fecha_pago
allowed_dimensions:
  - campus
  - titulacion
  - mes
blocked_columns:
  - dni
  - email_personal
owner: equipo_datos_matricula

Con esa capa, una pregunta como “ingresos por campus en marzo” no empieza desde cero. El sistema sabe que “ingresos” apunta a ingreso_neto, que marzo debe filtrarse con fecha_pago, que el grupo permitido es campus y que algunas columnas ni siquiera deben entrar en el contexto.

Para una persona curiosa, la idea es esta: una base de datos guarda datos, pero no siempre guarda significado. La capa semántica añade significado compartido. Para un ingeniero, añade algo igual de importante: reduce libertad donde la libertad produce errores.

Herramientas de datos: no todo es Text-to-SQL

Text-to-SQL es una herramienta, pero no la única. A veces conviene no dejar que el modelo genere SQL libre, sino exponer operaciones más estrechas.

Tipo de herramienta	Qué hace	Cuándo usarla	Ejemplo
Text-to-SQL libre	Genera consultas nuevas.	Análisis exploratorio con validación fuerte.	“Agrupa pagos por campus y mes”.
Plantilla parametrizada	Rellena parámetros de una consulta fija.	Métricas críticas y repetibles.	`campus`, `fecha_inicio`, `fecha_fin`.
Stored procedure	Llama a una función definida en la base.	Regla compleja y estable.	`calcular_morosidad(campus, mes)`.
Semantic layer	Consulta métricas y dimensiones declaradas.	BI, reporting y definiciones de negocio.	`ingreso_neto` por `campus`.
DataFrame tool	Opera sobre tablas en memoria.	Exploración local, CSV, notebooks.	Pandas, Polars, DuckDB.
Chart tool	Convierte resultados en gráfico.	Cuando la salida natural es visual.	Barras por campus.
Data quality tool	Comprueba nulos, duplicados o rangos.	Antes de confiar en una respuesta.	“¿Hay importes negativos?”.

La pregunta de arquitectura no es “¿puedo generar SQL?”. La pregunta buena es “¿qué superficie de datos quiero exponer?”. Cuanto más abierta sea la herramienta, más validación necesita.

Contrato de una herramienta SQL

Una herramienta SQL no debería aceptar una cadena cualquiera. Debería tener un contrato que obligue a declarar intención, dominio, límites y formato de respuesta.

{
  "name": "consultar_datos",
  "input": {
    "question": "Pagos pendientes por campus en marzo",
    "domain": "matricula",
    "sql": "SELECT campus, SUM(importe) AS total FROM pagos ...",
    "dialect": "sqlite",
    "max_rows": 50,
    "timeout_ms": 1500,
    "purpose": "analisis_agregado"
  },
  "output": {
    "columns": ["campus", "total"],
    "rows": [["Norte", 19320.0]],
    "row_count": 1,
    "elapsed_ms": 24,
    "trace_id": "f4c12-001"
  },
  "errors": [
    "tabla_no_permitida",
    "consulta_no_select",
    "demasiadas_filas",
    "timeout",
    "sql_invalido"
  ]
}

Cada campo tiene una razón:

Campo	Qué controla	Por qué importa
`domain`	Área funcional.	Evita mezclar tablas sin contexto.
`sql`	Consulta candidata.	Debe poder validarse y registrarse.
`dialect`	Motor SQL esperado.	`LIMIT`, fechas y funciones cambian entre motores.
`max_rows`	Filas máximas.	Protege coste y evita respuestas inmanejables.
`timeout_ms`	Tiempo máximo.	Una mala consulta no debe bloquear el sistema.
`purpose`	Uso declarado.	No es igual explorar que cerrar un informe.
`trace_id`	Identificador de ejecución.	Permite reproducir y auditar.

La herramienta puede estar detrás de OpenAI Function Calling, de un agente de LangChain, de LlamaIndex, de una API propia o de un servicio interno. El principio no cambia: el modelo propone argumentos estructurados, pero el servidor valida y ejecuta.

Permisos, datos sensibles y trazas

Una herramienta de datos tiene tres identidades distintas y conviene no mezclarlas:

Identidad	Qué representa	Error típico
Persona usuaria	Quien hace la pregunta.	Darle acceso por el rol técnico del servidor.
Modelo	Quien propone la consulta.	Tratar su SQL como decisión autorizada.
Servicio de datos	Quien ejecuta.	Conectar con permisos demasiado amplios.

El modelo no debería tener permisos. Quien tiene permisos es el servicio que recibe una petición, revisa el rol de la persona, aplica reglas y ejecuta una consulta limitada. Esa separación evita que una respuesta dependa de una frase del prompt.

En una arquitectura seria, pondría estos controles:

Control	Qué protege	Ejemplo concreto
Conexión read-only	Evita modificar datos.	Usuario SQL sin `INSERT`, `UPDATE`, `DELETE` ni DDL.
Réplica de lectura	Aísla producción.	Consultar una réplica o almacén analítico.
Row-level security	Limita filas por rol.	Un campus solo ve sus alumnos.
Column allowlist	Limita columnas visibles.	Exponer `campus`, no `dni` ni `email_personal`.
Query timeout	Evita consultas largas.	Cortar a 1.500 ms en exploración.
Row limit	Controla volumen de salida.	Máximo 100 filas por respuesta.
Redacción de logs	Evita guardar datos innecesarios.	Registrar SQL y hash de usuario, no tabla completa.
Trazabilidad	Permite reproducir.	`trace_id`, versión de esquema, modelo y validador.

La traza no es vigilancia decorativa. Es el expediente técnico de la respuesta. Si alguien pregunta “¿de dónde salió este número?”, necesitas poder reconstruir pregunta, usuario, rol, tablas candidatas, SQL generado, reglas aplicadas, resultado, latencia y versión del sistema.

Validación antes de ejecutar

La validación no es un adorno. Es el corazón del sistema. Un validador mínimo debería revisar:

Control	Qué comprueba	Ejemplo de regla
Tipo de consulta	Solo lectura.	Aceptar únicamente `SELECT` o `WITH ... SELECT`.
Tablas permitidas	Superficie acotada.	`pagos`, `alumnos`, `campus`.
Columnas permitidas	Evitar columnas fuera de contrato.	No exponer `dni` si no hace falta.
Límite de filas	Salida manejable.	Añadir o exigir `LIMIT 100`.
Timeout	Coste temporal.	Cortar a 1,5 segundos.
Dialecto	Sintaxis correcta.	SQLite no es BigQuery.
Agregación	Preguntas agregadas devuelven agregados.	`SUM`, `COUNT`, `AVG`.
Filtros de usuario	Permisos por rol.	Campus permitido por sesión.
Explicación	Respuesta basada en resultado.	No resumir columnas que no salieron.

Herramientas como SQLGlot ayudan a parsear, inspeccionar y transpilar SQL entre dialectos.⁹ Motores embebidos como DuckDB son útiles para análisis local, CSV, Parquet o notebooks, porque permiten ejecutar SQL desde Python sin levantar un servidor externo.¹⁰

Query plan: cuando una consulta correcta no cabe

Una consulta puede ser correcta y aun así no ser aceptable. Si tarda treinta segundos, bloquea recursos o escanea una tabla enorme para devolver tres filas, el problema no es solo del modelo: es del sistema que no miró el plan.

El query plan es la explicación interna que calcula el motor antes de ejecutar. Según el motor puede verse con EXPLAIN, EXPLAIN ANALYZE, perfiles de consulta o dry-run. Los nombres cambian, pero la pregunta es la misma: ¿qué tendrá que hacer la base para responder?

EXPLAIN
SELECT campus, SUM(importe) AS total_pendiente
FROM pagos
WHERE estado = 'pendiente'
GROUP BY campus
ORDER BY total_pendiente DESC
LIMIT 3;

Al leer un plan, no hace falta entender todo desde el primer día. Empieza por estas señales:

Señal	Qué significa	Por qué importa
Full scan	Recorrer muchas filas de una tabla.	Puede ser normal en tablas pequeñas, caro en tablas grandes.
Index scan	Localizar filas con un índice.	Suele ayudar si el filtro es selectivo.
Cardinalidad estimada	Filas que el motor cree que pasarán.	Si estima mal, elige planes pobres.
Join strategy	Forma de unir tablas.	Nested loop, hash join o merge join tienen costes distintos.
Sort	Ordenación intermedia.	`ORDER BY` sobre muchas filas puede ser caro.
Temporary spill	Datos intermedios fuera de memoria.	Señal de presión de memoria o consulta pesada.

Un índice no resuelve todo. Acelera ciertas búsquedas a cambio de ocupar espacio y complicar escrituras. Si filtras mucho por estado y fecha, un índice puede ayudar:

CREATE INDEX idx_pagos_estado_fecha
ON pagos (estado, fecha);

Pero si casi todos los pagos están en estado = 'pendiente', ese índice quizá no aporta mucho, porque el filtro no reduce bastante. Esta idea se llama selectividad: un filtro útil descarta muchas filas.

Para Text-to-SQL, el plan sirve como control previo:

Pregunta técnica	Decisión del sistema
¿Escanea más filas de las permitidas?	Pedir aclaración, añadir filtro o bloquear.
¿Usa tablas fuera del dominio?	Rechazar y pedir reformulación.
¿Ordena millones de filas sin agregación previa?	Proponer una consulta agregada.
¿No hay índice para el filtro principal?	Avisar de latencia o derivar a informe offline.

Dialecto SQL: el mismo pedido cambia por motor

SQL tiene una gramática común, pero cada motor añade funciones, tipos y límites. Un sistema que genera SQL debe saber para qué motor escribe. SQLite no es PostgreSQL, PostgreSQL no es BigQuery, BigQuery no es Snowflake.

Necesidad	SQLite	PostgreSQL	BigQuery	Snowflake
Limitar filas	`LIMIT 10`	`LIMIT 10`	`LIMIT 10`	`LIMIT 10`
Mes de una fecha	`strftime('%Y-%m', fecha)`	`date_trunc('month', fecha)`	`DATE_TRUNC(fecha, MONTH)`	`DATE_TRUNC('MONTH', fecha)`
Concatenar texto	`a		b`	`a
Fecha actual	`date('now')`	`CURRENT_DATE`	`CURRENT_DATE()`	`CURRENT_DATE()`
Muestra aproximada	Limitado	`TABLESAMPLE`	`TABLESAMPLE SYSTEM`	`SAMPLE`

No hace falta memorizar todos los dialectos. Lo importante es no mezclar. Si el contrato dice dialect: "sqlite", el generador, el parser, los ejemplos y el validador deben hablar SQLite. Si el almacén real es BigQuery, conviene validar con BigQuery o con un parser que entienda sus particularidades.

Esta es una razón más para no pegar ejemplos al azar en el prompt. Un ejemplo de PostgreSQL puede enseñar al modelo una función que luego falla en BigQuery. Los ejemplos son datos de entrenamiento local para la consulta que estás a punto de generar; si están mal elegidos, orientan mal.

Cómo elegir arquitectura

La solución correcta depende del riesgo, del tamaño del esquema y de lo repetible que sea la pregunta.

Situación	Arquitectura recomendada	Por qué
Métrica crítica y estable.	Plantilla parametrizada.	Menos libertad, más confianza.
Exploración interna con datos agregados.	Text-to-SQL con validación y trazas.	Permite flexibilidad controlada.
BI con definiciones compartidas.	Semantic layer + modelo.	Las métricas viven fuera del prompt.
CSV local o notebook.	DuckDB/DataFrame tool.	Iteración rápida y entorno cerrado.
Esquema enorme.	Retrieval de esquema + examples RAG.	No cabe todo el catálogo.
Varias bases y documentos.	Router + herramientas especializadas.	No todo debe ir por SQL.
Preguntas repetidas de negocio.	Stored procedures o vistas.	La lógica queda versionada.

Mi regla práctica: si la pregunta puede romper un informe importante, no empieces con SQL libre. Empieza con métrica declarada, plantilla o vista. Usa Text-to-SQL libre para exploración, no para convertir cada pregunta de negocio en una consulta nueva sin revisión.

Coste, latencia y contexto

Text-to-SQL parece barato porque la salida es corta. Pero el contexto puede crecer muchísimo: documentación de tablas, columnas, ejemplos, métricas, permisos, dialecto y trazas anteriores.

Ejemplo de fórmula. Podemos aproximar el contexto así:

T_{\text{ctx}} = T_{\text{pregunta}} + T_{\text{schema}} + T_{\text{docs}} + T_{\text{ejemplos}} + T_{\text{politicas}}

Símbolo	Significado	Ejemplo
$T_{\text{ctx}}$	Tokens totales de contexto.	6.400 tokens.
$T_{\text{pregunta}}$	Pregunta del usuario.	30 tokens.
$T_{\text{schema}}$	Tablas, columnas y claves incluidas.	2.500 tokens.
$T_{\text{docs}}$	Documentación de negocio.	1.200 tokens.
$T_{\text{ejemplos}}$	Consultas parecidas.	1.800 tokens.
$T_{\text{politicas}}$	Permisos y reglas.	870 tokens.

Ejemplo de fórmula. La latencia total no es solo generación:

L_{\text{total}} = L_{\text{router}} + L_{\text{schema}} + L_{\text{LLM}} + L_{\text{validacion}} + L_{\text{db}} + L_{\text{resumen}}

Símbolo	Significado	Ejemplo
$L_{\text{schema}}$	Tiempo de recuperar esquema relevante.	80 ms.
$L_{\text{LLM}}$	Tiempo de generar SQL o plan.	1.200 ms.
$L_{\text{validacion}}$	Parser, reglas y dry-run.	90 ms.
$L_{\text{db}}$	Ejecución en base de datos.	300 ms.
$L_{\text{resumen}}$	Redacción final.	700 ms.

Ejemplo de fórmula. Y el coste esperado por pregunta:

C = C_{\text{modelo}} + C_{\text{db}} + C_{\text{observabilidad}} + C_{\text{mantenimiento}}

La parte invisible suele ser $C_{\text{mantenimiento}}$ : documentar columnas, versionar métricas, revisar consultas fallidas, actualizar ejemplos y controlar cambios de esquema.

Evaluar Text-to-SQL

La evaluación clásica compara SQL generado contra SQL esperado. Eso ayuda, pero no basta. Dos consultas distintas pueden devolver el mismo resultado; dos consultas parecidas pueden divergir en casos frontera.

Métrica	Qué mide	Cuidado
Exact match	Si el SQL coincide con el esperado.	Penaliza consultas equivalentes escritas distinto.
Execution accuracy	Si produce el resultado correcto.	Puede acertar por casualidad en datos pequeños.
Result-set match	Si filas y columnas coinciden.	Hay que controlar orden, tipos y redondeo.
Component match	Si `SELECT`, `WHERE`, `JOIN`, `GROUP BY` están bien.	Útil para depurar.
Schema-link accuracy	Si eligió tablas y columnas correctas.	Necesita anotación o revisión.
Permission pass rate	Si respeta permisos y límites.	No basta medir precisión.
Query cost	Coste estimado o real de ejecución.	Una query correcta puede ser inviable.
Latencia P95	Tiempo para el 95% de consultas.	La media oculta colas lentas.
Clarification rate	Cuándo pide aclaración.	Preguntar puede ser mejor que inventar.

Un dataset propio debería tener:

Campo	Ejemplo
`question`	“Pagos pendientes por campus en marzo”.
`user_role`	`analista_matricula`.
`allowed_tables`	`pagos`, `alumnos`, `campus`.
`gold_sql`	Consulta esperada o plantilla.
`expected_result`	Filas esperadas.
`must_not_use`	Columnas que no proceden.
`notes`	Definición de negocio relevante.

En producción mediría, como mínimo:

Capa	Pregunta de evaluación
Clasificador	¿Detectó que era una pregunta de datos?
Selector de esquema	¿Incluyó las tablas necesarias y excluyó ruido?
Generador	¿Produjo SQL válido para el dialecto?
Validador	¿Bloqueó lo que debía bloquear?
Ejecución	¿Devolvió resultado correcto dentro de límite?
Resumen	¿Explicó solo lo que aparece en la tabla?
Trazas	¿Puedo reproducir la respuesta?

Una forma práctica de empezar es construir un pequeño harness de evaluación. No tiene que ser perfecto. Tiene que hacer visible cuándo el sistema mejora o empeora.

{
  "id": "matricula-001",
  "question": "Alumnos con pago pendiente por campus en marzo",
  "role": "analista_matricula",
  "dialect": "sqlite",
  "allowed_tables": ["pagos", "alumnos"],
  "expected_sql_patterns": ["GROUP BY campus", "estado = 'pendiente'"],
  "expected_result": [
    {"campus": "Norte", "alumnos": 2},
    {"campus": "Centro", "alumnos": 1}
  ],
  "max_latency_ms": 1500,
  "max_rows": 20,
  "must_not_use": ["dni", "email_personal"],
  "review_note": "Debe contar alumnos únicos, no pagos."
}

En ese ejemplo no basta con que aparezca GROUP BY campus. El caso dice explícitamente que hay que contar alumnos únicos. Esa nota evita que una consulta con COUNT(*) pase por casualidad cuando los datos de prueba son pequeños.

Un harness útil debería guardar cuatro salidas:

Salida	Para qué sirve
SQL generado	Revisar estructura y dialecto.
Resultado devuelto	Comparar con la tabla esperada.
Razón de validación	Saber si el sistema aceptó o bloqueó con criterio.
Traza	Reproducir el caso con misma versión de esquema y modelo.

Y debería separar tipos de error. No es igual fallar por sintaxis que fallar por semántica:

Tipo de fallo	Ejemplo	Qué arreglar
Sintaxis	Función inexistente para el dialecto.	Ejemplos y parser.
Schema linking	Usa `created_at` en lugar de `paid_at`.	Descripciones y selector de esquema.
Semántica	Cuenta pagos cuando debía contar alumnos.	Capa semántica y casos de prueba.
Permisos	Incluye columna no permitida.	Validador y allowlist.
Coste	Query correcta pero pesada.	Plan, índices, límites o vista agregada.
Explicación	Resume algo que no está en el resultado.	Contrato de respuesta y groundedness.

Cuando conviene pedir aclaración

Una buena herramienta de datos no responde siempre. A veces pregunta.

Pregunta original	Qué falta	Mejor respuesta del sistema
“Ventas del mes”.	Mes, definición de venta, región.	“¿Qué mes y qué métrica de ventas quieres usar?”
“Alumnos activos”.	Definición de activo.	“Puedo usar matrícula vigente o acceso reciente. ¿Cuál prefieres?”
“Top clientes”.	Top por ingresos, pedidos o margen.	“¿Quieres ordenar por ingresos, margen o número de pedidos?”
“Comparar campus”.	Periodo y métrica.	“Dime periodo y métrica principal.”

Pedir aclaración no es fallar. En datos, muchas respuestas incorrectas nacen de contestar demasiado rápido.

Caso completo: de pregunta a respuesta trazable

Tomemos una pregunta realista:

“Dame los tres campus con más alumnos con pagos pendientes en marzo.”

Parece una pregunta simple. No lo es. Hay una entidad, alumnos; un evento, pagos; una condición, pendientes; una ventana temporal, marzo; una agrupación, campus; un ranking, los tres primeros.

El sistema debería recorrer algo parecido a esto:

Paso	Decisión	Resultado intermedio
1. Intención	Es una pregunta de datos agregados.	Ruta a herramienta SQL.
2. Dominio	Matrícula y pagos.	No consulta documentos generales.
3. Usuario	Rol `analista_matricula`.	Puede ver agregados por campus.
4. Esquema	Necesita `pagos` y quizá `alumnos`.	No carga todo el catálogo.
5. Semántica	“Alumnos con pagos pendientes” cuenta alumnos únicos.	Métrica: `COUNT(DISTINCT alumno_id)`.
6. Fecha	Marzo se interpreta como rango semiabierto.	`>= '2026-03-01'` y `< '2026-04-01'`.
7. SQL candidato	Genera consulta agregada.	`GROUP BY campus`, `ORDER BY`, `LIMIT 3`.
8. Validación	Solo lectura, tablas permitidas, límite.	Acepta o pide corrección.
9. Plan	Estima filas y coste.	Bloquea si escanea demasiado.
10. Ejecución	Ejecuta en réplica de lectura.	Devuelve tabla pequeña.
11. Respuesta	Explica solo la tabla.	No inventa causas.
12. Traza	Registra expediente.	Permite reproducir.

Un SQL razonable podría ser:

SELECT
  p.campus,
  COUNT(DISTINCT p.alumno_id) AS alumnos_con_pago_pendiente
FROM pagos AS p
WHERE p.estado = 'pendiente'
  AND p.fecha >= '2026-03-01'
  AND p.fecha < '2026-04-01'
GROUP BY p.campus
ORDER BY alumnos_con_pago_pendiente DESC
LIMIT 3;

Fíjate en lo que no hace:

No hace	Por qué
No usa `COUNT(*)`.	Contaría pagos, no alumnos.
No usa `estado != 'pagado'`.	Metería estados no definidos.
No pide columnas personales.	La pregunta solo necesita agregados.
No devuelve filas individuales.	La salida pedida es un ranking.
No explica causas.	La consulta no investigó causas, solo conteos.

La respuesta humana debería sonar así:

“Con la definición de pagos pendientes como estado = 'pendiente' y tomando marzo como [2026-03-01, 2026-04-01), los tres campus con más alumnos únicos con pagos pendientes son Norte, Centro y Sur. La consulta usa datos agregados y no incluye información personal.”

Y la traza técnica podría guardar:

{
  "trace_id": "f4c12-demo-023",
  "question": "Dame los tres campus con más alumnos con pagos pendientes en marzo",
  "route": "sql_tool",
  "role": "analista_matricula",
  "dialect": "sqlite",
  "tables": ["pagos"],
  "metric": "count_distinct_alumno_id",
  "validated": true,
  "checks": ["read_only", "allowed_tables", "row_limit", "date_range"],
  "row_count": 3,
  "elapsed_ms": 31
}

Esta traza no es para enseñarla entera a la persona que pregunta. Es para que el equipo pueda auditar, depurar y mejorar el sistema.

Soluciones de terceros y piezas habituales

Hay herramientas ya hechas, pero conviene saber qué problema resuelve cada una. No todas sustituyen una arquitectura propia.

Pieza	Qué aporta	Qué revisaría antes de usarla
LangChain SQL Agent	Flujo agentic para inspeccionar esquema, generar, revisar y ejecutar SQL.	Permisos de conexión, trazas, límites y revisión humana.
LlamaIndex NL SQL	Query engines para lenguaje natural sobre tablas SQL.	Qué esquema entra, cómo controla ejecución y cómo registra fuentes.
Vanna	Enfoque natural language -> SQL -> respuestas con permisos y componentes de UI.	El repositorio público aparece archivado desde marzo de 2026; revisaría mantenimiento y versión usada.¹¹
SQLGlot	Parser, AST y transpiler SQL.	Cobertura del dialecto y reglas propias de validación.
DuckDB	Motor local para análisis, CSV y Parquet desde Python.	Memoria, tamaño de datos y diferencias frente al motor de producción.
dbt / capa semántica	Métricas y transformaciones versionadas.	Quién mantiene definiciones y cómo se exponen al modelo.
BI tradicional	Dashboards y métricas curadas.	Qué preguntas quedan fuera del dashboard.

Una buena arquitectura puede mezclar varias: LangChain o LlamaIndex para orquestar, SQLGlot para validar, DuckDB para prototipos locales, una capa semántica para métricas y una API propia para permisos.

Manos a la obra

Vamos a construir una mini herramienta Text-to-SQL sin llamar a ningún modelo. Simularemos la parte que haría el modelo con un diccionario de preguntas, pero construiremos lo importante: base de datos, SQL candidato, validación, ejecución limitada y traza.

import re
import sqlite3
from pprint import pprint


SCHEMA = {
    "pagos": {
        "columns": {
            "pago_id",
            "alumno_id",
            "campus",
            "estado",
            "importe",
            "fecha",
        }
    },
    "alumnos": {
        "columns": {
            "alumno_id",
            "titulacion",
            "campus",
            "estado_matricula",
        }
    },
}

ALLOWED_TABLES = set(SCHEMA)
MAX_ROWS = 20


def crear_bd():
    con = sqlite3.connect(":memory:")
    con.execute("""
        CREATE TABLE alumnos (
            alumno_id INTEGER PRIMARY KEY,
            titulacion TEXT,
            campus TEXT,
            estado_matricula TEXT
        )
    """)
    con.execute("""
        CREATE TABLE pagos (
            pago_id INTEGER PRIMARY KEY,
            alumno_id INTEGER,
            campus TEXT,
            estado TEXT,
            importe REAL,
            fecha TEXT
        )
    """)
    con.executemany(
        "INSERT INTO alumnos VALUES (?, ?, ?, ?)",
        [
            (1, "Informática", "Norte", "vigente"),
            (2, "Matemáticas", "Sur", "vigente"),
            (3, "Informática", "Norte", "vigente"),
            (4, "Diseño", "Centro", "pausada"),
        ],
    )
    con.executemany(
        "INSERT INTO pagos VALUES (?, ?, ?, ?, ?, ?)",
        [
            (101, 1, "Norte", "pendiente", 420.0, "2026-03-10"),
            (102, 2, "Sur", "pagado", 300.0, "2026-03-11"),
            (103, 3, "Norte", "pendiente", 380.0, "2026-03-14"),
            (104, 4, "Centro", "pendiente", 250.0, "2026-03-18"),
            (105, 2, "Sur", "pendiente", 120.0, "2026-04-02"),
        ],
    )
    return con


def simular_modelo(pregunta):
    texto = pregunta.lower()
    if "campus" in texto and "pendiente" in texto:
        return """
            SELECT campus, SUM(importe) AS total_pendiente
            FROM pagos
            WHERE estado = 'pendiente'
            GROUP BY campus
            ORDER BY total_pendiente DESC
            LIMIT 3
        """
    if "titulaci" in texto and "pendiente" in texto:
        return """
            SELECT a.titulacion, SUM(p.importe) AS total_pendiente
            FROM pagos AS p
            JOIN alumnos AS a ON a.alumno_id = p.alumno_id
            WHERE p.estado = 'pendiente'
            GROUP BY a.titulacion
            ORDER BY total_pendiente DESC
            LIMIT 5
        """
    return """
        SELECT estado, COUNT(*) AS pagos
        FROM pagos
        GROUP BY estado
        LIMIT 10
    """


def tablas_usadas(sql):
    patron = r"\b(?:FROM|JOIN)\s+([a-zA-Z_][a-zA-Z0-9_]*)"
    return {m.group(1).lower() for m in re.finditer(patron, sql, re.I)}


def validar_sql(sql):
    limpio = " ".join(sql.strip().split())
    errores = []

    if not re.match(r"^(SELECT|WITH)\b", limpio, re.I):
        errores.append("solo se permiten consultas de lectura")

    palabras_bloqueadas = {
        "insert", "update", "delete", "create", "alter", "drop",
        "truncate", "attach", "pragma",
    }
    usadas = set(re.findall(r"\b[a-zA-Z_]+\b", limpio.lower()))
    if usadas & palabras_bloqueadas:
        errores.append("aparece una operación fuera de contrato")

    desconocidas = tablas_usadas(limpio) - ALLOWED_TABLES
    if desconocidas:
        errores.append(f"tablas no permitidas: {sorted(desconocidas)}")

    if " limit " not in f" {limpio.lower()} ":
        limpio += f" LIMIT {MAX_ROWS}"

    return limpio, errores


def ejecutar(con, sql):
    sql, errores = validar_sql(sql)
    traza = {"sql": sql, "errores": errores}
    if errores:
        return {"ok": False, "traza": traza, "rows": []}

    plan = [
        fila[3]
        for fila in con.execute("EXPLAIN QUERY PLAN " + sql).fetchall()
    ]
    cur = con.execute(sql)
    columnas = [c[0] for c in cur.description]
    filas = cur.fetchmany(MAX_ROWS + 1)
    if len(filas) > MAX_ROWS:
        return {
            "ok": False,
            "traza": {**traza, "errores": ["demasiadas filas"]},
            "rows": [],
        }
    return {
        "ok": True,
        "traza": {
            **traza,
            "columnas": columnas,
            "row_count": len(filas),
            "query_plan": plan,
        },
        "rows": [dict(zip(columnas, fila)) for fila in filas],
    }


def responder(pregunta):
    con = crear_bd()
    sql = simular_modelo(pregunta)
    resultado = ejecutar(con, sql)
    return {
        "pregunta": pregunta,
        "sql_candidato": " ".join(sql.split()),
        "resultado": resultado,
    }


def evaluar_caso(caso):
    respuesta = responder(caso["question"])
    filas = respuesta["resultado"]["rows"]
    errores = []
    if filas != caso["expected_result"]:
        errores.append("resultado distinto al esperado")
    sql = respuesta["resultado"]["traza"]["sql"].lower()
    for patron in caso["expected_sql_contains"]:
        if patron.lower() not in sql:
            errores.append(f"falta patrón SQL: {patron}")
    return {
        "case_id": caso["id"],
        "pass": not errores,
        "errores": errores,
        "trace": respuesta["resultado"]["traza"],
    }


preguntas = [
    "Tres campus con más pagos pendientes",
    "Importe pendiente por titulación",
    "Cuántos pagos hay por estado",
]

casos_eval = [
    {
        "id": "matricula-001",
        "question": "Tres campus con más pagos pendientes",
        "expected_sql_contains": ["GROUP BY campus", "LIMIT 3"],
        "expected_result": [
            {"campus": "Norte", "total_pendiente": 800.0},
            {"campus": "Centro", "total_pendiente": 250.0},
            {"campus": "Sur", "total_pendiente": 120.0},
        ],
    }
]

for pregunta in preguntas:
    print("\\n---")
    pprint(responder(pregunta), width=88)

print("\\n--- evaluación")
pprint(evaluar_caso(casos_eval[0]), width=88)

Salida esperada aproximada:

---
pregunta: Tres campus con más pagos pendientes
rows:
  Norte  -> 800.0
  Centro -> 250.0
  Sur    -> 120.0

---
pregunta: Importe pendiente por titulación
rows:
  Informática -> 800.0
  Diseño      -> 250.0
  Matemáticas -> 120.0

---
evaluación:
  pass: True
  trace:
    row_count: 3
    query_plan:
      - SCAN pagos
      - USE TEMP B-TREE FOR GROUP BY

Prueba tres cambios:

Quita el LIMIT de una consulta y observa cómo el validador lo añade.
Cambia pagos por una tabla inexistente y comprueba el error.
Añade una columna sensible inventada y decide si debería estar en SCHEMA.
Cambia el resultado esperado del caso de evaluación y mira cómo falla el harness.

Cómo encaja todo

graph TD
    subgraph "Capítulo 12: datos y SQL"
        TSQL["Text-to-SQL"]
        INTENT["Intención de datos"]
        SCHEMA["Schema linking"]
        SEM["Capa semántica"]
        PERMS["Permisos y roles"]
        DIALECT["Dialecto SQL"]
        SQL["SQL candidato"]
        VALID["Validación"]
        PLAN["Query plan"]
        EXEC["Ejecución limitada"]
        RESULT["Resultado tabular"]
        TRACE["Traza"]
        EVAL["Evaluación SQL"]
    end
    subgraph "Viene de antes"
        API["Function calling (F4C2)"]
        STRUCT["Structured outputs (F4C2)"]
        VECTOR["Búsqueda híbrida (F4C8)"]
        RAG["RAG básico (F4C9)"]
        RAGEVAL["Evaluar RAG (F4C10)"]
        AGENTIC["Agentic RAG (F4C11)"]
    end
    subgraph "Sigue después"
        LAB["Laboratorio mínimo (F4C13)"]
        RECAP["Recapitulación (F4C14)"]
        AGENTES["Agentes con herramientas (F5)"]
        OPERAR["Operación y observabilidad (F6)"]
        DATOS["Ciencia de datos (F8)"]
    end

    API -->|"declara herramienta"| TSQL
    STRUCT -->|"estructura argumentos"| TSQL
    VECTOR -->|"recupera esquema"| SCHEMA
    RAG -->|"recupera documentación"| SEM
    AGENTIC -->|"decide usar"| TSQL
    TSQL -->|"parte de"| INTENT
    INTENT -->|"necesita"| SCHEMA
    SCHEMA -->|"alimenta"| SQL
    SEM -->|"corrige significado"| SQL
    PERMS -->|"acota superficie"| VALID
    DIALECT -->|"marca sintaxis"| VALID
    SQL -->|"pasa por"| VALID
    VALID -->|"revisa coste"| PLAN
    PLAN -->|"autoriza"| EXEC
    EXEC -->|"devuelve"| RESULT
    RESULT -->|"se explica con"| TRACE
    TRACE -->|"alimenta"| EVAL
    RAGEVAL -->|"inspira métricas"| EVAL
    EVAL -->|"se practica en"| LAB
    TSQL -->|"se resume en"| RECAP
    TSQL -->|"será herramienta de"| AGENTES
    TRACE -->|"pasa a"| OPERAR
    RESULT -->|"conecta con"| DATOS

    style TSQL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style INTENT fill:#F5F5F5,stroke:#000000,stroke-width:2
    style SCHEMA fill:#F5F5F5,stroke:#000000,stroke-width:2
    style SEM fill:#F5F5F5,stroke:#000000,stroke-width:2
    style PERMS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style DIALECT fill:#F5F5F5,stroke:#000000,stroke-width:2
    style SQL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style VALID fill:#111111,stroke:#000000,stroke-width:2,color:#FFFFFF
    style PLAN fill:#F5F5F5,stroke:#000000,stroke-width:2
    style EXEC fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RESULT fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TRACE fill:#F5F5F5,stroke:#000000,stroke-width:2
    style EVAL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style API stroke-dasharray: 5 5
    style STRUCT stroke-dasharray: 5 5
    style VECTOR stroke-dasharray: 5 5
    style RAG stroke-dasharray: 5 5
    style RAGEVAL stroke-dasharray: 5 5
    style AGENTIC stroke-dasharray: 5 5
    style LAB stroke-dasharray: 5 5
    style RECAP stroke-dasharray: 5 5
    style AGENTES stroke-dasharray: 5 5
    style OPERAR stroke-dasharray: 5 5
    style DATOS stroke-dasharray: 5 5

Vocabulario aprendido

Término	Definición
Text-to-SQL	Traducción controlada de una pregunta humana a una consulta SQL ejecutable.
SQL	Lenguaje declarativo para consultar y transformar datos relacionales.
Tabla	Conjunto de filas y columnas.
Fila	Registro individual dentro de una tabla.
Columna	Atributo de una tabla, como fecha, estado o importe.
Clave primaria	Columna o conjunto de columnas que identifica una fila única.
Clave foránea	Columna que conecta una tabla con otra.
JOIN	Unión entre tablas mediante una relación, normalmente una clave.
Cardinalidad	Número aproximado de filas que participan en una operación.
Índice	Estructura que ayuda a encontrar filas sin recorrer toda la tabla.
Schema linking	Vincular palabras de la pregunta con tablas, columnas, claves y valores.
Dialecto SQL	Variante de SQL de un motor concreto.
Semantic layer	Capa de métricas y reglas de negocio compartidas.
Dry-run	Comprobación previa de una consulta antes de ejecutarla plenamente.
Query plan	Plan interno de ejecución calculado por la base de datos.
Read-only	Conexión que solo permite lectura.
Row-level security	Regla que limita qué filas puede ver cada rol o persona.
Execution accuracy	Métrica que evalúa si el resultado producido por la consulta es correcto.
Result-set match	Comparación entre resultado esperado y resultado devuelto.
Row limit	Límite máximo de filas que puede devolver una consulta.
Traza SQL	Registro de pregunta, SQL, usuario, tablas, tiempo, resultado y errores.

Dónde solía tropezar yo

Error	Por qué es un error	Antídoto
Confundir SQL válido con respuesta correcta	Una consulta puede ejecutar y aun así calcular otra cosa.	Evaluar resultado, tablas usadas y definición de negocio.
Meter todo el esquema en el prompt	Con esquemas grandes sube el coste y entra ruido.	Recuperar solo tablas, columnas y ejemplos relevantes.
Olvidar la capa semántica	“Ingresos”, “activo” o “pendiente” no significan lo mismo en cada empresa.	Declarar métricas y definiciones fuera del prompt.
Contar filas cuando quería entidades	`COUNT(*)` puede contar pagos, no alumnos.	Revisar cardinalidad y usar `COUNT(DISTINCT ...)` cuando proceda.
Ignorar el plan de consulta	Una query correcta puede ser demasiado cara.	Revisar `EXPLAIN`, cardinalidad, índices y límites.
Mezclar dialectos	Una función válida en un motor puede fallar en otro.	Pasar `dialect` en el contrato y validar contra ese motor.
Ejecutar antes de validar	La base de datos no sabe qué pretendía el usuario.	Parsear, limitar, revisar permisos y hacer dry-run.
Medir solo exact match	SQL distinto puede producir el mismo resultado correcto.	Combinar execution accuracy, result-set match y revisión por componentes.
No registrar trazas	No puedes explicar por qué salió un número.	Guardar pregunta, esquema, SQL, resultados, latencia y versión.

Antes de pasar página

En resumen

Idea fuerza	Detalle
Text-to-SQL no es una query suelta.	Es una cadena con intención, esquema, SQL, validación, ejecución, resultado y traza.
El esquema manda.	Si el sistema no entiende tablas, columnas, claves y valores, generará consultas frágiles.
La semántica evita números falsos.	Las métricas de negocio deben estar definidas fuera del prompt.
La cardinalidad cambia respuestas.	Contar filas, eventos o entidades no es lo mismo.
El plan importa.	Una consulta correcta puede ser demasiado cara para ejecutarse en vivo.
La validación es obligatoria.	Solo lectura, límites, permisos, dialecto, timeout y trazas antes de ejecutar.
La evaluación mira resultados.	Exact match ayuda, pero execution accuracy y result-set match son centrales.

Para saber más

DuckDB. (2026). Python API. Documentación oficial

LangChain. (2026). Build a SQL agent. Documentación oficial

Lei, F. et al. (2024). Spider 2.0: Evaluating Language Models on Real-World Enterprise Text-to-SQL Workflows. arXiv

Li, J. et al. (2023). Can LLM Already Serve as A Database Interface? A BIg Bench for Large-Scale Database Grounded Text-to-SQLs. arXiv

LlamaIndex. (2026). NL SQL table query engine. Documentación oficial

OpenAI. (2026). Function calling. Documentación oficial

OpenAI. (2026). Structured model outputs. Documentación oficial

Scholak, T., Schucher, N. y Bahdanau, D. (2021). PICARD: Parsing Incrementally for Constrained Auto-Regressive Decoding from Language Models. Proceedings of EMNLP, 9895-9901. DOI

SQLGlot. (2026). Python SQL parser and transpiler. Documentación

Vanna AI. (2026). Vanna 2.0: Turn Questions into Data Insights. GitHub

Wang, B., Shin, R., Liu, X., Polozov, O. y Richardson, M. (2020). RAT-SQL: Relation-Aware Schema Encoding and Linking for Text-to-SQL Parsers. Proceedings of ACL, 7567-7578. DOI

Yu, T. et al. (2018). Spider: A Large-Scale Human-Labeled Dataset for Complex and Cross-Domain Semantic Parsing and Text-to-SQL Task. Proceedings of EMNLP, 3911-3921. ACL Anthology

Notas

Yu, T. et al. (2018). Spider: A Large-Scale Human-Labeled Dataset for Complex and Cross-Domain Semantic Parsing and Text-to-SQL Task. Proceedings of EMNLP, 3911-3921. ACL Anthology. ↩
Wang, B., Shin, R., Liu, X., Polozov, O. y Richardson, M. (2020). RAT-SQL: Relation-Aware Schema Encoding and Linking for Text-to-SQL Parsers. Proceedings of ACL, 7567-7578. DOI. ↩
Scholak, T., Schucher, N. y Bahdanau, D. (2021). PICARD: Parsing Incrementally for Constrained Auto-Regressive Decoding from Language Models. Proceedings of EMNLP, 9895-9901. DOI. ↩
Li, J. et al. (2023). Can LLM Already Serve as A Database Interface? A BIg Bench for Large-Scale Database Grounded Text-to-SQLs. arXiv. ↩
Lei, F. et al. (2024). Spider 2.0: Evaluating Language Models on Real-World Enterprise Text-to-SQL Workflows. arXiv. ↩
LangChain. (2026). Build a SQL agent. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
LlamaIndex. (2026). NL SQL table query engine. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
OpenAI. (2026). Function calling. Documentación oficial. OpenAI. (2026). Structured model outputs. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
SQLGlot. (2026). Python SQL parser and transpiler. Documentación. Consultado el 26 de mayo de 2026. ↩
DuckDB. (2026). Python API. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
Vanna AI. (2026). Vanna 2.0: Turn Questions into Data Insights. GitHub. Consultado el 26 de mayo de 2026. El repositorio público consultado aparece como archivado el 29 de marzo de 2026. ↩

Capítulo 13

Facsímil 4 · La caja de herramientas

Capítulo 13: Laboratorio mínimo: notebooks, evals y trazas

El lugar donde una demo se vuelve discutible

Una demo sirve para ver una posibilidad. Un laboratorio sirve para decidir si esa posibilidad aguanta un poco de realidad.

En este facsímil hemos hablado de APIs, modelos locales, tokens, costes, embeddings, RAG, evaluación, GraphRAG y Text-to-SQL. Todo eso puede quedarse en palabras si no lo llevamos a una mesa de trabajo mínima: datos pequeños, código ejecutable, métricas claras, trazas legibles y una decisión final.

Este capítulo es ese puente. No vamos a montar una plataforma industrial. Vamos a construir lo justo para que otra persona pueda ejecutar, revisar, criticar y mejorar lo que hicimos. Ese es el gesto profesional: no pedir confianza; dejar evidencia.

Qué no es un laboratorio

Un laboratorio no es un notebook que funciona una vez en tu máquina y queda abandonado. Tampoco es una captura bonita de una respuesta acertada. Y no es una colección de librerías instaladas sin una pregunta clara.

Un laboratorio tampoco sustituye a producción. En producción aparecen permisos reales, usuarios, colas, coste variable, cambios de datos y mantenimiento. El laboratorio no pretende resolver todo eso. Pretende descubrir antes qué merece pasar a una fase más seria.

Si no sabes qué pregunta estás probando, qué métrica mirarás y qué harás si sale mal, todavía no tienes laboratorio. Tienes una exploración. Puede ser útil, pero no permite decidir.

Qué sí debería dejar

Un laboratorio mínimo debe dejar cinco artefactos:

Artefacto	Qué contiene	Por qué importa
Dataset	Casos de prueba con respuesta o fuente esperada.	Permite repetir la evaluación.
Runner	Código que ejecuta el sistema sobre esos casos.	Evita evaluar a mano caso por caso.
Métricas	Números que resumen el comportamiento.	Permite comparar versiones.
Trazas	Pasos internos de cada ejecución.	Permite depurar por qué falló.
Decisión	Pasar, parar, cambiar o medir más.	Evita terminar con “parece que va bien”.

Los notebooks son útiles porque mezclan explicación, código y resultados. El formato Jupyter se basa en documentos JSON con celdas, salidas y metadatos, lo que permite guardar no solo código, sino también el contexto de ejecución.¹ Esa flexibilidad es estupenda para aprender, pero también exige disciplina: fijar datos, ordenar celdas, limpiar salidas innecesarias y convertir lo aprendido en scripts o tests cuando el experimento empieza a importar.

En observabilidad, OpenTelemetry describe una traza como una operación formada por spans, donde cada span representa una unidad de trabajo con contexto y atributos.² Nosotros haremos una versión casera: una lista de pasos con nombre, entrada, salida y metadatos. No será una herramienta de producción, pero enseñará la forma mental correcta.

Estado de herramientas con fecha de corte

Fecha de corte: 26 de mayo de 2026.
Fuentes consultadas ese día: documentación de Jupyter nbformat, OpenTelemetry Tracing API, OpenAI Graders, Ragas metrics, LangSmith RAG evaluation y Arize Phoenix evaluation.

OpenAI documenta graders como evaluadores usados en evals y fine-tuning, incluyendo validación de graders y ejemplos de evaluadores basados en modelos.³ Ragas organiza métricas para aplicaciones RAG, entre ellas context precision y faithfulness.⁴ LangSmith estructura la evaluación de RAG alrededor de corrección, relevancia, groundedness y relevancia de documentos.⁵

Phoenix separa evaluación de retrieval y evaluación de respuesta, y permite trabajar con trazas para analizar qué documentos se recuperaron y cómo se generó la respuesta.⁶ Su documentación de evaluación distingue evaluadores deterministas y evaluadores con modelo, y los presenta como forma de detectar regresiones y comparar cambios.⁷

La lección estable no depende de una marca concreta: una evaluación útil separa dataset, ejecución, métrica, trazas y decisión.

Anatomía de un laboratorio mínimo

La figura puede leerse de izquierda a derecha: parto de casos, ejecuto variantes, observo resultados y decido. Debajo aparecen las tres piezas que suelen faltar en las demos: manifest, trazas y gate.

Laboratorio

Un laboratorio, dentro de este libro, es una práctica guiada para poner en juego los conceptos del facsímil. Aquí no buscamos impresionar con una respuesta aislada. Buscamos construir algo pequeño que se pueda ejecutar, medir, explicar y corregir.

En este laboratorio vamos a tocar cuatro zonas del facsímil:

Del capítulo 2: contratos, tools y salidas estructuradas.
Del capítulo 3: coste, contexto y disciplina de ejecución.
De los capítulos 7, 8, 9 y 10: embeddings, búsqueda, RAG y evaluación.
Del capítulo 12: herramientas de datos, SQL, permisos, trazas y validación.

Los dos retos dejan solución completa. La idea no es esconder la respuesta, sino enseñar cómo piensa alguien que quiere llevar una idea desde “parece que funciona” hasta “puedo defender esta decisión”.

El kit real está en:

kit/

El capítulo muestra la lógica paso a paso. El kit deja los artefactos ejecutables: datos, contratos, scripts, trazas, gates y checker.

Reto 1: evaluar un mini RAG con trazas reproducibles

Contexto

Imagina que una escuela quiere un asistente interno para responder dudas administrativas. Hay documentos vigentes, documentos antiguos y preguntas donde el sistema debería decir “no tengo evidencia suficiente”.

Un RAG básico podría responder muy bien en una demo. Pero antes de confiar en él necesitamos saber tres cosas: si recupera el documento correcto, si evita documentos no vigentes y si deja una traza para depurar los fallos.

Objetivo

Construir un harness mínimo de evaluación RAG con Python puro. Debe ejecutar un conjunto de casos, recuperar documentos, decidir una respuesta sencilla, calcular métricas y guardar trazas.

Esto sale del capítulo 09, donde construimos RAG como recuperación más generación; del capítulo 10, donde medimos retrieval y groundedness; y del capítulo 14, donde decimos que una solución sin trazas sigue siendo una demo.

En el kit se ejecuta así:

# Descomprime el ZIP del capítulo y ejecuta estos comandos dentro de esa carpeta
python3 ops/evaluate_mini_rag.py --write
python3 -m json.tool output/ci_rag_gate.json
cat output/rag_decision.md

Material base

Tendremos cinco documentos:

ID	Estado	Texto
`matricula_vigente`	vigente	La matrícula ordinaria se puede modificar hasta el 15 de septiembre.
`matricula_antigua`	sustituido	La matrícula ordinaria se podía modificar hasta el 1 de septiembre.
`becas_vigente`	vigente	Las becas internas se revisan en dos fases: documentación y entrevista.
`pagos_vigente`	vigente	Los pagos pendientes se consultan en el panel económico por campus.
`soporte_vigente`	vigente	Las incidencias de acceso se atienden desde el portal de soporte.

Y cuatro casos de evaluación:

Caso	Pregunta	Documento esperado	Debe responder
`c1`	¿Hasta cuándo puedo modificar la matrícula?	`matricula_vigente`	Sí
`c2`	¿Cómo se revisan las becas internas?	`becas_vigente`	Sí
`c3`	¿Cuántos pagos pendientes hay por campus?	`pagos_vigente`	No con RAG textual
`c4`	¿Cuál es el horario de cafetería?	Ninguno	No

El tercer caso es importante. El documento habla de dónde consultar pagos, pero no contiene el número. Una respuesta honesta debe reconocer que necesita una herramienta de datos.

Enunciado

Representa documentos y casos como estructuras de datos.
Implementa recuperación léxica con filtro de documentos vigentes.
Guarda una traza con spans para cada caso.
Calcula Hit@1, MRR, tasa de abstención correcta y cobertura de trazas.
Decide si el RAG puede avanzar o qué habría que mejorar.

Resolución paso a paso

Primero hacemos explícito qué medimos.

\operatorname{Hit@1} = \frac{\text{casos donde el primer documento es el esperado}} {\text{casos con documento esperado}}

Símbolo	Significado	En este reto
Hit@1	Acierto en primera posición	Si `matricula_vigente` sale primero en `c1`.
Casos con documento esperado	Preguntas que sí tienen fuente textual	`c1`, `c2`, `c3`.
Documento esperado	Fuente que debería aparecer	Campo `expected_doc`.

MRR mide en qué posición aparece el primer resultado correcto:

\operatorname{MRR} = \frac{1}{N}\sum_{i=1}^{N}\frac{1}{\operatorname{rank}_i}

Símbolo	Significado	En este reto
$N$	Número de casos con fuente esperada	Tres casos.
$\operatorname{rank}_i$	Posición del documento esperado	1 si sale primero, 2 si sale segundo.
$\frac{1}{\operatorname{rank}_i}$	Premio por encontrar pronto	1.0 si sale primero, 0.5 si sale segundo.

Ahora programamos el laboratorio.

from collections import Counter
import json
import math
import re
import time
import uuid


DOCUMENTS = [
    {
        "id": "matricula_vigente",
        "status": "vigente",
        "text": "La matrícula ordinaria se puede modificar hasta el 15 de septiembre.",
    },
    {
        "id": "matricula_antigua",
        "status": "sustituido",
        "text": "La matrícula ordinaria se podía modificar hasta el 1 de septiembre.",
    },
    {
        "id": "becas_vigente",
        "status": "vigente",
        "text": "Las becas internas se revisan en dos fases: documentación y entrevista.",
    },
    {
        "id": "pagos_vigente",
        "status": "vigente",
        "text": "Los pagos pendientes se consultan en el panel económico por campus.",
    },
    {
        "id": "soporte_vigente",
        "status": "vigente",
        "text": "Las incidencias de acceso se atienden desde el portal de soporte.",
    },
]

CASES = [
    {
        "id": "c1",
        "question": "¿Hasta cuándo puedo modificar la matrícula?",
        "expected_doc": "matricula_vigente",
        "should_answer": True,
    },
    {
        "id": "c2",
        "question": "¿Cómo se revisan las becas internas?",
        "expected_doc": "becas_vigente",
        "should_answer": True,
    },
    {
        "id": "c3",
        "question": "¿Cuántos pagos pendientes hay por campus?",
        "expected_doc": "pagos_vigente",
        "should_answer": False,
        "reason": "La pregunta pide un número vivo, no una explicación documental.",
    },
    {
        "id": "c4",
        "question": "¿Cuál es el horario de cafetería?",
        "expected_doc": None,
        "should_answer": False,
        "reason": "No hay documento sobre cafetería.",
    },
]

STOPWORDS = {
    "a",
    "al",
    "como",
    "con",
    "cual",
    "cuando",
    "cuantos",
    "de",
    "del",
    "desde",
    "donde",
    "el",
    "en",
    "es",
    "hasta",
    "la",
    "las",
    "lo",
    "los",
    "me",
    "mi",
    "no",
    "por",
    "puedo",
    "que",
    "se",
    "un",
    "una",
    "y",
}


def tokens(text):
    return [
        token
        for token in re.findall(r"[a-záéíóúñ0-9]+", text.lower())
        if token not in STOPWORDS
    ]


def vector(text):
    return Counter(tokens(text))


def score(query, document):
    q = vector(query)
    d = vector(document["text"])
    overlap = sum(min(q[t], d[t]) for t in q)
    if overlap == 0:
        return 0.0
    return overlap / math.sqrt(sum(v * v for v in d.values()))


def trace_span(trace, name, **attrs):
    trace["spans"].append(
        {
            "name": name,
            "timestamp_ms": int(time.time() * 1000),
            "attrs": attrs,
        }
    )


def retrieve(case, top_k=2):
    trace = {"trace_id": str(uuid.uuid4()), "case_id": case["id"], "spans": []}
    trace_span(trace, "input", question=case["question"])

    candidates = [doc for doc in DOCUMENTS if doc["status"] == "vigente"]
    trace_span(trace, "filter_documents", candidates=[doc["id"] for doc in candidates])

    ranked = sorted(
        ((score(case["question"], doc), doc["id"], doc["text"]) for doc in candidates),
        reverse=True,
    )
    ranked = [item for item in ranked if item[0] > 0][:top_k]
    trace_span(trace, "retrieve", results=[doc_id for _, doc_id, _ in ranked])

    answerable = case["should_answer"] and bool(ranked)
    if not answerable:
        answer = "No tengo evidencia suficiente para responder con este RAG."
    else:
        answer = ranked[0][2]
    trace_span(trace, "generate", answer=answer, answerable=answerable)

    return {
        "case_id": case["id"],
        "expected_doc": case["expected_doc"],
        "should_answer": case["should_answer"],
        "ranked_docs": [doc_id for _, doc_id, _ in ranked],
        "answer": answer,
        "trace": trace,
    }


def reciprocal_rank(expected_doc, ranked_docs):
    if expected_doc is None:
        return None
    if expected_doc not in ranked_docs:
        return 0.0
    return 1.0 / (ranked_docs.index(expected_doc) + 1)


def evaluate(results):
    with_expected = [r for r in results if r["expected_doc"] is not None]
    hit_at_1 = sum(
        r["ranked_docs"][:1] == [r["expected_doc"]] for r in with_expected
    ) / len(with_expected)

    rr_values = [reciprocal_rank(r["expected_doc"], r["ranked_docs"]) for r in with_expected]
    mrr = sum(rr_values) / len(rr_values)

    abstention_ok = sum(
        (not r["should_answer"]) == r["answer"].startswith("No tengo evidencia")
        for r in results
    ) / len(results)

    trace_ok = sum(len(r["trace"]["spans"]) >= 4 for r in results) / len(results)

    return {
        "hit@1": round(hit_at_1, 2),
        "mrr": round(mrr, 2),
        "abstention_ok": round(abstention_ok, 2),
        "trace_ok": round(trace_ok, 2),
    }


results = [retrieve(case) for case in CASES]
metrics = evaluate(results)

print("Métricas")
print(json.dumps(metrics, ensure_ascii=False, indent=2))

print("\nTrazas resumidas")
for result in results:
    span_names = [span["name"] for span in result["trace"]["spans"]]
    print(result["case_id"], result["ranked_docs"], span_names)

Salida esperada

Métricas
{
  "hit@1": 1.0,
  "mrr": 1.0,
  "abstention_ok": 1.0,
  "trace_ok": 1.0
}

Trazas resumidas
c1 ['matricula_vigente'] ['input', 'filter_documents', 'retrieve', 'generate']
c2 ['becas_vigente'] ['input', 'filter_documents', 'retrieve', 'generate']
c3 ['pagos_vigente'] ['input', 'filter_documents', 'retrieve', 'generate']
c4 [] ['input', 'filter_documents', 'retrieve', 'generate']

Solución

El resultado pasa el gate mínimo:

Métrica	Valor esperado	Lectura
Hit@1	1.0	Cuando hay documento esperado, aparece primero.
MRR	1.0	El documento esperado aparece en la primera posición.
Abstención correcta	1.0	El sistema no responde cuando no debe.
Trazas completas	1.0	Cada caso deja pasos mínimos para depurar.

El caso c3 enseña la parte más importante: recuperar pagos_vigente no autoriza inventar un número. El documento sirve para saber dónde consultar pagos. La pregunta pide una cifra viva, así que la respuesta correcta para este RAG textual es abstenerse y derivar a una herramienta de datos.

Por qué funciona

Este reto junta varias piezas del facsímil:

Capítulo 08: usamos filtro de metadatos para evitar documentos sustituidos.
Capítulo 09: separamos recuperación y generación.
Capítulo 10: medimos retrieval y abstención.
Capítulo 12: reconocemos cuándo una pregunta documental pasa a ser una pregunta de datos.

La clave es que el laboratorio no solo mide respuestas. Mide piezas: si recuperó, si debía responder, si dejó traza y si el resultado permite decidir.

Cómo explicarlo a otra persona

"No hemos preguntado si el asistente suena bien. Hemos preparado cuatro casos, sabemos qué fuente debería recuperar, comprobamos si responde solo cuando toca y guardamos los pasos. Si falla, sabremos si falló buscando, filtrando o decidiendo responder."

Variaciones

Cambia el estado de matricula_antigua a vigente y observa si aparece ruido.
Añade una métrica precision@2.
Añade un campo source_status en la traza de retrieval.
Añade un caso donde el documento correcto sale segundo y revisa cómo baja MRR.

Reto 2: decidir ruta entre RAG, SQL, clasificador y cálculo

Contexto

Ahora queremos probar una idea más cercana a producto. Una misma interfaz recibe preguntas distintas: algunas son documentales, otras piden datos, otras clasifican tickets y otras son cálculos exactos.

No queremos un agente complejo todavía. Queremos un laboratorio mínimo que enrute cada caso a la herramienta adecuada y mida si la decisión fue correcta. Esto prepara el paso al facsímil 5, donde sí hablaremos de orquestación con más profundidad.

Objetivo

Construir un router pequeño con cuatro rutas:

Ruta	Uso
`rag`	Preguntas sobre documentos.
`sql`	Preguntas sobre datos tabulares.
`classifier`	Clasificación estructurada de tickets.
`code`	Cálculo determinista sin modelo.

El sistema debe devolver una salida estructurada y una traza. La evaluación debe medir si eligió la ruta correcta, si produjo el resultado esperado y si dejó evidencia suficiente.

En el kit se ejecuta así:

# Descomprime el ZIP del capítulo y ejecuta estos comandos dentro de esa carpeta
python3 ops/evaluate_router.py --write
python3 -m json.tool output/ci_router_gate.json
cat output/router_decision.md

Material base

Casos:

Caso	Entrada	Ruta esperada
`r1`	¿Hasta cuándo puedo modificar la matrícula?	`rag`
`r2`	¿Cuántos pagos pendientes hay por campus?	`sql`
`r3`	Clasifica: no puedo entrar en mi cuenta	`classifier`
`r4`	Suma 230 y 515	`code`

Este reto fuerza una idea del capítulo 01: no todo se arregla con la misma herramienta.

Enunciado

Define casos con ruta esperada y resultado esperado.
Implementa cuatro herramientas mínimas.
Implementa un router explicable.
Registra spans route, tool y evaluate.
Calcula route_accuracy, task_pass_rate y trace_complete_rate.
Decide si el router puede avanzar al laboratorio del capítulo 14 o debe corregirse.

Resolución paso a paso

Primero definimos qué significa pasar:

\operatorname{route\_accuracy} = \frac{\text{casos con ruta correcta}}{\text{casos totales}}

\operatorname{task\_pass\_rate} = \frac{\text{casos con resultado correcto}}{\text{casos totales}}

Métrica	Pregunta que responde	Por qué importa
Route accuracy	¿Elegimos la herramienta correcta?	Un buen resultado por casualidad no basta.
Task pass rate	¿El caso terminó bien?	Mide utilidad visible.
Trace complete rate	¿Podemos depurar cada caso?	Sin traza, no hay aprendizaje reproducible.

Ahora el código.

import json
import re
import sqlite3
import time
import uuid


DOCS = {
    "matricula": "La matrícula ordinaria se puede modificar hasta el 15 de septiembre.",
    "becas": "Las becas internas se revisan en dos fases.",
}

CASES = [
    {
        "id": "r1",
        "input": "¿Hasta cuándo puedo modificar la matrícula?",
        "expected_route": "rag",
        "expected_contains": "15 de septiembre",
    },
    {
        "id": "r2",
        "input": "¿Cuántos pagos pendientes hay por campus?",
        "expected_route": "sql",
        "expected_contains": "Norte: 2",
    },
    {
        "id": "r3",
        "input": "Clasifica: no puedo entrar en mi cuenta",
        "expected_route": "classifier",
        "expected_contains": "acceso",
    },
    {
        "id": "r4",
        "input": "Suma 230 y 515",
        "expected_route": "code",
        "expected_contains": "745",
    },
]


def new_trace(case_id):
    return {"trace_id": str(uuid.uuid4()), "case_id": case_id, "spans": []}


def span(trace, name, **attrs):
    trace["spans"].append(
        {"name": name, "timestamp_ms": int(time.time() * 1000), "attrs": attrs}
    )


def route(text):
    lower = text.lower()
    if "suma" in lower or re.search(r"\d+\s+y\s+\d+", lower):
        return "code", "la entrada pide cálculo exacto"
    if "cuántos" in lower or "pagos pendientes" in lower:
        return "sql", "la entrada pide datos agregados"
    if "clasifica" in lower:
        return "classifier", "la entrada pide etiqueta estructurada"
    return "rag", "la entrada pregunta por documentación"


def tool_rag(text):
    if "matrícula" in text.lower() or "matricula" in text.lower():
        return {"answer": DOCS["matricula"], "evidence": ["matricula"]}
    return {"answer": "No tengo evidencia suficiente.", "evidence": []}


def tool_sql(_text):
    con = sqlite3.connect(":memory:")
    con.execute("CREATE TABLE pagos (campus TEXT, estado TEXT)")
    con.executemany(
        "INSERT INTO pagos VALUES (?, ?)",
        [
            ("Norte", "pendiente"),
            ("Norte", "pendiente"),
            ("Sur", "pagado"),
            ("Centro", "pendiente"),
        ],
    )
    rows = con.execute("""
        SELECT campus, COUNT(*) AS pagos
        FROM pagos
        WHERE estado = 'pendiente'
        GROUP BY campus
        ORDER BY pagos DESC, campus ASC
    """).fetchall()
    answer = "; ".join(f"{campus}: {count}" for campus, count in rows)
    return {"answer": answer, "evidence": ["sql:pagos"]}


def tool_classifier(text):
    lower = text.lower()
    if "entrar" in lower or "cuenta" in lower:
        category = "acceso"
    elif "factura" in lower:
        category = "facturacion"
    else:
        category = "general"
    return {"answer": json.dumps({"categoria": category}, ensure_ascii=False), "evidence": ["rules:ticket"]}


def tool_code(text):
    numbers = [int(n) for n in re.findall(r"\d+", text)]
    return {"answer": str(sum(numbers)), "evidence": ["python:sum"]}


TOOLS = {
    "rag": tool_rag,
    "sql": tool_sql,
    "classifier": tool_classifier,
    "code": tool_code,
}


def run_case(case):
    trace = new_trace(case["id"])
    selected_route, reason = route(case["input"])
    span(trace, "route", selected_route=selected_route, reason=reason)

    result = TOOLS[selected_route](case["input"])
    span(trace, "tool", route=selected_route, evidence=result["evidence"])

    route_ok = selected_route == case["expected_route"]
    task_ok = case["expected_contains"] in result["answer"]
    span(trace, "evaluate", route_ok=route_ok, task_ok=task_ok)

    return {
        "case_id": case["id"],
        "route": selected_route,
        "answer": result["answer"],
        "route_ok": route_ok,
        "task_ok": task_ok,
        "trace": trace,
    }


def summarize(results):
    total = len(results)
    return {
        "route_accuracy": sum(r["route_ok"] for r in results) / total,
        "task_pass_rate": sum(r["task_ok"] for r in results) / total,
        "trace_complete_rate": sum(len(r["trace"]["spans"]) == 3 for r in results) / total,
    }


results = [run_case(case) for case in CASES]
metrics = summarize(results)

for result in results:
    print(result["case_id"], result["route"], result["answer"])

print(json.dumps(metrics, indent=2))

Salida esperada

r1 rag La matrícula ordinaria se puede modificar hasta el 15 de septiembre.
r2 sql Norte: 2; Centro: 1
r3 classifier {"categoria": "acceso"}
r4 code 745
{
  "route_accuracy": 1.0,
  "task_pass_rate": 1.0,
  "trace_complete_rate": 1.0
}

Solución

El router pasa el gate mínimo:

Caso	Ruta elegida	Por qué es correcta
`r1`	`rag`	La respuesta vive en un documento.
`r2`	`sql`	La pregunta pide una agregación sobre datos.
`r3`	`classifier`	La salida esperada es una categoría estructurada.
`r4`	`code`	Es un cálculo exacto; no necesita modelo.

El resultado más valioso quizá sea r4. Nos recuerda que la caja de herramientas incluye no usar IA generativa cuando una operación determinista resuelve mejor.

Por qué funciona

Este reto junta casi todo el facsímil:

Capítulo 01: elegimos intervención según el cuello real.
Capítulo 02: devolvemos salidas estructuradas en el clasificador.
Capítulo 09: usamos RAG solo para documentación.
Capítulo 12: usamos SQL cuando la respuesta está en datos.
Capítulo 14: dejamos trazas y métricas antes de confiar.

La frontera con agentes está muy cerca, pero todavía no la cruzamos del todo. Aquí el router es simple y explicable. Eso es una virtud: si falla, sabemos dónde mirar.

Cómo explicarlo a otra persona

"Hemos construido una ventanilla que no responde todo igual. Si la pregunta va de documentos, busca documentos. Si pide datos, consulta una tabla. Si pide clasificación, devuelve una categoría. Si pide una suma, usa código. Además, deja una traza para saber qué ruta eligió y si acertó."

Variaciones

Añade una ruta human_review para preguntas ambiguas.
Añade un presupuesto máximo de latencia por ruta.
Añade un caso que parezca documental pero necesite SQL.
Cambia el router para devolver también una confianza y decide cuándo pedir aclaración.

Validar la entrega

La solución de referencia se valida con:

# Descomprime el ZIP del capítulo y ejecuta estos comandos dentro de esa carpeta
python3 ops/check_student_submission.py --submission-dir solutions/reference --write

Para una entrega propia:

python3 ops/check_student_submission.py --submission-dir solutions/mi-equipo --write --fail-on-missing

La referencia obtiene 70/70. La carpeta esperada es:

tools-evals-release/
  rag_eval_report.json
  ci_rag_gate.json
  rag_traces.jsonl
  rag_decision.md
  router_eval_report.json
  ci_router_gate.json
  router_traces.jsonl
  router_decision.md

Cierre del laboratorio

Si has trabajado los dos retos, ya has hecho lo esencial de un laboratorio de IA: preparar casos, ejecutar una variante, medir resultados, guardar trazas y convertir los números en una decisión.

El primer reto te obligó a mirar un RAG por dentro. El segundo te obligó a decidir qué herramienta usar para cada tipo de petición. Esa es la idea central del facsímil 4: la caja de herramientas no vale por la cantidad de piezas, sino por saber cuándo usar cada una y cómo comprobar que funcionó.

Lo que viene después, en agentes y orquestación, no cambia esta base. La amplifica. Cuantas más herramientas coordine un sistema, más importante será medir rutas, permisos, coste, evidencia y trazas.

Cómo encaja todo

graph TD
    subgraph "Capítulo 13: laboratorio mínimo"
        LAB["Laboratorio"]
        DATASET["Dataset de evaluación"]
        RUNNER["Runner"]
        METRICS["Métricas"]
        TRACE["Trazas"]
        GATE["Gate de decisión"]
        RAGLAB["Reto RAG"]
        ROUTERLAB["Reto router"]
    end
    subgraph "Viene del facsímil 04"
        API["APIs y contratos (F4C2)"]
        TOKENS["Coste y contexto (F4C3)"]
        VECTOR["Búsqueda híbrida (F4C8)"]
        RAG["RAG básico (F4C9)"]
        RAGEVAL["Evaluar RAG (F4C10)"]
        SQL["Text-to-SQL (F4C12)"]
    end
    subgraph "Sigue después"
        RECAP["Recapitulación (F4C14)"]
        AGENTES["Agentes y orquestación (F5)"]
        OPERAR["Construir y operar (F6)"]
        EVALUAR["Evaluar e interpretar (F7)"]
    end

    LAB -->|"se apoya en"| DATASET
    DATASET -->|"alimenta"| RUNNER
    RUNNER -->|"produce"| METRICS
    RUNNER -->|"registra"| TRACE
    METRICS -->|"activan"| GATE
    TRACE -->|"explica"| GATE
    RAG -->|"se practica en"| RAGLAB
    RAGEVAL -->|"mide"| RAGLAB
    SQL -->|"se practica en"| ROUTERLAB
    API -->|"estructura"| ROUTERLAB
    VECTOR -->|"recupera en"| RAGLAB
    TOKENS -->|"limita"| GATE
    RAGLAB -->|"prepara"| RECAP
    ROUTERLAB -->|"prepara"| AGENTES
    TRACE -->|"prepara"| OPERAR
    METRICS -->|"prepara"| EVALUAR

    style LAB fill:#F5F5F5,stroke:#000000,stroke-width:2
    style DATASET fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RUNNER fill:#F5F5F5,stroke:#000000,stroke-width:2
    style METRICS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TRACE fill:#111111,stroke:#000000,stroke-width:2,color:#FFFFFF
    style GATE fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RAGLAB fill:#F5F5F5,stroke:#000000,stroke-width:2
    style ROUTERLAB fill:#F5F5F5,stroke:#000000,stroke-width:2
    style API stroke-dasharray: 5 5
    style TOKENS stroke-dasharray: 5 5
    style VECTOR stroke-dasharray: 5 5
    style RAG stroke-dasharray: 5 5
    style RAGEVAL stroke-dasharray: 5 5
    style SQL stroke-dasharray: 5 5
    style RECAP stroke-dasharray: 5 5
    style AGENTES stroke-dasharray: 5 5
    style OPERAR stroke-dasharray: 5 5
    style EVALUAR stroke-dasharray: 5 5

Vocabulario aprendido

Término	Definición
Laboratorio	Espacio reproducible para probar una idea con casos, métricas y trazas.
Notebook	Documento ejecutable que mezcla explicación, código, salidas y metadatos.
Eval	Prueba sistemática para medir si un sistema cumple un comportamiento esperado.
Dataset de evaluación	Conjunto de casos con entradas, resultados esperados y criterios de aceptación.
Traza	Registro estructurado de los pasos que produjeron una respuesta.
Span	Paso concreto dentro de una traza.
Hit@k	Indica si el resultado esperado aparece entre los k primeros.
MRR	Media del inverso de la posición del primer resultado correcto.
Gate	Umbral o regla que decide si una variante puede avanzar.
Manifest	Registro de versión, datos, entorno y configuración del experimento.

Dónde solía tropezar yo

Error	Por qué es un error	Antídoto
Confundir notebook con laboratorio	Un notebook puede ejecutar sin dejar decisión ni reproducibilidad.	Añadir dataset, métricas, manifest y conclusión.
Medir solo la respuesta final	No sabes si falló retrieval, routing, herramienta o generación.	Medir por capas y guardar spans.
No incluir casos donde debe abstenerse	El sistema aprende a contestar siempre.	Añadir casos sin evidencia suficiente.
Cambiar prompt y dataset a la vez	Si mejora, no sabes qué lo causó.	Fijar dataset y cambiar una variable por experimento.
No poner gate	La evaluación queda como un informe decorativo.	Definir umbrales antes de mirar resultados.
Olvidar que una regla puede ser mejor	Algunas rutas no necesitan modelo generativo.	Comparar contra SQL, código o reglas simples.

Antes de pasar página

En resumen

Idea fuerza	Detalle
Un laboratorio no es una demo.	Debe dejar casos, métricas, trazas y decisión.
El dataset manda.	Sin casos fijos, no puedes comparar variantes con rigor.
Las trazas explican los fallos.	Permiten saber si falló recuperar, enrutar, ejecutar o evaluar.
La abstención también se evalúa.	Un sistema útil debe saber cuándo no tiene evidencia suficiente.
El router prepara agentes.	Antes de orquestar muchas herramientas, hay que medir rutas simples.
El gate cierra el ciclo.	Una métrica solo sirve si cambia una decisión.

Para saber más

Arize Phoenix. (2026). Evaluate RAG. Documentación oficial

Arize Phoenix. (2026). Evaluation concepts. Documentación oficial

Cormack, G. V., Clarke, C. L. A. y Büttcher, S. (2009). Reciprocal rank fusion outperforms Condorcet and individual rank learning methods. Proceedings of SIGIR, 758-759. DOI

Johnson, J., Douze, M. y Jégou, H. (2019). Billion-scale similarity search with GPUs. IEEE Transactions on Big Data, 7(3), 535-547. DOI

Jupyter. (2026). The Notebook file format. Documentación oficial

LangChain. (2026). Evaluate a RAG application. Documentación oficial

Lewis, P. et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. Advances in Neural Information Processing Systems 33, 9459-9474. NeurIPS

OpenAI. (2026). Graders. Documentación oficial

OpenTelemetry. (2026). Tracing API. Documentación oficial

Ragas. (2026). List of available metrics. Documentación oficial

Robertson, S. y Zaragoza, H. (2009). The probabilistic relevance framework: BM25 and beyond. Foundations and Trends in Information Retrieval, 3(4), 333-389. DOI

Notas

Jupyter. (2026). The Notebook file format. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
OpenTelemetry. (2026). Tracing API. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
OpenAI. (2026). Graders. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
Ragas. (2026). List of available metrics. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
LangChain. (2026). Evaluate a RAG application. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
Arize Phoenix. (2026). Evaluate RAG. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
Arize Phoenix. (2026). Evaluation concepts. Documentación oficial. Consultado el 26 de mayo de 2026. ↩

Capítulo 14

Facsímil 4 · La caja de herramientas

Capítulo 14: Lo que deberías saber: la caja de herramientas

Entrando en el cierre

Este facsímil empezó con una pregunta muy práctica: cuando un sistema de IA no hace lo que necesitas, ¿qué cambias exactamente?

Podrías cambiar el prompt. Podrías exigir una salida estructurada. Podrías añadir documentos con RAG. Podrías conectar una herramienta. Podrías elegir otro modelo. Podrías servirlo en local. Podrías usar embeddings, bases vectoriales, búsqueda híbrida, evaluación, GraphRAG o Text-to-SQL. La caja ya no está vacía.

Pero tener herramientas no significa tener criterio. Un equipo puede complicar una solución hasta que nadie la entiende. También puede quedarse corto y llamar “IA” a una demo que no soporta coste, permisos, datos reales ni evaluación. Este capítulo es una revisión activa: no busca que recuerdes nombres, sino que puedas justificar decisiones.

Si has entendido el facsímil, deberías poder mirar un caso y decir con calma: qué problema hay, qué intervención toca, qué contrato hace falta, qué métrica lo prueba, qué coste introduce y qué pasaría si mañana cambia el dato, el modelo o el usuario.

El capítulo 13 es el lugar donde esto se practica con las manos: notebooks, evaluaciones y trazas. Este capítulo 14 hace otra cosa: te da la brújula para revisar lo construido. Si el laboratorio es el banco de pruebas, esta recapitulación es la conversación técnica posterior: qué hemos aprendido, qué sigue flojo y qué ya podríamos defender delante de otra persona.

Fecha de corte y alcance

Fecha de corte: 26 de mayo de 2026.
Alcance: este cierre resume mecanismos estables del facsímil y referencias ya trabajadas: function calling, salidas estructuradas, prompt caching, model cards, LoRA, QLoRA, RAG, búsqueda vectorial, búsqueda híbrida, evaluación RAG, GraphRAG y Text-to-SQL.

Las herramientas concretas cambiarán. Los nombres de APIs, modelos, precios, runtimes y proveedores se moverán. El criterio que queremos conservar es más estable: separar entrada, contexto, herramienta, pesos, despliegue, evaluación y trazas.

Qué debería llevarse cada perfil

Este libro está escrito para gente curiosa con o sin perfil técnico. Eso no significa que todo el mundo tenga que llevarse lo mismo. Significa que cada persona debería poder salir con una forma más precisa de mirar un sistema de IA.

Perfil	Debería poder hacer al terminar este facsímil	Pregunta que ya no debería aceptar sin más
Ingeniería	Diseñar una arquitectura mínima con contratos, permisos, trazas y evaluación.	“¿Y si le ponemos un agente?”
Datos	Separar pregunta documental, búsqueda semántica, métrica, SQL y validación de resultados.	“¿El modelo ya sabe los datos?”
Producto	Decidir si una función merece prompt, RAG, tool, ajuste, modelo local o nada de IA.	“¿Podemos meter IA aquí?”
Docencia	Explicar cada herramienta con un ejemplo pequeño, una limitación y una prueba.	“¿Esto funciona porque lo he visto en una demo?”
Persona curiosa	Preguntar qué entra, qué sale, qué se mide, qué cuesta y qué pasa cuando no hay evidencia.	“¿La IA lo ha dicho, entonces será verdad?”

El punto común es el criterio. La persona técnica lo aplicará escribiendo código, definiendo contratos o levantando infraestructura. La persona no técnica lo aplicará haciendo mejores preguntas, detectando promesas débiles y pidiendo pruebas antes de confiar.

La brújula: qué quieres cambiar

La pregunta más importante del facsímil no es “¿qué herramienta está de moda?”. Es esta:

¿Dónde está el cuello del problema?

Cada intervención cambia una parte distinta del sistema. Si confundes la parte, puedes trabajar mucho y mejorar poco.

Si el problema está en...	Intervención natural	Qué cambia	Qué no arregla
Instrucción confusa	Prompt, ejemplos, formato	La entrada	Datos que el modelo no tiene.
Salida frágil	JSON schema, parser, validador	El contrato de salida	La calidad del contenido.
Conocimiento cambiante	RAG o herramienta de consulta	El contexto	El razonamiento sobre datos mal definidos.
Estado real	Tool/API/base de datos	La capacidad de actuar o consultar	Permisos, auditoría o validación.
Estilo repetido	Fine-tuning o LoRA	Parte del comportamiento	Información viva.
Coste o latencia	Modelo menor, caché, local, cuantización	Infraestructura y presupuesto	Preguntas mal formuladas.
Recuperación pobre	Embeddings, BM25, híbrida, reranking	Evidencia encontrada	Respuestas sin verificación.
Preguntas relacionales	GraphRAG o Text-to-SQL	Estructura consultable	Ambigüedad de negocio.

OpenAI documenta function calling como forma de describir herramientas con esquemas y recibir argumentos estructurados.¹ Las salidas estructuradas permiten exigir una forma de respuesta compatible con un esquema.² Esos mecanismos no hacen que el modelo “sepa más”; hacen que el sistema sea más gobernable.

La primera habilidad del facsímil es elegir la intervención pequeña que toca. La segunda es saber cuándo esa intervención ya no basta.

El mapa completo de la caja

El mapa tiene una idea central: las herramientas no están alineadas por glamour, sino por responsabilidad. Si una pieza no tiene contrato, métrica ni traza, todavía no es una pieza de ingeniería; es una promesa.

1. Elegir la intervención correcta

En el capítulo 01 aprendimos a no empezar por la herramienta. Antes de decir RAG, fine-tuning, modelo local o agente, hay que diagnosticar el tipo de fallo.

Para recordar. Prompt y ejemplos cambian la entrada. Structured outputs cambian el contrato. RAG cambia el contexto. Una tool cambia la capacidad de consultar o actuar. Fine-tuning y LoRA cambian parte del comportamiento aprendido.³

Caso cercano. Una universidad quiere un asistente que responda dudas de matrícula. Si falla el tono, quizá basta con ejemplos. Si falla porque desconoce normas nuevas, RAG. Si debe consultar expediente, tool. Si debe devolver JSON para abrir un ticket, structured outputs. Si siempre corrige con una rúbrica propia, puede aparecer un ajuste.

Vuelve al capítulo 01 si: no puedes rellenar una tabla de “cambia / sirve cuando / no sirve para” sin mirar apuntes.

2. APIs: mensajes, eventos y contratos

En el capítulo 02 dejamos de tratar la API como una caja negra. Una llamada moderna tiene mensajes, roles, instrucciones, entradas multimodales, parámetros, streaming, tools, esquemas de salida y manejo de errores.

Para recordar. Una API buena no es solo “envío prompt y recibo texto”. Es un contrato entre aplicación y modelo. La aplicación decide qué datos manda, qué formato exige, qué herramientas declara, cómo valida y qué hace si la respuesta no cumple.

Pieza	Pregunta que responde	Error típico
Mensajes	¿Quién dice qué y con qué prioridad?	Mezclar instrucciones de sistema con texto de usuario.
Parámetros	¿Cuánta variación permito?	Tocar temperatura sin evaluación.
Streaming	¿Cómo llega la respuesta?	No diseñar cancelación ni estados parciales.
Tools	¿Qué puede consultar el sistema?	Dejar que el modelo decida permisos.
Structured outputs	¿Qué forma debe tener la salida?	Parsear texto libre con expresiones frágiles.

Caso cercano. Un asistente administrativo clasifica correos y crea tareas. No debería “redactar algo parecido a JSON”. Debería devolver campos obligatorios, categorías permitidas, confianza y razón breve. La aplicación valida antes de crear nada.

Vuelve al capítulo 02 si: no puedes diseñar una llamada completa con entrada, salida estructurada, streaming opcional, tool declarada y errores previstos.

3. Tokens, contexto y caché

En el capítulo 03 aprendimos que el contexto no es gratis. Cada tabla, documento, ejemplo, historial y política consume tokens. El coste no vive solo en la salida.

Para recordar. El contexto es memoria temporal, no memoria perfecta. La caché puede reducir coste si reutilizas prefijos estables, pero no arregla un prompt lleno de ruido. La documentación de prompt caching trata precisamente esta idea: reutilizar segmentos repetidos para optimizar coste y latencia cuando el patrón lo permite.⁴

Ejemplo de fórmula. Una cuenta de ejemplo para razonar:

C_{\text{turno}} = C_{\text{input}} + C_{\text{output}} + C_{\text{herramientas}} + C_{\text{observabilidad}}

Símbolo	Qué significa	Qué revisar
$C_{\text{input}}$	Coste de contexto enviado.	Esquema, docs, ejemplos, historial.
$C_{\text{output}}$	Coste de tokens generados.	Respuestas largas, razonamiento, formato.
$C_{\text{herramientas}}$	Consultas externas.	Bases, vector stores, APIs.
$C_{\text{observabilidad}}$	Trazas y evaluación.	Logs, métricas, almacenamiento.

Caso cercano. Meter todo el manual de 300 páginas en cada llamada puede funcionar en una demo y fracasar en coste. Un sistema serio recupera lo relevante, cachea instrucciones estables y mide si el contexto añadido mejora la respuesta.

Vuelve al capítulo 03 si: no puedes explicar por qué más contexto puede empeorar una respuesta.

4. Model cards y elección de modelos

En el capítulo 04 aprendimos a leer una ficha de modelo como un expediente técnico. Nombre, licencia, parámetros, contexto, precisión, benchmarks, proveedor, plantilla de chat y formato de pesos no son adornos.

Para recordar. Una model card sirve para comparar promesas con restricciones. El trabajo original sobre model cards propuso documentar uso previsto, factores relevantes, métricas, datos de evaluación y consideraciones éticas de los modelos.⁵

Término	Qué aporta realmente	Pregunta sana
Parámetros totales	Capacidad almacenada aproximada.	¿Cuántos se activan por token?
Context length	Ventana máxima declarada.	¿Con qué coste y calidad real?
Tensor type	Precisión y formatos presentes.	¿Qué usa inferencia de verdad?
License	Condiciones de uso.	¿Permite mi caso concreto?
Benchmarks	Señales comparativas.	¿Se parecen a mi tarea?
Chat template	Contrato de entrada.	¿Estoy enviando mensajes como toca?

Caso cercano. Un modelo con ventana de contexto enorme puede parecer perfecto para contratos. Pero si recupera mal detalles de la mitad del documento, tarda demasiado o cuesta diez veces más, el número de contexto no resuelve el producto.

Vuelve al capítulo 04 si: no puedes explicar una model card sin convertirla en un catálogo de siglas.

5. Local, cuantización y dependencia operativa

En los capítulos 05 y 06 bajamos del modelo abstracto a la máquina real: memoria, VRAM, cuantización, runtimes, cloud, local, alquiler de GPUs, latencia, privacidad, coste y mantenimiento.

Para recordar. Local no significa gratis. Cloud no significa simple. Un modelo local necesita formato, runtime, memoria, CPU/GPU, plantilla, servidor, límites, observabilidad y actualización. Un modelo cloud necesita contrato de datos, precios, latencia, región, cuotas, cambios de versión y fallback.

Decisión	Ganas	Pagas
API cloud	Facilidad, escalado, modelos potentes.	Coste variable, dependencia, políticas de datos.
Local en portátil	Control y aprendizaje.	Menos potencia, setup, rendimiento limitado.
Servidor local	Control operativo.	GPU, mantenimiento, scheduling, monitorización.
GPU alquilada	Capacidad temporal.	Gestión de imágenes, datos, apagado y coste/hora.
Cuantización	Menos memoria y coste.	Posible pérdida de calidad y estabilidad.

Caso cercano. Si una herramienta interna procesa expedientes sensibles y tiene pocos usuarios, local puede ser razonable. Si atiende miles de solicitudes variables y necesita el mejor modelo disponible, cloud puede ganar. Si la carga es estable y grande, quizá compensa un servidor propio. No hay respuesta universal: hay presupuesto y restricciones.

Vuelve a los capítulos 05 y 06 si: no puedes estimar memoria, latencia y coste antes de instalar nada.

6. Embeddings y búsqueda semántica

En el capítulo 07 convertimos texto en vectores. Un embedding no es una etiqueta. Es una posición en un espacio de dimensiones donde podemos medir cercanía.

Para recordar. La dimensión de un embedding no es “una idea humana”, sino un eje numérico aprendido. El significado aparece por la combinación de muchos ejes. Comparar embeddings permite buscar por parecido semántico, no solo por palabras exactas.

La similitud coseno sigue siendo la fórmula mental básica:

\operatorname{sim}(q,d)= \frac{q\cdot d}{\|q\|\|d\|}

Símbolo	Qué significa	Lectura
$q$	Vector de la consulta.	Lo que pregunta la persona en números.
$d$	Vector del documento.	Un fragmento convertido en números.
$q\cdot d$	Producto escalar.	Cuánto apuntan en dirección parecida.
$\\|q\\|$ , $\\|d\\|$	Normas.	Tamaño de cada vector.

FAISS mostró cómo buscar de forma eficiente entre miles de millones de vectores en GPU.⁶ HNSW es una estructura de grafos aproximados muy usada para búsqueda vectorial eficiente.⁷

Caso cercano. “Cómo pedir vacaciones” puede recuperar “procedimiento de ausencia laboral” aunque no comparta palabras. Eso es buenísimo. Pero “parecido” no significa “suficiente”: todavía hay que validar fecha, versión, permisos y respuesta.

Vuelve al capítulo 07 si: no puedes explicar qué es una dimensión y por qué dos textos cercanos pueden no responder la misma pregunta.

7. Bases vectoriales y búsqueda híbrida

En el capítulo 08 vimos que buscar no es solo guardar embeddings. Hay índices, filtros, metadatos, fragmentos, reranking y búsqueda híbrida.

Para recordar. BM25 sigue siendo fuerte para coincidencia léxica y términos exactos.⁸ Reciprocal Rank Fusion permite combinar rankings de distintas búsquedas sin convertir todo a una misma escala.⁹

Pieza	Qué aporta	Qué puede fallar
Chunking	Divide documentos recuperables.	Cortar contexto necesario.
Embeddings	Busca por significado.	Perder números, códigos o nombres exactos.
BM25	Busca por términos.	No captar paráfrasis.
Filtros	Acotan por permisos, fecha, tipo.	Filtrar demasiado o tarde.
Reranking	Reordena candidatos.	Añadir latencia sin mejorar.
Metadatos	Dan contexto operativo.	Estar incompletos o desactualizados.

Caso cercano. Si buscas “artículo 17.3” necesitas texto exacto. Si buscas “cómo se solicita una revisión”, necesitas semántica. Si necesitas ambas cosas, híbrida.

Vuelve al capítulo 08 si: no puedes diseñar un índice con texto, metadatos, filtros y estrategia de recuperación.

8. RAG básico: evidencia antes que respuesta

En el capítulo 09 construimos RAG: recuperar información externa, pasarla al modelo y responder con evidencia. RAG no es “hacer que el modelo sepa más”. Es darle contexto verificable en el momento de responder.

Para recordar. Un RAG mínimo necesita colección, limpieza, chunking, embeddings o búsqueda léxica, recuperación, contexto, generación, citas y abstención. El trabajo original de RAG combinó recuperación con generación para tareas intensivas en conocimiento.¹⁰

Caso cercano. Un asistente de normativa responde mejor si cita el documento vigente. Pero si recupera un párrafo antiguo, la redacción puede ser impecable y la respuesta falsa. RAG no elimina el problema: lo hace medible.

Vuelve al capítulo 09 si: no puedes explicar la diferencia entre entrenar conocimiento y recuperar evidencia.

9. Evaluar RAG y no fiarse de la demo

En el capítulo 10 dejamos claro que una demo que responde bien tres veces no es una evaluación. Hay que medir retrieval, contexto, groundedness, abstención, latencia, coste y regresiones.

Para recordar. Evaluar RAG tiene varias capas:

Capa	Pregunta
Recuperación	¿Aparece la fuente correcta entre los candidatos?
Contexto	¿Lo recuperado contiene evidencia suficiente?
Generación	¿La respuesta se apoya en esa evidencia?
Abstención	¿Sabe parar cuando no hay base?
Operación	¿Cuánto cuesta y tarda en casos reales?

RAGAS popularizó métricas orientadas a RAG como faithfulness, answer relevancy, context precision y context recall.¹¹

Caso cercano. Si tu sistema responde “no lo sé” ante una pregunta que sí tiene respuesta, falta recall. Si responde con seguridad sin evidencia, falta abstención o groundedness. Si acierta pero tarda doce segundos, falta operación.

Vuelve al capítulo 10 si: no puedes proponer un dataset de evaluación con preguntas, fuentes esperadas, respuestas aceptables y casos donde debe abstenerse.

10. Agentic RAG y GraphRAG: complicar con permiso

En el capítulo 11 vimos cuándo un RAG fijo se queda corto: preguntas compuestas, rutas de búsqueda, fuentes múltiples, relaciones globales o necesidad de comprobar si la evidencia basta.

Para recordar. Agentic RAG añade decisiones de flujo: descomponer, elegir fuente, recuperar de nuevo, revisar evidencia, usar herramientas. GraphRAG añade estructura de entidades y relaciones para responder preguntas locales o globales sobre corpus complejos. Microsoft GraphRAG propuso construir grafos de entidades y resúmenes de comunidades para preguntas de comprensión global.¹²

Si necesitas...	Puede tener sentido
Comparar varias fuentes	Query decomposition o multi-query.
Buscar con distintas estrategias	Router controlado.
Entender relaciones entre entidades	GraphRAG o grafo de conocimiento.
Revisar evidencia insuficiente	Corrective RAG o validación previa.
Limitar coste	Presupuesto de pasos y trazas.

Caso cercano. “Qué departamentos aparecen conectados a quejas sobre becas y retrasos de pago” no se resuelve igual que “cuál es el plazo de becas”. La primera pide patrones y relaciones. La segunda pide recuperar una fuente concreta.

Vuelve al capítulo 11 si: no puedes explicar qué complejidad pagas cuando añades pasos agentic.

11. Text-to-SQL y herramientas de datos

En el capítulo 12 cruzamos otra frontera: preguntas que no se contestan con documentos, sino con datos. Ahí no basta con recuperar párrafos. Hay que consultar tablas, esquemas, permisos y métricas.

Para recordar. Text-to-SQL traduce una pregunta humana a SQL controlado. No es acceso libre a la base de datos. Es una cadena: intención, esquema, semántica, SQL candidato, validación, plan, ejecución limitada, resultado y traza. Spider ayudó a medir Text-to-SQL con bases nuevas y consultas complejas.¹³

Pregunta	Riesgo si lo simplificas
“Alumnos con pagos pendientes”	Contar pagos en vez de alumnos.
“Ingresos de marzo”	Usar fecha de creación en vez de fecha de pago.
“Top campus”	No definir si top es por alumnos, importe o incidencias.
“Datos por titulación”	Exponer columnas innecesarias.

Caso cercano. Un JOIN mal hecho puede duplicar filas y devolver una cifra convincente pero falsa. En Text-to-SQL, la sintaxis correcta es solo el comienzo. La semántica y la cardinalidad mandan.

Vuelve al capítulo 12 si: no puedes explicar por qué COUNT(*) y COUNT(DISTINCT alumno_id) responden preguntas distintas.

La matriz de decisión final

Esta matriz es una forma de hacer arquitectura sin postureo. Primero identifica el tipo de necesidad; después elige la herramienta más pequeña que cubre el caso.

Necesidad real	Primer intento razonable	Escalaría a...	Señal de que te estás pasando
Mejor tono o formato	Prompt + ejemplos	Structured outputs	Cambiar pesos sin evaluar prompts.
JSON fiable	Schema + validador	Tool contract	Parsear texto libre.
Responder sobre documentos	RAG básico	Agentic RAG	Usar agente para una FAQ simple.
Encontrar documentos	Híbrida + filtros	Reranking	Embeddings sin metadatos.
Consultar datos vivos	Tool o Text-to-SQL	Semantic layer	Dejar SQL libre sin permisos.
Reducir coste	Modelo menor + caché	Cuantización/local	Recortar contexto sin medir calidad.
Controlar despliegue	API cloud con contratos	Servidor propio	Montar GPUs sin carga estable.
Dominio repetido	Plantillas + evals	LoRA/fine-tuning	Ajustar pesos para conocimiento cambiante.
Relaciones globales	RAG + metadatos	GraphRAG	Construir grafo sin preguntas de competencia.

La matriz no decide por ti. Te obliga a decir qué estás comprando con cada capa nueva. Esa frase, “qué estoy comprando”, es una de las mejores defensas contra arquitecturas hinchadas.

Mini casos con solución

Una buena recapitulación no solo pregunta “¿lo entendiste?”. Te pone delante situaciones pequeñas y obliga a decidir. Estas son decisiones de bolsillo, pero condensan casi todo el facsímil.

Caso	Decisión razonable	Por qué
Una FAQ interna cambia cada mes y el asistente responde con información antigua.	RAG básico con fuentes versionadas, citas y evaluación.	El problema es conocimiento cambiante, no estilo del modelo.
Un clasificador de tickets devuelve texto libre y rompe el flujo de soporte.	Structured outputs con catálogo cerrado y validador.	El fallo está en el contrato de salida, no en saber más contenido.
Una herramienta debe decir cuántos pagos pendientes hay por campus.	Tool de datos o Text-to-SQL con permisos y métricas definidas.	La respuesta vive en tablas, no en documentos parecidos.
Un RAG recupera fragmentos relacionados pero no la norma exacta.	Búsqueda híbrida, filtros por fecha/tipo y quizá reranking.	El problema está en retrieval, no en generación.
El sistema acierta pero tarda demasiado y cuesta demasiado por consulta.	Reducir contexto, cachear prefijos, probar modelo menor o cuantización.	El cuello está en presupuesto operativo.
El equipo quiere fine-tuning para añadir una política que cambia cada semana.	No ajustar pesos; usar RAG o tool.	El conocimiento vivo debe vivir fuera del modelo.
La pregunta exige comparar documentos, entidades y patrones de varias fuentes.	Agentic RAG controlado o GraphRAG si las relaciones importan.	La complejidad se justifica si la pregunta necesita pasos o estructura.

Ahora lo mismo, pero con tres decisiones desarrolladas.

Caso 1: “Tenemos una FAQ interna que cambia cada mes”.
No empezaría por fine-tuning. Cambiar pesos para información viva suele crear deuda: cada cambio exige nuevo ajuste, evaluación y despliegue. Empezaría por RAG básico: documentos versionados, chunking razonable, búsqueda híbrida si hay códigos o artículos, citas visibles y casos donde el sistema debe abstenerse. La métrica mínima sería: ¿recupera la fuente vigente?, ¿cita bien?, ¿responde solo con esa evidencia?

Caso 2: “Queremos consultar pagos pendientes”.
No usaría RAG como primera opción. Un documento puede explicar qué es un pago pendiente, pero el número está en una base de datos. Haría una tool o Text-to-SQL controlado: rol de usuario, tablas permitidas, métrica definida, SQL validado, límite de filas, query plan y traza. La pregunta clave sería: ¿estoy contando pagos, alumnos o expedientes?

Caso 3: “El RAG responde bonito pero cita mal”.
No tocaría temperatura ni modelo todavía. Mediría recuperación antes: recall de fuentes esperadas, precisión de contexto, frescura de documentos, metadatos, filtros y reranking. Si la evidencia correcta no entra en el contexto, el generador no puede arreglarlo de forma fiable. Si la evidencia entra pero la respuesta no se apoya en ella, entonces revisaría prompt, formato de citas y evaluación de groundedness.

La idea de estos casos no es memorizar respuestas. Es aprender el gesto mental: diagnosticar la pieza que falla antes de cambiar la herramienta.

Cuándo no usar IA

Una caja de herramientas seria también incluye la opción de no sacar ninguna herramienta de IA. Hay problemas que se resuelven mejor con una regla, una consulta, un formulario, una validación clásica o una interfaz más clara.

Situación	Mejor primera opción	Por qué
Categorías cerradas y reglas simples.	`if`, reglas o tabla de decisión.	Más barato, explicable y determinista.
Cálculo exacto.	Código o SQL.	Un modelo generativo no debería inventar aritmética.
Flujo con permisos estrictos.	API con roles y validación.	El permiso no debe depender de texto.
Información ya estructurada.	Consulta directa o dashboard.	No hace falta traducir a lenguaje natural si el informe basta.
Tarea muy sensible y sin evaluación.	Esperar, medir o rediseñar.	No se despliega lo que no se puede comprobar.
Problema mal definido.	Taller de requisitos.	La IA no arregla una pregunta que nadie entiende.

Esto no va contra la IA. Va a favor de usarla bien. A veces la decisión más profesional es decir: aquí no hace falta un modelo; hace falta una regla clara, una tabla limpia o una conversación de producto.

El cálculo que deberías hacer antes de construir

Antes de escribir código, puedes estimar si una solución tiene sentido.

Ejemplo de fórmula. Una cuenta cualitativa para discusión técnica es:

U = Q - (C_{\text{tokens}} + C_{\text{latencia}} + C_{\text{mantenimiento}} + C_{\text{riesgo}})

Símbolo	Qué significa	Cómo se observa
$U$	Utilidad neta de la solución.	Valor práctico después de costes.
$Q$	Calidad útil para la tarea.	Aciertos, groundedness, satisfacción, ahorro real.
$C_{\text{tokens}}$	Coste de entrada y salida.	Tokens, caché, modelo elegido.
$C_{\text{latencia}}$	Tiempo que tarda.	TTFT, P95, tiempo total.
$C_{\text{mantenimiento}}$	Trabajo de sostenerlo.	Datos, índices, evals, versiones.
$C_{\text{riesgo}}$	Impacto de fallos.	Permisos, datos sensibles, decisiones críticas.

No es una fórmula para sacar decimales. Es una disciplina mental. Si una herramienta sube $Q$ un poco pero dispara mantenimiento y latencia, quizá no compensa. Si baja coste sin destruir calidad, merece atención. Si reduce riesgo aunque cueste algo más, puede ser la decisión correcta.

Manos a la obra

Vamos a construir una pequeña rúbrica ejecutable. La idea es puntuar una propuesta de sistema antes de enamorarnos de ella. No sustituye a una evaluación real, pero obliga a mirar las piezas que este facsímil nos ha enseñado.

from dataclasses import dataclass


@dataclass
class PropuestaIA:
    nombre: str
    problema_definido: bool
    contrato_salida: bool
    evidencia_verificable: bool
    permisos_explicitos: bool
    coste_estimado: bool
    latencia_estimable: bool
    evaluacion_offline: bool
    trazas: bool
    mantenimiento_asignado: bool
    complejidad_justificada: bool


PESOS = {
    "problema_definido": 2,
    "contrato_salida": 2,
    "evidencia_verificable": 2,
    "permisos_explicitos": 2,
    "coste_estimado": 1,
    "latencia_estimable": 1,
    "evaluacion_offline": 2,
    "trazas": 2,
    "mantenimiento_asignado": 1,
    "complejidad_justificada": 2,
}


def revisar(propuesta):
    total = sum(PESOS.values())
    puntos = 0
    pendientes = []

    for campo, peso in PESOS.items():
        if getattr(propuesta, campo):
            puntos += peso
        else:
            pendientes.append(campo)

    ratio = puntos / total
    if ratio >= 0.85:
        decision = "puede pasar a prototipo controlado"
    elif ratio >= 0.65:
        decision = "necesita cerrar huecos antes de prototipar"
    else:
        decision = "todavía es una demo, no una arquitectura"

    return {
        "nombre": propuesta.nombre,
        "puntos": puntos,
        "total": total,
        "ratio": round(ratio, 2),
        "decision": decision,
        "pendientes": pendientes,
    }


casos = [
    PropuestaIA(
        nombre="FAQ con RAG básico",
        problema_definido=True,
        contrato_salida=True,
        evidencia_verificable=True,
        permisos_explicitos=True,
        coste_estimado=True,
        latencia_estimable=True,
        evaluacion_offline=True,
        trazas=True,
        mantenimiento_asignado=True,
        complejidad_justificada=True,
    ),
    PropuestaIA(
        nombre="Agente que consulta todo",
        problema_definido=False,
        contrato_salida=False,
        evidencia_verificable=True,
        permisos_explicitos=False,
        coste_estimado=False,
        latencia_estimable=False,
        evaluacion_offline=False,
        trazas=True,
        mantenimiento_asignado=False,
        complejidad_justificada=False,
    ),
]


for caso in casos:
    print(revisar(caso))

Salida esperada:

{
  'nombre': 'FAQ con RAG básico',
  'puntos': 17,
  'total': 17,
  'ratio': 1.0,
  'decision': 'puede pasar a prototipo controlado',
  'pendientes': []
}
{
  'nombre': 'Agente que consulta todo',
  'puntos': 4,
  'total': 17,
  'ratio': 0.24,
  'decision': 'todavía es una demo, no una arquitectura',
  'pendientes': [...]
}

Prueba tres variaciones:

Añade una propuesta de Text-to-SQL y decide qué campos deberían ser obligatorios.
Cambia pesos: haz que permisos y trazas valgan más en sistemas con datos sensibles.
Añade un campo plan_de_retroceso: qué hace el sistema cuando no hay evidencia suficiente.

Del laboratorio al siguiente facsímil

El cierre natural de este facsímil no es “ya sabemos usar herramientas”. Es más preciso: ya sabemos poner herramientas bajo control.

El laboratorio del capítulo 13 debería servir para demostrarlo con algo concreto: una evaluación reproducible, una traza que explique qué ocurrió, una decisión de arquitectura defendible y una salida que no dependa de buena suerte. Si una solución no deja rastro, no tiene contrato y no se puede evaluar, todavía pertenece al terreno de la demo.

El facsímil 05 dará el siguiente paso: agentes y orquestación. Ahí las herramientas dejan de ser piezas aisladas y empiezan a coordinarse. Por eso este cierre insiste tanto en límites, permisos, trazas, costes y abstención. Un agente sin esas piezas no es más capaz: solo es más difícil de depurar.

Laboratorio

El laboratorio operativo de este facsímil está en el capítulo 13 y se descarga desde kit descargable. Esta recapitulación no lo duplica: lo cierra. Si has hecho los retos, deberías tener artefactos concretos: rag_eval_report.json, rag_traces.jsonl, router_eval_report.json, router_traces.jsonl, decisiones Markdown y gates de CI.

Además, las prácticas cortas de capítulo están agrupadas en kit descargable. Úsalas como banco de comprobación rápido antes de volver al laboratorio largo: intervención correcta, payload de API, presupuesto de tokens, model card, modelo local, cloud/local, embeddings, índice híbrido, mini RAG, eval RAG, Agentic RAG, Text-to-SQL y rúbrica de arquitectura.

La regla editorial queda así: el laboratorio final prueba el sistema de extremo a extremo; las prácticas de capítulo prueban una pieza aislada. Las dos cosas hacen falta. Sin pieza aislada no sabes depurar; sin laboratorio no sabes integrar.

Cómo encaja todo

graph TD
    subgraph "Facsímil 04: caja de herramientas"
        PROBLEMA["Problema definido"]
        INTERVENCION["Intervención correcta"]
        API["API y contrato"]
        TOKENS["Tokens y presupuesto"]
        MODELO["Modelo y model card"]
        LOCAL["Cloud, local y cuantización"]
        EMB["Embeddings"]
        VECTOR["Índices y búsqueda híbrida"]
        RAG["RAG básico"]
        EVAL["Evaluación"]
        AGENTIC["Agentic RAG y GraphRAG"]
        SQL["Text-to-SQL"]
        TRAZA["Trazabilidad"]
        NOIA["No usar IA"]
        LAB["Laboratorio (F4C13)"]
        CRITERIO["Criterio de arquitectura"]
    end
    subgraph "Viene de antes"
        FUND["Tokens y embeddings (F1)"]
        TRANS["Transformer y sampling (F3)"]
        CSP["Restricciones y planificación (F2)"]
        ONTO["Grafos y ontologías (F2)"]
    end
    subgraph "Sigue después"
        AGENTES["Agentes y orquestación (F5)"]
        OPERAR["Construir y operar (F6)"]
        EVALUAR["Evaluar e interpretar (F7)"]
        DATOS["Ciencia de datos (F8)"]
    end

    FUND -->|"preparar"| EMB
    TRANS -->|"explicar coste de"| TOKENS
    CSP -->|"inspirar límites"| API
    ONTO -->|"anticipar relaciones"| AGENTIC
    PROBLEMA -->|"determinar"| INTERVENCION
    INTERVENCION -->|"declarar"| API
    API -->|"consumir"| TOKENS
    TOKENS -->|"condicionar"| MODELO
    MODELO -->|"desplegar en"| LOCAL
    EMB -->|"alimentar"| VECTOR
    VECTOR -->|"sostener"| RAG
    RAG -->|"necesitar"| EVAL
    EVAL -->|"decidir si compensa"| AGENTIC
    AGENTIC -->|"consultar relaciones"| SQL
    SQL -->|"producir datos con"| TRAZA
    PROBLEMA -->|"puede concluir en"| NOIA
    TRAZA -->|"cerrar"| CRITERIO
    CRITERIO -->|"se practica en"| LAB
    CRITERIO -->|"preparar"| AGENTES
    TRAZA -->|"preparar"| OPERAR
    EVAL -->|"preparar"| EVALUAR
    SQL -->|"conectar con"| DATOS

    style PROBLEMA fill:#F5F5F5,stroke:#000000,stroke-width:2
    style INTERVENCION fill:#F5F5F5,stroke:#000000,stroke-width:2
    style API fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TOKENS fill:#F5F5F5,stroke:#000000,stroke-width:2
    style MODELO fill:#F5F5F5,stroke:#000000,stroke-width:2
    style LOCAL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style EMB fill:#F5F5F5,stroke:#000000,stroke-width:2
    style VECTOR fill:#F5F5F5,stroke:#000000,stroke-width:2
    style RAG fill:#F5F5F5,stroke:#000000,stroke-width:2
    style EVAL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style AGENTIC fill:#F5F5F5,stroke:#000000,stroke-width:2
    style SQL fill:#F5F5F5,stroke:#000000,stroke-width:2
    style TRAZA fill:#111111,stroke:#000000,stroke-width:2,color:#FFFFFF
    style NOIA fill:#F5F5F5,stroke:#000000,stroke-width:2
    style LAB fill:#F5F5F5,stroke:#000000,stroke-width:2
    style CRITERIO fill:#F5F5F5,stroke:#000000,stroke-width:2
    style FUND stroke-dasharray: 5 5
    style TRANS stroke-dasharray: 5 5
    style CSP stroke-dasharray: 5 5
    style ONTO stroke-dasharray: 5 5
    style AGENTES stroke-dasharray: 5 5
    style OPERAR stroke-dasharray: 5 5
    style EVALUAR stroke-dasharray: 5 5
    style DATOS stroke-dasharray: 5 5

Vocabulario aprendido

Término	Definición
Intervención	Cambio concreto sobre entrada, contexto, herramienta, pesos o infraestructura.
Contrato	Especificación de entrada, salida, límites, errores y trazas.
Superficie de control	Lugar del sistema donde puedes limitar, validar o medir.
Presupuesto operativo	Límite de coste, tokens, latencia, memoria, pasos o consultas.
Evidencia	Información recuperada o calculada que sostiene una respuesta.
Abstención	Decisión de no responder cuando no hay base suficiente.
Trazabilidad	Capacidad de reconstruir cómo se produjo una respuesta.
Evaluación offline	Pruebas con casos preparados antes de uso real.
Evaluación online	Medición con uso real, tráfico y cambios.
Arquitectura mínima suficiente	Diseño más sencillo que resuelve el problema medido.
Decisión sin IA	Elección de resolver con reglas, SQL, interfaz o proceso cuando un modelo no aporta valor suficiente.

Dónde solía tropezar yo

Error	Por qué es un error	Antídoto
Empezar por la herramienta	“Metamos RAG” no dice qué fallo estás resolviendo.	Escribir primero qué cambia: entrada, contexto, herramienta, pesos o despliegue.
Confundir demo con sistema	Una respuesta buena no prueba permisos, coste, latencia ni regresiones.	Exigir dataset mínimo, trazas y casos donde debe abstenerse.
Meter más contexto sin medir	Puede subir coste y ruido sin mejorar groundedness.	Medir recall, precisión de contexto y calidad de respuesta por separado.
Complicar antes de cerrar lo básico	Agentic RAG o GraphRAG pueden esconder problemas de chunking, filtros o definición.	Probar primero el flujo más simple que pueda evaluarse.
Olvidar mantenimiento	Índices, prompts, modelos, esquemas y datos cambian.	Nombrar propietario, versión y prueba de regresión de cada pieza.
No diseñar salida de fallo	El sistema acaba respondiendo incluso cuando no sabe.	Definir abstención, aclaración y escalado antes de producción.
No contemplar la opción sin IA	Algunas tareas se resuelven mejor con reglas, SQL o una interfaz más clara.	Preguntar siempre qué gana el modelo frente a una solución clásica.

Antes de pasar página

Responde sin consultar los capítulos. Si fallas una pregunta, el número te dice dónde volver.

En resumen

Idea fuerza	Detalle
La caja de herramientas empieza con diagnóstico.	Antes de elegir técnica, hay que saber qué parte del sistema falla.
Un modelo útil necesita contratos alrededor.	APIs, schemas, herramientas, validadores y trazas hacen gobernable la respuesta.
La evidencia se recupera, se mide y se cita.	RAG, búsqueda híbrida, GraphRAG y Text-to-SQL son formas distintas de traer base verificable.
El coste también es arquitectura.	Tokens, contexto, caché, latencia, GPU, local y cloud cambian el diseño.
La evaluación separa demo de sistema.	Sin casos, métricas, abstención y regresiones, no sabes si mejoraste.
La complejidad tiene que ganarse el sitio.	Agentic RAG, GraphRAG o fine-tuning solo compensan cuando resuelven un fallo medido.
No usar IA también es una decisión técnica.	Si una regla, SQL o una interfaz clara resuelve mejor, esa es la herramienta correcta.
El siguiente paso es coordinar herramientas.	El facsímil 05 parte de esta base para hablar de agentes y orquestación.

Para saber más

Cormack, G. V., Clarke, C. L. A. y Büttcher, S. (2009). Reciprocal rank fusion outperforms Condorcet and individual rank learning methods. Proceedings of SIGIR, 758-759. DOI

Edge, D. et al. (2024). From Local to Global: A Graph RAG Approach to Query-Focused Summarization. arXiv

Es, S. et al. (2023). RAGAS: Automated Evaluation of Retrieval Augmented Generation. arXiv

Hu, E. J. et al. (2022). LoRA: Low-Rank Adaptation of Large Language Models. arXiv

Johnson, J., Douze, M. y Jégou, H. (2019). Billion-scale similarity search with GPUs. IEEE Transactions on Big Data, 7(3), 535-547. DOI

Lewis, P. et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. Advances in Neural Information Processing Systems 33, 9459-9474. NeurIPS

Malkov, Y. A. y Yashunin, D. A. (2020). Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs. IEEE Transactions on Pattern Analysis and Machine Intelligence, 42(4), 824-836. DOI

Mitchell, M. et al. (2019). Model Cards for Model Reporting. Proceedings of FAT 2019, 220-229. DOI

OpenAI. (2026). Function calling. Documentación oficial

OpenAI. (2026). Prompt caching. Documentación oficial

OpenAI. (2026). Structured model outputs. Documentación oficial

Robertson, S. y Zaragoza, H. (2009). The probabilistic relevance framework: BM25 and beyond. Foundations and Trends in Information Retrieval, 3(4), 333-389. DOI

Yu, T. et al. (2018). Spider: A Large-Scale Human-Labeled Dataset for Complex and Cross-Domain Semantic Parsing and Text-to-SQL Task. Proceedings of EMNLP, 3911-3921. ACL Anthology

Notas

OpenAI. (2026). Function calling. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
OpenAI. (2026). Structured model outputs. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
Hu, E. J. et al. (2022). LoRA: Low-Rank Adaptation of Large Language Models. International Conference on Learning Representations. arXiv. Dettmers, T. et al. (2023). QLoRA: Efficient Finetuning of Quantized LLMs. Advances in Neural Information Processing Systems 36. arXiv. ↩
OpenAI. (2026). Prompt caching. Documentación oficial. Consultado el 26 de mayo de 2026. ↩
Mitchell, M. et al. (2019). Model Cards for Model Reporting. Proceedings of FAT 2019, 220-229. DOI. ↩
Johnson, J., Douze, M. y Jégou, H. (2019). Billion-scale similarity search with GPUs. IEEE Transactions on Big Data, 7(3), 535-547. DOI. ↩
Malkov, Y. A. y Yashunin, D. A. (2020). Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs. IEEE Transactions on Pattern Analysis and Machine Intelligence, 42(4), 824-836. DOI. ↩
Robertson, S. y Zaragoza, H. (2009). The probabilistic relevance framework: BM25 and beyond. Foundations and Trends in Information Retrieval, 3(4), 333-389. DOI. ↩
Cormack, G. V., Clarke, C. L. A. y Büttcher, S. (2009). Reciprocal rank fusion outperforms Condorcet and individual rank learning methods. Proceedings of SIGIR, 758-759. DOI. ↩
Lewis, P. et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. Advances in Neural Information Processing Systems 33, 9459-9474. NeurIPS. ↩
Es, S. et al. (2023). RAGAS: Automated Evaluation of Retrieval Augmented Generation. arXiv. ↩
Edge, D. et al. (2024). From Local to Global: A Graph RAG Approach to Query-Focused Summarization. arXiv. ↩
Yu, T. et al. (2018). Spider: A Large-Scale Human-Labeled Dataset for Complex and Cross-Domain Semantic Parsing and Text-to-SQL Task. Proceedings of EMNLP, 3911-3921. ACL Anthology. ↩