如果你正在尝试将大语言模型LLM能力集成到你的 Spring Boot 应用中却卡在了第一步——环境配置上那么这篇文章就是为你准备的。SpringAI 作为 Spring 官方推出的 AI 应用开发框架其核心价值在于将复杂的 AI 模型调用抽象为熟悉的 Spring 风格编程模型让开发者能像使用JdbcTemplate操作数据库一样使用ChatClient与 GPT、通义千问等模型对话。然而很多开发者在初次接触 SpringAI 时会陷入一个误区认为它只是一个简单的 SDK 封装配置一下 API Key 就能跑通。实际上SpringAI 的环境设置远不止于此它涉及到依赖管理、模型选择、配置隔离、流式响应处理等一系列工程化问题。一个不恰当的初始配置可能会在后续开发中引发依赖冲突、配置混乱、性能低下等连锁反应。本文将聚焦于SpringAI 4.x 的环境设置这不仅是项目启动的第一步更是决定整个 AI 应用工程化质量的关键一步。我们将从零开始不仅告诉你如何“跑起来”更会深入分析每个配置项背后的考量以及如何为构建一个健壮的、可维护的 AI Agent 或工作流打下坚实基础。读完本文你将能清晰地搭建一个支持多模型、配置清晰、具备流式响应能力的 SpringAI 开发环境。1. 这篇文章真正要解决的问题为什么 SpringAI 的环境设置值得单独写一篇文章因为对于大多数 Java/Spring 开发者而言AI 开发是一个新领域其工具链和依赖管理与传统 Web 开发有显著差异。环境设置不当会导致以下几个典型问题依赖地狱SpringAI 的起步依赖Starter会自动引入一系列相关库如果与项目中已有的 Spring Boot、Spring Cloud 版本不兼容极易引发难以排查的依赖冲突。配置散乱API Key、Base URL、模型参数等敏感或环境相关的配置如果随意写在application.properties中会给安全性和多环境部署带来麻烦。模型切换成本高今天测试用 OpenAI GPT-4明天想换到阿里的通义千问如果代码中硬编码了模型客户端切换起来就需要大量修改。无法享受流式响应大语言模型的流式响应Streaming能极大提升用户体验但如果环境配置不支持如缺少相关依赖或配置错误就只能使用阻塞的同步调用体验大打折扣。对“Agent”和“工作流”开发准备不足SpringAI 的高级特性如 Function Calling、Prompt Templates、Output Parsers 以及构建复杂 Agent都依赖于一套正确且灵活的基础环境。因此本文的目标是帮你建立一个标准化、可扩展、生产就绪的 SpringAI 开发环境。这不仅是为了运行第一个 Demo更是为了让你后续的vibe coding沉浸式编码和搭建 AI 工作流时没有后顾之忧。2. 基础概念与核心原理在动手之前理解几个核心概念能让你更清楚每一步配置的意义。SpringAI Project这是 Spring 官方为 AI 应用开发提供的一整套项目集合包括核心抽象spring-ai、对各种 AI 服务提供商的客户端实现如spring-ai-openai,spring-ai-ollama、以及一些示例和扩展。ChatClient这是 SpringAI 的核心接口之一它抽象了与 AI 模型对话的行为。无论底层是 OpenAI、Azure OpenAI 还是阿里云灵积你都可以通过统一的ChatClientAPI 进行调用。这实现了模型调用的解耦。ChatModelChatClient的一个更具体实现通常指代一个具有聊天能力的语言模型。在配置中我们经常需要指定具体使用的ChatModel实现。Streaming流式响应。传统的 HTTP 调用是等待模型生成完整响应后再一次性返回。而流式响应允许服务器边生成边返回通常通过 Server-Sent Events客户端可以实时看到生成的文字体验更流畅。SpringAI 提供了ChatModel.stream()方法来支持此功能。API Key Base URL访问商业化 AI 服务如 OpenAI, 通义千问的凭证和端点。对于本地或自托管模型如 OllamaBase URL 通常指向本地服务地址。Spring Boot StartersSpringAI 为不同的模型提供商提供了“起步依赖”如spring-ai-openai-spring-boot-starter。引入它Spring Boot 的自动配置机制就会帮你创建好相应的ChatModelBean并绑定配置文件中的属性。理解了这些你就会明白环境设置的本质是通过合理的依赖管理和配置让 Spring 容器能够自动装配出我们需要的、功能完整的ChatModel或ChatClientBean。3. 环境准备与前置条件在开始配置 SpringAI 之前请确保你的基础开发环境已经就绪。Java 开发环境JDKSpring Boot 3.x 和 SpringAI 4.x 要求 JDK 17 或更高版本。推荐使用 JDK 17 或 JDK 21LTS版本。可以通过命令检查版本java -version构建工具Maven版本 3.6 或更高。Gradle版本 7.x (兼容 Spring Boot 3) 或 8.x。本文将以Maven为例进行演示Gradle 的配置逻辑类似。IDE集成开发环境IntelliJ IDEA推荐、Eclipse 或 VS Code 等。确保 IDE 已正确配置 JDK 和构建工具。网络环境如果你计划使用 OpenAI、Azure OpenAI 或国内如阿里云的通义千问等在线模型需要确保你的开发机器能够访问相应的 API 端点。如果你计划使用本地模型如通过 Ollama 运行 Llama 3则需要安装并运行相应的本地服务。API 密钥如使用在线模型提前准备好你计划使用的 AI 服务提供商的 API Key。例如OpenAI: 从 OpenAI Platform 获取。阿里云百炼/通义千问从阿里云控制台获取。重要安全提示API Key 是敏感信息绝对不要直接提交到代码仓库。我们后续会通过环境变量或配置文件.gitignore来管理。4. 核心流程拆解搭建 SpringAI 项目环境我们将创建一个全新的 Spring Boot 项目并集成 SpringAI。整个过程分为以下几个关键步骤4.1 创建 Spring Boot 项目使用 Spring Initializr 或 IDE 内置的创建向导生成一个基础项目。Project: MavenLanguage: JavaSpring Boot: 选择最新的 3.x 版本如 3.2.5Group Artifact: 按你的习惯定义例如com.example和springai-demoPackaging: JarJava Version: 17 或 21Dependencies: 初始只需选择Spring Web用于创建简单的 Web 接口测试。先不要在这里添加任何 AI 相关的依赖我们将在下一步手动添加以便更精确地控制版本。生成项目后用 IDE 打开。4.2 添加 SpringAI 依赖与 BOM 管理这是最关键的一步正确的依赖管理能避免大量冲突。添加 SpringAI BOM物料清单 在pom.xml的project标签下添加dependencyManagement部分引入 SpringAI 的 BOM。BOM 能统一管理所有 SpringAI 相关组件的版本确保它们彼此兼容。dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0-M4/version !-- 使用最新的稳定或里程碑版本 -- typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement注意SpringAI 版本迭代较快请访问 SpringAI 官方项目页面 或 Spring Initializr 查看推荐的最新版本。1.0.0-M4是一个里程碑版本功能已相对稳定。添加具体的模型 Starter 依赖 在dependencies部分添加你需要的模型客户端。例如如果你要使用 OpenAI 的接口包括 GPT-4, GPT-3.5-Turbo则添加dependencies !-- 之前通过Initializr添加的Spring Web -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- SpringAI OpenAI Starter -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId !-- 版本由上面的BOM统一管理此处无需指定 -- /dependency !-- 可选用于测试 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies如果你想使用阿里云的通义千问则需要添加对应的 starter如果官方提供。目前 SpringAI 社区可能有第三方实现或阿里云官方提供的适配器请根据实际情况添加对应依赖。4.3 配置模型连接参数接下来在src/main/resources/application.properties或application.yml中配置连接信息。对于 OpenAI# application.properties # OpenAI 配置 spring.ai.openai.api-key${OPENAI_API_KEY:your-openai-api-key-placeholder} spring.ai.openai.chat.options.modelgpt-3.5-turbo # spring.ai.openai.chat.options.modelgpt-4 # 如果需要使用 GPT-4 spring.ai.openai.base-urlhttps://api.openai.com/v1 # 默认值如果是Azure OpenAI或其他兼容API需要修改重要${OPENAI_API_KEY}表示从环境变量中读取OPENAI_API_KEY的值。这是推荐的做法可以避免密钥泄露。你可以在系统环境变量中设置或在 IDE 的运行配置中指定。对于本地 Ollama运行 Llama 3 等模型首先需要安装并启动 Ollama 服务。然后在配置中指向本地地址。# application.properties # Ollama 配置 (使用 ollama-spring-boot-starter) spring.ai.ollama.base-urlhttp://localhost:11434 # Ollama 默认端口 spring.ai.ollama.chat.options.modelllama3:8b # 指定本地运行的模型名称4.4 编写一个简单的测试 Controller创建一个 REST 端点来测试环境是否正常工作。// 文件路径src/main/java/com/example/springaidemo/controller/TestController.java package com.example.springaidemo.controller; import org.springframework.ai.chat.ChatClient; import org.springframework.ai.chat.ChatResponse; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.chat.prompt.PromptTemplate; 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 java.util.Map; RestController public class TestController { private final ChatClient chatClient; // 通过构造器注入 ChatClient Autowired public TestController(ChatClient chatClient) { this.chatClient chatClient; } /** * 最简单的对话测试 */ GetMapping(/ai/chat) public String chat(RequestParam(value message, defaultValue Hello) String message) { Prompt prompt new Prompt(message); ChatResponse response chatClient.call(prompt); return response.getResult().getOutput().getContent(); } /** * 使用 PromptTemplate 进行带变量的对话 */ GetMapping(/ai/generate) public String generate(RequestParam String topic) { PromptTemplate promptTemplate new PromptTemplate(请用一句话介绍{subject}。); Prompt prompt promptTemplate.create(Map.of(subject, topic)); ChatResponse response chatClient.call(prompt); return response.getResult().getOutput().getContent(); } }4.5 处理流式响应Streaming流式响应是提升体验的关键。SpringAI 使其变得非常简单。// 文件路径src/main/java/com/example/springaidemo/controller/StreamController.java package com.example.springaidemo.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.OpenAiChatClient; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.http.MediaType; 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 StreamController { // 这里可以直接注入 OpenAiChatClient 或特定模型的 ChatClient // 使用更通用的 ChatClient 接口也可以但调用 stream 方法时可能需要类型转换 private final OpenAiChatClient chatClient; Autowired public StreamController(OpenAiChatClient chatClient) { this.chatClient chatClient; } /** * 流式对话接口 * 注意produces MediaType.TEXT_EVENT_STREAM_VALUE 是关键 */ GetMapping(value /ai/chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString streamChat(RequestParam(value message, defaultValue 讲一个简短的笑话) String message) { Prompt prompt new Prompt(new UserMessage(message)); // 调用 stream 方法返回一个 FluxChatResponse FluxChatResponse responseFlux chatClient.stream(prompt); // 从 FluxChatResponse 中提取并输出文本内容流 return responseFlux .map(chatResponse - { // 从每个 ChatResponse 中获取生成的文本片段 if (chatResponse.getResult() ! null chatResponse.getResult().getOutput() ! null) { return chatResponse.getResult().getOutput().getContent(); } return ; }); } }这段代码的关键点produces MediaType.TEXT_EVENT_STREAM_VALUE声明该端点返回的是 Server-Sent Events (SSE) 流。chatClient.stream(prompt)返回FluxChatResponse这是一个响应式流。使用map操作符从每个ChatResponse中提取文本内容最终返回FluxString给前端。5. 运行结果与效果验证5.1 启动应用在项目根目录下运行mvn spring-boot:run或直接在 IDE 中运行主类SpringAiDemoApplication。看到类似以下的日志表示启动成功Started SpringAiDemoApplication in 3.456 seconds (process running for 3.789)5.2 测试同步接口打开浏览器或使用curl、Postman 测试测试基础聊天GET http://localhost:8080/ai/chat?messageJava是什么预期返回一个关于 Java 的文本描述。测试 PromptTemplateGET http://localhost:8080/ai/generate?topicSpring框架预期返回一句对 Spring 框架的介绍。5.3 测试流式接口流式接口需要使用支持 SSE 的客户端。可以使用curl进行简单测试curl -N http://localhost:8080/ai/chat/stream?message用100字介绍人工智能-N参数用于禁用缓冲你会看到文字一段一段地实时输出到终端。更直观的测试方法是使用前端页面。创建一个简单的index.html放在src/main/resources/static/目录下!DOCTYPE html html langen head meta charsetUTF-8 titleSpringAI Stream Test/title /head body h2SpringAI 流式响应测试/h2 input typetext idinputMessage placeholder输入你的问题... value为什么天空是蓝色的/ button onclicksendStreamRequest()发送/button br/br/ div idresponseArea stylewhite-space: pre-wrap; border:1px solid #ccc; padding:10px; min-height:100px;/div script function sendStreamRequest() { const message document.getElementById(inputMessage).value; const responseArea document.getElementById(responseArea); responseArea.textContent ; // 清空之前的内容 // 创建 EventSource 连接用于接收 SSE const eventSource new EventSource(/ai/chat/stream?message${encodeURIComponent(message)}); eventSource.onmessage function(event) { // 接收到数据追加到显示区域 responseArea.textContent event.data; }; eventSource.onerror function(err) { console.error(EventSource failed:, err); eventSource.close(); responseArea.textContent \n\n[连接已关闭或出错]; }; // 10秒后自动关闭连接可选 setTimeout(() { eventSource.close(); responseArea.textContent \n\n[流式响应结束]; }, 10000); } /script /body /html启动应用后访问http://localhost:8080/index.html输入问题并点击发送即可在页面上看到文字逐字输出的效果。6. 常见问题与排查思路在环境设置过程中你可能会遇到以下问题问题现象可能原因排查方式解决方案应用启动失败报NoSuchBeanDefinitionException或BeanCreationException1. 依赖未正确添加或版本冲突。2. 配置属性缺失或错误如 API Key 为空。3. 使用了错误的 Starter。1. 检查pom.xml依赖确保 BOM 和 Starter 已添加。2. 运行mvn dependency:tree查看依赖树排除冲突。3. 检查application.properties配置特别是 API Key 和 Base URL。4. 查看完整的启动错误堆栈。1. 确保 BOM 版本与 Spring Boot 版本兼容。2. 通过环境变量设置正确的 API Key。3. 确认配置的前缀如spring.ai.openai与使用的 Starter 匹配。调用接口返回 401 或 403 错误API Key 无效、过期或没有对应模型的权限。1. 检查控制台日志确认请求是否携带了正确的认证头。2. 去对应的 AI 服务平台验证 API Key 是否有效、额度是否充足。1. 重新生成并配置有效的 API Key。2. 检查模型名称是否正确如gpt-3.5-turbo。调用接口超时或连接被拒绝1. 网络无法访问 API 端点。2. Base URL 配置错误。3. 本地代理设置问题。1. 使用curl或ping测试网络连通性。2. 检查spring.ai.openai.base-url配置。3. 如果是公司内网可能需要配置代理。1. 确保网络通畅。2. 修正 Base URL。3. 在 JVM 参数或代码中配置网络代理。流式接口 (/ai/chat/stream) 不流式输出而是一次性返回1. 客户端不支持 SSE如浏览器直接访问。2. 控制器方法返回类型不是Flux或未设置produces MediaType.TEXT_EVENT_STREAM_VALUE。3. 注入的ChatClient不支持stream()方法。1. 使用curl -N或专门的 SSE 测试工具。2. 检查控制器代码确保返回类型和produces属性正确。3. 确认注入的是具体模型的 ChatClient如OpenAiChatClient它肯定支持stream()。1. 使用正确的客户端进行测试。2. 对照本文示例代码检查控制器。3. 确保依赖的 Starter 版本支持流式响应。项目编译报错提示ChatClient等类找不到1. Maven/Gradle 依赖未下载成功。2. IDE 未正确索引项目。1. 检查网络尝试mvn clean compile。2. 在 IDE 中刷新 Maven/Gradle 项目。3. 检查本地 Maven 仓库是否存在对应的 jar 包。1. 清理本地仓库后重新下载 (mvn clean install -U)。2. 重启 IDE。7. 最佳实践与工程建议一个良好的初始环境是成功的一半。遵循以下实践能让你的 SpringAI 项目更健壮、更易维护使用 BOM 管理版本始终坚持使用spring-ai-bom来管理所有 SpringAI 相关依赖的版本。这是避免依赖冲突最有效的方法。将敏感配置外部化永远不要将 API Key 等敏感信息硬编码在application.properties中或提交到代码仓库。使用环境变量、云平台的密钥管理服务如 AWS Secrets Manager, Azure Key Vault或 Spring Cloud Config。推荐做法在application.properties中这样写spring.ai.openai.api-key${OPENAI_API_KEY}然后在运行环境系统环境变量、IDE 配置、Docker 环境变量中设置OPENAI_API_KEY。为多环境配置使用 Spring Boot 的 Profile 机制为开发、测试、生产环境准备不同的配置文件如application-dev.properties,application-prod.properties在其中配置不同的模型、参数或开关。封装 AI 服务层不要在 Controller 中直接大量使用ChatClient。应该创建一个 Service 层将 AI 调用、Prompt 构建、结果处理、错误重试、日志记录等逻辑封装起来。这提高了代码的可测试性和可维护性。Service public class AIChatService { private final ChatClient chatClient; private final RetryTemplate retryTemplate; // 可选用于重试 public String generateContent(String userInput) { // 构建更复杂的 Prompt处理异常记录日志等 Prompt prompt new Prompt(userInput); try { ChatResponse response chatClient.call(prompt); return response.getResult().getOutput().getContent(); } catch (Exception e) { log.error(AI调用失败, e); throw new BusinessException(AI服务暂时不可用); } } }考虑模型降级与切换在生产环境中依赖单一 AI 服务提供商是有风险的。可以设计一个ModelProvider接口并有多个实现如OpenAIProvider,AzureProvider,LocalModelProvider。结合配置中心可以在某个服务不可用时快速切换。监控与可观测性AI 调用可能产生延迟和费用。集成 Micrometer 等监控工具记录每次调用的耗时、令牌使用量、成功率等指标这对于成本控制和性能优化至关重要。流式响应的超时与错误处理流式连接是长连接需要妥善处理客户端断开、服务器超时等异常。在服务端可以考虑使用timeout和onErrorResume等操作符来增强鲁棒性。8. 总结与后续学习方向至此你已经成功搭建了一个功能完整的 SpringAI 4.x 开发环境。我们不仅完成了从依赖引入、配置编写到接口测试的全流程更深入探讨了流式响应的实现、常见问题的排查以及面向生产的最佳实践。这个环境是你探索 SpringAI 更强大功能的起点。基于此你可以继续深入以下几个方向深入 Prompt 工程SpringAI 提供了强大的PromptTemplate、ChatOptions等工具学习如何系统化地构建和优化 Prompt是提升 AI 应用效果的核心。开发复杂的 AI AgentAgent 是能自主调用工具、完成复杂任务的 AI 实体。SpringAI 提供了Agent、Tool等抽象接下来你可以尝试让 AI 调用你的业务函数、查询数据库或访问外部 API。实现 Function Calling让大模型学会在需要时调用你预先定义好的 Java 方法这是构建智能应用的关键一步。集成向量数据库结合 SpringAI 的VectorStoreAPI为你的应用添加长期记忆和语义检索能力构建真正的 RAG检索增强生成应用。探索多模态SpringAI 也开始支持图像、音频等多模态模型的调用尝试让 AI 理解并生成更丰富的内容。环境设置是基石它决定了上层建筑是否稳固。建议你将本文的配置作为模板保存在开始任何一个新的 SpringAI 项目时都能快速搭建起一个规范、高效且可扩展的起点。现在你可以自信地开始你的vibe coding去构建那些充满想象力的 AI 工作流了。如果在实践中遇到新的问题不妨回到这里检查一下你的“地基”是否依然牢固。