shuolol/PoJie

Fork 0

Files

T

History

shuolol b236048a24 first commit

2026-02-22 12:12:02 +08:00

src

first commit

2026-02-22 12:12:02 +08:00

pom.xml

first commit

2026-02-22 12:12:02 +08:00

README.md

first commit

2026-02-22 12:12:02 +08:00

README.md

RuoYi Chat 模块

模块简介

ruoyi-chat 是 PoJie 项目的智能聊天系统模块，提供完整的聊天会话管理、消息处理、知识库集成和实时通信功能。该模块通过集成 ruoyi-ai 和 ruoyi-knowledge 模块，实现了基于知识库的智能问答系统（RAG），支持多种通信方式（REST API、SSE 流式、WebSocket）。

功能特性

1. 聊天会话管理 ✅

✅ 创建和管理聊天会话
✅ 支持多用户并发聊天
✅ 会话历史记录和导出
✅ 会话状态管理
✅ 会话标题自动生成和手动编辑

2. 消息处理 ✅

✅ 实时消息发送和接收
✅ 消息类型支持（文本、图片等）
✅ 消息历史查询（支持分页和条件筛选）
✅ 消息状态跟踪
✅ Token 使用量和成本统计

3. 知识库集成（RAG）✅

✅ 基于知识库的智能问答
✅ 上下文理解和构建
✅ 向量相似度搜索
✅ 智能回复生成
✅ 知识库会话管理
✅ 知识库内容搜索
内部对接模块：
- AI 模块：AiChatService（统一聊天接口）
- 知识库模块：KnowledgeVectorService（向量检索）

4. 实时通信 ✅

✅ REST API：标准 HTTP 接口
✅ SSE 流式：服务器推送事件，支持流式对话（ChatOpenApiController）
✅ WebSocket：STOMP 协议，实时双向通信（ChatStompController）

5. 使用统计 ✅

✅ Token 使用量统计
✅ 聊天成本计算
✅ 用户活跃度分析
✅ 模型使用情况
✅ 使用记录导出

6. 配置管理 ✅

✅ 聊天配置管理（键值对配置）
✅ 模型配置管理（模型信息、价格、API 配置）
✅ 配置分类管理
✅ 配置导入导出

目录结构

ruoyi-chat/
├─ src/main/java/org/dromara/chat/
│  ├─ controller/         # REST 控制器层
│  │  ├─ AIKnowledgeChatController.java    # 知识库聊天控制器
│  │  ├─ ChatSessionController.java        # 会话管理控制器
│  │  ├─ ChatMessageController.java        # 消息管理控制器
│  │  ├─ ChatOpenApiController.java        # 开放 API 控制器（SSE 流式）
│  │  ├─ ChatStompController.java          # WebSocket 控制器（STOMP）
│  │  ├─ ChatConfigController.java         # 配置管理控制器
│  │  ├─ ChatModelController.java          # 模型管理控制器
│  │  └─ ChatUsageTokenController.java     # Token 使用记录控制器
│  ├─ service/            # 核心业务服务层
│  │  ├─ AiKnowledgeChatService.java       # 知识库聊天服务
│  │  ├─ ChatSessionService.java           # 会话管理服务
│  │  ├─ ChatMessageService.java           # 消息管理服务
│  │  ├─ ChatConfigService.java            # 配置管理服务
│  │  ├─ ChatModelService.java             # 模型管理服务
│  │  ├─ ChatUsageTokenService.java        # Token 使用记录服务
│  │  └─ impl/                             # 服务实现类
│  ├─ domain/             # 领域模型
│  │  ├─ bo/              # 业务对象（Business Object）
│  │  ├─ vo/              # 视图对象（View Object）
│  │  ├─ request/         # 请求对象
│  │  └─ *.java           # 实体类（Entity）
│  ├─ mapper/             # MyBatis Mapper 接口
│  ├─ config/             # 配置类（WebSocket 配置等）
│  └─ client/             # Java SDK（统一网关封装）
│     └─ ChatSdk.java
└─ docs/                  # API 使用说明文档

