Retrieval on lo0 — Blog Técnico

Function calling y tool-augmented retrieval: el detective que sabe qué archivo pedir

Thu, 04 Jun 2026 10:00:00 +0200

Este post profundiza en el mecanismo de razonamiento agentivo que extiende el RAG descrito en RAG con reranker e hybrid retrieval. El retriever que se invoca cuando el LLM elige vector_search es exactamente el pipeline de ese artículo. El JSON Schema que define cada tool call es structured output aplicado a la interfaz herramienta. Y las requests del agente pasan por el gateway L7 de inferencia antes de llegar al modelo.

TL;DR

Un RAG naive consulta siempre la misma fuente. Function calling le da al LLM la capacidad de decidir qué herramienta invocar — vector store, SQL, web search — en función de lo que la query realmente necesita. El patrón ReAct encadena esas invocaciones en un bucle razonado hasta obtener suficiente evidencia. Un pipeline de 3 iteraciones con Llama-3.1-70B en hardware on-premise tarda ≈ 1,1 s frente a los ≈ 300 ms del RAG de un solo paso; la ganancia no es en velocidad sino en queries que el RAG naive simplemente no puede responder. La métrica de eval crítica es tool selection accuracy: el porcentaje de turns en que el modelo elige el tool correcto, medida sobre un eval set sintético.

La analogía: el detective que sabe qué archivo pedir

Un detective de novela no va al mismo archivador independientemente del caso que le llegue. Cuando recibe un caso, razona primero: ¿qué tipo de evidencia necesito? Si hay testigos, pide los testimonios (vector search sobre documentos no estructurados). Si hay transacciones financieras, pide los registros contables al banco (SQL sobre la base de datos estructurada). Si el sospechoso tiene actividad reciente que la empresa no puede tener indexada, va a la hemeroteca (web search). No consulta las tres fuentes de golpe en cada caso: elige la que la evidencia requiere, recibe el resultado, razona de nuevo si necesita más, y sólo cuando tiene suficiente evidencia redacta el informe.

Un detective malo siempre va al mismo archivador. Un RAG naive es ese detective malo: vectoriza la query, va al vector store, y devuelve lo que encuentra aunque la pregunta fuera “¿cuántos contratos?” — algo que ningún chunk de PDF puede responder mejor que un COUNT(*) en SQL.

Function calling es darle al LLM la capacidad de razonar sobre qué fuente pedir, y de invocarla de forma estructurada. La analogía tiene tres aristas que conviene retener:

El detective no improvisa el archivo que pide: hay un catálogo de fuentes disponibles con descripción de qué contiene cada una. La descripción del tool en el system prompt cumple esa función.
El detective puede pedir varias evidencias a la vez si son independientes (parallel tool calling).
El detective sabe cuándo parar: si tras N rondas no llega a conclusión, declara que no tiene suficiente evidencia. El agente tiene un límite de iteraciones por la misma razón.

Qué es function calling: la anatomía de una tool call

Function calling — también llamado tool use — es un mecanismo por el que el LLM, en vez de generar texto libre como respuesta, genera un objeto JSON estructurado que representa una invocación de herramienta. El sistema intercepta ese JSON, ejecuta la herramienta real, y devuelve el resultado como un mensaje de rol tool en la conversación.

Definición de tools en el system prompt

Cada tool se define mediante un JSON Schema que especifica nombre, descripción y parámetros. Este JSON Schema es exactamente el mismo mecanismo descrito en structured output, aplicado aquí a la interfaz herramienta:

{
 "tools": [
 {
 "name": "vector_search",
 "description": "Search internal company documents about policies, contracts and procedures. Use when the query requires unstructured text, document context or semantic similarity.",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string", "description": "Natural language search query"},
 "top_k": {"type": "integer", "default": 5}
 },
 "required": ["query"]
 }
 },
 {
 "name": "sql_query",
 "description": "Query the SQL database for structured metrics, counts, aggregations and financial data. Use when the query requires exact numbers, filters, sums or joins over structured records.",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string", "description": "Parameterized SQL query with $1, $2 placeholders"},
 "params": {"type": "array", "items": {}, "description": "Parameter values for the placeholders"}
 },
 "required": ["query"]
 }
 },
 {
 "name": "web_search",
 "description": "Search public web for real-time information, recent news or current prices. Use only when data is public and not covered by internal sources.",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string"}
 },
 "required": ["query"]
 }
 }
 ]
}

El ciclo de una tool call

Cuando el LLM decide invocar una tool, el mensaje que genera en lugar de texto libre tiene esta estructura (formato OpenAI-compatible, el mismo que soporta vLLM):

{
 "role": "assistant",
 "tool_calls": [
 {
 "id": "call_01",
 "type": "function",
 "function": {
 "name": "sql_query",
 "arguments": "{\"query\": \"SELECT COUNT(*), SUM(amount) FROM contracts WHERE amount > $1 AND year = $2 AND provider_region = $3\", \"params\": [100000, 2025, \"EU\"]}"
 }
 }
 ]
}

El sistema ejecuta la tool y devuelve:

{"role": "tool", "tool_call_id": "call_01", "content": "{\"count\": 47, \"total\": 8300000}"}

El LLM recibe ese mensaje como continuación de la conversación y decide si necesita más información o puede generar la respuesta final.

Soporte en modelos OSS

En 2026, el soporte de function calling nativo (no emulado vía system prompt) está disponible en:

Llama 3.1 / 3.3+: formato de tool call nativo, soportado en vLLM con --enable-auto-tool-choice --tool-call-parser llama3_json
Qwen 2.5+: soporte nativo con --tool-call-parser hermes
Mistral NeMo / Mistral 7B Instruct v0.3+: formato nativo con --tool-call-parser mistral
Qwen3 (2025+): soporte nativo extendido con parallel tool calling

Sin --enable-auto-tool-choice, vLLM puede forzar el formato de tool call vía guided decoding (JSON Schema), pero la capacidad de decidir cuándo invocar una tool vs generar texto libre requiere entrenamiento específico del modelo.

