Spring AI 开发前必须搞定的 Maven 依赖与环境配置指南

刚把 Spring AI 的项目拉起来，第一件让我头疼的事不是写代码，而是 Maven 依赖怎么都下不全。pom.xml 里明明就写了几个 starter，reload 后 IDEA 的依赖列表里一片红色，要么是spring-ai-openai找不到，要么是下载到一半就报错。很多刚接触 Spring AI 的朋友都会卡在这一步，甚至误以为是代码问题，来回改配置改了半天，最后才发现是 Maven 环境本身没搞定。

这篇文章就专注解决 Spring AI 开发前期的这些事：为什么要用 Maven、Maven 环境怎么配才能在国内环境下顺畅下载依赖、创建工程时到底怎么选结构、不同模型平台（千问、本地 DeepSeek）要引哪些 jar 包，以及依赖下载失败时怎么一步步排查。给准备用 Spring AI 做 LLM 应用、但不想在环境问题上浪费时间的 Java 开发者一些可直接照做的方案。

1. 先把 Spring AI 前期的坑讲清楚:Maven为什么卡住了一大批人

1.1 Spring AI 是什么，前期准备到底要准备什么

Spring AI 是 Spring 官方推出的 AI 应用开发框架，简单说，它把 Java 对接大模型（LLM）的流程标准化了。以前你想在 Java 项目里调用一个聊天模型，得自己封装 HTTP 请求、处理流式响应、维护对话上下文，不同模型平台的参数格式还不一样。Spring AI 提供了一套统一的ChatModel/ChatClient接口，接 OpenAI、通义千问、DeepSeek、Ollama 都走同样的代码模式，另外还内置了向量存储、提示词模板、结构化输出、Tool Calling、RAG 这些 AI 应用里高频用到的能力。它解决的核心问题是：让 Spring Boot 开发者用熟悉的编程习惯去写 AI 应用，而不是被迫学一套新的工具链。

既然是基于 Spring Boot 的框架，前期开发就绕不开三个准备环节：JDK 环境（Spring AI 要求 JDK 17+）、Maven 构建环境、以及第三方依赖的下载通道。前两个属于老生常谈，最折磨人的是第三点。Spring AI 的依赖在 Maven 中央仓库里确实都能找到，但对国内开发者来说，直接拉取中央仓库的体验相当不稳定，依赖体积大、连接超时、下载到一半卡住，这些每天都在发生。很多人就是死在这一步，代码写得很顺，偏偏环境搭不起来。

1.2 Maven 在 Spring AI 开发里到底干了什么

Maven 的核心作用可以概括为一句话：它是 Java 项目的"依赖管家+构建工具"。如果你没有接触过它，可以把它想象成手机的应用商店，你只需要在 pom.xml 里声明需要什么依赖，Maven 会自动从仓库里下载 jar 包、管理版本、帮你完成编译打包测试的全流程。它把"我需要 spring-ai-openai 这个库"写成配置，剩下的下载路径、版本选择、冲突仲裁都由 Maven 处理，不用你手工把 jar 包往项目里塞。

在 Spring AI 项目里，Maven 承担的职责会比普通项目更重一些。Spring AI 的模块数量很多，从模型接入、向量存储到 Agent 工具链，依赖关系错综复杂。如果只引入一个 starter，Maven 的传递依赖机制会自动拉取它依赖的十几个底层库，比如 Spring Framework 核心、Jackson、Spring Retry 等。一旦某个传递依赖没拉下来，后面所有编译都会失败。所以理解 Maven 是怎么解析、下载、缓存依赖的，对排查 Spring AI 的依赖问题非常关键。

1.3 Spring AI 版本演进对依赖管理的直接影响

很多人在查资料时发现，有的博客让你引spring-ai-core，有的让你引spring-ai-starter-model-openai，还有的提到spring-ai-alibaba，这是因为 Spring AI 的模块命名和版本策略一直在变。早期 0.8.x 阶段，模型客户端的 starter 用得比较多；1.0 正式版发布后，模块划分趋向稳定，官方主推spring-ai-starter-model-*这一系列的 starter，并且强烈建议通过 BOM（Bill of Materials）统一管理版本号。

