retriEVAL

retriEVAL

作为 MCP 服务的大模型评估。 在任意 MCP 客户端中评估 AI 输出的忠实度、相关性和幻觉情况——无需工作流或测试框架。每次评估结果都会附上仪表板链接，便于查看历史记录。

立即体验（无需注册） · 观看 2 分钟演示 · 仪表板

---

为什么需要它

以下是 5 个客服答复在两项指标上的评分：

指标	分数	达标数
answer_relevancy	0.98	5/5
faithfulness	0.70	3/5

所有答复都切合主题，表达得也很好。但其中两条与其声称依据的政策相矛盾——一条承诺政策并未提供的免费退货运费，另一条则编造了免费隔夜换货服务。人工逐条审查时，你可能会认可这 5 条答复。

问题就在于这个差距。相关性关注的是是否回答了问题。忠实度关注的是内容是否确实来自源材料。两者都不可或缺，而后者能发现代价高昂的错误。

连接

可自托管。克隆项目，指定评审模型并运行即可——数据不会离开你的机器，也无需注册任何服务。

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，评审模型也会在你的机器上运行，因此数据在任何时候都不会离开你的网络。适合评估任何不能发送给第三方的内容。

你将获得

• 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)。

支出上限（避免账单过高）

Judge 的费用根据实际 Token 用量计费并持久化。设置硬性上限：

export RETRIEVAL_BUDGET_USD=20     # 0/unset = unlimited

累计支出达到上限后，将停止后续 Anthropic 调用，工具会返回清晰的 budget_exceeded 消息。使用 get_budget / reset_budget 检查或清除预算。（价格为近似值——可覆盖 RETRIEVAL_PRICE_IN/OUT，单位为每 1M Token 的 $，以匹配当前模型定价。）

混合部署（本地 + 全天候运行的仪表板）

运行历史使用可插拔存储，按环境变量选择：

• 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 judge、文件历史记录）；网站则是查看共享历史记录的全天候窗口。

本地运行（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 检索，通过 gold 段落计算 recall@k（确定性结果——即检索器的评分），生成答案，然后评估忠实度（即生成器的评分）。其中一个答案故意包含幻觉，让你观察两种失败模式如何区分。

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），即可获得由 judge 评分的版本。这就是衔接方式：你的流水线输出预测结果，数据集提供标签，RetriEval 分别对检索器和生成器评分。

连接到 RAG 流水线

• 离线（默认）： 将流水线检索到的上下文和答案导出到黄金集并进行评分——RetriEval 完全不会接触你的流水线。
• 实时： 添加一个 query_rag(question) 工具，用于调用你的 RAG 端点或向量存储（Chroma / Supabase pgvector），捕获上下文和答案，并一次性完成评分。

Judge 后端

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

Jev（实验性）

Jev 是一种决策模型：它返回概率，而不是文本。设置 RETRIEVAL_JUDGE_BACKEND=jev 后，faithfulness 会变为混合模式：LLM 将答案拆分为独立的陈述，Jev 并行检查每条陈述是否得到上下文支持，分数为受支持的陈述数 / 陈述总数（与 LLM 评分标准的定义相同）。原因说明会列出不受支持的陈述及其概率，而 details.claims 会包含每条陈述的 p_supported。 hallucination 使用相同的陈述，每条陈述对应一个 Jev Choice（支持 / 矛盾 / 未提及）：分数 = 1 - 矛盾的陈述数 / 陈述总数；对于上下文未提及的内容，报告为“上下文中未提及”，而不予扣分。 answer_relevancy 使用 Jev Score，根据 5 级评分标准评估，无需调用 LLM。每条陈述还会带有其来源答案中的精确段落（quote），沙盒会将其突出显示。其他所有指标仍由 RETRIEVAL_DECOMPOSER_BACKEND 指定的 LLM 运行。

export RETRIEVAL_JUDGE_BACKEND=jev
export TYPESAFE_API_KEY=...                       # console.typesafe.ai/keys
export RETRIEVAL_DECOMPOSER_BACKEND=anthropic     # or ollama / openai
# optional: JEV_MODEL (jev-latest), JEV_MAX_WORKERS (8), JEV_PRICE_IN (0.042)

或者保留服务默认设置，按调用选择 Jev：run_eval 和 evaluate_case 接受 judge="jev"（或使用 judge="llm" 强制采用 LLM 评判）。在服务上设置 TYPESAFE_API_KEY 后，沙盒选择器也会列出“Jev · TypeSafe”，并使用 Groq 预设拆分陈述。

Jev 的费用计入 RETRIEVAL_BUDGET_USD。Jev 对数字、日期和对抗性文本的处理较弱，而且目前尚未测量其与人工标签的一致性，因此请将 Jev 分数视为实验性结果。

报告：运行通过或失败的原因

每个 run_eval 结果都包含 aggregate[metric].verdict：一条摘要（“失败：faithfulness 的平均分为 0.33，低于 0.70 的阈值”）以及导致该结果的因素（失败的案例或不受支持的陈述）。该内容会随运行结果一起保存。

• 在 Claude 中，summary_md 会包含评估结论；支持 MCP Apps 的客户端会以内嵌紧凑卡片的形式呈现：摘要分数、其他指标，以及列出失败项及原因的检查清单。
• 完整报告位于 report_url（你的仪表板主机上的 /report?run=<id>）：其中包含分数、评估结论、每条陈述，以及突出显示问题段落的答案。它与沙盒在运行后显示的视图相同，由同一个共享渲染器（web/report.js、web/report.css）绘制。

工具

工具	用途
list_metrics	内置和自定义指标
load_golden_set(name, source, fmt)	为数据集命名以便复用（仅限自托管——数据集为共享数据，重启后会丢失）
list_golden_sets	查看已加载的数据集
author_metric(name, criteria, examples)	将自然语言转换为评分器
run_eval(metrics, cases, golden_set, threshold, outputs, label, limit)	为数据集评分；可内联传入 cases（JSON/JSONL/CSV/TSV/路径/URL）——不会存储任何内容
show_run_cases(run_id, offset, limit, metric)	分页查看其余内容
evaluate_case(...)	对单个案例评分
ground_against_url(url, output, question)	检查输出与网页的一致性（无标签——评估一致性，而非正确性）
list_runs(golden_set, last_n)	已保存的运行记录
plot_metric_trend / plot_run / compare_runs	内嵌图表
get_budget / reset_budget	费用上限状态 / 重置

---

许可证

Apache License 2.0。由 Hanns Carrillo 构建。