El patrón ReAct: Reasoning + Acting

ReAct (Yao et al., 2022) es el bucle que convierte un LLM con tools en un agente con razonamiento. La idea central es que el modelo intercala pensamientos (razonamiento explícito sobre qué hacer) con acciones (invocación de tools) y observaciones (resultados recibidos). Este bucle se repite hasta que el modelo estima tener suficiente información para responder, o hasta que se alcanza el límite de iteraciones.

Thought → Action → Observation → Thought → Action → Observation → ... → Response

Trace ReAct completo: una query de producción real

Query: "¿Cuántos contratos de más de 100k€ firmamos en 2025 con proveedores de la UE, y cuáles son las condiciones especiales que se repiten?"

Esta query requiere dos fuentes distintas: los números exactos viven en SQL, y el contexto de condiciones especiales vive en los PDFs de contratos indexados en el vector store.

Iteración 1

Thought: La query pide datos agregados (conteo y suma) con filtros exactos sobre campos estructurados (importe, año, región). Esto es una consulta SQL, no una búsqueda semántica.

Action: sql_query

SELECT COUNT(*) AS num_contratos, SUM(amount) AS total_eur
FROM contracts
WHERE amount > $1 AND year = $2 AND provider_region = $3

params: [100000, 2025, "EU"]

Observation: {"num_contratos": 47, "total_eur": 8300000}

Iteración 2

Thought: Tengo los números. Ahora necesito las condiciones especiales que se repiten en estos contratos. Ese tipo de información está en el texto libre de los PDFs, no en la tabla estructurada. Voy al vector store.

Action: vector_search

"contratos proveedores UE 2025 importe superior 100k condiciones especiales cláusulas recurrentes"

top_k: 5

Observation:

[chunk_1] Contrato Proveedor A — cláusula 8.3: penalización por retraso del 2% mensual sobre el importe facturado...
[chunk_2] Contrato Proveedor C — cláusula 7.1: revisión de precios vinculada al IPC de la zona euro con tope del 4% anual...
[chunk_3] Contrato Proveedor B — cláusula 8.3: penalización por retraso del 2% mensual...

Thought: Tengo datos suficientes de ambas fuentes. La cláusula 8.3 de penalización por retraso aparece en al menos dos contratos de los recuperados. Puedo sintetizar la respuesta.

Response: “En 2025 firmasteis 47 contratos con proveedores de la UE por importe superior a 100.000 €, con un total acumulado de 8,3 M€. La condición especial que aparece con más frecuencia en los contratos de mayor valor es la cláusula de penalización por retraso (8.3 en los modelos de contrato de Proveedor A y B): 2% mensual sobre importe facturado. También se repite la revisión de precios vinculada al IPC de la zona euro con tope del 4% anual (cláusula 7.1).”

Este trace tiene 2 iteraciones. Una query más compleja (comparar con el año anterior, cruzar con estado de pago) añadiría iteraciones adicionales. La práctica habitual es fijar un límite de 5–10 iteraciones máximo para evitar bucles.

Las tres fuentes y cuándo usar cada una

La elección de fuente no es arbitraria ni queda sólo en manos del LLM: la arquitectura define qué tools existen y cómo se describen. La tabla siguiente resume los criterios de selección:

Característica	Vector store (Qdrant)	SQL / estructurado (PostgreSQL)	Web search
Tipo de dato	Texto libre, documentos, PDFs	Tablas con esquema fijo	Páginas públicas, noticias
Estructura	No estructurado	Altamente estructurado	Semi-estructurado
Temporalidad	Índice estático (actualización periódica)	Tiempo real (transaccional)	Tiempo real (crawl)
Latencia típica	5–50 ms	10–200 ms	200–2.000 ms
Privacidad	Datos internos, soberanía total	Datos internos, soberanía total	Solo datos públicos
Query natural	Sí (lenguaje natural → embedding)	No (SQL parametrizado)	Sí
Agregaciones exactas	No	Sí (`COUNT`, `SUM`, `GROUP BY`)	No
Cuándo usar	Contexto documental, semántica, PDFs	Métricas, conteos, filtros exactos, joins	Datos que no existen internamente y son públicos

La regla práctica más importante: si la pregunta contiene palabras como “cuántos”, “suma”, “total”, “más de X”, “en el año Y” y los datos están en una tabla estructurada, la respuesta correcta es sql_query. Si la pregunta pide contexto, explicaciones, cláusulas, procedimientos o ejemplos de documentos, la respuesta es vector_search. Si pide el precio actual de algo o noticias recientes sobre un tercero, web_search — pero sólo si no hay soberanía de datos implicada.

Tool routing: cómo el LLM elige el tool correcto

La descripción de cada tool en el system prompt es el factor más crítico para la precisión del routing. Un LLM con buenas capacidades de function calling puede elegir mal si las descripciones son ambiguas o se solapan.

Descripciones que funcionan vs las que no

Descripción débil (lleva al LLM a usar el tool equivocado):

"search_docs" — Busca información en las fuentes disponibles.
"query_data" — Obtiene datos del sistema.

Descripción fuerte (delimita con precisión cuándo usar cada uno):

"vector_search" — Search internal company documents about policies, contracts and procedures.
Use when the query requires unstructured text, document context or semantic
similarity. NOT for counts, sums or exact filters.
"sql_query" — Query the SQL database for structured metrics, counts, aggregations and
financial data. Use when the query requires exact numbers, filters, sums or
joins over structured records. NOT for finding document context.

La diferencia está en dos elementos: (1) ejemplos de casos de uso positivos, y (2) exclusiones explícitas con NOT for. Ambos reducen el solapamiento semántico entre tools y mejoran la tool selection accuracy.

Parallel tool calling

Cuando dos tools son independientes entre sí — es decir, el resultado de una no afecta a la query de la otra — el LLM puede invocarlas simultáneamente en el mismo turno:

{
 "tool_calls": [
 {"id": "call_01", "function": {"name": "sql_query", "arguments": "..."}},
 {"id": "call_02", "function": {"name": "vector_search", "arguments": "..."}}
 ]
}

El sistema ejecuta ambas en paralelo y devuelve ambas observaciones antes del siguiente turno del LLM. Esto reduce la latencia total cuando las queries son independientes: en vez de 2 iteraciones secuenciales (2 × latencia_tool), se paga 1 × max(latencia_sql, latencia_vector). Para el ejemplo del detective: si necesita tanto los registros contables como los testimonios para responder, puede pedirlos a la vez.

Tool selection accuracy: la métrica de eval

La tool selection accuracy es el porcentaje de turns en que el LLM elige el tool correcto dado un conjunto de queries evaluadas:

[ \text{TSA} = \frac{\text{turns con tool correcto elegido}}{\text{total turns con tool call esperada}} ]

Se mide sobre un eval set sintético construido con triples (query, tool_esperado, args_esperados). Un ejemplo de eval set mínimo:

Query	Tool esperado	Indicador de fallo
“¿Cuántos pedidos en marzo?”	`sql_query`	LLM usa `vector_search`
“¿Qué dice la política de devoluciones?”	`vector_search`	LLM usa `sql_query`
“¿Cuál es el precio del cobre hoy?”	`web_search`	LLM usa `vector_search`
“Suma los contratos del Q3”	`sql_query`	LLM usa `vector_search`

Una TSA < 0,85 en un agente de producción es señal de que las descripciones de tools necesitan revisión antes que el modelo. Para más detalle sobre cómo construir estos evals, ver evals LLM.

Manejo de errores en tool calls

SQL injection via prompt

El riesgo más serio del tool-augmented retrieval es que el LLM genere SQL malicioso — bien porque un usuario lo indujo via prompt injection, bien porque el modelo alucinó una query destructiva. Este vector de ataque se cubre en detalle en LLM Guard, pero las reglas mínimas del lado del tool son:

Regla 1: Queries parametrizadas siempre, nunca interpolación directa.

# NUNCA esto:
cursor.execute(f"SELECT * FROM contracts WHERE provider = '{llm_output}'")

# Siempre esto:
cursor.execute("SELECT * FROM contracts WHERE provider = $1", [llm_output])

Regla 2: Usuario de BD con permisos mínimos. El usuario con el que el agente ejecuta SQL debe tener SELECT sobre las tablas necesarias y nada más. Ningún DROP, INSERT, UPDATE ni DELETE.

Regla 3: Allowlist de tablas. El sistema valida que la query generada por el LLM sólo referencia tablas en una allowlist antes de ejecutarla.

Regla 4: Timeout por query. Queries que bloquean demasiado tiempo — potencialmente inducidas para hacer DoS a la BD — se cancelan con timeout configurado.

Rate limits, timeouts y errores de tool

Cuando una tool falla, el error se devuelve al LLM como observación:

{"role": "tool", "tool_call_id": "call_01", "content": "{\"error\": \"timeout after 5s\", \"tool\": \"web_search\"}"}

El system prompt debe instruir al LLM sobre qué hacer en este caso:

If a tool returns an error or is unavailable, acknowledge the limitation in your response.
Do not retry more than once. If web_search is unavailable, state that real-time data
is not accessible at this moment and answer with available internal sources only.

Esto evita que el agente entre en bucles de reintentos y gestiona la degradación graceful: si web_search no está disponible, responde con lo que tiene en las fuentes internas.

Diagrama del bucle ReAct con las tres fuentes

Matemáticas de latencia del pipeline ReAct

Cada iteración del bucle ReAct tiene tres componentes de latencia:

[ T_{\text{iter}} = \text{TTFT}{\text{LLM}} + T{\text{tool}} + \Delta_{\text{context}} ]

donde:

TTFT_LLM: tiempo hasta el primer token del LLM (dominado por el prefill del contexto acumulado)
T_tool: tiempo de ejecución de la tool
Δ_context: overhead de context window creciente (cada iteración añade el output anterior al contexto)

Valores de referencia: Llama-3.1-70B en 4×H100 SXM (320 GB, NVLink)

Con Llama-3.1-70B en FP8 en un nodo con 4×H100 SXM (320 GB HBM3, NVLink 900 GB/s), los valores típicos en producción son:

Componente	Valor
TTFT con contexto < 4k tokens	≈ 150 ms
TTFT con contexto 8k tokens	≈ 220 ms
`sql_query` (query simple, índice)	≈ 50 ms
`vector_search` (top-5, Qdrant en RAM)	≈ 20 ms
`web_search` (API externa)	≈ 600 ms

Latencia total según número de iteraciones

Pipeline de 1 iteración (query simple, una sola tool):

[ T_1 = 150 + 50 = 200 \text{ ms} + \text{síntesis final} \approx 200 + 300 = 500 \text{ ms} ]

Pipeline de 2 iteraciones (SQL + vector_search secuenciales):

[ T_2 = (150 + 50) + (180 + 20) + 400 = 800 \text{ ms} ]

El contexto en la segunda iteración ya incluye el resultado de la primera, por lo que el TTFT sube ligeramente a ≈ 180 ms.

Pipeline de 3 iteraciones (el caso más común en queries complejas):

[ T_3 = (150 + 50) + (180 + 20) + (200 + 50) + 450 \approx 1.100 \text{ ms} ]

Parallel tool calling (SQL + vector_search en paralelo, 1 sola iteración):

[ T_{\text{parallel}} = 150 + \max(50, 20) + 400 = 600 \text{ ms} ]

Cuando las dos queries son independientes, el parallel tool calling recorta la latencia de ≈ 800 ms a ≈ 600 ms: un 25% de mejora para el caso de 2 iteraciones secuenciales.

Comparación con RAG naive

