retriEVAL

retriEVAL

MCP サーバーとしての LLM 評価。 あらゆる MCP クライアントから、パイプラインもテストハーネスも使わずに、AI の出力の忠実性、関連性、ハルシネーションをスコアリングできます。すべての結果には、履歴を保存するダッシュボードへのリンクが付いています。

ライブで試す（登録不要） · 2 分間のデモを見る · ダッシュボード

---

理由

カスタマーサポートの回答 5 件を、2 つの指標でスコアリングした例です。

指標	スコア	合格
answer_relevancy	0.98	5/5
faithfulness	0.70	3/5

どの回答も質問に沿っており、よく書けていました。そのうち 2 件は、根拠としているはずのポリシーと矛盾していました。ポリシーにはない無料の返品送料を約束した回答が 1 件、無料の翌日交換をでっち上げた回答が 1 件です。目視で確認していたら、5 件すべてに承認を出していたでしょう。

ここにギャップがあります。関連性が問うのは、質問に答えているかです。忠実性が問うのは、実際に情報源に記載されているかです。両方が必要で、2 つ目の指標が高くつく失敗を捉えます。

接続方法

セルフホスト可能です。クローンし、評価モデルを指定して実行するだけです。データがマシンの外に出ることはなく、サービスへの登録も不要です。

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

あとは、次のように尋ねるだけです。

次のケースを忠実性でスコアリングしてください：[{"input": "...", "actual_output": "...", "retrieval_context": ["..."]}]

ケースをインラインで渡せば何も保存されません。1 回の呼び出しだけで、セットアップも不要です。クライアントの設定についてはローカルで実行（stdio）を、自分専用の常時稼働インスタンスとダッシュボードが必要な場合はHTTP としてデプロイをご覧ください。

インストール前に試してみたい場合は、retrieval-mcp.com にライブサンドボックスがあります。登録不要で、無料の評価モデル上で動作し、データは保存されません。

すべてをローカルに保つ場合： RETRIEVAL_JUDGE_BACKEND=ollama を設定すると、評価モデルもマシン上で動作するため、データがネットワークの外に出ることはありません。第三者に送信できないものを評価する場合に便利です。

利用できる機能

• 9 種類の組み込み指標に加えて、平易な英語で作成できるカスタム指標
• 切り替え可能な評価モデル — Anthropic、Groq、Gemini、OpenRouter、またはローカルの Ollama モデルを利用できるため、ネットワークの外にデータを出す必要はありません
• ファイル、URL、インライン JSON、JSONL、CSV、TSV からのゴールデンセット
• Supabase 上の実行履歴。共有可能なパーマリンクと実行比較に対応
• 支出上限。評価モデルを使うツールは、そうでなければ料金が膨らむ可能性があるためです

制限事項

• 評価モデルと人間のラベルとの一致度はまだ検証されていないため、スコアは絶対的な正解ではなく、判断材料として扱ってください。
• ゴールデンセットには現時点で独自の出力が含まれるため、新しいモデル出力に対して再実行するには、2 つ目のセットを読み込む必要があります。セットを分割する変更を次に予定しています。
• ゴールデンセットと作成した指標はサーバープロセス内に保存され、再起動すると失われます。実行結果は保持されますが、これらは保持されません。

---

指標（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 の支出は、実際のトークン使用量に基づいて計測され、保存されます。ハード上限を設定します。

export RETRIEVAL_BUDGET_USD=20     # 0/unset = unlimited

累計支出が上限に達すると、それ以降の Anthropic 呼び出しは停止し、ツールは明確な budget_exceeded メッセージを返します。get_budget／reset_budget で確認・リセットできます。（料金は概算です。お使いのモデルの現在の料金に合わせるには、RETRIEVAL_PRICE_IN/OUT の 100 万トークンあたりの料金を上書きしてください。）

ハイブリッド構成（ローカル＋常時稼働のダッシュボード）

実行履歴にはプラグイン可能なストアが使われ、環境変数で選択されます。

• 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 で検索し、正解のパッセージに対する recall@k を計算し（決定論的なリトリーバーのスコア）、回答を生成した後、faithfulness を評価します（ジェネレーターのスコア）。失敗の 2 つのパターンを見分けられるよう、回答の 1 つには意図的にハルシネーションを含めています。

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 がパイプラインにアクセスすることはありません。
• ライブ： RAG エンドポイントまたはベクトルストア（Chroma／Supabase pgvector）を呼び出す query_rag(question) ツールを追加し、コンテキストと回答を取得して、一度に評価します。

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 は 5 段階の評価基準による Jev Score で、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" を指定します（LLM 判定を強制する場合は judge="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 が開発しました。