BOM 是 Maven 里的一种特殊 pom，它不直接提供依赖，而是集中声明一组依赖的版本。你引入 BOM 后再写 Spring AI 相关依赖时就不用写 version 了，Maven 会自动按 BOM 中的版本号解析。这一步看起来麻烦，实际上能帮你避开大量版本冲突。如果你自己在 0.8.x、1.0.0-M6、2.0.0-M1 这些版本号里手动挑一个填进去，很容易选到不兼容的组合。这也是为什么身边越来越多推荐新项目直接用 Spring Initializr 生成，因为它的依赖版本是官方验证过的组合。至于 2.0，目前整体处于迭代期，核心 API 仍在调整，生产项目建议优先使用 1.x 的最新稳定版，至少文档和社区方案都是齐的。

2. 开发环境准备：JDK、Maven 安装与全局配置

2.1 版本选型：JDK 17+ 与 Maven 3.9.x

先确认底线：Spring AI 1.x 基于 Spring Framework 6 构建，Spring Framework 6 的最低要求是 JDK 17，所以你装的 JDK 不能低于 17。我建议直接用 JDK 21，因为 JDK 21 是 LTS 版本，Spring AI 的很多示例和文档默认也是跑在 21 上的，性能和对虚拟线程的支持都更完整。用老项目里的 JDK 8 来跑 Spring AI，会在编译阶段直接报UnsupportedClassVersionError或invalid source release，不用怀疑是 Maven 的问题。

Maven 本身选 3.8.x 或 3.9.x 都可以，3.9 系列目前稳定度很高，建议直接上 3.9.9。有一个容易忽略的兼容性点：Maven 自身运行也需要 JDK，如果你的机器上有多个 JDK，要确保 Maven 使用的 JDK 是 17+。这个可以通过检查JAVA_HOME环境变量和mvn -version输出里的 Java version 字段来确认。很多离奇的问题，比如 Maven 明明装了却报Unsupported major.minor version，根源就是 Maven 跑在了一个老 JDK 上。

2.2 Maven 下载、环境变量配置与命令行验证

Maven 本身是一个绿色软件，不涉及安装过程，下载后解压到一个目录就能用。官方下载入口是 Maven 官网的 download 页面，找到apache-maven-3.9.9-bin.zip这种格式的压缩包。我个人的习惯是解压到一个不含中文、不含空格的路径，比如D:\DevTools\apache-maven-3.9.9，Windows 下尤其要注意，路径里的中文可能导致某些插件解析异常。

接下来配置环境变量。Windows 上新增一个MAVEN_HOME指向解压目录，然后在Path变量里追加%MAVEN_HOME%\bin；macOS 或 Linux 上在~/.zshrc或~/.bashrc里写入export MAVEN_HOME=/opt/apache-maven-3.9.9和export PATH=$MAVEN_HOME/bin:$PATH。配置完打开新的终端，输入下面两行命令验证：

mvn -version

正常会输出 Maven 版本号、Java 版本号、系统环境信息。如果你在 IDEA 里只用内置 Maven 也能跑，但前期开发阶段我强烈建议装一个独立的 Maven，因为后面要改全局的 settings.xml 镜像配置，也方便在命令行直接执行mvn clean install这样的操作，排查问题更灵活。

2.3 一份可用的 settings.xml：镜像源、本地仓库、JDK 编译级别

Maven 的全局配置文件是conf/settings.xml，所有的下载源、本地仓库位置、代理配置都在这个文件里控制。Spring AI 项目依赖下载失败，九成问题出在这个文件配置不完整。下面是一份我在 Spring AI 前期开发里常用的基础配置：

<settings> <localRepository>D:/DevTools/maven-repository</localRepository> <mirrors> <mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror> </mirrors> <profiles> <profile> <id>jdk-21</id> <activation> <activeByDefault>true</activeByDefault> </activation> <properties> <maven.compiler.source>21</maven.compiler.source> <maven.compiler.target>21</maven.compiler.target> </properties> </profile> </profiles> </settings>

