企业官网建设流程全解析

“RAG知识库问答机器人”，听起来像是要在本地搭一套检索增强生成系统，但真要动手，很多人卡在第一步：文档怎么切？向量怎么存？模型怎么和知识库对接？“我本地明明跑通了向量化，结果一问三不知”——这类问题我见过太多次。这次整理一份Spring AI实现RAG的完整入门方案，从关键概念、环境配置、代码分层到调优思路，全程带可抄作业的配置和代码，让小白也能一条路跑通。

1. 内容整体设计与思路拆解

1.1 为什么用RAG而不是直接微调模型

RAG（Retrieval-Augmented Generation，检索增强生成）的核心思路，是在模型回答问题之前，先从知识库中检索出相关的文本片段，把这些片段作为上下文一起交给大模型，让模型基于给定的资料内容生成答案。这样做的好处非常明显：

• 知识可控：知识库维护在本地，答案有据可依，不会像大模型凭空编造。
• 更新低成本：新增文档到知识库即可，不需要重新训练模型。
• 回答可溯源：可以返回引用了哪些片段，方便验证答案是否正确。

相比之下，Fine-tuning（微调）要准备大量标注数据、要算力资源，且每次知识更新都要重新训练，对大多数中小项目来说性价比偏低。

1.2 Spring AI在RAG链路中的定位

Spring AI是Spring生态下的AI应用开发框架，它把与大模型交互、向量化、检索这些操作统一封装成一套API。对于RAG知识库机器人，我们需要完成的核心工作分为四块：

1. 把本地文档（PDF、Markdown、TXT等）切分成小段，然后调用Embedding模型转换成向量。
2. 把向量存入向量数据库，如Chroma、PGVector、Milvus等。
3. 用户提问时，用同一个Embedding模型把问题向量化，在向量库中做相似度检索，找出最相关的片段。
4. 把原始问题加上检索到的上下文一起发给大模型，由大模型生成最终答案。

Spring AI为这些步骤提供了开箱即用的组件：DocumentReader处理文档解析，TokenTextSplitter负责文本切分，VectorStore接口屏蔽了不同向量库的差异，QuestionAnswerAdvisor实现检索增强的自动拼接。也就是说，我们用统一的API就能切换底层实现，不用在业务代码里写死某家厂商的SDK。

1.3 整体架构与目录划分

我建议把项目按功能拆成清晰的层级，方便后续维护：

• 配置层：管理模型地址、API Key、向量库路径等参数。
• 组件层：封装文档读取、文本切分、向量存储等通用组件。
• 服务层：提供知识库写入接口、问答接口。
• 接口层：对外暴露REST API，方便Web端、小程序端调用。

目录结构参考如下：

src/main/java/com/xxx/ragdemo/ ├── config/ │ ├── EmbeddingConfig.java │ ├── VectorStoreConfig.java │ └── ModelConfig.java ├── service/ │ ├── KnowledgeService.java │ └── ChatService.java ├── controller/ │ └── RagController.java └── RagDemoApplication.java

这样做的好处是，组件之间只管自己的事，后续替换Embedding模型、切换向量库，都只动配置层和组件层，业务接口不受影响。

2. 核心细节解析与实操要点

2.1 Embedding模型选型：决定检索质量的底层因素

Embedding模型的效果，直接决定检索结果准不准。选型时要关注三个指标：

• 维度大小：维度越高通常语义表达越丰富，但存储和计算成本也越高。
• 中文支持能力：如果知识库以中文为主，必须选中文效果好的模型，OpenAI的text-embedding-3-small对英文表现出色，中文也能用，但专项中文模型在行业术语上往往更准。
• 服务化部署方式：可以调用云端API，也可以本地部署开源模型。

我在项目里选择的是OpenAI的text-embedding-3-small，因为Spring AI对它的支持最完善，配置简单，兼容性好。如果你用的是国产模型，比如某平台的地平线嵌入模型，只要兼容OpenAI接口格式，在Spring AI里同样可以通过自定义EmbeddingModel接入。这里的关键点是选好一个模型后，向量化和检索必须用同一个模型，否则检索结果基本作废。

2.2 向量数据库选型：从开发环境到生产环境的平滑迁移

向量数据库负责存储和检索Embedding向量。Spring AI的VectorStore接口抽象了统一操作，实现了几个流行的向量库：

从我实操过的项目看，前期开发直接用Chroma的内嵌模式最省事，不需要单独部署容器，启动应用时自动建库。等到了正式上线，如果数据量不大、团队已经用了PostgreSQL，换到PGVector是迁移成本最小的路径。Spring AI统一抽象了这些实现，业务代码无需改动，只换配置和依赖。

2.3 文本切分参数：为什么切分长度直接影响回答效果

