Spring AI 2.0 RAG模块升级：依赖改名、Advisor架构与迁移注意事项

文章摘要

Spring AI 2.0对RAG相关模块进行了重新组织：原来的 spring-ai-advisors-vector-store 已改名为 spring-ai-vector-store-advisor，常用RAG流程继续通过QuestionAnswerAdvisor接入ChatClient，同时保留可自定义的模块化RAG架构。对于从1.1.x升级的项目，除了修改依赖，还需要检查Starter命名、包结构、Advisor注册、向量库自动配置和过滤表达式。本文给出完整迁移清单。

一、最直接的变化：依赖改名

旧依赖：

    org.springframework.ai

        spring-ai-advisors-vector-store

Spring AI 2.0改为：

    org.springframework.ai

        spring-ai-vector-store-advisor

如果升级后出现：

QuestionAnswerAdvisor找不到
依赖无法解析
ClassNotFoundException

先检查是否还在使用旧Artifact ID。

二、Starter命名也需要一起检查

Spring AI的新命名规则更加统一。

模型Starter：

spring-ai-starter-model-{provider}

向量库Starter：

spring-ai-starter-vector-store-{store}

例如PGvector：

    org.springframework.ai

        spring-ai-starter-vector-store-pgvector

旧项目中可能仍使用：

spring-ai-pgvector-store-spring-boot-starter

升级时不要只修改BOM版本，要逐项检查依赖名称。

三、Spring AI的RAG有两种使用方式

1. 开箱即用Advisor

最简单的方式：

ChatResponse response = ChatClient
        .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的两种方式

默认注册

@Bean
ChatClient ragChatClient(
        ChatClient.Builder builder,
        QuestionAnswerAdvisor ragAdvisor
) {
    return builder
            .defaultAdvisors(ragAdvisor)
            .build();
}

对该ChatClient全部请求生效。

单次注册

String answer = chatClient.prompt()
        .advisors(
                QuestionAnswerAdvisor
                        .builder(vectorStore)
                        .build()
        )
        .user(question)
        .call()
        .content();

适合按请求选择不同知识库或策略。

常见问题是：

Advisor注册在一个ChatClient
业务调用另一个ChatClient

六、动态过滤条件怎么处理

企业RAG必须按租户和权限过滤。

伪代码：

String filter = "tenant_id == '" 
        + safeTenantId + "'"
        + " && status == 'EFFECTIVE'";

SearchRequest request = SearchRequest.builder()
        .query(question)
        .topK(8)
        .filterExpression(filter)
        .build();

注意：

  • 不要直接拼接未经校验的用户输入；
  • tenantId应来自认证上下文；
  • 过滤表达式要做转义；
  • 服务端仍需执行数据权限；
  • 检索日志不要泄露敏感过滤条件。

七、VectorStore自动配置变化

Spring AI 2.0将自动配置拆分得更细，目的是减少不必要依赖和版本冲突。

升级后如果VectorStore Bean不存在，检查：

Starter是否正确
配置前缀是否正确
数据库驱动是否存在
Schema初始化是否完成
EmbeddingModel Bean是否存在

不要直接手工创建多个重复VectorStore Bean，否则可能产生注入歧义。

八、Document与Metadata迁移检查

入库代码：

Document document = new Document(
        content,
        Map.of(
                "document_id", documentId,
                "tenant_id", tenantId,
                "version", version,
                "status", "EFFECTIVE"
        )
);

升级时检查：

  • Metadata类型是否兼容；
  • 主键生成方式；
  • ID是否稳定；
  • Filter字段是否已建立索引；
  • 日期类型是否一致；
  • 数字是否被保存为字符串。

九、ETL模块也要同步验证

Spring AI ETL包含：

DocumentReader
DocumentTransformer
DocumentWriter

常见链路：

List documents = reader.get();
List chunks = splitter.apply(documents);
vectorStore.write(chunks);

升级后需要验证：

  • PDF Reader依赖；
  • Markdown Reader依赖；
  • TokenTextSplitter参数；
  • Metadata是否复制到Chunk；
  • 批量Embedding策略；
  • Writer失败重试。

十、TokenTextSplitter中文配置

Spring AI TokenTextSplitter支持自定义标点。

中文场景建议包含：

。
！
？
；
\n

示意：

TokenTextSplitter splitter =
        TokenTextSplitter.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过滤，不能只修改版本号。

延伸阅读

想持续跟踪大模型、RAG、Agent、MCP 与开发者生态的最新变化，欢迎访问 智元界：

https://www.zyentor.com/

智元界将持续分享 AI 热点解读、技术实战、工具推荐与企业落地案例。