localRepository是本地仓库路径，Maven 下载的所有依赖都会缓存在这里。默认路径是~/.m2/repository，放在系统盘，时间长了体积会非常大，建议改到数据盘单独位置。mirrors里面定义的镜像源是解决下载问题的核心，mirrorOf写成*表示对所有仓库请求都走这个镜像，包括中央仓库和 Spring 的里程碑仓库。profiles里配置 JDK 编译版本，保证命令行构建时编译版本与 IDEA 里的 Project SDK 一致。

注意：镜像源配置后，首次构建 Spring AI 项目可能仍然会从"默认中央仓库"拉取少量不在镜像中的元数据，这是正常的。不要因为日志里出现Downloading from central就觉得配置没生效，判断标准是最终依赖都能成功下载。

2.4 多镜像源配置：阿里云、华为云、腾讯云与权重策略

单镜像源偶尔不够用，尤其高并发构建时，阿里云公共仓库偶尔会返回连接超时。后来我改用多镜像源配置，思路是在 settings.xml 里并列多个 mirror，比如华为云镜像、腾讯云镜像，但这里面有个细节：Maven 解析镜像时是按id匹配的，如果多个 mirror 的mirrorOf都写成*，只有第一个生效，后面的会被忽略。所以多镜像源不是简单倒进去就能用的。

比较推荐的做法是用阿里云镜像作为*兜底，再为特定仓库指定专用镜像。比如 Spring 的里程碑仓库和快照仓库，可以单独给它们配一个镜像地址，这样既不影响主仓库的下载效率，又能覆盖特殊依赖。还有一个思路是使用仓库分组服务，配置一个统一入口，但这需要域名支持，对大多数团队来说不用这么复杂。我在实战中的建议是：团队开发优先保证 settings.xml 在所有人之间保持一致，不要一个人用阿里云、一个人用默认源，否则一旦某人本地缓存的依赖不完整，问题会非常难排查。多镜像的正确打开方式是把仓库索引服务配好，而不是在每台机器上堆 mirror。

3. 创建 Spring AI 工程：从 archetype 到 IDEA 的 Maven 关联

3.1 项目怎么建：IDEA archetype 还是 Spring Initializr

新建项目时，IDEA 的 New Project 界面会问你选不选 Maven Archetype，有人在这里纠结选哪个 archetype。简单解释下：archetype 是 Maven 的项目模板，maven-archetype-quickstart是最基础的空 Java 项目模板，创建出来只有一个 main 方法和一个空的 pom.xml。如果你打算从零手写一个 Spring AI 项目，选这个没问题。

但实际操作中，我更推荐直接去 Spring Initializr 生成工程，在选择依赖时直接搜Spring AI相关的模块（比如 OpenAI、Ollama、Azure OpenAI，不同的 Spring Boot 版本对应不同的 Spring AI 模块），再选好 Spring Boot 版本，生成后下载解压，用 IDEA 打开。这样做的好处是，生成好的 pom.xml 里已经包含了官方推荐组合的依赖坐标和版本，不会出现 starter 版本互不兼容的问题。对于前期开发来说，少踩一个版本坑，比省一次下载时间更重要。如果你还是想走 IDEA 的 archetype 方式，就在 New Project 界面选择Maven Archetype，然后选org.apache.maven.archetypes:maven-archetype-quickstart，创建之后再去 Spring Initializr 上拷贝一个对应版本的 pom 进行覆盖，效果一样。

3.2 让 IDEA 使用你指定的 Maven 与 settings.xml

IDEA 默认自带一个 Maven，也会用默认的~/.m2/settings.xml。如果你已经按照上一节的内容装好了独立 Maven 并写好了 settings.xml，就需要告诉 IDEA 用它。打开 IDEA 的设置（Settings -> Build, Execution, Deployment -> Build Tools -> Maven），看到三个关键配置：

