企业官网建设流程全解析

这次我们来看 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 的环境要求和核心能力，这能帮你判断它是否适合你的项目。

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. 环境准备与前置条件

开始之前，请确保你的开发环境满足以下最低要求。这是后续所有步骤的基础。

1. 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.3+9-57) OpenJDK Build (build 21.0.3+9-57, mixed mode, sharing)

   • 安装：如果未安装或版本过低，请从 Adoptium 或 Oracle 官网下载安装。

2. 构建工具：

   • Maven：版本 3.6 或更高。检查命令：mvn -v。
   • Gradle：版本 7.x 或更高（推荐 8.x）。检查命令：gradle -v。
   • 二者任选其一即可，本文后续示例以Maven为主。

3. 集成开发环境 (IDE)：

   • 推荐使用IntelliJ IDEA Ultimate/Community、Visual Studio Code（需安装 Java 扩展包）或Eclipse。它们对 Spring Boot 有良好的支持。

4. 模型服务准备（二选一）：

   • 选项A：使用远程 API（如 OpenAI）：你需要一个有效的 API Key。前往 OpenAI Platform 注册并获取。
   • 选项B：使用本地模型（如 Ollama）：需要在本地安装并运行 Ollama。前往 Ollama 官网 下载安装，并拉取一个模型，例如ollama pull llama3.2，然后运行ollama serve启动服务。

5. 网络环境：如果使用远程 API，请确保你的网络能够稳定访问对应的服务地址。

4. 创建项目与依赖引入

一切就绪，我们开始创建 Spring Boot 项目并引入 SpringAI 依赖。

4.1 使用 Spring Initializr 创建项目

最快捷的方式是使用 start.spring.io 。

1. 访问网站。
2. 进行如下配置：
   • Project: Maven
   • Language: Java
   • Spring Boot: 选择最新的稳定版（如 3.3.x）
   • Project Metadata:
     • Group:com.example
     • Artifact:springai-demo
     • Name:springai-demo
     • Package name:com.example.springaidemo
     • Packaging: Jar
     • Java: 21
3. Dependencies: 点击 “ADD DEPENDENCIES”，搜索并添加：
   • Spring Web- 用于创建 REST API。
   • Spring Boot DevTools- 可选，用于热加载，提升开发体验。
4. 点击 “GENERATE” 下载项目压缩包，并解压到本地目录。

4.2 添加 SpringAI 依赖

打开项目中的pom.xml文件。SpringAI 的依赖尚未直接集成到 Initializr，需要手动添加。

首先，添加 SpringAI 的 BOM (Bill of Materials)到<dependencyManagement>部分。BOM 能帮你统一管理所有 SpringAI 相关组件的版本，避免冲突。

<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0-M4</version> <!-- 请检查官网获取最新稳定版 --> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

然后，在<dependencies>部分添加你需要的具体 Starter。这里以连接 OpenAI 和 Ollama 为例：

<dependencies> <!-- Spring Boot 基础依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> <scope>runtime</scope> <optional>true</optional> </dependency> <!-- SpringAI OpenAI 支持 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> </dependency> <!-- SpringAI Ollama 支持 (如果需要连接本地模型) --> <!-- <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-ollama-spring-boot-starter</artifactId> </dependency> --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</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.model=gpt-4o-mini spring.ai.openai.chat.options.temperature=0.7

重要安全提示：永远不要将真实的 API Key 硬编码在代码或配置文件中提交到版本控制系统（如 Git）。上述示例中的sk-your-openai-api-key-here只是一个占位符。

正确的做法是使用环境变量：

1. 在启动应用前，设置环境变量。
   • Linux/macOS:export OPENAI_API_KEY=sk-your-real-key
   • Windows (CMD):set OPENAI_API_KEY=sk-your-real-key
   • Windows (PowerShell):$env:OPENAI_API_KEY="sk-your-real-key"
2. 在配置文件中，只写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.enabled=true/false或 Profile 来激活其中一个。

例如，你可以同时配置 OpenAI 和 Ollama，但默认禁用 Ollama：

spring: 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.active=ollama来切换到 Ollama 模型。

