Spring AI 2.0 开发Java Agent智能体：阿里云百炼大模型平台接入与 API Key 配置实战

1. Spring AI 2.0 里接百炼为什么总在配置这一步卡住Spring AI 2.0 把 Java 侧的模型调用抽象成了ChatModel、EmbeddingModel这类接口写业务代码时确实清爽但真正落到「阿里云百炼大模型平台接入」这个环节很多人第一次跑会卡在几个很具体的地方依赖坐标选错、base-url和completions-path拼不对、API Key 塞进环境变量后读不到、模型名写成了控制台里的展示名而不是调用名。这些都不是概念问题是配置问题。这篇就聚焦配置这一层。目标很明确让你在 Spring Boot 工程里用 Spring AI 2.0 的 OpenAI 兼容方式接上百炼的模型端点写一个能跑起来的 Java Agent 骨架并且知道每一步为什么这么写。适合已经在写 Java、想给工程加一个大模型能力、但还没打通调用链的开发者。读完之后你应该能自己复制配置、启动服务、发一个请求拿到模型回复出错了也知道去哪查。需要先说明一个前提百炼平台本身提供 OpenAI 兼容的接口所以 Spring AI 里可以直接用spring-ai-openai这个 starter把base-url指向百炼的兼容端点即可不需要为它单独找什么特殊 SDK。理解这一点后面的配置就顺了。2. 前置准备Key、端点与统一通道2.1 百炼侧要拿到的东西在百炼控制台里你需要确认三样东西API Key、模型调用名、兼容端点地址。API Key 在密钥服务里创建创建时选好归属账号创建完只显示一次记得当场复制。模型调用名不是控制台里那个中文展示名而是类似qwen-plus、qwen-turbo这样的英文标识在模型列表或文档里能看到。兼容端点一般是https://dashscope.aliyuncs.com/compatible-mode/v1这种形式Spring AI 的 OpenAI starter 会在这个地址后面拼/chat/completions。这里有个容易忽略的点百炼新账号通常有免费额度建议在用量页面把「免费额度用完即停」打开避免调试阶段不小心跑超。这个开关不影响你写代码但影响你调试时的心态。2.2 用统一 Key/API 通道做调用验证实际开发里经常遇到一个情况手上不止一个模型平台Key 散落在各处切换环境时改配置改到烦。这时候可以用一个统一的 Key/API 通道来收敛比如 TaoToken 提供的通道官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。它的作用是让你用一套 Key 和一套 base-url 去访问不同模型Spring AI 侧只需要改模型名不用动连接配置。对这篇的场景来说它的价值在于你可以先用统一通道把 Spring AI 的调用链跑通确认依赖、Bean、请求格式都没问题再决定生产环境是直连百炼还是走通道。排障的时候这一点特别有用因为变量少了。如果你要管理多个 Key可以在控制台里创建和查看https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。Key 的创建入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这些先了解即可下面进入代码。3. 可复制的依赖与 Bean 配置3.1 Maven 依赖Spring AI 2.0 的 starter 命名和 1.x 有差异建议用 BOM 统一版本避免各个 starter 版本打架。下面是一个最小可用的依赖片段dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version2.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies注意 artifactId 是spring-ai-starter-model-openai不是老版本的spring-ai-openai-spring-boot-starter。这个改名是很多人第一次跑报「找不到 Bean」的根因依赖没进来自动配置自然不会生效。3.2 application.yml 配置骨架配置文件里要写清楚 base-url、api-key、模型名和 completions 路径。直连百炼的写法大致如下spring: ai: openai: base-url: https://dashscope.aliyuncs.com/compatible-mode api-key: ${BAILIAN_API_KEY} chat: options: model: qwen-plus temperature: 0.7 embedding: options: model: text-embedding-v3如果你走统一通道把base-url换成https://taotoken.net/apiapi-key换成通道里创建的 Key模型名按通道支持的写即可。这样切换时只动这几行业务代码零改动。关于base-url有个坑要提前说Spring AI 的 OpenAI 客户端会在base-url后面自动拼/v1/chat/completions或/chat/completions具体拼哪个取决于版本和配置。百炼兼容端点的完整路径是.../compatible-mode/v1/chat/completions所以base-url写到.../compatible-mode就够了不要再手动加/v1否则会变成/v1/v1/...直接 404。这个错误非常常见排查时先看拼接后的完整 URL。3.3 用环境变量而不是硬编码API Key 不要写死在 yml 里。上面用了${BAILIAN_API_KEY}启动前设置环境变量export BAILIAN_API_KEYsk-你的keyWindows 下用set BAILIAN_API_KEYsk-你的key或者在 IDE 的 Run Configuration 里配 Environment variables。如果读不到先确认变量名拼写和大小写Spring 的占位符解析对大小写敏感。3.4 声明一个 ChatClient BeanSpring AI 2.0 推荐用ChatClient而不是直接操作ChatModel前者封装了对话记忆、Advisor 这些能力写 Agent 更顺手。一个基础 BeanConfiguration public class AiConfig { Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder .defaultSystem(你是一个 Java 技术助手回答简洁准确。) .build(); } }ChatClient.Builder由 starter 自动配置注入你不需要手动 new。如果启动时报「找不到 ChatClient.Builder」八成是依赖没引对回到 3.1 检查 artifactId。4. 发一个请求验证链路4.1 写一个最小 Controller配置完先别急着写复杂 Agent用一个最简单的接口验证链路通不通RestController RequestMapping(/ai) public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient chatClient) { this.chatClient chatClient; } GetMapping(/chat) public String chat(RequestParam String message) { return chatClient.prompt() .user(message) .call() .content(); } }启动服务然后请求curl http://localhost:8080/ai/chat?message用一句话解释什么是Java Agent如果返回了一段模型生成的文本说明依赖、配置、Key、端点全部打通。这一步是整个接入过程的分水岭过了这步后面加工具调用、加 RAG 都是在这个基础上叠。4.2 用统一通道做交叉验证如果直连百炼报错但你不确定是 Key 问题、端点问题还是代码问题可以临时把base-url和api-key换成统一通道的配置再发一次同样的请求。如果通道能通、直连不通问题就在百炼侧的 Key 或端点如果两边都不通问题在代码或依赖。这种交叉验证能帮你快速缩小范围比盯着日志猜快得多。想单独验证模型本身是否可用也可以直接在模型对话页面发一条消息试试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。这一步不涉及代码纯粹确认 Key 和模型名对不对。4.3 加一点 Agent 味道工具调用链路通了之后可以试一下 Spring AI 2.0 的工具调用这是 Java Agent 的核心能力之一。定义一个简单工具public class TimeTools { Tool(description 获取当前服务器时间) public String currentTime() { return LocalDateTime.now().toString(); } }在调用时注册进去String answer chatClient.prompt() .user(现在几点了) .tools(new TimeTools()) .call() .content();模型会判断是否需要调用这个工具需要的话 Spring AI 会自动完成调用并把结果回填给模型。这一步能跑通说明你的 Agent 骨架已经具备扩展能力了。5. 本篇常见错误排查5.1 404 或路径重复最常见的报错是 404日志里能看到请求 URL 变成了.../compatible-mode/v1/v1/chat/completions这种重复路径。原因是base-url里多写了/v1。解决方法是把base-url收敛到域名加兼容前缀让客户端自己拼版本号和路径。改完重启再看日志里的实际 URL。5.2 401 或 Key 无效401 一般是 Key 没读到或者 Key 本身无效。先确认环境变量是否在当前 shell 或 IDE 里生效可以在启动类里临时打印一下System.getenv(BAILIAN_API_KEY)看是否为 null。如果 Key 是从控制台复制的注意有没有多复制空格或换行。另外Key 创建后如果归属账号选错也可能导致无权限。5.3 模型名不存在报「model not found」通常是模型名写错了。百炼控制台里显示的可能是中文名或带版本的展示名但调用时要用英文标识。去模型列表里确认调用名或者查一下文档里对应模型的 model 字段。不同模型支持的参数也不同比如有些模型不支持temperature传了会报参数错误。5.4 Bean 注入失败启动时报NoSuchBeanDefinitionException: ChatClient.Builder基本是依赖问题。检查spring-ai-starter-model-openai是否真的进了 classpath可以用mvn dependency:tree | grep spring-ai看一下。如果用的是 Gradle检查 implementation 有没有写对。还有一种情况是 BOM 版本和 starter 版本不匹配统一用 BOM 管理就不会有这个问题。5.5 超时或连接失败如果请求卡住然后超时先确认网络能访问到端点地址。可以在服务器上直接 curl 一下base-url对应的域名看能不能通。如果是走统一通道确认 API 地址写的是https://taotoken.net/api而不是官网首页。连接类问题优先排查地址和网络不要一上来就怀疑代码。6. 接下来怎么走链路通了之后下一步通常是两件事一是把对话记忆加上让 Agent 能记住上下文二是接 RAG让模型能基于你的私有文档回答。Spring AI 2.0 对这两块都有现成支持Advisor 模式可以挂载记忆和检索逻辑不用自己从头写。如果你打算长期做 Java Agent 开发建议把模型调用层再抽象一层业务代码只依赖ChatClient底层用哪个平台通过配置切换。这样以后换模型、加通道、做灰度都不用动业务逻辑。需要管理多个 Key 和通道时控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果是做长期编码类 Agent可以了解一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后留一个我调试时的小习惯每次改完配置先只发一个最简单的「你好」请求确认链路通再去测复杂功能。这样出问题时你能确定是配置问题还是业务逻辑问题省掉很多来回猜的时间。