• Maven home path：选择你本地安装的 Maven 目录，比如D:\DevTools\apache-maven-3.9.9。
• User settings file：勾选 Override，然后选择你的 settings.xml 路径。
• Local repository：这里会自动读取 settings.xml 里的localRepository，如果没有自动识别，手动填上同样路径。

这三项配置完，点 Apply，然后打开右侧的 Maven 面板，点一次 Reload All Maven Projects。这里我吃过一个亏：只改了Maven home path，却忘了改User settings file，结果 IDEA 还是使用默认设置，镜像源配置没生效，依赖照样下载失败。所以一定要逐个确认这三个位置的路径都对得上。另外，如果你之前已经用 IDEA 内置 Maven 打开过项目，本地仓库里可能会缓存部分失败的.lastUpdated文件，建议切换 Maven 后顺手清理一下再重载。

3.3 pom.xml 引入 Spring AI 依赖：BOM 与 starter 坐标

Spring AI 依赖管理的特殊之处在于官方的 BOM 很关键，你可以理解成它是所有 Spring AI 模块版本的"总表"。正确做法是先在<dependencyManagement>里引入spring-ai-bom，然后再去写具体的依赖。下面是接入 OpenAI 兼容接口（比如用于 DeepSeek）时需要的最小依赖配置：

<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-openai</artifactId> </dependency> </dependencies>

注意点有两个。第一，不引入 BOM 的情况下，你必须给每个 Spring AI 依赖手动写<version>，而手写版本就很容易错；第二，Spring AI 1.x 需要配合 Spring Boot 3.4.x/3.5.x 使用，不要拿 Spring Boot 2.x 试，编译会直接失败。引入依赖后点 Reload，能看到 Maven 面板里出现一长串传递依赖，这说明依赖关系已经解析成功。如果你的模型是通义千问，就把spring-ai-starter-model-openai换成spring-ai-starter-model-dashscope，原理一样，只是底层请求的 API 格式不同。

3.4 第一次执行 mvn clean install 的完整过程

依赖在 IDEA 里显示正常，不代表命令行构建也正常。项目前期，我会习惯性在项目根目录执行一次完整构建，这样能把 IDEA 隐藏的问题暴露出来：

mvn clean install -DskipTests

这个过程会依次执行 clean（清空 target 目录）、compile（编译 Java 源码）、test（跳过）、package（打包）、install（安装到本地仓库）。第一次执行时，Maven 会下载大量插件和依赖，耗时比较长，如果 settings.xml 的镜像配置正确，日志里能看到Downloading from aliyunmaven这样的字样，下载速度会快很多。如果在这里看到Downloading from central并且速度很慢，基本可以确定镜像没有生效，回去检查mirrorOf和 settings.xml 是否被命令行 Maven 读到。

这个过程中还有一个容易踩的坑：如果 pom.xml 里的 Spring AI 依赖version被注释掉但 BOM 写错，Maven 会在编译阶段报dependencies.dependency.version is missing。解决方式是回头检查 BOM 的groupId、artifactId和version是否完全匹配官方文档。依赖全部下载完成后，target/classes 里会生成编译好的 class 文件，这说明 Spring AI 前期的依赖问题已经基本过关。

4. Spring AI 核心接入：千问平台与本地 DeepSeek 的依赖与配置

4.1 需要引哪个 jar 包：不同接入方式对应的依赖选择

很多人一开始最困惑的就是"我该引哪个 jar"。其实选依赖的逻辑很简单：模型用什么协议，就选对应的 starter。Spring AI 把主流的模型接入方式分类了：

核心判断依据是端点服务的协议格式。如果你在本地用 Ollama 跑了一个 qwen 模型，Ollama 提供的是兼容 OpenAI 的接口，那你照样可以用spring-ai-starter-model-openai，只需要在配置里把 base-url 指向 Ollama 的地址。反过来说，如果接的是阿里云百炼平台，因为它的兼容端点也支持 OpenAI 格式，所以你可以用 dashscope 的 starter 拿更完善的官方整合，也可以用 openai 的 starter 配合对应 base-url，两个方案都能跑通。前期开发就选一个最稳定的路径：百炼选 dashscope，其他统一先试 openai 的 starter。