文本切分是RAG里最容易被忽视却最关键的一环。切得太短，每个片段语义不完整，检索到的上下文缺乏前后文逻辑；切得太长，向量表达的语义不聚焦，检索精度下降，而且超出模型上下文窗口的片段要截断。不管是调用OpenAI接口还是本地部署的开源模型，都要先了解这个模型支持的最大上下文长度。开源模型的上下文窗口差异很大，具体长度要去模型发布页确认。切分参数没有“万能值”，我的经验是先跑一轮测试看效果再调，不要盲目抄配置。

Spring AI提供的TokenTextSplitter允许设置：

• defaultChunkSize：每个片段的Token数上限。
• minChunkSize：片段最小Token数。
• overlap：前后片段重叠的Token数，保留上下文衔接。

这边给出一个中文知识库常用的起点配置：

spring.ai.vectorstore.chroma.client.similarity-top-k=5

同时在代码中用TokenTextSplitter构建切分器：

TokenTextSplitter splitter = new TokenTextSplitter.Builder() .withChunkSize(500) .withOverlap(80) .build();

withChunkSize(500)代表单段控制在约500个Token，中文场景大概对应600到800字，withOverlap(80)让相邻片段有约80个Token的重叠，保证被切断的句子在下一个片段里有延续。实际使用中，如果发现某类专业文档问题答不全，优先考虑放大overlap而不是盲目加大chunkSize。

2.4 提示词模板：约束模型引用上下文回答

RAG的提示词模板决定了模型怎么“使用”检索到的上下文。Spring AI的QuestionAnswerAdvisor内置了一套模板，我习惯自定义调整，强调“未知就直说不知道”和“引用给定上下文”，避免模型强行编造。一个效果不错的参考模板：

你是一名知识库助手。请仅根据以下“参考资料”回答用户问题，不要使用参考资料之外的知识。 参考资料： {context} 用户问题： {question} 要求： 1. 如果参考资料中没有答案，请明确回答“资料库中暂无相关信息”。 2. 回答尽量简洁明确，引用关键片段。 3. 不要编造资料中不存在的数据或结论。

通过模板约束，可以明显减少大模型“自由发挥”带来的答案漂移问题。

3. 实操过程与核心环节实现

3.1 环境准备与依赖配置

我用的是Spring Boot 3.x + Spring AI 1.0.0版本，注意Spring AI仍在快速迭代中，不同版本之间API差异不小，建议先锁定一个稳定版本再往下跟。Maven构建时，在pom.xml中引入关键依赖：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-chroma-store-spring-boot-starter</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-pdf-document-reader</artifactId> </dependency>

如果使用国产模型或私有化部署的模型，往往只需要调整spring.ai.openai.*指向本地地址就可以了，前提是这个服务暴露的是OpenAI兼容接口。举例来说，本地跑了一个兼容OpenAI协议的大模型服务，端口是11434，配置就可以改成spring.ai.openai.base-url=http://localhost:11434，这样既不用改代码，还能快速验证效果。

3.2 关键配置文件与启动参数

在application.yml中配置模型地址、API Key和Chroma的数据库路径：

