Spring AI + Java实战：企业级RAG知识库问答全链路构建与调优

很多 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 List<Document> splitForRag(String content, String source) { List<Document> 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) { Map<String, 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 对象里的 Map：

Map<String, 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> <groupId>org.springframework.ai</groupId> <artifactId>spring-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, Map<String, Object> metadata) { List<Document> 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 里，一段检索代码是这样的：

List<Document> 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(); List<Document> 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 对流式支持很成熟：

Flux<String> stream = chatClient.prompt() .messages(messages) .stream() .content();

后端往 WebFlux 的 SSE 通道推，前端逐字展示。这里有个经验：流式输出的第一个字到得越快，用户对系统的信任感越强。

引文是另一个容易被忽略但极其重要的点。企业问答系统不像聊天机器人可以随便聊，回答里的每个关键结论都得能追溯到来源。最简单的实现是：把检索命中的 Document 的 source 元数据收集起来，在回答末尾附上“参考文档”列表。更严谨的做法是要求模型在回答中插入引用标记，比如“根据 [文档A] 中的描述……”。这个可以写进 Prompt 模板里，让模型引用来源。

5.3 如何防幻觉

RAG 最大的优势就是减少幻觉，但减少不等于消除。模型依然可能“发挥”。除了用 Prompt 约束，还要在工程上兜底。

我的做法是三重防线。第一，检索结果为空或相似度低于阈值时不进入生成阶段，直接返回“未找到相关资料”。第二，生成 Prompt 里明确禁止编造，并且要求“上下文缺失时必须承认缺失”。第三，对回答做来源验证——把模型引用的来源和实际检索结果做比对，对不上就标记为不可信。

temperature 参数也要注意。知识库问答场景我一般设 0.2 以下，让模型输出更保守。temperature 调太高，同一个问题两次回答的文字差异会很大，用户会觉得系统不稳定。

6. 进阶：多轮对话、自动路由与Agentic RAG

6.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 团队一个简单的对照：

两者不是竞争关系，而是分工关系。企业级 Agent 项目里，通常既有 RAG 组件负责知识供给，也有 MCP 组件负责行动落地。

7. 常见问题排查与效果调优速查表

7.1 常见问题速查表

跑完一遍 RAG 全链路，你大概率会遇到下面这些问题。我把典型的症状、原因和处理建议整理成了一张表：

这些坑我基本都踩过一遍。尤其是维度不一致那个，很容易在切换模型时触发，你以为只是配置改一下，实际要重建整个索引，数据量大的时候非常痛苦。

7.2 效果调优心得

如果只能记住一个原则，我建议你先接受这句话：RAG 的改进是链条式的，要整体看效果，不能只盯单个环节。

我的调优顺序是这样的。第一步，先把链路跑通，用最简单的固定切块和内存向量库，做出一个能回答的版本。第二步，准备 10 到 20 个高频真实问题作为测试集，记录下来每个问题的回答质量。第三步，逐一调切块参数、TopK、阈值、Prompt，每调一次就跑一遍测试集对比。第四步，优化元数据过滤和检索策略，重点看答非所问类问题是否减少。

这中间最容易被低估的是切块。我见过不少团队在向量模型和 Prompt 上花了很多精力，最后发现问题其实是切块把关键信息切碎了。早点准备测试集，能帮你快速锁定问题出在哪一层，而不是凭感觉盲调。

最后分享一个我自己惯用的小技巧：把容易翻车的 10 个问题固化成自动化测试，接入 CI。每次调整切块策略或 Prompt 之后，自动跑一遍测试集，用分数判断是否回退。这样迭代起来心态会稳很多，因为你改的每一个参数，都有数据告诉你值不值。RAG 是一个没有银弹的领域，但把链路和数据握在手里，Java 程序员完全可以把这件事做到生产级别。