让AI读你的文档

Spring AI 1.0 的 Advisor 机制上一篇讲完了，这篇直接上 RAG。

RAG 不是一个新概念，但很多人对它的理解停留在"把文档丢给 AI"这一步。实际上 RAG 是一个完整的数据处理流水线：文档加载、切分、向量化、存储、检索、生成。每一步都有坑。

Spring AI 1.0 把这条流水线的每一步都封装成了标准接口，你只需要组合配置，不用自己从零拼。

这一篇从文档加载到最终回答，全流程跑通。

RAG 的全流程长什么样

先把整个流程理清楚：

文档加载：把 PDF、Word、Markdown 读进来
切分：把长文档切成小段，每段 200-500 字
向量化：把每段文字转成向量
存储：向量存到向量数据库
检索：用户提问时，找到最相关的几段
生成：把找到的内容拼到 prompt 里，让 AI 回答

每一步 Spring AI 都有对应的接口，往下看。

第一步：文档加载

Spring AI 提供了 DocumentReader 接口，内置了几种常见格式：

// PDF 文档 PagePdfDocumentReader pdfReader = new PagePdfDocumentReader("classpath:product-manual.pdf"); List<Document> pdfDocs = pdfReader.get(); // Markdown 文档 MarkdownDocumentReader mdReader = new MarkdownDocumentReader("classpath:faq.md"); List<Document> mdDocs = mdReader.get(); // 纯文本 TextReader textReader = new TextReader("classpath:knowledge-base.txt"); List<Document> textDocs = textReader.get();

每个 Document 包含三部分：内容文本、元数据（来源、页码等）、唯一的 ID。

加载完之后，你拿到了一堆 Document，但每个可能很长，不能直接用。

第二步：切分

切分是 RAG 里最容易被忽略、但对效果影响最大的一步。

切太大：检索精度差，一段里混了多个主题。切太小：上下文不完整，AI 回答时缺信息。

Spring AI 用 TokenTextSplitter 做切分：

// 按Token切分，每块800 token，重叠100 token TokenTextSplitter splitter = new TokenTextSplitter( 800, // 每块最大 token 数 100, // 相邻块之间的重叠 token 数 10, // 最小块大小 5000, // 最大块大小 true // 是否保留分隔符 ); List<Document> chunks = splitter.apply(pdfDocs);

为什么要有重叠？因为切分点是任意的，可能把一句话切成两半。重叠 100 token 保证切分边界的信息不会丢失。

经验值：中文文档建议每块 500-800 字，重叠 50-100 字。不要切得太碎，否则检索到了也拼不出完整答案。

第三步：向量化 + 存储

切分完的每一段，需要转成向量存起来。Spring AI 把这两步合并了：

