rag-eval

rag-eval

目的

「調整 → 目を凝らす → モデルを入れ替える → クレジットを消費する」というループを、ユーザーのゴールドセット上で評価バリアントのグリッドを実行し、コストを考慮したスコアで順位付けして、アーキテクチャ、スタック、想定される問題について構造化されたフィードバックを返す単一のコマンドに置き換えます。エビデンスに基づく RAG の実践を活用し、ユーザーの過去の実行から学習します。

使用するタイミング

次のような場合に実行します：「RAG のテストを手伝って」「RAG を調整して」「RAG の性能が悪い」「検索プロンプトを比較して」「これをどう評価すればいい？」「X に最適な埋め込みモデルは？」「RAG の評価に費用がかかりすぎる」。また、改善の明確な手応えがないまま OpenRouter / OpenAI のクレジットを消費しているとユーザーが報告した場合にも実行します。

前提条件 — 実行前に収集する

最初のスイープの前に、ユーザーから次の情報を収集します。多くは妥当なデフォルト値があるため任意ですが、費用に関わる項目は必ず確認してください。

1. RAG コードベースのルート — テスト対象のリポジトリ／モジュールへのパス。
2. ゴールドセット — Q&A ペアを 10 件以上。ない場合は、ユーザーのデータセットからスターター用のゴールドセットを生成することを提案します（LLM で合成し、人間がレビュー）。references/best-practices.md を参照してください。
3. データセット — RAG が検索するコーパス。
4. 予算上限 — 1 回の実行に対する厳格なドル上限（ユーザーが指定しない場合のデフォルト：$2）。スイープの前に必ず確認してください。
5. プロバイダーのキー — OPENROUTER_API_KEY または OPENAI_API_KEY（環境変数から読み取ります）。
6. ベクトルストアの設定 — コレクション名、埋め込みモデル、チャンクサイズ（リポジトリから読み取ります。不明確な場合は確認してください）。
7. 評価履歴のパス（任意） — デフォルトはリポジトリルートの .rag-eval/history.jsonl です。

ワークフロー

次の順序で進めてください。標準チェックリストは references/best-practices.md を、研究に裏付けられたデフォルト値は references/evidence-base.md を参照してください。

ステップ 0 — （任意）過去の反復セッションを取り込む

ユーザーからセッション ID（Claude Code のトランスクリプト、skill-studio のセッション、または Fathom の会議）が提供された場合は、まず 決定論的な取り込みを実行します。LLM 呼び出しは行いません。有用なシグナル（試したモデル、プロンプトのバリアント、費用の記録、評価結果）のみを簡潔な JSON として抽出するため、以降のスキルは長い生トランスクリプトではなく、小さな構造化バンドルを使用できます。

python scripts/session_ingest.py <session_id> > /tmp/rag-eval-bundle.json
# or with a direct path:
python scripts/session_ingest.py --path /path/to/transcript.jsonl > /tmp/rag-eval-bundle.json

バンドルには models_tried、prompts_tried（ハッシュのみ）、iterations、total_cost_usd、summary_stats が含まれます。これをステップ 1 に渡してください。生トランスクリプトを貼り付けないでください。

重要な理由： トランスクリプトには、ノイズとなるトークンが 100k 以上含まれることがあります。取り込みスクリプトは正規表現による抽出のみを行い、実際の監査とスイープ計画に LLM の予算を残します。これは最適化ではなく、必須要件です。

ステップ 1 — スタックを監査する

references/best-practices.md を読み、ユーザーのリポジトリとベクトルストアの設定を調べます。次の内容を含む構造化レポートを作成してください。

• アーキテクチャ（検索タイプ：dense / hybrid / rerank、チャンク分割戦略、プロンプト構成）
• 技術スタック（埋め込みモデル、LLM、ベクトルストア）
• リソース（データセットの規模、ゴールドセットの規模、過去の評価実行）
• リスク（既知のアンチパターン、不足している要素）

レポートをユーザーに提示し、どの問題から対処するか尋ねてください。

ステップ 2 — スイープ計画を提案する

監査結果に基づいて、テストするバリアントを 3～8 個提案します。初回のグリッドは小さくしてください（デフォルト：プロンプト 2 種類 × モデル 2 種類 × 検索バリアント 1 種類 = 4 セル）。ゴールドセットの規模 × バリアント数 × 平均トークン数 × プロバイダーの料金に基づいて費用を見積もります。費用の見積もりを提示し、実行前にユーザーの確認を待ってください。

ステップ 3 — スイープを実行する

scripts/eval_sweep.py を使用します（呼び出し方法はスクリプトのヘッダーを参照）。設定 YAML を読み込み、各バリアントをゴールドセットに対して実行し、バリアントごとの費用と回答品質を記録して、history.jsonl に追記します。

安全策：

• 予算上限を決して超えないでください。上限に達した場合は、スイープの途中でも停止してください。
• ユーザーのリポジトリを変更しないでください。すべての成果物は .rag-eval/ の下に書き込みます（gitignore に追加してください）。
• ユーザーの上限を超えると推定されるスイープを実行する前に、必ず確認してください。

Step 4 — ランク付けして報告する

スイープの後、コストを考慮したスコア quality × (1 / log(1 + cost)) でバリアントをランク付けします。次の内容を提示します。

• 上位 3 つのバリアントと、品質指標およびコスト
• 前回の最良バリアントからの変更点
• 次に試す具体的な実験

完全なレポートを .rag-eval/reports/<timestamp>.md に書き込みます。

Step 5 — 自己改善する

以降の実行の前に history.jsonl を読み、ユーザーがすでに試したことを考慮します。却下されたバリアントは再テストしないでください。傾向を明らかにします（「モデル A、B、C はいずれも複数ホップのクエリで性能が低かったため、次はリランカーを試す」）。

再利用可能なリソース

• scripts/eval_sweep.py — グリッド検索の実行スクリプトです。eval_config.yaml を読み込み、結果を history.jsonl に書き込みます。
• references/best-practices.md — エージェントが基準として使用する、エビデンスに基づいた RAG チェックリストです。
• references/evidence-base.md — 最新の RAG 研究と各手法が有効な場面への参照です。
• assets/eval_config.template.yaml — ユーザーのリポジトリにコピーするための初期設定です。
• assets/gold_set.template.jsonl — ゴールドセット形式を示す 3 組の Q&A サンプルです。

注意事項

• 主な失敗要因はコストです。 確認済みの予算がない状態で実行しないでください。小規模なスイープを優先してください。ユーザーはいつでも再実行できます。
• リポジトリは変更しません。 すべての出力は対象リポジトリの .rag-eval/ 配下に置きます。
• ベストプラクティスに確信が持てない場合は、ウェブで調査してください。 tavily-search または firecrawl-research を使って最新のエビデンスを集め、監査レポートにまとめます。
• ユーザーの判断を優先します。 対象リポジトリ内のファイルを変更する前に、必ず確認してください。