4.2 对接千问平台（DashScope）的依赖与最小配置

接千问平台时，最省心的方式是引入spring-ai-starter-model-dashscope。在 application.yml 里做最小配置：

spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY} base-url: https://dashscope.aliyuncs.com/compatible-mode/v1

然后在代码里注入ChatModel或者用ChatClient直接发起对话：

@RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient = builder.build(); } @GetMapping("/chat") public String chat(String message) { return chatClient.prompt(message) .call() .content(); } }

这里要说明一下：ChatClient是 Spring AI 1.0 起推荐使用的门面类，它封装了对ChatModel的调用、消息组装、流式响应等操作，日常开发都建议直接面向ChatClient编程。用 dashscope starter 的好处是，阿里云官方对百炼平台的支持比较完整，模型名直接填qwen-plus、qwen-max这类就行，不存在模型名映射问题。API Key 从百炼控制台获取，建议放到环境变量里，不要硬编码在 yml。

4.3 对接本地部署的 DeepSeek：OpenAI 兼容端点方案

本地部署的 DeepSeek 目前最常用的部署方案是 vLLM、SGLang 或 Ollama，这些服务一般都会暴露一个http://localhost:8000/v1的 OpenAI 兼容端点。Spring AI 项目接上去，引的依赖反而比千问还简单，直接用spring-ai-starter-model-openai：

spring: ai: openai: base-url: http://localhost:8000/v1 api-key: dummy-key chat: options: model: deepseek-chat

api-key 填个占位符就行，因为本地服务不会校验真实 Key。这里有个细节需要注意：如果你的本地服务不是跑在默认的 8000 端口，或者 Ollama 的 OpenAI 兼容端点实际是http://localhost:11434/v1，那就要在 base-url 里写全。很多人初次对接失败，就是因为在 Ollama 里只填了 11434 端口，忘了补/v1后缀，Spring AI 会把请求拼到http://localhost:8000/chat/completions，跟实际路径对不上，自然返回 404。接好后，用前面的ChatClient代码直接就能打通本地 DeepSeek，对话和流式响应都会走本地模型，调试速度和隐私体验都很好。

4.4 依赖冲突诊断：mvn dependency:tree 的实战用法

Spring AI 项目依赖复杂，偶尔会碰到版本冲突。比如你用了一个内部组件，它依赖低版本的 Spring Framework，而 Spring AI 需要更高版本，最后抛出一堆NoSuchMethodError或ClassNotFoundException。排查这类问题，Maven 自带的 dependency 插件非常有用：

mvn dependency:tree -Dincludes=org.springframework:spring-core

执行后，Maven 会打印出 Spring Core 在工程里的完整依赖树，哪个依赖引入了哪个版本一目了然。看到有多个版本，就在 pom.xml 里用<dependencyManagement>强制统一版本，或者在冲突的依赖上用<exclusions>排除低版本。我在接 DeepSeek 时还遇到过一次 Jackson 版本冲突，日志里反复提示InvalidDefinitionException，最后也是靠 dependency:tree 定位到某个工具库引入了旧版 jackson-databind，直接排除掉才解决。

经验：不要一报冲突就加 exclusions，应该先把 dependency:tree 的结果看全，确认到底是谁引入的、影响哪个传递链，再从根上处理。盲删依赖有时会让其他地方出问题。

5. Maven 依赖下载问题排查实录：从爆红到跑通的常见问题速查

5.1 高频报错与解决方案速查表

前期开发里碰到的问题基本就那么几类，我把最常遇到的整理成了一张速查表，遇到问题先对着找。这张表是我在实际项目里反复踩坑总结出来的，不敢说覆盖 100%，但覆盖 Spring AI 前期依赖问题的 90% 还是没问题的。

