1. 从零跑通 Spring AI Alibaba 对话 Demo 的真实场景如果你是一个写 Java 后端的开发者最近想在自己的项目里接一个大模型对话能力大概率会搜到 Spring AI Alibaba 这个框架。它把 Spring 生态那套依赖注入、自动配置、Advisor 拦截的玩法搬到了大模型调用上写起来确实顺手。但真正动手时第一个卡点往往不是代码而是配置application.yml里那个spring.ai.dashscope到底该填什么api-key从哪来endpoint 能不能换换完之后请求发出去返回的 JSON 长什么样。这篇内容就是解决这个问题的。我会带你从零搭一个能跑起来的 Spring AI Alibaba 对话 Demo重点放在application.yml里 DashScope endpoint 与 api-key 的可复制配置片段、Maven 依赖坐标、启动类代码最后用一次 curl 验证调用是否返回预期 JSON。整个过程控制在十分钟左右适合第一次接触 Spring AI Alibaba 的 Java 开发者。先说清楚这个 Demo 能做什么启动一个 Spring Boot 服务暴露一个/chat接口你传一句中文进去它返回模型生成的回复。适合谁有 Java 基础、用过 Spring Boot、想快速验证大模型接入链路的同学。不适合谁完全没写过 Spring Boot 的人建议先补一下RestController和application.yml的基本用法。我试过把 endpoint 指向 TaoToken 的兼容地址整个链路是通的返回结构和官方 DashScope 一致。下面按步骤来每一步都给可复制的代码和配置。2. TaoToken 前置准备拿到 Base URL 和 API Key在写代码之前先把两样东西准备好一个可用的 API Key一个正确的 Base URL。Spring AI Alibaba 的 DashScope starter 默认会去请求官方的 DashScope 地址但它的base-url是可配置的所以我们可以在application.yml里把它改掉。TaoToken 的 API 地址是https://taotoken.net/api这个地址就是我们要填进base-url的值。注意这里不要带任何多余的路径后缀Spring AI Alibaba 会自己在后面拼接/chat/completions之类的路径。如果你填成https://taotoken.net/api/v1很可能会拼出双份路径导致 404。API Key 的获取走控制台打开https://taotoken.net/console登录后在 API Keys 页面创建一个新的 Key。创建时建议给它起个能认出来的名字比如spring-ai-demo方便以后区分。Key 只在创建时完整显示一次复制下来存好后面要填进配置文件。这里有个小细节不要把 Key 硬编码进application.yml然后提交到 Git。正确做法是用环境变量。Windows 下可以这样设setx TAOTOKEN_API_KEY sk-你的keymacOS 或 Linux 下export TAOTOKEN_API_KEYsk-你的key设完之后重启一下终端用echo $TAOTOKEN_API_KEYWindows 用echo %TAOTOKEN_API_KEY%确认能打印出来。这样配置文件里写${TAOTOKEN_API_KEY}就能读到。如果你还想在浏览器里先验证一下 Key 能不能用可以打开模型对话页面https://taotoken.net/model-chat选一个模型发一句话能正常回复说明 Key 没问题。这一步能帮你排除掉后面一半的报错。3. 可复制配置pom.xml 依赖与 application.yml 片段这一节是核心所有配置都给完整片段你直接复制改 Key 就能用。先看 Maven 依赖。Spring AI Alibaba 的版本管理用 BOM这样各个 starter 的版本不会打架。在pom.xml的properties和dependencyManagement里加上properties java.version17/java.version spring-boot.version3.4.0/spring-boot.version spring-ai.version1.0.0/spring-ai.version spring-ai-alibaba.version1.0.0.3/spring-ai-alibaba.version /properties dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version${spring-boot.version}/version typepom/type scopeimport/scope /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-bom/artifactId version${spring-ai-alibaba.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement然后在dependencies里加核心 starterdependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter-dashscope/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency注意spring-ai-alibaba-starter-dashscope不需要写版本号BOM 已经管了。Java 版本要求 17 以上Spring Boot 3.4.0 对应的是 Spring Framework 6别用 JDK 8 去跑。接下来是application.yml这是整篇最关键的一段server: port: 888 spring: ai: dashscope: api-key: ${TAOTOKEN_API_KEY} base-url: https://taotoken.net/api chat: options: model: qwen-plus temperature: 0.7逐行解释一下。api-key读环境变量避免明文。base-url指向 TaoToken 的 API 地址这是把请求从默认 DashScope 切过来的关键。chat.options.model指定模型 ID这里用qwen-plus你也可以换成别的可用模型。temperature控制随机性0.7 是个比较平衡的值。如果你用的是application.properties格式等价写法是spring.ai.dashscope.api-key${TAOTOKEN_API_KEY} spring.ai.dashscope.base-urlhttps://taotoken.net/api spring.ai.dashscope.chat.options.modelqwen-plus两种格式选一种就行别混用。配置写完后Spring Boot 启动时会自动装配DashScopeChatModel这个 Bean你直接注入就能用。4. 启动类与 Controller写第一个可验证的对话接口配置好了现在写代码。先看启动类标准的 Spring Boot 入口package com.example.demo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }然后写一个 Controller暴露两个接口一个普通调用一个流式调用。普通调用返回完整字符串流式调用返回FluxString适合做打字机效果。package com.example.demo.controller; import lombok.RequiredArgsConstructor; import org.springframework.ai.chat.model.ChatModel; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import reactor.core.publisher.Flux; RequiredArgsConstructor RestController public class ChatController { private final ChatModel chatModel; GetMapping(/chat) public String chat(RequestParam String msg) { return chatModel.call(msg); } GetMapping(/stream/chat) public FluxString streamChat(RequestParam String msg) { return chatModel.stream(msg); } }ChatModel是 Spring AI 的核心接口call是同步阻塞stream是响应式流。这里注入的是DashScopeChatModel因为 starter 自动配置了它。RequiredArgsConstructor是 Lombok 的注解帮你生成构造器注入没装 Lombok 的话手写构造器也行。启动服务mvn spring-boot:run看到控制台打印Started DemoApplication就说明起来了。如果启动时报No qualifying bean of type org.springframework.ai.chat.model.ChatModel八成是api-key没读到检查环境变量是否生效。服务起来后用 curl 验证一下。这是整篇最关键的检查动作curl http://localhost:888/chat?msg用一句话介绍Spring%20AI%20Alibaba预期返回是一段中文文本类似Spring AI Alibaba 是阿里云推出的、基于 Spring AI 的 Java 框架用于快速接入通义千问等大模型能力。如果你想要更结构化的验证可以看流式接口curl -N http://localhost:888/stream/chat?msg你好-N参数关闭 curl 的缓冲你会看到文字一段段吐出来每段是 SSE 格式的data:行。这说明流式链路也通了。到这里第一条链路就跑通了。整个过程的核心就是base-url那一行配置把它指向 TaoToken 的 API 地址其余代码和官方示例完全一致。5. 常见报错排查401、local proxy failed、reading choices 怎么解跑通之后我把踩过的坑整理一下你遇到报错可以对照。报错一401 Unauthorized 或 invalid api key返回体里带code:InvalidApiKey或 HTTP 401。原因通常是api-key没读到或者 Key 本身失效。排查顺序先在终端echo $TAOTOKEN_API_KEY确认环境变量有值再确认application.yml里写的是${TAOTOKEN_API_KEY}而不是别的变量名最后去控制台https://taotoken.net/api-keys看这个 Key 是否被删了或者过期。注意 Key 前后不要有空格YAML 里冒号后面要有一个空格。报错二local proxy failed 或 connection refused这个报错说明请求根本没发出去卡在网络层。常见原因是base-url写错了比如写成了https://taotoken.net/api/带尾斜杠或者写成了http://而不是https://。还有一种情况是本地开了某些网络工具导致请求被劫持。先确认base-url是https://taotoken.net/api然后关掉本地不必要的网络软件再试。如果公司网络有出口限制换一个网络环境验证。报错三Error reading choices 或 JSON parse error请求发出去了返回也回来了但解析失败。这种多半是base-url指向了一个返回非标准结构的地址。Spring AI Alibaba 期望的响应结构里有choices数组如果返回的是 HTML 错误页或者别的 JSON 结构就会报这个。检查base-url是否精确等于https://taotoken.net/api不要多加/v1或/chat。另外确认model字段填的模型 ID 是真实存在的填错模型有时会返回非预期结构。报错四OAuth 或 token 相关错误如果你看到OAuth字样通常是把别的认证方式混进来了。Spring AI Alibaba 的 DashScope starter 用的是 API Key 认证不需要 OAuth 流程。确认你没有额外引入别的认证 starter也没有在配置里写spring.ai.dashscope.oauth之类的字段。报错五启动时 Bean 找不到No qualifying bean of type DashScopeChatModel说明 starter 没生效。检查pom.xml里spring-ai-alibaba-starter-dashscope是否真的加进去了以及dependencyManagement里的 BOM 是否 import 成功。有时候 IDE 没刷新 Maven执行一次mvn clean compile强制重新拉依赖。排查的时候有个通用技巧把日志级别调到 DEBUG在application.yml里加logging: level: com.alibaba.cloud.ai: DEBUG org.springframework.ai: DEBUG这样能看到请求的完整 URL 和响应体定位问题快很多。6. 继续深入从 Demo 到可用服务的下一步Demo 跑通只是起点。如果你打算把它用到实际项目里有几个方向可以继续。第一是加对话记忆。默认的ChatModel.call是无状态的每次请求都是独立的。要做多轮对话需要引入ChatMemory和MessageChatMemoryAdvisor把历史消息存起来。Spring AI Alibaba 提供了基于 JDBC 的记忆实现可以存到 MySQL。第二是加 Advisor 做统一处理。比如日志记录用SimpleLoggerAdvisor敏感词拦截用SafeGuardAdvisor这些都能在ChatClient.builder()时挂上去不用改业务代码。第三是流式接口的工程化。FluxString直接返回给前端时记得设置Content-Type: text/event-stream并且处理好客户端断开连接的情况否则容易泄漏连接。第四是模型切换。如果你需要在不同模型之间动态切换可以维护一个MapString, ChatModel根据请求参数选对应的模型再构建ChatClient。这在做 A/B 测试或者成本优化时很有用。如果你打算长期在编码场景里用这套能力可以了解一下 Coding Plan它针对代码补全、Agent 这类高频调用场景做了优化。地址是https://taotoken.net/coding-plan。最后提醒一句base-url和api-key这两项配置建议放在环境变量或配置中心里不要写死在代码仓库。Demo 阶段图方便可以写在application.yml上线前一定要改掉。接入文档在https://taotoken.net/doc遇到配置项不确定的时候去翻一下比搜索引擎靠谱。