1. 背景企业知识问答为什么最终选了 RAG 方案先交代一下项目场景。我所在的团队负责的是某企业内部知识管理平台的升级里面沉淀了产品手册、故障排查文档、历史工单、API 说明和流程规范累计几百份文档且以每个月几十篇的速度持续新增。最初大家靠传统关键字搜索找资料但文档一多精确匹配就非常痛苦——尤其是那种“我用一段自然语言描述故障现象希望能直接拿到排查步骤和结论”的场景传统搜索基本无能为力。所以领导层提了一个原始但很刚的需求让员工像聊天一样问问题系统从现有文档里找答案并且答案要能对应到原始出处。当时我们锁定的技术方向就是企业级 RAG 问答系统也就是检索增强生成。这套方案并不新鲜核心思路是先对知识库文档做解析、切片、向量化存入向量数据库用户提问后先从向量库召回相关片段再把召回内容作为上下文交给大模型生成回答。换句话说答案不是模型凭空编造的而是先找到依据再组织语言。这样一来模型的通用语义理解能力得到了保留企业内部专有的、随时更新的知识也能被覆盖而不是每隔几个月就去重新微调一次模型。这篇文章适合两类人看一类是在 Java 技术栈里准备落地 RAG 系统想看看真实工程怎么组织的另一类是已经接触过 Spring AI Alibaba但不确定 ReactAgent 到底该放在哪一环Qdrant 怎么配合才不踩坑。我会尽量把这个项目里的关键决策、代码片段、参数调优和踩坑记录都写清楚相当于给这套实现做一次完整的复盘。1.1 项目要解决的核心问题这个项目表面上是在做一个“企业知识库问答”实际上要解决三个层次的问题。第一层是知识的碎片化。文档散落在多个仓库、目录甚至个人电脑里PDF、Word、Markdown 混在一起格式不统一。员工想找一份半年前的故障处理记录可能得问三个人才能定位到文件。第二层是检索精度的问题。传统的关键字搜索对同义词、口语化提问、隐含语义完全不敏感比如文档里写的是“内存溢出”用户问的是“服务莫名其妙崩了”这两者在字面上没有交集但在语义上是强相关的。第三层是答案的可信度问题。直接用大模型做问答会很流畅但员工并不敢直接相信模型的输出因为没有人知道它依据的是哪份文档如果答错了还会误导处理流程甚至酿成事故。所以系统在设计之初就定了几条硬性指标回答必须基于知识库内容不能自由发挥答案必须附带引用来源知识库更新后系统能在小时级内感知到变化而不是等重新训练同时还要支持按部门和权限范围过滤不同角色只能检索到与自己相关的文档。这几条指标基本把方案推向了 RAG而不是微调。1.2 RAG 与微调的选择为什么不是单独微调模型在真正动手之前团队内部进行过一次 RAG 和微调的对比讨论。当时有同事提出过一个疑问既然企业内部知识是相对固定的为什么不直接用领域数据微调大模型让模型本身学会这些知识这样线上问答就不需要去查向量库了响应还会更快。这个思路在某些场景下没问题但在我们这个项目里存在几个硬伤。首先是更新成本知识库每周都有新增内容如果每次新增都要触发一次微调训练资源消耗先不说流程周期就很难接受。其次是数据量和分布的问题几百份文档对于微调来说仍然太少很容易导致模型过拟合或记住噪音反而降低泛化能力。然后是溯源问题微调后的模型是一个黑盒它隐约知道某个知识点但不可能告诉你这段话出自哪份文档的哪一页这对于需要追责的企业场景是致命的。而 RAG 天然把“知识存储”和“生成能力”解耦知识更新只需要重新切片、重新向量化回答时还能把检索到的原文一起交给模型由模型引用段落编号溯源链路非常清晰。当然 RAG 也不是没有代价。它会引入检索失败的风险如果召回环节没找到正确片段再强的模型也回答不了。所以在实施阶段我们花了很大精力在文档解析、切片策略、向量检索和重排上而不是只关注最后的 Agent 对话效果。下面我会从技术选型开始把整条链路完整展开。2. 技术选型为什么是 Spring AI Alibaba ReactAgent Qdrant项目组是标准的 Java 技术栈这一点直接决定了框架选择的范围。早期我们考虑过 LangChain 系列它在 Python 社区生态丰富但在 Java 端的维护质量和社区活跃度参差不齐引入之后团队还得专门养一个 Python 服务来完成 Agent 编排等于增加了一个跨语言维护节点。后来又看到 Spring AI 逐渐成熟而 Spring AI Alibaba 作为适配国内模型生态的扩展包已经实现了包括 ChatModel、EmbeddingModel、VectorStore、Agent 在内的一系列抽象并且兼容 Spring Boot 的自动装配习惯对 Java 团队非常友好。Qdrant 的选择相对曲折。当时对比过几款向量数据库最终从部署复杂度、过滤能力、性能稳定性和社区活跃度几个维度打分Qdrant 胜出。它用 Rust 实现单机性能很好支持 payload 元数据过滤这对我们后续做多租户和权限隔离非常关键。而且它的 Docker 镜像启动非常轻量企业内部测试环境一台 4C8G 的机器就能跑起来压力测试后再上高可用集群迭代路径很平滑。2.1 Spring AI Alibaba 在项目里的真实定位Spring AI Alibaba 不是一个独立的大模型平台它更像是一座连接 Java 业务系统和模型能力的桥梁。它把不同模型厂商的差异封装成了统一的接口比如 ChatModel 对应大语言模型EmbeddingModel 对应向量化模型VectorStore 对应向量数据库操作。业务代码写完之后如果想从模型 A 切换到模型 B只需要改配置和依赖不需要改核心逻辑。这一点在企业内部非常重要因为模型厂商的商务策略和技术指标变化很快我们不能把系统绑死在一家厂商上。ReactAgent 是 Spring AI Alibaba 里基于 ReAct 模式实现的一种 Agent 实现。ReAct 是 Reasoning and Acting 的缩写核心思路是让模型在推理过程中交替进行“思考”“行动”“观察”。在复杂的问答场景里用户的一次问题可能需要多次检索才能回答完整比如“先查一下某模块的报错原因再根据报错信息找到对应的处理方案”。ReactAgent 能把“检索知识库”封装成工具函数模型会根据用户问题自己决定要不要调用这个工具、传入什么查询词、观察返回结果后继续推理最终生成有依据的回答。这种编排方式比单纯的“检索一次就生成答案”要灵活得多。需要说明的是ReactAgent 并不是万能的。它依赖大模型的工具调用能力如果模型本身不擅长遵循指令Agent 可能会在工具调用上反复横跳浪费 token 且降低响应速度。所以我们在实际应用中并没有把所有问答都交给 Agent而是把常见的事实型问题做成了一条快速检索通道只有当系统判定问题复杂或第一次检索结果不够充分时才切换到 ReactAgent 做多步推理。这种“简单走快路、复杂走 Agent”的组合线上稳定性会好很多。2.2 Qdrant 为什么适合企业级场景Qdrant 是专门为向量检索设计的数据库核心数据结构是 Collection一个 Collection 里可以维护一批向量及对应的 payload 元数据。它有四个特点非常适合企业级 RAG一是支持 HNSW 索引高并发下检索延迟能控制在毫秒级二是支持丰富的 payload 过滤条件可以在向量检索之前先按元数据进行过滤实现部门隔离、文档类型过滤、时间范围过滤等三是内置了向量存储的持久化和备份机制不需要自己额外维护数据同步四是 REST/gRPC 接口非常规范Spring AI 里有对应的 VectorStore 实现可以直接对接。在实际部署中我们最开始只是用 Docker 起了单实例把 collection 和索引参数调试好之后才用它的分布式模式做数据分片和副本。Qdrant 的查询流程可以简单地理解为先匹配向量相似度再结合 payload 条件做过滤最后返回 top-K 结果。它支持多种距离计算方式常见的包括余弦相似度、点积和欧氏距离在企业文本检索场景里通常选择 Cosine。2.3 ReactAgent、向量库和应用服务的协作关系如果画一张逻辑图整个系统的角色可以分为三层。最上层是 API 网关和业务应用层负责接收用户提问、调用 Agent、记录日志和返回结果中间层是 Spring AI Alibaba 提供的 Agent 编排层ReactAgent 在这里负责解析意图、调度工具、维护多轮状态最底层是知识接入层由 Qdrant 和嵌入模型组成承担数据切片、向量化、存储和检索工作。用户发起一个问题时通常情况下 ReactAgent 会先做一次工具调用即把用户的问题转换为检索关键词传给 Qdrant 进行相似度检索。Qdrant 返回若干条候选片段后Agent 会把片段连同系统提示词一起交给大模型让模型基于上下文生成答案。整个过程对用户是感知不到中间步骤的但如果设置了可观测链路就能看到模型的推理日志、工具调用参数、候选片段分数等调起问题来非常方便。这套协作方式既保持了业务代码的简洁又把检索和生成之间的衔接逻辑放到了 Agent 层后续要调整系统行为只需要修正工具描述和提示词不需要改动业务接口。3. 全链路设计与核心模块拆解从一份原始文档到用户看到一条答案中间要经历数据接入、文档解析、清洗、切片、向量化、存储、召回、重排、上下文组装和生成回答这几个环节。前四个环节往往被低估但恰好是决定系统上限的部分。下面我把每一个模块拆开来说清楚当时是怎么设计的以及为什么这样设计。3.1 数据接入与文档解析企业里的文档格式千奇百怪我们面对的主要是 PDF、Word、Markdown 和 HTML 四种。PDF 里还分电子版和扫描件电子版可以直接抽取文本扫描件必须先走 OCR 识别。当时接入的第一批资料里产品手册大多是电子版 PDF历史工单则导出成了 Word还有一部分线上文档是 HTML。我们做了一个统一的数据接入管道每一种文件类型对应一个解析器解析完都转成统一的文本结构附带来源文件标识和页号信息方便后期溯源。这里有个值得注意的细节PDF 的原始文本提取顺序不能完全相信排版。有些手册是双栏布局直接抽取会出现左右两栏文字交错的情况导致切出来的片段语义混乱。我们后来加入了一步结构还原按页面块解析尽量保留标题层级。对于 Word 文档重点处理表格和列表因为表格一旦被拍平成纯文本行列关系就没了回答里涉及参数对照时模型根本读不懂。所以我建议任何团队做 RAG宁可多花一点时间在解析器和清洗规则上也不要一上来就批量向量化。3.2 切片与清洗策略文本切片是整个 RAG 链路里最微妙的一环。切片太大单条上下文容易塞进多个主题召回的命中率和精准度都会下降还会浪费模型上下文窗口切片太小又可能截断关键的背景信息导致模型看到的是孤立句子无法理解上下文。我们最终采用的是“标题结构优先、固定大小兜底”的混合策略优先按照文档的章节标题切分保持自然语义边界如果某个章节太长再按固定长度二次切分同时设置切片重叠避免把连续的知识从中间拦腰截断。在清洗环节我们做了一些看起来不起眼但很有效的事情。比如去掉页眉页脚、目录页码、重复的版权声明把全角符号统一转成半角把连续的换行压缩成单换行对表格内容按行重建把表头重复拼接到每行避免模型在检索到表格片段时看不懂列含义。清洗规则不能做得太激进否则会丢失原文语义比如不要把标点符号全部删除后期的向量模型还依赖标点切分句子。这块踩过不少坑在后面常见问题里我会专门提。3.3 向量化与索引策略向量化是 RAG 里最关键也是最依赖外部模型能力的环节。我们最终选用的是一个开源的中文文本向量模型维度是 1024 维在相似句子匹配和长文档语义理解上表现稳定。向量化之后每个文档片段会包含三部分信息文本原文、向量值、payload 元数据。payload 里记录了文档编号、标题、页号、所属部门、标签、更新时间等字段。索引策略上我们在 Qdrant 里建了两个 collection一个是正式业务库一个用来做夜间批量重建。为什么用两个因为文档更新时如果直接在正式 collection 上更新会遇到索引写入与线上检索的锁竞争影响查询延迟。夜间同步的模式虽然牺牲了一点实时性但换来了系统稳定性。Qdrant 的 HNSW 参数我们调整过一轮m 值从默认 16 增大到 24召回率有提升内存消耗也相应增加ef_construct 设为 100建索引速度稍微慢了一些但在可控范围。召回参数方面top_k 设置为 20后面再通过重排压缩到 5 个上下文片段效果比直接取 top 5 好得多。3.4 检索增强与重排第一轮向量检索返回的 20 个候选片段里真正相关的可能只有三四个。如果直接把前 5 个全部塞给模型无关内容会产生干扰甚至把答案带偏。我们在这里加了一个重排环节用专门的排序模型对候选重新打分。重排模型和向量模型是两回事向量模型负责在百万级文档里快速粗筛重排模型负责对粗筛后的几十个结果做精排。这种“粗召回 精重排”的模式在企业级 RAG 里基本是标配了。重排之后的上下文管控同样重要。大模型上下文窗口有限我们不能把所有召回片段都塞进去。我们设了一个相关性阈值低于 0.35 的片段直接丢弃保留的片段按分数降序排列再根据窗口大小尽量多地塞入。另外特别长的片段会被截断到单条最大 800 字确保多条片段之间不会互相挤占 token。这里有一个技巧上下文里的每条片段都要带上文档标题和来源并显式标注为“知识片段”模型在生成时就会更容易去引用这些来源而不是凭空发挥。4. 实战落地关键步骤与核心代码到这一步系统骨架已经清晰了。接下来是真正动手实现的环节我会按照从环境准备到接口交付的顺序把关键步骤、配置和代码片段贴出来。这些代码是我在模拟项目 X 中实际用过的精简版本大家可以按需修改。4.1 环境准备与依赖配置基础环境包含一个可用的 Spring Boot 3.x 工程、Qdrant 服务、大模型 API 的接入凭证。我们通过 Docker 运行 Qdrant官方镜像可以直接拉起一个单节点监听 6333 端口和 6334 端口前者是 HTTP 接口后者是 gRPC 接口。Spring AI Alibaba 依赖需要根据版本选择合适的 Spring Boot 版本我这里给出一个可运行的依赖组合。dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter-vector-store-qdrant/artifactId version1.0.0/version /dependency dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter-agent-react/artifactId version1.0.0/version /dependency dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter-model/artifactId version1.0.0/version /dependency这里说明一下依赖版本随着社区迭代会变建议以实际仓库发布版本为准。不要把三个依赖看成“必须同时引入”如果只需要检索可以只引入 qdrant 和 model 的 starterAgent 需要的时候再加。依赖引多了会增加自动装配的复杂度容易触发不必要的组件初始化。4.2 application.yml 配置配置是 Spring AI Alibaba 里最容易出错的部分。除了大模型 API 的 key 以外还需要配置 embedding 模型、Qdrant 服务地址、collection 名称和检索参数。我们把这些配置全部放在配置中心方便不同环境测试、预发、生产切换。spring: ai: alibaba: embedding: enabled: true model: bge-m3 chat: model: qwen-plus api-key: ${LLM_API_KEY} base-url: ${LLM_BASE_URL} qdrant: host: 127.0.0.1 port: 6333 collection-name: enterprise_kb search: top-k: 20 score-threshold: 0.25 limit: 20这里有几个关键点。top-k 是召回候选数score-threshold 是召回的最低相似度阈值两者需要配合。阈值设得太高容易漏召回设得太低则会把大量无关片段送进重排环节。我们一开始按默认配置跑的时候返回质量非常不稳定后来对着测试集调了一轮才确定 0.25 作为初筛阈值比较合理。需要注意的是不同向量模型的分数分布差异很大换模型之后这组参数必须重新校准。4.3 Qdrant Collection 初始化Qdrant 的 collection 不是启动时自动创建的需要提前初始化。我们写了一个启动监听器在服务初始化时就检查 collection 是否存在不存在则创建并指定向量维度、距离算法和 HNSW 配置。维度必须和 embedding 模型输出的维度一致我们用的模型是 1024 维所以维度也写 1024。Service public class QdrantCollectionInitializer { private final QdrantVectorStore vectorStore; public QdrantCollectionInitializer(QdrantVectorStore vectorStore) { this.vectorStore vectorStore; } PostConstruct public void init() { QdrantVectorStore.QdrantVectorStoreConfig.Coordinate... } }由于不同版本的 API 略有差异我这里就不贴完整代码了重点说一下配置原则。HNSW 参数里 m 控制节点最大连接数m 越大召回越好但内存越高ef_construct 控制建索引时的搜索广度越大索引质量越高但建库越慢。我们线上用的是 m24、ef_construct100、距离选择 Cosine。如果文档量不超过几十万默认参数也够用优先保证稳定。4.4 接入大模型与向量模型Spring AI Alibaba 的自动装配已经帮我们把大模型客户端的创建做了封装。业务代码里只需要注入 ChatModel 和 EmbeddingModel 两个接口不需要自己管理 HTTP 客户端和连接池。下面是一个简单的注入示例Service public class KnowledgeVectorizer { private final EmbeddingModel embeddingModel; private final VectorStore vectorStore; public KnowledgeVectorizer(EmbeddingModel embeddingModel, VectorStore vectorStore) { this.embeddingModel embeddingModel; this.vectorStore vectorStore; } public void addDocument(String docId, String title, String content, MapString, Object payload) { TextSegment segment TextSegment.builder() .text(content) .metadata(docId, docId) .metadata(title, title) .build(); ListEmbedding embeddings embeddingModel.embed(List.of(segment)); // 将 embedding 和 payload 写入 Qdrant vectorStore.add(List.of( new VectorStoreEntry(embeddings.get(0).getVector(), payload) )); } }这里的重点是元数据设计。上面的 payload 里除了 docId、title我在真实项目里还加入了部门编码、文档类型、更新时间、可见范围这些字段后面会用于权限过滤。如果一开始只放文本内容等做到多部门隔离时再补就会非常痛苦因为历史向量数据都要重新刷一遍。4.5 实现 ReactAgent 问答接口ReactAgent 的实现是整个系统的核心编排层。我们需要把一个“知识库检索”方法封装成 Agent 可以调用的工具然后让 Agent 根据用户问题来决定调用方式。下面是一个简化版的接口代码Service public class RagAgentService { private final ChatModel chatModel; public RagAgentService(ChatModel chatModel) { this.chatModel chatModel; } public String answer(String userQuestion) { String systemPrompt 你是一个企业知识库问答助手。请严格基于检索到的知识片段回答用户问题。 知识片段以【片段】标记开始其中包含标题和正文。 若没有检索到相关信息请直接回答“未在知识库中找到相关内容”。 回答时必须说明依据的文档标题。 ; return chatModel.call(systemPrompt \n用户问题 userQuestion); } }真实项目里这层会加上对 Qdrant 的检索调用并且嵌入多轮对话历史。这里我故意没写太复杂是想强调一个设计原则ReactAgent 不是必须的。如果系统只是做“单轮单次检索回答”一个普通 ChatModel 加检索查询就够了。只有当你发现用户问题可能需要拆成多个子查询、且子查询之间有依赖关系时ReactAgent 的“思考-行动-观察”循环才有明显优势。在引入 ReactAgent 之后要多写一个工具注册方法给检索函数包上一层描述。描述写得越清楚模型越知道什么时候调用它。比如描述可以写“当用户询问任何与内部产品使用、故障排查、流程规范相关的问题时调用此工具检索企业知识库。参数请提炼成简洁的中文关键词短语不要过长”。这个描述看起来不起眼但直接影响 Agent 的工具调用准确率。我们曾因为描述写得太笼统出现过模型在回答简单问题时也去调工具、白白增加延迟的情况。4.6 企业级增强权限过滤与可观测对于企业级系统光能回答问题远远不够。权限隔离是我们的硬需求不同部门只能检索本部门可见的文档。这件事在 Qdrant 里可以通过 payload 过滤实现具体做法是在检索请求中带上当前用户可见范围的过滤条件Qdrant 会先过滤 payload 再计算向量相似度。地图上就是在调用 VectorStore 时传入一个 Filter 对象把部门编码等条件放进去。可观测性方面我们给每次问答生成一个 requestId把用户输入、召回候选及分数、重排结果、最终上下文、模型输出、耗时和 token 消耗全部记录到日志系统里。这样做最大的收益是人工评测当用户反馈答案不好时我们可以通过日志快速定位是检索没召回到正确内容还是模型没有正确依据上下文回答还是权限过滤把正确文档挡掉了。如果没有这个追踪链路调优基本上就是盲人摸象。public class QdrantSearchService { public ListRetrievedSegment search(String userQuery, String userDeptCode) { // 先过滤权限再检索向量 Filter filter new Filter( new Condition(deptCode, MatchValue.of(userDeptCode)) ); SearchRequest request SearchRequest.builder() .query(userQuery) .withPayload(true) .withVector(true) .filter(filter) .limit(20) .build(); return vectorStore.search(request); } }5. 常见问题与性能调优实录从开发到上线我们踩过的坑五花八门但归纳起来就几类。我挑了一些有代表性的放在这里给大家一个速查。很多问题不遇到的时候觉得不会发生等真发生了往往要浪费好几天。这里我把解决思路也一并写上。5.1 问题速查表问题现象根因分析解决思路检索结果与问题毫无关联embedding 模型与领域文本不适配或未做清洗换用更适合中文领域语义的模型优化清洗规则增加重排答案总是引用错误文档切片太大一条片段里混入多个主题按标题结构切片控制单条片段长度增加正文主题拆分回答内容流畅但完全不属于知识库内容上下文构建时没有控制好阈值提高召回阈值过滤低分片段并加强系统提示词约束权限过滤后检索结果为空Filter 字段类型或值不匹配大小写不一致检查 payload 字段类型统一部门编码大小写Agent 在工具调用里死循环模型工具调用能力弱或描述不清精简工具描述限制最大循环次数增加调用失败后的回退策略并发较高时响应变慢Qdrant connection pool 配置过低调大连接池、开启缓存、对热点查询加 Redis 缓存还有一个小概率但很讨厌的问题PDF 中原生文本顺序错乱。我们排查了半天发现是文档中有多栏排版导致抽取顺序交叉。后来通过页面块抽取和按阅读顺序重组修复了。遇到这类问题一定要在解析环节做充分验证不要让脏数据进入向量库否则后面很难溯源处理。5.2 参数调优心得说到参数调优我想重点聊一下 top-k、score-threshold 和上下文长度三个参数的关系。它们不是独立存在的而是互相制衡的。top-k 决定了候选池的大小score-threshold 决定候选池里哪些片段能进入上下文而上下文长度则决定了最终能塞多少片段。很多人只调 top-k忽视了 threshold导致候选返回 20 条但模型上下文只能放 5 条剩下 15 条全被无差别截断质量自然不稳定。我们的经验是先固定上下文窗口比如模型支持 8K给系统提示词和对话历史留出 3K留给知识片段的只有 5K。以单条片段 500 字左右估算最终放进去的片段在 8 到 10 条之间。因此重排后的 top-N 设置为 10 就足够了。然后可以尝试调整 threshold观察测试集上的“漏召回”和“误召回”数量找到一个平衡点。我最开始把 threshold 设到 0.5结果相当一部分正确答案被过滤掉了后来降到 0.25 才恢复正常。对于 HNSW 参数建议先不要过度追求极限。企业级 RAG 的文档量级通常在几十万片段以内默认的 HNSW 配置已经够快真正影响体验的是检索召回质量和上下文构建这块。内存足够再加 m 值否则优先保证系统的稳定性。我见过一些团队在几十万条数据上把 m 调到 64内存直线上升但查询延迟并没有明显改善这就是典型的参数过度调优。5.3 几个值得坚持的工程习惯除了参数我更想分享几个工程上的习惯它们对长期维护的帮助远大于某一两个算法。第一个习惯是建立评测集。上线前要准备至少五十条覆盖典型场景的问答对每次修改检索策略或提示词之后都跑一遍回归测试看正答率是否下降。没有评测集所有的优化都是拍脑袋你甚至不知道某个改动是在提升还是在倒退。第二个习惯是缓存热点问题。企业内部的问答其实有明显的二八效应很多员工问的问题是重复的。我们在问答接口外面加了一层 Redis 缓存对完全相同的用户问题和权限范围在一定时间窗口内直接返回缓存答案大幅度降低了模型调用成本和响应延迟。第三个习惯是保留原始文档版本。当文档解析或切片规则更新后不要直接覆盖旧向量数据而是采用新版本文档重新生成片段并做标记。这样如果新规则有问题还可以快速回滚到旧数据恢复线上问答质量。6. 写在最后这个项目给我留下最深的一点体会复盘这套企业级 RAG 问答系统的实现我最大的感触是Agent 和向量数据库都只是工具真正决定系统效果的是数据工程。如果文档解析乱、切片不合理、检索召回质量差那再强的 Agent 和再大的模型也救不回来。反过来只要把知识库的结构化处理做扎实哪怕用很朴素的检索增强生成链路也能取得不错的效果。如果你也在做类似的项目我建议不要一上来就堆各种高级特性。先把一条最基础的链路跑通文档解析、切片、向量化、检索、组装上下文、生成回答。跑通之后再用真实问题去测试找到最薄弱的环节去优化。ReactAgent 这种带工具调用的 Agent 编排更适合在基础链路稳定之后再引入否则只会增加排查问题的复杂度。最后再分享一个小技巧一定要让每次问答都在日志里留下完整的检索证据链。这样当用户说“答得不对”的时候你能清楚地判断是哪一环出了问题。很多企业级 RAG 项目不是死于技术选型而是死于无法排查。能定位问题就已经解决了一半。希望这篇实现记录能给正在做同类系统的朋友一些参考少走几个我走过的弯路。
1. 背景企业知识问答为什么最终选了 RAG 方案先交代一下项目场景。我所在的团队负责的是某企业内部知识管理平台的升级里面沉淀了产品手册、故障排查文档、历史工单、API 说明和流程规范累计几百份文档且以每个月几十篇的速度持续新增。最初大家靠传统关键字搜索找资料但文档一多精确匹配就非常痛苦——尤其是那种“我用一段自然语言描述故障现象希望能直接拿到排查步骤和结论”的场景传统搜索基本无能为力。所以领导层提了一个原始但很刚的需求让员工像聊天一样问问题系统从现有文档里找答案并且答案要能对应到原始出处。当时我们锁定的技术方向就是企业级 RAG 问答系统也就是检索增强生成。这套方案并不新鲜核心思路是先对知识库文档做解析、切片、向量化存入向量数据库用户提问后先从向量库召回相关片段再把召回内容作为上下文交给大模型生成回答。换句话说答案不是模型凭空编造的而是先找到依据再组织语言。这样一来模型的通用语义理解能力得到了保留企业内部专有的、随时更新的知识也能被覆盖而不是每隔几个月就去重新微调一次模型。这篇文章适合两类人看一类是在 Java 技术栈里准备落地 RAG 系统想看看真实工程怎么组织的另一类是已经接触过 Spring AI Alibaba但不确定 ReactAgent 到底该放在哪一环Qdrant 怎么配合才不踩坑。我会尽量把这个项目里的关键决策、代码片段、参数调优和踩坑记录都写清楚相当于给这套实现做一次完整的复盘。1.1 项目要解决的核心问题这个项目表面上是在做一个“企业知识库问答”实际上要解决三个层次的问题。第一层是知识的碎片化。文档散落在多个仓库、目录甚至个人电脑里PDF、Word、Markdown 混在一起格式不统一。员工想找一份半年前的故障处理记录可能得问三个人才能定位到文件。第二层是检索精度的问题。传统的关键字搜索对同义词、口语化提问、隐含语义完全不敏感比如文档里写的是“内存溢出”用户问的是“服务莫名其妙崩了”这两者在字面上没有交集但在语义上是强相关的。第三层是答案的可信度问题。直接用大模型做问答会很流畅但员工并不敢直接相信模型的输出因为没有人知道它依据的是哪份文档如果答错了还会误导处理流程甚至酿成事故。所以系统在设计之初就定了几条硬性指标回答必须基于知识库内容不能自由发挥答案必须附带引用来源知识库更新后系统能在小时级内感知到变化而不是等重新训练同时还要支持按部门和权限范围过滤不同角色只能检索到与自己相关的文档。这几条指标基本把方案推向了 RAG而不是微调。1.2 RAG 与微调的选择为什么不是单独微调模型在真正动手之前团队内部进行过一次 RAG 和微调的对比讨论。当时有同事提出过一个疑问既然企业内部知识是相对固定的为什么不直接用领域数据微调大模型让模型本身学会这些知识这样线上问答就不需要去查向量库了响应还会更快。这个思路在某些场景下没问题但在我们这个项目里存在几个硬伤。首先是更新成本知识库每周都有新增内容如果每次新增都要触发一次微调训练资源消耗先不说流程周期就很难接受。其次是数据量和分布的问题几百份文档对于微调来说仍然太少很容易导致模型过拟合或记住噪音反而降低泛化能力。然后是溯源问题微调后的模型是一个黑盒它隐约知道某个知识点但不可能告诉你这段话出自哪份文档的哪一页这对于需要追责的企业场景是致命的。而 RAG 天然把“知识存储”和“生成能力”解耦知识更新只需要重新切片、重新向量化回答时还能把检索到的原文一起交给模型由模型引用段落编号溯源链路非常清晰。当然 RAG 也不是没有代价。它会引入检索失败的风险如果召回环节没找到正确片段再强的模型也回答不了。所以在实施阶段我们花了很大精力在文档解析、切片策略、向量检索和重排上而不是只关注最后的 Agent 对话效果。下面我会从技术选型开始把整条链路完整展开。2. 技术选型为什么是 Spring AI Alibaba ReactAgent Qdrant项目组是标准的 Java 技术栈这一点直接决定了框架选择的范围。早期我们考虑过 LangChain 系列它在 Python 社区生态丰富但在 Java 端的维护质量和社区活跃度参差不齐引入之后团队还得专门养一个 Python 服务来完成 Agent 编排等于增加了一个跨语言维护节点。后来又看到 Spring AI 逐渐成熟而 Spring AI Alibaba 作为适配国内模型生态的扩展包已经实现了包括 ChatModel、EmbeddingModel、VectorStore、Agent 在内的一系列抽象并且兼容 Spring Boot 的自动装配习惯对 Java 团队非常友好。Qdrant 的选择相对曲折。当时对比过几款向量数据库最终从部署复杂度、过滤能力、性能稳定性和社区活跃度几个维度打分Qdrant 胜出。它用 Rust 实现单机性能很好支持 payload 元数据过滤这对我们后续做多租户和权限隔离非常关键。而且它的 Docker 镜像启动非常轻量企业内部测试环境一台 4C8G 的机器就能跑起来压力测试后再上高可用集群迭代路径很平滑。2.1 Spring AI Alibaba 在项目里的真实定位Spring AI Alibaba 不是一个独立的大模型平台它更像是一座连接 Java 业务系统和模型能力的桥梁。它把不同模型厂商的差异封装成了统一的接口比如 ChatModel 对应大语言模型EmbeddingModel 对应向量化模型VectorStore 对应向量数据库操作。业务代码写完之后如果想从模型 A 切换到模型 B只需要改配置和依赖不需要改核心逻辑。这一点在企业内部非常重要因为模型厂商的商务策略和技术指标变化很快我们不能把系统绑死在一家厂商上。ReactAgent 是 Spring AI Alibaba 里基于 ReAct 模式实现的一种 Agent 实现。ReAct 是 Reasoning and Acting 的缩写核心思路是让模型在推理过程中交替进行“思考”“行动”“观察”。在复杂的问答场景里用户的一次问题可能需要多次检索才能回答完整比如“先查一下某模块的报错原因再根据报错信息找到对应的处理方案”。ReactAgent 能把“检索知识库”封装成工具函数模型会根据用户问题自己决定要不要调用这个工具、传入什么查询词、观察返回结果后继续推理最终生成有依据的回答。这种编排方式比单纯的“检索一次就生成答案”要灵活得多。需要说明的是ReactAgent 并不是万能的。它依赖大模型的工具调用能力如果模型本身不擅长遵循指令Agent 可能会在工具调用上反复横跳浪费 token 且降低响应速度。所以我们在实际应用中并没有把所有问答都交给 Agent而是把常见的事实型问题做成了一条快速检索通道只有当系统判定问题复杂或第一次检索结果不够充分时才切换到 ReactAgent 做多步推理。这种“简单走快路、复杂走 Agent”的组合线上稳定性会好很多。2.2 Qdrant 为什么适合企业级场景Qdrant 是专门为向量检索设计的数据库核心数据结构是 Collection一个 Collection 里可以维护一批向量及对应的 payload 元数据。它有四个特点非常适合企业级 RAG一是支持 HNSW 索引高并发下检索延迟能控制在毫秒级二是支持丰富的 payload 过滤条件可以在向量检索之前先按元数据进行过滤实现部门隔离、文档类型过滤、时间范围过滤等三是内置了向量存储的持久化和备份机制不需要自己额外维护数据同步四是 REST/gRPC 接口非常规范Spring AI 里有对应的 VectorStore 实现可以直接对接。在实际部署中我们最开始只是用 Docker 起了单实例把 collection 和索引参数调试好之后才用它的分布式模式做数据分片和副本。Qdrant 的查询流程可以简单地理解为先匹配向量相似度再结合 payload 条件做过滤最后返回 top-K 结果。它支持多种距离计算方式常见的包括余弦相似度、点积和欧氏距离在企业文本检索场景里通常选择 Cosine。2.3 ReactAgent、向量库和应用服务的协作关系如果画一张逻辑图整个系统的角色可以分为三层。最上层是 API 网关和业务应用层负责接收用户提问、调用 Agent、记录日志和返回结果中间层是 Spring AI Alibaba 提供的 Agent 编排层ReactAgent 在这里负责解析意图、调度工具、维护多轮状态最底层是知识接入层由 Qdrant 和嵌入模型组成承担数据切片、向量化、存储和检索工作。用户发起一个问题时通常情况下 ReactAgent 会先做一次工具调用即把用户的问题转换为检索关键词传给 Qdrant 进行相似度检索。Qdrant 返回若干条候选片段后Agent 会把片段连同系统提示词一起交给大模型让模型基于上下文生成答案。整个过程对用户是感知不到中间步骤的但如果设置了可观测链路就能看到模型的推理日志、工具调用参数、候选片段分数等调起问题来非常方便。这套协作方式既保持了业务代码的简洁又把检索和生成之间的衔接逻辑放到了 Agent 层后续要调整系统行为只需要修正工具描述和提示词不需要改动业务接口。3. 全链路设计与核心模块拆解从一份原始文档到用户看到一条答案中间要经历数据接入、文档解析、清洗、切片、向量化、存储、召回、重排、上下文组装和生成回答这几个环节。前四个环节往往被低估但恰好是决定系统上限的部分。下面我把每一个模块拆开来说清楚当时是怎么设计的以及为什么这样设计。3.1 数据接入与文档解析企业里的文档格式千奇百怪我们面对的主要是 PDF、Word、Markdown 和 HTML 四种。PDF 里还分电子版和扫描件电子版可以直接抽取文本扫描件必须先走 OCR 识别。当时接入的第一批资料里产品手册大多是电子版 PDF历史工单则导出成了 Word还有一部分线上文档是 HTML。我们做了一个统一的数据接入管道每一种文件类型对应一个解析器解析完都转成统一的文本结构附带来源文件标识和页号信息方便后期溯源。这里有个值得注意的细节PDF 的原始文本提取顺序不能完全相信排版。有些手册是双栏布局直接抽取会出现左右两栏文字交错的情况导致切出来的片段语义混乱。我们后来加入了一步结构还原按页面块解析尽量保留标题层级。对于 Word 文档重点处理表格和列表因为表格一旦被拍平成纯文本行列关系就没了回答里涉及参数对照时模型根本读不懂。所以我建议任何团队做 RAG宁可多花一点时间在解析器和清洗规则上也不要一上来就批量向量化。3.2 切片与清洗策略文本切片是整个 RAG 链路里最微妙的一环。切片太大单条上下文容易塞进多个主题召回的命中率和精准度都会下降还会浪费模型上下文窗口切片太小又可能截断关键的背景信息导致模型看到的是孤立句子无法理解上下文。我们最终采用的是“标题结构优先、固定大小兜底”的混合策略优先按照文档的章节标题切分保持自然语义边界如果某个章节太长再按固定长度二次切分同时设置切片重叠避免把连续的知识从中间拦腰截断。在清洗环节我们做了一些看起来不起眼但很有效的事情。比如去掉页眉页脚、目录页码、重复的版权声明把全角符号统一转成半角把连续的换行压缩成单换行对表格内容按行重建把表头重复拼接到每行避免模型在检索到表格片段时看不懂列含义。清洗规则不能做得太激进否则会丢失原文语义比如不要把标点符号全部删除后期的向量模型还依赖标点切分句子。这块踩过不少坑在后面常见问题里我会专门提。3.3 向量化与索引策略向量化是 RAG 里最关键也是最依赖外部模型能力的环节。我们最终选用的是一个开源的中文文本向量模型维度是 1024 维在相似句子匹配和长文档语义理解上表现稳定。向量化之后每个文档片段会包含三部分信息文本原文、向量值、payload 元数据。payload 里记录了文档编号、标题、页号、所属部门、标签、更新时间等字段。索引策略上我们在 Qdrant 里建了两个 collection一个是正式业务库一个用来做夜间批量重建。为什么用两个因为文档更新时如果直接在正式 collection 上更新会遇到索引写入与线上检索的锁竞争影响查询延迟。夜间同步的模式虽然牺牲了一点实时性但换来了系统稳定性。Qdrant 的 HNSW 参数我们调整过一轮m 值从默认 16 增大到 24召回率有提升内存消耗也相应增加ef_construct 设为 100建索引速度稍微慢了一些但在可控范围。召回参数方面top_k 设置为 20后面再通过重排压缩到 5 个上下文片段效果比直接取 top 5 好得多。3.4 检索增强与重排第一轮向量检索返回的 20 个候选片段里真正相关的可能只有三四个。如果直接把前 5 个全部塞给模型无关内容会产生干扰甚至把答案带偏。我们在这里加了一个重排环节用专门的排序模型对候选重新打分。重排模型和向量模型是两回事向量模型负责在百万级文档里快速粗筛重排模型负责对粗筛后的几十个结果做精排。这种“粗召回 精重排”的模式在企业级 RAG 里基本是标配了。重排之后的上下文管控同样重要。大模型上下文窗口有限我们不能把所有召回片段都塞进去。我们设了一个相关性阈值低于 0.35 的片段直接丢弃保留的片段按分数降序排列再根据窗口大小尽量多地塞入。另外特别长的片段会被截断到单条最大 800 字确保多条片段之间不会互相挤占 token。这里有一个技巧上下文里的每条片段都要带上文档标题和来源并显式标注为“知识片段”模型在生成时就会更容易去引用这些来源而不是凭空发挥。4. 实战落地关键步骤与核心代码到这一步系统骨架已经清晰了。接下来是真正动手实现的环节我会按照从环境准备到接口交付的顺序把关键步骤、配置和代码片段贴出来。这些代码是我在模拟项目 X 中实际用过的精简版本大家可以按需修改。4.1 环境准备与依赖配置基础环境包含一个可用的 Spring Boot 3.x 工程、Qdrant 服务、大模型 API 的接入凭证。我们通过 Docker 运行 Qdrant官方镜像可以直接拉起一个单节点监听 6333 端口和 6334 端口前者是 HTTP 接口后者是 gRPC 接口。Spring AI Alibaba 依赖需要根据版本选择合适的 Spring Boot 版本我这里给出一个可运行的依赖组合。dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter-vector-store-qdrant/artifactId version1.0.0/version /dependency dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter-agent-react/artifactId version1.0.0/version /dependency dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter-model/artifactId version1.0.0/version /dependency这里说明一下依赖版本随着社区迭代会变建议以实际仓库发布版本为准。不要把三个依赖看成“必须同时引入”如果只需要检索可以只引入 qdrant 和 model 的 starterAgent 需要的时候再加。依赖引多了会增加自动装配的复杂度容易触发不必要的组件初始化。4.2 application.yml 配置配置是 Spring AI Alibaba 里最容易出错的部分。除了大模型 API 的 key 以外还需要配置 embedding 模型、Qdrant 服务地址、collection 名称和检索参数。我们把这些配置全部放在配置中心方便不同环境测试、预发、生产切换。spring: ai: alibaba: embedding: enabled: true model: bge-m3 chat: model: qwen-plus api-key: ${LLM_API_KEY} base-url: ${LLM_BASE_URL} qdrant: host: 127.0.0.1 port: 6333 collection-name: enterprise_kb search: top-k: 20 score-threshold: 0.25 limit: 20这里有几个关键点。top-k 是召回候选数score-threshold 是召回的最低相似度阈值两者需要配合。阈值设得太高容易漏召回设得太低则会把大量无关片段送进重排环节。我们一开始按默认配置跑的时候返回质量非常不稳定后来对着测试集调了一轮才确定 0.25 作为初筛阈值比较合理。需要注意的是不同向量模型的分数分布差异很大换模型之后这组参数必须重新校准。4.3 Qdrant Collection 初始化Qdrant 的 collection 不是启动时自动创建的需要提前初始化。我们写了一个启动监听器在服务初始化时就检查 collection 是否存在不存在则创建并指定向量维度、距离算法和 HNSW 配置。维度必须和 embedding 模型输出的维度一致我们用的模型是 1024 维所以维度也写 1024。Service public class QdrantCollectionInitializer { private final QdrantVectorStore vectorStore; public QdrantCollectionInitializer(QdrantVectorStore vectorStore) { this.vectorStore vectorStore; } PostConstruct public void init() { QdrantVectorStore.QdrantVectorStoreConfig.Coordinate... } }由于不同版本的 API 略有差异我这里就不贴完整代码了重点说一下配置原则。HNSW 参数里 m 控制节点最大连接数m 越大召回越好但内存越高ef_construct 控制建索引时的搜索广度越大索引质量越高但建库越慢。我们线上用的是 m24、ef_construct100、距离选择 Cosine。如果文档量不超过几十万默认参数也够用优先保证稳定。4.4 接入大模型与向量模型Spring AI Alibaba 的自动装配已经帮我们把大模型客户端的创建做了封装。业务代码里只需要注入 ChatModel 和 EmbeddingModel 两个接口不需要自己管理 HTTP 客户端和连接池。下面是一个简单的注入示例Service public class KnowledgeVectorizer { private final EmbeddingModel embeddingModel; private final VectorStore vectorStore; public KnowledgeVectorizer(EmbeddingModel embeddingModel, VectorStore vectorStore) { this.embeddingModel embeddingModel; this.vectorStore vectorStore; } public void addDocument(String docId, String title, String content, MapString, Object payload) { TextSegment segment TextSegment.builder() .text(content) .metadata(docId, docId) .metadata(title, title) .build(); ListEmbedding embeddings embeddingModel.embed(List.of(segment)); // 将 embedding 和 payload 写入 Qdrant vectorStore.add(List.of( new VectorStoreEntry(embeddings.get(0).getVector(), payload) )); } }这里的重点是元数据设计。上面的 payload 里除了 docId、title我在真实项目里还加入了部门编码、文档类型、更新时间、可见范围这些字段后面会用于权限过滤。如果一开始只放文本内容等做到多部门隔离时再补就会非常痛苦因为历史向量数据都要重新刷一遍。4.5 实现 ReactAgent 问答接口ReactAgent 的实现是整个系统的核心编排层。我们需要把一个“知识库检索”方法封装成 Agent 可以调用的工具然后让 Agent 根据用户问题来决定调用方式。下面是一个简化版的接口代码Service public class RagAgentService { private final ChatModel chatModel; public RagAgentService(ChatModel chatModel) { this.chatModel chatModel; } public String answer(String userQuestion) { String systemPrompt 你是一个企业知识库问答助手。请严格基于检索到的知识片段回答用户问题。 知识片段以【片段】标记开始其中包含标题和正文。 若没有检索到相关信息请直接回答“未在知识库中找到相关内容”。 回答时必须说明依据的文档标题。 ; return chatModel.call(systemPrompt \n用户问题 userQuestion); } }真实项目里这层会加上对 Qdrant 的检索调用并且嵌入多轮对话历史。这里我故意没写太复杂是想强调一个设计原则ReactAgent 不是必须的。如果系统只是做“单轮单次检索回答”一个普通 ChatModel 加检索查询就够了。只有当你发现用户问题可能需要拆成多个子查询、且子查询之间有依赖关系时ReactAgent 的“思考-行动-观察”循环才有明显优势。在引入 ReactAgent 之后要多写一个工具注册方法给检索函数包上一层描述。描述写得越清楚模型越知道什么时候调用它。比如描述可以写“当用户询问任何与内部产品使用、故障排查、流程规范相关的问题时调用此工具检索企业知识库。参数请提炼成简洁的中文关键词短语不要过长”。这个描述看起来不起眼但直接影响 Agent 的工具调用准确率。我们曾因为描述写得太笼统出现过模型在回答简单问题时也去调工具、白白增加延迟的情况。4.6 企业级增强权限过滤与可观测对于企业级系统光能回答问题远远不够。权限隔离是我们的硬需求不同部门只能检索本部门可见的文档。这件事在 Qdrant 里可以通过 payload 过滤实现具体做法是在检索请求中带上当前用户可见范围的过滤条件Qdrant 会先过滤 payload 再计算向量相似度。地图上就是在调用 VectorStore 时传入一个 Filter 对象把部门编码等条件放进去。可观测性方面我们给每次问答生成一个 requestId把用户输入、召回候选及分数、重排结果、最终上下文、模型输出、耗时和 token 消耗全部记录到日志系统里。这样做最大的收益是人工评测当用户反馈答案不好时我们可以通过日志快速定位是检索没召回到正确内容还是模型没有正确依据上下文回答还是权限过滤把正确文档挡掉了。如果没有这个追踪链路调优基本上就是盲人摸象。public class QdrantSearchService { public ListRetrievedSegment search(String userQuery, String userDeptCode) { // 先过滤权限再检索向量 Filter filter new Filter( new Condition(deptCode, MatchValue.of(userDeptCode)) ); SearchRequest request SearchRequest.builder() .query(userQuery) .withPayload(true) .withVector(true) .filter(filter) .limit(20) .build(); return vectorStore.search(request); } }5. 常见问题与性能调优实录从开发到上线我们踩过的坑五花八门但归纳起来就几类。我挑了一些有代表性的放在这里给大家一个速查。很多问题不遇到的时候觉得不会发生等真发生了往往要浪费好几天。这里我把解决思路也一并写上。5.1 问题速查表问题现象根因分析解决思路检索结果与问题毫无关联embedding 模型与领域文本不适配或未做清洗换用更适合中文领域语义的模型优化清洗规则增加重排答案总是引用错误文档切片太大一条片段里混入多个主题按标题结构切片控制单条片段长度增加正文主题拆分回答内容流畅但完全不属于知识库内容上下文构建时没有控制好阈值提高召回阈值过滤低分片段并加强系统提示词约束权限过滤后检索结果为空Filter 字段类型或值不匹配大小写不一致检查 payload 字段类型统一部门编码大小写Agent 在工具调用里死循环模型工具调用能力弱或描述不清精简工具描述限制最大循环次数增加调用失败后的回退策略并发较高时响应变慢Qdrant connection pool 配置过低调大连接池、开启缓存、对热点查询加 Redis 缓存还有一个小概率但很讨厌的问题PDF 中原生文本顺序错乱。我们排查了半天发现是文档中有多栏排版导致抽取顺序交叉。后来通过页面块抽取和按阅读顺序重组修复了。遇到这类问题一定要在解析环节做充分验证不要让脏数据进入向量库否则后面很难溯源处理。5.2 参数调优心得说到参数调优我想重点聊一下 top-k、score-threshold 和上下文长度三个参数的关系。它们不是独立存在的而是互相制衡的。top-k 决定了候选池的大小score-threshold 决定候选池里哪些片段能进入上下文而上下文长度则决定了最终能塞多少片段。很多人只调 top-k忽视了 threshold导致候选返回 20 条但模型上下文只能放 5 条剩下 15 条全被无差别截断质量自然不稳定。我们的经验是先固定上下文窗口比如模型支持 8K给系统提示词和对话历史留出 3K留给知识片段的只有 5K。以单条片段 500 字左右估算最终放进去的片段在 8 到 10 条之间。因此重排后的 top-N 设置为 10 就足够了。然后可以尝试调整 threshold观察测试集上的“漏召回”和“误召回”数量找到一个平衡点。我最开始把 threshold 设到 0.5结果相当一部分正确答案被过滤掉了后来降到 0.25 才恢复正常。对于 HNSW 参数建议先不要过度追求极限。企业级 RAG 的文档量级通常在几十万片段以内默认的 HNSW 配置已经够快真正影响体验的是检索召回质量和上下文构建这块。内存足够再加 m 值否则优先保证系统的稳定性。我见过一些团队在几十万条数据上把 m 调到 64内存直线上升但查询延迟并没有明显改善这就是典型的参数过度调优。5.3 几个值得坚持的工程习惯除了参数我更想分享几个工程上的习惯它们对长期维护的帮助远大于某一两个算法。第一个习惯是建立评测集。上线前要准备至少五十条覆盖典型场景的问答对每次修改检索策略或提示词之后都跑一遍回归测试看正答率是否下降。没有评测集所有的优化都是拍脑袋你甚至不知道某个改动是在提升还是在倒退。第二个习惯是缓存热点问题。企业内部的问答其实有明显的二八效应很多员工问的问题是重复的。我们在问答接口外面加了一层 Redis 缓存对完全相同的用户问题和权限范围在一定时间窗口内直接返回缓存答案大幅度降低了模型调用成本和响应延迟。第三个习惯是保留原始文档版本。当文档解析或切片规则更新后不要直接覆盖旧向量数据而是采用新版本文档重新生成片段并做标记。这样如果新规则有问题还可以快速回滚到旧数据恢复线上问答质量。6. 写在最后这个项目给我留下最深的一点体会复盘这套企业级 RAG 问答系统的实现我最大的感触是Agent 和向量数据库都只是工具真正决定系统效果的是数据工程。如果文档解析乱、切片不合理、检索召回质量差那再强的 Agent 和再大的模型也救不回来。反过来只要把知识库的结构化处理做扎实哪怕用很朴素的检索增强生成链路也能取得不错的效果。如果你也在做类似的项目我建议不要一上来就堆各种高级特性。先把一条最基础的链路跑通文档解析、切片、向量化、检索、组装上下文、生成回答。跑通之后再用真实问题去测试找到最薄弱的环节去优化。ReactAgent 这种带工具调用的 Agent 编排更适合在基础链路稳定之后再引入否则只会增加排查问题的复杂度。最后再分享一个小技巧一定要让每次问答都在日志里留下完整的检索证据链。这样当用户说“答得不对”的时候你能清楚地判断是哪一环出了问题。很多企业级 RAG 项目不是死于技术选型而是死于无法排查。能定位问题就已经解决了一半。希望这篇实现记录能给正在做同类系统的朋友一些参考少走几个我走过的弯路。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
