- 新增宠物医疗上下文实体类BizPetMedicalContext - 创建宠物医疗上下文业务对象BizPetMedicalContextBo - 实现宠物医疗上下文控制器BizPetMedicalContextController - 添加宠物医疗上下文数据访问层BizPetMedicalContextMapper - 实现宠物医疗上下文服务层BizPetMedicalContextServiceImpl - 创建宠物医疗上下文视图对象BizPetMedicalContextVo - 生成前端API接口文件api.d.ts.vm和api.ts.vm - 创建Vue组件模板index.vue.vm和操作抽屉operate-drawer.vue.vm - 更新代码生成配置generator.yml支持宠物模块 - 添加树形表格支持index-tree.vue.vm模板
RuoYi Chat 模块
模块简介
ruoyi-chat 是 PoJie 项目的智能聊天系统模块,提供完整的聊天会话管理、消息处理、知识库集成和实时通信功能。该模块通过集成 ruoyi-ai 和 ruoyi-knowledge 模块,实现了基于知识库的智能问答系统(RAG),支持多种通信方式(REST API、SSE 流式、WebSocket)。
功能特性
1. 聊天会话管理 ✅
- ✅ 创建和管理聊天会话
- ✅ 支持多用户并发聊天
- ✅ 会话历史记录和导出
- ✅ 会话状态管理
- ✅ 会话标题自动生成和手动编辑
2. 消息处理 ✅
- ✅ 实时消息发送和接收
- ✅ 消息类型支持(文本、图片等)
- ✅ 消息历史查询(支持分页和条件筛选)
- ✅ 消息状态跟踪
- ✅ Token 使用量和成本统计
3. 知识库集成(RAG)✅
- ✅ 基于知识库的智能问答
- ✅ 上下文理解和构建
- ✅ 向量相似度搜索
- ✅ 智能回复生成
- ✅ 知识库会话管理
- ✅ 知识库内容搜索
- 内部对接模块:
- AI 模块:
AiChatService(统一聊天接口) - 知识库模块:
KnowledgeVectorService(向量检索)
- AI 模块:
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, 必填) - 会话IDuserId(Long, 必填) - 用户IDquestion(String, 必填) - 问题knowledgeId(Long, 必填) - 知识库IDmodelName(String, 必填) - 模型名称
创建知识库会话
- 接口:
POST /chat/knowledge/session - 说明:创建知识库聊天会话
- 权限:
chat:knowledge:session - 参数:
userId(Long, 必填) - 用户IDknowledgeId(Long, 必填) - 知识库IDsessionTitle(String, 可选) - 会话标题
搜索知识内容
- 接口:
GET /chat/knowledge/search - 说明:搜索知识库内容
- 权限:
chat:knowledge:search - 参数:
knowledgeId(Long, 必填) - 知识库IDquery(String, 必填) - 查询内容limit(Integer, 可选, 默认5) - 返回数量
构建知识上下文
- 接口:
GET /chat/knowledge/context - 说明:构建知识库上下文
- 权限:
chat:knowledge:context - 参数:
knowledgeId(Long, 必填) - 知识库IDquestion(String, 必填) - 问题
获取聊天历史
- 接口:
GET /chat/knowledge/history/{sessionId} - 说明:获取知识库聊天历史
- 权限:
chat:knowledge:history - 参数:
sessionId(Long, 路径参数) - 会话IDlimit(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 文件。