⚡

rag-evalSkill rag-eval

本技能用于指导智能体执行NVIDIA RAG Blueprint的基于文件系统的RAG评估（RAGAS）。包括准备corpus/和train.json数据集、运行evaluate_rag.py、调整top_k/reranker/query rewriting等参数以优化质量、解读评估结果JSON并排查错误。关键词：RAG评估、RAGAS、NVIDIA RAG Blueprint、文件系统基准、检索增强生成、质量评估、evaluate_rag、corpus、train.json、错误排查。

检索增强(RAG) 0 次安装 0 次浏览 更新于 9/7/2026
名称 rag-eval
版本 “2.6.0”
描述 >- 基于文件系统的RAG基准测试：corpus/、train.json、evaluate_rag.py（RAGAS质量评估）。不用于生产监控、 延迟/吞吐量基准测试（使用rag-perf），也不适用于该仓库布局之外的评估。
开源协议 Apache-2.0 compatibility: 使用uv进行仓库签出；Python 3.11+；从仓库根目录运行；uv sync --project scripts/eval（评估依赖位于scripts/eval/pyproject.toml）；可访问RAG、ingestor和vdb端点；NVIDIA_API_KEY用于RAGAS；可选RAG_EVAL_JUDGE_MODEL（默认mistralai/mixtral-8x22b-instruct-v0.1）。 metadata:
作者 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 - docs/api_reference/openapi_schema_ingestor_server.json argument-hint: RAGAS 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、reranker和query重写开关，以及生成覆盖参数（--temperature、--top-p、--max-tokens）。
  4. 分析结果 — 使用references/result-analysis.md中的脚本；扫描rag_*_evaluation_summary.json以查看RAGAS总览指标。
  5. 错误排查 — 使用错误信号表和下方故障排除章节。

示例

在shell历史中不暴露密钥的情况下设置API密钥（推荐方式）： 从被git忽略的env文件或密钥管理器中加载；避免提交.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基准。
  • 向量数据库/嵌入的选择遵循已部署的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。
  • 向量数据库/嵌入设置：不通过此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

智能体操作手册

  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、reranker和query重写开关、--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。