Spring Boot 集成 Spring AI OpenAI Starter 教程

优质文章学习记录

— 11 min read
Spring Boot 集成 Spring AI OpenAI Starter 教程

前言

随着人工智能技术的快速发展，将AI能力集成到企业级应用中变得越来越重要。Spring AI作为Spring生态系统中的新成员，为Java开发者提供了标准化、开箱即用的AI集成方案。本教程将详细介绍如何使用Spring Boot集成Spring AI OpenAI Starter，快速为您的应用添加智能对话功能。

一、环境准备

1. 技术要求

  • ​​JDK​​: 17 或更高版本
  • ​​构建工具​​: Maven 3.6+ 或 Gradle
  • ​​Spring Boot​​: 3.2+ (推荐最新稳定版)
  • ​​OpenAI账号​​: 需要在OpenAI平台注册并获取API Key

2. 创建Spring Boot项目

您可以通过以下两种方式之一创建项目：

​​方式一：使用start.spring.io​​

  1. 访问 start.spring.io
  2. 选择以下依赖：
    • Spring Web
    • Spring AI (选择对应版本)
    • 其他您可能需要的依赖（如Spring Security等）

​​方式二：手动添加依赖​​
如果您已有Spring Boot项目，直接在pom.xml中添加以下依赖：

<!-- Spring AI OpenAI Starter --> <dependency> <groupId>io.springboot.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>

二、配置OpenAI API

1. 获取OpenAI API Key

  1. 登录OpenAI平台
  2. 进入"API Keys"页面
  3. 创建新的API Key并妥善保存

2. 配置application.yml

在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

三、核心功能实现

1. 基础对话功能

创建AI控制器

创建一个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请求​​

  • URL: http://localhost:8080/ai/chat
  • Method: POST
  • Body: raw, text/plain
  • 内容: "请解释Spring Boot的核心特性"

2. 带上下文的对话

为了让对话更有连续性，我们可以实现带上下文的对话功能：

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.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 prompt = new Prompt(conversationHistory); // 调用AI服务 String response = chatClient.call(prompt).getResult().getOutput().getContent(); // 添加AI回复到历史记录 conversationHistory.add(new UserMessage(response)); // 注意：这里应该是AssistantMessage，但Spring AI可能没有这个类 return response; } /** * 清除对话上下文 */ @PostMapping("/chat/context/clear") public String clearContext() { conversationHistory.clear(); conversationHistory.add(new SystemMessage("你是一个专业的技术助手，擅长Java开发和人工智能相关知识。")); return "对话上下文已清除"; } }

​​注意​​：上面的代码中使用了UserMessage来表示AI的回复，这在实际情况中可能不太准确。Spring AI可能提供了专门的AssistantMessage类，如果没有，您可能需要自己创建或考虑使用其他方式管理上下文。

3. 高级参数控制

您可以通过自定义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(); } /** * 使用不同模型的对话 * @param message 用户输入 * @param modelName 模型名称 * @return AI的回复 */ @PostMapping("/chat/model/{modelName}") public String chatWithSpecificModel(@RequestBody String message, @PathVariable String modelName) { OpenAiChatOptions options = OpenAiChatOptions.builder() .withModel(modelName) // 动态指定模型 .withTemperature(0.7) .withMaxTokens(800) .build(); Prompt request = new Prompt(message, options); return chatClient.call(request).getResult().getOutput().getContent(); } }

4. 流式响应（Server-Sent Events）

对于长时间运行的请求，流式响应可以提供更好的用户体验：

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(@RequestBody String message) { Prompt prompt = new Prompt(new UserMessage(message)); return streamingChatClient.stream(prompt) .map(content -> content.toString()); } }

​​测试流式响应​​：
您可以使用支持SSE的客户端（如Postman或专门的SSE客户端）来测试流式接口，或者创建一个简单的前端页面来展示流式效果。

四、进阶功能：提示词工程