spring: application: name: rag-demo ai: openai: api-key: ${OPENAI_API_KEY} base-url: ${OPENAI_BASE_URL:https://api.openai.com} chat: options: model: gpt-4o-mini temperature: 0.2 embedding: options: model: text-embedding-3-small vectorstore: chroma: client: host: localhost port: 8000 database-name: rag_demo

我这边在Linux服务器上经常用docker run -p 8000:8000 chromadb/chroma启动Chroma服务。内嵌模式虽然简单，但生产上不推荐，因为数据会跟随应用生命周期，容易丢数据。OPENAI_API_KEY尽量通过环境变量注入，避免硬编码到配置文件中泄露。

需要特别注意的是，Chat模型的temperature不要设置太高，RAG场景下我们希望模型严格依据上下文作答，一般0.1到0.3比较稳妥。设置太高模型容易发散，自己发挥“补充背景知识”，反而引入错误信息。

3.3 DocumentReader读取：处理不同格式的文档

Spring AI的Document家族支持读取多种格式。用PDF文档举例：

public List<Document> loadPdfDocuments(String filePath) { PdfDocumentReader reader = new PdfDocumentReader(filePath); return reader.get(); }

但要注意，PDF分页读取后默认每个Page是一个Document，metadata里带页码信息。如果知识库的文档是Markdown或纯文本，可以用TextDocumentReader，写法基本一致。从实际项目来看，扫描版PDF不能直接读取文字，这类文档需要先过一层OCR，否则索引进去的内容全是乱码，检索结果自然是一塌糊涂。章节类结构文档最好按章节切，Table或列表多的文档尽量保留原始排版格式，因为单纯按长度切分会把表格语义拆碎。

3.4 文本切分与向量化入库

文档加载完成后，用切分器处理，再写入向量库。这里实现了核心的KnowledgeService：

@Service public class KnowledgeService { private final VectorStore vectorStore; private final TokenTextSplitter splitter; public KnowledgeService(VectorStore vectorStore) { this.vectorStore = vectorStore; this.splitter = new TokenTextSplitter.Builder() .withChunkSize(500) .withOverlap(80) .build(); } public void importDocument(String filePath) { PdfDocumentReader reader = new PdfDocumentReader(filePath); List<Document> pages = reader.get(); List<Document> chunks = splitter.apply(pages); vectorStore.add(chunks); System.out.println("完成知识库写入，片段数量：" + chunks.size()); } }

splitter.apply()返回的是List<Document>，其中每个Document对应一个切分后的文本块，携带原文档的元数据。写入向量库时，Spring AI会自动调用配置好的Embedding模型，把每个Document的文本转换为向量一并存储。

实际操作时，经常会遇到重复写入的问题，同一份文档导入两次，查询时会出现两条相同的内容。解决思路有两种：一是导入前先做文档去重检查，二是利用向量库的ID机制，保证相同内容的文档使用同一个ID，重复导入时覆盖而不是新增。Spring AI的Document构造方法可以指定ID：

Document doc = new Document("unique-doc-id", "content", metadata); vectorStore.add(List.of(doc));

用业务上的文档唯一标识（比如文档编号或文件MD5）作为ID，能有效避免重复数据。

3.5 问答接口：检索增强的最终呈现

问答环节是整条链路的下游，也是用户直接感知效果的地方。实现的ChatService会做三件事：接收问题、从向量库检索相关上下文、带着上下文请求大模型生成回答。

@Service public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient.Builder chatClientBuilder) { this.chatClient = chatClientBuilder.build(); } public String ask(String question) { return chatClient.prompt() .advisors(a -> a.param("question", question)) .user(question) .call() .content(); } }

这里QuestionAnswerAdvisor会自动完成向量检索，并把检索片段拼接到提示词模板中，最终发给大模型。如果要调整检索的相似度阈值，可以在VectorStore的检索逻辑中配置：

SearchRequest searchRequest = SearchRequest.builder() .query(question) .topK(5) .similarityThreshold(0.6) .build();

topK控制返回多少个相关片段，similarityThreshold控制最低相似度，低于阈值的片段会被丢弃。阈值设太高容易查不到内容，设太低又可能带入无关信息。实际项目上我从0.5开始，结合知识库内容类型上下微调，效果比较稳。

最后，暴露一个简单的REST接口，供前端或其他服务调用:

@RestController @RequestMapping("/api/rag") public class RagController { private final ChatService chatService; private final KnowledgeService knowledgeService; public RagController(ChatService chatService, KnowledgeService knowledgeService) { this.chatService = chatService; this.knowledgeService = knowledgeService; } @GetMapping("/ask") public String ask(@RequestParam String question) { return chatService.ask(question); } @PostMapping("/import") public String importDocument(@RequestParam String path) { knowledgeService.importDocument(path); return "导入完成"; } }

启动应用后，访问http://localhost:8080/api/rag/ask?question=你的问题，输入问题即可拿到带知识库上下文生成的答案。实测我往库里放了约30篇产品文档，问“系统支持哪些登录方式”，回答准确引用了文档里的章节内容，甚至还能区分不同版本的差异，这比直接问大模型的效果好很多。

4. 常见问题与排查技巧实录

4.1 排查问题顺序：从输入到输出的链路检查

RAG报错，往往不是单点问题，而是一条链路任何一个环节都可能导致最终结果不对。我建议按这个顺序排查：

1. 文档有没有真正写进向量库：调用导入接口后，确认返回的片段数量符合预期。数量为0，说明切分器或读取器有问题。
2. 检索能不能查到相关片段：可以用一个简单的测试方法，把检索结果的片段内容直接打印出来，看它们是不是真的和问题相关。如果检索结果驴唇不对马嘴，后面大模型回答不可能准。
3. 大模型收到的上下文是什么：打开日志，打印实际发送给模型的Prompt，确认上下文中是否包含检索到的文档片段。如果Prompt里只有问题没有上下文，说明Advisor没生效。
4. 大模型返回是否合规：确认模型没有编造上下文之外的内容。

这条链路排查清楚，能覆盖90%的常见问题。

4.2 高频问题速查表

4.3 从实战中总结的避坑技巧

有一个坑是我在多个项目里反复踩过的：把PDF按页切块，而不做标题合并。导致后果是，同一个小节的内容被切割到不同页的多个片段里，检索时只召回其中一部分内容，回答就不完整。解决方式是在读取PDF后，先做一定的标题识别和合并，再把合并后的长文本交给切分器处理。Spring AI自带的ParagraphTextSplitter在这里能帮上忙，它尝试保留段落完整性，避免简单按Token硬切。

