rag-perf

RAG-Perf — 設定駆動型パフォーマンスベンチマーク CLI

目的

YAML 設定でデプロイ済みの NVIDIA RAG Blueprint サーバーを操作し、サーバー側のプロファイリング実行（ステージごとの時間、引用の品質、ボトルネックの推定）と、任意のaiperf 負荷テスト（TTFT／E2E／トークンおよびリクエストのスループット／エラー率）を実行して、統合レポートを出力します。CLI は意図的に最小限に設計されており、rag-perf -c <config> と --help／--version のみを使用します。動作は完全に設定駆動型で、フィールドの違いは YAML で指定します。

対象範囲

• 回答品質の正確性／RAGASスコアリング → rag-eval スキルを使用してください。
• サービスのデプロイ、修復、設定（compose、helm、NIM 環境変数） → rag-blueprint スキルを使用してください。
• 本番環境の監視／アラート — rag-perf は一度だけ実行するベンチマークツールです。
• 実行時の要件： ネットワーク経由でアクセス可能な、デプロイ済みの RAG サーバーが必要です。

前提条件

• リポジトリをクローンし、リポジトリのルートからコマンドを実行してください（プリセット内の設定パスはリポジトリのルートを基準としています）。
• Python 3.11+ および uv が PATH 上にあること。
• rag-perf を専用の uv 管理仮想環境にインストールします：uv sync --project scripts/rag-perf。
• 単体テストを実行するには、開発用エクストラもインストールします：uv sync --project scripts/rag-perf --extra dev（そうしないと pytest-asyncio が見つからず、非同期テストが収集時にエラーになります）。
• アクセス可能な RAG サーバー（デフォルトは http://localhost:8081）。aiperf のフェーズでは、同梱の nvidia_rag エンドポイントプラグインがインストールされている必要があります — pip install -e ./scripts/rag-perf により、aiperf.plugins エントリーポイントを通じて登録されます。
• 合成クエリの場合：synthetic.llm_url（デフォルトは http://localhost:8999/v1/chat/completions）でアクセス可能な、OpenAI 互換のチャット補完エンドポイントが必要です。
• rag-perf 自体の実行に NVIDIA_API_KEY は不要です（rag-eval とは異なります）。合成 LLM エンドポイントでは独自の認証が必要な場合がありますが、それはデプロイ環境側の要件です。

手順

1. プリセットを選択します。 scripts/rag-perf/configs/ にある3つのプリセットは次のとおりです。

   • quick_profile.yaml — プロファイルのみ、約30秒です。負荷テストはスキップします。検索やリランカーのチューニングをすばやく反復する場合に適しています。
   • single_run.yaml — 並行数は1段階で、プロファイリングと aiperf を実行し、約2分かかります。リグレッションチェック向けです。
   • sweep.yaml — 複数の軸を対象にスイープします。load.concurrency、rag.vdb_top_k、rag.reranker_top_k はすべて int | list[int] です。いずれかをリストにすると、スイープ軸になります（直積）。

2. プリセットを編集します。 必須： rag.collection_names: ["<collection_name>"] を、デプロイ済みのインジェスターサーバーにある実際のコレクション名に置き換えます。インジェスターの GET /v1/collections でコレクションが存在することを確認してください。プレースホルダーの <collection_name> は検証を通過しますが、リクエストはすべて検索時に失敗します。バリエーションを試すときは、YAML プリセットをコピーして使用してください。CLI は意図的に設定ファイルのみを受け付けます。

3. 実行します。 リポジトリのルートから実行します。

   uv run --project scripts/rag-perf rag-perf -c scripts/rag-perf/configs/single_run.yaml
   

   他のプリセットも同じ形式で実行します。CLI が受け付けるのは -c / --config（必須）、--help、--version のみです。

4. 標準出力を確認します。 実行のたびに、次の内容が順に出力されます。起動バナー、1行の概要、完全に解決された YAML 形式の設定（端末の出力から実行を再現できます）、コピーペースト可能な形式の shlex 結合済み aiperf コマンドを含むグリッドポイントごとの進捗、ポイントごとの詳細なサマリーテーブル（ステージ別内訳を棒グラフで表示し、引用品質、ボトルネック、負荷テストのブロックを含む）、最後に変化した軸に応じて自動でラベル付けされた並列比較テーブル。詳しくは references/output-and-analysis.md を参照してください。