提示词工程(Prompt Engineering)是通过精心设计提示词来引导AI生成更准确、更有用内容的技术。

1. 创建自定义提示词模板

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(); } /** * 代码生成 - 使用提示词模板 * @param language 编程语言 * @param description 功能描述 * @return 生成的代码 */ @PostMapping("/generate-code") public String generateCode(@RequestParam String language, @RequestParam String description) { PromptTemplate promptTemplate = new PromptTemplate(""" 用{language}编写一个程序，实现以下功能: {description} 请提供完整的可运行代码，包括必要的导入语句和主函数。 代码应该有良好的注释和结构。 生成的代码: """); promptTemplate.add("language", language); promptTemplate.add("description", description); return chatClient.call(promptTemplate.render()).getResult().getOutput().getContent(); } }

2. 测试提示词模板

​​测试翻译功能​​：

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); } }

六、测试与验证

1. 启动应用

使用您的IDE或命令行启动Spring Boot应用：

mvn spring-boot:run # 或 gradle bootRun

2. 测试接口

​​基础对话测试​​：

  • GET请求: http://localhost:8080/ai/chat?message=你好，介绍一下Spring Boot
  • 或POST请求到 http://localhost:8080/ai/chat，body为 "你好，介绍一下Spring Boot"

​​高级参数测试​​：

  • POST请求到 http://localhost:8080/ai/chat/advanced，body为 "解释微服务架构的优缺点"

​​流式响应测试​​：

  • GET请求: http://localhost:8080/ai/chat/stream?message=给我讲一个笑话
  • 使用支持SSE的客户端查看流式效果

​​翻译功能测试​​：

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

3. 单元测试

创建测试类验证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); } }

七、生产环境建议

1. 安全最佳实践

  • ​​API密钥管理​​：永远不要将API密钥硬编码在代码中，使用环境变量或密钥管理服务
  • ​​访问控制​​：为AI接口添加适当的认证和授权
  • ​​输入验证​​：验证所有用户输入，防止滥用和注入攻击
  • ​​速率限制​​：实现API速率限制，防止滥用和超额费用

2. 性能优化

  • ​​连接池​​：配置适当的网络连接池参数
  • ​​缓存​​：对常见问题的AI响应实现缓存机制
  • ​​异步处理​​：对复杂的AI请求考虑使用异步处理
  • ​​监控​​：监控AI接口的性能和使用情况

3. 错误处理与重试

  • 实现健壮的错误处理机制
  • 对暂时性错误实现重试逻辑
  • 监控API使用配额和限制

八、总结

通过本教程，您已经学会了如何使用Spring Boot集成Spring AI OpenAI Starter，为您的应用添加强大的AI能力。从基础对话功能到高级的流式响应和提示词工程，Spring AI提供了丰富的功能来满足各种AI集成需求。

Spring AI的优势在于其标准化的API设计，使得您可以轻松切换不同的AI供应商而无需大幅修改业务代码。随着AI技术的不断发展，这种抽象层将为您的应用提供更大的灵活性和未来保障。

Read more

【花雕学编程】Arduino BLDC 驱动方案 —— MimiClaw（迷你小龙虾）+ ESP32 嵌入式组合机器人

【花雕学编程】Arduino BLDC 驱动方案 —— MimiClaw（迷你小龙虾）+ ESP32 嵌入式组合机器人

这是一套面向无刷电机（BLDC）、高度集成、可快速开发、支持本地智能的机器人开发组合。它将 ESP32 高性能主控 + MimiClaw 智能控制框架 + Arduino 生态易用性 + BLDC 无刷电机驱动 融为一体，是目前创客、实验室、竞赛、小型机器人领域最实用、最稳定、性价比极高的嵌入式机器人方案。 一、核心定义（专业版一句话解释） MimiClaw（迷你小龙虾）+ ESP32是一套基于 Arduino 开发环境、面向 BLDC 无刷电机控制、支持本地智能决策的嵌入式机器人控制系统。它以 ESP32 为硬件核心，以 MimiClaw 为控制大脑，实现无刷电机驱动、传感器融合、自主决策、无线通信、多关节机器人控制一体化。 简单说：ESP32 = 身体与算力MimiClaw = 思考与逻辑BLDC 无刷驱动 = 动力系统Arduino

