很多 Java 后端同学的第一反应是知识库已经建好了文档也都传上去了那 RAG 是不是就该自动跑起来了结果一接 Spring AI 才发现事情没那么简单。RAG 不是“把文档塞进去”就完事而是一条完整的链路切块、向量化、存储、检索、生成每一环都影响最终回答质量。今天我就把这套链路拆开讲清楚从原理到代码从踩过的坑到调优经验全都摊在桌面上。这篇文章不是概念科普更不是面试八股而是面向有 Spring Boot 基础、想在企业内部把“知识库问答”真正落地的 Java 程序员。你会看到完整的工程实现思路、可以直接复制改的代码以及很多文档里不会告诉你的经验判断。准备好了就往下走。1. Spring AI RAG到底在解决什么事1.1 知识库不等于RAG应用很多项目里“知识库”就是一堆 Word、PDF、Markdown 躺在文件服务器上或者存在数据库的表里。模型不知道这些私有内容也不可能把这些内容全部塞进提示词去问。RAG 的核心思路是把知识库变成可检索的向量索引在回答用户问题之前先从索引里召回和问题最相关的片段再把这些片段作为上下文交给大模型让它“根据材料回答”。我用一个类比来说明知识库是仓库RAG 是配货员加组装工。用户提一个问题配货员先去仓库里找到最对口的几块材料组装工再按照这些材料拼出一段回答。如果配货员找错了材料或者材料切得残缺不全组装工再厉害也答不准。这个类比基本上概括了 RAG 的全部核心——前半段决定“有没有材料”后半段决定“材料怎么被用”。明白了这个流程你就知道“知识库已经有了”只是起点。你还得做切块、向量化、检索、组装这几件事才能让知识库变成一个可用的问答系统。Spring AI 的价值在于它把这些环节抽象成了统一的 Java API你不需要自己去拼 HTTP 调用也不需要去学 Python 那套生态用 Spring Boot 的套路就能搭完一整条 RAG 管道。1.2 为什么Java程序员要亲手做RAG有人会问市面上已经有那么多现成的 RAG API 或服务平台直接调不就行了在原型阶段可以但到了企业落地阶段问题就来了文档怎么切、检索要不要按部门过滤、答案能不能追溯来源、返回结果怎么和现有权限体系打通这些全是定制需求通用 API 给不了。而 Java 后端团队做 RAG 有一个天然优势权限、事务、缓存、消息队列、定时任务这些基础设施我们都熟。RAG 落地到企业里最难的技术点往往不是“怎么调大模型”而是“怎么把知识库的访问控制和检索流程结合起来”。打个比方同样一篇技术文档研发部的同事能查外包同学只能查部分章节。检索阶段就要带权限过滤这个能力在业务系统里早就有了接上 RAG 只是多写一个过滤条件的事。另外Spring AI 已经把大模型和向量库的交互抽象成了一致性的接口。不管底层接的是哪家模型服务商还是私有化部署的 Ollama在 Java 代码里看到的都是 ChatClient、EmbeddingModel、VectorStore 这一套对象。你的业务代码不用跟着模型厂商换。这就是 Java 程序员做 RAG 最舒服的地方底层怎么变我们这层接口不动。2. 动手前最该想明白的事切块与元数据设计2.1 切块质量直接决定回答质量我见过太多人一上来就写代码写完发现回答效果很差然后怀疑模型不行怀疑向量库不行。排查到最后问题往往出在最朴素的环节——切块。为什么切块这么关键因为 Embedding 模型是对“一小段文本”计算语义向量的。如果你把一整个文档切得太长比如上万字的操作手册直接变成一个向量那么这段文字的语义会被平均掉检索时什么都像什么都不像。反过来切得太碎一段话只剩下半句话上下文丢了向量也失去了语义锚点。举一个常见的例子。某 API 文档里有这么一句“创建订单接口如果调用超时请调用订单状态查询接口确认订单是否创建成功。”如果模型把这句话切碎了把“创建订单接口”和“订单状态查询接口”分到了两个 chunk 里那么用户问“怎么确认订单有没有创建成功”时检索系统可能只召回“创建订单接口”那一段答案自然不完整。切块的目的就是在“语义完整”和“定位精准”之间找平衡。2.2 三种常用切块策略与选择思路实际项目里我一般按优先级推荐三种策略。第一种是固定大小切块。按字符数或 Token 数硬切比如每 600 个字符一块块与块之间重叠 100 个字符。实现最简单适合内容格式高度统一的帮助中心文档。缺点是遇到表格、代码块这些特殊结构时容易拦腰截断。第二种是递归切块。优先按自然边界切比如先按段落切段落太长再按句子切句子还太长就按固定大小兜底。这么做的好处是尽量不让文本在语义中途断裂。大部分通用文档选这个策略都不会错。第三种是结构化切块。如果文档本身有明确结构比如 Markdown 的标题层级、HTML 的章节、PDF 的书签就按标题把文档分成若干节每一节自带父级标题作为上下文。这种方案最适合 API 文档、技术教程、制度文件这类“章节感”很强的材料。下面这段代码是我在项目里常用的“段落优先 容量兜底 重叠”切分示例你可以直接拿去改public ListDocument splitForRag(String content, String source) { ListDocument docs new ArrayList(); String[] paragraphs content.split(\\n{2,}); int chunkSize 600; int overlap 100; StringBuilder buffer new StringBuilder(); for (String para : paragraphs) { if (buffer.length() para.length() chunkSize buffer.length() 0) { docs.add(buildDocument(buffer.toString(), source)); buffer.setLength(0); if (overlap 0 !docs.isEmpty()) { String lastText docs.get(docs.size() - 1).getText(); int start Math.max(0, lastText.length() - overlap); buffer.append(lastText, start, lastText.length()); } } buffer.append(para).append(\n); } if (buffer.length() 0) { docs.add(buildDocument(buffer.toString(), source)); } return docs; } private Document buildDocument(String text, String source) { MapString, Object metadata new HashMap(); metadata.put(source, source); return new Document(text, metadata); }关于切块参数chunkSize 我建议先落在 500 到 800 之间overlap 在 80 到 150 之间。具体数值要看你的知识库语言和文档风格。中文内容一个字算一个字符600 字符大约是 600 个汉字这个长度对大多数 Embedding 模型都比较友好。overlap 的作用是防止关键信息恰好落在两块之间的缝隙里宁可多存一点重复内容也不能把信息切断。2.3 元数据检索的水下工程元数据是挂在每个 chunk 上的标签检索时可以用它做过滤。最常见的元数据包括来源文档名、所属部门、更新时间、文档版本、权限级别等。为什么说它是水下工程因为从表面看没有元数据系统也能跑通 RAG但一上生产就露馅。比如你有一个内部技术文档库和一个销售资料库如果不加部门过滤用户问一句“我们产品的报价策略”检索系统可能把内部技术方案也捞了出来。加上部门过滤之后检索只会在销售资料这个子集里找既安全又精准。在 Spring AI 里元数据就是 Document 对象里的 MapMapString, Object metadata new HashMap(); metadata.put(source, sales/2025-price.md); metadata.put(department, sales); metadata.put(version, v2.1); Document doc new Document(报价策略说明……, metadata);入库时把元数据一起写进向量库检索时通过 FilterExpressionBuilder 把它变成过滤条件。这个能力建议在一开始就设计好后面补的话要重建索引成本很高。3. Embedding与向量库选型3.1 Embedding模型怎么选Java 程序员不用关心 Embedding 模型怎么训练但要会选。核心看四件事接口稳定性、中文支持、向量维度、上下文长度限制。接入方式上最省事的是用模型服务商提供的 OpenAI 兼容接口。Spring AI 的 OpenAI starter 可以直接通过 base-url 指向任意兼容 OpenAI 协议的服务商不用改代码。配置长这样spring: ai: openai: base-url: ${AI_BASE_URL} api-key: ${AI_API_KEY} chat: options: model: chat-model-name embedding: options: model: embedding-model-name如果你的服务商不兼容 OpenAI 协议Spring AI 也提供了各家厂商的官方 starter常见的大模型服务商基本都有对应的 spring-ai-starter-model-xxx。社区还有基于 Spring AI 的增强实现比如 Spring AI Alibaba对国内云厂商做了不少适配。我的建议是先在本地用 Ollama 跑通流程再切到正式模型服务这样调试成本最低。选 Embedding 模型的时候还有一点容易被忽视入库和查询必须用同一个模型。如果你入库时用 A 模型查询时换了 B 模型向量空间都不一样检索结果必然稀烂。这个坑我后面会再提。3.2 向量库从内存到生产Spring AI 抽象了 VectorStore 接口底层实现可以随时切换。原型阶段我建议直接用内存版的 SimpleVectorStore零依赖启动就能跑。它适合验证你的切块策略和检索逻辑但不适合生产因为数据在重启后就没了吗没错内存存储重启即失。生产环境的选择我按团队现状给你一个判断路径。如果团队已经有 Elasticsearch优先考虑 ES 的向量检索能力不用再引一个新的存储组件运维成本最低。如果团队 Redis 用得很熟Spring AI 提供了 RedisVectorStore 的 starter接起来很快适合中低并发场景。如果数据量到了千万级或者检索 QPS 很高再考虑 Milvus 这类专业向量数据库。在 Spring AI 里接入 Redis 向量库依赖只要加一个dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-vector-store-redis/artifactId version${spring-ai.version}/version /dependency然后在配置文件里指定 Redis 地址和索引名称Spring AI 会自动帮你建索引。需要注意的是Redis 版本要支持向量检索相关的模块否则启动建索引那一步就会报错。3.3 入库Pipeline代码把文档切块、加元数据、向量化、写入向量库这一整套动作应该做成一个独立的入库服务。千万别说“在用户问答时实时切块入库”那会拖垮接口响应。一个最简单的入库 Service 长这样Service public class KnowledgeIngestService { private final VectorStore vectorStore; private final TextSplitter textSplitter; public KnowledgeIngestService(VectorStore vectorStore, TextSplitter textSplitter) { this.vectorStore vectorStore; this.textSplitter textSplitter; } public void ingest(String content, String source, MapString, Object metadata) { ListDocument chunks textSplitter.apply(content); chunks.forEach(doc - doc.getMetadata().putAll(metadata)); vectorStore.write(chunks); } }生产环境建议把入库放到 MQ 消费者或者定时任务里异步执行。文档多的时候几千个 chunk 的向量化调用是比较耗时的同步处理会把线程占死还容易导致接口超时。4. 检索阶段同样的代码效果差在细节里4.1 相似度TopK与相似度分数检索时我们关心两个参数TopK 和相似度阈值。TopK 是返回多少个候选块相似度阈值是低于多少分的块直接丢弃。TopK 太小容易漏掉关键信息TopK 太大噪声多模型容易被无关上下文带偏。我通常从 5 开始调。如果切块规模在 600 字符左右TopK 取 3 到 5 比较合适。相似度阈值我一般先设 0.7然后根据测试结果上下调整。阈值设得太高比如 0.85很多正确答案会因为表达方式不同被过滤掉设得太低比如 0.5无关内容就会混进来。在 Spring AI 里一段检索代码是这样的ListDocument docs vectorStore.similaritySearch( SearchRequest.builder() .query(question) .topK(5) .similarityThreshold(0.7) .build() );这里有一点要提醒不同向量库返回的相似度分数含义略有差异有的是余弦相似度有的换算成了距离。所以阈值不能直接照搬别人的经验要在你自己的数据上跑一遍看看分数分布再定。4.2 metadata过滤检索不是全库乱找企业级 RAG 最容易被忽略的就是“检索范围”。整个知识库全量做相似度搜索看起来没毛病但业务上往往有明确边界。Spring AI 的 SearchRequest 支持过滤器配合 FilterExpressionBuilder 使用FilterExpressionBuilder builder new FilterExpressionBuilder(); FilterExpression filter builder.eq(department, sales).build(); ListDocument docs vectorStore.similaritySearch( SearchRequest.builder() .query(question) .topK(5) .similarityThreshold(0.7) .filterExpression(filter) .build() );这种过滤第一个价值是权限第二个价值是精度。限制检索范围之后相似度计算不再被无关领域的文档干扰召回质量会明显提升。4.3 混合检索与重排向量检索擅长语义相似比如用户问“订单超时怎么办”它能找到和“超时处理”语义相近的内容。但它不擅长精确匹配。比如用户问“E1001 报错码是什么意思”如果文档里明确写了“E1001 表示库存不足”向量检索可能会因为语义泛化而把这条结果埋没。这时候就需要关键词检索兜底。混合检索的思路是两条腿走路向量检索跑一遍关键词检索比如 ES 的 match 查询、BM25跑一遍然后把两部分结果合并去重。合并之后如果还想再精准一点就加一层 Rerank。Rerank 模型会拿用户问题和候选文档逐条算相关性分数把真正对口的排到前面。在 Spring AI 里你可以自己编排这个流程先 VectorStore 召回 Top 20再用 Rerank API 或者一个专门的 LLM 调用重排只取前 5。重排会多花一些时间和成本但在回答质量要求比较高的场景这个投入很值。5. 生成阶段让模型“只会用上下文说话”5.1 Prompt模板设计检索做得再好如果 Prompt 没约束住模型答案照样会跑偏。RAG 的 System Prompt 必须明确告诉模型三件事第一只能使用上下文里的信息回答第二上下文里没有就直说不知道第三回答时可以引用来源。我常用的模板结构是这样的String systemPrompt 你是一名企业知识库问答助手。 请只根据用户提供的上下文回答问题。 如果上下文中没有相关信息请直接回答“我找不到相关资料”不要编造。 如果上下文中存在相互矛盾的信息请说明冲突内容。 ; String userTemplate 上下文 {context} 问题 {question} ;用 Spring AI 的 PromptTemplate 组织请求PromptTemplate promptTemplate new PromptTemplate(userTemplate, Map.of(context, context, question, question)); Message userMessage promptTemplate.createMessage(); Message systemMessage new SystemMessage(systemPrompt); String answer chatClient.prompt() .messages(List.of(systemMessage, userMessage)) .call() .content();这样写的好处是上下文和问题分开传入模型能清晰地区分“参考资料”和“待回答问题”不容易把上下文里的陈述当成交谈内容。5.2 流式输出与引文企业内部知识问答用户的耐心和搜索引擎时代一样超过两三秒没反应就想刷新。所以生产环境尽量做流式输出。Spring AI 的 ChatClient 对流式支持很成熟FluxString stream chatClient.prompt() .messages(messages) .stream() .content();后端往 WebFlux 的 SSE 通道推前端逐字展示。这里有个经验流式输出的第一个字到得越快用户对系统的信任感越强。引文是另一个容易被忽略但极其重要的点。企业问答系统不像聊天机器人可以随便聊回答里的每个关键结论都得能追溯到来源。最简单的实现是把检索命中的 Document 的 source 元数据收集起来在回答末尾附上“参考文档”列表。更严谨的做法是要求模型在回答中插入引用标记比如“根据 [文档A] 中的描述……”。这个可以写进 Prompt 模板里让模型引用来源。5.3 如何防幻觉RAG 最大的优势就是减少幻觉但减少不等于消除。模型依然可能“发挥”。除了用 Prompt 约束还要在工程上兜底。我的做法是三重防线。第一检索结果为空或相似度低于阈值时不进入生成阶段直接返回“未找到相关资料”。第二生成 Prompt 里明确禁止编造并且要求“上下文缺失时必须承认缺失”。第三对回答做来源验证——把模型引用的来源和实际检索结果做比对对不上就标记为不可信。temperature 参数也要注意。知识库问答场景我一般设 0.2 以下让模型输出更保守。temperature 调太高同一个问题两次回答的文字差异会很大用户会觉得系统不稳定。6. 进阶多轮对话、自动路由与Agentic RAG6.1 RAG多轮对话设计单轮问答跑通之后下一个需求通常是多轮对话。但 RAG 的多轮有个“指代消解”问题。用户第一轮问“怎么配置数据源”第二轮问“那如果连接超时呢”这里的“那”指代的是上一轮的数据源配置场景。如果直接拿“如果连接超时呢”去做向量检索召回可能完全跑偏。两种主流方案供你选。第一种是查询改写。每次检索前先用 LLM 把“对话历史 当前问题”改写成一个独立的、完整的查询语句。这个方案实现简单效果直接也是我优先推荐的方式。比如把“那如果连接超时呢”改写成“数据源连接超时时应该如何处理”。改写后的查询再去做向量检索召回质量会好很多。第二种是把历史问答也写进向量库作为额外的检索候选。这个方案适合“用户经常追问同类问题”的场景但实现复杂且历史数据会随对话增长而膨胀生产环境维护成本高。查询改写的 Prompt 模板参考如下你是一个问题改写助手。 请结合对话历史和当前问题生成一个独立、完整、可直接检索的查询语句。 要求保留实体名、产品名、报错码不要补充知识库中没有的信息直接输出改写结果不要解释。6.2 自动路由到底要不要查RAG不是每个问题都值得走一遍知识库检索。用户说“你好”你没必要去向量库里捞一遍用户问“今天天气怎么样”知识库里也没有。如果不做区分闲聊问题会浪费检索资源还可能因为检索到奇怪的内容而答非所问。自动路由的做法是在问答入口先让 LLM 做一次轻量分类判断问题属于“闲聊问候”“知识库问答”“需要工具处理”还是“无法回答”。分类结果决定后续走哪个 Handler。分类的 Prompt 可以很简单请判断用户问题的类型只输出一个类别 - greeting问候、感谢、寒暄 - knowledge需要查询企业知识库才能回答 - tool需要执行某个系统操作 - other其他 用户问题{question}路由之后greeting 直接走预设问候语knowledge 走 RAG 全链路tool 走 Agent 工具调用流程。这一步做完整个问答系统的行为会显得“有脑子”而不是对每句话都套一遍知识库。6.3 Agentic RAG 与 MCP 的边界最近总有人问我 RAG 和 MCP 是什么关系是有你没有我的替代关系吗还真不是。RAG 解决的是“模型不知道的知识”问题路径是检索私域文档然后生成回答。MCP 解决的是“模型做不了的动作”问题它是一套标准化协议让模型能调用外部工具和系统。一个负责“知道”一个负责“做到”。Agentic RAG 就是把两者融合的形态Agent 接到任务后判断要查哪些知识库多次检索、对比不同来源的信息然后规划行动步骤再通过工具调用去完成实际操作。比如“帮我查一下新员工的入职流程并提交一条请假申请”前半句走 RAG 检索入职文档后半句走 MCP 调用 OA 系统接口。给 Java 团队一个简单的对照维度RAGMCP定位私域知识检索增强生成模型调用外部工具/系统的协议核心解决模型不知道的知识模型做不了的动作Java侧落地VectorStore ChatClientAgent MCP Client / Server典型场景文档问答、客服、合规咨询查订单、发消息、调内部系统两者不是竞争关系而是分工关系。企业级 Agent 项目里通常既有 RAG 组件负责知识供给也有 MCP 组件负责行动落地。7. 常见问题排查与效果调优速查表7.1 常见问题速查表跑完一遍 RAG 全链路你大概率会遇到下面这些问题。我把典型的症状、原因和处理建议整理成了一张表问题现象大概率原因处理建议检索结果答非所问切块太大/太小、TopK 不合理、Embedding 模型选错先调切块参数再调 TopK最后换 Embedding 模型文档里有答案但回答“不知道”检索没召回或相似度阈值太高调大 TopK降低阈值检查 metadata 过滤条件回答内容与文档不一致模型自由发挥Prompt 约束不够收紧 System Prompt强制引用降低 temperature向量库报维度不一致错误入库和查询用了不同的 Embedding 模型固定模型统一配置重建索引响应速度很慢同步检索、串行调用、生成过长换流式输出检索和生成并行做缓存Redis 启动报索引相关错误Redis 版本不支持向量检索模块升级 Redis 或换用 ES/Milvus这些坑我基本都踩过一遍。尤其是维度不一致那个很容易在切换模型时触发你以为只是配置改一下实际要重建整个索引数据量大的时候非常痛苦。7.2 效果调优心得如果只能记住一个原则我建议你先接受这句话RAG 的改进是链条式的要整体看效果不能只盯单个环节。我的调优顺序是这样的。第一步先把链路跑通用最简单的固定切块和内存向量库做出一个能回答的版本。第二步准备 10 到 20 个高频真实问题作为测试集记录下来每个问题的回答质量。第三步逐一调切块参数、TopK、阈值、Prompt每调一次就跑一遍测试集对比。第四步优化元数据过滤和检索策略重点看答非所问类问题是否减少。这中间最容易被低估的是切块。我见过不少团队在向量模型和 Prompt 上花了很多精力最后发现问题其实是切块把关键信息切碎了。早点准备测试集能帮你快速锁定问题出在哪一层而不是凭感觉盲调。最后分享一个我自己惯用的小技巧把容易翻车的 10 个问题固化成自动化测试接入 CI。每次调整切块策略或 Prompt 之后自动跑一遍测试集用分数判断是否回退。这样迭代起来心态会稳很多因为你改的每一个参数都有数据告诉你值不值。RAG 是一个没有银弹的领域但把链路和数据握在手里Java 程序员完全可以把这件事做到生产级别。