刚把 Spring AI 的项目拉起来第一件让我头疼的事不是写代码而是 Maven 依赖怎么都下不全。pom.xml 里明明就写了几个 starterreload 后 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 工具链依赖关系错综复杂。如果只引入一个 starterMaven 的传递依赖机制会自动拉取它依赖的十几个底层库比如 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并且强烈建议通过 BOMBill 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.9Windows 下尤其要注意路径里的中文可能导致某些插件解析异常。接下来配置环境变量。Windows 上新增一个MAVEN_HOME指向解压目录然后在Path变量里追加%MAVEN_HOME%\binmacOS 或 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 localRepositoryD:/DevTools/maven-repository/localRepository mirrors mirror idaliyunmaven/id mirrorOf*/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors profiles profile idjdk-21/id activation activeByDefaulttrue/activeByDefault /activation properties maven.compiler.source21/maven.compiler.source maven.compiler.target21/maven.compiler.target /properties /profile /profiles /settingslocalRepository是本地仓库路径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.xmlIDEA 默认自带一个 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 groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-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 把主流的模型接入方式分类了接入方式典型场景Maven 依赖OpenAI 兼容接口DeepSeek、本地 vLLM/Ollama 提供的 OpenAI 格式端点spring-ai-starter-model-openai阿里云百炼 DashScope通义千问系列、百炼上的开源模型spring-ai-starter-model-dashscopeOllama 本地模型本机跑小模型做开发调试spring-ai-starter-model-ollamaSpring AI Alibaba结合阿里云 AI 能力做 Agent、RAG、Admin 运维spring-ai-alibaba-starter核心判断依据是端点服务的协议格式。如果你在本地用 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 对接本地部署的 DeepSeekOpenAI 兼容端点方案本地部署的 DeepSeek 目前最常用的部署方案是 vLLM、SGLang 或 Ollama这些服务一般都会暴露一个http://localhost:8000/v1的 OpenAI 兼容端点。Spring AI 项目接上去引的依赖反而比千问还简单直接用spring-ai-starter-model-openaispring: ai: openai: base-url: http://localhost:8000/v1 api-key: dummy-key chat: options: model: deepseek-chatapi-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 -Dincludesorg.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% 还是没问题的。现象根本原因解决方案IDEA 依赖列表爆红Maven 面板找不到 spring-ai 相关依赖settings.xml 镜像配置没生效中央仓库下载超时检查 IDEA 的 User settings file 路径配置阿里云镜像后 Reload报 Cannot resolve org.springframework.ai:spring-ai-bomBOM 版本号手写错误到 Spring Initializr 或官方文档核对最新稳定版本下载到一半报 Transfer failed, solution: check remote repository网络不稳定镜像源不可用换备用镜像源华为云、腾讯云或使用内网私服地址.lastUpdated文件残留重新加载还是失败上次下载失败留下了错误缓存删除本地仓库的 lastUpdated 文件再执行mvn -U强制更新编译报 UnsupportedClassVersionErrorJDK 版本低于 17切换 JDK 到 17检查JAVA_HOME和 IDEA Project SDK启动报 No qualifying bean of type ChatClient缺少对应 starter 依赖或组件扫描没覆盖检查 pom 是否引入了正确的 model starter确认启动类的位置这张表里最容易被忽略的是.lastUpdated文件因为 IDEA 的重载按钮有时候不够智能遇到了最好手动删一次再mvn -U。5.2 .lastUpdated 文件和 -U 强制更新的原理与使用如果你在本地仓库里翻过依赖目录会看到大量以.lastUpdated结尾的文件。这是 Maven 下载失败后留下的标记里面记录的是错误信息模板。问题在于只要.lastUpdated存在Maven 在接下来的一段时间内会直接认为该依赖下载失败不再尝试重新下载。这就是为什么你明明改了镜像源、删了 pom 重新 Reload依赖列表还是红的——本地仓库里堆着失败的旧标记Maven 到期前根本不重新拉取。解决方式是执行强制更新命令让 Maven 忽略.lastUpdatedmvn 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 idinternal-nexus/id mirrorOf*/mirrorOf urlhttp://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 的索引没有同步。我总结了一套固定的排查流程可以帮你少走很多弯路先看 Maven 面板里对应的模块是否有图标异常比如带红色波浪线、Dependencies列表里有not found字样。打开项目根目录的pom.xml看依赖是否被 IDEA 解析IDEA 通常在 Maven 面板和 pom 编辑区都会显示同步状态。点工具栏上的Reload All Maven Projects蓝色刷新图标等右下角进度条跑完。如果还是红执行mvn -U clean install看日志重点看哪个依赖报错。清理本地仓库失败文件重复第 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 功能开发的地基。希望这篇文章能帮你把这块地基打牢。