Spring AI API 接入流程（1.0 GA 从零到第一个接口）

API接口开发代码生成工作台集成工程交付应用搭建开发者生态

2026-09-17 02:47

5 浏览

0 点赞

AI 速览

Spring AI 1.0 GA 接入大模型的完整开发指南，适合 Java 工程师快速集成主流大模型 API。核心事实 - 技术框架：Spring 官方推出的 Java 生成式 AI 框架 Spring AI 1.0 GA - 发布时间：2025 年 5 月 20 日正式发布并上架 Maven Central - 核心抽象：通过 ChatClient 统一接口支持 20+ 大模型（含 DeepSeek、通义千问、Ollama 等） - 接入流程：五步完成——环境准备、引入 BOM、添加 starter、配置 Key、编写调用代码 - 命名变更：GA 版 starter 命名规则从 spring-ai-{model}-spring-boot-starter 改为 spring-ai-starter-model-{model} 避坑提示 - JDK 要求：必须使用 JDK 17+，推荐 JDK 21，低于 17 无法编译 - Boot 版本：仅兼容 Spring Boot 3.x，不支持 Spring Boot 2 项目 - 配置安全：API Key 必须通过环境变量注入，严禁硬编码到 yml 文件或提交至 Git 价值点帮助 Java 开发者用一套代码无缝切换不同大模型，大幅降低生成式 AI 集成成本和维护复杂度。

Spring AI 是 Spring 官方推出的 Java 生成式 AI 框架，1.0 GA 于 2025 年 5 月 20 日发布，已上架 Maven Central。接入一套大模型分五步：配好 JDK 与 Spring Boot 环境、引入 spring-ai-bom、加上对应模型的 starter、在 application.yml 填 Key 和模型名、用 ChatClient 写调用代码。下文按官方文档把这套流程拆开讲，并覆盖 DeepSeek、通义千问与本地 Ollama 等国内常用入口。

Spring AI 是什么

Spring AI 把各家大模型的接口收拢成一套 Spring 风格的抽象，核心入口是 ChatClient——一个流式 DSL，官方推荐作为首选交互方式。用 ChatClient 写一次业务代码，背后可以接 20 多家模型：OpenAI、Anthropic、Azure OpenAI、Amazon Bedrock、Google Vertex AI、Ollama、DeepSeek、通义千问、智谱等。换模型通常只动依赖和配置，java 代码基本不动。

官网在 spring.io/projects/spring-ai，参考文档在 docs.spring.io/spring-ai/reference/index.html。新项目可以在 start.spring.io 直接勾选 Spring AI 1.0 GA 依赖生成骨架。

环境准备

JDK 17 及以上：Spring Boot 3.x 最低要求 JDK 17，推荐用 21，低于 17 直接编译不过。

Spring Boot 3.x：1.0 GA 基于 Spring Boot 3.x 构建，别拿 Spring Boot 2 的项目硬接。

构建工具：Maven 3.6+ 或 Gradle 8.5+，二选一。

模型凭证：要么有一家云厂商的 API Key（OpenAI、DeepSeek 等），要么本地装好 Ollama 跑开源模型——后者免 Key、免联网，适合开发联调。

第一步：引入 BOM 与 starter（最容易踩的坑）

Spring AI 组件很多，先用 BOM 锁定统一版本，再按需加具体 starter。1.0 GA 已经发布到 Maven Central，普通使用不用再加 milestone 仓库；只有拉快照或里程碑版本才需要配 repo.spring.io 的仓库。

<dependencyManagement>  <dependencies>    <dependency>      <groupId>org.springframework.ai</groupId>      <artifactId>spring-ai-bom</artifactId>      <version>1.0.0</version>      <type>pom</type>      <scope>import</scope>    </dependency>  </dependencies></dependencyManagement><dependencies>  <dependency>    <groupId>org.springframework.boot</groupId>    <artifactId>spring-boot-starter-web</artifactId>  </dependency>  <!-- 以 OpenAI 为例，换模型只换这一行 -->  <dependency>    <groupId>org.springframework.ai</groupId>    <artifactId>spring-ai-starter-model-openai</artifactId>  </dependency></dependencies>

命名规则在 1.0 变了，这是新手看老教程最容易翻车的地方。里程碑版本用 spring-ai-openai-spring-boot-starter，GA 版改成了 spring-ai-starter-model-openai。套用下面这张表就不会配错：

组件类型	旧命名（M 版本）	新命名（1.0 GA）
对话/嵌入模型	spring-ai-{model}-spring-boot-starter	spring-ai-starter-model-{model}
向量数据库	spring-ai-{store}-store-spring-boot-starter	spring-ai-starter-vector-store-{store}
MCP	spring-ai-mcp-{type}-spring-boot-starter	spring-ai-starter-mcp-{type}

第二步：在 application.yml 填 Key 和模型

starter 上 classpath 后，Spring Boot 会自动装配 ChatModel，开发者只需在配置里给 Key 和模型名。多家的配置长这样：

spring:  ai:    openai:      api-key: ${OPENAI_API_KEY}      chat:        options:          model: gpt-4o          temperature: 0.7    deepseek:      api-key: ${DEEPSEEK_API_KEY}      # base-url 默认就是 https://api.deepseek.com，可省略      chat:        options:          model: deepseek-chat    ollama:      base-url: http://localhost:11434      chat:        options:          model: qwen2.5:latest

Key 一律用 ${ENV} 从环境变量或密钥管理工具注入，不要写死在 yml 里、更不要提交到代码仓库。一旦推到 git 历史，删掉也救不回。