这张表里最容易被忽略的是.lastUpdated文件，因为 IDEA 的重载按钮有时候不够智能，遇到了最好手动删一次再mvn -U。

5.2 .lastUpdated 文件和 -U 强制更新的原理与使用

如果你在本地仓库里翻过依赖目录，会看到大量以.lastUpdated结尾的文件。这是 Maven 下载失败后留下的标记，里面记录的是错误信息模板。问题在于：只要.lastUpdated存在，Maven 在接下来的一段时间内会直接认为该依赖下载失败，不再尝试重新下载。这就是为什么你明明改了镜像源、删了 pom 重新 Reload，依赖列表还是红的——本地仓库里堆着失败的旧标记，Maven 到期前根本不重新拉取。

解决方式是执行强制更新命令，让 Maven 忽略.lastUpdated：

mvn clean install -U -DskipTests

-U参数的全称是--update-snapshots，会强制检查 SNAPSHOT 依赖和新版本。在 Spring AI 开发阶段如果经常改换版本，这个命令几乎必用。还有更省事的做法：手动清理本地仓库里的失败文件：

# Windows PowerShell Get-ChildItem -Path "$env:USERPROFILE\.m2\repository" -Filter "*.lastUpdated" -Recurse | Remove-Item # macOS / Linux find ~/.m2/repository -name "*.lastUpdated" -delete

删完再执行mvn -U clean install，依赖大概率就能断点续传一样重新下载完整。需要提醒的是：不要动不动就把整个本地仓库删掉重下，那样代价非常大，只需要清理失败文件，Maven 会按需重新下载缺失的部分。

5.3 公司内网、私服与离线环境下的下载问题处理

团队开发时，很多人面临的是公司内网环境，不能直接访问公共仓库。这时 settings.xml 的镜像地址要指向公司内部的 Nexus 私服或 Artifactory，配置方式与阿里云镜像一致：

<mirror> <id>internal-nexus</id> <mirrorOf>*</mirrorOf> <url>http://nexus.internal.company.com/repository/maven-public/</url> </mirror>

访问私服一般需要账号密码，在 settings.xml 里配置<servers>节点，将私服 id 和对应用户名密码关联。另外一个常见问题是，公司已经用 Gradle 作为标准构建工具，新项目想用 Maven 就要单独维护一套依赖配置。这种情况下，可以考虑从已有 Gradle 依赖锁定文件中获取坐标版本，直接复制到 pom 里。离线环境最麻烦，如果有一台联网机器要先拉齐一套依赖，可以用mvn dependency:go-offline把全部依赖缓存好，再整体拷贝本地仓库到离线机器。这个方法对 Spring AI 这种依赖很多的框架特别有用，踩过一次坑后你就会养成"换环境先同步本地仓库"的习惯。

5.4 IDEA 里"爆红"的排查流程与正确重载姿势

IDEA 依赖爆红不一定代表着依赖真的缺失，有时只是 IDE 的索引没有同步。我总结了一套固定的排查流程，可以帮你少走很多弯路：

1. 先看 Maven 面板里对应的模块是否有图标异常，比如带红色波浪线、Dependencies列表里有not found字样。
2. 打开项目根目录的pom.xml，看依赖是否被 IDEA 解析，IDEA 通常在 Maven 面板和 pom 编辑区都会显示同步状态。
3. 点工具栏上的Reload All Maven Projects（蓝色刷新图标），等右下角进度条跑完。
4. 如果还是红，执行mvn -U clean install看日志，重点看哪个依赖报错。
5. 清理本地仓库失败文件，重复第 3 步。

特别要注意的是，不要反复点 Reload 按钮，一次没加载完就再点一次，这样只会加剧本地仓库的并发问题。正确姿势是先把 Maven 的错误日志调出来，日志里会明确告诉你缺的是哪个坐标、从哪里下载失败，照着错误走比盲试快得多。

6. 前期开发进阶：Spring AI 2.0、Skill 机制与 Admin 控制台

6.1 Spring AI 2.0 前后功能演进与版本选择建议

