如果你正在尝试将大模型能力集成到你的 Spring Boot 应用中却卡在了第一步——环境配置上那么这篇文章就是为你准备的。SpringAI 作为 Spring 官方推出的 AI 应用开发框架其核心价值在于让 Java 开发者能以熟悉的 Spring 风格像调用普通服务一样调用大模型。但很多开发者尤其是初次接触者往往在“环境设置”这一步就遇到了各种拦路虎依赖冲突、版本不匹配、API Key 配置错误、甚至因为网络问题连示例都跑不起来。这篇文章要解决的核心问题不是简单地复述官方文档而是帮你构建一个稳定、可复现、且面向实际开发的 SpringAI 环境。我们将从最基础的 JDK 和 Maven/Gradle 版本对齐开始一步步拆解依赖管理、模型供应商选择、API 密钥安全配置等关键环节并最终通过一个完整的流式对话示例让你亲手验证环境是否真正就绪。更重要的是我们会深入探讨那些官方文档可能一笔带过但实际开发中必然遇到的“坑”比如多模型供应商切换、配置中心集成、以及生产环境的最佳实践。读完本文你将能清晰地知道你的项目到底需要哪些依赖如何安全地管理敏感的 API Key如何编写第一个能跑起来的 AI 交互代码以及当环境出问题时应该按照什么顺序排查。让我们跳过那些泛泛而谈直接进入实战。1. 环境设置远不止“引入一个依赖”那么简单很多教程会把 SpringAI 的环境设置简化为“在pom.xml里加个依赖”这其实是一个巨大的误解。SpringAI 的环境是一个系统工程它至少包含四个层次基础运行环境JDK、构建工具Maven/Gradle的版本兼容性。框架依赖环境Spring Boot 的版本与 SpringAI Starter 的版本必须严格对应这是绝大多数启动失败问题的根源。模型供应商环境你需要决定使用 OpenAI、Azure OpenAI、Ollama本地模型还是 Anthropic 等并为它们配置正确的依赖和连接凭证API Key/Base URL。应用配置环境如何安全、灵活地管理这些凭证和模型参数避免硬编码。其中第二点和第三点是耦合最紧密、也最容易出错的地方。SpringAI 通过不同的starter来对接不同的模型供应商如果你引入了错误的 starter 或者版本不匹配整个应用可能连启动都做不到。因此环境设置的第一步永远是确定技术栈的版本矩阵。2. 核心概念与版本对齐理解 SpringAI 的模块化设计在开始动手之前需要理解 SpringAI 的几个核心概念这能帮你更好地选择依赖spring-ai-core: 提供核心的抽象接口如ChatClient、EmbeddingClient、PromptTemplate等。你写的业务代码主要面向这些接口。spring-ai-spring-boot-starter: 核心的 Spring Boot 自动配置模块。通常你会直接引入它。spring-ai-provider-spring-boot-starter: 各个模型供应商的 Starter。例如spring-ai-openai-spring-boot-starter用于 OpenAIspring-ai-ollama-spring-boot-starter用于本地 Ollama 服务。你的项目必须至少包含一个供应商 Starter。ChatModel/StreamingChatModel: 聊天模型客户端接口。ChatModel用于同步调用StreamingChatModel用于流式输出这正是网络热词中提到的fluxchatresponse stream chatmodel.stream(prompt)所使用的接口。版本兼容性是重中之重。SpringAI 的版本与 Spring Boot 版本有严格的对应关系。截至本文撰写时主流版本对应如下请务必根据你创建项目时的最新情况核对Spring Boot 版本推荐的 SpringAI 版本说明3.2.x0.8.1 (2024.0.0)早期稳定版本生态丰富3.3.x1.0.0-M3 (2024.0.0-M3)里程碑版本API可能有变3.2.x1.0.0-SNAPSHOT开发快照版不推荐生产最佳实践建议对于新项目建议使用 Spring Boot3.2.x SpringAI0.8.1这个组合这是目前最稳定、文档和社区资源最丰富的版本。本文后续示例也将基于此版本展开。3. 环境准备与项目初始化3.1 基础环境检查确保你的开发环境满足以下要求JDK 17 或更高版本这是 Spring Boot 3.x 的硬性要求。在终端执行java -version确认。Maven 3.6 或 Gradle 7.x本文以 Maven 为例。执行mvn -v确认。IDEIntelliJ IDEA推荐、VS Code 或 Eclipse确保已安装 Spring Boot 相关插件。网络能够访问 Maven 中央仓库用于下载依赖。如果要使用 OpenAI 等在线模型还需要能访问其 API 端点。3.2 创建 Spring Boot 项目使用 Spring Initializr 创建项目是最佳选择它能自动处理版本兼容性问题。访问 Spring Initializr。选择Project: MavenLanguage: JavaSpring Boot: 3.2.5 (选择一个 3.2.x 的稳定版本)Dependencies: 先添加Spring Web用于创建简单的测试接口。先不要在这里添加 SpringAI 依赖因为 Initializr 的依赖列表可能更新不及时我们手动添加更可靠。点击“Generate”下载项目压缩包并解压到本地。3.3 手动添加 SpringAI 依赖打开项目中的pom.xml文件。首先在properties标签内如果没有就创建或parent标签后定义 SpringAI 的 BOMBill of Materials。BOM 能统一管理所有 SpringAI 相关组件的版本避免冲突。properties spring-ai.version0.8.1/spring-ai.version /properties然后在dependencies部分添加 SpringAI 核心 Starter 和你选择的模型供应商 Starter。这里以最常用的 OpenAI 为例。dependencies !-- Spring Boot 基础依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- SpringAI 核心启动器 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-spring-boot-starter/artifactId version${spring-ai.version}/version /dependency !-- OpenAI 供应商启动器 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version${spring-ai.version}/version /dependency !-- 测试依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies关键点解释必须同时添加spring-ai-spring-boot-starter和供应商 starter如spring-ai-openai-spring-boot-starter。只加一个会导致ChatModelBean 无法被创建。版本通过${spring-ai.version}统一管理确保所有 SpringAI 组件版本一致。如果你打算使用本地模型如通过 Ollama 运行 Llama 3则应将 OpenAI 的依赖替换为dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId version${spring-ai.version}/version /dependency4. 核心配置详解安全地连接大模型依赖添加完成后下一步是配置。这里最大的陷阱是如何安全地管理 API Key。4.1 获取 API Key (以 OpenAI 为例)访问 OpenAI Platform 。登录后点击右上角个人头像选择 “View API keys”。点击 “Create new secret key” 创建一个新的密钥并妥善保存。此密钥只显示一次。4.2 应用配置文件 (application.yml或application.properties)绝对不要将 API Key 硬编码在代码中。我们使用 Spring Boot 的配置文件并结合环境变量来管理。首先在src/main/resources/application.yml中配置spring: ai: openai: api-key: ${OPENAI_API_KEY:} # 优先从环境变量读取如果为空则默认为空会启动失败 chat: options: model: gpt-3.5-turbo # 默认使用的模型 temperature: 0.7 # 创造性0-2之间 max-tokens: 500 # 最大输出token数在上面的配置中${OPENAI_API_KEY:}是一个 SpEL 表达式意思是首先查找名为OPENAI_API_KEY的环境变量或系统属性如果找不到则使用冒号后的默认值这里是空字符串。这为我们在不同环境开发、测试、生产安全地注入密钥提供了灵活性。4.3 安全地设置环境变量有多种方式设置OPENAI_API_KEY环境变量方式一IDE 运行配置推荐用于开发在 IntelliJ IDEA 中点击运行配置下拉菜单 - “Edit Configurations...”。找到你的 Spring Boot 应用配置。在 “Environment variables” 字段中添加OPENAI_API_KEY你的实际key。方式二系统环境变量不推荐影响所有应用在终端中临时设置Linux/macOSexport OPENAI_API_KEY你的实际key在 Windows PowerShell 中临时设置$env:OPENAI_API_KEY你的实际key然后在这个终端窗口启动应用。方式三使用.env文件更专业在项目根目录创建.env文件。写入OPENAI_API_KEY你的实际key。在pom.xml中引入dotenv依赖或使用第三方库来加载。对于 Spring Boot一个简单的方式是使用spring-boot-starter-dotenv需自行查找并添加依赖。生产环境建议使用配置中心如 Apollo、Nacos或云服务商提供的密钥管理服务如 AWS Secrets Manager, Azure Key Vault来管理 API Key。5. 编写第一个流式对话示例环境配置好后我们来编写一个简单的 REST 控制器实现一个流式对话接口验证整个环境是否工作正常。这正是网络热词中提到的fluxchatresponse stream chatmodel.stream(prompt)的应用场景。5.1 创建控制器创建文件src/main/java/com/example/demo/controller/AiChatController.java。package com.example.demo.controller; import org.springframework.ai.chat.ChatResponse; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.openai.OpenAiChatModel; import org.springframework.beans.factory.annotation.Autowired; 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; RestController public class AiChatController { private final OpenAiChatModel chatModel; // 使用构造器注入 ChatModel Autowired public AiChatController(OpenAiChatModel chatModel) { this.chatModel chatModel; } /** * 同步调用示例 * 访问GET /ai/chat?message你好 */ GetMapping(/ai/chat) public String chat(RequestParam(value message, defaultValue Hello) String message) { // 1. 构建用户消息 UserMessage userMessage new UserMessage(message); // 2. 构建提示 Prompt prompt new Prompt(userMessage); // 3. 调用模型获取同步响应 ChatResponse response chatModel.call(prompt); // 4. 从响应中提取文本内容 return response.getResult().getOutput().getContent(); } /** * 流式调用示例 (Server-Sent Events) * 访问GET /ai/chat/stream?message讲个故事 * 使用 curl 或前端 EventSource 测试 */ GetMapping(value /ai/chat/stream, produces text/event-stream) public FluxString streamChat(RequestParam(value message, defaultValue Hello) String message) { // 1. 构建提示 Prompt prompt new Prompt(new UserMessage(message)); // 2. 调用 streaming call 方法返回 FluxChatResponse FluxChatResponse responseFlux chatModel.stream(prompt); // 3. 将 FluxChatResponse 转换为 FluxString只提取文本内容流 return responseFlux .map(chatResponse - chatResponse.getResult().getOutput().getContent()) .filter(content - content ! null !content.isEmpty()); } }5.2 代码关键点解析依赖注入控制器通过构造器注入了OpenAiChatModel。SpringAI 的自动配置会根据application.yml中的配置自动创建这个 Bean。同步 vs 流式chatModel.call(prompt)同步调用会等待模型完全生成完毕后再返回整个响应。适用于短文本或不需要实时交互的场景。chatModel.stream(prompt)流式调用返回一个FluxChatResponse响应式流。模型生成一个字词就会推送一个事件非常适合需要实时显示、打字机效果的前端应用。内容提取ChatResponse对象结构较丰富我们通过response.getResult().getOutput().getContent()来获取最终的文本内容。媒体类型流式接口的GetMapping注解中produces text/event-stream声明了该端点返回 Server-Sent Events (SSE) 流这是前端EventSource对象能识别的标准格式。6. 运行与效果验证6.1 启动应用在项目根目录下运行mvn spring-boot:run或者直接在 IDE 中运行DemoApplication主类。观察控制台日志如果没有报错并且看到类似以下的日志说明 SpringAI 自动配置成功ChatModelBean 已就绪... o.s.ai.autoconfigure.openai.OpenAiAutoConfiguration : OpenAI Chat Properties: OpenAiChatProperties{apiKeysk-***, baseUrlhttps://api.openai.com/v1, ...} ... o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path 6.2 测试同步接口打开浏览器或使用curl命令测试curl http://localhost:8080/ai/chat?message用Java写一个Hello World程序你应该会立刻收到一个完整的、包含 Java Hello World 代码的文本响应。6.3 测试流式接口流式接口需要使用支持 SSE 的客户端。可以使用curl进行简单测试注意观察输出的逐字出现效果curl -N http://localhost:8080/ai/chat/stream?message用三句话介绍SpringAI参数-N表示禁用缓冲你会看到响应内容是一段一段对应每个ChatResponse块实时返回的。更专业的测试建议使用 Postman 或编写一个简单的前端 HTML 页面来测试流式效果。以下是一个简单的测试页面sse-test.html!DOCTYPE html html head titleSpringAI SSE 测试/title /head body input typetext idinput placeholder输入你的问题 / button onclicksendMessage()发送/button br/ div idoutput stylewhite-space: pre-wrap; border:1px solid #ccc; min-height:200px;/div script let eventSource; function sendMessage() { const message document.getElementById(input).value; const url http://localhost:8080/ai/chat/stream?message${encodeURIComponent(message)}; // 关闭之前的连接 if (eventSource) { eventSource.close(); } document.getElementById(output).innerText ; eventSource new EventSource(url); eventSource.onmessage function(event) { document.getElementById(output).innerText event.data; }; eventSource.onerror function(error) { console.error(EventSource failed:, error); eventSource.close(); }; } /script /body /html用浏览器打开这个文件输入问题并点击发送你将在outputdiv 中看到模型逐字输出的效果。7. 常见问题与排查思路环境设置过程中90%的问题都集中在以下方面。遇到问题时请按此顺序排查。问题现象可能原因排查方式解决方案应用启动失败报BeanCreationException提示ChatModel或相关 Bean 找不到1. 依赖缺失或版本冲突。2. 未正确配置 API Key。1. 检查pom.xml确认同时引入了spring-ai-spring-boot-starter和供应商 starter。2. 运行mvn dependency:tree查看依赖树检查是否有版本冲突。3. 检查启动日志看是否有关于api-key为空的警告。1. 补全依赖。2. 使用exclusions排除冲突的传递依赖。3. 确保环境变量OPENAI_API_KEY已正确设置且应用能读取到。调用接口返回401 Unauthorized或Invalid API KeyAPI Key 错误、过期或未正确传递。1. 检查application.yml中spring.ai.openai.api-key的配置值。2. 确认环境变量名是否正确是否被其他配置覆盖。3. 去 OpenAI 平台确认密钥是否有效、是否有额度。1. 在代码中临时打印配置值仅限开发环境进行调试。2. 重新生成 API Key 并更新配置。流式接口 (/ai/chat/stream) 不返回数据或立即关闭连接1. 客户端不支持 SSE。2. 响应被缓冲或网关超时。3. 模型供应商端流式支持问题。1. 使用curl -N或专门的 SSE 客户端测试。2. 检查是否有 Nginx、Spring Cloud Gateway 等代理其可能默认有缓冲或超时设置。3. 先测试同步接口是否正常。1. 确保使用正确的客户端。2. 在代理配置中禁用缓冲如 Nginx 的proxy_buffering off;。3. 检查模型供应商的文档确认所用模型支持流式输出。响应速度非常慢1. 网络问题。2. 模型参数如max-tokens设置过大。3. 模型供应商 API 限速或拥堵。1. 使用ping或traceroute测试到 API 端点的网络。2. 检查max-tokens设置适当调小。3. 查看供应商状态页面。1. 考虑使用代理或更换供应商区域。2. 优化请求参数使用更快的模型如gpt-3.5-turbo比gpt-4快。3. 实现客户端重试和退避机制。报错No qualifying bean of type OpenAiChatModel注入的 Bean 类型不对。可能配置了其他供应商如 Ollama但代码中注入了OpenAiChatModel。检查application.yml配置和pom.xml中的依赖确保供应商一致。1. 统一依赖和配置。2.更佳实践在业务代码中注入通用的ChatModel或StreamingChatModel接口而非具体的实现类如OpenAiChatModel。这样切换供应商时只需改配置无需改代码。8. 最佳实践与工程建议8.1 使用接口而非具体实现类这是最重要的设计原则。在你的 Service 或 Controller 中应该依赖ChatModel或StreamingChatModel接口而不是OpenAiChatModel。修改后的 Controller 注入方式// 更优的写法 import org.springframework.ai.chat.ChatClient; // 或者 ChatModel import org.springframework.ai.chat.StreamingChatClient; // 或者 StreamingChatModel RestController public class BetterAiChatController { private final ChatClient chatClient; private final StreamingChatClient streamingChatClient; Autowired public BetterAiChatController(ChatClient chatClient, StreamingChatClient streamingChatClient) { this.chatClient chatClient; this.streamingChatClient streamingChatClient; } GetMapping(/better/chat) public String chat(RequestParam String message) { // 直接使用 chatClient.call(message) 更简洁 return chatClient.call(message); } GetMapping(value /better/chat/stream, produces text/event-stream) public FluxString streamChat(RequestParam String message) { return streamingChatClient.stream(message) .map(ChatResponse::getResults) // 注意streamingChatClient.stream 返回 FluxChatResponse .flatMap(list - Flux.fromIterable(list)) .map(Generation::getText); } }使用接口后只需在application.yml中切换spring.ai.openai到spring.ai.ollama等配置并更换对应的 starter 依赖业务代码无需任何改动。8.2 集中化配置管理将模型参数抽取到独立的配置类中便于管理和复用。Configuration public class AiConfig { Bean ConfigurationProperties(prefix spring.ai.openai.chat.options) public OpenAiChatOptions openAiChatOptions() { return new OpenAiChatOptions(); } // 如果需要自定义 ChatModel Bean例如配置多个模型可以在这里创建 // Bean // public OpenAiChatModel myChatModel(OpenAiChatOptions options, ...) { ... } }然后在application.yml中配置spring: ai: openai: api-key: ${OPENAI_API_KEY} chat: options: model: gpt-4 temperature: 0.8 max-tokens: 10008.3 实现简单的重试与降级网络调用不稳定必须增加重试机制。Spring 提供了Retryable注解结合 Resilience4j 或 Spring Retry 模块可以轻松实现。添加依赖dependency groupIdorg.springframework.retry/groupId artifactIdspring-retry/artifactId /dependency dependency groupIdorg.springframework/groupId artifactIdspring-aspects/artifactId /dependency在主应用类上添加EnableRetry。在调用 AI 服务的方法上添加注解Service public class AiService { Retryable(value {ResourceAccessException.class, HttpClientErrorException.class}, maxAttempts 3, backoff Backoff(delay 1000, multiplier 2)) public String callWithRetry(String prompt) { // 调用 chatClient.call(prompt) } }8.4 生产环境安全与监控密钥管理务必使用环境变量、配置中心或云密钥管理服务严禁将密钥提交到代码仓库。可以在application.yml中使用spring.ai.openai.api-key${OPENAI_API_KEY:}并在部署时注入。限流与熔断使用 Resilience4j 或 Sentinel 对 AI 接口进行限流和熔断防止因供应商 API 不稳定或成本超支导致系统雪崩。日志与审计记录 AI 调用的请求和响应注意脱敏不要记录完整的 API Key 和可能包含敏感信息的 Prompt/Response用于成本分析和效果评估。超时设置在配置中或自定义的RestTemplate/WebClient中设置合理的连接超时和读取超时。9. 总结与后续方向至此你已经完成了一个从零开始、可运行、可调试的 SpringAI 开发环境搭建。我们不仅解决了“如何跑起来”的问题更深入到了配置管理、安全实践和工程化建议的层面。回顾一下关键路径确定版本 - 创建项目 - 添加正确依赖 - 安全配置 API Key - 编写面向接口的代码 - 实现流式交互 - 按清单排查问题。这个流程适用于任何基于 SpringAI 的项目初始化。环境设置只是起点。接下来你可以沿着以下几个方向深入探索 SpringAI 的更多能力多模态与函数调用尝试ImageClient处理图像生成或使用Function Calling让大模型与你的业务系统联动。向量数据库集成结合VectorStore接口和 SpringAI 对 Pinecone、Redis、PGVector 等的支持构建 RAG检索增强生成应用。复杂的提示工程利用PromptTemplate和ChatOptions实现系统指令、上下文管理、思维链等高级提示技巧。构建 AI Agent正如网络热词中提到的“写一个 Agent”你可以利用 SpringAI 提供的Agent、Tool等抽象构建能够自主规划、使用工具完成复杂任务的智能体。建议将本文作为一份环境配置的“检查清单”和“排错指南”收藏。在实际开发中大部分时间将花在业务逻辑和提示优化上而一个稳固的基础环境是这一切高效进行的前提。现在你的 SpringAI 之旅已经正式启航可以开始构建真正有价值的 AI 应用了。