retriEVAL

LLM 평가를 MCP 서버로 제공합니다. 파이프라인이나 테스트 하네스 없이, 어떤 MCP 클라이언트에서든 AI 출력의 충실성(faithfulness), 관련성(relevancy), 환각(hallucination)을 평가하세요. 모든 결과에는 기록을 유지하는 대시보드 링크가 함께 제공됩니다.

라이브 체험 (가입 불필요) · 2분 데모 보기 · 대시보드

왜 필요한가

고객 지원 답변 5개를 두 가지 지표로 평가한 결과:

모든 답변은 주제에 맞고 잘 작성되었습니다. 그중 두 개는 근거로 삼았다고 주장하는 정책과 모순됩니다. 하나는 정책이 제공하지 않는 무료 반품 배송을 약속했고, 다른 하나는 무료 익일 교체를 지어냈습니다. 육안으로 검토하면 다섯 개 모두 승인했을 것입니다.

그 차이가 핵심입니다. 관련성은 질문에 답했는가를 묻고, 충실성은 실제로 출처에 있는 내용인가를 묻습니다. 둘 다 필요하며, 두 번째가 비용이 많이 드는 실패를 잡아냅니다.

Related MCP server: mcp-llm-eval

연결

자체 호스팅. 클론하고, 판정기(judge)에 연결하고, 실행하세요. 데이터가 머신을 떠나지 않으며 가입할 서비스도 없습니다.

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

그런 다음 이렇게 요청하세요:

다음 사례를 faithfulness로 평가해 줘: [{"input": "...", "actual_output": "...", "retrieval_context": ["..."]}]

사례를 인라인으로 전달하면 아무것도 저장되지 않습니다. 한 번의 호출, 설정 단계 없음. 클라이언트 구성은 로컬 실행 (stdio)을, 대시보드가 있는 항상 켜진 인스턴스를 원한다면 HTTP로 배포를 참조하세요.

설치 전에 먼저 시도해 보시겠어요? retrieval-mcp.com에 라이브 샌드박스가 있습니다. 가입 불필요, 무료 판정기로 실행, 아무것도 저장되지 않습니다.

모든 것을 로컬로 유지: RETRIEVAL_JUDGE_BACKEND=ollama로 설정하면 판정기도 사용자 머신에서 실행되므로 어떤 시점에도 데이터가 네트워크를 떠나지 않습니다. 제3자에게 보낼 수 없는 것을 평가할 때 유용합니다.

제공 기능

• 9가지 기본 제공 지표 및 일반 영어로 작성하는 사용자 정의 지표

• 교체 가능한 판정기 — Anthropic, Groq, Gemini, OpenRouter 또는 로컬 Ollama 모델. 네트워크 밖으로 나갈 필요가 없습니다.

• 골든 세트 — 파일, URL, 인라인 JSON, JSONL, CSV 또는 TSV에서 로드

• Supabase의 실행 기록 — 공유 가능한 영구 링크 및 실행 비교

• 지출 상한 — 판정기 기반 도구는 그렇지 않으면 비용이 많이 나올 수 있기 때문입니다.

솔직한 한계

• 판정기 일치도가 아직 인간 라벨로 검증되지 않았으므로 점수를 참고 신호로 취급하세요. 절대적 진실로 보지 마세요.

• 골든 세트는 현재 자체 출력을 보유하므로 새 모델 출력에 대해 다시 실행하려면 두 번째 세트를 로드해야 합니다. 분리하는 것이 다음 변경 사항입니다.

• 골든 세트와 작성된 지표는 서버 프로세스에 저장되며 재시작 시 손실됩니다. 실행 기록은 유지되지만 이들은 유지되지 않습니다.

지표 (DeepEval 정렬)

faithfulness · answer_relevancy · contextual_precision · contextual_recall · contextual_relevancy · hallucination · bias · toxicity · summarization — 그리고 일반 언어로 정의하는 작성된 G-Eval 지표. 모두 정규화되어 높을수록 좋음 (bias/toxicity는 깨끗한 비율 보고), 각 지표는 점수 매기기 전에 추론합니다.

다재다능한 골든 세트

load_golden_set은 파일 경로 (업로드된 파일 포함), http(s) URL, 인라인 JSON 배열 또는 JSONL 텍스트를 JSON / JSONL / CSV / TSV 형식으로 허용합니다. 필드 이름은 자동으로 정규화됩니다 (question→input, answer→actual_output, ground_truth→expected_output, contexts→context, passages→retrieval_context, …). 따라서 대부분의 공개 벤치마크를 그대로 로드할 수 있습니다.

기본적으로 짧은 답변