模块结构

org.dromara.chat
├── controller/              # 控制器层
│   ├── AIKnowledgeChatController.java      # 知识库聊天
│   ├── ChatSessionController.java          # 会话管理
│   ├── ChatMessageController.java          # 消息管理
│   ├── ChatOpenApiController.java          # 开放 API（SSE）
│   ├── ChatStompController.java            # WebSocket（STOMP）
│   ├── ChatConfigController.java           # 配置管理
│   ├── ChatModelController.java            # 模型管理
│   └── ChatUsageTokenController.java       # Token 统计
├── service/                 # 服务层
│   ├── AiKnowledgeChatService.java
│   ├── ChatSessionService.java
│   ├── ChatMessageService.java
│   ├── ChatConfigService.java
│   ├── ChatModelService.java
│   ├── ChatUsageTokenService.java
│   └── impl/                # 服务实现
├── domain/                  # 领域模型
│   ├── bo/                  # 业务对象
│   ├── vo/                  # 视图对象
│   ├── request/             # 请求对象
│   ├── ChatSession.java     # 会话实体
│   ├── ChatMessage.java     # 消息实体
│   ├── ChatConfig.java      # 配置实体
│   ├── ChatModel.java       # 模型实体
│   └── ChatUsageToken.java  # Token 使用实体
├── mapper/                  # MyBatis Mapper
├── config/                  # 配置类
│   └── StompWebSocketConfig.java
└── client/                  # Java SDK
    └── ChatSdk.java

架构设计

┌─────────────────────────────────────────────────────────────┐
│                    Chat Controller Layer                    │
├─────────────────────────────────────────────────────────────┤
│  AIKnowledgeChatController │ ChatSessionController          │
│  ChatMessageController     │ ChatConfigController           │
│  ChatModelController       │ ChatUsageTokenController       │
│  ChatOpenApiController     │ ChatStompController            │
│  (SSE 流式)                │ (WebSocket)                    │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                    Service Layer                            │
├─────────────────────────────────────────────────────────────┤
│  AiKnowledgeChatService    │ ChatSessionService             │
│  ChatMessageService        │ ChatConfigService              │
│  ChatModelService          │ ChatUsageTokenService          │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                 Integration Layer                           │
├─────────────────────────────────────────────────────────────┤
│              RuoYi AI Module                               │
│              └─ AiChatService                              │
│              └─ AiChatHistoryService                       │
│              └─ AiProviderManager                          │
│                                                             │
│              RuoYi Knowledge Module                        │
│              └─ KnowledgeVectorService                     │
│              └─ KnowledgeInfoService                       │
└─────────────────────────────────────────────────────────────┘

数据库表结构

1. 聊天会话表 (chat_session)

存储用户聊天会话信息。

字段名	类型	说明
id	BIGINT	主键ID
user_id	BIGINT	用户ID
session_title	VARCHAR(255)	会话标题
session_content	TEXT	会话内容
create_by	BIGINT	创建者
create_time	DATETIME	创建时间
update_by	BIGINT	更新者
update_time	DATETIME	更新时间
remark	VARCHAR(500)	备注

索引：PRIMARY KEY (id)

2. 聊天消息表 (chat_message)

存储聊天消息记录。

字段名	类型	说明
id	BIGINT	主键ID
session_id	BIGINT	会话ID
user_id	BIGINT	用户ID
content	LONGTEXT	消息内容
role	VARCHAR(255)	对话角色（user/assistant/system）
deduct_cost	DOUBLE(20,2)	扣除金额（默认 0.00）
total_tokens	INT(20)	累计 Tokens（默认 0）
model_name	VARCHAR(255)	模型名称
create_by	BIGINT	创建者
create_time	DATETIME	创建时间
update_by	BIGINT	更新者
update_time	DATETIME	更新时间
remark	VARCHAR(500)	备注

索引：PRIMARY KEY (id)

3. 聊天配置表 (chat_config)