@Service public class KnowledgeIngestionService { private final VectorStore vectorStore; public KnowledgeIngestionService(VectorStore vectorStore) { this.vectorStore = vectorStore; } // 把文档批量写入向量库 public void ingest(List<Document> documents) { // Spring AI 会自动： // 1. 调用 EmbeddingModel 把文本转成向量 // 2. 把向量 + 原文 + 元数据一起存入 vectorStore.add(documents); } }

配置向量数据库（以 PgVector 为例）：

spring: ai: openai: api-key: ${OPENAI_API_KEY} embedding: options: model: text-embedding-3-small vectorstore: pgvector: index-type: HNSW distance-type: COSINE_DISTANCE dimensions: 1536

vectorStore.add(documents) 这一行代码背后做了三件事：调用 embedding 模型把每个 Document 的文本转成 1536 维向量，把向量、原文、元数据（文件名、页码等）存入 PgVector，建立索引加速后续检索。

你也可以用 Redis、Chroma、Milvus，换一个配置就行，代码不用改。

第四步：检索 + 生成

这是 RAG 的核心环节。上一篇讲的 QuestionAnswerAdvisor 就是干这个的，但这次我们手动控制检索过程，看看里面发生了什么：

@Service public class RAGService { private final ChatClient chatClient; private final VectorStore vectorStore; public RAGService(ChatClient.Builder builder, VectorStore vectorStore) { this.vectorStore = vectorStore; this.chatClient = builder .defaultSystem(""" 你是企业知识库助手。根据下面提供的上下文回答用户问题。如果上下文中没有相关信息，直接说"这个问题我暂时答不了"。回答时请引用信息来源。 """) .build(); } public String ask(String question) { // 1. 构造检索请求 SearchRequest searchRequest = SearchRequest.builder() .query(question) .topK(5) .similarityThreshold(0.7) .build(); // 2. 执行向量检索 List<Document> relevantDocs = vectorStore.similaritySearch(searchRequest); // 3. 把检索结果拼成上下文 String context = relevantDocs.stream() .map(doc -> { String source = (String) doc.getMetadata().get("source"); return "[" + source + "] " + doc.getText(); }) .collect(Collectors.joining("\n\n")); // 4. 调用 AI 生成回答 return chatClient .prompt() .user(question) .system(s -> s.param("question_answer_context", context)) .call() .content(); } }

这段代码做了什么：

用户问"我们的退款政策是什么"，系统把问题转成向量在向量库里找最相关的 5 段文档，把这 5 段文档拼成上下文，把上下文和用户问题一起发给 AI，AI 基于上下文生成回答。

如果文档库里有退款政策，AI 会准确回答。如果没有，AI 会说"这个问题我暂时答不了"，而不是瞎编。这就是 RAG 相比直接调大模型最大的价值：让 AI 基于你的私有数据回答，而不是凭空生成。

第五步：用 Advisor 简化

上面手写的检索逻辑，其实可以用 Advisor 简化。Spring AI 1.0 提供了 RetrievalAugmentationAdvisor：

@Configuration public class RAGConfig { @Bean public Advisor ragAdvisor(VectorStore vectorStore, ChatClient.Builder chatClientBuilder) { return RetrievalAugmentationAdvisor.builder() // 检索器：从向量库取 top-5 .documentRetriever(VectorStoreDocumentRetriever.builder() .vectorStore(vectorStore) .topK(5) .similarityThreshold(0.7) .build()) // 查询改写：把口语化问题改成检索友好的 .queryTransformer(RewriteQueryTransformer.builder() .chatClientBuilder(chatClientBuilder) .build()) .build(); } }

这个 Advisor 自动处理了检索和上下文拼接。RewriteQueryTransformer 还会把用户的口语化问题改写成更适合检索的形式。

比如用户问"咋退款"，它会改写成"退款流程退款政策"，检索效果更好。

然后你只需要在调用时加上这个 Advisor：

@RestController public class ChatController { private final ChatClient chatClient; private final Advisor ragAdvisor; public ChatController(ChatClient.Builder builder, Advisor ragAdvisor) { this.ragAdvisor = ragAdvisor; this.chatClient = builder.build(); } @PostMapping("/ask") public String ask(@RequestBody Map<String, String> body) { return chatClient .prompt() .user(body.get("question")) .advisors(ragAdvisor) .call() .content(); } }

整个 RAG 流程对调用方完全透明。加一个 Advisor，普通对话就变成了知识库问答。

生产环境的三个坑

坑一：切分策略影响检索质量

技术文档按段落切分没问题，但代码文档要按函数切分。一段代码从中间切断，检索到了也没用。

对于 API 文档，建议按接口粒度切分，每个接口自成一块。对于教程类文档，按章节切分，保留完整上下文。

坑二：embedding 模型和生成模型要配套

用 OpenAI 的 embedding，就别混用别的模型的 embedding。不同模型的向量空间不一样，混用会导致检索准确率暴跌。

一个常见错误：先用 text-embedding-ada-002 建库，后来换成 text-embedding-3-small。向量维度不同，之前的索引全部作废，必须重建。

坑三：定期更新向量库

文档变了，向量库也要跟着变。做法是给每个文档加版本号或文件名作为元数据，更新时先按元数据删除旧版本再写入新版本：

// 先删旧版本 vectorStore.delete( DeleteBatchFilter.builder() .key("source", "product-manual.pdf") .build() ); // 再写新版本 vectorStore.add(newDocuments);

小结

Spring AI 1.0 的 RAG 流程可以用四个核心接口概括：

DocumentReader：读文档
TokenTextSplitter：切分文档
VectorStore：存取向量
RetrievalAugmentationAdvisor：自动检索增强

从手写检索逻辑到 Advisor 一步到位，1.0 的抽象确实比 0.8 版本干净太多。下一篇我们往 Agent 方向走，看看 Function Calling 在 1.0 里怎么配合 Advisor 玩。

下篇预告：Spring AI 1.0 第三篇——Function Calling 在 1.0 里怎么玩。和 Advisor 机制结合后，写 Agent 比以前简单太多了。

这套 Spring AI 1.0 RAG 的完整 Java 源码（含本文所有代码的可运行版本），以及 100 多个 AI 变现案例和可复制 SOP，全部整理在知识星球「AI搞钱实验室」里。68 块一年，不只是代码，还有从零到一跑通的全过程记录。

星球里有 Spring AI 实战笔记、Agent 系列全部源码（含完整 Spring Boot 项目），每周更新不少于 3 篇。

你的 RAG 项目遇到过什么坑？评论区聊聊。