这次我们来看 SpringAI 的环境设置。对于想快速上手 AI 应用开发的 Java 开发者来说SpringAI 提供了一个非常友好的框架让你能像调用普通服务一样集成大语言模型。但第一步也是最关键的一步就是把环境搭起来。这篇文章不讲复杂概念直接告诉你 SpringAI 4 的环境怎么配从依赖、配置到第一个能跑的 Demo全程踩坑点都会覆盖。SpringAI 的核心是简化 AI 能力的集成。它最值得关注的几个特点是第一它提供了统一的 API 来对接 OpenAI、Azure OpenAI、Ollama、阿里云灵积等多种模型服务你不用为每个服务写不同的客户端代码。第二它深度集成 Spring Boot配置方式非常“Spring”有经验的开发者几乎零学习成本。第三它支持流式响应、函数调用等高级特性方便构建复杂的 AI Agent。本文会带你完成从零开始的完整环境搭建包括依赖引入、配置文件编写、模型服务连接测试并重点说明在 Mac、Windows 以及使用 UV 等不同环境下的关键配置差异。1. 核心能力速览在动手之前先快速了解 SpringAI 4 的环境要求和核心能力这能帮你判断它是否适合你的项目。能力项说明项目类型Spring Boot 生态的 AI 应用开发框架主要功能统一 API 调用多种大模型OpenAI, Ollama, 阿里云等、支持 Prompt 模板、流式响应、函数调用、上下文管理、向量数据库集成等环境门槛Java 17是硬性要求推荐 Java 21。需要 Maven 3.6 或 Gradle 7.x。启动方式标准的 Spring Boot 应用启动方式mvn spring-boot:run或运行main方法是否支持 API是。SpringAI 本身不提供对外 HTTP API但你可以轻松在 Spring Boot 中创建RestController来暴露 AI 能力。是否支持“批量任务”间接支持。可以通过编程方式循环调用或利用 Spring Batch 等框架结合 SpringAI 客户端处理批量提示词。模型依赖无需本地部署模型。主要依赖远程模型服务如 OpenAI API或本地运行的模型服务如 Ollama。因此对本地显卡无要求。适合场景快速为 Java 应用添加 AI 对话、内容生成、总结、翻译等能力构建企业级 AI Agent需要与现有 Spring 技术栈深度集成的项目。2. 适用场景与使用边界SpringAI 非常适合已经熟悉 Spring Boot 生态的团队或个人开发者希望以最低的集成成本为应用注入 AI 能力。它能解决的核心问题是“模型接入的碎片化”。你不用再为 OpenAI 写一套 HTTP 客户端为 Ollama 写另一套SpringAI 的ChatClient或ChatModel接口提供了统一的抽象。它适合做什么快速原型验证几分钟内连接上模型服务开始测试提示词效果。企业应用集成在已有的 Spring Cloud、Spring Security 体系中无缝加入 AI 功能。构建复杂 AI Agent利用其 Prompt 模板、函数调用、上下文管理能力构建多步骤的智能工作流。需要流式响应的场景如构建类似 ChatGPT 的逐字输出体验。它不适合或需注意什么极致性能与底层控制如果你需要对网络请求、连接池、重试策略进行毫米级优化可能需要直接使用模型服务商的原生 SDK。非 Java/Spring 技术栈如果你的项目不是基于 Java那么 SpringAI 并不适用。模型训练与微调SpringAI 专注于推理和对话不提供模型训练能力。成本与合规使用远程模型 API如 OpenAI会产生费用且数据会发送到第三方服务器需注意企业数据安全和合规要求。使用本地模型如通过 Ollama则无此顾虑。3. 环境准备与前置条件开始之前请确保你的开发环境满足以下最低要求。这是后续所有步骤的基础。Java 开发工具包 (JDK)版本必须使用Java 17 或更高版本。SpringAI 4 基于 Spring Boot 3.x后者强制要求 Java 17。强烈推荐使用Java 21 (LTS)以获得最佳性能和兼容性。检查命令打开终端或命令提示符运行java -version。# 预期输出类似 openjdk version 21.0.3 2024-04-16 OpenJDK Runtime Environment (build 21.0.39-57) OpenJDK Build (build 21.0.39-57, mixed mode, sharing)安装如果未安装或版本过低请从 Adoptium 或 Oracle 官网下载安装。构建工具Maven版本 3.6 或更高。检查命令mvn -v。Gradle版本 7.x 或更高推荐 8.x。检查命令gradle -v。二者任选其一即可本文后续示例以Maven为主。集成开发环境 (IDE)推荐使用IntelliJ IDEA Ultimate/Community、Visual Studio Code需安装 Java 扩展包或Eclipse。它们对 Spring Boot 有良好的支持。模型服务准备二选一选项A使用远程 API如 OpenAI你需要一个有效的 API Key。前往 OpenAI Platform 注册并获取。选项B使用本地模型如 Ollama需要在本地安装并运行 Ollama。前往 Ollama 官网 下载安装并拉取一个模型例如ollama pull llama3.2然后运行ollama serve启动服务。网络环境如果使用远程 API请确保你的网络能够稳定访问对应的服务地址。4. 创建项目与依赖引入一切就绪我们开始创建 Spring Boot 项目并引入 SpringAI 依赖。4.1 使用 Spring Initializr 创建项目最快捷的方式是使用 start.spring.io 。访问网站。进行如下配置Project: MavenLanguage: JavaSpring Boot: 选择最新的稳定版如 3.3.xProject Metadata:Group:com.exampleArtifact:springai-demoName:springai-demoPackage name:com.example.springaidemoPackaging: JarJava: 21Dependencies: 点击 “ADD DEPENDENCIES”搜索并添加Spring Web- 用于创建 REST API。Spring Boot DevTools- 可选用于热加载提升开发体验。点击 “GENERATE” 下载项目压缩包并解压到本地目录。4.2 添加 SpringAI 依赖打开项目中的pom.xml文件。SpringAI 的依赖尚未直接集成到 Initializr需要手动添加。首先添加 SpringAI 的 BOM (Bill of Materials)到dependencyManagement部分。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然后在dependencies部分添加你需要的具体 Starter。这里以连接 OpenAI 和 Ollama 为例dependencies !-- Spring Boot 基础依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId scoperuntime/scope optionaltrue/optional /dependency !-- SpringAI OpenAI 支持 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency !-- SpringAI Ollama 支持 (如果需要连接本地模型) -- !-- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId /dependency -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies注意SpringAI 版本迭代较快请务必访问 SpringAI 官方文档 查看最新的稳定版版本号替换掉上面的1.0.0-M4。M4表示里程碑版本生产环境建议等待GA(General Availability) 版本。4.3 关于 UV 环境针对 Mac/Linux 开发者网络热词中提到了 “macbook设置uv环境”。uv是一个用 Rust 编写的、极其快速的 Python 包管理器和解析器。但请注意SpringAI 是 Java 项目不直接依赖 Python 或uv。这个热词可能源于一些 AI 项目如使用 LangChain 的 Python 项目的配置经验被混用了。对于 SpringAI你只需要管理好Java 环境JDK和构建工具Maven/Gradle即可。如果你同时在进行 Python AI 开发uv是一个优秀的工具但它与 SpringAI 的 Java 环境设置是并行且独立的两件事。5. 关键配置详解依赖添加后下一步是配置应用程序告诉它如何连接模型服务。配置主要在application.properties或application.yml文件中进行。5.1 配置 OpenAI使用远程 API如果你选择使用 OpenAI配置如下application.yml格式 (推荐)spring: ai: openai: api-key: ${OPENAI_API_KEY:sk-your-openai-api-key-here} # 优先从环境变量读取找不到则用默认值 chat: options: model: gpt-4o-mini # 或 gpt-4-turbo, gpt-3.5-turbo temperature: 0.7或者使用application.properties格式spring.ai.openai.api-key${OPENAI_API_KEY:sk-your-openai-api-key-here} spring.ai.openai.chat.options.modelgpt-4o-mini spring.ai.openai.chat.options.temperature0.7重要安全提示永远不要将真实的 API Key 硬编码在代码或配置文件中提交到版本控制系统如 Git。上述示例中的sk-your-openai-api-key-here只是一个占位符。正确的做法是使用环境变量在启动应用前设置环境变量。Linux/macOS:export OPENAI_API_KEYsk-your-real-keyWindows (CMD):set OPENAI_API_KEYsk-your-real-keyWindows (PowerShell):$env:OPENAI_API_KEYsk-your-real-key在配置文件中只写spring.ai.openai.api-key${OPENAI_API_KEY}。这样应用启动时会自动从环境变量读取。5.2 配置 Ollama使用本地模型如果你在本地运行了 Ollama 服务默认地址http://localhost:11434配置如下spring: ai: ollama: base-url: http://localhost:11434 # Ollama 服务地址 chat: options: model: llama3.2 # 你通过 ollama pull 拉取的模型名称5.3 多模型配置与激活SpringAI 允许你配置多个模型连接并通过spring.ai.openai.chat.enabledtrue/false或 Profile 来激活其中一个。例如你可以同时配置 OpenAI 和 Ollama但默认禁用 Ollamaspring: ai: openai: api-key: ${OPENAI_API_KEY} chat: enabled: true # 默认启用 OpenAI options: model: gpt-4o-mini ollama: base-url: http://localhost:11434 chat: enabled: false # 默认禁用 Ollama options: model: llama3.2然后你可以通过启动命令--spring.profiles.activeollama来切换到 Ollama 模型。6. 编写第一个 AI 对话接口配置完成后我们来写一个简单的 REST 控制器验证环境是否工作正常。在src/main/java/com/example/springaidemo目录下创建AiController.javapackage com.example.springaidemo; import org.springframework.ai.chat.client.ChatClient; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController public class AiController { private final ChatClient chatClient; // 构造器注入 ChatClientSpringAI 会自动配置 public AiController(ChatClient chatClient) { this.chatClient chatClient; } GetMapping(/ai/chat) public String chat(RequestParam(value message, defaultValue Hello, who are you?) String message) { // 同步调用获取完整的响应字符串 String response chatClient.prompt() .user(message) .call() .content(); return response; } GetMapping(/ai/chat/stream) public String chatStream(RequestParam(value message, defaultValue Tell me a short joke.) String message) { // 流式调用收集所有片段后返回演示用实际应使用 SSE/WebFlux StringBuilder fullResponse new StringBuilder(); chatClient.prompt() .user(message) .stream() .content() // 返回 FluxString .doOnNext(chunk - { System.out.print(chunk); // 在控制台看到流式效果 fullResponse.append(chunk); }) .blockLast(); // 仅为演示阻塞直到流结束 return fullResponse.toString(); } }这段代码做了两件事/ai/chat接口同步调用模型一次性返回所有结果。/ai/chat/stream接口演示流式调用。它会逐块打印响应到控制台最后将所有块拼接返回。注意在真正的 Web 应用中流式响应应使用SseEmitter或 Spring WebFlux 的Flux返回给前端这里简化了。7. 启动服务与功能测试7.1 启动 Spring Boot 应用在项目根目录下运行 Maven 命令mvn spring-boot:run或者直接在 IDE 中运行SpringaiDemoApplication类的main方法。看到控制台输出类似以下的日志说明启动成功Started SpringaiDemoApplication in 3.456 seconds (process running for 3.789)7.2 测试接口打开浏览器或使用curl、Postman 等工具进行测试。测试同步接口GET http://localhost:8080/ai/chat?message用一句话介绍SpringAI预期返回一个连贯的、介绍 SpringAI 的句子。测试流式接口观察控制台GET http://localhost:8080/ai/chat/stream?message讲一个关于编程的笑话此时你应该能在启动应用的终端或 IDE 控制台中看到笑话被逐词或逐句地打印出来而不是一次性全部出现。这就是流式响应的效果。7.3 验证核心功能连接验证如果接口返回了合理的 AI 生成内容说明 SpringAI 成功连接到了你配置的模型服务OpenAI 或 Ollama。配置验证修改application.yml中的temperature参数例如改为 0.1 或 1.0重新提问同样的问题观察回答的创造性是否发生变化。temperature越低回答越确定和保守越高越随机和有创造性。模型切换验证如果配置了多模型通过修改配置或切换 Profile测试不同的模型是否能正常工作。8. 深入使用 ChatModel 与流式处理上面的例子使用了高级的ChatClient。SpringAI 也提供了更底层的ChatModel接口。网络热词中提到的springai fluxchatresponse stream chatmodel.stream(prompt) 读取text正是这种用法。下面是一个在 Service 层使用ChatModel进行流式处理的示例package com.example.springaidemo.service; import org.springframework.ai.chat.model.ChatModel; import org.springframework.ai.chat.model.ChatResponse; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.stereotype.Service; import reactor.core.publisher.Flux; Service public class AdvancedAiService { private final ChatModel chatModel; public AdvancedAiService(ChatModel chatModel) { this.chatModel chatModel; } public String getSyncResponse(String userMessage) { Prompt prompt new Prompt(new UserMessage(userMessage)); ChatResponse response chatModel.call(prompt); return response.getResult().getOutput().getContent(); } public FluxString getStreamResponse(String userMessage) { Prompt prompt new Prompt(new UserMessage(userMessage)); FluxChatResponse responseFlux chatModel.stream(prompt); // 将 FluxChatResponse 转换为 FluxString (内容块) return responseFlux .map(chatResponse - chatResponse.getResult().getOutput().getContent()) .filter(content - content ! null !content.isEmpty()); } }然后在 Controller 中注入这个 ServicegetStreamResponse方法返回的FluxString可以直接被 Spring WebFlux 的GetMapping(produces MediaType.TEXT_EVENT_STREAM_VALUE)接口使用实现真正的服务器发送事件 (SSE) 流式输出。9. 常见问题与排查方法环境设置过程中你可能会遇到以下问题问题现象可能原因排查方式解决方案启动失败报错java.lang.UnsupportedClassVersionErrorJDK 版本过低不满足 Java 17 要求。运行java -version确认版本。升级 JDK 至 17 或 21。依赖下载失败提示Could not find artifact org.springframework.ai:spring-ai-bom:pom:xxx1. Maven 仓库网络问题。2. 使用的 SpringAI 版本号不存在或太新。1. 检查网络尝试mvn clean compile -U。2. 访问 SpringAI 仓库 确认版本号。1. 配置国内镜像源如阿里云。2. 在pom.xml中使用官方文档确认的稳定版本号。应用启动成功但调用接口返回401或Connection refused模型服务连接失败。1. (OpenAI) API Key 错误或未设置。2. (Ollama) 服务未启动。1. 检查环境变量OPENAI_API_KEY是否已设置且正确。2. 运行ollama serve并访问http://localhost:11434看是否正常。1. 重新设置正确的 API Key 环境变量。2. 启动 Ollama 服务并确保配置中的base-url正确。调用接口超时1. 网络问题无法访问远程 API。2. 模型响应过慢。1. 使用curl或ping测试网络连通性。2. 尝试一个更简单的提示词。1. 检查代理或防火墙设置。2. 对于 Ollama尝试更小的模型对于 OpenAI检查是否有速率限制。流式接口没有“逐字输出”效果在 Controller 中错误地等待流结束如使用了collectList().block()后才返回。检查接口返回值类型和逻辑。确保接口返回类型为FluxString或使用SseEmitter并且不阻塞流。配置了多个模型不知道当前用的是哪个未明确激活哪个配置或依赖冲突。查看启动日志搜索ChatModel或ChatClient的初始化信息。在application.yml中明确设置spring.ai.openai.chat.enabledtrue/false或使用 Profile 隔离配置。10. 最佳实践与下一步成功运行第一个 SpringAI 应用只是开始。以下是一些进阶建议配置管理始终使用环境变量或配置中心如 Spring Cloud Config来管理 API Key 等敏感信息。绝对不要提交到 Git。异常处理在调用ChatClient或ChatModel时使用try-catch处理可能的异常如网络超时、额度不足、模型不可用等给用户友好的提示。提示词工程SpringAI 支持强大的PromptTemplate。将复杂的提示词模板化、参数化并存储在配置文件或数据库中便于管理和迭代。Bean public PromptTemplate rolePromptTemplate() { return new PromptTemplate(你是一个专业的{role}。请用{style}的风格回答以下问题\n{question}); }连接池与超时在生产环境中合理配置 HTTP 客户端的连接池、超时时间和重试策略以提高应用的健壮性。走向 Agent 与工作流探索 SpringAI 的Function Calling和Agent特性。这允许 AI 模型调用你提供的工具函数如查询数据库、调用外部 API从而实现复杂的自动化工作流即网络热词中提到的“会搭建工作流”。向量数据库集成如果需要让模型基于你的私有知识库回答问题可以集成 SpringAI 对 Pinecone、Redis、PGVector 等向量数据库的支持实现 RAG检索增强生成应用。SpringAI 将 AI 能力变成了 Spring 开发者熟悉的“依赖注入”和“配置驱动”模式。环境设置的核心就是引入正确的 Starter、配置好模型连接信息。完成这一步后你就能将全部精力投入到 Prompt 设计、业务逻辑和用户体验优化上而不用再操心不同模型 API 的差异。建议从同步调用开始验证整个链路然后逐步尝试流式响应和函数调用最终构建出真正智能的应用 Agent。