存储聊天系统配置（键值对形式）。

字段名	类型	说明
id	BIGINT	主键ID
category	VARCHAR(255)	配置类型
config_name	VARCHAR(255)	配置名称
config_value	TEXT	配置值
config_dict	VARCHAR(255)	说明
create_by	BIGINT	创建者
create_time	DATETIME	创建时间
update_by	BIGINT	更新者
update_time	DATETIME	更新时间
remark	VARCHAR(500)	备注
version	INT	版本
del_flag	CHAR(1)	删除标志（0存在 1删除）
update_ip	VARCHAR(128)	更新IP

索引：

PRIMARY KEY (id)
UNIQUE KEY unique_category_key (category, config_name)

4. 聊天模型表 (chat_model)

存储聊天模型配置信息。

字段名	类型	说明
id	BIGINT	主键ID
category	VARCHAR(20)	模型分类
model_name	VARCHAR(50)	模型名称
model_describe	VARCHAR(255)	模型描述
model_price	DOUBLE	模型价格
model_type	CHAR(1)	计费类型
model_show	CHAR(1)	是否显示
system_prompt	VARCHAR(255)	系统提示词
api_host	VARCHAR(255)	请求地址
api_key	VARCHAR(255)	密钥
api_url	VARCHAR(50)	请求后缀
create_by	BIGINT	创建者
create_time	DATETIME	创建时间
update_by	BIGINT	更新者
update_time	DATETIME	更新时间
remark	VARCHAR(500)	备注

索引：PRIMARY KEY (id)

5. Token 使用记录表 (chat_usage_token)

存储用户 Token 使用统计。

字段名	类型	说明
id	BIGINT	主键ID
user_id	BIGINT	用户ID
token	INT(10)	待结算 token
model_name	VARCHAR(64)	模型名称
total_token	VARCHAR(255)	累计使用 token

索引：PRIMARY KEY (id)

数据库脚本位置：script/sql/ry_chat.sql

API 接口

知识库聊天接口 (`/chat/knowledge`)

知识库问答

接口：POST /chat/knowledge/chat
说明：基于知识库进行智能问答
权限：chat:knowledge:chat
参数：
- sessionId (Long, 必填) - 会话ID
- userId (Long, 必填) - 用户ID
- question (String, 必填) - 问题
- knowledgeId (Long, 必填) - 知识库ID
- modelName (String, 必填) - 模型名称

创建知识库会话

接口：POST /chat/knowledge/session
说明：创建知识库聊天会话
权限：chat:knowledge:session
参数：
- userId (Long, 必填) - 用户ID
- knowledgeId (Long, 必填) - 知识库ID
- sessionTitle (String, 可选) - 会话标题

搜索知识内容

接口：GET /chat/knowledge/search
说明：搜索知识库内容
权限：chat:knowledge:search
参数：
- knowledgeId (Long, 必填) - 知识库ID
- query (String, 必填) - 查询内容
- limit (Integer, 可选, 默认5) - 返回数量

构建知识上下文

接口：GET /chat/knowledge/context
说明：构建知识库上下文
权限：chat:knowledge:context
参数：
- knowledgeId (Long, 必填) - 知识库ID
- question (String, 必填) - 问题

获取聊天历史

接口：GET /chat/knowledge/history/{sessionId}
说明：获取知识库聊天历史
权限：chat:knowledge:history
参数：
- sessionId (Long, 路径参数) - 会话ID
- limit (Integer, 可选, 默认20) - 返回数量

会话管理接口 (`/chat/session`)

GET /chat/session/list - 查询会话列表（分页）
GET /chat/session/{id} - 获取会话详情
POST /chat/session - 创建新会话
PUT /chat/session - 更新会话
DELETE /chat/session/{ids} - 删除会话（批量）
POST /chat/session/export - 导出会话数据

权限前缀：chat:session:*

消息管理接口 (`/chat/message`)