Configuración	Latencia	Queries que puede responder
RAG naive (1 retriever, 1 paso)	≈ 300 ms	Queries de contexto documental
ReAct 1 iteración (SQL)	≈ 500 ms	Queries de agregación estructurada
ReAct 2 iteraciones (SQL + vector)	≈ 800 ms	Queries híbridas numérico + contexto
ReAct 3 iteraciones	≈ 1.100 ms	Queries complejas multi-fuente
ReAct con web_search	≈ 1.500 ms	Queries que requieren datos en tiempo real

La conclusión práctica: ReAct multi-hop es 3–5× más lento que un RAG naive de un solo paso. La ganancia no está en la velocidad sino en la cobertura de queries: el RAG naive no puede responder “¿cuántos contratos?” porque esa respuesta no está en ningún chunk de texto. Para aplicaciones con SLO de latencia estricto (< 500 ms), hay que diseñar si el caso de uso realmente necesita ReAct o si un RAG bien configurado con hybrid retrieval cubre el 90% de las queries.

Hardware on-premise para agentes ReAct

Un agente ReAct con Llama-3.1-70B en producción tiene requisitos distintos a un RAG naive porque el contexto crece con cada iteración y el throughput de prefill es más crítico.

Configuración recomendada: 4×H100 SXM (320 GB HBM3, NVLink 900 GB/s)

Llama-3.1-70B en FP8: cabe en 2×H100 (70B params × 1 byte/param ≈ 70 GB + KV cache). Con 4×H100 se puede servir en tensor parallelism TP=4, reduciendo el TTFT por prefill en ≈ 2×.
Instancia de Qdrant: se puede colocar en el mismo nodo (si la colección cabe en RAM) o en nodo dedicado. Para colecciones < 50M vectores de 768 dims: ≈ 150 GB, cabe en RAM de un servidor dual-socket.
PostgreSQL: nodo separado o instancia gestionada. El agente no añade carga inusual al SQL — las queries son simples y acotadas por timeout.
vLLM con --enable-auto-tool-choice --tool-call-parser llama3_json --max-model-len 16384: el contexto de 16k tokens cubre con holgura los 5–10 turns de un pipeline ReAct.

Configuración mínima viable: 2×H100 SXM (160 GB)

Llama-3.1-70B en FP8 en TP=2. TTFT ≈ 250–300 ms para contextos de 4k tokens (aumento del 60–100% sobre TP=4).
Sirve para workloads internos con < 20 requests concurrentes.
No recomendable para SLO < 1 s con más de 5 usuarios concurrentes y contexto largo.

Lo que no hemos cubierto

Agentic retrieval loops con planificación. ReAct es el patrón más simple de agente. Cuando una query requiere descomposición en sub-tareas con dependencias, se necesitan frameworks de orquestación como LangGraph (grafos de estados), smolagents (Hugging Face, agentes con código Python como actions) o llama-index Agents (pipeline de planning + retrieval). Estos introducen un paso de planificación previo al bucle de ejecución.

MCP (Model Context Protocol). El estándar emergente de Anthropic — con implementaciones OSS — para definir tools de forma portable entre frameworks y hosts. En lugar de definir el JSON Schema de cada tool por separado en cada aplicación, MCP centraliza esas definiciones en un servidor MCP que cualquier cliente compatible puede descubrir e invocar. La adopción en 2025–2026 es rápida entre frameworks OSS (LangChain, smolagents, OpenWebUI).

Tool caching. Si el mismo tool call (mismos argumentos, misma tool) se va a invocar múltiples veces dentro del mismo contexto o en contextos muy similares, se puede cachear el resultado. El mecanismo es análogo al semantic cache descrito para RAG: antes de ejecutar el tool, se compara el hash de los argumentos (o su embedding para matching semántico) contra una caché con TTL. Especialmente valioso para sql_query con queries frecuentes y datos que cambian poco.

Multi-agent. Cuando un agente orquestador delega sub-tareas a agentes especializados — uno para SQL, otro para recuperación de documentos, otro para generación de código — se entra en el territorio de los sistemas multi-agente. Cada sub-agente puede tener su propio set de tools y su propio LLM (posiblemente más pequeño y especializado). La coordinación entre agentes introduce complejidad de trazado y observabilidad adicional.

Ver también

RAG con reranker e hybrid retrieval — el retriever que se invoca cuando el LLM elige vector_search es exactamente el pipeline descrito allí: dense + sparse + reranker cruzado
Structured output: fundamentos — el JSON Schema que define el contrato de cada tool call es exactamente structured output aplicado a la interfaz herramienta
Router de inferencia y LLM gateway L7 — el gateway L7 que recibe las requests del agente ReAct y enruta al LLM correcto; también aplica rate limiting por usuario y tenant
LLM Guard: fundamentos — SQL injection via prompt es un vector de ataque real en tool-augmented retrieval; LLM Guard cubre la detección de prompt injection antes de que el request llegue al LLM
Pipeline LLMOps de seis etapas — tool-augmented retrieval vive en la intersección de las etapas Deploy y Observe del pipeline: se despliega como parte del sistema de inferencia y se observa vía tracing de cada turn del agente
Evals LLM: la capa después del tracing — tool selection accuracy es la métrica de eval crítica para un agente ReAct; el golden dataset de eval debe incluir triples (query, tool esperado, args esperados)

Referencias

Yao, S. et al. (2022). ReAct: Synergizing Reasoning and Acting in Language Models. arXiv:2210.03629. https://arxiv.org/abs/2210.03629
vLLM documentation. Tool calling. https://docs.vllm.ai/en/stable/features/tool_calling.html
Qdrant documentation. Search. https://qdrant.tech/documentation/concepts/search/
OpenAI. Function calling. https://platform.openai.com/docs/guides/function-calling
Meta AI. Llama 3.1 Model Card. https://github.com/meta-llama/llama-models/blob/main/models/llama3_1/MODEL_CARD.md
Qwen Team (Alibaba). Qwen2.5 Technical Report. arXiv:2412.15115. https://arxiv.org/abs/2412.15115
Anthropic. Model Context Protocol. https://modelcontextprotocol.io
OWASP. LLM Top 10 for Large Language Model Applications. LLM01: Prompt Injection. https://owasp.org/www-project-top-10-for-large-language-model-applications/