Spring AI 1.0 在 2025 年正式 GA 之后，社区和公司的采用速度明显加快，而 2.0 已经进入大家的视野。2.0 最主要的演进方向包括更稳定的 API 抽象、更强的模型互操作性、以及更成熟的 Agent 开发框架。但对你前期开发来说，版本选择的建议很明确：如果目标是快速验证业务，用 1.x 最新稳定版；如果目标是跟进最新特性且愿意承担 API 变动风险，可以单独开分支尝试 2.x 里程碑版本，不要直接用在核心项目里。

Spring AI 2.0 的 API 变动比较大，我在迁移一个内部项目时，就碰到过把ChatClient的 builder 方法拆成了更细粒度的配置类，旧代码里chatClient.prompt()的链式调用在新的 API 下会报编译错误。这类迁移成本，前期开发阶段完全是浪费，所以我的经验是：先锁定 1.x 稳定版，把环境跑通，等 2.0 正式版文档齐了再做升级评估，这个策略比盲目追新靠谱得多。

6.2 Skill 机制：从依赖 ChatModel 到自定义工具能力

Spring AI 里有一个很实用的机制叫 Skill，你可以把它理解成给模型准备的一个动作库。普通的ChatClient只是"你说一句我回一句"，而 Skill 让模型可以在回答过程中主动去调用外部函数——比如查数据库、调一个内部服务接口、读取某个日志文件——然后把结果作为上下文继续生成回答。这个机制在很多 Agent 场景里非常关键。

开发 Skill 的思路是写一个带注解的类，方法上定义清楚功能和参数。当你用 Maven 管理依赖时，要注意 Skill 相关扩展包有可能是单独的模块，比如spring-ai-agent-executor或者spring-ai-skills，具体依赖坐标随版本变化较大。这一块的入门并不复杂，但建议先把模型对接调通，再引入 Skill，否则模型对话还没通的时候引入它，出现报错你会分不清是 Skill 问题还是底层依赖问题。

6.3 Spring AI Alibaba Admin 的本地部署思路

Spring AI Alibaba 是阿里在 Spring AI 之上做的一套面向生产场景的扩展，它提供了 DashScope 的深度集成、RAG 组件、Agent 执行器，还有一个叫 Spring AI Alibaba Admin 的可视化管理控制台。不少人在前期开发里就想着把它部署起来，方便观察模型调用日志和 Token 消耗。这里给一个务实的建议：先用 Docker 把 Admin 拉起来看效果，用docker run加几个环境变量就能启动，但前提是你的模型通过 Spring AI Alibaba 的 starter 接入，Admin 才能采集到调用数据。

依赖上有两点需要注意。第一，spring-ai-alibaba-starter和spring-ai-starter-model-dashscope不要混引，否则会出现重复的 Bean 定义，启动时直接报错。第二，Admin 部署时的端口、数据库配置要提前规划，不要默认端口和业务服务撞车后，再把问题赖到依赖上。前期开发想快速看到端到端效果，本地部署 Admin 是一个不错的加分项，但它不是你发模型的必要前提，先跑通ChatClient对话再考虑运维设施会顺畅得多。

最后分享一点实际操作里的经验

很多人感觉 Spring AI 入门难，不是因为模型 API 复杂，而是前期开发环境里 Maven 依赖反复出问题，一遍遍重试把耐心耗光了。我自己也经历过反复删除本地仓库、重新加载项目、再遇到新的版本冲突这样的死循环，最后慢慢养成了一套习惯：先统一 JDK 和 Maven 版本，再配置好镜像，然后严格走 BOM 管理依赖，最后再写任何业务代码。这套流程走完，后面搭模型对接基本一路绿灯。

一个小建议：把mvn -U clean install记成肌肉记忆，很多黑盒问题都能通过它暴露出来。Spring AI 本身是一个够新也够活的框架，版本迭代速度比传统框架快得多，前期能稳定地把依赖控制在一个固定版本上，是后面所有 AI 功能开发的地基。希望这篇文章能帮你把这块地基打牢。