1. Spring AI 1.x 是什么Java 开发者接入大模型的第一站Spring AI 1.x 是 Spring 官方推出的 AI 应用开发框架它把 Spring 生态里那套「可移植、模块化、约定优于配置」的设计思路搬到了大模型集成领域。简单说它想解决的问题是以前你在 Spring Boot 里调一个大模型得自己写 HTTP 客户端、拼 JSON、处理流式返回、管理重试现在这些都被抽象成了ChatClient、Advisor、ToolCallback这些接口你只需要注入、调用、拿结果。它适合谁适合已经熟悉 Spring Boot、手里有现成 Java 服务、想把对话、RAG、工具调用这些能力嵌进业务系统的后端开发者。你不需要换语言也不需要把服务拆成 Python 微服务直接在原来的工程里加一个 Starter 就能跑。Spring AI 1.x 的定位不是「又一个 SDK」而是「AI 集成的标准层」。它把不同厂商的模型 API 差异收敛到统一的ChatModel接口下OpenAI、Anthropic、DeepSeek、智谱、Ollama 这些都可以通过同一套ChatClient调用。核心抽象有三个ChatClient负责对话交互支持同步和流式Advisor负责在请求前后插入逻辑比如记忆、RAG 检索、内容过滤Tool Calling让模型可以请求执行你注册的 Java 方法从而访问实时数据或业务系统。这三个抽象撑起了 Spring AI 1.x 的主要使用场景。我试过在 Spring Boot 3.4 项目里直接引入spring-ai-starter-model-openai把base-url指向统一通道改完application.yml就能跑通对话。整个过程不需要改业务代码结构ChatClient的调用风格和RestClient很像学习成本很低。下面我会从零开始把依赖、配置、验证、排错一步步写清楚让你在本地完成第一个可运行示例。2. TaoToken 前置准备统一 Key 与 API 通道在写代码之前先把「通道」这件事说清楚。Spring AI 默认对接的是各家厂商的官方地址但实际开发中你可能会遇到几个问题多个模型要管理多套 Key、切换模型要改配置、某些模型访问不稳定。TaoToken 在这里扮演的角色是统一 Key 和 API 通道它提供兼容 OpenAI 协议的 endpointSpring AI 的 OpenAI Starter 可以直接把base-url指过去Key 用 TaoToken 生成的即可。你需要先拿到两样东西一个 API Key一个 Base URL。Key 在控制台的 API Keys 页面创建Base URL 是https://taotoken.net/api。注意这个地址后面不要多加/v1Spring AI 的 OpenAI 实现会自动拼接路径写多了会变成/v1/v1/chat/completions直接 404。这一点我在第一次配置时就踩过后面排错章节会详细说。模型 ID 方面你需要确认当前通道支持哪些模型。常见的有gpt-4o、gpt-4o-mini、claude-3-5-sonnet这类。Spring AI 的配置里model字段填的就是模型 ID它会被拼进请求体。如果你不确定某个模型 ID 是否可用可以先用 curl 直接打一次接口验证确认通了再写进application.yml这样能把「配置问题」和「代码问题」分开排查。提示Key 不要硬编码在代码里也不要在文章或截图里暴露完整 Key。本地开发可以用环境变量生产环境走配置中心或密钥管理服务。TaoToken 的接入文档里有各语言的示例Java 这边其实就是标准 OpenAI 协议Spring AI 的 Starter 已经封装好了。你只需要把base-url和api-key两个值填对剩下的交给自动配置。如果你还没有 Key可以先到官网了解通道能力再决定用哪个模型做第一个示例。第一个示例建议选一个响应快、成本低的模型比如gpt-4o-mini先把链路跑通再换更强的模型做复杂任务。3. 可复制配置依赖坐标与 application.yml这一节是整篇的核心所有片段都可以直接复制。先看 Maven 依赖。Spring AI 1.x 的 Starter 命名规则是spring-ai-starter-model-{provider}我们用 OpenAI 兼容通道所以引入spring-ai-starter-model-openai。同时需要 Spring AI 的 BOM 来统一版本避免各模块版本不一致。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如果你用的是 Gradle对应写法是implementation platform(org.springframework.ai:spring-ai-bom:1.0.0)加implementation org.springframework.ai:spring-ai-starter-model-openai。版本号以你实际使用的 1.x 为准1.0.0 GA 之后 API 已经稳定可以放心用于生产。接下来是application.yml。这里要写全三件套Base URL、Key、Model ID。缺任何一个都会启动失败或请求报错。spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.7注意base-url写的是https://taotoken.net/api不要带/v1。api-key用环境变量注入启动前在 IDE 或 shell 里设置TAOTOKEN_API_KEY。model填你要用的模型 IDtemperature控制随机性0 到 2 之间写代码场景建议 0.2 到 0.7。如果你需要更细的控制比如超时、重试、代理设置可以在同一层级加spring.ai.retry相关配置。Spring AI 内置了重试机制默认对可重试异常做退避。生产环境建议把超时设短一点避免线程被长时间占用。spring: ai: retry: max-attempts: 3 backoff: initial-interval: 1000 multiplier: 2 max-interval: 5000配置写完后Spring Boot 启动时会自动装配OpenAiChatModel和ChatClient.Builder。你不需要手动 new 任何东西直接在需要的地方注入ChatClient即可。这就是 Spring AI 自动配置的价值把连接细节收进配置把使用方式留给代码。4. 验证请求从 curl 到单元测试跑通对话配置写好了先别急着写 Controller。第一步用 curl 直接打通道确认 Key 和 Base URL 是通的。这一步能排除掉大部分「配置写错」的问题。curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [ {role: user, content: 用一句话解释什么是 Spring AI} ] }如果返回 JSON 里有choices[0].message.content说明通道没问题。注意 curl 里的路径是/api/v1/chat/completions而 Spring AI 配置里base-url只写到/api框架会自动补/v1/chat/completions。这两处路径写法不同但最终请求地址一致不要混淆。通道验证通过后写一个最小的 Spring Boot 单元测试。用SpringBootTest启动上下文注入ChatClient.Builder构建ChatClient并发起调用。SpringBootTest class SpringAiSmokeTest { Autowired private ChatClient.Builder chatClientBuilder; Test void shouldReturnAnswerFromModel() { ChatClient chatClient chatClientBuilder.build(); String answer chatClient.prompt() .user(用一句话解释什么是 Spring AI) .call() .content(); System.out.println(模型返回: answer); assertNotNull(answer); assertFalse(answer.isBlank()); } }运行这个测试如果控制台打印出模型返回的中文句子说明整条链路已经通了Spring Boot 启动 → 自动配置读取application.yml→ 构建OpenAiChatModel→ChatClient发起请求 → TaoToken 通道转发 → 模型返回 → 内容解析。整个过程你只写了配置和一个测试方法。如果你想验证流式返回把.call()换成.stream()返回FluxString配合 WebFlux 或 SSE 使用。流式在聊天类应用里体验更好但第一个示例建议先用同步方式确认链路再切流式。FluxString stream chatClient.prompt() .user(写一段 50 字的 Java 简介) .stream() .content(); stream.toIterable().forEach(System.out::print);到这里你已经完成了 Spring AI 1.x 的第一个可运行示例。接下来可以在这个基础上加Advisor做记忆、加ToolCallback做工具调用、加向量库做 RAG。核心抽象不变只是往ChatClient上挂更多能力。5. 本篇常见错排查401、local proxy failed、reading choices这一节把我实际遇到过的报错和排查思路列出来你对照着看基本能覆盖第一次接入的坑。401 Unauthorized。最常见的原因是 Key 没传对。检查三处环境变量TAOTOKEN_API_KEY是否真的设置成功在 IDE 里跑测试时IDE 可能没继承 shell 的环境变量需要在 Run Configuration 里单独配application.yml里api-key的占位符拼写是否和变量名一致Key 是否被复制时带了空格或换行。还有一种情况是 Key 被禁用或额度耗尽去控制台确认状态。local proxy failed / Connection refused。这个报错通常出现在你本地配了代理但代理没启动或端口不对。Spring AI 底层用的是 Java HTTP 客户端会读取 JVM 的代理设置。如果你不需要代理检查http_proxy、https_proxy环境变量和 JVM 参数-Dhttp.proxyHost是否被误设。如果你确实需要走代理确认代理地址和端口正确并且代理允许访问目标域名。这个报错和 Key 无关是网络层问题。Error reading choices / Cannot deserialize。这个报错说明请求发出去了返回也回来了但 JSON 结构和 Spring AI 预期的对不上。常见原因是base-url写成了https://taotoken.net/api/v1导致实际请求路径变成/api/v1/v1/chat/completions返回的是 404 页面或错误 JSON解析自然失败。把base-url改回https://taotoken.net/api即可。另一个原因是模型 ID 写错通道返回了错误结构检查model字段是否和通道支持的模型一致。OAuth / token 相关报错。如果你看到类似 OAuth 或 token 无效的提示先确认你用的是 API Key 而不是其他类型的凭证。Spring AI 的 OpenAI Starter 走的是 Bearer Token 认证api-key会被放进Authorization头。如果你误填了 OAuth 的 client id 或 secret认证方式不匹配就会报错。重新生成一个 API Key替换配置即可。启动时报 No qualifying bean of type ChatClient.Builder。这说明自动配置没生效。检查依赖是否引入了spring-ai-starter-model-openaiBOM 版本是否和 Starter 匹配application.yml里spring.ai.openai层级是否写对。如果用了多环境配置确认当前激活的 profile 里有这段配置。排查顺序建议先 curl 验证通道再跑单元测试验证代码最后看日志定位具体异常。把「通道问题」和「代码问题」分开能省很多时间。6. 下一步从对话到 Coding Plan 与工具调用第一个示例跑通后你手里已经有了一个能对话的 Spring Boot 服务。接下来可以往三个方向扩展。第一是加记忆用ChatMemory和MessageChatMemoryAdvisor让多轮对话能记住上下文。第二是加工具调用用Tool注解把 Java 方法暴露给模型模型会在需要时请求执行比如查数据库、调内部 API。第三是加 RAG用VectorStore和QuestionAnswerAdvisor把文档检索结果注入提示词让模型基于你的知识库回答。如果你打算把 AI 能力长期用在编码辅助或 Agent 场景可以了解 Coding Plan 这类方案它更适合高频、长会话的编码任务。日常调试和验证模型效果用模型对话页面直接试提示词会更方便。接入过程中遇到配置问题接入文档里有各语言的完整示例API Keys 页面可以管理你的 Key 和额度。Spring AI 1.x 的价值在于它把 AI 集成变成了 Spring Boot 开发的一部分你不需要成为大模型专家也能把对话、工具、检索这些能力嵌进现有系统。先把今天这个示例跑通再按需往上加模块节奏会比较稳。