还有一点容易忽略：Document的metadata非常有用。比如PDF读取时自动带上了页码，问答时需要展示引用来源，完全可以把这个页码信息作为引用标注返回给前端。我在实际项目中就把metadata里的page和file_name提取出来，拼到回答后面，用户能看到“答案参考了xxx.pdf第12页”，整个知识库机器人可信度一下就上来了。

4.4 接入WebUI的小扩展

做成机器人之后，很多人不满足于REST接口，想要一个网页聊天界面。我一般直接甩给前端同学一个HTML页面，用JavaScript调用/api/rag/ask接口。有个轻量的集成方式，用Streaming Responsive渲染流式输出，让用户像ChatGPT那样看到逐字生成的效果。Spring AI的ChatClient支持流式调用：

public Flux<String> askStream(String question) { return chatClient.prompt() .advisors(a -> a.param("question", question)) .user(question) .stream() .content(); }

配合text/event-stream响应，前端就能展示打字机效果。这里注意，流式模式下QuestionAnswerAdvisor同样会先做检索再流入模型，链路逻辑不变，只是响应方式变了。

5. 进阶优化思路：让检索更精准

5.1 混合检索与Rerank

向量检索虽然语义理解能力强，但有时关键词匹配反而更精确。更好的方案是混合检索，把向量相似度与BM25等全文检索分数融合起来，再做一次Rerank，用Cross Encoder模型重新排序。Spring AI扩展了多种检索方式，生产级应用建议保留一层Rerank机制，比如直接用Spring AI的QueryTransformer或在应用侧自定义Advisor。这样做能显著提升长尾问题和专业术语场景的召回率。

5.2 多租户数据隔离

当知识库要为多个团队、多个客户服务时，一定要在元数据里打上租户标识，检索时加上过滤条件。Spring AI的向量查询允许自定义过滤表达式，Chroma等原生支持metadata过滤，这样就能避免不同租户之间的数据互相污染。

实际项目里，我常在Document元数据中加入tenantId字段，查询时在SearchRequest中绑定过滤条件：

SearchRequest.builder() .query(question) .topK(5) .filterExpression("tenantId == '" + tenantId + "'") .build();

这一步看似小事，不做的话线上迟早会出严重数据越权事故。

5.3 知识库自动更新机制

RAG的知识库不是一次性写完就完事。我常遇到的情况是，业务文档每周更新，系统需要定时重新解析指定目录。最简单的做法是写一个定时任务，每天凌晨清空旧向量、重新导入文档。如果文档量大，也可以增量更新，通过比对文件MD5判断是否有变更，只有变更的文件才重新入库。整体维护成本低，收益却很直接。

6. 工具选型解析

说到工具选型，我个人理解很简单，团队擅长什么、数据规模多大，就选对应的方案。这里分享一下我平时几个组合怎么选。

• 本地开发快速验证：OpenAI嵌入模型或国产API + Chroma内嵌模式 + Spring AI，这套组合10分钟就能跑通全链路。
• 已有PostgreSQL业务的团队：PGVector是最平滑的升级路径，库不用新引入，一张表解决问题。
• 生产级海量数据：Milvus或Qdrant，支持分布式、多副本、高并发，运维成本也高一些，适合有专门运维力量的团队。
• 数据安全要求高的私有化场景：本地部署开源Embedding模型，搭配任意本地向量库，大模型也用私有化部署，数据不出机房。

Spring AI的价值在于，这些差异化组合都统一收敛到VectorStore接口上，应用层代码不绑定特定数据库。前期选型不确定也没关系，先跑通一套，后面按需替换成本很低。

我自己现在做RAG项目的标准流程是，不管最终生产用什么，开发阶段永远先用Chroma + OpenAI兼容模型跑通链路，验证回答质量和业务逻辑，然后再上生产环境的技术栈。这样做的好处是，开发期不被基础设施拖累，把精力集中在最核心的两件事上：知识库内容质量好不好、切分与检索参数是否匹配业务。

另外有句话我想多说一遍：参数先照抄，效果看结果，再根据结果反推调整。不要拿着别人项目的chunkSize和topK当银弹，同一套参数在不同文档结构下的表现差异非常大。实测中，代码文档和经验文档的差异就很明显。知识库内容偏技术、结构规整时，chunkSize可以放大；偏问答、片段独立时，适合缩小。跑一遍测试集，看哪些问题回答不准，一个个对着调整，才最可靠。

Spring AI + RAG这套组合，本质上解决的是“让大模型说实话、说我们想要的话”的问题。把上面这些细节处理好了，知识库问答机器人才真正能落地到业务里，而不是停留在Demo阶段。