1. 为什么 Agent 必须接上历史工单和知识库做过客服系统或者内部 IT 支持平台的人都有一个共同体会用户提的问题八成以上不是第一次出现。同一个报错、同一个流程卡点、同一个配置疑问换个人、换个时间又会重新问一遍。如果 Agent 每次都是从零开始推理不给它任何历史依据那它给出的答案质量完全取决于模型本身的泛化能力稳定性极差而且很容易出现“一本正经胡说八道”的情况。这个项目的核心目标很明确让 Agent 在回答用户问题之前先去历史工单库和知识库里检索相似问题把检索到的内容作为上下文喂给模型让它“有依据地回答”而不是凭空生成。这里涉及几个关键技术点历史工单的结构化处理、知识库的构建与检索、search_knowledge 工具的封装、RAG 检索增强生成的编排逻辑以及相似问题的召回与排序策略。适合谁来参考如果你正在做 Agent 开发、智能客服、内部知识助手或者你已经在用 Dify、LangChain、AgentScope 这类框架搭东西但发现 Agent 回答质量不稳定、经常答非所问那这篇内容就是为你写的。哪怕你只是刚接触 RAG 概念我也会把每个环节拆开讲清楚保证你能照着复现。我自己的背景是做了几年企业级客服系统和知识管理平台踩过不少坑。下面这些内容一部分来自实际项目经验一部分是基于常见工程实践做的合理补充我会明确标注哪些是实测结论、哪些是推荐做法。2. 整体架构设计与核心思路拆解2.1 为什么不是“直接把所有工单丢给模型”很多人第一反应是既然有历史工单那就全部塞进 prompt 里让模型自己找相似问题不就行了这个思路在小数据量下勉强能用但工单量一旦上千token 消耗会爆炸而且模型在长上下文里的注意力会分散召回准确率反而下降。更关键的是工单里往往包含大量敏感信息用户手机号、订单号、内部系统地址全量塞入存在合规风险。所以正确的做法是两阶段检索第一阶段用向量检索或关键词检索从海量工单中快速召回 Top-K 候选第二阶段把候选内容作为上下文交给模型做精排和答案生成。这就是 RAG 的经典范式也是这个项目采用的核心架构。2.2 整体链路拆解整个链路可以拆成四个层次数据层历史工单的清洗、脱敏、结构化知识库文档的切片与向量化检索层向量检索 关键词检索的混合召回相似度排序工具层把检索能力封装成 Agent 可调用的search_knowledge工具编排层Agent 的决策逻辑什么时候调用检索、怎么用检索结果、检索不到怎么办这四层里数据层是最脏最累的活但决定了整个系统的上限。检索层是效果的关键工具层是工程化的核心编排层是体验的保障。下面我逐层展开。2.3 方案选型为什么选混合检索而不是纯向量纯向量检索Dense Retrieval擅长语义匹配比如用户问“登录不上”和工单里写“无法进入系统”向量能召回。但它有个致命弱点对专有名词、错误码、版本号这类精确匹配不敏感。用户问“报错 E5021 怎么解决”向量检索可能召回一堆语义相似但错误码不同的工单。所以我在实际项目里一律用混合检索向量检索负责语义召回BM25 或关键词检索负责精确匹配两路结果做加权融合常用 RRF 倒数排名融合。实测下来混合检索的 Top-5 命中率比纯向量高出 15 到 25 个百分点尤其在技术类工单场景下差距更明显。提示如果你的知识库规模小于 500 条纯向量检索够用超过 1000 条强烈建议上混合检索。3. 历史工单与知识库的数据处理细节3.1 工单数据的清洗与脱敏历史工单最大的问题是“脏”。我见过太多工单里混着聊天记录、内部备注、甚至测试数据。直接拿来做知识库检索出来的东西根本没法用。清洗步骤我一般分四步走去重同一问题被多次提交的工单只保留解决质量最高的那条。判断标准可以是“有明确解决方案 客户确认解决”。脱敏手机号、身份证、邮箱、内部 IP、订单号统一替换成占位符比如[PHONE]、[ORDER_ID]。这一步必须做不然后面检索出来直接暴露给模型和用户。结构化把工单拆成“问题描述”“解决过程”“最终方案”三个字段。很多工单的解决过程是客服和用户的来回对话需要人工或规则提取出真正的解决方案。质量过滤没有解决方案的工单、纯咨询类无回复的工单、明显是测试的工单全部剔除。这里有个经验不要试图用模型自动提取解决方案至少在初期不要。我试过用 LLM 批量提取工单解决方案准确率大概只有 70% 左右剩下的 30% 需要人工复核反而更费时间。前期老老实实人工标注几百条高质量数据比什么都强。3.2 知识库文档的切片策略知识库文档比如产品手册、FAQ、操作指南的切片方式直接决定检索效果。常见的坑是“按固定字数切”比如每 500 字一刀。这样切出来的片段经常把一句话拦腰截断语义不完整。我的做法是按语义结构切Markdown 文档按标题层级切每个二级标题下的内容作为一个 chunkPDF 文档先转成 Markdown 再切表格类内容单独处理不要和正文混在一起每个 chunk 控制在 300 到 800 字之间太短信息不足太长检索精度下降切片的时候还要保留元数据来源文档名、章节标题、更新时间。这些元数据在检索结果展示和排序时非常有用。比如用户问的是最新版本的问题那更新时间近的 chunk 应该加权。3.3 向量化模型的选择向量化模型的选择上我实测过几类方案方案类型代表模型优势劣势适用场景通用中文向量常见中文 embedding 模型语义理解好对专业术语弱通用客服问答领域微调向量在工单数据上微调领域召回率高需要标注数据垂直行业多语言向量多语言 embedding支持中英混合中文精度略低国际化产品对于大多数团队我建议先用通用中文向量模型跑起来收集一批 bad case 之后再考虑微调。不要一上来就搞微调投入产出比不划算。注意向量维度不是越高越好。1024 维和 768 维在实际检索效果上差距很小但存储和计算成本差不少。我一般选 768 维性价比最高。4. search_knowledge 工具的封装与实现4.1 工具接口设计Agent 调用工具的本质是“模型输出一个结构化请求系统执行后返回结果”。所以search_knowledge的接口设计要满足两个要求参数简单、返回结构化。我设计的接口大概是这样{ name: search_knowledge, description: 根据用户问题检索历史工单和知识库返回最相似的解决方案, parameters: { query: 用户的问题描述, top_k: 返回结果数量默认5, source_type: 检索来源可选 ticket / kb / all } }query是必填的top_k和source_type给默认值这样模型不用每次都填所有参数降低调用出错率。4.2 检索结果的格式化检索回来的原始结果是一堆 chunk 和相似度分数直接丢给模型效果不好。我会做一层格式化把结果整理成模型容易理解的格式[检索结果 1] 来源历史工单 #12345 相似度0.92 问题用户无法登录提示密码错误 解决方案重置密码后仍无法登录检查发现账号被锁定解锁后恢复正常。 [检索结果 2] 来源知识库 - 账号管理章节 相似度0.87 内容账号连续输错密码 5 次会被锁定锁定后需等待 30 分钟或联系管理员解锁。这样模型能清楚看到每条结果的来源、相似度和内容方便它判断哪条更相关、怎么组织答案。4.3 相似度阈值与兜底策略这里有个关键细节不是所有检索结果都值得用。如果最高相似度只有 0.5说明知识库里根本没有相关内容这时候硬塞给模型反而会误导它。我的做法是设一个阈值比如 0.75。高于阈值的结果正常使用低于阈值的直接丢弃并在返回里告诉模型“未找到高相关度的历史记录”。模型收到这个信号后可以选择如实告诉用户“这个问题我暂时没有找到相关记录”而不是强行编一个答案。提示阈值不要拍脑袋定。拿一批标注好的测试问题跑一遍检索看正样本的相似度分布取一个能覆盖 80% 正样本的值作为阈值。4.4 工具调用的错误处理Agent 调用工具时可能出各种问题检索服务超时、向量库连接失败、query 为空。这些都要在工具层处理好返回明确的错误信息给模型而不是直接抛异常导致整个对话中断。我一般会返回这样的结构{ status: error, message: 检索服务暂时不可用请稍后重试或直接根据已有知识回答 }模型收到这个之后可以选择降级回答而不是卡死。5. Agent 编排逻辑什么时候查、怎么用查到的内容5.1 检索时机的判断不是每个问题都需要查知识库。用户说“你好”“谢谢”这种寒暄查了也是浪费。所以 Agent 需要一个判断逻辑什么问题该查什么问题不该查。我的做法是在 system prompt 里明确写清楚涉及具体产品功能、报错、操作步骤的问题必须先调用search_knowledge寒暄、闲聊、通用常识问题直接回答不调用工具如果第一次检索结果相似度都低于阈值可以换一个 query 再试一次但最多重试一次这个逻辑看起来简单但实际效果很好。关键是 prompt 里要把边界写清楚不能含糊。5.2 多轮检索的策略有些复杂问题一次检索不够。比如用户问“我登录不上而且重置密码也失败了”这里面其实包含两个子问题登录问题和密码重置问题。这时候 Agent 应该拆成两次检索分别查“登录失败”和“密码重置失败”然后把两组结果合并。我在编排层会加一个逻辑如果用户的问题里包含“而且”“并且”“同时”这类连接词或者问题明显包含多个独立诉求就触发多轮检索。这个判断可以交给模型做也可以写规则我倾向于交给模型因为规则很难覆盖所有情况。5.3 检索结果与模型知识的融合检索到内容之后怎么让模型用这里有个常见误区很多人直接把检索结果拼在 prompt 里然后说“请根据以上内容回答”。这样模型很容易被检索结果带偏尤其是检索结果质量不高的时候。我的做法是在 prompt 里明确优先级优先使用检索结果中的解决方案。如果检索结果与你的已有知识冲突以检索结果为准。如果检索结果不完整可以结合你的知识补充但要明确标注哪些是补充内容。这样既保证了有依据又给了模型一定的灵活性。5.4 引用来源的展示用户体验上回答里最好能标注来源。比如“根据历史工单 #12345 的解决方案……”。这样用户能判断答案的可信度也方便追溯。实现上就是在检索结果里带上来源 ID让模型在生成答案时引用。这个功能看起来小但对内部支持场景特别有用。客服人员看到来源后可以直接点进去看完整工单比只看 Agent 的总结更放心。6. 常见问题与排查技巧实录6.1 检索召回率低怎么办这是最常见的问题。用户问的问题知识库里明明有但就是检索不到。排查思路按优先级来检查切片是否合理把知识库里的 chunk 打印出来看是不是把完整答案切碎了。如果是调整切片策略。检查 query 改写用户的口语化表达和知识库的书面表达差距很大。可以在检索前加一步 query 改写用模型把用户问题改写成更规范的检索语句。检查向量模型换一个向量模型试试或者在同一批测试数据上对比几个模型的召回率。加关键词检索如果纯向量召回不行加上 BM25 做混合检索通常能明显改善。6.2 检索结果相关性差怎么办召回是召回了但排在前面的都不是最相关的。这时候要看排序策略相似度分数是否可靠有些向量模型的分数分布很集中0.8 和 0.85 可能代表完全不同的相关性需要做分数校准。是否考虑了时效性旧工单的解决方案可能已经过时需要在排序时给新内容加权。是否考虑了来源可信度官方知识库的内容应该比用户提交的工单权重更高。我一般会做一个加权公式最终分数 相似度 * 0.7 时效性 * 0.2 来源权重 * 0.1。具体权重根据业务调整。6.3 Agent 不调用工具怎么办有时候模型就是不愿意调用search_knowledge直接凭自己的知识回答。这个问题通常出在 prompt 上工具描述不够清晰模型不知道什么时候该用system prompt 里没有强调“必须检索”工具名称和参数设计不合理模型理解不了解决办法是把工具描述写得更具体在 system prompt 里用明确的指令比如“对于任何涉及产品功能的问题你的第一个动作必须是调用 search_knowledge”。6.4 检索太慢影响体验怎么办检索链路长了确实会慢。优化方向向量检索和关键词检索并行执行不要串行向量库加缓存相同 query 直接返回缓存结果Top-K 不要设太大5 到 10 条足够多了反而慢且干扰如果知识库很大考虑做分层检索先粗筛再精排6.5 常见问题速查表问题现象可能原因排查方向解决建议检索不到相关内容切片不合理 / query 表达差异大打印 chunk 检查完整性调整切片策略加 query 改写召回内容不相关排序策略单一检查相似度分数分布加时效性和来源权重Agent 不调用工具prompt 指令不明确检查工具描述和 system prompt强化指令明确调用条件检索响应慢串行检索 / Top-K 过大看检索链路耗时并行检索减小 Top-K答案与检索结果冲突prompt 优先级不清晰检查 prompt 中的使用规则明确检索结果优先敏感信息泄露脱敏不彻底抽查检索结果加强脱敏规则加过滤层7. 一些实操心得和踩坑记录先说一个我踩过的大坑早期做知识库的时候我图省事直接把工单的原始对话记录整段向量化。结果检索出来的内容全是“您好请问有什么可以帮您”“我这边帮您看一下”这种废话真正的解决方案被淹没在对话里。后来改成只向量化“问题描述 最终解决方案”两个字段召回质量立刻上了一个台阶。这个教训告诉我数据质量比模型选择重要得多。第二个心得是关于阈值调优的。我一开始把相似度阈值设成 0.8结果很多明明相关的结果被过滤掉了。后来拿测试集跑了一遍发现正样本的相似度中位数在 0.72 左右阈值调到 0.7 之后召回率明显提升同时引入的噪声也在可接受范围内。所以阈值一定要用数据说话不要凭感觉。第三个是工具调用的重试逻辑。Agent 有时候会用同一个 query 反复调用检索陷入死循环。我在工具层加了一个简单的去重如果连续两次调用的 query 相似度超过 0.95第二次直接返回“已检索过相似问题请基于已有结果回答”。这个小改动解决了不少死循环问题。最后分享一个关于混合检索权重的经验。RRF 融合的时候向量检索和关键词检索的权重我一般设成 0.6 比 0.4偏向向量。但在技术类工单场景下我会调到 0.5 比 0.5因为错误码、版本号这类精确匹配太重要了。这个权重没有标准答案拿你的业务数据跑 A/B 测试看哪个组合的 Top-5 命中率最高就用哪个。这套方案我在两个项目里落地过一个是内部 IT 支持助手一个是面向客户的产品客服 Agent。前者的知识库规模大概 3000 条工单加 500 篇文档后者规模更大一些。实测下来接入历史工单和知识库之后Agent 的首次解决率从 40% 左右提升到了 70% 以上人工转接率下降了一半多。当然这个数字跟业务场景强相关但方向是明确的让 Agent 有依据地回答比让它自由发挥靠谱得多。 Agent接入历史工单与知识库：RAG检索增强生成实战指南
1. 为什么 Agent 必须接上历史工单和知识库做过客服系统或者内部 IT 支持平台的人都有一个共同体会用户提的问题八成以上不是第一次出现。同一个报错、同一个流程卡点、同一个配置疑问换个人、换个时间又会重新问一遍。如果 Agent 每次都是从零开始推理不给它任何历史依据那它给出的答案质量完全取决于模型本身的泛化能力稳定性极差而且很容易出现“一本正经胡说八道”的情况。这个项目的核心目标很明确让 Agent 在回答用户问题之前先去历史工单库和知识库里检索相似问题把检索到的内容作为上下文喂给模型让它“有依据地回答”而不是凭空生成。这里涉及几个关键技术点历史工单的结构化处理、知识库的构建与检索、search_knowledge 工具的封装、RAG 检索增强生成的编排逻辑以及相似问题的召回与排序策略。适合谁来参考如果你正在做 Agent 开发、智能客服、内部知识助手或者你已经在用 Dify、LangChain、AgentScope 这类框架搭东西但发现 Agent 回答质量不稳定、经常答非所问那这篇内容就是为你写的。哪怕你只是刚接触 RAG 概念我也会把每个环节拆开讲清楚保证你能照着复现。我自己的背景是做了几年企业级客服系统和知识管理平台踩过不少坑。下面这些内容一部分来自实际项目经验一部分是基于常见工程实践做的合理补充我会明确标注哪些是实测结论、哪些是推荐做法。2. 整体架构设计与核心思路拆解2.1 为什么不是“直接把所有工单丢给模型”很多人第一反应是既然有历史工单那就全部塞进 prompt 里让模型自己找相似问题不就行了这个思路在小数据量下勉强能用但工单量一旦上千token 消耗会爆炸而且模型在长上下文里的注意力会分散召回准确率反而下降。更关键的是工单里往往包含大量敏感信息用户手机号、订单号、内部系统地址全量塞入存在合规风险。所以正确的做法是两阶段检索第一阶段用向量检索或关键词检索从海量工单中快速召回 Top-K 候选第二阶段把候选内容作为上下文交给模型做精排和答案生成。这就是 RAG 的经典范式也是这个项目采用的核心架构。2.2 整体链路拆解整个链路可以拆成四个层次数据层历史工单的清洗、脱敏、结构化知识库文档的切片与向量化检索层向量检索 关键词检索的混合召回相似度排序工具层把检索能力封装成 Agent 可调用的search_knowledge工具编排层Agent 的决策逻辑什么时候调用检索、怎么用检索结果、检索不到怎么办这四层里数据层是最脏最累的活但决定了整个系统的上限。检索层是效果的关键工具层是工程化的核心编排层是体验的保障。下面我逐层展开。2.3 方案选型为什么选混合检索而不是纯向量纯向量检索Dense Retrieval擅长语义匹配比如用户问“登录不上”和工单里写“无法进入系统”向量能召回。但它有个致命弱点对专有名词、错误码、版本号这类精确匹配不敏感。用户问“报错 E5021 怎么解决”向量检索可能召回一堆语义相似但错误码不同的工单。所以我在实际项目里一律用混合检索向量检索负责语义召回BM25 或关键词检索负责精确匹配两路结果做加权融合常用 RRF 倒数排名融合。实测下来混合检索的 Top-5 命中率比纯向量高出 15 到 25 个百分点尤其在技术类工单场景下差距更明显。提示如果你的知识库规模小于 500 条纯向量检索够用超过 1000 条强烈建议上混合检索。3. 历史工单与知识库的数据处理细节3.1 工单数据的清洗与脱敏历史工单最大的问题是“脏”。我见过太多工单里混着聊天记录、内部备注、甚至测试数据。直接拿来做知识库检索出来的东西根本没法用。清洗步骤我一般分四步走去重同一问题被多次提交的工单只保留解决质量最高的那条。判断标准可以是“有明确解决方案 客户确认解决”。脱敏手机号、身份证、邮箱、内部 IP、订单号统一替换成占位符比如[PHONE]、[ORDER_ID]。这一步必须做不然后面检索出来直接暴露给模型和用户。结构化把工单拆成“问题描述”“解决过程”“最终方案”三个字段。很多工单的解决过程是客服和用户的来回对话需要人工或规则提取出真正的解决方案。质量过滤没有解决方案的工单、纯咨询类无回复的工单、明显是测试的工单全部剔除。这里有个经验不要试图用模型自动提取解决方案至少在初期不要。我试过用 LLM 批量提取工单解决方案准确率大概只有 70% 左右剩下的 30% 需要人工复核反而更费时间。前期老老实实人工标注几百条高质量数据比什么都强。3.2 知识库文档的切片策略知识库文档比如产品手册、FAQ、操作指南的切片方式直接决定检索效果。常见的坑是“按固定字数切”比如每 500 字一刀。这样切出来的片段经常把一句话拦腰截断语义不完整。我的做法是按语义结构切Markdown 文档按标题层级切每个二级标题下的内容作为一个 chunkPDF 文档先转成 Markdown 再切表格类内容单独处理不要和正文混在一起每个 chunk 控制在 300 到 800 字之间太短信息不足太长检索精度下降切片的时候还要保留元数据来源文档名、章节标题、更新时间。这些元数据在检索结果展示和排序时非常有用。比如用户问的是最新版本的问题那更新时间近的 chunk 应该加权。3.3 向量化模型的选择向量化模型的选择上我实测过几类方案方案类型代表模型优势劣势适用场景通用中文向量常见中文 embedding 模型语义理解好对专业术语弱通用客服问答领域微调向量在工单数据上微调领域召回率高需要标注数据垂直行业多语言向量多语言 embedding支持中英混合中文精度略低国际化产品对于大多数团队我建议先用通用中文向量模型跑起来收集一批 bad case 之后再考虑微调。不要一上来就搞微调投入产出比不划算。注意向量维度不是越高越好。1024 维和 768 维在实际检索效果上差距很小但存储和计算成本差不少。我一般选 768 维性价比最高。4. search_knowledge 工具的封装与实现4.1 工具接口设计Agent 调用工具的本质是“模型输出一个结构化请求系统执行后返回结果”。所以search_knowledge的接口设计要满足两个要求参数简单、返回结构化。我设计的接口大概是这样{ name: search_knowledge, description: 根据用户问题检索历史工单和知识库返回最相似的解决方案, parameters: { query: 用户的问题描述, top_k: 返回结果数量默认5, source_type: 检索来源可选 ticket / kb / all } }query是必填的top_k和source_type给默认值这样模型不用每次都填所有参数降低调用出错率。4.2 检索结果的格式化检索回来的原始结果是一堆 chunk 和相似度分数直接丢给模型效果不好。我会做一层格式化把结果整理成模型容易理解的格式[检索结果 1] 来源历史工单 #12345 相似度0.92 问题用户无法登录提示密码错误 解决方案重置密码后仍无法登录检查发现账号被锁定解锁后恢复正常。 [检索结果 2] 来源知识库 - 账号管理章节 相似度0.87 内容账号连续输错密码 5 次会被锁定锁定后需等待 30 分钟或联系管理员解锁。这样模型能清楚看到每条结果的来源、相似度和内容方便它判断哪条更相关、怎么组织答案。4.3 相似度阈值与兜底策略这里有个关键细节不是所有检索结果都值得用。如果最高相似度只有 0.5说明知识库里根本没有相关内容这时候硬塞给模型反而会误导它。我的做法是设一个阈值比如 0.75。高于阈值的结果正常使用低于阈值的直接丢弃并在返回里告诉模型“未找到高相关度的历史记录”。模型收到这个信号后可以选择如实告诉用户“这个问题我暂时没有找到相关记录”而不是强行编一个答案。提示阈值不要拍脑袋定。拿一批标注好的测试问题跑一遍检索看正样本的相似度分布取一个能覆盖 80% 正样本的值作为阈值。4.4 工具调用的错误处理Agent 调用工具时可能出各种问题检索服务超时、向量库连接失败、query 为空。这些都要在工具层处理好返回明确的错误信息给模型而不是直接抛异常导致整个对话中断。我一般会返回这样的结构{ status: error, message: 检索服务暂时不可用请稍后重试或直接根据已有知识回答 }模型收到这个之后可以选择降级回答而不是卡死。5. Agent 编排逻辑什么时候查、怎么用查到的内容5.1 检索时机的判断不是每个问题都需要查知识库。用户说“你好”“谢谢”这种寒暄查了也是浪费。所以 Agent 需要一个判断逻辑什么问题该查什么问题不该查。我的做法是在 system prompt 里明确写清楚涉及具体产品功能、报错、操作步骤的问题必须先调用search_knowledge寒暄、闲聊、通用常识问题直接回答不调用工具如果第一次检索结果相似度都低于阈值可以换一个 query 再试一次但最多重试一次这个逻辑看起来简单但实际效果很好。关键是 prompt 里要把边界写清楚不能含糊。5.2 多轮检索的策略有些复杂问题一次检索不够。比如用户问“我登录不上而且重置密码也失败了”这里面其实包含两个子问题登录问题和密码重置问题。这时候 Agent 应该拆成两次检索分别查“登录失败”和“密码重置失败”然后把两组结果合并。我在编排层会加一个逻辑如果用户的问题里包含“而且”“并且”“同时”这类连接词或者问题明显包含多个独立诉求就触发多轮检索。这个判断可以交给模型做也可以写规则我倾向于交给模型因为规则很难覆盖所有情况。5.3 检索结果与模型知识的融合检索到内容之后怎么让模型用这里有个常见误区很多人直接把检索结果拼在 prompt 里然后说“请根据以上内容回答”。这样模型很容易被检索结果带偏尤其是检索结果质量不高的时候。我的做法是在 prompt 里明确优先级优先使用检索结果中的解决方案。如果检索结果与你的已有知识冲突以检索结果为准。如果检索结果不完整可以结合你的知识补充但要明确标注哪些是补充内容。这样既保证了有依据又给了模型一定的灵活性。5.4 引用来源的展示用户体验上回答里最好能标注来源。比如“根据历史工单 #12345 的解决方案……”。这样用户能判断答案的可信度也方便追溯。实现上就是在检索结果里带上来源 ID让模型在生成答案时引用。这个功能看起来小但对内部支持场景特别有用。客服人员看到来源后可以直接点进去看完整工单比只看 Agent 的总结更放心。6. 常见问题与排查技巧实录6.1 检索召回率低怎么办这是最常见的问题。用户问的问题知识库里明明有但就是检索不到。排查思路按优先级来检查切片是否合理把知识库里的 chunk 打印出来看是不是把完整答案切碎了。如果是调整切片策略。检查 query 改写用户的口语化表达和知识库的书面表达差距很大。可以在检索前加一步 query 改写用模型把用户问题改写成更规范的检索语句。检查向量模型换一个向量模型试试或者在同一批测试数据上对比几个模型的召回率。加关键词检索如果纯向量召回不行加上 BM25 做混合检索通常能明显改善。6.2 检索结果相关性差怎么办召回是召回了但排在前面的都不是最相关的。这时候要看排序策略相似度分数是否可靠有些向量模型的分数分布很集中0.8 和 0.85 可能代表完全不同的相关性需要做分数校准。是否考虑了时效性旧工单的解决方案可能已经过时需要在排序时给新内容加权。是否考虑了来源可信度官方知识库的内容应该比用户提交的工单权重更高。我一般会做一个加权公式最终分数 相似度 * 0.7 时效性 * 0.2 来源权重 * 0.1。具体权重根据业务调整。6.3 Agent 不调用工具怎么办有时候模型就是不愿意调用search_knowledge直接凭自己的知识回答。这个问题通常出在 prompt 上工具描述不够清晰模型不知道什么时候该用system prompt 里没有强调“必须检索”工具名称和参数设计不合理模型理解不了解决办法是把工具描述写得更具体在 system prompt 里用明确的指令比如“对于任何涉及产品功能的问题你的第一个动作必须是调用 search_knowledge”。6.4 检索太慢影响体验怎么办检索链路长了确实会慢。优化方向向量检索和关键词检索并行执行不要串行向量库加缓存相同 query 直接返回缓存结果Top-K 不要设太大5 到 10 条足够多了反而慢且干扰如果知识库很大考虑做分层检索先粗筛再精排6.5 常见问题速查表问题现象可能原因排查方向解决建议检索不到相关内容切片不合理 / query 表达差异大打印 chunk 检查完整性调整切片策略加 query 改写召回内容不相关排序策略单一检查相似度分数分布加时效性和来源权重Agent 不调用工具prompt 指令不明确检查工具描述和 system prompt强化指令明确调用条件检索响应慢串行检索 / Top-K 过大看检索链路耗时并行检索减小 Top-K答案与检索结果冲突prompt 优先级不清晰检查 prompt 中的使用规则明确检索结果优先敏感信息泄露脱敏不彻底抽查检索结果加强脱敏规则加过滤层7. 一些实操心得和踩坑记录先说一个我踩过的大坑早期做知识库的时候我图省事直接把工单的原始对话记录整段向量化。结果检索出来的内容全是“您好请问有什么可以帮您”“我这边帮您看一下”这种废话真正的解决方案被淹没在对话里。后来改成只向量化“问题描述 最终解决方案”两个字段召回质量立刻上了一个台阶。这个教训告诉我数据质量比模型选择重要得多。第二个心得是关于阈值调优的。我一开始把相似度阈值设成 0.8结果很多明明相关的结果被过滤掉了。后来拿测试集跑了一遍发现正样本的相似度中位数在 0.72 左右阈值调到 0.7 之后召回率明显提升同时引入的噪声也在可接受范围内。所以阈值一定要用数据说话不要凭感觉。第三个是工具调用的重试逻辑。Agent 有时候会用同一个 query 反复调用检索陷入死循环。我在工具层加了一个简单的去重如果连续两次调用的 query 相似度超过 0.95第二次直接返回“已检索过相似问题请基于已有结果回答”。这个小改动解决了不少死循环问题。最后分享一个关于混合检索权重的经验。RRF 融合的时候向量检索和关键词检索的权重我一般设成 0.6 比 0.4偏向向量。但在技术类工单场景下我会调到 0.5 比 0.5因为错误码、版本号这类精确匹配太重要了。这个权重没有标准答案拿你的业务数据跑 A/B 测试看哪个组合的 Top-5 命中率最高就用哪个。这套方案我在两个项目里落地过一个是内部 IT 支持助手一个是面向客户的产品客服 Agent。前者的知识库规模大概 3000 条工单加 500 篇文档后者规模更大一些。实测下来接入历史工单和知识库之后Agent 的首次解决率从 40% 左右提升到了 70% 以上人工转接率下降了一半多。当然这个数字跟业务场景强相关但方向是明确的让 Agent 有依据地回答比让它自由发挥靠谱得多。