GET /chat/message/list - 查询消息列表（分页）
GET /chat/message/{id} - 获取消息详情
POST /chat/message - 新增消息
PUT /chat/message - 更新消息
DELETE /chat/message/{ids} - 删除消息（批量）
POST /chat/message/export - 导出消息数据

权限前缀：chat:message:*

开放 API 接口 (`/chat`)

SSE 流式聊天

接口：POST /chat/send
说明：SSE 流式聊天接口，支持 OpenAI 兼容格式
认证：需要登录（@SaCheckLogin）
响应类型：text/event-stream

请求体：JSON 格式

{
  "model": "gpt-3.5-turbo",
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "sessionId": "1",
  "temperature": 0.7,
  "max_tokens": 2000
}

WebSocket 接口

STOMP 消息映射

映射路径：/chat/send
说明：STOMP 协议消息发送
订阅主题：/topic/session/{sessionId}
配置类：StompWebSocketConfig

配置管理接口 (`/chat/config`)

GET /chat/config/list - 查询配置列表（分页）
GET /chat/config/{id} - 获取配置详情
POST /chat/config - 新增配置
PUT /chat/config - 更新配置
DELETE /chat/config/{ids} - 删除配置（批量）
POST /chat/config/export - 导出配置数据

权限前缀：chat:config:*

模型管理接口 (`/chat/model`)

GET /chat/model/list - 查询模型列表（分页）
GET /chat/model/{id} - 获取模型详情
POST /chat/model - 新增模型
PUT /chat/model - 更新模型
DELETE /chat/model/{ids} - 删除模型（批量）
POST /chat/model/export - 导出模型数据

权限前缀：chat:model:*

Token 使用记录接口 (`/chat/token`)

GET /chat/token/list - 查询 Token 使用记录列表（分页）
GET /chat/token/{id} - 获取 Token 使用记录详情
POST /chat/token - 新增 Token 使用记录
PUT /chat/token - 更新 Token 使用记录
DELETE /chat/token/{ids} - 删除 Token 使用记录（批量）
POST /chat/token/export - 导出 Token 使用记录数据

权限前缀：chat:token:*

统一网关与协同

后端统一网关

Chat 模块可通过 ruoyi-ai 模块的统一网关进行对话：

POST /api/ai/chat - 同步聊天
POST /api/ai/chat/async - 异步聊天
POST /api/ai/chat/stream - 流式聊天（SSE）
WS /ws/ai/chat - WebSocket 实时通道

Chat 模块与 AI/Knowledge 的协同

知识库增强聊天：
- 在 AiKnowledgeChatServiceImpl 中构建 AiChatRequest
- 调用 AiChatService.chat，开启知识库增强（enableKnowledge=true）
- 通过 KnowledgeVectorService.vectorSimilaritySearch 进行相关性检索
- 构建上下文并注入到消息中
聊天历史管理：
- 使用 AiChatHistoryService 保存和管理聊天记录
- 支持 Redis 缓存和历史查询
模型管理：
- 通过 AiProviderManager 获取可用模型列表
- 支持模型切换和负载均衡

使用示例

1. 创建知识库会话

curl -X POST "http://localhost:8080/chat/knowledge/session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "userId": 1,
    "knowledgeId": 1,
    "sessionTitle": "技术咨询会话"
  }'

2. 知识库问答

curl -X POST "http://localhost:8080/chat/knowledge/chat" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Bearer <token>" \
  -d "sessionId=1&userId=1&question=什么是Spring Boot？&knowledgeId=1&modelName=gpt-3.5-turbo"

3. SSE 流式聊天

curl -X POST "http://localhost:8080/chat/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    "sessionId": "1",
    "temperature": 0.7
  }'

4. 通过统一网关进行对话

curl -X POST "http://localhost:8080/api/ai/chat" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "userId": "1",
    "sessionId": "1",
    "model": "gpt-4o-mini",
    "enableKnowledge": true,
    "knowledgeId": "1",
    "knowledgeLimit": 5,
    "knowledgeThreshold": 0.7,
    "messages": [
      {"role": "user", "content": "什么是Spring Boot？"}
    ]
  }'