5. 成果物を確認します。 ディレクトリ構成は実行形式によって異なります。1ポイントで iterations=1 の場合はフラットになり、それ以外の場合は iter_<i>/<point>/... の下にネストされます。ディレクトリツリー全体、ファイルの用途、results.json / results.csv / report.md の解析方法については、references/output-and-analysis.md を参照してください。

6. ユーザー向けに要約します。 結果を報告するときは、references/output-and-analysis.md#summarising-results-to-the-user の手順に従ってください。実行形式に合った標準結果ファイルを選び、見出し用のテーブル（並行数 × top-k 軸 × TTFT × スループット × ボトルネック × 引用品質）を作成し、スイープではスケーリング効率を算出してください。引用が0件、エラー率が0以外、llm_ttft_ms が疑わしい値、p99 のサンプル数が少ない場合は、必ず明記し、次の実験に使う具体的な YAML を提案してください。

7. チューニングします。 スキーマの詳細は docs/performance-benchmarking.md と、以下の詳細リファレンスに記載されています。よく使う設定は、プロファイルのみのモードにする aiperf.enabled: false、ばらつきの推定精度を高める load.iterations の増加、一晩かけて直積スイープを行うための load.sleep_between_points_s: 60 です。

例

プロファイルのみ（検索やリランカーのチューニングに最も早く手応えを得られます）：

uv run --project scripts/rag-perf rag-perf -c scripts/rag-perf/configs/quick_profile.yaml

出力：rag-perf-results/quick_profile/run_<ts>/{profile_report.md, profile_results.json, profiling/}。aiperf.enabled: false のため、aiperf_rag_on/ ディレクトリは作成されません。ファイル名が profile_* なのもこの設定によるものです。

完全なレポートを含む単一のベンチマークポイント：

uv run --project scripts/rag-perf rag-perf -c scripts/rag-perf/configs/single_run.yaml

出力：フラットな run_<ts>/{report.md, results.json, results.csv, profiling/, aiperf_rag_on/}。

並行数のスイープ：

uv run --project scripts/rag-perf rag-perf -c scripts/rag-perf/configs/sweep.yaml

出力：ポイントごとに run_<ts>/iter_1/<CR:_VDB-K:_RERANKER-K:_…>/{profiling,aiperf_rag_on}/ の下にネストされます。さらに、実行ルートに集計済みの report.md / results.json / results.csv が作成されます。

ユニットテストを実行します：

uv sync --project scripts/rag-perf --extra dev   # one-time, installs pytest-asyncio
uv run --project scripts/rag-perf python -m pytest tests/unit/test_rag_perf/

制限事項

• CLI は設定専用です。パラメーターを変更するには、YAML を作成またはコピーしてください。
• load.concurrency／rag.vdb_top_k／rag.reranker_top_k は int | list[int] を受け付けます。各値は一意のポイントディレクトリを示すため、バリデーターはリスト内の値が一意であることを要求します。
• input.file と input.synthetic には XOR ルールが適用されます。両方を設定すると検証に失敗します。どちらも設定されていない場合、synthetic にデフォルト値が自動入力されるため、空の設定でも検証に通ります。
• ファイル入力の形式は拡張子のみから推測されます（.jsonl または .csv）。それ以外の拡張子は拒否されます。
• 合成データの生成では、各クエリの完了時にディスクへ書き込みます（障害に強い設計です）が、最初の LLM エラーで即時に失敗します。部分的な JSONL は保持されます。エンドポイントを修正して再実行してください。
• 推論モデル（Nemotron Omni、Qwen-Reasoning）では synthetic.disable_thinking: true（デフォルト）が必要です。これを設定しないと、モデルは chain-of-thought でトークン予算を使い果たし、content が空になります。現在は、回答の代わりに reasoning_content を使用するのではなく、生成器が明確なメッセージを表示してエラーを発生させます。
• YAML で設定できない aiperf 固有のオプション（リクエストレートの分布、GPU テレメトリー設定など）を変更するには、scripts/rag-perf/rag_perf/runner.py の AiperfRunner._base_aiperf_cmd を編集する必要があります。
• 詳細な手順は、このファイルを簡潔に保つため references/ に記載されています。

