rag-retriever-bench

3ステップで回る

1. rag-retriever-bench prepare データセット取得・サンプリング・埋め込み。1回だけ実行、以降はキャッシュ
2. rag-retriever-bench run 同一クエリで9構成をまとめてベンチマーク
3. results/*.md レポートで横並び比較。品質・レイテンシ・取り込み・self_check証跡

誰のためのツールか

• AIエンジニア ベンダー資料ではなく実測値でベクトルデータベースを選ぶ
• RAG・検索開発者 プロンプトに手を入れる前にインデックスが本当に効いているか確かめる
• AIプラットフォームチーム 運用する複数バックエンドを1つのベンチマークで横並び評価する
• LLM研究者 完全な正解集合つきで再現可能な検索ベースラインを取る

どんな時に使うか

• プロンプトに手を入れる前に。まずretrieverを除外診断して、違う層をデバッグし続けない
• ベクトルDBを乗り換える前に。ベンダー資料ではなく自分の実測値で決める
• 本番デプロイ前に。インデックスが無音でバイパスされていないかself_checkで確認する
• 「エラーは出ないのに検索が怪しい」とき。下の無音劣化3例がまさにそれ

インストール

git clone https://github.com/kenimo49/rag-retriever-bench
cd rag-retriever-bench
pip install -e ".[all]"

docker compose up -d
cp .env.example .env   # OPENAI_API_KEY (embeddings only)

サーバー型バックエンド(pgvector, ClickHouse, Qdrant, Weaviate, Milvus)はdocker composeで起動。ChromaとLanceDBは埋め込み型なのでサービス不要です。

計測するもの

• 検索品質: recall@k, hit@k, MRR@k, nDCG@k。人手アノテーションの正解データと突合、LLM判定なし
• クエリレイテンシ: クライアント側のp50 / p95 / p99 / 平均。シリアライズ込み
• 取り込み: バックエンドごとのバルクロード秒数とインデックス構築秒数
• 7バックエンド9構成: pgvector, ClickHouse (HNSW ×2 + brute force), Qdrant, Weaviate, Milvus, Chroma, LanceDB
• バックエンドごとのself_check: EXPLAINまたはサーバー統計でANNインデックスの実使用を検証
• HNSWパラメータを全バックエンドで統一(m=16, ef_construction=64, ef_search=100)。差が出たらエンジンの差、チューニングの差ではない
• MIRACL-jaデータセット: サンプルコーパスが正解パッセージを全部含むので、recallは完全な正解集合に対して測れる

実測結果 (10万件)

MIRACL-ja 10万パッセージ · 860クエリ · text-embedding-3-small · top_k=10 · 2026-07-11計測、シングルノード。

サーバー型バックエンド (ネットワークホップ込み)

埋め込み型バックエンド (インプロセス。レイテンシはサーバー型と直接比較不可)

品質の上限はbrute forceのrecall 0.952。ANN構成で最も近いのはQdrantの0.947です。この規模ではHNSWエンジンの差は主にレイテンシに出ます。WeaviateとMilvusはp95で2.5ms未満、ClickHouseはインデックスgranularity次第で13〜52msかかります。

フルレポート (MRR, hit@k, 取り込み, self_check証跡) →

選択1つで数字はこれだけ動く

同一コーパス・同一埋め込み・同一HNSW条件。変えたのは以下の選択だけです。

使い方

# 1万件のスモークラン (MIRACL-jaは初回に自動ダウンロード)
rag-retriever-bench run -c configs/miracl-ja.yaml --corpus-size 10000

# 10万件のフルラン
rag-retriever-bench run -c configs/miracl-ja.yaml

# 準備のみ: データセット取得・サンプリング・埋め込み
rag-retriever-bench prepare -c configs/miracl-ja.yaml

実際に捕まえたもの

9構成のうち3つに「エラーゼロのまま無音で劣化する」経路がありました。self_checkプローブは開発中にその3つ全部を検出しています。

• ClickHouse HNSW: OPTIMIZE FINALを省くと静かにbrute forceへフォールバック。EXPLAINプローブが「ClickHouseは遅い」という誤った結果になる前に検出
• Qdrant: indexing_threshold_kbがコーパスサイズより大きいとインデックスが構築されず、indexed_vectors_count = 0のまま生セグメントを検索
• Milvus: flush後にsealed segmentを欠いたstale snapshotをロードし、エラーなしで部分的な結果を返す

どの劣化経路も、それらしい数値を出してきます。レポートはresults/にMarkdown + JSONLで出力され、バックエンドごとに品質・レイテンシ・取り込み・インデックス使用検証の証跡が1行にまとまります。

数値はMIRACL-ja + text-embedding-3-smallをシングルノードで測ったもの。埋め込み型とサーバー型はレイテンシを直接比較できないため別テーブルで報告されます。最終判断の前に自分のデータで測ってください。

なぜ作ったか

多くのRAGチームは、検索品質を確かめる前にプロンプトの調整を始めます。答えがおかしいとモデルが疑われ、プロンプトが書き直され、間違ったパッセージを返したretrieverは問われないままです。このハーネスを作ったのは、検索の不具合が日常的にLLMの不具合と誤診されるからです。上の9構成のうち3つはエラーゼロのまま劣化しえて、回答だけを見てもインデックスにはたどり着けません。まず検索を測りましょう。

RAGAS・DeepEvalとの位置関係

役割は補完関係です。RAGASとDeepEvalはパイプラインが返したcontextsと回答を採点する層、このハーネスはその下にある検索バックエンド自体を採用前に実測する層です。

表の「—」は2026年7月時点で公式docsに記載がないことを示します。どちらもパイプラインの返り値を採点する設計で、それ自体が役割分担です。バックエンド選定はこのハーネス、パイプラインの採点はRAGAS/DeepEvalが受け持ちます。

よくある質問

作者について

作者はKen Imoto。Zenn・Qiita・Dev.to・当サイトで技術記事300本以上、4言語で書籍40冊以上、Zenn・Qiitaで累計40万PV超、Zenodoで研究論文4本を公開し、LLMO Frameworkを設計しています。

詳しいプロフィール →

関連

このハーネスの実測結果はrag-db-advisorに供給されます。RAGスタックの質問に実測エビデンスで答えるMCP/CLIアドバイザーです。

rag-db-advisor →