最近一直在折腾 Spring AI Alibaba把项目中一个“文档问答”的需求落地了。核心就是 RAG检索增强生成。这篇我把自己从零开始搭建、踩坑、调优的完整过程整理出来包括代码、参数配置和排查思路。如果你正在用 Java 做 AI 应用或者想把私有知识库接入大模型这篇应该能帮你省不少时间。先说清楚这里讲的是 Spring AI Alibaba 这套框架它把 Spring AI 的抽象和国内模型服务比如 DashScope 上的一系列模型打通了。RAG 本身是个偏工程化的方案不复杂但里面细节很多文档怎么切、向量库怎么选、召回怎么调、Prompt 怎么组织每一步都影响最终效果。我会按照实际项目里从零到一的顺序来讲而不是按官方文档的目录来讲。1. RAG 为什么值得自己搭一套1.1 先厘清一个问题LLM 的短板大语言模型的知识截止日期是硬伤这是所有做 AI 应用的人都要面对的现实。我在项目里遇到的情况是用户会咨询最近更新的业务政策、内部操作规程、某个产品线的具体参数这些内容既不在模型的预训练数据里也不可能指望模型“猜”出来。如果硬让模型回答它十有八九会一本正经地编造答案也就是所谓的幻觉。解决思路其实很朴素把需要回答的知识先准备好每次提问时先从知识库里检索出相关片段再把“问题 相关片段”一起丢给大模型生成最终答案。这样模型不用依赖自己记忆里的旧知识而是基于你给它的材料作答。这个方案就是 RAG检索增强生成。它的核心价值在于知识可以随时更新不用重新训练模型回答有依据可以追溯到具体文档领域适配成本远低于微调。对于企业内部知识库、产品文档问答、客服辅助这类场景RAG 几乎是当前最务实的选择。1.2 RAG 的完整链路拆解一个标准的 RAG 系统包含两条链路一条是离线的索引构建链路一条是在线的问答检索链路。离线链路做的事情是读取源文档 - 拆分成小块chunk - 向量化 - 写入向量数据库。这一步的目标是把非结构化的文档变成可检索的结构化数据。在线链路做的事情是接收用户问题 - 向量化用户问题 - 在向量库中检索相似片段 - 组装 Prompt - 请求大模型生成回答。这两条链路涉及的组件分别是文档解析器、文本分割器、嵌入模型Embedding Model、向量数据库、大模型、Prompt 模板。Spring AI Alibaba 把其中大部分组件都做了统一抽象并提供了自动配置。你只需要在配置文件里声明用哪个模型、哪个向量库框架会自动组装好相应的 Bean。要理解 RAG 为什么能工作关键要理解“向量”和“相似度检索”这两个概念。文本嵌入模型会把一段文字转成一个高维向量语义相近的文本在向量空间里的距离也更近。用户提问时先用同一个嵌入模型把问题向量化然后在已有的文档向量里找出距离最近的几个片段这些片段就是和问题最相关的知识。用生活化的比喻来说想象你有一个装满了索引卡片的文件柜每张卡片写着一段知识点。用户问问题的时候你不是让一个什么都可能忘事的图书管理员凭借记忆瞎答而是先快速翻出最相关的几张卡片把卡片上的内容递给答题人让他看着卡片来回答。RAG 做得就是“翻卡片”这件事。2. 我们怎么选型Spring AI Alibaba 本地向量库2.1 为什么是 Spring AI Alibaba 而不是直接调 HTTP API做 AI 应用最粗暴的方式是直接用 HTTP 请求调用模型服务的接口自己管理会话、Prompt、上下文。我早期也是这么干的但很快发现问题代码里到处是拼接 JSON、处理鉴权、维护历史消息的模板代码而且换一个模型厂商就意味着改一大部分逻辑。Spring AI 做的事情是把这些操作统一抽象成 ChatClient、EmbeddingModel、VectorStore 等接口。你面向接口编程具体用哪个模型是配置决定。Spring AI Alibaba 更进一步把国内模型服务接入的细节做好了同时兼容了一个很重要的特性让模型可以调用已注册的工具这在 RAG 之外的 Agent 场景里也很有价值后面我会专门写一篇。选 Spring AI Alibaba 的另一个原因是它对向量数据库的抽象足够干净。项目初期我用的是本地内存向量库一个 Bean 搞定不需要额外部署任何中间件后期数据量上来了再切换到 Redis 或更大的向量数据库业务代码不用动。这种先跑通再优化的模式非常适合快速验证。2.2 向量库到底怎么选先内存后外部存储RAG 落地最容易犯的错误是上来就上重型组件。向量数据库确实是大数据量场景的标配但对一个初版 Demo 或者内部工具来说本地内存型的向量库完全够用而且调试体验好得多。我用的方案是 Spring AI 自带的 SimpleVectorStore它把向量保存在内存里通过 JSON 文件做持久化。优点零部署、启动即用、方便调试。缺点数据量大了之后检索速度下降且只适合单机场景。我的建议很明确先用 SimpleVectorStore 把链路跑通确认检索效果和回答质量没问题后再根据数据量决定要不要迁移。如果你需要迁移第一选择是 Redis。原因是大多数 Java 团队本来就有 Redis运维成本低而且 Spring AI 对 Redis VectorStore 的支持成熟配置几个参数就能搞定。如果数据量到了百万级向量以上再考虑专用向量数据库但那是另一个话题了。2.3 嵌入模型和大模型的选择RAG 里的嵌入模型决定了检索的上限。如果嵌入模型本身对领域语义理解不到位后面怎么调 Prompt 都白搭。我在项目里用的是 DashScope 提供的文本嵌入模型它与 Spring AI Alibaba 集成后可以零配置使用只需要在配置文件中指定模型名和 API Key。大模型负责最终回答的生成我用的也是 DashScope 上的对话模型。这里有个经验之谈选择模型时不要只盯着参数量和榜单分数要看实际任务类型。文档问答这类任务模型对长上下文的处理能力和指令遵循能力比“知识量”更重要因为知识已经通过检索提供给你了模型的角色是“基于材料做总结和推理”。Spring AI Alibaba 一个友好的地方在于它支持配置多个模型按照场景分别使用嵌入用专门的嵌入模型对话用生成模型。你可以在配置中声明多个 ChatModel Bean运行时按需注入。3. 从零开始环境准备与基础依赖3.1 项目搭建与依赖引入我用的是 Spring Boot 3.x 加 JDK 17。Spring AI Alibaba 的依赖坐标可以从官方文档的版本页找到。核心依赖就两组一组是 Spring AI Alibaba 的 Starter负责模型接入和自动配置另一组是 Spring AI 的文档解析器负责把各种格式的文档读进来。建项目时我建议直接从 start.spring.io 生成一个空项目再手动加依赖不要用 IDE 里的 AI 模板那些模板混乱得很。pom.xml 里需要加入的核心依赖dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter/artifactId version${spring-ai-alibaba.version}/version /dependency为了读取本地文档还需要引入文档读取相关的模块。比如要解析文本文件、Markdown、PDF分别对应不同的 Reader。官方文档里可以查到对应关系这里不一一罗列。我刚开始只解析 Markdown 文件所以只需要一个基础的读取模块。3.2 配置文件与模型接入自动配置是 Spring Boot 的强项Spring AI Alibaba 把模型的接入做到了极简。在 application.yml 里配置几个关键项即可spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY} chat: options: model: qwen-plus embedding: options: model: text-embedding-v3这里有几个值得解释的点。api-key 是调用模型服务的凭证建议通过环境变量或配置中心注入不要硬编码在配置文件里更不要提交到代码仓库。chat.options.model 指定对话模型embedding.options.model 指定嵌入模型。Spring AI Alibaba 之所以能零代码接入模型是因为它实现了 Spring Boot 的自动配置机制。只要 classpath 里有对应依赖容器启动时就会自动构建出 ChatModel、EmbeddingModel 等 Bean。这些 Bean 就是后续我们构建 RAG 链路的基础组件。如果你已经有 OpenAI 兼容的网关也可以配置 Spring AI 原生的 OpenAI 接入方式。Spring AI Alibaba 的自动配置支持覆盖和切换但我不建议同时混用两套配置排查问题的时候会非常痛苦。3.3 嵌入模型真实效果验证配置完成后我做的第一件事不是写 RAG而是先写一个最小的测试验证 EmbeddingModel 是否可用。这个测试虽然简单但非常重要它能帮你把“模型配置问题”和“RAG 逻辑问题”隔离开。SpringBootTest class EmbeddingModelTest { Resource private EmbeddingModel embeddingModel; Test void testEmbedding() { var response embeddingModel.embed(Spring AI Alibaba 的 RAG 方案); System.out.println(Arrays.toString(response)); Assertions.assertTrue(response.length 0); } }运行这个测试如果控制台打印出了一个浮点数数组说明嵌入模型接入成功。我在实际测试中发现文本嵌入模型对英文和中文的效果差异较大如果你的知识库以中文为主最好用对中文支持更好的嵌入模型并在后续评估检索效果时特别留意中文语义的匹配情况。一个小技巧你可以把两条语义相近的中文句子分别嵌入然后计算它们的余弦相似度看模型是不是真的“理解”了中文语义。这一步能帮你提前发现模型选型的坑比跑完整流程再回头查问题高效得多。4. 索引链路文档读取、拆分与向量化4.1 文档读取不止是 IO 操作文档读取是 RAG 的第一步但很多人做得太随意。以前我以为读取就是 FileReader 读字符串后来发现实际场景里文档格式千变万化有 Markdown、有 Word、有 PDF、有扫描件。Spring AI 提供了 DocumentReader 抽象不同格式有对应的实现。我常用的读取方式大体有这几种文本文件和 Markdown 用行读取PDF 用解析库抽取文本。如果文档结构复杂比如有标题层级、表格、图片还需要自定义 Reader 做清洗。RAG 的检索质量很大程度上取决于文档清洗质量不是简单把文字抽出来就完事。以读取一个文本文件为例var reader new FileSystemDocumentReader( Paths.get(src/main/resources/docs/knowledge-base.txt) ); ListDocument documents reader.get();Document 是 Spring AI 对文本块的统一抽象包含 id、text、metadata 三个核心字段。metadata 里可以放文件路径、来源、作者、时间等辅助信息这些信息在后面回答追溯时有重要作用。这里我踩过一个坑文件编码。Windows 环境下常见的中文文本是 GBK 编码而 Spring AI 的默认读取是基于 UTF-8 的。如果我直接用默认配置读 GBK 文件出来的文本是乱码向量化出来的效果惨不忍睹。解决方式是先统一文件编码或者在读取前做转码。4.2 文本分割chunk 大小的学问文档读取后是一整篇长文本直接向量化会有两个问题。一是嵌入模型通常有输入长度限制超长文本会被截断二是整篇文档的向量只有一个检索时命中粒度太粗用户问的是某个细节你返回的是一整篇文档大模型很难从大量无关内容里找到准确答案。所以需要做文本分割把长文档切成块chunk。Spring AI 提供了 TokenTextSplitter它基于 token 数切分比按字符切分更符合模型的处理方式var splitter TokenTextSplitter.builder() .withChunkSize(500) .withChunkOverlap(100) .build(); ListDocument chunks splitter.apply(documents);chunkSize 控制每块的最大 token 数chunkOverlap 控制相邻块之间的重叠 token 数。为什么要重叠呢?如果一个知识点恰好被切在边界上没有重叠这个知识点就会被切成两半检索时无论哪一半都可能语义不完整。有了重叠边界处的信息会在相邻块里重复出现降低丢失概率。chunk 大小没有魔法数字需要根据实际文档和问题类型来调。我在项目里总结出一个规律面向事实型问答的chunk 在 300 到 500 token 效果比较好如果文档是流程说明、步骤型内容chunk 要更大一些保证一个完整流程落在一个块里。4.3 向量化与入库文本切分完成之后需要把每个 chunk 转成向量并存入向量库。Spring AI 的 VectorStore 接口统一了这个操作。使用 SimpleVectorStore 的话只需要声明一个 Bean把 EmbeddingModel 注入进去框架会帮你做向量化Bean VectorStore vectorStore(EmbeddingModel embeddingModel) { return SimpleVectorStore.builder(embeddingModel).build(); }接下来就是执行入库操作。这一步也是整个 RAG 链路里最直白的一步遍历所有 chunk调用 vectorStore.add()。但很多人会在这里忽略一个关键点向量化是调用外部 API 的批量文档可能有几百上千块逐条调用耗时非常长必须用批量方式提交。Spring AI 的 add 方法天然支持批量操作传入 Document 列表即可。Resource private VectorStore vectorStore; public void buildIndex(ListDocument documents) { // 批量写入向量库 vectorStore.add(documents); log.info(索引构建完成共写入 {} 个文档块, documents.size()); }这一步我有过惨痛的教训第一次测试时我把一个 PDF 解析出 800 多个 chunk直接循环逐条调用 add结果跑了将近二十分钟还频繁触发接口限流。改成批量提交后一次调用解决时间从二十分钟降到了一分钟以内。所以任何调用外部模型的场景只要接口支持批量务必用批量。4.4 索引完成的验证手段索引构建完成后很多同学直接就开始写问答接口跳过了中间验证环节。一旦问答效果不好根本不知道问题出在检索还是生成。我建议插入一个检索独立测试直接调用 VectorStore 的相似度检索看返回的 chunk 是否匹配预期。var results vectorStore.similaritySearch( SearchRequest.builder() .query(项目的技术选型是什么) .withTopK(3) .build() ); for (var doc : results) { System.out.println(doc.getText()); }这一步输出的内容就是大模型最终“看到”的参考材料。如果这里返回的内容和问题不相关那无论换多大的模型、调多好的 Prompt 都没用。相反如果这里返回的内容精准但最终回答质量不行问题就锁定在 Prompt 组织或者模型参数上。我的习惯是每次调整切分参数或嵌入模型后先跑一轮检索测试把各测试问题的 Top5 结果都打出来看一眼再决定要不要进下一环节。5. 问答链路从检索到 Prompt 组装到生成5.1 原生检索 Prompt 模板最朴素但最可控的方式很多人一上来就用框架提供的高级 API比如 Advisor结果出了问题既不知道内部做了什么也不知道怎么调。我在讲解 RAG 实现时更喜欢先从最原始的方式开始再逐层封装。最原始的问题是用户输入 question我从向量库搜到 List 然后用一个 Prompt 模板把 question 和 docs 拼起来发给 ChatModel。Spring AI 提供了 PromptTemplate用起来很直观Resource private ChatModel chatModel; Resource private VectorStore vectorStore; public String answer(String question) { // 1. 检索 var searchResults vectorStore.similaritySearch( SearchRequest.builder().query(question).withTopK(3).build() ); // 2. 组装上下文 String context searchResults.stream() .map(Document::getText) .collect(Collectors.joining(\n\n)); // 3. 提示词模板 var promptTemplate new PromptTemplate( 你是智能文档助手。请仅根据以下资料回答问题如果资料中没有相关信息请明确回答“资料中没有相关内容”不要编造。 资料 {context} 用户问题 {question} ); MapString, Object params Map.of( context, context, question, question ); Prompt prompt promptTemplate.create(params); // 4. 生成 return chatModel.call(prompt).getResult().getOutput().getText(); }这段代码是整个 RAG 问答链路的灵魂。各个步骤的目的如下检索阶段query 直接使用用户问题Spring AI 内部会先对 query 做嵌入再用向量相似度在库里检索。上下文组装阶段把检索到的 TopK 个 chunk 用换行拼接。这里要注意拼接的顺序其实大部分情况下按相似度分排序就好不需要额外逻辑。Prompt 模板阶段我特意要求模型“仅根据资料回答资料没有就直说”。这一句是抑制幻觉的关键。没有这句话模型很可能觉得资料不全开始调动自己的预训练知识来脑补答案。生成阶段把组装好的 Prompt 传给 ChatModel拿到最终输出。用这个方式的优势是每一步都裸奔可见检索结果对不对拼接的 prompt 长什么样模型最终回答了什么。出了问题你能一步步定位不会被框架的“黑盒”困住。5.2 用 Advisor 简化代码自己组装 Prompt 固然清晰但如果只是做一个标准问答工具每次都写这段样板代码也挺烦。Spring AI 提供了 QuestionAnswerAdvisor它把“检索 组 Prompt 调用大模型”这一套封装好了Resource private ChatClient.Builder chatClientBuilder; Resource private VectorStore vectorStore; public String answerWithAdvisor(String question) { ChatClient chatClient chatClientBuilder .defaultAdvisors(new QuestionAnswerAdvisor(vectorStore)) .build(); return chatClient.prompt() .user(question) .call() .content(); }代码量确实减少了很多而且默认行为已经覆盖了基本需求自动检索、自动拼 Prompt、自动要求模型基于上下文回答。但用 Advisor 有一个前提你必须理解它也做了一些你没有主动要求的事情。它在内部对于检索结果、Prompt 组装方式有默认实现。业务简单时没问题一旦需要控制“检索多少个结果”“相似度阈值是多少”“如何引用来源”你还是得回到自定义方式或者深入了解 Advisor 的可配置项。我的做法是项目里先用原生方式跑通沉淀出一版稳定可用的 Prompt 模板之后如果业务接入点比较多、需要统一行为再考虑封装成自己的工具方法或使用 Advisor。5.3 回答来源回溯让 RAG 更可信RAG 相比纯模型问答的一个关键优势是“可追溯”。用户想知道这个答案的依据是什么应该能看到相关文档片段。这在企业场景几乎是个硬需求。实现方式其实很简单Prompt 模板里要求模型在回答后附上来源编号同时在代码里把检索结果和答案一起返回。或者更直接一点在组装上下文时给每个 chunk 标记序号并让模型在引用时输出序号。下面是我常用的一个模板写法你是智能文档助手。请仅根据以下资料回答问题并在回答末尾标注引用的资料编号。 资料 [1] 第一段资料内容…… [2] 第二段资料内容…… 用户问题……这样前端可以把答案里的编号映射到具体文档片段上实现答案溯源。调试时也更容易看出模型到底用了哪部分资料。5.4 ChatClient 的高级玩法在实际项目中一个问答接口往往不只是“问一句答一句”。用户可能追问、可能一个会话里涉及多个问题。RAG 如果每次都不带历史对话用户追问“那第二个方案呢”的时候模型根本不知道“那”指什么。解决方案是给 ChatClient 配置 ChatMemory。Spring AI 的 ChatClient 支持在 builder 里设置默认上下文的记忆机制。这样 RAG 检索到的内容会和历史消息一起进入到模型上下文中模型能理解代词指代。这里我提醒一个性能点会话历史越长token 消耗越大响应越慢。务必要给 ChatMemory 配置合理的过期策略和最大消息数否则长会话场景下成本会很可观。比如设置最近 20 条消息或者最早的过期时间具体看业务需要。另外历史消息里的“资料片段”是否也要全部带入下一轮?我的策略是不把完整的检索结果历史带进去只带用户问题历史每次回答时重新检索保证答案依据最新资料。6. 参数调优RAG 效果好不好的分水岭6.1 可调参数全景图不少同学跑通 RAG 后说效果不好但具体哪里不好又说不上来。我发现RAG 系统的效果调优其实就几个变量把它们一个个梳理清楚问题多半能定位到具体参数上。我把 RAG 参数分为三组分割参数、检索参数、生成参数。每组参数背后都有明确的调整逻辑。分割参数包括 chunkSize 和 chunkOverlap它们决定“知识切片的大小和重叠程度”。chunkSize 太小语义碎片化严重检索可能漏掉完整信息chunkSize 太大每个 chunk 包含太多无关信息召回的噪音太大模型也容易迷失重点。chunkOverlap 如果设为零语义断点风险显著上升设太大又会造成存储冗余和检索重复命中。检索参数包括 topK 和相似度阈值。topK 决定每次喂给模型的片段数量相似度阈值决定“低于多少相似度就视为不相关”。我习惯先开放式检索看再调阈值不要一开始就被阈值挡掉太多结果。生成参数包括 temperature 和系统提示词中的约束。文档问答场景我建议 temperature 调低比如 0.2 或 0.3让模型更忠实于资料。如果 temperature 太高同一个问题每次都给出不同答案而且容易发散在知识问答场景里很致命。6.2 各参数的调试策略与效果观察先看 chunkSize 调整。我在一个内部 FAQ 文档上做过对比chunkSize 控制在 400 到 600 token 之间效果明显好于 200 和 1200。原因是 FAQ 的每一条知识大多在这个长度范围内如果切太大一条 chunk 里混了多个知识点检索时明明只问其中一条结果把整个 chunk 带了回来虽然答案也能对但引用的资料里塞了大量无关内容模型生成质量被稀释。再看 topK 调整。topK1 时回答往往信息不足遇到需要多文档综合的问题就抓瞎topK5 时如果文档本身噪音大反而会引入干扰信息。我的经验是先设 topK3 做基线再针对典型测试问题分别试 2 和 4观察输出质量。记得把每个测试问题对应的检索结果打印出来肉眼检查有没有相关片段被漏掉有没有不相关片段混进来。最后说温度。RAG 场景和创意写作不同你要的是“稳定、忠于材料”的答案而不是“每次不一样但有文采”的答案。我把 temperature 调制 0.2 以后实测回答质量明显更稳定幻觉率也下降。6.3 相似度阈值什么时候该拒绝回答在 RAG 系统中最尴尬的结果是用户问了一个知识库根本不覆盖的问题系统还是硬着头皮用不太相关的资料凑了个答案。这是个很现实的问题尤其在客服、企业内部问答场景答错比拒答危害大得多。解决办法是给检索加一个相似度阈值。如果检索出来的最相似片段分数仍然很低就说明问题超出了知识库范围主动判定为无法回答。Spring AI 的 SearchRequest 支持 withSimilarityThresholdSearchRequest.builder() .query(question) .withTopK(3) .withSimilarityThreshold(0.6) .build();相似度阈值需要调试。我建议先不加阈值收集一批知识库内问题和知识库外问题分别观察它们的相似度分布然后取一个能把“库外问题”大部分挡掉的值。这个值不要拍脑袋定要靠数据来定。阈值设太高会把本该能答的问题挡掉太低又起不到拒绝回答的作用。6.4 调参过程中需要留意的评估方法调参最怕的是自我感觉良好换几个方向就宣布 OJ 了。我建议每个参数调整都配一组固定的测试问题集问题集里覆盖简单事实、跨文档综合、库外问题三类。每次调参都在这组问题上跑一遍并记录结果。表格记录是个好习惯方便互相比较参数变化测试问题集检索命中率回答正确率回答稳定性chunkSize 400事实型 20 题85%90%稳定chunkSize 800事实型 20 题75%80%稳定topK3 无阈值跨文档 10 题80%70%内容冗余有了这个评估底子参数调优就变成了数据驱动的工作而不是玄学。7. 常见问题与排查技巧实录7.1 检索结果为空或者明显不相关这是 RAG 落地中最常见的现象。通常的原因有四个按出现概率排序第一没有执行 add 操作或者 add 时传入的是空列表。代码跑得很顺但一直没把文档写入向量库检索自然没有结果。检查方式很简单检索前先打印 vectorStore 里有没有数据。第二query 和文档的语言不一致。嵌入模型通常对跨语言检索支持一般文档是英文、问题是中文或者反过来检索效果都会大打折扣。统一的嵌入模型加统一语言是很重要的。第三文档分割太大或太小。太大导致每个 chunk 包含太多主题检索结果里混着大量噪声太小导致语义不完整检索不到关键上下文。第四embedding 模型切换后旧向量的维度不一致。如果原本用的是 1024 维的嵌入模型后面改成 512 维新老向量没法对齐检索结果必然异常。这种情况下必须重建整个索引不要尝试混用。7.2 回答幻觉严重、答非所问模型明明检索到了资料但回答里出现了资料中没有的“事实”这是最让人头疼的。这儿的根因往往是 Prompt 约束不足。我在 Prompt 里专门加了一条系统约束“只能基于资料作答资料没有就明确说不知道”幻觉率下降明显。此外chunk 太大或者 topK 太大会让资料里包含大量无关内容模型在噪声背景下容易“顺着自己的思路跑偏”。可以把 topK 调小或者加相似度阈值过滤掉低质片段。最后要检查一下检索到的资料是不是真的和问题相关。如果相关资料本身就没检索到模型只能硬编这是检索问题不是生成问题。7.3 向量库服务启动报错或 Bean 缺失使用 SimpleVectorStore 时一切正常切到 Redis 或者外部向量数据库时经常出现启动报错常见的有两种。一种是找不到对应的 VectorStore Bean原因通常是依赖没引入。比如用 Redis 做向量库除了要引入 Redis 依赖还得引入 Spring AI 的 Redis VectorStore 模块。另一种是配置项缺失比如 Redis 的连接地址、索引名称没有配置Spring AI 自动配置没有生效容器启动时拿不到 VectorStore Bean。解决方式是先看启动日志里的配置报告确认哪个配置没有生效再对照官方文档检查坐标和属性名。不要一上来就怀疑代码大部分 Bean 缺失问题都是依赖或配置层面的。7.4 中文文档乱码和切分异常中文乱码大部分是编码问题前面已经提过。切分异常则更隐蔽英文按空格和标点切分天然适合 token 级别处理中文没有空格且一个汉字往往对应 1 到 2 个 token切分后可能会出现一个词被截断成两部分的情况。我的处理经验是优先选用对中文支持较好、按语义分句的分割器如果只能用基础 TokenTextSplitter就把 chunkSize 稍微调大降低语义断裂概率。同时文档清洗阶段注意去掉特殊符号和排版残留比如多余的换行、页码、页眉页脚这些噪音对中文嵌入效果的影响比想象中大得多。7.5 API 调用报错和限流接入外部模型服务后最容易碰到的报错是超时和限流。批量向量化几百个 chunk 时如果并发控制不好很容易触发限流。解决方案不难批量调用时适当增加重试机制和退避时间。Spring AI 内部对模型调用有重试机制但如果你的批次太大、并发太高还是要自己控制节奏可以把大列表拆成小批次每批之间做短暂休眠。另外Prompt 太长、超过模型上下文限制这个问题也会出现。尤其会话历史加检索资料叠加后很容易顶到上下文上限。遇到这种报错先看是不是历史消息没有裁剪再查检索回来的 chunk 是否过大。8. 项目落地过程中的几点体会这套 RAG 功能从搭建到稳定运行前后迭代了几轮。最后分享一些个人总结给你做个参照。第一先把链路跑通再优化效果。一开始不要追求完美SimpleVectorStore 加最小 Prompt 模板就够验证方案了。很多同学第一步就栽在选型上纠结用哪个向量库、哪个模型结果迟迟没有跑起来。先用最简单的方式验证可行性再逐步升级。第二检索效果决定了整个系统的上线。在 RAG 里大模型的生成能力通常不是瓶颈瓶颈在检索是否精准。每次调优我都把检索结果打出来看这一步的投入产出比是最高的。如果检索出来一堆不相关内容后面优化的不应该是模型而是文档拆解和嵌入模型。第三沉淀自己的评估集。做 RAG 和做推荐系统在这一点上很像没有评估集你根本不知道改动是变好还是变坏。哪怕先准备二十条典型问题也比没有强。第四控制好成本。RAG 能解决知识更新问题但每次检索和生成都在调用模型是有调用成本的。加大 chunk 或者把 topK 调高每次问答消耗的 token 都会上涨。在效果达标的前提下尽量让资料“少而精”这对成本和延迟都有好处。后续我做 Agent 相关功能时发现 RAG 的向量检索和 Agent 的工具调用组合起来可以处理更复杂的任务。这部分的实践等下一篇再展开讲。就 RAG 本身而言它真正解决了企业内部知识问答的核心痛点值得系统掌握。