5. 获取聊天历史

curl -X GET "http://localhost:8080/chat/knowledge/history/1?limit=10" \
  -H "Authorization: Bearer <token>"

6. 查询会话列表

curl -X GET "http://localhost:8080/chat/session/list?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer <token>"

Java SDK

ChatSdk（统一网关封装）

封装类：org.dromara.chat.client.ChatSdk

// 初始化 SDK
ChatSdk sdk = new ChatSdk("http://localhost:8080")
    .withToken("Bearer xxx");

// 同步聊天
String result = sdk.chat("{\"model\":\"gpt-4o\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}");

// 流式聊天（SSE）
sdk.chatStream("{\"model\":\"gpt-4o\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}", 
    chunk -> System.out.println(chunk),
    response -> System.out.println("Complete: " + response),
    error -> System.err.println("Error: " + error));

配置说明

应用配置

Chat 模块依赖 ruoyi-ai 模块的配置，主要配置在 application.yml 中：

ruoyi:
  ai:
    # 是否启用 AI 模块
    enabled: true
    
    # 知识库配置
    knowledge:
      enabled: true
      default-search-count: 5
      similarity-threshold: 0.7
      max-context-length: 4000
      
    # 流式响应配置
    stream:
      enabled: true
      buffer-size: 1024
      timeout: 60

WebSocket 配置

WebSocket 配置在 StompWebSocketConfig 中：

端点路径：/ws
消息映射：/chat/send
订阅主题：/topic/session/{sessionId}

数据库配置

确保已执行 script/sql/ry_chat.sql 初始化脚本。

依赖模块

核心依赖

ruoyi-ai: AI 服务集成
- AiChatService - 统一聊天服务
- AiChatHistoryService - 聊天历史服务
- AiProviderManager - Provider 管理器
ruoyi-knowledge: 知识库服务
- KnowledgeVectorService - 向量检索服务
- KnowledgeInfoService - 知识库信息服务
ruoyi-common-core: 核心工具类
ruoyi-common-mybatis: 数据库操作
ruoyi-common-web: Web 框架支持
ruoyi-common-security: 安全认证（Sa-Token）
ruoyi-common-log: 日志记录
ruoyi-common-excel: Excel 导出

开发指南

添加新的聊天类型

创建新的 Controller 类，继承 BaseController
实现对应的 Service 接口
添加相关的 BO 和 VO 类
配置路由映射和权限注解

扩展消息类型

在 ChatMessage 实体中添加新字段
更新数据库表结构（修改 ry_chat.sql）
修改消息处理逻辑
添加相应的验证规则

集成新的 AI 模型

在 ruoyi-ai 模块中添加新的 Provider
在 chat_model 表中添加模型配置
测试模型兼容性
更新文档

WebSocket 扩展

在 StompWebSocketConfig 中添加新的消息映射
创建对应的 Controller 处理消息
配置订阅主题
更新客户端连接代码

认证与权限

认证方式

登录认证：基于 Sa-Token，所有写操作需要登录态（@SaCheckLogin）
权限控制：管理接口需要相应权限（@SaCheckPermission）
令牌格式：Authorization: Bearer <token>

权限列表

chat:knowledge:* - 知识库聊天权限
chat:session:* - 会话管理权限
chat:message:* - 消息管理权限
chat:config:* - 配置管理权限
chat:model:* - 模型管理权限
chat:token:* - Token 统计权限

统一网关权限

