Spring Boot 集成 Spring AI OpenAI Starter 教程
如何在 Spring Boot 项目中集成 Spring AI OpenAI Starter。内容包括环境准备(JDK 17+, Maven/Gradle)、配置 OpenAI API Key、实现基础对话及带上下文的对话功能、高级参数控制、流式响应(SSE)以及提示词工程。教程还提供了完整的代码示例、项目结构、测试方法及生产环境的安全与性能建议,帮助开发者快速构建具备 AI 能力的 Java 应用。

如何在 Spring Boot 项目中集成 Spring AI OpenAI Starter。内容包括环境准备(JDK 17+, Maven/Gradle)、配置 OpenAI API Key、实现基础对话及带上下文的对话功能、高级参数控制、流式响应(SSE)以及提示词工程。教程还提供了完整的代码示例、项目结构、测试方法及生产环境的安全与性能建议,帮助开发者快速构建具备 AI 能力的 Java 应用。

随着人工智能技术的快速发展,将 AI 能力集成到企业级应用中变得越来越重要。Spring AI 作为 Spring 生态系统中的新成员,为 Java 开发者提供了标准化、开箱即用的 AI 集成方案。本教程将详细介绍如何使用 Spring Boot 集成 Spring AI OpenAI Starter,快速为您的应用添加智能对话功能。
您可以通过以下两种方式之一创建项目:
方式一:使用 start.spring.io
方式二:手动添加依赖
如果您已有 Spring Boot 项目,直接在 pom.xml 中添加以下依赖:
<!-- Spring AI OpenAI Starter -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
<version>1.0.0</version> <!-- 请使用最新版本 -->
</dependency>
<!-- Spring Boot Web Starter (如果尚未添加) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
在 src/main/resources/application.yml 文件中添加以下配置:
spring:
ai:
openai:
api-key: "sk-your-openai-api-key-here" # 替换为您的实际 OpenAI API Key
base-url: "https://api.openai.com/v1" # 默认值,通常无需修改
chat:
options:
model: "gpt-4-turbo" # 您想使用的模型,如 gpt-3.5-turbo, gpt-4 等
temperature: 0.7 # 控制生成文本的随机性 (0-2)
max-tokens: 500 # 生成的最大 token 数
安全建议:
为了安全起见,建议不要将 API Key 直接硬编码在配置文件中,而是使用环境变量:
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY} # 从环境变量读取
然后,在运行应用前设置环境变量:
export OPENAI_API_KEY=sk-your-openai-api-key-here
或者在 Windows 命令提示符中:
set OPENAI_API_KEY=sk-your-openai-api-key-here
创建一个 REST 控制器来处理 AI 对话请求:
import org.springframework.ai.chat.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/ai")
public class AIController {
private final ChatClient chatClient;
@Autowired
public AIController(ChatClient chatClient) {
this.chatClient = chatClient;
}
/**
* 基础对话接口
* @param message 用户输入的消息
* @return AI 的回复
*/
@GetMapping("/chat")
public String chat(@RequestParam String message) {
return chatClient.call(message);
}
/**
* 基础对话接口 (POST 方式)
* @param userInput 用户输入
* @return AI 的回复
*/
@PostMapping("/chat")
public String generateText(@RequestBody String userInput) {
return chatClient.call(userInput);
}
}
启动 Spring Boot 应用后,您可以通过以下方式测试:
方式一:浏览器访问
http://localhost:8080/ai/chat?message=你好,请介绍一下你自己
方式二:使用 cURL 测试
curl -X GET "http://localhost:8080/ai/chat?message=请写一个简单的 Java Hello World 程序"
方式三:使用 Postman 等工具发送 POST 请求
http://localhost:8080/ai/chat为了让对话更有连续性,我们可以实现带上下文的对话功能:
import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.message.Message;
import org.springframework.ai.chat.message.SystemMessage;
import org.springframework.ai.chat.message.UserMessage;
import org.springframework.ai.chat.message.AssistantMessage;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
@RestController
@RequestMapping("/ai")
public class AIContextController {
private final ChatClient chatClient;
// 简单的上下文存储(生产环境应使用更可靠的存储方案)
private List<Message> conversationHistory = new ArrayList<>();
@Autowired
public AIContextController(ChatClient chatClient) {
this.chatClient = chatClient;
// 初始化系统消息
conversationHistory.add(new SystemMessage("你是一个专业的技术助手,擅长 Java 开发和人工智能相关知识。"));
}
/**
* 带上下文的对话
* @param userInput 用户输入
* @return AI 的回复
*/
@PostMapping("/chat/context")
public String chatWithContext(@RequestBody String userInput) {
// 添加用户消息到历史记录
conversationHistory.add(new UserMessage(userInput));
// 创建包含历史记录的 Prompt
Prompt (conversationHistory);
chatClient.call(prompt).getResult().getOutput().getContent();
conversationHistory.add( (response));
response;
}
String {
conversationHistory.clear();
conversationHistory.add( ());
;
}
}
您可以通过自定义 OpenAiChatOptions 来更精细地控制 AI 的行为:
import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.openai.OpenAiChatOptions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/ai")
public class AIAdvancedController {
private final ChatClient chatClient;
@Autowired
public AIAdvancedController(ChatClient chatClient) {
this.chatClient = chatClient;
}
/**
* 高级参数控制的对话
* @param message 用户输入
* @return AI 的回复
*/
@PostMapping("/chat/advanced")
public String advancedChat(@RequestBody String message) {
// 自定义参数
OpenAiChatOptions options = OpenAiChatOptions.builder()
.withModel("gpt-4") // 指定模型
.withTemperature(0.3) // 较低的随机性,回复更确定
.withMaxTokens(1000) // 最大生成 token 数
// 可以添加更多选项,如 topP, frequencyPenalty, presencePenalty 等
.build();
// 构建 Prompt
Prompt request = new Prompt(message, options);
return chatClient.call(request).getResult().getOutput().getContent();
}
String {
OpenAiChatOptions.builder()
.withModel(modelName)
.withTemperature()
.withMaxTokens()
.build();
(message, options);
chatClient.call(request).getResult().getOutput().getContent();
}
}
对于长时间运行的请求,流式响应可以提供更好的用户体验:
import org.springframework.ai.chat.StreamingChatClient;
import org.springframework.ai.chat.message.UserMessage;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;
@RestController
@RequestMapping("/ai")
public class AIStreamingController {
private final StreamingChatClient streamingChatClient;
@Autowired
public AIStreamingController(StreamingChatClient streamingChatClient) {
this.streamingChatClient = streamingChatClient;
}
/**
* 流式对话接口
* @param message 用户输入的消息
* @return 流式的 AI 回复
*/
@GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamChat(@RequestParam String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return streamingChatClient.stream(prompt)
.map(content -> content.toString());
}
/**
* 流式对话接口 (POST 方式)
* @param message 用户输入
* @return 流式的 AI 回复
*/
@PostMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamChatPost {
( (message));
streamingChatClient.stream(prompt)
.map(content -> content.toString());
}
}
测试流式响应:
您可以使用支持 SSE 的客户端(如 Postman 或专门的 SSE 客户端)来测试流式接口,或者创建一个简单的前端页面来展示流式效果。
提示词工程 (Prompt Engineering) 是通过精心设计提示词来引导 AI 生成更准确、更有用内容的技术。
import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
// 假设有一个 DTO 类用于封装翻译请求
record TranslationRequest(String sourceLang, String targetLang, String text) {}
@RestController
@RequestMapping("/ai")
public class AIPromptTemplateController {
private final ChatClient chatClient;
@Autowired
public AIPromptTemplateController(ChatClient chatClient) {
this.chatClient = chatClient;
}
/**
* 翻译功能 - 使用提示词模板
* @param request 翻译请求
* @return 翻译结果
*/
@PostMapping("/translate")
public String translate(@RequestBody TranslationRequest request) {
// 创建提示词模板
PromptTemplate promptTemplate = new PromptTemplate(
"""
将以下{sourceLang}文本翻译成{targetLang}: {text}
翻译结果:
"""
);
// 设置模板变量
promptTemplate.add("sourceLang", request.sourceLang());
promptTemplate.add("targetLang", request.targetLang());
promptTemplate.add("text", request.text());
// 渲染提示词并调用 AI
return chatClient.call(promptTemplate.render()).getResult().getOutput().getContent();
}
String {
(
);
promptTemplate.add(, language);
promptTemplate.add(, description);
chatClient.call(promptTemplate.render()).getResult().getOutput().getContent();
}
}
测试翻译功能:
curl -X POST -H "Content-Type: application/json" \
-d '{"sourceLang":"English","targetLang":"Chinese","text":"Hello, how are you today?"}' \
http://localhost:8080/ai/translate
测试代码生成功能:
curl -X POST "http://localhost:8080/ai/generate-code?language=Java&description=一个简单的计算器,能够进行加减乘除运算" \
-H "Content-Type: application/x-www-form-urlencoded"
src/
├── main/
│ ├── java/
│ │ └── com/
│ │ └── example/
│ │ └── aiintegration/
│ │ ├── AiIntegrationApplication.java
│ │ ├── controller/
│ │ │ ├── AIController.java
│ │ │ ├── AIContextController.java
│ │ │ ├── AIAdvancedController.java
│ │ │ └── AIStreamingController.java
│ │ └── dto/
│ │ └── TranslationRequest.java
│ └── resources/
│ ├── application.yml
│ └── static/ # 可选:前端文件
└── test/
└── java/
└── com/
└── example/
└── aiintegration/
└── AiIntegrationApplicationTests.java
package com.example.aiintegration;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class AiIntegrationApplication {
public static void main(String[] args) {
SpringApplication.run(AiIntegrationApplication.class, args);
}
}
使用您的 IDE 或命令行启动 Spring Boot 应用:
mvn spring-boot:run # 或 gradle bootRun
基础对话测试:
http://localhost:8080/ai/chat?message=你好,介绍一下 Spring Boothttp://localhost:8080/ai/chat,body 为 "你好,介绍一下 Spring Boot"高级参数测试:
http://localhost:8080/ai/chat/advanced,body 为 "解释微服务架构的优缺点"流式响应测试:
http://localhost:8080/ai/chat/stream?message=给我讲一个笑话翻译功能测试:
curl -X POST -H "Content-Type: application/json" \
-d '{"sourceLang":"English","targetLang":"Chinese","text":"The quick brown fox jumps over the lazy dog."}' \
http://localhost:8080/ai/translate
创建测试类验证 ChatClient 的基本功能:
package com.example.aiintegration;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.ai.chat.ChatClient;
import static org.junit.jupiter.api.Assertions.assertNotNull;
@SpringBootTest
class AiIntegrationApplicationTests {
@Autowired
private ChatClient chatClient;
@Test
void contextLoads() {
}
@Test
void testChatClient() {
String response = chatClient.call("你好,你能做什么?");
System.out.println("AI 回复:" + response);
assertNotNull(response);
}
}
通过本教程,您已经学会了如何使用 Spring Boot 集成 Spring AI OpenAI Starter,为您的应用添加强大的 AI 能力。从基础对话功能到高级的流式响应和提示词工程,Spring AI 提供了丰富的功能来满足各种 AI 集成需求。
Spring AI 的优势在于其标准化的 API 设计,使得您可以轻松切换不同的 AI 供应商而无需大幅修改业务代码。随着 AI 技术的不断发展,这种抽象层将为您的应用提供更大的灵活性和未来保障。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online