EvalScope+ Langfuse实现RAG三指标分层计算与组合归因操作手册

EvalScope Langfuse实现RAG三指标分层计算与组合归因操作手册核心落地逻辑EvalScope 负责分层执行评测、自动计算指标Langfuse 负责全链路Trace埋点、结果回写、根因定位与资产沉淀。通过「三层独立评测任务 唯一标识透传 指标双向回写 归因矩阵自动匹配」实现三个核心指标的精准拆分计算与组合根因定位彻底解决“效果差但不知道差在哪”的痛点。一、前置准备环境与规范对齐1. 工具环境部署工具版本核心部署说明EvalScope1.8.0部署评测服务配置RAGAS评测引擎、裁判模型critic_llm、被测RAG系统接口地址开启独立检索评测、生成评测、端到端评测三类任务模板Langfusev2.42.0部署服务端获取API密钥被测RAG系统接入Python/JS SDK开启全链路Span埋点启用Dataset数据集功能与评分回写API2. RAG系统埋点规范Langfuse侧必须按节点打独立Span透传统一标识这是分层定位的基础# 伪代码示例RAG全链路埋点fromlangfuseimportLangfuse langfuseLangfuse()defrag_pipeline(query,eval_case_idNone):# 根Span透传评测用例ID绑定整条Tracewithlangfuse.trace(namerag_full,metadata{eval_case_id:eval_case_id,version:v1.2.3})astrace:# 节点1查询改写withtrace.span(namequery_rewrite)asspan:rewritten_queryquery_rewrite(query)span.set_input(query)span.set_output(rewritten_query)# 节点2混合检索withtrace.span(namehybrid_retriever)asspan:chunkshybrid_retrieve(rewritten_query,top_k10)span.set_input(rewritten_query)span.set_output([c[id]forcinchunks])# 记录召回片段IDspan.set_metadata({top_k:10,recall_num:len(chunks)})# 节点3答案生成withtrace.span(nameanswer_generation)asspan:answergenerate_answer(query,chunks)span.set_input({query:query,contexts:chunks})span.set_output(answer)returnanswer强制规范每条评测请求必须透传唯一eval_case_id写入根Trace的metadata实现用例与链路一一对应检索、生成节点必须打独立Span分别记录输入输出统一版本标签知识库版本、Prompt版本、模型版本确保可横向对比3. 三层测试集准备EvalScope侧按评测层级分别准备独立测试集禁止混用测试集类型用途标准字段检索层测试集计算召回率query、ground_truth_chunks标准相关片段ID列表生成层测试集计算忠实度query、fixed_contexts固定召回片段端到端测试集计算答案正确率query、ground_truth_answer标准答案数据来源可从Langfuse Dataset导入历史bad case或人工标注Golden Set也可使用EvalScope自动生成基础测试集后人工校验。二、三个核心指标分开计算的具体操作1. 检索召回率RecallK——检索层独立评测控制变量原则固定索引库、固定TopK参数只跑检索链路完全绕开生成模型指标仅反映检索能力。EvalScope侧操作新建「检索独立评测」任务选择指标Recall10、Precision10、NDCG10、MRR导入检索层测试集配置被测系统的纯检索接口地址只返回召回片段不生成答案配置参数top_k10与生产环境一致、索引版本与生产对齐执行评测EvalScope自动比对召回片段与标注的标准片段输出各指标得分RecallK 命中的相关片段数 / 全部相关片段总数支持按查询维度输出每条用例的召回明细Langfuse侧对应每条检索请求对应hybrid_retriever节点Span记录召回的片段ID列表通过eval_case_id筛选Trace可逐条回放召回结果人工复核漏检片段可按检索节点的错误标签批量导出漏检case验证标准指标仅由检索策略、分块、Embedding影响与生成模型无关同一测试集多次执行结果波动≤2%否则索引不稳定2. 生成忠实度Faithfulness——生成层独立评测控制变量原则固定输入同一批召回上下文只跑生成环节完全排除检索质量干扰指标仅反映生成模型与Prompt的忠实性。EvalScope侧操作新建「生成层独立评测」任务选择RAGAS框架的Faithfulness忠实度指标导入生成层测试集固定传入同一批标准上下文片段配置被测系统的纯生成接口地址只接收上下文query返回答案不做检索配置裁判模型建议能力≥被测模型如70B级或GPT-4o确保评分稳定执行评测EvalScope自动拆解原子事实校验每个事实是否有上下文支撑输出整体忠实度与幻觉率忠实度 有上下文支撑的原子事实数 / 总原子事实数幻觉率 1 - 忠实度Langfuse侧对应每条生成请求对应answer_generation节点Span记录输入上下文与输出回答评测完成后通过EvalScope API将忠实度得分、幻觉标记回写到对应Trace的评分与标签中低忠实度的Trace一键导入Langfuse Dataset作为bad case沉淀验证标准固定上下文时忠实度波动≤3%否则生成模型不稳定或Prompt有歧义必须先用50条人工标注样本校准裁判模型Cohen’s Kappa ≥ 0.75方可批量执行3. 端到端答案正确率Answer Correctness——全链路综合评测控制变量原则全链路跑通不隔离任何环节模拟真实用户请求指标反映系统整体效果。EvalScope侧操作新建「端到端RAG评测」任务选择指标AnswerCorrectness答案正确性、AnswerRelevancy答案相关性导入端到端测试集配置被测系统的完整RAG接口地址配置评分规则事实准确性、完整性、合规性三个维度加权执行评测EvalScope对比最终回答与标准答案输出整体正确率答案正确率 回答完全正确的样本数 / 总样本数Langfuse侧对应每条请求对应完整Trace包含所有节点的输入输出、耗时、Token消耗评测结果回写到根Trace的评分中标记correct/incorrect标签与错误类型支持按错误类型筛选Trace回放全链路定位问题三、三维组合归因实现方法通过「指标回写 归因矩阵 自动标签」实现三个指标的组合分析与根因自动定位。1. 指标双向回写数据打通核心评测完成后通过API将EvalScope计算的三个指标回写到Langfuse对应Trace中指标回写位置标签字段检索召回率检索节点Span评分recall_score、retrieval_level: high/medium/low生成忠实度生成节点Span评分faithfulness_score、generation_level: high/medium/low答案正确率根Trace评分correctness_score、overall_level: high/medium/low实现方式EvalScope回调 Langfuse Score API每条eval_case_id匹配对应Trace批量回写评分与标签。2. 自动归因矩阵匹配配置规则引擎根据三个指标的高/中/低组合自动判定根因层级与优化方向检索召回率生成忠实度端到端正确率自动根因标签优化优先级核心优化方向70%低≥85%高低bottleneck:retrievalP0优化分块、Embedding、混合检索、重排序≥85%高70%低低bottleneck:generationP0优化系统Prompt、增加事实约束、更换生成模型≥85%高≥85%高低bottleneck:knowledgeP1修正知识库内容、补充多跳推理能力70%低70%低低bottleneck:fullP0从底座开始逐层优化≥85%高≥85%高≥85%高quality:excellent-维持基线监控长尾场景3. Langfuse侧归因分析操作按标签筛选在Langfuse Trace页面按bottleneck:retrieval等标签筛选批量查看对应问题轨迹回放点击单条Trace逐层展开Span回放每个节点的输入输出人工复核根因判断维度统计按标签统计各瓶颈类型的占比输出质量分布报表资产沉淀将标注好根因的bad case一键导入Langfuse Dataset补充进EvalScope测试集形成闭环四、工程化进阶自动化执行与CI集成1. 批量自动化执行流程触发方式知识库更新、Prompt迭代、模型升级时通过Webhook自动触发EvalScope评测任务执行顺序严格自下而上先跑检索层评测达标再跑生成层最后跑端到端下层不达标直接终止结果输出自动生成评测报告 Langfuse Trace链接 根因分析结论通知推送核心指标劣化自动推送告警附带问题定位链接2. 嵌入CI/CD质量门禁合并前门禁检索召回率、生成忠实度不低于基线禁止合并发布前门禁端到端正确率不低于基线安全红线零违规禁止发布所有门禁结果关联Langfuse Trace链接研发可直接跳转定位问题3. 持续优化闭环每日定时跑核心基准集监控指标漂移每周从Langfuse拉取线上bad case人工复核后补充测试集每月输出质量趋势报告分析各层级指标变化与优化收益五、常见落地避坑变量不隔离混着算算忠实度时用真实检索结果每次检索都不一样导致忠实度波动大。必须固定上下文输入。K值不匹配评测用Recall20生产实际用Top5指标好看但无业务价值。K值必须和生产环境一致。裁判模型不校准直接用LLM-as-Judge打分不做校准结果偏差大。必须先用人工样本做一致性校验。用例和链路对应不上不透传唯一case_id批量执行后无法一一对应排查效率极低。只看总分不看分层只关注端到端正确率不做分层指标出问题完全不知道优化方向。