第三步：写第一个对话接口

注入 ChatClient.Builder 即可，自动配置会帮你建好底层 ChatModel。同步调用三板斧：

@RestController@RequestMapping("/api/ai")public class ChatController {    private final ChatClient chatClient;    public ChatController(ChatClient.Builder builder) {        this.chatClient = builder                .defaultSystem("你是一个专业的 Java 技术专家")                .build();    }    @GetMapping("/chat")    public String chat(@RequestParam String message) {        return chatClient.prompt()                .user(message)                .call()                .content();    }    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)    public Flux<String> stream(@RequestParam String message) {        return chatClient.prompt()                .user(message)                .stream()                .content();    }}

想要打字机效果，把 call() 换成 stream()，返回 Flux<String>，前端用 SSE 接收即可，业务代码几乎不变。

国内模型与本地模型怎么接

国内开发者常接 DeepSeek、通义千问，或本地用 Ollama 跑开源模型。它们的接入姿势和上面完全一致，只是换 starter 和配置前缀：

模型/平台	starter（1.0 GA）	关键配置	说明
DeepSeek	spring-ai-starter-model-deepseek	spring.ai.deepseek.api-key / chat.options.model=deepseek-chat（或 deepseek-reasoner）	base-url 默认 https://api.deepseek.com，对话路径 /chat/completions
通义千问（阿里云百炼）	spring-ai-starter-model-dashscope	spring.ai.dashscope.api-key	配置前缀 spring.ai.dashscope，starter 名以官方文档为准
智谱 ZhiPu	spring-ai-starter-model-zhipuai	spring.ai.zhipuai.api-key	配置前缀 spring.ai.zhipuai
Ollama（本地）	spring-ai-starter-model-ollama	spring.ai.ollama.base-url=http://localhost:11434	免 Key，需本地装 Ollama 并 pull 模型

DeepSeek 的官方文档还暴露了一批重试参数，默认就比较友好：最大尝试 10 次、初始退避 2 秒、退避倍数 5、最大退避 3 分钟。可在 spring.ai.retry.* 下调整。

一个 OpenAI starter 接多家的技巧

很多厂商的接口兼容 OpenAI 协议，Spring AI 允许只改 base-url 就用同一个 OpenAI starter 接它们，不需要额外依赖。常见几组：

Gemini：spring.ai.openai.base-url=https://generativelanguage.googleapis.com/v1beta/openai/

Groq：spring.ai.openai.base-url=https://api.groq.com/openai/v1

Docker Model Runner：spring.ai.openai.base-url=http://localhost:12434/v1

这套「OpenAI 兼容层」思路能少装好几个 starter，适合做多供应商灰度或快速试水新模型。

常见错误与排查

现象	常见原因	解决
编译找不到类 / 自动装配失败	用了旧命名 spring-ai-openai-spring-boot-starter	改成 spring-ai-starter-model-openai
启动报缺少 API Key	yml 里没配或环境变量没注入	确认 spring.ai.{model}.api-key 已设，优先走 ${ENV}
调本地 Ollama 连不上	base-url 写成 OpenAI 地址或端口错	Ollama 固定 http://localhost:11434，先 curl 验证服务在跑
模型不存在报错	model 字段写错（如 gpt-4o 拼错）	对照各家控制台当前模型名
项目起不来、提示需要更高 JDK	JDK 低于 17	升级到 17 或 21，Spring Boot 3.x 硬性要求

新手常见问题

Q：Spring AI 本身收费吗？ A：框架开源免费。花钱的是背后调用的模型，按各家自己的计费走，跟 Spring AI 没关系。

Q：必须用 Spring Boot 3 吗？ A：1.0 GA 基于 Spring Boot 3.x，要求 JDK 17+，Spring Boot 2 的项目接不了。

Q：为什么教程里的 starter 名字和我配的对不上？ A：老教程是里程碑版本，用的是 spring-ai-{model}-spring-boot-starter；1.0 GA 统一改成了 spring-ai-starter-model-{model}。

Q：同一套代码能接多家模型吗？ A：能。ChatClient 是统一抽象，把 DeepSeek 换成 Ollama 基本只改依赖和配置，Controller 不动。

Q：本地免费用哪个模型最方便？ A：装 Ollama，pull 一个 qwen2.5 之类的开源模型，base-url 指向 11434，不需要任何 Key。

Q：DeepSeek 怎么接？ A：加 spring-ai-starter-model-deepseek，yml 里填 spring.ai.deepseek.api-key 和 chat.options.model=deepseek-chat，base-url 默认就是 api.deepseek.com。

Q：流式输出怎么写？ A：把 call() 换成 stream()，返回 Flux<String>，接口 produces 设为 text/event-stream，前端用 SSE 收。

Q：API Key 该怎么保管？ A：放服务端环境变量或密钥管理工具，用 ${ENV} 注入，别进代码仓库，定期轮换。

Q：要加 spring milestone 仓库吗？ A：用 1.0 GA 不用加，已经在 Maven Central。只有你想拉快照或里程碑版本时才需要配 repo.spring.io。

Spring AI API 接入流程说到底就是五步：JDK 17 配 Spring Boot 3、引 spring-ai-bom、按新命名加 spring-ai-starter-model-*、yml 里填 Key 和模型、用 ChatClient 写调用。把命名规则和 base-url 这两处易错点记牢，从 OpenAI 切到 DeepSeek、通义千问或本地 Ollama 都只是改配置的事。想跟进 Spring AI 新版本与更多模型适配，可以关注本站的 AI 开发栏目，有更新我们再同步。

好文章，需要你的鼓励