Spring AI 版本升级踩坑：ChatClient 变 ChatModel、artifact 改名、配置属性迁移

一句话先说结论：Spring AI 是快速迭代的框架，1.0 前后踩了几乎所有“命名迁移”的坑——旧 ChatClient 的功能挪进了 ChatModel，EmbeddingClient/ImageClient 这类 *Client 统一改成 *Model，starter 的 artifact 名也标准化了。升级时最容易翻车的是照着旧博客抄代码，结果类名、包名、配置键全对不上。升级前先读官方 upgrade notes，再用 BOM + OpenRewrite 自动迁移。

背景

Spring AI 从 0.7/0.8 一路发到 1.0（2025-05 GA），每个 milestone 都带着 breaking change。早期很多教程、博客里的代码是 0.8 时代的，直接照搬到 1.x 项目里会到处编译不过。理解那条主线——“把模型访问能力从 *Client 归到 *Model”，就能抓住大半变化。

现象

升级后最常见的几类报错：

// 类找不到
Cannot resolve symbol 'ChatClient'
// 或者方法名变了
Cannot resolve method 'getGenerationTokens'
// 或者配置键不生效，模型 Bean 没注册
Unsupported model provider: 'openai'

更隐蔽的是：代码能编译、启动也不报错，但某些配置项（比如 .options 前缀下的 model）悄悄失效，导致运行时走了默认值，行为不对。

根因分析

变化 1：Client → Model 的角色迁移

这是最核心的一条。1.0.0-M1 起，旧的 ChatClient 被拆了：

模型访问能力（call/stream）挪进了 ChatModel。
新的 ChatClient 持有一个 ChatModel 实例，主打 fluent API（链式 prompt().user().call()）。

同类命名统一也在发生：EmbeddingClient → EmbeddingModel、ImageClient → ImageModel。所以旧代码里凡是 *Client 当模型用的，升级后基本都要改成 *Model。

变化 2：artifact 名标准化

pre-1.0 的 spring-ai-openai-spring-boot-starter 这种长名字，1.0 起统一成 spring-ai-starter-model-openai。memory 相关还加了 repository 后缀：

spring-ai-openai-spring-boot-starter          → spring-ai-starter-model-openai
spring-ai-model-chat-memory-jdbc              → spring-ai-model-chat-memory-repository-jdbc
spring-ai-elasticsearch-store-spring-boot-starter → spring-ai-starter-vector-store-elasticsearch

只换 starter 名字、不碰内部模块，就会因为 artifact 找不到而构建失败。

变化 3：包名和模块拆分

spring-ai-core 这个大杂烩被拆成了 spring-ai-commons / spring-ai-model / spring-ai-vector-store / spring-ai-client-chat 等。一些类也搬了包：

org.springframework.ai.model.Content         → org.springframework.ai.content.Content
org.springframework.ai.transformer.xxx        → org.springframework.ai.chat.transformer.xxx

变化 4：方法名和配置键

Usage.getGenerationTokens() → getCompletionTokens()，token 计数 Long → Integer。
到 1.1/2.0，配置属性去掉了 .options 这一层：spring.ai.openai.chat.options.model → spring.ai.openai.chat.model（2.0.0-M6 起）。

解决方案

用 BOM 统一版本，不手动写版本号

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.1.7</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

用 BOM 后，starter 和内部模块版本由 BOM 拉平，避免“版本号各自为政”导致的 ClassNotFoundException。

有官方的 OpenRewrite recipe 可自动化迁移

Spring AI 提供了 OpenRewrite 迁移 recipe（Arconia Spring AI Migrations），能自动改大部分类名/包名/方法名：

# 参考 https://github.com/arconia-io/arconia-migrations

大项目手工改容易漏，建议先跑 recipe 再人工核对剩余 diff。

升级动作清单

查 upgrade notes 对应版本段。
升 BOM 版本，改 starter 为标准命名。
*Client → *Model，getGenerationTokens() → getCompletionTokens()。
检查包名是否迁移（IDE 的 import 会提示）。
检查配置键是否去掉了 .options 层。
跑一遍测试/压测确认行为没变，而不只是编译通过。

小结

Spring AI 升级的核心词是“改名”：*Client → *Model、artifact 标准化、包名重排、配置键去 .options。
别照抄旧博客，先对照 upgrade notes。
用 BOM 管版本 + OpenRewrite 自动化，能省一大半手工活。
编译过了还不够，配置键静默失效这种要跑功能验证才抓得到。