用途
rag-eval 用于评估 RAG（检索增强生成）系统，核心目标是分离检索层与生成层的问题。单一“RAG 准确率”无法区分是没检索到正确文档，还是模型没有正确使用文档，该技能将两者拆开，帮助定位应当修复的环节。
主要能力
- 加载 RAG 轨迹，校验 query + context + answer 三元组的数据完整性。
- 区分检索与生成两层，分别定位失败来源。
- 使用 OpenJudge 的 HallucinationGrader 评估忠实度，判断答案是否基于检索文档；分数 1-5，≥4 视为忠实。
- 使用 RelevanceGrader 评估答案是否真正回应查询。
- 在具备 gold_doc_ids 时计算 Recall@k、Precision@k、MRR 等检索指标；缺失时可使用语义相关性判定作为代理。
- 构建检索与生成的 2×2 诊断矩阵，交叉分析根因：检索好且忠实、检索好但幻觉、检索差但忠实、两者皆坏。
- 输出按优先级排列的问题与具体修复建议。
- 附带脚本 scripts/rag_diagnostic.py，仅用标准库、不依赖 OpenJudge，读取 JSONL 轨迹并输出忠实/幻觉划分、2×2 矩阵和主要问题。
使用方式
每条轨迹至少包含 query、retrieved_docs（每项含 id 与 text）、answer；可选 reference_answer、gold_doc_ids。若只有原始字符串，可先包裹为带 id 的字典。
快速路径：完成忠实度判定后运行
python scripts/rag_diagnostic.py --traces traces.jsonl
轨迹行可含 {"faithful":bool} 或 {"faithfulness_score":1-5}（≥4 视为忠实），可选检索信号 {"retrieval_good":bool} 或 {"recall_at_k":0-1}（≥0.5 视为良好）。可用 --self-test 自检。
详细步骤依次为：加载并校验轨迹；分离检索与生成；用 HallucinationGrader 做忠实度评估；用检索指标或语义判定做检索评估；构建诊断矩阵；输出发现。若检索是瓶颈，可对分块大小与重叠做网格搜索，重新分块、嵌入、检索并计算 Recall@5。
适用场景
- 判断 RAG 系统是否存在幻觉。
- 优化分块策略并做前后对比。
- 构建 RAG 评测数据集。
- 在修改生成提示词前后测量忠实度变化。
限制
需要已有的 RAG 轨迹数据；忠实度与相关性评估依赖 OpenJudge 评分器或其它判定模型；检索指标依赖 gold_doc_ids，缺失时只能使用语义代理。定价、平台支持范围等暂未提供。