rag-db-advisor

3ステップで回る

1. 聞く rag-db-advisor ask "…" 自由文の質問1つ。CLIでもMCPでも、質問票はありません
2. エビデンスが返る === note:qdrant#1 (knowledge/ja/qdrant.md) === 実測数字入りのチャンクが、チャンクIDと出典レコードを名乗って届きます
3. 決める --llm / MCP経由のあなたのLLM 合成は外側で。判定文はあなたのLLM(か、あなた)が出典つきで書きます

実際の回答例

実行例 2026-07-12: rag-db-advisor ask --llm --model gpt-4o の実出力を要約整形

エビデンスが載せられる判断軸

以下の軸はすべて、ストアに入ることを許された2種類のもの(実測と再現済みの罠)でカバーされています。

• データ規模 1万件と10万件、両方で実測
• 検索品質 recall@10・nDCG・MRR・hit@k。人手正解と突合
• レイテンシ クエリごとのp50 / p95 / p99
• 書き込み バルクロード+インデックス構築秒数
• 運用の罠 再現済み3件+機械検証
• 配置形態 embedded型とサーバー型を別テーブルで

メタデータフィルタリング・hybrid検索・コスト試算はv0.1のエビデンス範囲外です。範囲外の質問には、それらしく答えずfail-closedでエラーを返します。測った範囲に正直なのがこのツールの態度です。

誰のためのツールか

• AIエンジニア 設計文書の「なぜこのDB」に引用できる数字が要る
• RAG開発者 「検索が遅い気がする」のデバッグで、既知の罠から先に潰したい
• Claude Codeユーザー RAGスタックの質問にモデルの事前知識でなくエビデンスで答えてほしい
• テックリード ベクトルDB提案のレビューで数字の意味を確かめたい

どんな時に使うか

• 新しいRAG機能のDB選定前に。ベンダー資料でもLLMの一般論でもなく、同一条件の実測から始める
• 「ClickHouseのベクトル検索が遅い」と感じたとき。その印象のために再現済みの罠カタログがあります
• レビューで「なぜQdrant？」と聞かれたとき。出典レコードID付きのエビデンスで答えられる
• Claude Codeで実装中に。セッションを離れずMCP経由でLLMがエビデンスを引く

インストール

pip install git+https://github.com/kenimo49/rag-db-advisor
export OPENAI_API_KEY=sk-...
rag-db-advisor ingest

APIキーは埋め込み(text-embedding-3-small)のみに使用。MCP経由ならサーバー側に生成用キーは不要です: サーバーはエビデンスを返し、回答はあなたのLLMが書きます。

何を知っているか

• 実測レコード: 9バックエンド構成×2コーパス規模(MIRACL-ja 1万/10万件、人手アノテーション860クエリ)。レコードごとに品質・レイテンシ・取り込み・インデックス使用検証つき
• 運用ノート: 手書き8ファイル(バックエンド別7本+横断原則1本)。ベンチ作業中に再現した挙動だけを書く方針
• 罠カタログ: エラーゼロのまま劣化する経路3件。すべて再現→修正→記録済み
• 方法論の注意が回答に織り込み済み: 埋め込み型とサーバー型のレイテンシは直接比較不可、数値はMIRACL-ja+text-embedding-3-smallのシングルノード実測
• MCPツール3本: advise(エビデンス検索) / compare_backends(1万・10万件の比較表) / list_traps(バックエンド別の罠)。失敗時は例外でなく{"error", "hint"}を返す

罠カタログから3件

7バックエンド中3つに「エラーゼロのまま劣化する」経路がありました。3つともベンチ作業中に実際に踏み、再現してから知識ベースに書かれています。

出典: knowledge/ja/clickhouse.md · qdrant.md · milvus.md（すべて再現してから記録）

エビデンスで答えが変わった実例

データシートでなく実測を見ると答えが反転する例を2つ:

使い方

# エビデンスのみ
rag-db-advisor ask "pgvector or Qdrant for 100k Japanese docs?"

# + OpenAIによる回答合成 (デフォルトはgpt-4o-mini)
rag-db-advisor ask "ClickHouse vector search feels slow. What should I check?" --llm

# Claude CodeにMCPサーバーとして登録
claude mcp add rag-db-advisor -- rag-db-advisor mcp

「答えない」という機能

このツールが想定する事故はこうです: 検索レイヤーが壊れ、呼び出し側のLLMが黙って事前知識で答え、誰も気づかない。だからアドバイザーはfail-closedに作られています。

• 検索の失敗はMCPツール3本すべてで明示的な{"error", "hint"}になる。例外が文章に飲み込まれることはない
• 結果0件も「null回答」ではなくエラー。呼び出し側モデルには「問題なし」ではなく「エビデンスなし」が見える
• 判定文は中で生成しない。アドバイザーは検索し、合成はあなたのLLM(か人間)が行い、出典は付いたまま

すべてのチャンクは同梱のベンチ記録(knowledge/results/*.jsonl)か、再現済み挙動の手書きノート(knowledge/ja/*.md)まで遡れます。推測ベースの助言は方針としてスコープ外です。

ドッグフーディング: 検索レイヤーはrag-retriever-bench自身のBaseRetriever抽象を輸入し、ナレッジの保存先にはChromaを選択。ベンチのデータが「この規模では素のHNSW勢の品質は横並び」と示しているためで、アドバイザーは自分の助言に従っています。

なぜ作ったか

rag-retriever-benchを作って分かったのは、数字は残るということです。JSONLとレポートに落ちて消えません。消えていくのはその周りの運用知識でした。インデックスを黙って無効化するフラグ、greenステータスのまま索引ゼロにするしきい値。データベースについての意見は再現しませんが、実測と再現済みの罠は再現します。だからこのアドバイザーでループを閉じました。測り、測ったものと踏んだものを知識ベースに蒸留し、次の質問に供給する。そしてエビデンスが無いときは、推測せずに無いと言います。

LLM直答・ann-benchmarksとの位置関係

「どのベクトルDB？」への答え方は道具ごとに違います。正直な違いは、答えがどこから来るかです。

「—」はそのツールが劣るという意味ではなく、その軸を扱わないという意味です。LLM直答は広く速く、ann-benchmarksは素のANN性能のリファレンスです。このアドバイザーは意図的に狭く、1つのコーパス系統と1つの埋め込みモデルの範囲に絞る代わりに、全主張がレコードに遡れます。

よくある質問

作者について

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

詳しいプロフィール →

関連

エビデンスはすべてrag-retriever-benchから。同一コーパス・同一クエリで9バックエンド構成を測るベンチマークハーネスです。

rag-retriever-bench →