1. 为什么 Java 后端需要 ChatClient 统一接入很多 Java 团队在 2024 年之后都遇到同一个尴尬产品经理说“加个 AI 对话”你打开 IDE 却发现要面对 OpenAI、通义、混元、DeepSeek 各家 SDK字段名不一样、鉴权方式不一样、流式返回格式也不一样。更麻烦的是测试环境用一家、生产环境想换另一家代码里到处是if (provider.equals(...))。Spring AI 的定位就是解决这个问题。它把不同模型服务商的对话能力抽象成统一的ChatClient你写业务代码时只面向ChatClient编程底层换模型只改application.yml。这跟当年 SLF4J 统一日志门面是一个思路门面稳定实现可插拔。那 TaoToken 在这里扮演什么角色它是一个统一 API 通道对外暴露 OpenAI 兼容的/v1/chat/completions接口。也就是说Spring AI 的 OpenAI starter 只要把base-url指向 TaoToken就能用同一套ChatClient代码调用通道背后的多种模型。对 Java 开发者来说这意味着不用为每家模型单独写适配层密钥管理集中在一个地方方便轮换本地开发、测试、生产可以用同一份配置结构只改环境变量。适合谁看这篇有 Spring Boot 基础、能独立写RestController和Configuration、想在半天内跑通一次真实对话请求的后端同学。如果你还没写过 Spring Boot建议先把SpringBootApplication和依赖注入弄明白再回来。我试过在一个已有订单服务的项目里加 AI 摘要功能最省事的路径就是 Spring AI 统一通道下面把完整步骤拆开讲。2. TaoToken 前置准备与 Spring AI 依赖引入2.1 拿到 Base URL 和 API KeyTaoToken 的 API 入口是https://taotoken.net/api注意这个地址不带任何查询参数直接作为base-url使用。密钥需要到控制台创建路径是 API Keys 页面。创建时建议按环境命名比如spring-ai-dev、spring-ai-prod方便后续排查是哪个环境在调用。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspringai_chatclientAPI Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspringai_chatclient创建完先复制保存页面关闭后通常不再完整显示。如果你只是想先验证模型能不能通也可以直接用模型对话页面手动发一条消息确认账号状态正常再写代码。模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspringai_chatclient2.2 确认 Spring AI 版本与 JDK 要求Spring AI 目前稳定线是 1.0.x要求 JDK 17 及以上Spring Boot 3.2。如果你项目还在 JDK 8需要先升级这不是本文能绕过的硬门槛。在pom.xml里加 BOM 管理版本避免各个 starter 版本打架dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement然后引入 OpenAI starter因为 TaoToken 兼容 OpenAI 协议所以用这个 starter 即可dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency注意 artifactId 在 1.0.0 之后从spring-ai-openai-spring-boot-starter改成了spring-ai-starter-model-openai如果你搜到的老教程用的是旧名字启动会报找不到 bean这是第一个常见坑。2.3 环境变量与密钥管理不要把 key 硬编码进application.yml提交到 Git。推荐用环境变量注入本地开发可以在 IDE 的 Run Configuration 里设置服务器上用 systemd 或 K8s Secret。命名建议TAOTOKEN_API_KEY下面配置里会引用它。3. 可复制的 application.yml 与 ChatClient 配置3.1 application.yml 完整片段这是核心配置直接复制改 key 即可。注意base-url结尾不要多加/v1Spring AI 的 OpenAI 客户端会自己拼/v1/chat/completions多写一层会变成/v1/v1/...导致 404。spring: ai: openai: api-key: ${TAOTOKEN_API_KEY} base-url: https://taotoken.net/api chat: options: model: gpt-4o-mini temperature: 0.7 max-tokens: 1024这里model填的是通道支持的模型 ID。如果你不确定当前账号能用哪些可以先在模型对话页面选一个确认可用再填进来。temperature控制随机性做客服问答建议 0.2~0.5做创意文案可以 0.8 以上。3.2 ChatClient Bean 配置类Spring AI 会自动装配一个ChatClient.Builder但直接注入 Builder 在每个类里 build 一次比较啰嗦。推荐写一个Configuration统一构建顺便设置系统提示词Configuration public class ChatClientConfig { Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder .defaultSystem(你是一个简洁的 Java 技术助手回答控制在三句话内。) .build(); } }defaultSystem是全局系统提示所有通过这个 ChatClient 发起的对话都会带上。如果你有多个业务场景需要不同人设可以建多个 Bean用Qualifier区分。3.3 Controller 调用示例写一个最简单的 GET 接口验证RestController RequestMapping(/ai) public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient chatClient) { this.chatClient chatClient; } GetMapping(/chat) public String chat(RequestParam String q) { return chatClient.prompt() .user(q) .call() .content(); } }注意 1.0.x 的 API 是chatClient.prompt().user(...).call().content()老教程里的chatClient.call(question)已经废弃编译不过。这是第二个高频坑。3.4 流式返回配置可选如果你要做打字机效果把.call()换成.stream()返回FluxStringGetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString stream(RequestParam String q) { return chatClient.prompt().user(q).stream().content(); }需要额外引入spring-boot-starter-webflux否则Flux无法序列化。SSE 场景下前端用EventSource接收即可。4. 启动后验证请求与成功结果4.1 启动项目用mvn spring-boot:run或 IDE 直接跑主类。启动日志里如果看到OpenAiChatModel初始化成功说明配置被读取了。如果报api-key must not be empty检查环境变量有没有真正传进 JVMIDE 里设置的环境变量有时不会自动继承到 Maven 插件。4.2 curl 验证先用 curl 排除 Spring 层的问题直接打通道curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句话解释什么是 Spring Boot}] }返回 JSON 里choices[0].message.content有内容说明通道和 key 都没问题。这一步能帮你快速区分是通道问题还是代码问题。4.3 调用本地接口curl http://localhost:8080/ai/chat?q用一句话形容Java预期返回类似“Java 是一门跨平台、面向对象的编程语言”。如果返回空字符串多半是模型 ID 写错或通道侧限流看下一节排查。4.4 观察日志确认模型在application.yml里把日志级别调一下能看到实际请求体logging: level: org.springframework.ai: DEBUG启动后调用一次控制台会打印请求的 URL 和 model 字段确认base-url拼接正确、model 是你要的那个。这一步对排查 404 特别有用。5. 本篇常见报错排查5.1 401 Unauthorized最常见。先确认TAOTOKEN_API_KEY环境变量在当前 shell 里echo $TAOTOKEN_API_KEY有值。如果 curl 能通但 Spring 报 401检查 yml 里是不是写成了api-key: TAOTOKEN_API_KEY少了${}那样会把字面量当 key 发出去。5.2 local proxy failed / Connection refused这个报错通常出现在你本机配了 HTTP 代理而 Spring 的 RestClient 默认会读http_proxy环境变量。解决办法是在启动参数里加-Dhttp.proxyHost -Dhttp.proxyPort清空或者检查 IDE 的代理设置。注意这里说的是本机网络配置问题不是通道本身的问题。5.3 reading choices 为空 / NullPointerException返回 200 但choices是空数组一般是 model ID 不被通道支持。把 model 换成模型对话页面里确认可用的那个再试。另外max-tokens设成 0 也会导致空返回检查配置。5.4 OAuth / invalid_client如果你误用了需要 OAuth 的端点会报这个。TaoToken 的 API 走 Bearer Token不需要 OAuth 流程。确认base-url是https://taotoken.net/api不要写成带/oauth的地址。5.5 三件套对照表出现配置类问题时按这张表逐项核对配置项正确值常见错误Base URLhttps://taotoken.net/api多写/v1或漏写httpsAPI Key控制台创建的sk-开头字符串写成环境变量名没加${}Model ID模型对话页确认可用的 ID凭记忆填了不存在的模型如果你用的是 Claude Code 或 Cline 这类工具配置逻辑一样Base URL 填https://taotoken.net/apiKey 填创建的密钥Model ID 填确认可用的模型。三者缺一不可少一个就会在启动或首次请求时报错。6. 下一步从跑通到用起来跑通一次对话只是起点。接下来你可以做三件事第一把ChatClient注入到现有 Service 里给订单、工单加自动摘要第二用ChatMemory做多轮对话Spring AI 提供了InMemoryChatMemory几行代码就能让机器人记住上下文第三如果要做长期编码或 Agent 类任务可以了解 Coding Plan它更适合持续性的开发场景。Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspringai_chatclient接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspringai_chatclientAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspringai_chatclient最后留一个我踩过的坑temperature设太高时同样的 prompt 每次返回差异很大做单元测试会不稳定。测试环境建议固定 0生产再按场景调。