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 服务。

前置条件

• 已克隆仓库；从仓库根目录运行命令（预设中的配置路径均相对于仓库根目录）。
• PATH 中有 Python 3.11+ 和 uv。
• 将 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 的 OpenAI 兼容聊天补全端点（默认地址为 http://localhost:8999/v1/chat/completions）。
• rag-perf 本身无需 NVIDIA_API_KEY 即可运行（rag-eval 则需要）。合成 LLM 端点可能需要自己的身份验证 — 这由部署环境负责。

说明

1. 选择预设。 scripts/rag-perf/configs/ 下有三个预设：

   • quick_profile.yaml — 仅进行性能分析，约 30 秒。跳过负载测试。适合快速迭代检索 / 重排器调优。
   • single_run.yaml — 一个并发级别，包含性能分析和 aiperf，约 2 分钟。用于回归检查。
   • sweep.yaml — 多轴扫描。load.concurrency、rag.vdb_top_k、rag.reranker_top_k 都是 int | list[int]；其中任何一项设为列表，就会成为一个扫描轴（笛卡尔积）。

2. 编辑预设。 必需： 将 rag.collection_names: ["<collection_name>"] 替换为已部署的 ingestor 服务上的真实集合。通过 ingestor 上的 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. 查看标准输出。 每次运行都会按顺序打印：启动横幅、单行摘要、完全解析后的 YAML 配置（可根据终端输出复现运行）、每个网格点的进度及可复制粘贴的 shlex 拼接 aiperf 命令、丰富的逐点摘要表（阶段分解及条形图、引用质量、瓶颈、负载测试区块），最后是根据变化轴自动标注的并排对比表。参见 references/output-and-analysis.md。

5. 检查产物。 目录布局取决于运行形态 — 单点且 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 × 吞吐量 × 瓶颈 × 引用质量），在扫描中计算扩展效率，始终标明零引用 / 非零错误率 / 可疑的 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_rag_on/ 目录。文件名以 profile_* 开头，因为 aiperf.enabled: false。

使用完整报告进行单个基准测试点：

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（默认值）。若不设置，模型会在思维链上耗尽 token 预算，导致 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 并耗尽了 token	设置 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 venv 中缺少 rag-perf 包	在单元测试作业的顶层安装步骤之后添加 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 shell 命令。 在标准输出中查找 \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——重新运行 uv sync --project scripts/rag-perf（或 uv pip install -e ./scripts/rag-perf）。
• 扫描模式下的测试点名称冲突。 如果两个测试点仅并发数不同（例如 [1, 4] × 单个 vdb_top_k），目录名会编码所有信息：CR:1_ISL:50_OSL:512_VDB-K:20_RERANKER-K:4_Model:...。此外还会附加集群 / GPU / 实验名称（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

Agent 操作手册

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 中每个（测试点 × 迭代）组合占一行。
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. 排查故障： 参见上文的故障排除部分，以及 references/output-and-analysis.md 中关于空引用／瓶颈=N/A 情况的说明。