run_eval은 모든 사례를 평가하지만 기본적으로 가장 낮은 점수의 3개만 반환합니다 (limit으로 조정 가능). total_cases/shown 및 나머지를 페이지로 넘기기 위한 show_run_cases(run_id, offset, limit, metric) 포인터가 포함됩니다.

지출 상한 (비용 폭주 방지)

판정기 지출은 실제 토큰 사용량에서 측정되어 유지됩니다. 하드 상한을 설정하세요:

export RETRIEVAL_BUDGET_USD=20     # 0/unset = unlimited

누적 지출이 상한에 도달하면 추가 Anthropic 호출이 중지되고 도구는 명확한 budget_exceeded 메시지를 반환합니다. get_budget / reset_budget으로 확인/재설정하세요. (가격은 근사치입니다. 모델의 현재 가격에 맞게 RETRIEVAL_PRICE_IN/OUT $/1M 토큰을 재정의하세요.)

하이브리드 설정 (로컬 + 항상 켜진 대시보드)

실행 기록은 플러그형 저장소를 사용하며, 환경 변수로 선택됩니다:

• FileStore (기본값) — ~/.retrieval의 JSONL. 설정 없음, 로컬 전용.

• SupabaseStore — SUPABASE_URL + SUPABASE_SERVICE_KEY가 설정된 경우. 실행 기록은 Postgres에 저장되며 로컬 CLI, 배포된 MCP, 웹사이트 대시보드가 공유합니다.

권장 하이브리드 흐름:

1. Supabase에서 supabase_schema.sql을 실행합니다 (runs 테이블 생성).

2. MCP (로컬 및/또는 Railway)에 SUPABASE_URL + SUPABASE_SERVICE_KEY를 설정하여 모든 실행이 중앙에 기록되도록 합니다. 각 실행은 generator_model과 judge_model을 기록하여 모델 간 비교를 지원합니다.

3. web/을 Vercel에 배포하고 (동일한 Supabase 환경 변수 설정) retrieval-mcp.com에 매핑합니다. 대시보드는 /api/runs를 통해 기록을 읽고 (서비스 키는 서버 측에 유지) 모델별 추세, 모델 리더보드, 실행 기록을 렌더링합니다. Supabase가 연결될 때까지 샘플 데이터를 표시합니다.

로컬은 무료 샌드박스로 유지되고 (Ollama 판정기, 파일 기록), 웹사이트는 공유 기록에 대한 항상 켜진 창입니다.

로컬 실행 (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" }
    }
  }
}

그런 다음: "examples/rag_golden.jsonl을 'space'로 로드하고, faithfulness를 실행하고, v1로 라벨링해 줘."

HTTP로 배포 (어디서든 접근)

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

Railway (또는 다른 호스트)에 배포하세요: 포함된 Dockerfile / Procfile이 그대로 작동합니다. 호스트 환경에 ANTHROPIC_API_KEY, RETRIEVAL_TOKEN, RETRIEVAL_BUDGET_USD를 설정하세요. 클라이언트는 Authorization: Bearer <token> 헤더와 함께 https://<host>/mcp에 연결합니다. claude.ai / Claude Desktop에서 사용자 지정 커넥터로 추가하거나 Agent Builder / CI에서 연결하세요. 상태 (골든 세트, 실행 기록, 지출)는 서버 측에 저장되므로 머신 간에 유지됩니다.

실제 RAG 파이프라인에서 보기 (데모)

demo/rag_demo.py는 작은 라벨링된 데이터셋 (demo/labeled.json + demo/corpus.json) 위에 소규모 엔드투엔드 RAG를 구축합니다: BM25로 검색하고, 골드 패시지에 대해 recall@k를 계산하고 (결정적 — 검색기의 점수), 답변을 생성한 다음 faithfulness를 평가합니다 (생성기의 점수). 하나의 답변은 의도적으로 환각을 포함하므로 두 실패 모드가 분리되는 것을 볼 수 있습니다.

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

또한 demo/generated_goldenset.jsonl을 작성합니다. 이를 MCP에 로드 (load_golden_set → run_eval)하여 판정기 점수 버전을 얻으세요. 이것이 다리입니다: 파이프라인이 예측을 생성하고, 데이터셋이 라벨을 제공하며, RetriEval이 검색기와 생성기를 독립적으로 평가합니다.

RAG 파이프라인 연결

• 오프라인 (기본값): 파이프라인의 검색 컨텍스트 + 답변을 골든 세트로 내보내고 평가하세요. RetriEval은 파이프라인을 건드리지 않습니다.

• 라이브: RAG 엔드포인트 또는 벡터 저장소 (Chroma / Supabase pgvector)를 호출하는 query_rag(question) 도구를 추가하고, 컨텍스트 + 답변을 캡처하여 한 번에 평가합니다.

판정기 백엔드

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

도구

라이선스

Apache License 2.0. Hanns Carrillo 제작.