Dify 中级实验10知识库深度调优——如何科学评估检索质量Dify 实验系列 · 中级 10/20 | 实验编号DIFY-102-11基于 Dify 1.16.1 实测2026-081. 业务场景先讲一个我们实际遇到的场景。一家做企业软件的公司把 500 页产品技术文档做成知识库上线 RAG 问答。用户问「怎么重置密码」回答牛头不对马嘴问「错误码 E1001 是什么」答非所问。技术支持团队每天收到「AI 答得不对」的投诉但问题出在哪——分段检索模式TopK——没人说得清因为没有任何数据。我们第一次接这类需求时第一反应也是「把 TopK、分段策略、Rerank 挨个调一遍看哪个效果好」。真正动手才发现——改了一堆参数效果原地踏步因为「好不好」根本没有数字不知道现在多差就不知道改没改对。后来才想明白调优的前提是评估——先有尺子才有调参。这不是个例。任何 RAG 系统的调优都是这个模式改一个参数好不好得用数字说话——没有评估体系的调优就是瞎调。产品文档知识库、客服 FAQ、RAG 问答系统上线前调优与持续监控都需要一把「尺子」。2. 场景痛点这个流程的痛点在知识库建设团队身上体现得最直接召回差但说不清差在哪用户反馈答非所问定位不到是「哪类查询召不回」——操作类错误码类概念类全靠猜——猜着调参越调越心虚没有数字连「改对了」都无法定义。调参靠感觉TopK、分段策略、Rerank 改来改去不知道哪个参数真正生效——改了一堆效果原地踏步。回归没有基线改了分段策略旧的能答的问题会不会变差无从对比——调优像打地鼠。数据与检索脱节种子文档不含用户真实问法检索「看似正常实则全空」关键词命中率恒 0还误判「检索坏了」。本质上调优的前提是评估——先能量化「现在多差」才能知道「改没改对」。参数可以慢慢调尺子必须一开始就有。3. 方案为什么是评估工作流本实验不调某个单一参数而是先搭一把「尺子」——一个检索质量评估工作流用测试集自动打分测试集驱动10 组典型查询硬编码在代码节点query expected_keywords 期望关键词 expected_doc 期望命中文档覆盖操作类重置密码、错误码类E1001、概念类什么是 RAG量化评分每组用例算关键词命中率 Top1 文档匹配综合评分 0.5 × 关键词命中率 0.5 × Top1 匹配——数字说话回归闭环同一测试集反复跑调整分段策略/TopK/Rerank 前后对比 avg_score——分数上升说明改对了这就是「评估比配置重要」的落地方式。这篇文章我们就用它搭一个「检索质量评估器」10 组用例自动检索、自动评分、自动汇总。4. 整体架构逐条检索评估迭代开始无变量生成测试集Code 10 组 query/expected_keywords/expected_doc拆解测试项Code item → query/expected_keywords/expected_doc技术文档库检索KB top_k 3 迭代内评估检索质量Code keyword_rate top1_match score汇总综合评分Code结束链路很清晰生成测试集 → 迭代逐条检索并评估 → 汇总综合评分。迭代把 10 组用例逐条过一遍 KB 检索每条算一个分数最后汇总成 avg_score/avg_keyword_rate/top1_matched——一把可复用的尺子。5. 模块设计5.1 测试集Code测试用例要覆盖典型查询形态操作类重置密码、错误码类E1001、概念类什么是 RAGdefmain()-dict:test_cases[{query:如何重置密码,expected_keywords:[密码重置,忘记密码,重置步骤],expected_doc:用户管理_密码重置},{query:API 调用频率限制,expected_keywords:[限流,Rate Limit,API配额],expected_doc:API文档_限流策略},{query:错误码 E1001 是什么,expected_keywords:[E1001,错误码,排查],expected_doc:排障手册_错误码},# ... 共 10 组]return{test_cases:test_cases}5.2 迭代内知识库检索迭代内 KB 节点需要五件套isInIteration/iteration_id/parentId/sourcePosition/targetPosition-data:dataset_ids:-459c4981-6b76-43e7-b44f-c430f33ef035# 你的知识库 IDisInIteration:trueiteration_id:iter_testoutput_retrieval_result:true# 必须 true否则 result 为空parentId:iter_testquery_attachment_selector:[]query_variable_selector:[cd_split,query]retrieval_mode:singlescore_threshold:0.0title:技术文档库检索top_k:3type:knowledge-retrievalid:kb_retrieve5.3 评估节点CodeKB 结果传给代码节点参数类型必须声明为list检索结果是 list[dict]评分 0.5 × 关键词命中率 0.5 × Top1 文档匹配defmain(query:str,expected_keywords:str,expected_doc:str,retrieved:list)-dict:importjson retrievedretrievedifisinstance(retrieved,list)else[]texts[str(r.get(content,))forrinretrievedifisinstance(r,dict)]all_text .join(texts).lower()try:kwsjson.loads(expected_keywordsor[])exceptException:kws[]kws[str(k).lower()forkinkwsifk]hitssum(1forkinkwsifkinall_text)keyword_rateround(hits/len(kws),2)ifkwselse0.0top1_titlestr(retrieved[0].get(title,))ifretrievedandisinstance(retrieved[0],dict)elsetop1_matchbool(top1_title)andstr(expected_docor).lower()intop1_title.lower()scoreround(keyword_rate*0.5(1.0iftop1_matchelse0.0)*0.5,2)return{eval_text:json.dumps({...},ensure_asciiFalse)}# 序列化成 string 供迭代收集5.4 迭代输出与汇总迭代output_selector只能选可见类型array[object] 收集不到所以评估节点输出eval_text字符串、output_type: array[string]汇总节点再逐个json.loads聚合defmain(results:list)-dict:importjson total0;score_sum0.0;kw_sum0.0;top1_ok0forrinresults:try:djson.loads(r)ifisinstance(r,str)else{}exceptException:d{}total1score_sumfloat(d.get(score,0)or0)kw_sumfloat(d.get(keyword_hit_rate,0)or0)ifd.get(top1_match):top1_ok1return{total_cases:total,avg_score:round(score_sum/total,2)iftotalelse0.0,avg_keyword_rate:round(kw_sum/total,2)iftotalelse0.0,top1_matched:top1_ok,summary_text:检索质量评估共 {} 组用例综合评分 {}关键词命中率均值 {}Top1 文档匹配 {} 组.format(total,round(score_sum/total,2)iftotalelse0.0,round(kw_sum/total,2)iftotalelse0.0,top1_ok),}6. 运行验证检查项预期实测total_cases1010avg_keyword_rate0~1 之间反映关键词召回水平视知识库质量而定top1_matched期望文档命中 Top1 的组数视知识库质量而定summary_text「共 10 组用例综合评分 X关键词命中率均值 YTop1 文档匹配 Z 组」与预期一致调优闭环跑出基线 → 调整知识库分段策略/TopK/是否开 Rerank → 重跑同一测试集 → 对比 avg_score。分数上升说明改对了——这就是「评估比配置重要」的落地方式。7. 实战坑坑现象修复KB 结果传给 code 签名写 str运行报list object has no attribute ...参数类型声明list用r.get(content, )提取忘了 output_retrieval_result[kb, result]返回空评估全 0设为true结果才是结构化 list[dict]把 Rerank 当工作流节点找不到 rerank 节点类型Rerank 是知识库检索设置dataset 层面 reranking_enable reranking_model不在工作流里配置迭代 output_selector 选 array[object]迭代输出为空数组评估节点输出json.dumps字符串output_type: array[string]测试集超过 30 组迭代报then length of var item must be less than 30 elements测试集留余量本实验 10 组种子文档不含测试关键词关键词命中率恒 0误判「检索坏了」测试集与知识库种子文档对齐先验证数据再调参 调优顺序建议① 先保证文档质量预处理清洗、分段语义完整——垃圾进垃圾出② 再选检索模式混合 单一有 rerank 模型就开③ 最后调 TopK/Score 阈值每次只改一个变量并用同一测试集回归。8. 实验文档及源码获取实验文档完整操作步骤DIFY-11知识库深度调优.md源码可直接导入dify102_11_知识库调优评估.yml文章聚焦核心配置与采坑点实验的完整分步操作节点搭建/参数表/调试指引见实验文档原文。下一篇Dify 中级实验11高级 RAG 流水线——如何搭建多路检索与精排 你在这个实验的场景里踩过什么坑欢迎评论区分享你的实战经验。