RAG-Perf性能基准测试工具Skill rag-perf

名称	rag-perf
版本	2.6.0
描述	>- 面向已部署的 NVIDIA RAG Blueprint 服务器的性能基准测试：Profiling 阶段 + aiperf 负载测试，由单个 YAML 配置驱动。不用于准确性/RAGAS 评分（使用 rag-eval）， 也不用于部署/修复服务（使用 rag-blueprint）。
开源协议	Apache-2.0 compatibility: 使用 uv 管理仓库；Python 3.11+；在仓库根目录运行；uv sync --project scripts/rag-perf（性能依赖位于 scripts/rag-perf/pyproject.toml）；需要可访问的 RAG 服务器（默认 http://localhost:8081）；对于合成查询，需要 OpenAI 兼容的 chat-completions 端点（默认 http://localhost:8999/v1/chat/completions）；aiperf 负载测试阶段使用随附的 nvidia_rag endpoint 插件，rag-perf 以可编辑模式安装后会自动注册。 metadata: tool-version: 0.1.0
作者	NVIDIA RAG foundational-rag-dev@exchange.nvidia.com github-url: https://github.com/NVIDIA-AI-Blueprints/rag endpoint-openapi-schemas: - docs/api_reference/openapi_schema_rag_server.json argument-hint: rag-perf

RAG-Perf — 配置驱动的性能基准 CLI

目的

通过 YAML 配置驱动已部署的 NVIDIA RAG Blueprint 服务器，执行服务端 profiling（分阶段计时、引用质量、瓶颈推断），并可执行 aiperf 负载测试（TTFT、端到端时延、令牌/请求吞吐、错误率），最终生成统一报告。CLI 保持极简：rag-perf -c <config> + --help/–version。行为完全由配置决定。

范围

• 不用于准确性/RAGAS 评估（用 rag-eval）。
• 不用于部署/修复服务（用 rag-blueprint）。
• 一次性基准测试，不做生产监控。
• 需要一个可访问的已部署 RAG 服务器。

先决条件

• 在仓库根目录运行命令。
• Python 3.11+，需要 uv。
• 安装：uv sync --project scripts/rag-perf。
• 单元测试额外安装：uv sync --project scripts/rag-perf --extra dev。
• 为了 aiperf 阶段，需要 nvidia_rag 插件，通过 pip install -e ./scripts/rag-perf 注册。
• 合成查询需要 OpenAI 兼容的 chat-completions 端点（默认 localhost:8999）。
• rag-perf 自身不需要 NVIDIA_API_KEY。

指令

1. 选择预设：quick_profile.yaml（仅 profiling，约30秒）、single_run.yaml（一个并发档位，profiling+aiperf，约2分钟）、sweep.yaml（多维并发+top-K扫描）。
2. 必须把 rag.collection_names 占位符替换为真实 collection。
3. 从仓库根运行：uv run --project scripts/rag-perf rag-perf -c <config>。
4. 阅读 stdout 中的解析后配置、每点进度和 aiperf 命令。
5. 检查产物：单点 run_<ts>/ 下 results.json/csv、report.md、profiling/、aiperf_rag_on/；扫描多点 nested iter_<i>/…。
6. 按照 references/output-and-analysis.md 中的 playbook 进行结果总结。
7. 调优常见旋钮：aiperf.enabled: false（仅 profiling）、load.iterations 增加样本、load.sleep_between_points_s 用于长时间扫描。

示例

• 快速 profile：uv run --project scripts/rag-perf rag-perf -c scripts/rag-perf/configs/quick_profile.yaml
• 单点完整报告：uv run --project scripts/rag-perf rag-perf -c scripts/rag-perf/configs/single_run.yaml
• 并发扫描：uv run --project scripts/rag-perf rag-perf -c scripts/rag-perf/configs/sweep.yaml
• 单元测试：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 支持标量或列表，列表值必须唯一。
• input.file 与 input.synthetic 必须二选一；两者都不设置时自动使用 synthetic 默认值。
• 文件输入仅支持 .jsonl/.csv，按扩展名推断。
• 合成生成在第一个 LLM 错误时快速失败，但保留已完成查询的 JSONL。
• 推理模型需要 synthetic.disable_thinking=true。
• aiperf 特殊开关需要修改 runner.py。

故障排除

• 输入 XOR 规则错误 → 只设置 input.file 或 synthetic。
• 文件扩展名错误 → 使用 .jsonl/.csv。
• 并发值重复 → 去重。
• warmup_requests 必须 >=1。
• LLM 返回空内容（reasoning_content 占用）→ 设 disable_thinking=true 或提高 min_query_tokens。
• 所有 profiling 请求失败 → 检查 target.url、rag.collection_names 和占位符。
• 部分迭代失败 → 查看 rag-server 日志，提高 timeout，降低并发。
• 合成生成中途失败 → 修复 LLM 端点后重试，或用生成的部分文件作为 input.file。
• 引用计数为 0 → 常见于 collection 不匹配，检查实际 collection。

注意事项

• 必须从仓库根执行。
• 所有配置修改都通过 YAML。
• 首次使用务必替换 collection_names 占位符。
• concurrency_list / vdb_top_k_list / reranker_top_k_list 是只读规范化属性。
• aiperf.enabled: false 会改变输出文件名为 profile_*。
• 解析后的配置 dump 很冗长，但这是为了可复现，不要过滤。
• aiperf 命令会在 stdout 中打印，可复制单独运行。
• nvidia_rag 插件需要 rag-perf 可编辑安装。
• 多点扫描目录名编码所有参数，并附加 cluster/gpu/experiment_name。
• load.iterations>1 时网格重复，每个迭代独立目录。

产物与参考

组件	位置
CLI 驱动	scripts/rag-perf/rag_perf/cli.py
配置模型	scripts/rag-perf/rag_perf/config.py
运行器	scripts/rag-perf/rag_perf/runner.py
aiperf 插件	scripts/rag-perf/rag_perf/plugin/nvidia_rag.py
用户文档	docs/performance-benchmarking.md
预设	scripts/rag-perf/configs/
示例查询	scripts/rag-perf/examples/queries.jsonl
合成 prompt	scripts/rag-perf/prompts/default_prompts.yaml

Agent playbook

1. 同步依赖并安装 rag-perf。
2. 定制预设并设置 collection_names。
3. 从 repo 根运行基准。
4. 解析 stdout 表格。
5. 根据参考文献进行总结、标记异常并建议下一步实验。
6. 调优时用 quick_profile 或 aiperf.enabled=false 加快迭代，之后回到 single_run/sweep。