Evaluar un RAG sin engañarse: RAGAS, el golden dataset y las cuatro métricas que importan

Thu, 04 Jun 2026 09:00:00 +0200

TL;DR

Un pipeline RAG falla en modos que la satisfacción del usuario no distingue: el LLM puede alucinar incluso con buenos chunks, o el retrieval puede ignorar documentos clave aunque el LLM sintetice bien lo que recibe. RAGAS descompone la evaluación en cuatro métricas ortogonales —faithfulness, answer relevance, context precision y context recall— cada una apuntando a un sub-componente diferente. El golden dataset es el calibrador de referencia; sin él las métricas no tienen ancla. El stack completo corre 100 % on-premise con vLLM como judge y Langfuse para trazabilidad.

La analogía maestra: el inspector de calidad de una fábrica de muebles

Imagina que fabricas sillas. Podrías preguntar a los clientes “¿es cómoda?” y punto. Pero esa pregunta no te dice qué arreglar cuando la respuesta es “no”. El inspector de calidad no pregunta eso: mide el tablero con dureza Shore, comprueba que cada pata tenga exactamente 45 cm, verifica que el manual de montaje incluya los doce tornillos del BOM y detecta si un tablero de densidad baja pasó el filtro de entrada.

RAGAS es ese inspector aplicado a RAG:

Faithfulness → ¿el tablero tiene la dureza especificada? El LLM solo puede usar el material (chunks) que el retrieval le entrega.
Context Precision → ¿la pata tiene la longitud exacta? De los K chunks recuperados, ¿cuántos son realmente útiles o son relleno que confunde al ensamblador?
Context Recall → ¿el manual incluye todos los tornillos? De todos los hechos que debería contener la respuesta correcta, ¿cuántos aparecen en los chunks recuperados?
Noise Sensitivity → ¿si el operario usa un tablero de densidad media baja, se nota en el producto final? Si introduces chunks irrelevantes, ¿el LLM empieza a alucinar?

Sin medir cada dimensión por separado, el diagnóstico es opaco: “el RAG no funciona bien” no te dice si reparar el embedder, el reranker, el prompt o el corpus.

El problema de evaluar RAG

La clasificación tiene una virtud incómoda: si predices 87 de 100 etiquetas correctamente, accuracy = 0,87. No hay ambigüedad. RAG no tiene esa gracia.

Un sistema RAG puede fallar en al menos tres modos independientes:

Retrieval correcto, LLM alucina: los chunks contienen la respuesta correcta, pero el LLM genera afirmaciones que no están en esos chunks. Faithfulness baja; context recall alta.
LLM correcto, retrieval falla: el retrieval devuelve chunks irrelevantes (baja context precision) o incompletos (bajo context recall). Si el LLM tiene suficiente conocimiento paramétrico, puede parecer que responde bien, pero en realidad está ignorando el contexto — lo cual es una bomba de tiempo cuando el conocimiento paramétrico queda obsoleto.
Retrieval y LLM correctos, respuesta no responde la pregunta: la respuesta es fiel al contexto y los chunks son relevantes, pero la pregunta era otra. Answer relevance baja.

Cada modo requiere una métrica diferente y una acción correctiva diferente. Usar una métrica única (BLEU, ROUGE, satisfacción de usuario) mezcla las señales y hace imposible priorizar el trabajo de mejora.

Las cuatro métricas RAGAS

1. Faithfulness — fidelidad al contexto

Pregunta: ¿cuántas afirmaciones de la respuesta generada están soportadas por los chunks recuperados?

Cálculo:

$$\text{Faithfulness} = \frac{|\text{claims soportados por el contexto}|}{|\text{total claims en la respuesta}|}$$