统一网关（/api/ai/*）需要相应的 AI 模块权限，如 ai:chat:sync、ai:chat:stream 等。

监控和日志

关键指标

会话创建数量
消息发送成功率
平均响应时间
Token 使用量
错误率统计
知识库检索命中率

日志配置

logging:
  level:
    org.dromara.chat: DEBUG
    org.dromara.ai: INFO
    org.dromara.knowledge: INFO

日志记录

所有接口调用记录（通过 @Log 注解）
异常错误日志
性能监控日志
Token 使用日志

故障排除

常见问题

AI 服务不可用
- 检查 ruoyi-ai 模块状态
- 验证 API 密钥配置
- 查看网络连接
- 检查 Provider 配置
知识库搜索失败
- 确认知识库 ID 有效
- 检查知识库内容是否已索引
- 验证搜索权限
- 查看向量服务状态
会话创建失败
- 检查用户权限
- 验证数据库连接
- 查看参数格式
- 检查会话表结构
SSE 流式响应中断
- 检查网络连接稳定性
- 查看超时配置
- 验证模型响应时间
- 检查服务器资源
WebSocket 连接失败
- 检查 WebSocket 配置
- 验证 STOMP 端点路径
- 查看防火墙设置
- 检查客户端连接代码

性能优化

数据库优化
- 添加适当索引（session_id, user_id, create_time 等）
- 定期清理历史数据
- 使用连接池
- 考虑分表策略（按时间或用户）
缓存策略
- 缓存热门会话
- 缓存知识库搜索结果
- 使用 Redis 缓存会话信息
- 缓存模型配置信息
异步处理
- 异步保存消息
- 后台统计计算
- 队列处理长任务
- 异步日志记录
流式响应优化
- 调整缓冲区大小
- 优化模型响应时间
- 使用连接池管理 SSE 连接
- 实现背压控制

版本历史

v1.0.0: 初始版本，基础聊天功能
v1.1.0: 添加知识库集成（RAG）
v1.2.0: 支持多模型切换
v1.3.0: 增加使用统计功能
v1.4.0: 对接统一 AI 网关与 RAG 能力，完善文档与 SDK
v1.5.0: 添加 SSE 流式支持和 WebSocket 实时通信

贡献指南

Fork 项目
创建功能分支（git checkout -b feature/AmazingFeature）
提交代码变更（git commit -m 'Add some AmazingFeature'）
推送到分支（git push origin feature/AmazingFeature）
创建 Pull Request
等待代码审查

许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

README.md Unescape Escape

RuoYi Chat 模块

模块简介

功能特性

1. 聊天会话管理 ✅

2. 消息处理 ✅

3. 知识库集成（RAG）✅

4. 实时通信 ✅

5. 使用统计 ✅

6. 配置管理 ✅

目录结构

模块结构

架构设计

数据库表结构

1. 聊天会话表 (chat_session)

2. 聊天消息表 (chat_message)

3. 聊天配置表 (chat_config)

4. 聊天模型表 (chat_model)

5. Token 使用记录表 (chat_usage_token)

API 接口

知识库聊天接口 (/chat/knowledge)

知识库问答

创建知识库会话

搜索知识内容

构建知识上下文

获取聊天历史

会话管理接口 (/chat/session)

消息管理接口 (/chat/message)

开放 API 接口 (/chat)

SSE 流式聊天

WebSocket 接口

STOMP 消息映射

配置管理接口 (/chat/config)

模型管理接口 (/chat/model)

Token 使用记录接口 (/chat/token)

统一网关与协同

后端统一网关

Chat 模块与 AI/Knowledge 的协同

使用示例

1. 创建知识库会话

2. 知识库问答

3. SSE 流式聊天

4. 通过统一网关进行对话

5. 获取聊天历史

6. 查询会话列表

Java SDK

ChatSdk（统一网关封装）

配置说明

应用配置

WebSocket 配置

数据库配置

依赖模块

核心依赖

开发指南

添加新的聊天类型

扩展消息类型

集成新的 AI 模型

WebSocket 扩展

认证与权限

认证方式

权限列表

统一网关权限

监控和日志

关键指标

日志配置

日志记录

故障排除

常见问题

性能优化

版本历史

贡献指南

许可证

相关文档

README.md

知识库聊天接口 (`/chat/knowledge`)

会话管理接口 (`/chat/session`)

消息管理接口 (`/chat/message`)

开放 API 接口 (`/chat`)

配置管理接口 (`/chat/config`)

模型管理接口 (`/chat/model`)

Token 使用记录接口 (`/chat/token`)