rag-eval

オンディスク RAG 評価（corpus/ + train.json）

目的

NVIDIA RAG Blueprint のファイルシステムベンチマークについて、エージェント向けに説明します。corpus/ と train.json の準備、scripts/eval/evaluate_rag.py の実行、品質比較のための検索・生成フラグの調整、RAGAS JSON 出力の解釈、エラー（HTTP／ストリームエラー、空のコンテキスト、コレクションの不一致、ジャッジ API）の切り分けを扱います。

レイテンシ、スループット、負荷テストには、rag-perf スキル（scripts/rag-perf、docs/performance-benchmarking.md）を使用してください。このスキルは使用しないでください。

使用しない場合

以下の場合、このスキルは使用しないでください。サービスのデプロイや修復（rag-blueprint を使用してください）、corpus/ + train.json のレイアウトを使用しない API の評価、この評価ツールに関係のない一般的な ML 実験、本番環境の監視／アラート、レイテンシ／スループットのベンチマーク（rag-perf を使用してください）。

前提条件

• リポジトリがクローン済みであること。コマンドはリポジトリのルートから実行してください（インポートとパスはこの前提です）。
• Python 3.11+ と uv。評価用依存関係：uv sync --project scripts/eval。
• 接続可能な RAG サーバー と ingestor（デフォルトは localhost:8081 / 8082 の場合が多いです）。
• RAGAS 用の NVIDIA_API_KEY（認証情報の管理を参照）。RAG_EVAL_JUDGE_MODEL は任意です。
• --dataset-paths に渡す各データセットのルートに、corpus/ と train.json が含まれていること。

手順

1. データを準備する — 各データセットディレクトリが、references/dataset-and-conversion.md に記載されているレイアウトと train.json の規則に従っていることを確認します。データソースが公開リンク（サイトやデータセットのページ）として提供される場合は、ドキュメントを corpus/ の下に配置します。マルチモーダルコンテンツでは、画像を埋め込んだままにできるため、PDF を推奨します。CSV／JSONL などは、同ファイルのパターンに従って変換します。
2. 評価を実行する — --dataset-paths、--host、--port を指定して、uv run --project scripts/eval python scripts/eval/evaluate_rag.py を実行します。コマンド例、出力、エラーについては references/benchmark-execution.md を参照してください。フラグの詳細は references/evaluate-rag-cli.md を参照してください。
3. 品質を調整する — RAGAS スコアで検索／生成の設定を比較する際は、references/benchmark-execution.md の説明に従って、--top_k / --vdb_top_k、リランカーとクエリ書き換えの切り替え、生成のオーバーライド（--temperature、--top-p、--max-tokens）を調整します。
4. 結果を分析する — スクリプトについては references/result-analysis.md を参照し、主要な RAGAS メトリクスは rag_*_evaluation_summary.json を確認します。
5. エラーを切り分ける — エラーシグナルの表と、以下のトラブルシューティングセクションを参照してください。

例

シェルの履歴にシークレットを残さずに API キーを設定する（推奨方法）： Git で追跡対象外の環境ファイルまたはシークレットマネージャーから読み込みます。.env をコミットしないでください。キーが漏えいした場合はローテーションしてください。詳細：references/benchmark-execution.md#credential-hygiene-nvidia_api_key。

最小限の評価（キーはすでに環境に設定済み）：

uv sync --project scripts/eval
uv run --project scripts/eval python scripts/eval/evaluate_rag.py \
  --dataset-paths /path/to/my_dataset \
  --host localhost \
  --port 8081

サマリー JSON を整形して表示する：

python3 -m json.tool results/my_dataset/rag_my_dataset_evaluation_summary.json

その他の例（取り込みのスキップ、品質の一括評価）：references/benchmark-execution.md。

制限事項

