retriEVAL

Evaluación de LLM como servidor MCP. Puntúa las salidas de tu IA en cuanto a fidelidad, relevancia y alucinación desde cualquier cliente MCP, sin pipeline ni banco de pruebas. Cada resultado incluye un enlace a un panel que conserva el historial.

Pruébalo en vivo (sin registro) · Mira la demo de 2 minutos · Panel

Por qué

Cinco respuestas de atención al cliente, puntuadas en dos métricas:

Todas las respuestas eran pertinentes y estaban bien redactadas. Dos de ellas contradecían la política en la que supuestamente se basaban: una prometía envío de devolución gratuito que la política no ofrece, y otra inventaba un reemplazo gratuito al día siguiente. Si las revisaras a simple vista, aprobarías las cinco.

Esa brecha es el punto. La relevancia pregunta ¿respondió a la pregunta?. La fidelidad pregunta ¿está realmente en la fuente?. Necesitas ambas, y la segunda detecta los fallos costosos.

Related MCP server: mcp-llm-eval

Conectar

Autohospedado. Clónalo, apúntalo a un juez, ejecútalo: tus datos nunca salen de tu máquina y no hay ningún servicio al que registrarse.

git clone https://github.com/hcarrillo001/retrieval-mcp
cd retrieval-mcp
pip install -r requirements.txt

export ANTHROPIC_API_KEY=sk-ant-...        # or a local judge, below
python server.py                            # stdio, for Claude Desktop / Cursor

Luego solo pregunta:

Score these cases with faithfulness: [{"input": "...", "actual_output": "...", "retrieval_context": ["..."]}]

Pasa tus casos en línea y no se almacena nada: una llamada, sin paso de configuración. Consulta Ejecutar localmente (stdio) para la configuración del cliente, y Desplegar como HTTP si quieres tu propia instancia siempre activa con un panel.

¿Quieres probarlo antes de instalar nada? Hay un sandbox en vivo en retrieval-mcp.com — sin registro, funciona con un juez gratuito, no se guarda nada.

Manteniendo todo local: establece RETRIEVAL_JUDGE_BACKEND=ollama y el juez también se ejecuta en tu máquina, de modo que ningún dato sale de tu red en ningún momento. Útil si estás evaluando algo que no puedes enviar a un tercero.

Lo que obtienes

• 9 métricas integradas más métricas personalizadas que puedes crear en inglés sencillo

• Jueces intercambiables — Anthropic, Groq, Gemini, OpenRouter o un modelo local de Ollama, para que nada tenga que salir de tu red

• Conjuntos dorados desde archivos, URLs, JSON en línea, JSONL, CSV o TSV

• Historial de ejecuciones en Supabase con enlaces permanentes compartibles y comparación de ejecuciones

• Un límite de gasto, porque una herramienta basada en jueces puede generar una factura elevada

Limitaciones honestas

• La concordancia del juez aún no se ha validado contra etiquetas humanas, así que trata las puntuaciones como una señal, no como una verdad absoluta.

• Los conjuntos dorados actualmente contienen sus propias salidas, por lo que volver a ejecutarlos contra nuevas salidas de modelo implica cargar un segundo conjunto. Separarlos es el próximo cambio.

• Los conjuntos dorados y las métricas creadas viven en el proceso del servidor y se pierden al reiniciar. Las ejecuciones persisten; esos no.

Métricas (alineadas con DeepEval)

faithfulness · answer_relevancy · contextual_precision · contextual_recall · contextual_relevancy · hallucination · bias · toxicity · summarization — además de métricas G-Eval creadas que defines en lenguaje sencillo. Todas están normalizadas para que más alto = mejor (bias/toxicity informan la fracción limpia), y cada una razona antes de puntuar.

Conjuntos dorados versátiles

load_golden_set acepta una ruta de archivo (incluidos archivos subidos), una URL http(s), un array JSON en línea o texto JSONL, en JSON / JSONL / CSV / TSV. Los nombres de campo se normalizan automáticamente (question→input, answer→actual_output, ground_truth→expected_output, contexts→context, passages→retrieval_context, …), por lo que la mayoría de los benchmarks públicos se cargan tal cual.

Respuestas cortas por defecto

run_eval puntúa cada caso pero devuelve solo los 3 de menor puntuación por defecto (ajusta con limit), con total_cases/shown y un puntero a show_run_cases(run_id, offset, limit, metric) para paginar el resto.

Límite de gasto (para que no genere una factura elevada)

El gasto del juez se mide a partir del uso real de tokens y se persiste. Establece un límite máximo:

export RETRIEVAL_BUDGET_USD=20     # 0/unset = unlimited

