【RuoYi-SpringBoot3-Pro】：接入 AI 对话能力
本文详细介绍 RuoYi-SpringBoot3-Pro 框架中内置的 OpenAI 工具类，帮助开发者快速集成 AI 对话能力。
GitHub：
https://github.com/undsky/RuoYi-SpringBoot3-Pro
一、概述
RuoYi-SpringBoot3-Pro 基于官方 OpenAI Java SDK 封装了一套开箱即用的 AI 工具类，支持同步对话、流式对话、多角色消息、代理配置等特性，并兼容所有遵循 OpenAI 协议的第三方 API。
核心组件位于 ruoyi-common 模块：
ruoyi-common/src/main/java/com/ruoyi/common/
├── config/
│ └── OpenAIConfig.java # 配置类
└── utils/ai/
├── OpenAI.java # 核心工具类
├── AIMessage.java # 消息实体
└── AIRole.java # 角色枚举
二、快速开始
2.1 Maven 依赖
框架已内置 OpenAI SDK 依赖，无需额外引入：
<dependency>
<groupId>com.openai</groupId>
<artifactId>openai-java</artifactId>
<version>2.20.1</version>
</dependency>
2.2 配置文件
在 application.yml 中添加 OpenAI 配置：
# OpenAI配置
openai:
# API密钥
api-key: sk-xxx
# 基础URL（支持自定义API地址）
base-url: https://api.openai.com/v1
# 默认模型
model: gpt-4o
# 代理配置（可选）
proxy:
# 是否启用代理
enabled: false
# 代理类型 (HTTP/SOCKS)
type: HTTP
# 代理主机
host: 127.0.0.1
# 代理端口
port: 7890
配置说明：
| 配置项 | 说明 | 示例 |
|---|---|---|
api-key | OpenAI API 密钥 | sk-xxx |
base-url | API 基础地址，支持第三方兼容 API | https://api.openai.com/v1 |
model | 默认使用的模型 | gpt-4o、gpt-3.5-turbo |
proxy.enabled | 是否启用代理 | true/false |
proxy.type | 代理类型 | HTTP/SOCKS |
proxy.host | 代理服务器地址 | 127.0.0.1 |
proxy.port | 代理服务器端口 | 7890 |
三、核心 API
3.1 角色枚举 - AIRole
支持 OpenAI Chat API 的三种标准角色：
public enum AIRole {
USER("user"), // 用户消息
SYSTEM("system"), // 系统提示词
ASSISTANT("assistant"); // AI 助手回复
}
3.2 消息实体 - AIMessage
封装对话消息：
@Data
public class AIMessage {
private AIRole role; // 消息角色
private String message; // 消息内容
public AIMessage(AIRole role, String message) {
this.role = role;
this.message = message;
}
}
3.3 工具类 - OpenAI
提供三个核心静态方法：
| 方法 | 说明 |
|---|---|
chatClient() | 创建 OpenAI 客户端 |
chatParams() | 构建会话参数 |
chat() | 同步对话 |
chatStream() | 流式对话（SSE） |
四、使用示例
4.1 同步对话
适用于简单的问答场景，等待 AI 完整响应后返回：
import com.openai.client.OpenAIClient;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import com.ruoyi.common.config.OpenAIConfig;
import com.ruoyi.common.utils.ai.*;
import java.util.ArrayList;
import java.util.List;
public class ChatExample {
public String simpleChat(String userMessage) {
// 1. 创建客户端
OpenAIClient client = OpenAI.chatClient(
OpenAIConfig.getApiKey(),
OpenAIConfig.getBaseUrl(),
OpenAIConfig.getProxy() != null ? OpenAIConfig.getProxy().toJavaProxy() : null
);
// 2. 构建消息列表
List<AIMessage> messages = new ArrayList<>();
messages.add(new AIMessage(AIRole.SYSTEM, "你是一个有帮助的助手。"));
messages.add(new AIMessage(AIRole.USER, userMessage));
// 3. 构建请求参数
ChatCompletionCreateParams params = OpenAI.chatParams(
OpenAIConfig.getModel(),
messages
);
// 4. 发起同步请求
return OpenAI.chat(client, params);
}
}
4.2 流式对话（SSE）
适用于需要实时展示生成内容的场景，如聊天界面：
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;
@RestController
@RequestMapping("/api/ai")
public class AIController {
@PostMapping("/chat/stream")
public ResponseEntity<StreamingResponseBody> streamChat(@RequestBody String userMessage) {
// 1. 创建客户端
OpenAIClient client = OpenAI.chatClient(
OpenAIConfig.getApiKey(),
OpenAIConfig.getBaseUrl(),
OpenAIConfig.getProxy() != null ? OpenAIConfig.getProxy().toJavaProxy() : null
);
// 2. 构建消息
List<AIMessage> messages = new ArrayList<>();
messages.add(new AIMessage(AIRole.SYSTEM, "你是一个有帮助的助手。"));
messages.add(new AIMessage(AIRole.USER, userMessage));
// 3. 构建参数
ChatCompletionCreateParams params = OpenAI.chatParams(
OpenAIConfig.getModel(),
messages
);
// 4. 流式响应
return OpenAI.chatStream(client, params, new OpenAI.StreamContentListener() {
@Override
public void onContent(String content) {
// 每收到一段增量内容时调用
System.out.print(content);
}
@Override
public void onComplete(String fullContent) {
// 全部内容流式结束后调用
System.out.println("\n完整响应：" + fullContent);
}
});
}
}
4.3 多轮对话
维护对话历史实现上下文连续：
public class MultiTurnChat {
private final List<AIMessage> conversationHistory = new ArrayList<>();
private final OpenAIClient client;
public MultiTurnChat() {
this.client = OpenAI.chatClient(
OpenAIConfig.getApiKey(),
OpenAIConfig.getBaseUrl(),
OpenAIConfig.getProxy() != null ? OpenAIConfig.getProxy().toJavaProxy() : null
);
// 设置系统提示词
conversationHistory.add(new AIMessage(AIRole.SYSTEM, "你是一个专业的技术顾问。"));
}
public String chat(String userMessage) {
// 添加用户消息
conversationHistory.add(new AIMessage(AIRole.USER, userMessage));
// 构建参数并请求
ChatCompletionCreateParams params = OpenAI.chatParams(
OpenAIConfig.getModel(),
conversationHistory
);
String response = OpenAI.chat(client, params);
// 保存 AI 回复到历史
conversationHistory.add(new AIMessage(AIRole.ASSISTANT, response));
return response;
}
}
4.4 使用代理
在网络受限环境下配置代理：
import java.net.InetSocketAddress;
import java.net.Proxy;
// 方式一：使用配置文件中的代理
OpenAIClient client = OpenAI.chatClient(
OpenAIConfig.getApiKey(),
OpenAIConfig.getBaseUrl(),
OpenAIConfig.getProxy().toJavaProxy()
);
// 方式二：手动创建代理
Proxy httpProxy = new Proxy(
Proxy.Type.HTTP,
new InetSocketAddress("127.0.0.1", 7890)
);
Proxy socksProxy = new Proxy(
Proxy.Type.SOCKS,
new InetSocketAddress("127.0.0.1", 1080)
);
OpenAIClient clientWithProxy = OpenAI.chatClient(
"sk-xxx",
"https://api.openai.com/v1",
httpProxy
);
五、兼容第三方 API
框架支持所有兼容 OpenAI 协议的第三方 API，只需修改 base-url 配置：
openai:
api-key: your-api-key
# 使用第三方 API
base-url: https://your-custom-api.com/v1
model: your-model-name
常见兼容 API 示例：
| 服务商 | base-url 示例 |
|---|---|
| Azure OpenAI | https://{resource}.openai.azure.com/openai/deployments/{deployment} |
| 智谱 AI | https://open.bigmodel.cn/api/paas/v4 |
| 月之暗面 | https://api.moonshot.cn/v1 |
| DeepSeek | https://api.deepseek.com/v1 |
六、前端集成
6.1 接收流式响应
前端使用 fetch API 处理 SSE 流式响应：
async function streamChat(message) {
const response = await fetch('/api/ai/chat/stream', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ message })
});
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const text = decoder.decode(value);
if (text === '[DONE]') break;
// 实时显示内容
appendToChat(text);
}
}
6.2 Vue 3 组件示例
<template>
<div class="chat-container">
<div class="messages" ref="messagesRef">
<div v-for="msg in messages" :key="msg.id" :class="['message', msg.role]">
{{ msg.content }}
</div>
</div>
<div class="input-area">
<input v-model="input" @keyup.enter="sendMessage" placeholder="输入消息..." />
<button @click="sendMessage" :disabled="loading">发送</button>
</div>
</div>
</template>
<script setup>
import { ref } from 'vue'
const messages = ref([])
const input = ref('')
const loading = ref(false)
async function sendMessage() {
if (!input.value.trim() || loading.value) return
const userMessage = input.value
messages.value.push({ id: Date.now(), role: 'user', content: userMessage })
input.value = ''
loading.value = true
// 添加 AI 消息占位
const aiMessage = { id: Date.now() + 1, role: 'assistant', content: '' }
messages.value.push(aiMessage)
try {
const response = await fetch('/api/ai/chat/stream', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ message: userMessage })
})
const reader = response.body.getReader()
const decoder = new TextDecoder()
while (true) {
const { done, value } = await reader.read()
if (done) break
const text = decoder.decode(value)
if (text === '[DONE]') break
aiMessage.content += text
}
} finally {
loading.value = false
}
}
</script>
七、最佳实践
7.1 错误处理
public String safeChatWithRetry(String message, int maxRetries) {
for (int i = 0; i < maxRetries; i++) {
try {
return simpleChat(message);
} catch (Exception e) {
if (i == maxRetries - 1) {
throw new RuntimeException("AI 服务调用失败: " + e.getMessage(), e);
}
// 等待后重试
try {
Thread.sleep(1000 * (i + 1));
} catch (InterruptedException ie) {
Thread.currentThread().interrupt();
}
}
}
return null;
}
7.2 Token 控制
合理控制对话历史长度，避免超出模型 Token 限制：
public void trimConversationHistory(int maxMessages) {
if (conversationHistory.size() > maxMessages) {
// 保留系统提示词和最近的消息
AIMessage systemMessage = conversationHistory.get(0);
List<AIMessage> recentMessages = conversationHistory.subList(
conversationHistory.size() - maxMessages + 1,
conversationHistory.size()
);
conversationHistory.clear();
conversationHistory.add(systemMessage);
conversationHistory.addAll(recentMessages);
}
}
7.3 敏感信息保护
// 不要在日志中打印完整的 API Key
String maskedKey = apiKey.substring(0, 8) + "..." + apiKey.substring(apiKey.length() - 4);
log.info("Using API Key: {}", maskedKey);
八、总结
RuoYi-SpringBoot3-Pro 的 AI 能力集成模块具有以下特点：
- 开箱即用：基于官方 SDK 封装，配置简单
- 功能完整：支持同步/流式对话、多角色、代理配置
- 扩展性强：兼容所有 OpenAI 协议的第三方 API
- 易于集成：提供完整的工具类和示例代码
扫一扫
510
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