• 評価ツールの動作はファイルシステムの仕様と evaluate_rag.py に固定されており、カスタムのオフラインジャッジや RAG 以外のベンチマークの代わりにはなりません。
• ベクトル DB／埋め込みの選択は、デプロイ済みの ingestor と RAG の環境変数に従います。この CLI だけでは上書きされません。
• スコアは検索品質、ジャッジモデルの利用可否、NVIDIA_API_KEY に依存します。コンテキストが空の場合、RAGAS メトリクスは一部のみ算出されます（参考資料を参照）。
• 手順の詳細は**references/**以下に記載されています。案内を簡潔に保つため、段階的な変換手順、すべてのフラグ、エラー一覧が必要な場合は、それらのファイルを参照してください。

トラブルシューティング

エラー／シグナル	考えられる原因	対処方法
NVIDIA_API_KEY に言及して即時終了する	キーがない、または無効です	セキュアな経路でキーを設定してください。認証情報の管理については、references/benchmark-execution.md を参照してください。
train.json must be a JSON array	JSON の形式が正しくありません	トップレベルをオブジェクトの配列にしてください。references/dataset-and-conversion.md に従って検証してください。
evaluation_data.json の行数が train.json より少ない	クエリごとの処理に失敗しています	stderr を確認してください。ネットワークまたはストリーム JSON のエラーが考えられます。benchmark-execution のエラー表を参照してください。
generated_contexts がすべて空	検索に問題があります	コレクション、取り込み、top_k／vdb_top_k、および /v1 サフィックスのない ingestor_server_url を確認してください。
アップロード時に Ingestor が 404 を返す	Ingestor のベース URL が正しくありません	http://host:port のみを渡してください。コードが /v1/ を追加します。

シグナルの全表については、references/benchmark-execution.md#common-error-cases-and-signals を参照してください。

注意点

• リポジトリのルートから実行してください：scripts/eval/evaluate_rag.py 内のパスとインポートはこれを前提としています。作業ディレクトリが間違っていると、インポートが警告なく失敗します。
• --ingestor_server_url：http://host:port を渡し、/v1 は付けないでください。コードが自動的に /v1/ を追加します。/v1 を含めると、Ingestor への呼び出しで 404 が発生します。
• ベクトル DB／埋め込み設定：この CLI では設定されません。デプロイ済みの Ingestor と RAG サーバーの環境変数（例：APP_VECTORSTORE_URL、埋め込みモデル）で設定してください。
• --model／--llm_endpoint：明示的に設定した場合にのみ、そのまま転送されます。サーバーに設定済みの LLM を使うには省略してください。
• 古いコレクション：--force_ingestion を使わない限り、前回の実行で取り込まれたデータは残ります。実行ごとの品質を比較する際は、一意の名前を --collection に指定してください。
• コンテキスト指標が空：generated_contexts がすべて空の場合、RAGAS は nv_accuracy のみを採点し、ほかの 2 つの指標は空欄のままになります。これはエラーのない成功ではありません。

正式な情報源

項目	場所
ドライバー	scripts/eval/evaluate_rag.py（CORPUS_DIRECTORY = corpus、EVAL_DATA = train.json）
人間向け README（常にリポジトリ内）	scripts/eval/README.md
CLI 全体（フラグ、デフォルト値）	scripts/eval/evaluate_rag.py --help、references/evaluate-rag-cli.md
データセット／変換	references/dataset-and-conversion.md
実行、出力、エラー	references/benchmark-execution.md
結果分析スクリプト	references/result-analysis.md
レイテンシ／スループット	rag-perf スキル、docs/performance-benchmarking.md

エージェント向け手順

1. 評価を実行する — uv sync --project scripts/eval を実行し、続けて必須の --dataset-paths、--host、--port（および環境変数 NVIDIA_API_KEY）を指定して uv run --project scripts/eval python scripts/eval/evaluate_rag.py を実行します。引数 --ingestor_server_url は省略可能です（デフォルトは http://localhost:8082）。Ingestor のエンドポイントを変更する場合にのみ指定してください。
2. 品質を調整する — references/benchmark-execution.md を参照してください。--top_k／--vdb_top_k、リランカーとクエリ書き換えの切り替え、--temperature、--top-p、--max-tokens について説明しています。
3. データを変換する — references/dataset-and-conversion.md に従ってください。
4. 結果を分析する — references/result-analysis.md を参照してください。簡易確認には python3 -m json.tool results/<dataset>/rag_<dataset>_evaluation_summary.json を実行します。
5. エラーを切り分ける — references/benchmark-execution.md#common-error-cases-and-signals を参照してください。