文章摘要Spring AI 2.0对RAG相关模块进行了重新组织原来的spring-ai-advisors-vector-store已改名为spring-ai-vector-store-advisor常用RAG流程继续通过QuestionAnswerAdvisor接入ChatClient同时保留可自定义的模块化RAG架构。对于从1.1.x升级的项目除了修改依赖还需要检查Starter命名、包结构、Advisor注册、向量库自动配置和过滤表达式。本文给出完整迁移清单。一、最直接的变化依赖改名旧依赖dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-advisors-vector-store/artifactId/dependencySpring AI 2.0改为dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-vector-store-advisor/artifactId/dependency如果升级后出现QuestionAnswerAdvisor找不到 依赖无法解析 ClassNotFoundException先检查是否还在使用旧Artifact ID。二、Starter命名也需要一起检查Spring AI的新命名规则更加统一。模型Starterspring-ai-starter-model-{provider}向量库Starterspring-ai-starter-vector-store-{store}例如PGvectordependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-vector-store-pgvector/artifactId/dependency旧项目中可能仍使用spring-ai-pgvector-store-spring-boot-starter升级时不要只修改BOM版本要逐项检查依赖名称。三、Spring AI的RAG有两种使用方式1. 开箱即用Advisor最简单的方式ChatResponseresponseChatClient.builder(chatModel).build().prompt().advisors(QuestionAnswerAdvisor.builder(vectorStore).build()).user(userText).call().chatResponse();QuestionAnswerAdvisor会接收用户问题 → 查询VectorStore → 获取相关Document → 把上下文加入Prompt → 调用模型适合基础知识问答快速原型单一向量库简单过滤条件。2. 模块化RAG Flow复杂项目需要控制查询改写多路检索Metadata过滤Reranker上下文压缩多知识库父子Chunk检索后评测。这时可以使用Spring AI的模块化RAG组件自定义完整流程。四、不要把QuestionAnswerAdvisor当成完整企业RAG它解决的是基本链路不会自动提供文档版本治理多租户权限混合检索Rerank引用校验答案忠实度解析质量门禁增量更新数据删除审计。生产系统通常需要在Advisor前后增加TenantAdvisor QueryRewriteAdvisor RetrievalAdvisor CitationAdvisor EvaluationAdvisor五、注册Advisor的两种方式默认注册BeanChatClientragChatClient(ChatClient.Builderbuilder,QuestionAnswerAdvisorragAdvisor){returnbuilder.defaultAdvisors(ragAdvisor).build();}对该ChatClient全部请求生效。单次注册StringanswerchatClient.prompt().advisors(QuestionAnswerAdvisor.builder(vectorStore).build()).user(question).call().content();适合按请求选择不同知识库或策略。常见问题是Advisor注册在一个ChatClient 业务调用另一个ChatClient六、动态过滤条件怎么处理企业RAG必须按租户和权限过滤。伪代码Stringfiltertenant_id safeTenantId status EFFECTIVE;SearchRequestrequestSearchRequest.builder().query(question).topK(8).filterExpression(filter).build();注意不要直接拼接未经校验的用户输入tenantId应来自认证上下文过滤表达式要做转义服务端仍需执行数据权限检索日志不要泄露敏感过滤条件。七、VectorStore自动配置变化Spring AI 2.0将自动配置拆分得更细目的是减少不必要依赖和版本冲突。升级后如果VectorStore Bean不存在检查Starter是否正确 配置前缀是否正确 数据库驱动是否存在 Schema初始化是否完成 EmbeddingModel Bean是否存在不要直接手工创建多个重复VectorStore Bean否则可能产生注入歧义。八、Document与Metadata迁移检查入库代码DocumentdocumentnewDocument(content,Map.of(document_id,documentId,tenant_id,tenantId,version,version,status,EFFECTIVE));升级时检查Metadata类型是否兼容主键生成方式ID是否稳定Filter字段是否已建立索引日期类型是否一致数字是否被保存为字符串。九、ETL模块也要同步验证Spring AI ETL包含DocumentReader DocumentTransformer DocumentWriter常见链路ListDocumentdocumentsreader.get();ListDocumentchunkssplitter.apply(documents);vectorStore.write(chunks);升级后需要验证PDF Reader依赖Markdown Reader依赖TokenTextSplitter参数Metadata是否复制到Chunk批量Embedding策略Writer失败重试。十、TokenTextSplitter中文配置Spring AI TokenTextSplitter支持自定义标点。中文场景建议包含。 \n示意TokenTextSplittersplitterTokenTextSplitter.builder().withChunkSize(600).withMinChunkSizeChars(200).withMinChunkLengthToEmbed(20).withKeepSeparator(true).withPunctuationMarks(List.of(。,,,,\n)).build();具体方法签名应以当前2.0.0 API为准。十一、迁移时建立兼容测试入库测试同一文档 → 旧版本分块 → 新版本分块 → 比较数量、内容和Metadata检索测试固定问题集 → 比较Top K → 比较排名 → 比较过滤结果问答测试固定检索结果 → 比较最终答案 → 比较引用 → 比较Token十二、常见升级故障1. 找不到QuestionAnswerAdvisor检查新依赖。2. VectorStore Bean不存在检查新Starter和配置前缀。3. 检索为空检查Embedding模型、维度、Collection和过滤条件。4. Advisor没有执行检查调用的ChatClient实例。5. Metadata过滤失败检查字段类型和表达式语法。6. 中文Chunk异常检查标点和TokenSplitter参数。十三、推荐迁移流程固定旧版本依赖 → 导出黄金测试集 → 修改BOM与Artifact ID → 修复编译错误 → 验证ETL → 验证VectorStore → 验证Advisor链 → 影子检索 → 灰度上线不要在没有检索基线的情况下直接升级生产。总结Spring AI 2.0 RAG升级的核心不是功能完全重写而是依赖命名统一 模块拆分更清晰 Advisor继续承担基础RAG入口 复杂流程保留模块化扩展能力从1.1.x迁移时要同时检查依赖、Starter、Advisor、ETL、VectorStore和Metadata过滤不能只修改版本号。