这次我们来看 SpringAI 的环境设置。对于想快速上手 AI 应用开发的 Java 开发者来说SpringAI 提供了一个将大模型能力集成到 Spring 应用中的标准化方案。它最核心的价值在于你不用再为不同 AI 服务商如 OpenAI、阿里通义、智谱等的 API 差异而烦恼通过一套统一的抽象接口就能调用文本生成、图像理解、函数调用等多种 AI 能力。本文将带你从零开始完成 SpringAI 的环境搭建与基础验证。重点不是讲解复杂的 AI 概念而是确保你能在自己的开发机器上无论是 Windows、macOS 还是 Linux都能成功跑通第一个 SpringAI 应用。我们会重点关注几个实际问题项目依赖如何管理、API Key 如何安全配置、不同模型供应商如何切换以及如何通过一个简单的聊天接口验证环境是否就绪。如果你关心如何在 Spring Boot 项目中快速集成 AI 能力并希望后续能平滑地接入工作流或构建 Agent那么这篇文章可以直接跟着操作。1. 核心能力速览在深入配置之前我们先快速了解 SpringAI 是什么以及它能为你带来什么。能力项说明项目类型Spring 生态的官方 AI 集成框架提供了一套统一的 API 来调用多种大模型服务。开源团队Spring 官方团队主导开发与维护。主要功能1.Chat文本对话与生成。2.Embeddings文本向量化。3.Images文生图、图生文。4.Audio语音转文本STT。5.Vector Stores向量数据库集成。推荐环境Java 17 或更高版本Spring Boot 3.x构建工具Maven/Gradle。硬件门槛无特殊要求。SpringAI 本身是客户端框架推理计算发生在云端 AI 服务商如 OpenAI或你自行部署的本地模型服务端。你的开发机只需能运行 Java 和 Spring Boot 应用即可。启动方式标准的 Spring Boot 应用启动方式通过main方法或mvn spring-boot:run命令启动。是否支持 API是。SpringAI 本身不提供对外 API但它让你能在自己的 Spring Boot 应用中快速构建出 AI 功能 API。是否支持批量任务间接支持。可以通过编程方式循环调用或利用 Spring 的异步任务处理批量请求但具体并发能力受限于你集成的 AI 服务商的 API 限制。适合场景1. 快速为现有 Spring Boot 应用添加 AI 能力。2. 构建需要切换不同模型供应商的 AI 应用。3. 开发基于大模型的 Agent、工作流或业务系统。简单来说SpringAI 是一个“连接器”和“标准化层”。你的代码面向 SpringAI 的ChatClient、ChatModel等接口编程而具体背后是调用 OpenAI 的 GPT-4 还是阿里通义千问只需修改配置文件即可。2. 适用场景与使用边界适合谁Java/Spring 技术栈的开发者如果你熟悉 Spring Boot那么上手 SpringAI 几乎没有额外学习成本。需要快速验证 AI 能力的团队希望以最小代价在业务系统中集成聊天、摘要、翻译等 AI 功能。考虑模型供应商锁定的项目使用 SpringAI 的抽象层可以在 OpenAI、Anthropic、Azure OpenAI、本地模型等多种后端间灵活切换。能解决什么问题统一编程模型用同一套代码调用不同厂商的 AI API。简化配置通过 Spring Boot 的application.properties或application.yml文件集中管理 AI 模型参数和 API Key。快速集成提供开箱即用的ChatClient、VectorStore等组件无需从零编写 HTTP 客户端和解析逻辑。生态集成与 Spring 生态的其他项目如 Spring Data、Spring Security无缝结合便于构建企业级应用。不适合什么场景追求极致性能或最低延迟SpringAI 增加了一层抽象理论上会引入微小开销。对于超高频、超低延迟的裸 API 调用场景直接使用各厂商的 SDK 可能更直接。非 Java 技术栈如果你的主力技术栈是 Python、Node.js 等使用对应语言的 SDK 是更自然的选择。完全离线的本地模型推理虽然 SpringAI 支持通过LocalAI等项目连接本地模型但其主要设计目标是连接云端 API。复杂的本地模型加载、显存管理、性能优化并非其核心功能。安全与合规边界API Key 管理务必通过环境变量或安全的配置中心管理 API Key严禁将 Key 硬编码在代码或提交到版本库。内容安全你集成的 AI 服务商如 OpenAI有其自身的内容安全策略。你的应用需要额外考虑用户输入和 AI 输出的过滤与审核避免产生有害或违规内容。数据隐私向第三方 AI 服务发送数据时需了解其数据使用政策。对于敏感数据应考虑使用支持数据脱敏或本地部署的模型方案。版权与授权确保使用 AI 生成的内容如文本、图片符合版权法规特别是在商用场景下。3. 环境准备与前置条件开始之前请确保你的开发环境满足以下基本要求。这是后续所有步骤能顺利进行的基础。Java 开发套件 (JDK)版本JDK 17 或更高版本。Spring Boot 3.x 和 SpringAI 基于 Java 17 构建。推荐使用 JDK 17 或 JDK 21LTS版本。检查命令打开终端或命令提示符运行java -version。安装如果未安装可从 Oracle JDK 或 OpenJDK 官网下载。构建工具Maven版本 3.6。检查命令mvn -v。Gradle版本 7.x 或 8.x。检查命令gradle -v。二者任选其一即可本文示例将以Maven为主。集成开发环境 (IDE)推荐使用IntelliJ IDEA Ultimate/Community、Visual Studio Code或Eclipse它们对 Spring Boot 和 Maven/Gradle 有良好支持。网络环境由于需要从 Maven 中央仓库下载依赖以及后续会调用云端 AI 服务如 OpenAI请确保你的开发机具备稳定的网络连接。如果遇到依赖下载慢的问题可考虑配置国内镜像源。AI 服务商账户与 API Key这是 SpringAI 能工作的关键。你需要至少准备一个 AI 服务商的 API Key。OpenAI前往 OpenAI Platform 注册并创建 API Key。阿里云通义千问前往 阿里云百炼 开通服务并获取 API Key。智谱 AI前往 智谱开放平台 获取。其他SpringAI 还支持 Anthropic、Azure OpenAI、Hugging Face 等请根据需求准备。重要准备好 Key 后不要直接写在代码里我们下一步会教你怎么安全配置。4. 安装部署与启动方式SpringAI 不是一个需要独立安装的软件它是一个库依赖。因此“安装部署”实则是创建一个新的 Spring Boot 项目并引入 SpringAI 依赖。4.1 创建 Spring Boot 项目最快捷的方式是使用 Spring Initializr 。访问 Spring Initializr 网站。按以下选项进行配置Project: MavenLanguage: JavaSpring Boot: 选择最新的 3.x 稳定版本如 3.2.5Project Metadata:Group:com.example(可按需修改)Artifact:springai-demo(可按需修改)Name:springai-demoDescription: Demo project for Spring AIPackage name:com.example.springaidemoPackaging: JarJava: 17 或 21Dependencies: 在搜索框中添加以下依赖Spring Web- 用于构建 Web 接口。Spring AI- 这是核心。添加后你可以在生成的pom.xml中看到spring-ai-bom和具体的 starter如spring-ai-openai-spring-boot-starter。注意Spring Initializr 可能将 Spring AI 作为一个顶级选项直接勾选即可。点击Generate按钮下载项目压缩包。解压压缩包并用 IDE 打开该项目。4.2 检查与调整pom.xml打开项目中的pom.xml文件其内容应该类似于以下结构。关键是确保引入了正确的 Spring AI BOM物料清单和具体的 Starter。?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version !-- 版本可能更新 -- relativePath/ /parent groupIdcom.example/groupId artifactIdspringai-demo/artifactId version0.0.1-SNAPSHOT/version namespringai-demo/name descriptionDemo project for Spring AI/description properties java.version17/java.version spring-ai.version0.8.1/spring-ai.version !-- 注意Spring AI版本 -- /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI OpenAI Starter -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency !-- 测试依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies dependencyManagement dependencies !-- Spring AI BOM 管理所有Spring AI组件的版本 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project关键点说明spring-ai.version这个属性定义了 Spring AI 的版本。请使用 Initializr 生成的最新稳定版或查阅 Spring AI 官方文档 获取推荐版本。spring-ai-openai-spring-boot-starter这个依赖表示我们将使用 OpenAI 作为 AI 提供商。如果你想换用阿里通义依赖应替换为spring-ai-alibaba-spring-boot-starter。4.3 配置 API Key 与模型参数SpringAI 遵循 Spring Boot 的配置惯例。我们需要在src/main/resources/application.properties或application.yml中配置 AI 服务的连接信息。方式一使用application.properties(推荐初学者)# 应用基础配置 server.port8080 spring.application.namespringai-demo # OpenAI 配置 (示例) spring.ai.openai.api-key${OPENAI_API_KEY:your-openai-api-key-here} spring.ai.openai.chat.options.modelgpt-3.5-turbo # spring.ai.openai.chat.options.temperature0.7 # 阿里通义千问配置 (示例如使用需注释掉OpenAI配置并引入对应starter) # spring.ai.alibaba-chat.api-key${ALIBABA_API_KEY:your-alibaba-api-key-here} # spring.ai.alibaba-chat.chat.options.modelqwen-max # spring.ai.alibaba-chat.base-urlhttps://dashscope.aliyuncs.com/compatible-mode/v1方式二使用application.yml(更清晰的结构)server: port: 8080 spring: application: name: springai-demo ai: openai: api-key: ${OPENAI_API_KEY:your-openai-api-key-here} chat: options: model: gpt-3.5-turbo # temperature: 0.7 # alibaba-chat: # api-key: ${ALIBABA_API_KEY:your-alibaba-api-key-here} # chat: # options: # model: qwen-max # base-url: https://dashscope.aliyuncs.com/compatible-mode/v1安全配置最佳实践绝对不要将真实的 API Key 直接写在配置文件中并提交到代码仓库。上述配置中的${OPENAI_API_KEY:your-openai-api-key-here}是 Spring 的属性占位符。:your-openai-api-key-here是默认值仅用于本地测试且确保不提交生产环境务必删除。正确做法将OPENAI_API_KEY设置为环境变量。Linux/macOS:export OPENAI_API_KEYsk-xxxWindows (CMD):set OPENAI_API_KEYsk-xxxWindows (PowerShell):$env:OPENAI_API_KEYsk-xxx或者在 IDE 的运行配置中设置环境变量。这样应用启动时会自动读取环境变量中的值配置文件里只保留${OPENAI_API_KEY}。4.4 编写一个简单的测试接口为了验证环境是否配置成功我们创建一个简单的 REST 控制器。在src/main/java/com/example/springaidemo/目录下创建ChatController.javapackage com.example.springaidemo; import org.springframework.ai.chat.ChatClient; 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 ChatController { private final ChatClient chatClient; Autowired public ChatController(ChatClient chatClient) { this.chatClient chatClient; } GetMapping(/ai/chat) public MapString, String chat(RequestParam(value message, defaultValue Hello, who are you?) String message) { String response chatClient.call(message); return Map.of(question, message, answer, response); } }这个控制器注入了一个ChatClientBean由 Spring AI 自动配置提供并暴露了一个GET /ai/chat接口。调用时它会将接收到的消息转发给配置的 AI 模型并返回模型的回答。4.5 启动应用在 IDE 中找到主启动类通常名为SpringaiDemoApplication右键运行main方法。或者在项目根目录下使用 Maven 命令启动mvn spring-boot:run观察控制台日志如果没有错误看到类似Started SpringaiDemoApplication in X.XXX seconds的日志说明应用启动成功。5. 功能测试与效果验证环境搭建和启动只是第一步现在我们来验证 SpringAI 是否真的能工作。5.1 基础聊天功能测试应用启动后打开浏览器或使用任何 API 测试工具如 Postman、curl。测试 1浏览器直接访问在浏览器地址栏输入http://localhost:8080/ai/chat?message用中文介绍一下SpringAI如果一切正常你将看到一个 JSON 响应其中包含你的问题和 AI 模型的回答。测试 2使用 curl 命令打开终端执行curl http://localhost:8080/ai/chat?messageWhat%20is%20the%20capital%20of%20France?你应该收到类似这样的响应{question:What is the capital of France?,answer:The capital of France is Paris.}成功标准应用正常启动无报错。访问/ai/chat接口能收到 HTTP 200 响应。响应中的answer字段包含与问题相关的、由 AI 生成的合理文本。常见失败原因API Key 错误或未设置控制台会打印认证失败的错误信息。请检查环境变量是否设置正确或配置文件中默认的 Key 是否有效。网络问题无法连接到 OpenAI 等服务的 API 端点。检查网络连接和代理设置。依赖冲突或版本不兼容确保spring-ai.version与spring-boot.version兼容。参考官方文档的版本说明。端口冲突默认端口 8080 被占用。可以在application.properties中修改server.port。5.2 测试流式响应 (Streaming)流式响应对于需要实时显示生成结果的场景如聊天机器人非常重要。SpringAI 也提供了简单的支持。修改ChatController增加一个流式端点import org.springframework.ai.chat.ChatResponse; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.ai.chat.prompt.Prompt; 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 ChatController { private final ChatClient chatClient; private final ChatModel chatModel; // 注入 ChatModel 用于流式 Autowired public ChatController(ChatClient chatClient, ChatModel chatModel) { this.chatClient chatClient; this.chatModel chatModel; } // ... 原有的 chat 方法 ... GetMapping(value /ai/chat/stream, produces text/event-stream) public FluxString chatStream(RequestParam(value message, defaultValue Tell me a short story.) String message) { Prompt prompt new Prompt(new UserMessage(message)); FluxChatResponse responseFlux chatModel.stream(prompt); return responseFlux .map(chatResponse - chatResponse.getResult().getOutput().getContent()) .map(content - data: content \n\n); // 转换为 SSE 格式 } }这个端点返回text/event-stream类型符合 Server-Sent Events (SSE) 规范。你可以使用能处理 SSE 的客户端进行测试例如在浏览器中打开开发者工具的控制台运行一段 JavaScript 代码或者使用专门的工具。验证流式响应重启应用。使用curl测试流式接口注意-N参数禁用缓冲curl -N http://localhost:8080/ai/chat/stream?messageWrite%20a%20haiku%20about%20programming.你应该看到回答内容以数据块chunk的形式逐步输出而不是一次性返回。5.3 切换 AI 服务提供商这是 SpringAI 的核心优势之一。假设我们想从 OpenAI 切换到阿里通义千问。修改依赖在pom.xml中将spring-ai-openai-spring-boot-starter依赖替换为spring-ai-alibaba-spring-boot-starter。同时注释或删除 OpenAI 的 BOM 导入如果 Alibaba 有自己的 BOM 管理需参考其文档通常 Spring AI BOM 已统一管理。!-- 注释或删除 OpenAI starter -- !-- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency -- !-- 添加 Alibaba starter -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-alibaba-spring-boot-starter/artifactId /dependency注意不同 starter 的 artifactId 和版本请以 Spring AI 官方文档 为准。修改配置更新application.properties或application.yml。# 注释掉 OpenAI 配置 # spring.ai.openai.api-key${OPENAI_API_KEY} # spring.ai.openai.chat.options.modelgpt-3.5-turbo # 启用 Alibaba 配置 spring.ai.alibaba-chat.api-key${ALIBABA_API_KEY} spring.ai.alibaba-chat.chat.options.modelqwen-max spring.ai.alibaba-chat.base-urlhttps://dashscope.aliyuncs.com/compatible-mode/v1同样将ALIBABA_API_KEY设置为环境变量。重启应用并测试重启 Spring Boot 应用再次调用/ai/chat接口。你会发现业务代码ChatController一行未改但背后调用的 AI 模型已经切换成了通义千问。这个测试验证了 SpringAI 抽象层的价值业务逻辑与具体的 AI 服务商解耦。6. 接口 API 与批量任务6.1 构建更健壮的 API上面的示例只是一个起点。在实际项目中你需要更健壮的 API 设计。示例支持系统提示词和对话历史的聊天接口import org.springframework.ai.chat.messages.*; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.chat.prompt.SystemPromptTemplate; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; import java.util.List; import java.util.Map; RestController public class AdvancedChatController { private final ChatModel chatModel; // 构造器注入... PostMapping(/ai/chat/advanced) public MapString, Object advancedChat(RequestBody ChatRequest request) { // 1. 构建系统消息 SystemPromptTemplate systemPromptTemplate new SystemPromptTemplate(你是一个专业的{role}。请用{language}回答。); Message systemMessage systemPromptTemplate.createMessage(Map.of(role, 技术顾问, language, 中文)); // 2. 构建用户消息 Message userMessage new UserMessage(request.getMessage()); // 3. 构建提示可包含历史消息 Prompt prompt new Prompt(List.of(systemMessage, userMessage)); // 如果需要添加历史消息可以在这里将 request.getHistory() 转换为 Message 列表并加入 // 4. 调用模型 ChatResponse response chatModel.call(prompt); // 5. 构造返回 return Map.of( request, request, response, response.getResult().getOutput().getContent(), usage, response.getUsage() // 可能包含token消耗等信息 ); } // 内部类定义请求体 public static class ChatRequest { private String message; private ListMapString, String history; // 简单的历史记录表示 // getters and setters... } }这个接口通过RequestBody接收 JSON 请求支持自定义系统角色和语言并预留了对话历史的扩展能力。6.2 批量任务处理SpringAI 本身不提供内置的批量任务队列但你可以利用 Spring 框架的能力轻松实现。思路异步处理与线程池对于需要处理大量独立请求的场景可以使用Async注解和线程池来避免阻塞主线程。启用异步支持在主应用类上添加EnableAsync。创建服务层import org.springframework.ai.chat.ChatClient; import org.springframework.scheduling.annotation.Async; import org.springframework.stereotype.Service; import java.util.concurrent.CompletableFuture; Service public class BatchChatService { private final ChatClient chatClient; // 构造器注入... Async(taskExecutor) // 指定自定义线程池 public CompletableFutureString processSingleMessage(String message) { String response chatClient.call(message); // 这里可以加入更复杂的处理逻辑如保存到数据库 return CompletableFuture.completedFuture(response); } }配置线程池在配置类中import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor; import java.util.concurrent.Executor; Configuration public class AsyncConfig { Bean(name taskExecutor) public Executor taskExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(5); // 核心线程数 executor.setMaxPoolSize(10); // 最大线程数 executor.setQueueCapacity(100); // 队列容量 executor.setThreadNamePrefix(SpringAIAsync-); executor.initialize(); return executor; } }在控制器中调用PostMapping(/ai/chat/batch) public CompletableFutureListString batchChat(RequestBody ListString messages) { ListCompletableFutureString futures messages.stream() .map(batchChatService::processSingleMessage) .collect(Collectors.toList()); // 等待所有任务完成 return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])) .thenApply(v - futures.stream() .map(CompletableFuture::join) .collect(Collectors.toList())); }重要提醒批量调用第三方 AI API 时务必遵守其速率限制Rate Limit否则会导致请求失败。需要在代码中加入适当的延迟或使用更高级的限流器如 Resilience4j。7. 资源占用与性能观察由于 SpringAI 是客户端框架其本身的资源消耗CPU、内存与一个普通的 Spring Boot Web 应用无异。性能瓶颈和资源观察重点在于网络 I/O和对第三方 API 的调用。应用本身资源使用jconsole、jvisualvm或arthas等 JVM 监控工具观察堆内存、线程数、CPU 使用率。Spring Boot 应用通常内存占用在 200MB - 500MB 左右具体取决于业务复杂度。网络延迟AI 模型的响应时间Time to First Token, TTFT 和整体生成时间主导了接口的响应速度。可以在代码中记录每个请求的耗时或使用 APM 工具如 SkyWalking, Micrometer Prometheus进行监控。API 调用成本与限制Token 消耗关注ChatResponse中的Usage信息它通常包含本次请求消耗的 Prompt Tokens 和 Completion Tokens。这是计费的依据。速率限制监控调用失败率。如果出现大量429 Too Many Requests错误说明触发了速率限制需要调整调用频率或申请提升限额。连接池管理如果使用默认的 RestTemplate 或 WebClientSpring 会管理 HTTP 连接池。在高并发下可以调整连接池参数如最大连接数、超时时间以优化性能。性能优化建议使用流式响应对于生成较长内容的场景流式响应可以极大提升用户体验的“响应感”。合理设置超时为ChatClient或底层的 HTTP 客户端设置合理的连接超时和读取超时避免线程长时间阻塞。缓存对于重复性或可缓存的内容如某些标准问题的回答可以考虑使用 Spring Cache 将结果缓存起来。异步化如 6.2 节所述将耗时的 AI 调用放入线程池处理避免阻塞 Web 容器线程。8. 常见问题与排查方法问题现象可能原因排查方式解决方案启动失败报错No qualifying bean of type ChatClient1. 未引入正确的 Spring AI Starter 依赖。2. 依赖冲突导致自动配置失败。3. 配置文件中未正确配置 API Key导致 Bean 无法创建。1. 检查pom.xml或build.gradle中的依赖。2. 运行mvn dependency:tree查看依赖冲突。3. 检查控制台启动日志看是否有关于MissingApiKey或配置错误的警告。1. 确保引入了如spring-ai-openai-spring-boot-starter等正确的 starter。2. 排除冲突的依赖版本。3. 确保spring.ai.xxx.api-key配置正确且有效。调用接口返回 401 或 403 错误API Key 无效、过期或没有对应模型的访问权限。1. 检查环境变量或配置文件中的 Key 是否正确。2. 前往 AI 服务商控制台确认 Key 是否有效、额度是否充足、是否绑定了正确的模型。1. 重新生成并配置有效的 API Key。2. 在服务商控制台检查配额和模型访问权限。调用接口超时或连接被拒绝1. 网络问题无法访问 AI 服务商 API 端点。2. 本地代理设置导致连接失败。3. 服务商 API 服务暂时不可用。1. 使用ping或curl测试是否能访问 API 基础 URL如api.openai.com。2. 检查 IDE 或系统代理设置。3. 查看服务商状态页面。1. 检查网络连接配置代理或使用国内可访问的服务商如阿里云。2. 在 Spring 配置中为 RestTemplate 或 WebClient 配置代理。3. 等待服务恢复或联系服务商。流式接口不工作一次性返回所有内容1. 客户端未正确处理 SSE 流。2. 某些网关或代理服务器不支持或修改了 SSE 流。1. 使用curl -N命令测试确认服务端是否在流式输出。2. 检查是否经过了 Nginx 等反向代理确认其配置支持proxy_buffering off;对于 SSE 路径。1. 确保客户端代码能处理text/event-stream格式。2. 调整网关或代理配置以支持 SSE。依赖下载失败或版本冲突Maven 仓库网络问题或 Spring AI 版本与 Spring Boot 版本不兼容。1. 检查 Maven 配置尝试使用阿里云等国内镜像。2. 查看pom.xml中spring-ai.version属性对照 Spring AI 官方文档 的版本兼容性表格。1. 配置 Maven 镜像。2. 将 Spring AI 版本调整到与当前 Spring Boot 版本兼容的稳定版。ChatModel或ChatClient注入失败可能同时引入了多个 AI Provider 的 starter如 OpenAI 和 Alibaba且没有通过配置指定主要使用的那个。检查配置文件确保只激活了一个 Provider 的配置。或者使用Qualifier注解在注入时指定 Bean 的名称。1. 注释或删除不需要的 starter 依赖和配置。2. 使用Qualifier(openAiChatModel)等方式明确指定注入哪个 Bean。9. 最佳实践与使用建议配置管理永远不要提交 API Key使用环境变量、配置中心如 Spring Cloud Config、Apollo或密钥管理服务来管理敏感信息。多环境配置使用application-dev.properties、application-prod.properties来区分开发、测试、生产环境的配置如 API Endpoint、超时时间、模型版本。代码结构服务层抽象不要直接在 Controller 中调用ChatClient。创建一个 Service 层将 AI 调用逻辑封装起来便于维护、测试和切换实现。统一异常处理使用ControllerAdvice全局处理 AI 调用可能抛出的异常如超时、认证失败、额度不足并向客户端返回友好的错误信息。可观测性记录日志与监控为重要的 AI 调用记录日志包括请求、响应、耗时、Token 使用量。集成 Micrometer 将指标输出到 Prometheus监控调用成功率、延迟和 Token 消耗速率。设置熔断与降级使用 Resilience4j 或 Sentinel 为 AI 调用设置熔断器。当第三方服务不稳定时快速失败或返回预设的降级内容避免拖垮整个应用。安全与合规输入输出过滤对用户输入进行必要的清洗和过滤防止 Prompt 注入攻击。对 AI 返回的内容进行审核避免输出不当信息。用户数据隔离确保不同用户的会话和数据在调用 AI 时是隔离的防止信息泄露。合规使用了解并遵守所使用 AI 服务商的使用条款特别是关于生成内容版权和禁止用途的规定。开发与测试编写单元测试利用 Spring Boot 的测试切片对 Service 层进行单元测试可以 MockChatClient或ChatModel。集成测试在测试环境中配置一个测试用的 API Key或使用 Mock 服务确保整个调用链路畅通。版本化模型配置将模型名称、温度等参数也纳入配置管理。这样可以在不同环境或不同时间点快速切换模型版本进行 A/B 测试。10. 总结与下一步SpringAI 的环境设置并不复杂核心在于理解它是一个基于 Spring Boot 的“胶水”框架。通过本文的步骤你应该已经成功搭建了一个能调用云端大模型的基础 Spring Boot 应用。最值得尝试的点快速验证在几分钟内就能让一个 Spring Boot 应用“开口说话”。供应商无感通过修改配置即可在 OpenAI、通义千问等主流模型间切换代码无需改动。流式响应轻松实现类似 ChatGPT 的逐字输出体验。最先应该验证的功能 完成基础聊天后建议立即尝试更换不同的系统提示词观察 AI 行为的变化。测试 Embeddings 接口为后续的 RAG检索增强生成应用打下基础。尝试 Image 或 Audio 模块如果 starter 支持了解多模态能力的集成方式。最容易踩的坑API Key 泄露这是最高频的安全问题务必通过环境变量管理。版本兼容性Spring AI 迭代较快需严格对照官方文档的版本说明选择依赖。网络超时第三方 API 调用不稳定务必设置合理的超时和重试机制。后续扩展方向构建 RAG 应用结合 Spring AI 的 Vector Store 抽象支持 Redis、PgVector、Chroma 等将自有知识库与 AI 结合打造智能问答系统。开发 AI Agent利用 Spring AI 的函数调用Function Calling能力让 AI 能够操作工具、执行复杂任务。集成工作流引擎将 AI 调用节点嵌入到 Camunda、Flowable 等工作流中实现业务流程的智能化。探索本地模型研究如何通过spring-ai-ollama-spring-boot-starter或spring-ai-vertex-ai-spring-boot-starter连接本地部署的模型服务来调用本地大模型满足数据不出域的需求。环境设置只是起点SpringAI 真正的价值在于让 Java 开发者能以熟悉的方式快速、优雅地将强大的 AI 能力融入现有的企业级应用中。建议收藏本文在遇到配置问题时随时回顾排查清单。 SpringAI环境搭建指南：Java开发者快速集成大模型能力
这次我们来看 SpringAI 的环境设置。对于想快速上手 AI 应用开发的 Java 开发者来说SpringAI 提供了一个将大模型能力集成到 Spring 应用中的标准化方案。它最核心的价值在于你不用再为不同 AI 服务商如 OpenAI、阿里通义、智谱等的 API 差异而烦恼通过一套统一的抽象接口就能调用文本生成、图像理解、函数调用等多种 AI 能力。本文将带你从零开始完成 SpringAI 的环境搭建与基础验证。重点不是讲解复杂的 AI 概念而是确保你能在自己的开发机器上无论是 Windows、macOS 还是 Linux都能成功跑通第一个 SpringAI 应用。我们会重点关注几个实际问题项目依赖如何管理、API Key 如何安全配置、不同模型供应商如何切换以及如何通过一个简单的聊天接口验证环境是否就绪。如果你关心如何在 Spring Boot 项目中快速集成 AI 能力并希望后续能平滑地接入工作流或构建 Agent那么这篇文章可以直接跟着操作。1. 核心能力速览在深入配置之前我们先快速了解 SpringAI 是什么以及它能为你带来什么。能力项说明项目类型Spring 生态的官方 AI 集成框架提供了一套统一的 API 来调用多种大模型服务。开源团队Spring 官方团队主导开发与维护。主要功能1.Chat文本对话与生成。2.Embeddings文本向量化。3.Images文生图、图生文。4.Audio语音转文本STT。5.Vector Stores向量数据库集成。推荐环境Java 17 或更高版本Spring Boot 3.x构建工具Maven/Gradle。硬件门槛无特殊要求。SpringAI 本身是客户端框架推理计算发生在云端 AI 服务商如 OpenAI或你自行部署的本地模型服务端。你的开发机只需能运行 Java 和 Spring Boot 应用即可。启动方式标准的 Spring Boot 应用启动方式通过main方法或mvn spring-boot:run命令启动。是否支持 API是。SpringAI 本身不提供对外 API但它让你能在自己的 Spring Boot 应用中快速构建出 AI 功能 API。是否支持批量任务间接支持。可以通过编程方式循环调用或利用 Spring 的异步任务处理批量请求但具体并发能力受限于你集成的 AI 服务商的 API 限制。适合场景1. 快速为现有 Spring Boot 应用添加 AI 能力。2. 构建需要切换不同模型供应商的 AI 应用。3. 开发基于大模型的 Agent、工作流或业务系统。简单来说SpringAI 是一个“连接器”和“标准化层”。你的代码面向 SpringAI 的ChatClient、ChatModel等接口编程而具体背后是调用 OpenAI 的 GPT-4 还是阿里通义千问只需修改配置文件即可。2. 适用场景与使用边界适合谁Java/Spring 技术栈的开发者如果你熟悉 Spring Boot那么上手 SpringAI 几乎没有额外学习成本。需要快速验证 AI 能力的团队希望以最小代价在业务系统中集成聊天、摘要、翻译等 AI 功能。考虑模型供应商锁定的项目使用 SpringAI 的抽象层可以在 OpenAI、Anthropic、Azure OpenAI、本地模型等多种后端间灵活切换。能解决什么问题统一编程模型用同一套代码调用不同厂商的 AI API。简化配置通过 Spring Boot 的application.properties或application.yml文件集中管理 AI 模型参数和 API Key。快速集成提供开箱即用的ChatClient、VectorStore等组件无需从零编写 HTTP 客户端和解析逻辑。生态集成与 Spring 生态的其他项目如 Spring Data、Spring Security无缝结合便于构建企业级应用。不适合什么场景追求极致性能或最低延迟SpringAI 增加了一层抽象理论上会引入微小开销。对于超高频、超低延迟的裸 API 调用场景直接使用各厂商的 SDK 可能更直接。非 Java 技术栈如果你的主力技术栈是 Python、Node.js 等使用对应语言的 SDK 是更自然的选择。完全离线的本地模型推理虽然 SpringAI 支持通过LocalAI等项目连接本地模型但其主要设计目标是连接云端 API。复杂的本地模型加载、显存管理、性能优化并非其核心功能。安全与合规边界API Key 管理务必通过环境变量或安全的配置中心管理 API Key严禁将 Key 硬编码在代码或提交到版本库。内容安全你集成的 AI 服务商如 OpenAI有其自身的内容安全策略。你的应用需要额外考虑用户输入和 AI 输出的过滤与审核避免产生有害或违规内容。数据隐私向第三方 AI 服务发送数据时需了解其数据使用政策。对于敏感数据应考虑使用支持数据脱敏或本地部署的模型方案。版权与授权确保使用 AI 生成的内容如文本、图片符合版权法规特别是在商用场景下。3. 环境准备与前置条件开始之前请确保你的开发环境满足以下基本要求。这是后续所有步骤能顺利进行的基础。Java 开发套件 (JDK)版本JDK 17 或更高版本。Spring Boot 3.x 和 SpringAI 基于 Java 17 构建。推荐使用 JDK 17 或 JDK 21LTS版本。检查命令打开终端或命令提示符运行java -version。安装如果未安装可从 Oracle JDK 或 OpenJDK 官网下载。构建工具Maven版本 3.6。检查命令mvn -v。Gradle版本 7.x 或 8.x。检查命令gradle -v。二者任选其一即可本文示例将以Maven为主。集成开发环境 (IDE)推荐使用IntelliJ IDEA Ultimate/Community、Visual Studio Code或Eclipse它们对 Spring Boot 和 Maven/Gradle 有良好支持。网络环境由于需要从 Maven 中央仓库下载依赖以及后续会调用云端 AI 服务如 OpenAI请确保你的开发机具备稳定的网络连接。如果遇到依赖下载慢的问题可考虑配置国内镜像源。AI 服务商账户与 API Key这是 SpringAI 能工作的关键。你需要至少准备一个 AI 服务商的 API Key。OpenAI前往 OpenAI Platform 注册并创建 API Key。阿里云通义千问前往 阿里云百炼 开通服务并获取 API Key。智谱 AI前往 智谱开放平台 获取。其他SpringAI 还支持 Anthropic、Azure OpenAI、Hugging Face 等请根据需求准备。重要准备好 Key 后不要直接写在代码里我们下一步会教你怎么安全配置。4. 安装部署与启动方式SpringAI 不是一个需要独立安装的软件它是一个库依赖。因此“安装部署”实则是创建一个新的 Spring Boot 项目并引入 SpringAI 依赖。4.1 创建 Spring Boot 项目最快捷的方式是使用 Spring Initializr 。访问 Spring Initializr 网站。按以下选项进行配置Project: MavenLanguage: JavaSpring Boot: 选择最新的 3.x 稳定版本如 3.2.5Project Metadata:Group:com.example(可按需修改)Artifact:springai-demo(可按需修改)Name:springai-demoDescription: Demo project for Spring AIPackage name:com.example.springaidemoPackaging: JarJava: 17 或 21Dependencies: 在搜索框中添加以下依赖Spring Web- 用于构建 Web 接口。Spring AI- 这是核心。添加后你可以在生成的pom.xml中看到spring-ai-bom和具体的 starter如spring-ai-openai-spring-boot-starter。注意Spring Initializr 可能将 Spring AI 作为一个顶级选项直接勾选即可。点击Generate按钮下载项目压缩包。解压压缩包并用 IDE 打开该项目。4.2 检查与调整pom.xml打开项目中的pom.xml文件其内容应该类似于以下结构。关键是确保引入了正确的 Spring AI BOM物料清单和具体的 Starter。?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version !-- 版本可能更新 -- relativePath/ /parent groupIdcom.example/groupId artifactIdspringai-demo/artifactId version0.0.1-SNAPSHOT/version namespringai-demo/name descriptionDemo project for Spring AI/description properties java.version17/java.version spring-ai.version0.8.1/spring-ai.version !-- 注意Spring AI版本 -- /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI OpenAI Starter -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency !-- 测试依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies dependencyManagement dependencies !-- Spring AI BOM 管理所有Spring AI组件的版本 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project关键点说明spring-ai.version这个属性定义了 Spring AI 的版本。请使用 Initializr 生成的最新稳定版或查阅 Spring AI 官方文档 获取推荐版本。spring-ai-openai-spring-boot-starter这个依赖表示我们将使用 OpenAI 作为 AI 提供商。如果你想换用阿里通义依赖应替换为spring-ai-alibaba-spring-boot-starter。4.3 配置 API Key 与模型参数SpringAI 遵循 Spring Boot 的配置惯例。我们需要在src/main/resources/application.properties或application.yml中配置 AI 服务的连接信息。方式一使用application.properties(推荐初学者)# 应用基础配置 server.port8080 spring.application.namespringai-demo # OpenAI 配置 (示例) spring.ai.openai.api-key${OPENAI_API_KEY:your-openai-api-key-here} spring.ai.openai.chat.options.modelgpt-3.5-turbo # spring.ai.openai.chat.options.temperature0.7 # 阿里通义千问配置 (示例如使用需注释掉OpenAI配置并引入对应starter) # spring.ai.alibaba-chat.api-key${ALIBABA_API_KEY:your-alibaba-api-key-here} # spring.ai.alibaba-chat.chat.options.modelqwen-max # spring.ai.alibaba-chat.base-urlhttps://dashscope.aliyuncs.com/compatible-mode/v1方式二使用application.yml(更清晰的结构)server: port: 8080 spring: application: name: springai-demo ai: openai: api-key: ${OPENAI_API_KEY:your-openai-api-key-here} chat: options: model: gpt-3.5-turbo # temperature: 0.7 # alibaba-chat: # api-key: ${ALIBABA_API_KEY:your-alibaba-api-key-here} # chat: # options: # model: qwen-max # base-url: https://dashscope.aliyuncs.com/compatible-mode/v1安全配置最佳实践绝对不要将真实的 API Key 直接写在配置文件中并提交到代码仓库。上述配置中的${OPENAI_API_KEY:your-openai-api-key-here}是 Spring 的属性占位符。:your-openai-api-key-here是默认值仅用于本地测试且确保不提交生产环境务必删除。正确做法将OPENAI_API_KEY设置为环境变量。Linux/macOS:export OPENAI_API_KEYsk-xxxWindows (CMD):set OPENAI_API_KEYsk-xxxWindows (PowerShell):$env:OPENAI_API_KEYsk-xxx或者在 IDE 的运行配置中设置环境变量。这样应用启动时会自动读取环境变量中的值配置文件里只保留${OPENAI_API_KEY}。4.4 编写一个简单的测试接口为了验证环境是否配置成功我们创建一个简单的 REST 控制器。在src/main/java/com/example/springaidemo/目录下创建ChatController.javapackage com.example.springaidemo; import org.springframework.ai.chat.ChatClient; 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 ChatController { private final ChatClient chatClient; Autowired public ChatController(ChatClient chatClient) { this.chatClient chatClient; } GetMapping(/ai/chat) public MapString, String chat(RequestParam(value message, defaultValue Hello, who are you?) String message) { String response chatClient.call(message); return Map.of(question, message, answer, response); } }这个控制器注入了一个ChatClientBean由 Spring AI 自动配置提供并暴露了一个GET /ai/chat接口。调用时它会将接收到的消息转发给配置的 AI 模型并返回模型的回答。4.5 启动应用在 IDE 中找到主启动类通常名为SpringaiDemoApplication右键运行main方法。或者在项目根目录下使用 Maven 命令启动mvn spring-boot:run观察控制台日志如果没有错误看到类似Started SpringaiDemoApplication in X.XXX seconds的日志说明应用启动成功。5. 功能测试与效果验证环境搭建和启动只是第一步现在我们来验证 SpringAI 是否真的能工作。5.1 基础聊天功能测试应用启动后打开浏览器或使用任何 API 测试工具如 Postman、curl。测试 1浏览器直接访问在浏览器地址栏输入http://localhost:8080/ai/chat?message用中文介绍一下SpringAI如果一切正常你将看到一个 JSON 响应其中包含你的问题和 AI 模型的回答。测试 2使用 curl 命令打开终端执行curl http://localhost:8080/ai/chat?messageWhat%20is%20the%20capital%20of%20France?你应该收到类似这样的响应{question:What is the capital of France?,answer:The capital of France is Paris.}成功标准应用正常启动无报错。访问/ai/chat接口能收到 HTTP 200 响应。响应中的answer字段包含与问题相关的、由 AI 生成的合理文本。常见失败原因API Key 错误或未设置控制台会打印认证失败的错误信息。请检查环境变量是否设置正确或配置文件中默认的 Key 是否有效。网络问题无法连接到 OpenAI 等服务的 API 端点。检查网络连接和代理设置。依赖冲突或版本不兼容确保spring-ai.version与spring-boot.version兼容。参考官方文档的版本说明。端口冲突默认端口 8080 被占用。可以在application.properties中修改server.port。5.2 测试流式响应 (Streaming)流式响应对于需要实时显示生成结果的场景如聊天机器人非常重要。SpringAI 也提供了简单的支持。修改ChatController增加一个流式端点import org.springframework.ai.chat.ChatResponse; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.ai.chat.prompt.Prompt; 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 ChatController { private final ChatClient chatClient; private final ChatModel chatModel; // 注入 ChatModel 用于流式 Autowired public ChatController(ChatClient chatClient, ChatModel chatModel) { this.chatClient chatClient; this.chatModel chatModel; } // ... 原有的 chat 方法 ... GetMapping(value /ai/chat/stream, produces text/event-stream) public FluxString chatStream(RequestParam(value message, defaultValue Tell me a short story.) String message) { Prompt prompt new Prompt(new UserMessage(message)); FluxChatResponse responseFlux chatModel.stream(prompt); return responseFlux .map(chatResponse - chatResponse.getResult().getOutput().getContent()) .map(content - data: content \n\n); // 转换为 SSE 格式 } }这个端点返回text/event-stream类型符合 Server-Sent Events (SSE) 规范。你可以使用能处理 SSE 的客户端进行测试例如在浏览器中打开开发者工具的控制台运行一段 JavaScript 代码或者使用专门的工具。验证流式响应重启应用。使用curl测试流式接口注意-N参数禁用缓冲curl -N http://localhost:8080/ai/chat/stream?messageWrite%20a%20haiku%20about%20programming.你应该看到回答内容以数据块chunk的形式逐步输出而不是一次性返回。5.3 切换 AI 服务提供商这是 SpringAI 的核心优势之一。假设我们想从 OpenAI 切换到阿里通义千问。修改依赖在pom.xml中将spring-ai-openai-spring-boot-starter依赖替换为spring-ai-alibaba-spring-boot-starter。同时注释或删除 OpenAI 的 BOM 导入如果 Alibaba 有自己的 BOM 管理需参考其文档通常 Spring AI BOM 已统一管理。!-- 注释或删除 OpenAI starter -- !-- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency -- !-- 添加 Alibaba starter -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-alibaba-spring-boot-starter/artifactId /dependency注意不同 starter 的 artifactId 和版本请以 Spring AI 官方文档 为准。修改配置更新application.properties或application.yml。# 注释掉 OpenAI 配置 # spring.ai.openai.api-key${OPENAI_API_KEY} # spring.ai.openai.chat.options.modelgpt-3.5-turbo # 启用 Alibaba 配置 spring.ai.alibaba-chat.api-key${ALIBABA_API_KEY} spring.ai.alibaba-chat.chat.options.modelqwen-max spring.ai.alibaba-chat.base-urlhttps://dashscope.aliyuncs.com/compatible-mode/v1同样将ALIBABA_API_KEY设置为环境变量。重启应用并测试重启 Spring Boot 应用再次调用/ai/chat接口。你会发现业务代码ChatController一行未改但背后调用的 AI 模型已经切换成了通义千问。这个测试验证了 SpringAI 抽象层的价值业务逻辑与具体的 AI 服务商解耦。6. 接口 API 与批量任务6.1 构建更健壮的 API上面的示例只是一个起点。在实际项目中你需要更健壮的 API 设计。示例支持系统提示词和对话历史的聊天接口import org.springframework.ai.chat.messages.*; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.chat.prompt.SystemPromptTemplate; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; import java.util.List; import java.util.Map; RestController public class AdvancedChatController { private final ChatModel chatModel; // 构造器注入... PostMapping(/ai/chat/advanced) public MapString, Object advancedChat(RequestBody ChatRequest request) { // 1. 构建系统消息 SystemPromptTemplate systemPromptTemplate new SystemPromptTemplate(你是一个专业的{role}。请用{language}回答。); Message systemMessage systemPromptTemplate.createMessage(Map.of(role, 技术顾问, language, 中文)); // 2. 构建用户消息 Message userMessage new UserMessage(request.getMessage()); // 3. 构建提示可包含历史消息 Prompt prompt new Prompt(List.of(systemMessage, userMessage)); // 如果需要添加历史消息可以在这里将 request.getHistory() 转换为 Message 列表并加入 // 4. 调用模型 ChatResponse response chatModel.call(prompt); // 5. 构造返回 return Map.of( request, request, response, response.getResult().getOutput().getContent(), usage, response.getUsage() // 可能包含token消耗等信息 ); } // 内部类定义请求体 public static class ChatRequest { private String message; private ListMapString, String history; // 简单的历史记录表示 // getters and setters... } }这个接口通过RequestBody接收 JSON 请求支持自定义系统角色和语言并预留了对话历史的扩展能力。6.2 批量任务处理SpringAI 本身不提供内置的批量任务队列但你可以利用 Spring 框架的能力轻松实现。思路异步处理与线程池对于需要处理大量独立请求的场景可以使用Async注解和线程池来避免阻塞主线程。启用异步支持在主应用类上添加EnableAsync。创建服务层import org.springframework.ai.chat.ChatClient; import org.springframework.scheduling.annotation.Async; import org.springframework.stereotype.Service; import java.util.concurrent.CompletableFuture; Service public class BatchChatService { private final ChatClient chatClient; // 构造器注入... Async(taskExecutor) // 指定自定义线程池 public CompletableFutureString processSingleMessage(String message) { String response chatClient.call(message); // 这里可以加入更复杂的处理逻辑如保存到数据库 return CompletableFuture.completedFuture(response); } }配置线程池在配置类中import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor; import java.util.concurrent.Executor; Configuration public class AsyncConfig { Bean(name taskExecutor) public Executor taskExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(5); // 核心线程数 executor.setMaxPoolSize(10); // 最大线程数 executor.setQueueCapacity(100); // 队列容量 executor.setThreadNamePrefix(SpringAIAsync-); executor.initialize(); return executor; } }在控制器中调用PostMapping(/ai/chat/batch) public CompletableFutureListString batchChat(RequestBody ListString messages) { ListCompletableFutureString futures messages.stream() .map(batchChatService::processSingleMessage) .collect(Collectors.toList()); // 等待所有任务完成 return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])) .thenApply(v - futures.stream() .map(CompletableFuture::join) .collect(Collectors.toList())); }重要提醒批量调用第三方 AI API 时务必遵守其速率限制Rate Limit否则会导致请求失败。需要在代码中加入适当的延迟或使用更高级的限流器如 Resilience4j。7. 资源占用与性能观察由于 SpringAI 是客户端框架其本身的资源消耗CPU、内存与一个普通的 Spring Boot Web 应用无异。性能瓶颈和资源观察重点在于网络 I/O和对第三方 API 的调用。应用本身资源使用jconsole、jvisualvm或arthas等 JVM 监控工具观察堆内存、线程数、CPU 使用率。Spring Boot 应用通常内存占用在 200MB - 500MB 左右具体取决于业务复杂度。网络延迟AI 模型的响应时间Time to First Token, TTFT 和整体生成时间主导了接口的响应速度。可以在代码中记录每个请求的耗时或使用 APM 工具如 SkyWalking, Micrometer Prometheus进行监控。API 调用成本与限制Token 消耗关注ChatResponse中的Usage信息它通常包含本次请求消耗的 Prompt Tokens 和 Completion Tokens。这是计费的依据。速率限制监控调用失败率。如果出现大量429 Too Many Requests错误说明触发了速率限制需要调整调用频率或申请提升限额。连接池管理如果使用默认的 RestTemplate 或 WebClientSpring 会管理 HTTP 连接池。在高并发下可以调整连接池参数如最大连接数、超时时间以优化性能。性能优化建议使用流式响应对于生成较长内容的场景流式响应可以极大提升用户体验的“响应感”。合理设置超时为ChatClient或底层的 HTTP 客户端设置合理的连接超时和读取超时避免线程长时间阻塞。缓存对于重复性或可缓存的内容如某些标准问题的回答可以考虑使用 Spring Cache 将结果缓存起来。异步化如 6.2 节所述将耗时的 AI 调用放入线程池处理避免阻塞 Web 容器线程。8. 常见问题与排查方法问题现象可能原因排查方式解决方案启动失败报错No qualifying bean of type ChatClient1. 未引入正确的 Spring AI Starter 依赖。2. 依赖冲突导致自动配置失败。3. 配置文件中未正确配置 API Key导致 Bean 无法创建。1. 检查pom.xml或build.gradle中的依赖。2. 运行mvn dependency:tree查看依赖冲突。3. 检查控制台启动日志看是否有关于MissingApiKey或配置错误的警告。1. 确保引入了如spring-ai-openai-spring-boot-starter等正确的 starter。2. 排除冲突的依赖版本。3. 确保spring.ai.xxx.api-key配置正确且有效。调用接口返回 401 或 403 错误API Key 无效、过期或没有对应模型的访问权限。1. 检查环境变量或配置文件中的 Key 是否正确。2. 前往 AI 服务商控制台确认 Key 是否有效、额度是否充足、是否绑定了正确的模型。1. 重新生成并配置有效的 API Key。2. 在服务商控制台检查配额和模型访问权限。调用接口超时或连接被拒绝1. 网络问题无法访问 AI 服务商 API 端点。2. 本地代理设置导致连接失败。3. 服务商 API 服务暂时不可用。1. 使用ping或curl测试是否能访问 API 基础 URL如api.openai.com。2. 检查 IDE 或系统代理设置。3. 查看服务商状态页面。1. 检查网络连接配置代理或使用国内可访问的服务商如阿里云。2. 在 Spring 配置中为 RestTemplate 或 WebClient 配置代理。3. 等待服务恢复或联系服务商。流式接口不工作一次性返回所有内容1. 客户端未正确处理 SSE 流。2. 某些网关或代理服务器不支持或修改了 SSE 流。1. 使用curl -N命令测试确认服务端是否在流式输出。2. 检查是否经过了 Nginx 等反向代理确认其配置支持proxy_buffering off;对于 SSE 路径。1. 确保客户端代码能处理text/event-stream格式。2. 调整网关或代理配置以支持 SSE。依赖下载失败或版本冲突Maven 仓库网络问题或 Spring AI 版本与 Spring Boot 版本不兼容。1. 检查 Maven 配置尝试使用阿里云等国内镜像。2. 查看pom.xml中spring-ai.version属性对照 Spring AI 官方文档 的版本兼容性表格。1. 配置 Maven 镜像。2. 将 Spring AI 版本调整到与当前 Spring Boot 版本兼容的稳定版。ChatModel或ChatClient注入失败可能同时引入了多个 AI Provider 的 starter如 OpenAI 和 Alibaba且没有通过配置指定主要使用的那个。检查配置文件确保只激活了一个 Provider 的配置。或者使用Qualifier注解在注入时指定 Bean 的名称。1. 注释或删除不需要的 starter 依赖和配置。2. 使用Qualifier(openAiChatModel)等方式明确指定注入哪个 Bean。9. 最佳实践与使用建议配置管理永远不要提交 API Key使用环境变量、配置中心如 Spring Cloud Config、Apollo或密钥管理服务来管理敏感信息。多环境配置使用application-dev.properties、application-prod.properties来区分开发、测试、生产环境的配置如 API Endpoint、超时时间、模型版本。代码结构服务层抽象不要直接在 Controller 中调用ChatClient。创建一个 Service 层将 AI 调用逻辑封装起来便于维护、测试和切换实现。统一异常处理使用ControllerAdvice全局处理 AI 调用可能抛出的异常如超时、认证失败、额度不足并向客户端返回友好的错误信息。可观测性记录日志与监控为重要的 AI 调用记录日志包括请求、响应、耗时、Token 使用量。集成 Micrometer 将指标输出到 Prometheus监控调用成功率、延迟和 Token 消耗速率。设置熔断与降级使用 Resilience4j 或 Sentinel 为 AI 调用设置熔断器。当第三方服务不稳定时快速失败或返回预设的降级内容避免拖垮整个应用。安全与合规输入输出过滤对用户输入进行必要的清洗和过滤防止 Prompt 注入攻击。对 AI 返回的内容进行审核避免输出不当信息。用户数据隔离确保不同用户的会话和数据在调用 AI 时是隔离的防止信息泄露。合规使用了解并遵守所使用 AI 服务商的使用条款特别是关于生成内容版权和禁止用途的规定。开发与测试编写单元测试利用 Spring Boot 的测试切片对 Service 层进行单元测试可以 MockChatClient或ChatModel。集成测试在测试环境中配置一个测试用的 API Key或使用 Mock 服务确保整个调用链路畅通。版本化模型配置将模型名称、温度等参数也纳入配置管理。这样可以在不同环境或不同时间点快速切换模型版本进行 A/B 测试。10. 总结与下一步SpringAI 的环境设置并不复杂核心在于理解它是一个基于 Spring Boot 的“胶水”框架。通过本文的步骤你应该已经成功搭建了一个能调用云端大模型的基础 Spring Boot 应用。最值得尝试的点快速验证在几分钟内就能让一个 Spring Boot 应用“开口说话”。供应商无感通过修改配置即可在 OpenAI、通义千问等主流模型间切换代码无需改动。流式响应轻松实现类似 ChatGPT 的逐字输出体验。最先应该验证的功能 完成基础聊天后建议立即尝试更换不同的系统提示词观察 AI 行为的变化。测试 Embeddings 接口为后续的 RAG检索增强生成应用打下基础。尝试 Image 或 Audio 模块如果 starter 支持了解多模态能力的集成方式。最容易踩的坑API Key 泄露这是最高频的安全问题务必通过环境变量管理。版本兼容性Spring AI 迭代较快需严格对照官方文档的版本说明选择依赖。网络超时第三方 API 调用不稳定务必设置合理的超时和重试机制。后续扩展方向构建 RAG 应用结合 Spring AI 的 Vector Store 抽象支持 Redis、PgVector、Chroma 等将自有知识库与 AI 结合打造智能问答系统。开发 AI Agent利用 Spring AI 的函数调用Function Calling能力让 AI 能够操作工具、执行复杂任务。集成工作流引擎将 AI 调用节点嵌入到 Camunda、Flowable 等工作流中实现业务流程的智能化。探索本地模型研究如何通过spring-ai-ollama-spring-boot-starter或spring-ai-vertex-ai-spring-boot-starter连接本地部署的模型服务来调用本地大模型满足数据不出域的需求。环境设置只是起点SpringAI 真正的价值在于让 Java 开发者能以熟悉的方式快速、优雅地将强大的 AI 能力融入现有的企业级应用中。建议收藏本文在遇到配置问题时随时回顾排查清单。