6. 编写第一个 AI 对话接口

配置完成后，我们来写一个简单的 REST 控制器，验证环境是否工作正常。

在src/main/java/com/example/springaidemo目录下创建AiController.java：

package 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; // 构造器注入 ChatClient，SpringAI 会自动配置 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() // 返回 Flux<String> .doOnNext(chunk -> { System.out.print(chunk); // 在控制台看到流式效果 fullResponse.append(chunk); }) .blockLast(); // 仅为演示，阻塞直到流结束 return fullResponse.toString(); } }

这段代码做了两件事：

1. /ai/chat接口：同步调用模型，一次性返回所有结果。
2. /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 验证核心功能

1. 连接验证：如果接口返回了合理的 AI 生成内容，说明 SpringAI 成功连接到了你配置的模型服务（OpenAI 或 Ollama）。
2. 配置验证：修改application.yml中的temperature参数（例如改为 0.1 或 1.0），重新提问同样的问题，观察回答的创造性是否发生变化。temperature越低，回答越确定和保守；越高，越随机和有创造性。
3. 模型切换验证（如果配置了多模型）：通过修改配置或切换 Profile，测试不同的模型是否能正常工作。

8. 深入：使用 ChatModel 与流式处理

上面的例子使用了高级的ChatClient。SpringAI 也提供了更底层的ChatModel接口。网络热词中提到的springai flux<chatresponse> 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 Flux<String> getStreamResponse(String userMessage) { Prompt prompt = new Prompt(new UserMessage(userMessage)); Flux<ChatResponse> responseFlux = chatModel.stream(prompt); // 将 Flux<ChatResponse> 转换为 Flux<String> (内容块) return responseFlux .map(chatResponse -> chatResponse.getResult().getOutput().getContent()) .filter(content -> content != null && !content.isEmpty()); } }

然后在 Controller 中注入这个 Service，getStreamResponse方法返回的Flux<String>可以直接被 Spring WebFlux 的@GetMapping(produces = MediaType.TEXT_EVENT_STREAM_VALUE)接口使用，实现真正的服务器发送事件 (SSE) 流式输出。

9. 常见问题与排查方法

环境设置过程中，你可能会遇到以下问题：

10. 最佳实践与下一步

成功运行第一个 SpringAI 应用只是开始。以下是一些进阶建议：

1. 配置管理：始终使用环境变量或配置中心（如 Spring Cloud Config）来管理 API Key 等敏感信息。绝对不要提交到 Git。
2. 异常处理：在调用ChatClient或ChatModel时，使用try-catch处理可能的异常（如网络超时、额度不足、模型不可用等），给用户友好的提示。
3. 提示词工程：SpringAI 支持强大的PromptTemplate。将复杂的提示词模板化、参数化，并存储在配置文件或数据库中，便于管理和迭代。

   @Bean public PromptTemplate rolePromptTemplate() { return new PromptTemplate("你是一个专业的{role}。请用{style}的风格回答以下问题：\n{question}"); }

4. 连接池与超时：在生产环境中，合理配置 HTTP 客户端的连接池、超时时间和重试策略，以提高应用的健壮性。
5. 走向 Agent 与工作流：探索 SpringAI 的Function Calling和Agent特性。这允许 AI 模型调用你提供的工具函数（如查询数据库、调用外部 API），从而实现复杂的自动化工作流（即网络热词中提到的“会搭建工作流”）。
6. 向量数据库集成：如果需要让模型基于你的私有知识库回答问题，可以集成 SpringAI 对 Pinecone、Redis、PGVector 等向量数据库的支持，实现 RAG（检索增强生成）应用。

SpringAI 将 AI 能力变成了 Spring 开发者熟悉的“依赖注入”和“配置驱动”模式。环境设置的核心就是引入正确的 Starter、配置好模型连接信息。完成这一步后，你就能将全部精力投入到 Prompt 设计、业务逻辑和用户体验优化上，而不用再操心不同模型 API 的差异。建议从同步调用开始，验证整个链路，然后逐步尝试流式响应和函数调用，最终构建出真正智能的应用 Agent。