mcpField
R
rag-eval

rag-eval

github.com/glebis测试与质量404147 次安装4 天前更新
代码仓库

关于 rag-eval

rag-eval 是用于评估和调优 RAG 系统的技能，可审查技术栈、在预算上限内测试多个变体，并参考历史结果规划后续实验。

主要功能

  1. 01RAG 技术栈审查
  2. 02基于黄金集测试变体
  3. 03按成本与质量排序
  4. 04记录运行历史与反馈
  5. 05提取会话中的实验信号

适用场景

  1. 01比较检索提示词和模型
  2. 02定位 RAG 架构问题
  3. 03控制评估费用
  4. 04依据历史运行规划实验

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/glebis/claude-skills --skill rag-eval

安装后在 Claude Code 中输入/rag-eval确认已加载。

附带文件scripts/session_ingest.py

详细介绍

rag-eval

用途

用一条命令替代“调整 → 眯眼查看 → 更换模型 → 烧掉额度”的循环：在用户的金标准集上运行一组评估变体，按成本感知评分进行排序，并针对架构、技术栈和潜在问题提供结构化反馈。借鉴基于证据的 RAG 实践，并从用户以往的运行记录中学习。

适用场景

当用户说“帮我测试 RAG”“调整我的 RAG”“我的 RAG 效果很差”“比较检索提示词”“这个要怎么评估”“X 用什么嵌入模型最好”或“我的 RAG 评估成本很高”时触发。当用户表示在没有明确改进信号的情况下，烧掉了 OpenRouter / OpenAI 额度时，也应触发。

前置条件 — 运行前收集

首次运行前，请向用户收集以下信息。许多项都是可选的，也有合理的默认值；但始终要确认会影响成本的项目。

  1. RAG 代码库根目录 — 受测仓库或模块的路径。
  2. 金标准集 — 至少 10 组问答对。如果没有，可提议根据用户的数据集生成一个入门金标准集（由大模型合成、人工审核）。参见 references/best-practices.md。
  3. 数据集 — RAG 检索所用的语料库。
  4. 预算上限 — 每次运行的硬性美元上限（用户未指定时默认为 $2）。任何评估扫描开始前都必须确认。
  5. 服务商密钥 — OPENROUTER_API_KEY 或 OPENAI_API_KEY（从环境变量读取）。
  6. 向量存储配置 — 集合名称、嵌入模型、分块大小（从仓库读取；如有歧义则确认）。
  7. 评估历史路径（可选）— 默认为仓库根目录下的 .rag-eval/history.jsonl。

工作流

按以下顺序执行。权威检查清单参见 references/best-practices.md，基于研究的默认设置参见 references/evidence-base.md。

步骤 0 —（可选）导入先前迭代的会话

用户提供会话 ID（Claude Code transcript、skill-studio 会话或 Fathom 会议）时，先运行确定性导入，不调用大模型。该操作只提取有用信号（试用过的模型、提示词变体、成本事件、评估结果），并将其整理为紧凑的 JSON，这样后续流程就能基于一个精简的结构化数据包运行，而不必处理冗长的原始 transcript。

python scripts/session_ingest.py <session_id> > /tmp/rag-eval-bundle.json
# or with a direct path:
python scripts/session_ingest.py --path /path/to/transcript.jsonl > /tmp/rag-eval-bundle.json

数据包包含：models_tried、prompts_tried（仅哈希值）、iterations、total_cost_usd、summary_stats。将其提供给步骤 1；不要粘贴原始 transcript。

为何重要： transcript 中可能有 10 万个以上的噪声 token。导入脚本只进行正则提取，将大模型预算留给实际审计和评估扫描规划。这是硬性要求，不是优化选项。

步骤 1 — 审计技术栈

阅读 references/best-practices.md，并检查用户的仓库和向量存储配置。生成一份结构化报告，涵盖：

  • 架构（检索类型：dense / hybrid / rerank；分块策略；提示词结构）
  • 技术栈（嵌入模型、大模型、向量存储）
  • 资源（数据集大小、金标准集大小、过往评估运行记录）
  • 风险（已知反模式、缺失项）

向用户展示报告，并询问要优先解决哪些问题。

步骤 2 — 提出评估扫描计划

根据审计结果，提出 3–8 个待测变体。首次运行时保持网格较小（默认：2 个提示词 × 2 个模型 × 1 个检索变体 = 4 个单元）。根据金标准集大小 × 变体数 × 平均 token 数 × 服务商定价估算成本。向用户展示成本估算，并等待用户确认后再运行。

步骤 3 — 运行评估扫描

使用 scripts/eval_sweep.py（调用方式参见脚本头部）。该脚本读取 YAML 配置，针对金标准集运行每个变体，记录每个变体的成本和回答质量，并将结果追加到 history.jsonl。

防护措施：

  • 绝不超过预算上限 — 达到上限时立即停止正在进行的扫描。
  • 绝不修改用户的仓库。所有产物都写入 .rag-eval/（将其加入 gitignore）。
  • 任何预计会超过用户上限的评估扫描，都必须先征得确认。
第 4 步 — 排名并汇报

完成扫描后，按考虑成本的评分对各变体进行排名：quality × (1 / log(1 + cost))。报告以下内容：

  • 排名前 3 的变体及其质量指标和成本
  • 与上一版最佳方案相比有哪些变化
  • 可以尝试的具体下一项实验

将完整报告写入 .rag-eval/reports/<timestamp>.md。

第 5 步 — 自我改进

每次后续运行之前，先读取 history.jsonl，并考虑用户已经尝试过的内容。避免重新测试已被否决的变体。指出规律（“模型 A、B、C 在多跳查询上的表现都不佳——下一步尝试重排序器”）。

可复用资源

  • scripts/eval_sweep.py — 网格搜索运行器。读取 eval_config.yaml，并将结果写入 history.jsonl。
  • references/best-practices.md — 基于证据的 RAG 检查清单，Agent 将其用作参考基准。
  • references/evidence-base.md — 近期 RAG 研究的参考资料，以及各项技术适用的场景。
  • assets/eval_config.template.yaml — 可复制到用户仓库的入门配置。
  • assets/gold_set.template.jsonl — 用于展示黄金集格式的 3 组示例问答。

备注

  • 成本是主要的失败原因。 未确认预算时绝不运行。优先选择规模较小的扫描；用户随时可以再次运行。
  • 不得修改仓库。 所有输出都写入目标仓库中的 .rag-eval/。
  • 不确定最佳实践时，进行网络调研。 使用 tavily-search 或 firecrawl-research 获取最新证据，再综合整理到审计报告中。
  • 听从用户的决定。 修改目标仓库中的任何文件之前，务必先征得确认。

评论

支持 Markdown