El proceso usa un LLM-as-judge (ver https://blog.lo0.es/posts/llm-as-judge-fundamentos/): primero se extraen las afirmaciones atómicas de la respuesta (“el modelo fue lanzado en 2023”, “admite contextos de 128k tokens”, …), luego el judge clasifica cada claim como supported o not supported por los chunks.

Ejemplo: La respuesta generada tiene 5 claims. El judge determina que 4 están en los chunks y 1 es una extrapolación sin respaldo.

$$\text{Faithfulness} = \frac{4}{5} = 0{,}80$$

Señal de alarma: faithfulness < 0,85 indica que el LLM está generando contenido que va más allá del contexto — es decir, está alucinando con respaldo superficial.

2. Answer Relevance — relevancia de la respuesta

Pregunta: ¿la respuesta realmente responde a la pregunta formulada?

Intuición: Una respuesta que responde bien a la pregunta “implica” esa pregunta. Si generas N preguntas hipotéticas a partir de la respuesta y mides su similitud semántica con la pregunta original, obtienes una señal de relevancia.

Cálculo:

$$\text{AnswerRelevance} = \frac{1}{N} \sum_{i=1}^{N} \cos(\vec{q}{\text{original}}, \vec{q}{i}^{\text{generada}})$$

donde $\vec{q}$ son embeddings de las preguntas.

Ejemplo: Para la pregunta “¿Qué versiones de Python soporta FastAPI?” y una respuesta sobre frameworks web en general, las preguntas hipotéticas generadas versarán sobre “¿cuáles son los mejores frameworks web?” — coseno bajo con la pregunta original → answer relevance baja.

3. Context Precision — precisión del retrieval

Pregunta: de los K chunks recuperados, ¿qué proporción son realmente relevantes?

Cálculo (versión weighted):

$$\text{ContextPrecision@K} = \frac{\sum_{k=1}^{K} \text{Precision@}k \cdot \mathbb{1}[\text{chunk}_k \text{ es relevante}]}{|\text{chunks relevantes en top-K}|}$$

La forma más directa: el judge LLM clasifica cada chunk como relevante o no para responder la pregunta. La precisión es la fracción relevante.

Ejemplo: Se recuperan 5 chunks. El judge considera que 3 son relevantes y 2 son ruido.

$$\text{ContextPrecision} = \frac{3}{5} = 0{,}60$$

Señal de alarma: precision < 0,6 indica que el retrieval está contaminando el contexto con información que puede contradecir o diluir la respuesta correcta.

4. Context Recall — recall del retrieval

Pregunta: de todos los hechos necesarios para construir la respuesta correcta (ground-truth), ¿qué proporción están cubiertos por los chunks recuperados?

Cálculo:

$$\text{ContextRecall} = \frac{|\text{claims del ground-truth atribuibles a algún chunk}|}{|\text{total claims en ground-truth}|}$$

Esta métrica requiere ground-truth, es decir, necesitas el golden dataset.

Ejemplo: El ground-truth tiene 6 afirmaciones. Los chunks recuperados cubren 5 de ellas; la sexta está en un documento que el retrieval no encontró.

$$\text{ContextRecall} = \frac{5}{6} \approx 0{,}83$$

5. Noise Sensitivity — sensibilidad al ruido

Pregunta: si introduces chunks irrelevantes en el contexto, ¿cómo cae la faithfulness?

Se calcula como la diferencia de faithfulness entre la condición limpia y la condición con ruido controlado:

$$\Delta\text{Faithfulness} = \text{Faithfulness}{\text{limpio}} - \text{Faithfulness}{\text{ruidoso}}$$

Un $\Delta > 0{,}15$ indica que el prompt o el LLM son frágiles ante contextos contaminados — problema que context precision baja convierte en rutinario.

Ejemplo numérico completo

Escenario

Pregunta: “¿Qué garantías de latencia ofrece Redis para operaciones de lectura en memoria con un dataset de 10 GB?”

Respuesta generada por el RAG:

“Redis garantiza latencias sub-milisegundo para operaciones GET en datasets que caben en RAM. Con 10 GB de dataset y clientes en la misma red local, P99 está típicamente por debajo de 1 ms. Redis también soporta clustering horizontal para escalar más allá de la RAM de un nodo. Además, Redis incluye soporte nativo para JSON desde la versión 7.2.”

Ground-truth (respuesta de referencia):

“Redis opera completamente en memoria, lo que garantiza latencias sub-milisegundo para GET. En redes locales con datasets de 10 GB en RAM, el P99 se sitúa por debajo de 1 ms. El clustering permite escalar más allá de la RAM de un único nodo.”

Chunks recuperados (5 chunks, fragmentos resumidos):

#	Contenido resumido	Relevante
C1	“Redis opera en memoria; GET tiene latencias < 1 ms en LAN”	Sí
C2	“Redis Cluster permite sharding para escalar la RAM total”	Sí
C3	“Redis Sentinel gestiona alta disponibilidad mediante failover automático”	No
C4	“Benchmarks de Redis: P50 = 0,3 ms, P99 = 0,9 ms en 10 GB dataset”	Sí
C5	“Redis Stack añade módulos: RedisJSON, RediSearch, RedisTimeSeries”	No

Cálculo paso a paso

Faithfulness:

Claims en la respuesta generada:

“Redis garantiza latencias sub-milisegundo para GET en datasets en RAM” → soportado por C1, C4
“Con 10 GB en LAN, P99 < 1 ms” → soportado por C4
“Redis soporta clustering horizontal para escalar RAM” → soportado por C2
“Redis incluye soporte nativo para JSON desde la versión 7.2” → NO soportado por ningún chunk (C5 menciona RedisJSON como módulo de Redis Stack, no como nativo de Redis core)

$$\text{Faithfulness} = \frac{3}{4} = 0{,}75$$

El claim 4 es una extrapolación que mezcla información de C5 de forma imprecisa — alucinación parcial.

Context Precision:

Chunks relevantes: C1, C2, C4 (3 de 5).

$$\text{ContextPrecision} = \frac{3}{5} = 0{,}60$$

C3 y C5 son ruido. C5 en particular contribuyó a la alucinación parcial sobre JSON.

Context Recall:

Claims del ground-truth:

“Redis opera en memoria, GET < 1 ms” → atribuible a C1 ✓
“P99 < 1 ms en LAN con 10 GB” → atribuible a C4 ✓
“Clustering escala más allá de la RAM de un nodo” → atribuible a C2 ✓

$$\text{ContextRecall} = \frac{3}{3} = 1{,}00$$

El retrieval encontró todos los chunks necesarios para el ground-truth. El problema no es recall sino precision (C3, C5 contaminaron el contexto).

Answer Relevance:

El judge genera 3 preguntas hipotéticas a partir de la respuesta:

“¿Qué latencias ofrece Redis para lecturas en memoria?” — cos = 0,91
“¿Cómo escala Redis horizontalmente?” — cos = 0,74
“¿Qué módulos JSON incluye Redis?” — cos = 0,52 (deriva de la alucinación)

$$\text{AnswerRelevance} = \frac{0{,}91 + 0{,}74 + 0{,}52}{3} = 0{,}72$$

La derivación hacia JSON redujo la relevancia. Una respuesta más ajustada habría obtenido ~0,90.

Resumen del ejemplo

Métrica	Valor	Diagnóstico
Faithfulness	0,75	LLM extrapoló más allá del contexto
Context Precision	0,60	Retrieval devolvió 2 chunks irrelevantes
Context Recall	1,00	Retrieval capturó todo lo necesario
Answer Relevance	0,72	Respuesta desvía el tema

Acción correctiva principal: mejorar el reranker para filtrar C3 y C5 antes de que lleguen al LLM. El problema de faithfulness y relevance es consecuencia directa de la baja precision, no del LLM en sí.

Construcción del golden dataset

Qué es y por qué importa

El golden dataset es un conjunto de tuplas (pregunta, chunks relevantes, respuesta correcta) que actúa como calibrador de referencia. Sin él, context recall no se puede calcular (no hay ground-truth) y las demás métricas carecen de ancla interpretativa: ¿0,75 de faithfulness es bueno o malo para este corpus y este dominio?

Un golden dataset bien construido permite:

Comparar versiones del pipeline (embedder v1 vs v2, chunk size 512 vs 1024)
Detectar regresiones en CI antes de desplegar
Estratificar el análisis por tipo de pregunta

Pipeline de construcción asistida por LLM

La construcción manual pura es cara. El patrón estándar en 2026 es asistencia LLM con revisión humana de muestra:

Paso 1 — Selección de chunks semilla. Del corpus total, seleccionar chunks representativos mediante muestreo estratificado (por sección, fecha, tipo de documento). Para un corpus técnico de 10.000 chunks, 500-1.000 semillas es un punto de partida razonable.

Paso 2 — Generación de preguntas. Un LLM potente (Llama-3.1-70B o similar) genera 2-3 preguntas por chunk semilla usando un prompt del tipo:

Dado el siguiente fragmento de documentación, genera preguntas específicas
que solo puedan responderse correctamente usando ESTE fragmento y no
conocimiento general. Las preguntas deben ser las que haría un ingeniero
buscando información operativa.
Fragmento: {chunk}

Paso 3 — Generación de respuestas de referencia. El mismo LLM, con acceso al chunk semilla (y a chunks adyacentes si la pregunta lo requiere), genera la respuesta de referencia.

Paso 4 — Revisión humana de muestra. Revisar manualmente el 10-20 % del dataset generado. Los criterios de rechazo más comunes: preguntas triviales que cualquier LLM responde sin el corpus, respuestas que el LLM rellenó con conocimiento paramétrico en lugar de los chunks, y preguntas mal formuladas o ambiguas.

Tamaño mínimo

Caso de uso	Pares mínimos	Notas
Prototipo / validación inicial	50-100	Suficiente para detectar problemas gruesos
Corpus técnico en producción	200-500	Permite estratificación básica
Producción robusta con estratificación completa	500-1.000+	Necesario para detectar regresiones sutiles

Estratificación del dataset

Un golden dataset plano mide el promedio pero oculta los casos extremos. La estratificación mínima recomendada incluye tres tipos de preguntas:

Fáciles (single-hop): Un único chunk contiene toda la información necesaria. El baseline que cualquier RAG decente debe superar.
Difíciles (multi-hop): La respuesta correcta requiere combinar información de 2-4 chunks diferentes. Aquí se detectan los límites del reranker y del prompt de síntesis.
Adversariales: La pregunta tiene una premisa falsa, o el corpus no contiene la respuesta. El RAG correcto debe responder “no tengo información suficiente” — un RAG frágil alucina con confianza. Este tipo de pregunta mide directamente el riesgo de alucinación de alto impacto.

La trampa de Goodhart

“Cuando una medida se convierte en objetivo, deja de ser una buena medida.” — Charles Goodhart

Si optimizas el embedder o el reranker usando el golden dataset como función de pérdida, el dataset se corrompe como métrica: el sistema aprende a rendir bien en esas preguntas específicas sin mejorar en el dominio general.

La solución es la misma que en ML supervisado: separar dev set (para optimización e iteración) de test set (para evaluación final, congelado y auditado). El test set nunca debe usarse para tomar decisiones de diseño; solo para reportar el estado del sistema en releases.

Correlación con satisfacción real

Los estudios de campo publicados por los equipos de Databricks (2024) y los análisis de adopción de RAGAS (2025) apuntan a umbrales operativos interpretables:

Rango de métrica	Síntoma observable	Acción correctiva
Faithfulness < 0,75	Usuarios reportan “respuestas inventadas” con frecuencia	Revisar el prompt del LLM; aumentar instrucciones de cita; reducir temperatura
Faithfulness 0,75-0,85	Alucinaciones ocasionales en topics periféricos	Mejorar context precision para eliminar chunks contaminantes
Faithfulness ≥ 0,85	Correlaciona con NPS positivo en estudios de campo	Mantener; monitorear deriva
Context Precision < 0,60	LLM incluye información contradictoria; respuestas inconsistentes	Ajustar el reranker; reducir K; revisar umbrales de similitud
Context Recall < 0,70	Preguntas multi-hop fallidas; información clave ausente	Revisar el chunking strategy; añadir chunks de mayor tamaño; enriquecer metadatos
Answer Relevance < 0,70	Respuestas “correctas pero que no responden”	Revisar el prompt de síntesis; añadir instrucción explícita de adherencia a la pregunta

La context precision baja es especialmente perniciosa: chunks irrelevantes no son neutrales. Aumentan la probabilidad de que el LLM use información incorrecta como si fuera relevante, degradando faithfulness de forma encadenada. Es la transmisión por la que un problema de retrieval se convierte en un problema de LLM.

Diagrama: el bucle de evaluación continua

El bucle de evaluación continua: corpus → retrieval → LLM → RAGAS judge → métricas → alerta → acción correctiva → corpus.

Stack OSS 2026 para ejecutar RAGAS on-premise

ragas (Apache 2.0)

La librería ragas soporta evaluación asíncrona y múltiples backends de LLM. La integración con vLLM como judge elimina la necesidad de enviar datos a APIs externas — crítico en entornos con datos sensibles.

from ragas import evaluate
from ragas.metrics import (
 faithfulness,
 answer_relevancy,
 context_precision,
 context_recall,
)
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

# Judge LLM apuntando a vLLM on-premise
judge_llm = ChatOpenAI(
 model="meta-llama/Llama-3.1-70B-Instruct",
 base_url="http://vllm-service:8000/v1",
 api_key="sk-local", # vLLM ignora el valor pero requiere el campo
)

embeddings = OpenAIEmbeddings(
 model="BAAI/bge-m3",
 base_url="http://embedding-service:8001/v1",
 api_key="sk-local",
)

result = evaluate(
 dataset=golden_dataset, # HuggingFace Dataset con columnas estándar
 metrics=[faithfulness, answer_relevancy, context_precision, context_recall],
 llm=judge_llm,
 embeddings=embeddings,
)

El dataset esperado por RAGAS tiene cuatro columnas: question, answer, contexts (lista de strings), ground_truth.

Langfuse para trazabilidad de evals

Cada evaluación RAGAS se registra en Langfuse como un dataset experiment, vinculando los scores a los spans de producción (ver https://blog.lo0.es/posts/tracing-llm-otel-genai/). Esto permite correlacionar una caída de faithfulness con el request específico que la provocó — sin esta vinculación, las métricas son números sin contexto accionable.

from langfuse import Langfuse

lf = Langfuse()

# Crear o recuperar el dataset en Langfuse
dataset = lf.get_or_create_dataset("rag-golden-v3")

# Registrar scores del experiment
for idx, row in result.to_pandas().iterrows():
 lf.score(
 name="ragas-faithfulness",
 value=row["faithfulness"],
 trace_id=row["trace_id"], # vinculado al span de producción
 )

Prometheus + Grafana para alertas operativas

Las métricas RAGAS se exponen como gauges de Prometheus. Un dashboard de Grafana con umbrales configura alertas cuando faithfulness cae sostenidamente por debajo de 0,80:

# regla de alerta Prometheus
- alert: RAGFaithfulnessLow
 expr: avg_over_time(rag_faithfulness_score[30m]) < 0.80
 for: 10m
 labels:
 severity: warning
 annotations:
 summary: "RAG faithfulness por debajo de umbral ({{ $value | humanize }})"
 description: "Revisar context precision y reranker. Posible deriva del corpus."

Corriendo RAGAS contra vLLM on-premise — consideraciones prácticas

Tamaño del judge: Llama-3.1-70B como judge produce resultados comparables a GPT-4 en faithfulness y context evaluation, según los benchmarks de RAGAS 0.2 (2025). Modelos más pequeños (8B-13B) degradan la calidad del judge en preguntas multi-hop.
Throughput: En hardware on-premise con 4×H100 SXM (320 GB, NVLink), un run de 200 evaluaciones con Llama-3.1-70B tarda aproximadamente 8-12 minutos con batch_size=8 y vLLM en modo continuous batching.
Coste por evaluación: Sin API externa, el coste marginal es electricidad + amortización de GPU. Con 4×H100 a ~3 kW sostenidos, un run de 200 evaluaciones cuesta < 0,10 € en energía a tarifa industrial típica.
Frecuencia recomendada: eval offline semanal sobre el golden dataset completo + eval online muestreada (5-10 % de requests de producción) con un subconjunto de métricas que no requieren ground-truth (faithfulness, answer relevance).

Lo que no hemos cubierto

Alternativas a RAGAS: TruLens (evaluación con feedbacks modulares), DeepEval (aserciones programáticas, integración con pytest), ARES (framework de Stanford con trained classifiers en lugar de LLM-as-judge), y el framework de evals de OpenAI. Cada uno tiene trade-offs distintos en coste de judge, fiabilidad y facilidad de integración.
Continuous eval en producción: muestrear automáticamente requests reales, anonimizarlos, ejecutar un subconjunto de métricas sin ground-truth y usar el resultado para detectar deriva del sistema antes de que los usuarios lo reportan. Requiere un pipeline de datos separado del pipeline de inferencia.
Eval multilingüe: RAGAS con un judge en español o catalán sobre corpus no inglés tiene sesgos documentados cuando el judge es un modelo fundamentalmente entrenado en inglés. Los embeddings de similitud semántica para answer relevance son especialmente sensibles al idioma del corpus vs. idioma del judge.
A/B testing de configuraciones RAG: usar las métricas RAGAS como criterio de éxito en experimentos controlados — chunk size 512 vs. 1024, BM25 puro vs. hybrid, reranker cross-encoder vs. biencoder — con significancia estadística calculada sobre el golden dataset.

Ver también

https://blog.lo0.es/posts/llm-as-judge-fundamentos/ — el patrón de juez LLM que RAGAS usa para medir faithfulness claim a claim
https://blog.lo0.es/posts/evals-llm-la-capa-despues-de-tracing/ — el marco general de evals donde RAGAS es la especialización RAG
https://blog.lo0.es/posts/rag-reranker-hybrid-retrieval-fundamentos/ — la capa de retrieval cuya context precision y recall miden estas métricas
https://blog.lo0.es/posts/rag-corpus-curation-fundamentos/ — la calidad del corpus que context recall refleja
https://blog.lo0.es/posts/tracing-llm-otel-genai/ — los spans de producción donde Langfuse anota los scores RAGAS
https://blog.lo0.es/posts/data-versioning-dvc-lakefs/ — el golden dataset es un artefacto data que necesita versioning igual que el corpus

Referencias

Es Shahul, et al. RAGAS: Automated Evaluation of Retrieval Augmented Generation. arXiv:2309.15217 (2023). https://arxiv.org/abs/2309.15217
RAGAS Documentation v0.2. Metrics Reference. https://docs.ragas.io/en/stable/concepts/metrics/ (consultado junio 2026)
Langfuse. Dataset Experiments. https://langfuse.com/docs/datasets/overview (consultado junio 2026)
Databricks. LLM Quality Evaluation: From Lab to Production. Databricks Engineering Blog (2024).
Saad-Falcon, J. et al. ARES: An Automated Evaluation Framework for Retrieval-Augmented Generation Systems. arXiv:2311.09476 (2023).
Goodhart, C.A.E. Problems of Monetary Management: The U.K. Experience. Papers in Monetary Economics. Reserve Bank of Australia (1975). Formulación moderna de la ley que lleva su nombre.
vLLM Project. OpenAI-Compatible Server. https://docs.vllm.ai/en/stable/serving/openai_compatible_server.html (consultado junio 2026)