トラブルシューティング

エラー／通知	可能性の高い原因	対処方法
Configuration errors in <yaml>: • input — ... XOR rule	input.file と input.synthetic の両方が設定されている	どちらか一方を選んでください。XOR バリデーターは YAML の読み込み時に実行されます。
input.file must end in .jsonl or .csv	.jsonl／.csv 以外の拡張子	ファイル名を変更するか、変換してください。
load.concurrency has duplicate values	例：[2, 2, 4]	並行数ごとに一意のポイントディレクトリが割り当てられるため、重複を削除してください。
warmup_requests must be >= 1	YAML で warmup_requests: 0 が設定されている	aiperf は warmup=0 を受け付けません。最小値は 1 です。
LLM returned empty content (reasoning_content was populated — model exhausted its budget on chain-of-thought; raise min_query_tokens or set synthetic.disable_thinking=true).	推論モデルが CoT を使用し、トークンを使い果たした	synthetic.disable_thinking: true（デフォルト）を設定するか、min_query_tokens を増やしてください。
✗ All N profiling requests failed across M point(s). + exit 1	URL の誤り、サーバーの停止、コレクションの誤り	target.url と rag.collection_names を確認してください（<collection_name> プレースホルダーを指定すると、このエラーが発生します）。
イテレーションごとに ⚠ N profiling requests failed の警告が表示されるが、実行は継続する	実行中に一部のリクエストがタイムアウトまたはエラーになった	rag-server のログを確認し、target.timeout_s を増やすか、並行数を減らしてください。
RuntimeError: Random synthetic query generation failed at query N: ...	生成中に LLM エンドポイントがリクエストを拒否した	部分的な JSONL は synthetic.jsonl_output_path にあります。エンドポイントを修正して num_queries を減らして再実行するか、input.file に部分ファイルを指定してください。
デプロイにデータがあるのに Citation count (mean): 0 と Citation relevance score: N/A が表示される	rag.collection_names と実際に取り込まれたコレクションが一致していない	curl -s http://<ingestor>:8082/v1/collections を実行して、実際のコレクションを一覧表示してください。
テストで ModuleNotFoundError: No module named 'pytest_asyncio' が発生する	開発用追加パッケージが不足している	uv sync --project scripts/rag-perf --extra dev を実行してください。
CI：tests/unit/test_rag_perf/ から ModuleNotFoundError: No module named 'ruamel' が発生する	CI の仮想環境に rag-perf パッケージがない	unit-tests ジョブで、トップレベルのインストール後に uv pip install -e ./scripts/rag-perf を追加してください。

注意点

