rag-eval

磁盘上的 RAG 评估（corpus/ + train.json）

用途

指导 Agent 使用 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 服务和摄取器（默认通常为 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. 调整质量 — 按照 references/benchmark-execution.md 中的说明，调整 --top_k / --vdb_top_k、重排器和查询重写开关，以及生成参数覆盖项（--temperature、--top-p、--max-tokens），以比较不同检索/生成配置的 RAGAS 分数。
4. 分析结果 — 使用 references/result-analysis.md 中的脚本；查看 rag_*_evaluation_summary.json，了解主要 RAGAS 指标。
5. 排查错误 — 使用错误信号表以及下方的故障排除部分。

示例

设置 API 密钥，避免机密出现在 Shell 历史记录中（推荐方式）： 从被 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 基准。
• 向量数据库 / 嵌入选项取决于已部署的摄取器和 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：传入不带 /v1 的 http://host:port——代码会自动附加 /v1/。包含 /v1 会导致调用 ingestor 时返回 404。
• 向量数据库 / 嵌入设置：此 CLI 不设置这些配置；请通过已部署的 ingestor 和 RAG 服务环境变量（例如 APP_VECTORSTORE_URL、嵌入模型）进行配置。
• --model / --llm_endpoint：仅在显式设置时才会原样转发；省略即可使用服务已配置的 LLM。
• 过期集合：除非使用 --force_ingestion，否则上一次运行摄取的数据会保留。比较不同隔离运行的质量时，请使用唯一名称设置 --collection。
• 上下文指标为空：如果所有 generated_contexts 都为空，RAGAS 只会计算 nv_accuracy，另外两个指标会留空——这并不代表静默成功。

信息源

内容	位置
驱动程序	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

Agent 操作指南

1. 运行评估 — 先运行 uv sync --project scripts/eval，然后运行 uv run --project scripts/eval python scripts/eval/evaluate_rag.py，并传入必需的 --dataset-paths、--host 和 --port（以及环境变量 NVIDIA_API_KEY）。参数 --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。