Una vez que el gasto acumulado alcanza el límite, las llamadas adicionales a Anthropic se detienen y las herramientas devuelven un mensaje claro de budget_exceeded. Consulta/limpia con get_budget / reset_budget. (Los precios son aproximados: anula RETRIEVAL_PRICE_IN/OUT $/1M tokens para ajustarlos al precio actual de tu modelo).

Configuración híbrida (local + panel siempre activo)

El historial de ejecuciones utiliza un almacén conectable, elegido por env:

• FileStore (predeterminado) — JSONL en ~/.retrieval. Sin configuración, solo local.

• SupabaseStore — cuando se establecen SUPABASE_URL + SUPABASE_SERVICE_KEY. El historial de ejecuciones vive en Postgres, compartido por la CLI local, el MCP desplegado y el panel del sitio web.

Flujo híbrido recomendado:

1. Ejecuta supabase_schema.sql en Supabase (crea la tabla runs).

2. Establece SUPABASE_URL + SUPABASE_SERVICE_KEY en el MCP (local y/o Railway) para que cada ejecución se escriba de forma centralizada. Cada ejecución registra su generator_model y judge_model para comparación entre modelos.

3. Despliega web/ en Vercel (establece las mismas variables de entorno de Supabase) y asígnalo a retrieval-mcp.com. El panel lee el historial a través de /api/runs (la clave de servicio permanece en el servidor) y muestra tendencia por modelo, una tabla de clasificación de modelos e historial de ejecuciones. Muestra datos de muestra hasta que Supabase esté conectado.

Lo local sigue siendo tu sandbox gratuito (juez Ollama, historial de archivos); el sitio web es la ventana siempre activa al historial compartido.

Ejecutar localmente (stdio) — Claude Desktop

pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...

{
  "mcpServers": {
    "retrieval": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/server.py"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-...", "RETRIEVAL_BUDGET_USD": "10" }
    }
  }
}

Luego: "Carga examples/rag_golden.jsonl como 'space', ejecuta faithfulness, etiquétalo como v1."

Desplegar como HTTP (accede desde cualquier lugar)

export RETRIEVAL_TOKEN=$(openssl rand -hex 24)   # required for a public endpoint
export ANTHROPIC_API_KEY=sk-ant-...
export RETRIEVAL_BUDGET_USD=20
python app.py        # serves $PORT (default 8000); MCP at /mcp, health at /healthz

Despliega en Railway (o cualquier host): el Dockerfile / Procfile incluidos funcionan tal cual. Establece ANTHROPIC_API_KEY, RETRIEVAL_TOKEN, RETRIEVAL_BUDGET_USD en el entorno del host. Los clientes se conectan a https://<host>/mcp con el encabezado Authorization: Bearer <token> — agrégalo como conector personalizado en claude.ai / Claude Desktop, o apunta Agent Builder / CI hacia él. El estado (conjuntos dorados, historial de ejecuciones, gasto) vive en el servidor, por lo que persiste entre máquinas.

Míralo en un pipeline RAG real (demo)

demo/rag_demo.py construye un RAG de extremo a extremo diminuto sobre un pequeño conjunto de datos etiquetado (demo/labeled.json + demo/corpus.json): recupera con BM25, calcula recall@k contra los pasajes dorados (determinista — la puntuación del recuperador), genera una respuesta y luego puntúa la fidelidad (la puntuación del generador). Una respuesta está deliberadamente alucinada para que veas separarse los dos modos de fallo.

python demo/rag_demo.py            # offline, no key needed
python demo/rag_demo.py --real     # real generation + RetriEval judge (needs ANTHROPIC_API_KEY)

También escribe demo/generated_goldenset.jsonl — carga eso en el MCP (load_golden_set → run_eval) para la versión puntuada por el juez. Este es el puente: tu pipeline emite predicciones, el conjunto de datos proporciona las etiquetas y RetriEval puntúa al recuperador y al generador de forma independiente.

Conectando a un pipeline RAG

• Sin conexión (predeterminado): exporta el contexto recuperado + la respuesta de tu pipeline a un conjunto dorado y púntalo — RetriEval nunca toca tu pipeline.

• En vivo: agrega una herramienta query_rag(question) que llame a tu endpoint RAG o a tu almacén vectorial (Chroma / Supabase pgvector), capture contexto + respuesta y puntúe de una sola vez.

Backend del juez

export RETRIEVAL_JUDGE_BACKEND=anthropic          # default
export RETRIEVAL_JUDGE_MODEL=claude-sonnet-4-6
# or local, free:
export RETRIEVAL_JUDGE_BACKEND=ollama
export RETRIEVAL_JUDGE_MODEL=deepseek-r1:70b

Herramientas

Licencia

Apache License 2.0. Creado por Hanns Carrillo.