• リポジトリのルートから実行してください。 プリセット設定では、リポジトリのルートを基準とした相対パスで scripts/rag-perf/examples/queries.jsonl と scripts/rag-perf/prompts/default_prompts.yaml を参照します。scripts/rag-perf/ 内から実行すると、これらのファイルの検索に失敗します。
• CLI で変更できるのは設定のみです。 URL、同時実行数、コレクションなどの項目を変更するには、YAML を編集するか、プリセットをコピーしてください。
• 初回実行前に必ず rag.collection_names を編集してください。 プリセットには意図的なプレースホルダーとして ["<collection_name>"] が設定されています。検証は通りますが、すべてのリクエストで取得が黙って失敗し、どこでも Citation count (mean): 0 になります。
• load.concurrency_list、rag.vdb_top_k_list、rag.reranker_top_k_list は、スカラー値またはリストをリストに正規化する読み取り専用プロパティです。グリッドについて考えるときはこれらを使用してください。基になる YAML フィールドには、ユーザーが記述した値がそのまま設定されています。
• aiperf.enabled: false にするとファイル名が変わります。 トップレベルの出力は profile_report.md／profile_results.json／profile_results.csv になります。集計スイープテーブルでは負荷テストの行も、末尾の「Optimal throughput」も表示されなくなります。
• 解決済み設定のダンプは冗長です（50 行以上）。これは想定どおりです。ターミナル出力だけで再現できるようにするためのものなので、スクリプトでフィルタリングしないでください。
• 各サブプロセスの実行前に aiperf のシェルコマンドがログに記録されます。 標準出力で \n $ python -m aiperf profile -m ... --endpoint-type nvidia_rag ... を探してください。コピー＆ペーストして実行すれば、rag-perf を介さずに単一の測定点を再現できます。
• --endpoint-type nvidia_rag は、同梱のプラグイン scripts/rag-perf/rag_perf/plugin/nvidia_rag.py によるものです。このプラグインによって、aiperf は RAG の /v1/generate リクエスト形式を認識し、SSE ストリームから引用とステージごとの metrics を解析できるようになります。aiperf が nvidia_rag を解決できない場合、rag-perf を venv に編集可能インストールする必要があります。uv sync --project scripts/rag-perf（または uv pip install -e ./scripts/rag-perf）を再実行してください。
• スイープモードで測定点名が衝突する場合があります。 2 つの測定点の違いが同時実行数のみの場合（例：[1, 4] と単一の vdb_top_k の組み合わせ）、ディレクトリ名にはすべての情報が含まれます。例：CR:1_ISL:50_OSL:512_VDB-K:20_RERANKER-K:4_Model:...。クラスター／GPU／experiment_name（output.cluster、output.gpu、output.experiment_name）も追加されます。マシン間で差分を確認しやすい成果物パスを作るのに便利です。
• load.iterations > 1 の場合、グリッド全体が繰り返されます。 繰り返しごとに独自の iter_<i>/ に出力されます。集計 CSV の行数は n_points × iterations です。

信頼できる情報源

項目	場所
ドライバー	scripts/rag-perf/rag_perf/cli.py（main は唯一の Click コマンドです）
スキーマ	scripts/rag-perf/rag_perf/config.py（RunConfig とサブモデル）
オーケストレーター	scripts/rag-perf/rag_perf/runner.py（BenchmarkRunner.run、RagProfiler、AiperfRunner）
aiperf プラグイン	scripts/rag-perf/rag_perf/plugin/nvidia_rag.py
ユーザー向けドキュメント	docs/performance-benchmarking.md
プリセット	scripts/rag-perf/configs/{quick_profile,single_run,sweep}.yaml
サンプルクエリ	scripts/rag-perf/examples/queries.jsonl
合成プロンプト	scripts/rag-perf/prompts/default_prompts.yaml
設定スキーマの詳細	references/config-schema.md
合成クエリの生成	references/synthetic-generation.md
出力構成とメトリクスの意味	references/output-and-analysis.md

エージェント向けプレイブック

1. 依存関係を同期します： uv sync --project scripts/rag-perf（チェックアウトごとに一度実行します）。
2. プリセットを選択してカスタマイズします： バリエーションが必要な場合は scripts/rag-perf/configs/<preset>.yaml をコピーします。rag.collection_names は必ず実在するコレクションに設定してください。
3. 実行します： リポジトリのルートから uv run --project scripts/rag-perf rag-perf -c <config> を実行します。
4. 標準出力のポイントごとの表と集計表を確認します。 ボトルネックの推定はポイントごとのプロファイリングセクションにあります。ポイント間の比較は最後の集計表で確認できます。
5. output.dir/run_<ts>/ 以下の成果物を解析します。詳細は references/output-and-analysis.md を参照してください。複数ポイントを実行した場合、results.csv には（ポイント × イテレーション）ごとに1行ずつ記録されます。
6. references/output-and-analysis.md#summarising-results-to-the-user のプレイブックに従って、結果をユーザー向けに要約します。要約には、見出しの表、スイープのスケーリング効率の計算、引用がゼロ／エラーがゼロでない／llm_ttft_ms が疑わしい／サンプル数が少ない場合に必須のフラグ、および次に実施する実験の具体的な YAML を含めてください。
7. 検索／リランカーを調整します： すばやく反復するには quick_profile.yaml に切り替えるか、aiperf.enabled: false に設定します。その後、負荷時の特性を調べる際は single_run.yaml／sweep.yaml に戻します。
8. 失敗をトリアージします： 上記のトラブルシューティングと、引用が空／ボトルネックが N/A となるパターンについて references/output-and-analysis.md を参照してください。