Spring AI和Spring Boot版本对应关系 Spring Boot如何集成Spring AI框架-Spring中文网站

　　很多团队第一次把大模型接进Java服务时，踩坑往往不在业务代码，而在版本对不上：Spring Boot升了，Spring AI没跟上，自动配置类找不到；Spring AI升了，仓库还停在旧镜像，依赖拉不下来。把版本对应关系先理清，再按官方推荐的依赖管理方式接入，后面才不会在一堆NoClassDefFoundError里兜圈子。

　　一、Spring AI和Spring Boot版本对应关系

　　先说结论会更省事：Spring AI不是随便挑一个版本就能塞进任何Boot里，它跟随Boot大版本演进，尤其是自动配置与Starter部分对Boot的依赖非常敏感。官方文档明确当前支持的Boot主线集中在3.4与3.5两个代际，而Spring AI主分支也给了对Boot 4的对应关系。

　　1、你用Spring Boot 3.4.x时，优先选Spring AI 1.0.x这条线更稳，Spring AI升级说明里也出现了将依赖管理对齐到Spring Boot 3.4.2的变更记录，说明这一代际是它的重要基线之一。

　　2、你用Spring Boot 3.5.x时，Spring AI 1.1.x是明确对应的分支线，仓库README里直接写了1.1.x对应Boot 3.5.x，用它可以减少自动配置类变动带来的兼容风险。

　　3、你准备上Spring Boot 4.x时，需要跟Spring AI 2.x走同一代际，README把2.x对应Boot 4.x写得很直白，别拿1.0或1.1去硬配Boot 4。

　　4、如果你还在Spring Boot 3.3及更早，官方入门文档写的是支持3.4.x与3.5.x，意味着你继续停留在更早代际时，接入会更容易遇到依赖缺口或自动配置缺失，这种情况下要么先把Boot抬到受支持代际，要么接受自行适配的成本。

　　二、Spring Boot如何集成Spring AI框架

　　接入的核心思路就两件事：用BOM把Spring AI一组依赖锁住，用Starter把自动配置打开，然后用配置文件把模型提供方的参数接上。Spring AI文档强调它的BOM只做依赖版本管理，不替你管理Spring Boot版本，你仍然用Spring Boot父POM或spring-boot-dependencies来管Boot那条线。

　　1、先用Spring Initializr起项目更省时间：打开start.spring.io，选择Spring Boot版本时按上一节的对应关系选3.4.x或3.5.x，然后点【Add Dependencies】搜索Spring AI相关依赖并加入，生成后解压导入IDEA即可。

　　2、再把Spring AI BOM接进构建管理里：Maven用dependencyManagement导入org.springframework.ai:spring-ai-bom，Gradle用platform方式引入，官方入门页给的示例就是这个思路，这一步做完你后续加模块依赖时就不用手写一堆版本号。

　　3、按你要用的模型提供方加Starter依赖：如果你先从OpenAI接入，文档示例给的是org.springframework.ai:spring-ai-starter-model-openai，把它加进依赖即可，其他模型提供方也有对应的starter，思路一致。

　　4、把关键配置写进application.yml或application.properties：至少要把API Key与模型名写进去，OpenAI场景常见配置项以spring.ai.openai开头，后续你要控温度、最大token、是否并行工具调用等，也是在这些配置项上加。

　　5、跑通一条最短调用链做冒烟验证：启动应用后用一个最简单的接口调用一次ChatClient或ChatModel拿到返回内容即可，先验证网络、密钥、依赖与自动配置都正常，再去做RAG、工具调用与向量库接入，排障会轻很多。

　　三、Spring AI升级与兼容问题排查

　　实际落地时最常见的不是写错业务逻辑，而是版本和仓库源导致的构建失败或运行期类缺失。这里按出现频率把几个高发点捋清，你照着对照排一遍，基本能把大部分接入故障在半小时内定位出来。

　　1、遇到ClassNotFoundException先回看代际是否混搭：Boot 3.5配Spring AI 1.0，或Boot 4配Spring AI 1.1，都属于典型混搭，先把版本回到README写明的对应关系再谈别的。

　　2、依赖拉不下来先检查仓库源：如果你用的是里程碑版或快照版，入门文档提到要加spring.io的milestone与snapshot仓库，同时还要注意Maven镜像的mirrorOf配置不要把spring快照仓库挡掉。

　　3、版本漂移问题用BOM收口：团队里有人手动在子模块写了某个AI组件的版本号，很容易把BOM托底打穿，建议统一只在父工程导入spring-ai-bom，子模块只写artifactId不写version，先把依赖树稳定住再优化功能。

　　4、升级前先看升级说明再动手：Spring AI升级说明里会记录依赖管理基线变化与API改动点，你从1.0升1.1或从1.x升2.x之前，把对应版本的升级说明扫一遍，能提前避开不少编译期报错。

　　总结

　　把Spring AI接进Spring Boot，优先做对版本代际选择，然后用spring-ai-bom锁依赖组，再按模型提供方加对应starter与配置项，最后用一条最短调用链验证闭环。这样做的好处是问题范围很小，出错也好定位，后续再叠加向量库、工具调用与观测链路会更顺。