多智能体+RAG实战：Spring AI Alibaba构建企业知识库问答

多智能体加RAG这两个词放在一起很多人第一反应是是不是有点过度设计。我最初也这么想——一个检索增强生成的应用单Agent跑得好好的为什么要拆成多个智能体直到我接手一个内部知识库问答项目文档横跨产品手册、运维记录、合同模板、故障复盘四大类单Agent方案在意图识别上就开始翻车用户问上次那个接口超时怎么处理的它跑去检索产品手册里的接口文档答得头头是道但完全跑偏。那次之后我才认真研究多智能体编排这条路用Spring AI Alibaba落地了一版跑下来效果确实不一样。这篇就把整个设计思路、核心实现和踩过的坑完整摊开讲适合有一定Java后端基础、想在企业知识问答场景里把RAG做扎实的同行参考小白也能看懂整体逻辑照着骨架能搭出自己的版本。1. 整体架构设计与方案选型思路1.1 为什么单Agent撑不住复杂知识场景先说清楚问题在哪。RAG的本质是先检索、再生成单Agent模式下检索和生成是串行绑死的一个查询进来走同一个检索器、同一个提示词模板、同一个大模型。这套结构在知识域单一的时候非常香代码少、链路短、调试直观。但企业知识库的典型特征是异构——不同来源的文档语言风格、术语体系、甚至正确答案的形态都不一样。我拿实际项目举例。产品手册类问题用户要的是精确参数和操作步骤检索时应该偏向结构化片段生成时要求严格引用原文故障复盘类问题用户要的是当时怎么定位、怎么解决的叙事逻辑检索要跨多篇复盘做关联生成时允许归纳总结合同模板类问题用户要的是条款原文一个字都不能改这时候生成环节甚至应该退化成抽取拼接。你让一个Agent用同一套检索参数和提示词去覆盖这三类必然有一类被牺牲。多智能体的核心价值就在这里把理解意图和执行任务解耦。一个路由智能体专门判断这个问题属于哪一类、该交给谁下游每个专职智能体带着自己的检索策略、提示词模板、甚至不同的大模型配置去干活。这跟微服务拆分的逻辑一模一样——不是为拆而拆是因为不同业务的SLA和实现路径确实不同。1.2 Spring AI Alibaba在这个方案里扮演什么角色选型这块我对比过几套方案。纯手写编排自己写状态机调大模型API灵活但重复劳动多LangChain4j生态成熟但Java侧的Agent编排抽象还在演进Spring AI Alibaba的优势在于它把模型接入、提示词管理、工具调用、对话记忆这几层做了统一抽象而且和Spring生态无缝衔接——你项目里已有的Bean、配置中心、监控埋点都能直接复用。具体到多智能体场景它提供的几个能力是关键ChatClient的统一封装每个智能体本质上是一个配置了不同系统提示词和工具的ChatClient创建成本极低可以按需实例化多个。Advisor机制检索增强可以通过Advisor挂载到ChatClient上意味着检索策略变成了可插拔的组件不同智能体挂不同的Advisor即可。工具调用Function Calling路由智能体可以把下游智能体包装成工具让大模型自己决定调哪个这是实现智能路由最省事的方式。对话记忆多轮对话的上下文管理有现成抽象不用自己维护会话状态。提示Spring AI Alibaba的版本迭代较快Advisor和Tool的API在不同小版本间有过调整落地前务必锁定版本并核对官方示例别直接抄半年前的博客代码。1.3 整体链路长什么样我把整个应用拆成四层从上到下依次是接入层统一对话入口、路由层意图识别与分发、执行层多个专职RAG智能体、基础层向量库、文档解析、模型服务。用户的一次提问先经过路由层判断意图再分发给对应的专职智能体专职智能体完成检索-重排-生成后返回路由层负责汇总和兜底。这个分层的好处是每一层都能独立演进。比如后来我要给故障复盘智能体加一个按时间线排序的后处理只动执行层那一个类路由层和接入层完全不受影响。下面几节就按这个结构逐层拆。2. 路由层意图识别到底怎么做才靠谱2.1 三种路由策略的取舍路由是整个多智能体方案的咽喉路由错了后面全错。我试过三种做法各有适用场景策略实现方式优点缺点适用场景关键词规则路由正则/关键词匹配零延迟、可控覆盖不全、维护成本高意图极固定的场景分类模型路由微调小模型做分类准确率高、快需要标注数据、训练成本意图类别稳定且数据充足大模型路由让大模型判断意图灵活、零训练有延迟、偶发不稳定意图类别多、边界模糊我最终选的是大模型路由为主、关键词规则兜底的混合方案。原因很实际项目初期没有标注数据分类模型无从谈起而纯关键词规则在接口超时怎么处理这种既像运维又像产品的问题上直接失效。大模型路由虽然多一次调用实测增加300-800ms但意图判断的准确率从规则版的六成多提到了九成以上这个延迟换准确率我认为值。2.2 用工具调用实现智能路由具体实现上我把每个下游智能体包装成一个工具交给路由智能体的大模型去选择。核心思路是给路由智能体一个精简的系统提示词明确列出每个工具的职责边界然后让模型输出工具调用。// 路由智能体的系统提示词精简版 String routerPrompt 你是一个知识库问答的路由器。根据用户问题选择最合适的处理工具。 可选工具 - productManualAgent产品参数、操作步骤、功能说明类问题 - opsRecordAgent故障处理、运维操作、历史事件类问题 - contractAgent合同条款、法律文本原文查询类问题 - generalAgent无法明确归类时的通用问答 只输出工具名不要解释。 ;这里有个细节值得说提示词里必须写清边界而不是能力。早期我写的是productManualAgent处理产品相关问题结果模型把产品接口超时也判给了它。改成涉及具体参数、操作步骤、功能说明的才归它涉及故障现象和处理的归opsRecordAgent之后误判明显下降。边界的描述要具体到什么情况不归我管这比正面描述有效得多。2.3 路由结果的校验与兜底大模型路由不是百分百可靠的必须做校验。我的做法是路由智能体返回工具名后先做一次合法性校验是不是在预设的工具列表里不合法就落到generalAgent同时对置信度做一层判断——如果模型在回复里带了犹豫性表述比如可能大概也降级到通用智能体。public String route(String question) { String toolName routerClient.prompt() .system(routerPrompt) .user(question) .call() .content() .trim(); // 合法性校验 if (!VALID_AGENTS.contains(toolName)) { log.warn(路由结果非法降级到通用智能体: {}, toolName); return generalAgent; } return toolName; }注意路由层一定要有通用兜底智能体它不追求精准但保证任何问题都有回应。没有兜底的路由系统一旦模型抽风返回空或乱码整个对话就断了用户体验极差。3. 执行层每个专职智能体的差异化设计3.1 检索策略为什么要按智能体分开这是多智能体RAG和单Agent RAG最本质的区别。单Agent只有一个检索器多智能体则是每个智能体一套检索配置。我按知识类型做了三套差异化配置产品手册智能体文档结构规整、术语统一检索用较小的分块300-500字保证片段精确相似度阈值设高0.75以上宁可少召回也不要引入噪声。Top-K取3-5即可因为答案通常集中在少数几个片段。故障复盘智能体复盘文档是叙事性的一个故障的完整处理过程可能横跨几千字分块要放大到800-1200字否则现象-定位-解决的因果链会被切断。相似度阈值可以放低到0.6Top-K取8-10因为需要跨多篇复盘做关联归纳。合同条款智能体这个最特殊检索精度要求极高但生成环节要克制。分块按条款自然边界切一条一款检索用混合检索向量关键词因为法律术语的精确匹配很重要。生成时提示词强制要求只引用检索到的原文不得改写。这套差异化配置不是拍脑袋定的是拿真实问题集反复调出来的。我建议你也这么做先准备50-100条真实问题标注好正确答案来源然后针对每类智能体单独调参看召回率和答案准确率的变化。3.2 用Advisor挂载检索增强Spring AI Alibaba的Advisor机制让检索增强变成了可插拔组件。每个智能体创建自己的ChatClient时挂载不同的QuestionAnswerAdvisor或自定义的检索Advisor检索逻辑就绑定在这个智能体上了。// 产品手册智能体 ChatClient manualAgent ChatClient.builder(chatModel) .defaultSystem(你是产品手册助手回答必须基于检索到的原文给出具体参数和步骤。) .defaultAdvisors( new QuestionAnswerAdvisor(vectorStore, SearchRequest.builder() .topK(4) .similarityThreshold(0.75) .build()) ) .build(); // 故障复盘智能体 ChatClient opsAgent ChatClient.builder(chatModel) .defaultSystem(你是运维复盘助手综合多篇复盘记录按现象、定位、解决三段式回答。) .defaultAdvisors( new QuestionAnswerAdvisor(vectorStore, SearchRequest.builder() .topK(10) .similarityThreshold(0.6) .build()) ) .build();这里的关键认知是Advisor不只是检索它是检索注入提示词的完整链路。QuestionAnswerAdvisor会把检索到的文档拼进用户消息的上下文里模型看到的是问题参考资料。所以不同智能体挂不同Advisor等于同时定制了检索参数和上下文注入方式。3.3 提示词模板的差异化设计提示词这块我踩过最大的坑是一套模板打天下。早期所有智能体共用一个请基于以下资料回答问题的模板结果合同智能体开始自由发挥改写条款这在法务场景是灾难。后来我给每个智能体写了独立的系统提示词核心差异在三个维度引用要求产品手册要求标注参数出处合同要求逐字引用原文并标注条款号故障复盘允许归纳总结但需列出参考的复盘编号。拒答策略产品手册检索不到时明确说资料中未找到该参数合同检索不到时直接拒答未检索到相关条款故障复盘可以基于相似案例给参考性建议但需声明。输出结构产品手册用参数表步骤列表故障复盘用现象/定位/解决三段式合同用条款原文适用说明。String contractSystem 你是合同条款查询助手。严格遵守 1. 只输出检索到的条款原文不得改写、不得归纳。 2. 每条引用标注来源文档名和条款号。 3. 检索不到相关条款时直接回复未检索到相关条款不得推测。 ;提示拒答策略一定要在提示词里写死并且用测试用例验证。大模型天生乐于助人你不明确禁止它检索不到也会编一个看起来合理的答案这在企业场景里比不回答更危险。4. 基础层文档处理与检索质量优化4.1 文档解析与分块的真实难点多智能体方案对文档质量的要求比单Agent更高因为每个智能体的检索精度都依赖分块质量。我在文档解析上花的时间比写Agent代码还多几个真实难点PDF表格解析产品手册里大量参数表用通用PDF解析器出来是一堆错位的文本参数和值对不上。后来针对表格区域单独处理用结构化提取把表格转成参数名: 参数值的键值对再入库检索准确率立竿见影。跨页段落故障复盘经常一个处理过程跨两三页按页切块会把因果链切断。我的做法是先做全文拼接再按语义边界标题、空行、编号切块而不是按页切。术语一致性不同文档对同一概念叫法不同比如接口超时和请求超时纯向量检索可能漏召回。我在入库前做了一层术语归一化维护一个同义词表把变体统一映射到标准术语检索时也做同样映射。4.2 分块参数的计算与选择分块大小不是拍脑袋我按一个简单公式估算分块大小 ≈ 单个答案的平均长度 × 1.5。比如产品参数类答案平均200字分块取300字左右故障复盘答案平均600字分块取900字左右。1.5的系数是给上下文留余量保证答案完整落在块内。重叠overlap我统一取分块大小的15%-20%。这个比例的经验来源是答案很少恰好落在块边界重叠太小会切断关键句太大则冗余检索增多。实测15%在多数场景够用叙事性文档可以提到20%。文档类型分块大小重叠比例相似度阈值Top-K产品手册300-500字15%0.753-5故障复盘800-1200字20%0.68-10合同条款按条款切10%0.7混合检索54.3 检索质量的两道保险光靠向量检索不够我加了两道保险。第一道是混合检索向量检索负责语义相似关键词检索BM25类负责精确术语匹配两路结果做加权融合。合同场景对这道保险依赖最重因为第X条第Y款这种精确引用纯向量检索经常召回语义相近但条款号不对的内容。第二道是重排Rerank初检召回Top-20再用重排模型精排取Top-5。重排模型对问题-片段的相关性判断比向量相似度更准尤其在片段较长时优势明显。这一步会增加100-300ms延迟但对答案准确率的提升在故障复盘场景实测有十几个百分点值得。// 混合检索的融合逻辑简化示意 ListDocument vectorResults vectorSearch(question, 20); ListDocument keywordResults keywordSearch(question, 20); ListDocument merged weightedMerge(vectorResults, keywordResults, 0.6, 0.4); ListDocument reranked rerankModel.rerank(question, merged, 5);5. 多智能体协同与上下文管理5.1 智能体之间要不要互相调用这里有个设计决策智能体之间是完全隔离还是允许协作。完全隔离实现简单但遇到复合问题就抓瞎——比如这个接口超时了产品文档里怎么说的历史上怎么处理的这需要产品手册智能体和故障复盘智能体都参与。我的方案是路由层支持多工具调用路由智能体判断出问题涉及多个领域时可以返回多个工具名由编排层依次调用后汇总。实现上不是让智能体互相调用那会形成复杂的依赖图而是让路由层做扇出-汇总。// 多工具扇出执行简化示意 ListString agents router.routeMulti(question); // 可能返回多个 ListString answers agents.stream() .map(name - agentRegistry.get(name).answer(question)) .toList(); String finalAnswer synthesizer.synthesize(question, answers);汇总环节我用一个轻量的综合智能体它的职责是把多个智能体的回答整合成一段连贯的话并标注各部分来源。这里要注意综合智能体不做新的检索只做整合避免引入未经验证的内容。5.2 多轮对话的上下文怎么管多轮对话在多智能体场景下有个特殊问题上下文该跟着谁走。用户第一轮问产品参数路由到产品手册智能体第二轮问那它的故障率呢应该路由到故障复盘智能体但它指代的是第一轮的产品这个指代关系必须传递过去。我的做法是维护一份会话级共享上下文记录最近几轮的问题、路由结果和关键实体。路由时把这份上下文一起喂给路由智能体让它结合历史判断当前意图执行时把相关实体注入到当前智能体的提示词里。// 会话上下文结构简化 class SessionContext { ListTurn history; // 历史轮次 MapString, String entities; // 提取的关键实体如产品名、故障编号 }实体提取我用的是轻量方案每轮对话后让模型抽取一次关键实体产品名、系统名、时间等存进entities。下一轮路由和执行时把这些实体作为已知信息注入。这套机制让那它的故障率呢能正确理解为某产品的故障率路由到故障复盘智能体。注意共享上下文要设上限我限制只保留最近5轮和最多10个实体否则上下文越滚越长既增加token成本又稀释关键信息。5.3 并发与性能的实际考量多智能体扇出执行时串行调用会明显拖慢响应。我的做法是扇出的多个智能体并行执行用CompletableFuture做异步编排最后统一等待汇总。ListCompletableFutureString futures agents.stream() .map(name - CompletableFuture.supplyAsync( () - agentRegistry.get(name).answer(question), executor)) .toList(); ListString answers futures.stream() .map(CompletableFuture::join) .toList();实测下来两个智能体扇出并行比串行快40%左右因为单个智能体的检索生成本身有几百毫秒到一两秒。但要注意线程池隔离——不同智能体可能调用不同模型服务共用一个线程池容易互相拖累我给每个智能体配了独立的小线程池。6. 常见问题与排查实录6.1 路由误判怎么定位和修正路由误判是最常见的问题排查思路是先看日志再看提示词。我在路由层打了详细日志原始问题、路由结果、模型原始输出、耗时。误判发生时先看模型原始输出是不是带了多余解释导致解析失败再看是不是提示词边界描述不清。一个典型case用户问合同里的违约责任怎么写的被路由到了产品手册智能体。查日志发现模型输出是contractAgent因为涉及合同带了括号解释导致字符串匹配失败落到了兜底。修正方法是提示词里强调只输出工具名不要任何其他字符同时在解析时做一次清洗提取第一个匹配的工具名。6.2 检索召回不准的三层排查法召回不准我按三层排查分块层、检索层、重排层。分块层把召回片段打印出来看答案是不是被切断了。如果是调大分块或重叠。检索层看正确答案所在片段有没有进初检Top-20。没进说明向量或关键词检索有问题检查术语归一化和混合检索权重。重排层正确答案在初检里但被重排挤掉了说明重排模型对该类问题判断有偏考虑调整重排的输入格式或换模型。现象可能原因排查动作解决方向答案被截断分块过小打印召回片段调大分块/重叠正确答案未召回术语不一致检查同义词映射补同义词表召回噪声多阈值过低看相似度分布提高阈值精确引用错纯向量检索检查是否走混合检索加关键词检索重排后变差重排模型不适配对比重排前后换模型/调输入6.3 大模型编答案的抑制手段这是RAG最顽固的问题。我的组合拳是提示词强制拒答 检索结果为空时短路 答案后校验。短路逻辑很关键如果检索返回的片段相似度全部低于阈值直接返回未找到相关资料根本不调生成模型。这一步能挡掉相当一部分编造。答案后校验则是让一个轻量模型检查生成的答案是否都能在检索片段里找到依据找不到依据的句子标记出来或直接剔除。// 检索为空时短路 ListDocument docs retrieve(question); if (docs.isEmpty() || docs.get(0).getScore() MIN_THRESHOLD) { return 未在知识库中检索到相关资料建议换个问法或联系人工。; }提示拒答话术要友好且给出下一步别只甩一句不知道。我用的模板是未检索到相关资料你可以尝试换个关键词、缩小范围或转人工。用户体验差别很大。6.4 多智能体扇出时的超时与降级扇出并行时只要有一个智能体超时整个汇总就被拖住。我的处理是给每个智能体设独立超时比如3秒超时的直接跳过并在最终答案里标注某部分暂未获取到其余正常汇总。这样保证整体响应时间可控不会因为一个慢智能体拖垮全局。降级策略也要提前设计模型服务不可用时路由层降级到关键词规则路由执行层降级到只返回检索原文不生成。这些降级路径平时用不到但故障时能保证系统可用而不是全挂。7. 落地过程中的经验与参数调优心得7.1 从单Agent迁移到多智能体的渐进路径如果你手上已经有一个跑着的单Agent RAG别一上来就全量重构。我的建议是先加路由层再拆执行层。第一步在现有单Agent前面加一个路由智能体把明显不属于当前知识域的问题分流出去哪怕分流后只是给个提示先验证路由准确率。第二步把分流出去的那类问题做成第一个专职智能体跑通后再逐个拆。这样每一步都有可回退的余地风险可控。我当初就是先拆了故障复盘这一类因为它和产品手册的检索策略差异最大收益最明显跑了两周确认效果后才拆合同类。渐进迁移的另一个好处是你能在真实流量下积累每类问题的样本为后续调参提供依据。7.2 参数调优的优先级排序参数一大堆先调哪个我的经验优先级是分块质量 检索阈值 Top-K 重排 提示词。分块是地基分块不好后面全白搭阈值决定召回质量的下限Top-K影响成本和噪声重排是锦上添花提示词虽然重要但调整成本低可以随时改。调参一定要有评估集。我维护了一个200条真实问题的评估集每条标注了正确答案来源文档每次调参跑一遍看召回率和答案准确率两个指标。没有评估集的调参就是盲调改了一个参数不知道是变好还是变坏。7.3 成本与延迟的平衡多智能体天然比单Agent贵——路由多一次模型调用扇出可能多次检索多次生成。我的成本控制手段有三个路由用轻量模型意图判断不需要强模型扇出只在路由判断为复合问题时触发多数问题单智能体就够重排只对初检Top-20做不对全量做。延迟方面路由的300-800ms是硬开销但可以通过流式输出缓解感知——路由完成后立即开始流式返回用户感知到的首字延迟并不高。扇出并行则把多智能体的额外延迟压到了可接受范围。实测端到端P95延迟在3-5秒对于知识问答场景是可以接受的。8. 这套方案适合谁、不适合谁多智能体RAG不是银弹。它适合知识域明显异构、对答案准确性要求高、有一定工程能力维护多套配置的场景比如企业内部知识库、专业领域问答、多产品线客服。它不适合知识域单一、追求极简架构、团队规模小的场景——那种情况下单Agent加好的分块和提示词性价比高得多。我在实际项目里最大的体会是多智能体的复杂度主要不在代码而在配置管理和效果评估。每个智能体一套检索参数、一套提示词、一套评估标准维护成本是实打实的。所以上这套方案前先问自己一句我的知识域真的异构到单Agent搞不定了吗如果答案是肯定的那这套分层路由加专职智能体的结构确实能把RAG的效果往上抬一个台阶。后续如果要扩展我打算在综合智能体那层加一个答案溯源能力把每个结论对应的原文片段直接展示给用户让可信度再往上走一步。