DankDroneDownloader：大疆无人机固件自由下载终极指南

DankDroneDownloader：大疆无人机固件自由下载终极指南 【免费下载链接】DankDroneDownloaderA Custom Firmware Download Tool for DJI Drones Written in C# 项目地址: https://gitcode.com/gh_mirrors/da/DankDroneDownloader 想要完全掌控你的大疆无人机固件版本吗？厌倦了厂商限制固件选择权的做法？DankDroneDownloader（简称DDD）正是你需要的解决方案！这个免费开源的C#工具让你重新获得固件下载的完全自由，支持大疆全系列无人机和配件。 🚀 打破限制，重获控制权 大疆等无人机厂商常常移除旧版固件，限制用户只能使用最新版本。但很多时候，旧版固件更加稳定，或者包含某些新版移除的实用功能。DDD解决了这个痛点，为你提供完整的固件版本历史存档。 核心优势： * 支持大疆无人机全系列固件下载 * 提供Windows桌面应用程序 * 与第三方刷写工具完美兼容 * 持续更新的固件库 📋 全面支持的设备列表 DDD目前
Windows 安装 Neo4j（2025最新·极简）

Windows 安装 Neo4j（2025最新·极简）

目录 1. 准备 2. 下载安装包 3. 一键安装 4. 启动 Neo4j 5.安装 Neo4j 的系统服务 Neo4j 是目前最流行的原生图数据库，用图结构（节点-关系-属性）存储数据，而非传统表结构。它专为海量关联数据设计，提供： * 原生图存储：基于免索引邻接结构，每个节点直接维护指向相邻节点的物理指针，实现 O(1) 时间复杂度的图遍历。 * Cypher 查询语言：ISO 标准化图查询语言，采用 ASCII-Art 模式匹配语法，支持可变长度路径、子图查询、聚合与更新混合事务。 * ACID 事务：支持完整事务、集群高可用，可承载企业级负载。 * 丰富生态：内置 Graph Data Science (GDS)

Techub News 專訪高鋒集團合夥人、Web3Labs行政總裁黃俊瑯：以資本與生態，賦能傳統企業Web3轉型

本次專訪聚焦高鋒集團如何透過資本投入與生態資源，助力傳統企業邁向Web3轉型。從近期戰略參與上市公司德祥地產的配股出發，高鋒集團合夥人、Web3Labs CEO黃俊瑯（Caspar）分享了集團的戰略思考、核心優勢、執行機制，以及對傳統企業轉型痛點的觀察與未來願景。這場對話展現了高鋒集團與Web3Labs在「實物資產代幣化」（RWA）等領域的創新實踐，以及他們致力成為傳統企業數字化轉型可靠夥伴的定位。 戰略投資德祥地產：搭建Web3與傳統實體經濟的橋樑 Techub News：Caspar您好。我們注意到高鋒集團近期戰略性參與了上市公司德祥地產的配股。這在市場看來頗為創新，能否請您談談這次投資背後的戰略思考？ 黃俊瑯：這次對德祥地產的投資，對我們而言，遠超一次單純的財務投資。它是一個清晰的信號，也是我們戰略的關鍵落子。高鋒集團的核心使命之一，是搭建Web3前沿科技與傳統實體經濟之間的橋樑。德祥擁有紮實的房地產業務與實物資產，這正是探索「實物資產代幣化」（RWA）最具潛力的領域。我們這次參與，是協助其啟動轉型的第一步，未來將結合我們的專業生態，共同探索如何利用區塊鏈技術提升資產流