【RuoYi-SpringBoot3-Pro】：接入 AI 对话能力

本文详细介绍 RuoYi-SpringBoot3-Pro^[1] 框架中内置的 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
• 易于集成：提供完整的工具类和示例代码

• 项目地址：RuoYi-SpringBoot3-Pro^[1]
• 开发文档：RuoYi-SpringBoot3-Pro 文档^[2]

引用链接

[1] RuoYi-SpringBoot3-Pro: https://github.com/undsky/RuoYi-SpringBoot3-Pro
[2] RuoYi-SpringBoot3-Pro 文档: https://www.undsky.com/blog/?category=RuoYi-SpringBoot3-Pro#