# 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 格式 ```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 的协同 1. **知识库增强聊天**: - 在 `AiKnowledgeChatServiceImpl` 中构建 `AiChatRequest` - 调用 `AiChatService.chat`,开启知识库增强(`enableKnowledge=true`) - 通过 `KnowledgeVectorService.vectorSimilaritySearch` 进行相关性检索 - 构建上下文并注入到消息中 2. **聊天历史管理**: - 使用 `AiChatHistoryService` 保存和管理聊天记录 - 支持 Redis 缓存和历史查询 3. **模型管理**: - 通过 `AiProviderManager` 获取可用模型列表 - 支持模型切换和负载均衡 ## 使用示例 ### 1. 创建知识库会话 ```bash curl -X POST "http://localhost:8080/chat/knowledge/session" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "userId": 1, "knowledgeId": 1, "sessionTitle": "技术咨询会话" }' ``` ### 2. 知识库问答 ```bash curl -X POST "http://localhost:8080/chat/knowledge/chat" \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Authorization: Bearer " \ -d "sessionId=1&userId=1&question=什么是Spring Boot?&knowledgeId=1&modelName=gpt-3.5-turbo" ``` ### 3. SSE 流式聊天 ```bash curl -X POST "http://localhost:8080/chat/send" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -H "Accept: text/event-stream" \ -d '{ "model": "gpt-3.5-turbo", "messages": [ {"role": "user", "content": "你好,请介绍一下你自己"} ], "sessionId": "1", "temperature": 0.7 }' ``` ### 4. 通过统一网关进行对话 ```bash curl -X POST "http://localhost:8080/api/ai/chat" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -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. 获取聊天历史 ```bash curl -X GET "http://localhost:8080/chat/knowledge/history/1?limit=10" \ -H "Authorization: Bearer " ``` ### 6. 查询会话列表 ```bash curl -X GET "http://localhost:8080/chat/session/list?pageNum=1&pageSize=10" \ -H "Authorization: Bearer " ``` ## Java SDK ### ChatSdk(统一网关封装) 封装类:`org.dromara.chat.client.ChatSdk` ```java // 初始化 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` 中: ```yaml 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 导出 ## 开发指南 ### 添加新的聊天类型 1. 创建新的 Controller 类,继承 `BaseController` 2. 实现对应的 Service 接口 3. 添加相关的 BO 和 VO 类 4. 配置路由映射和权限注解 ### 扩展消息类型 1. 在 `ChatMessage` 实体中添加新字段 2. 更新数据库表结构(修改 `ry_chat.sql`) 3. 修改消息处理逻辑 4. 添加相应的验证规则 ### 集成新的 AI 模型 1. 在 `ruoyi-ai` 模块中添加新的 Provider 2. 在 `chat_model` 表中添加模型配置 3. 测试模型兼容性 4. 更新文档 ### WebSocket 扩展 1. 在 `StompWebSocketConfig` 中添加新的消息映射 2. 创建对应的 Controller 处理消息 3. 配置订阅主题 4. 更新客户端连接代码 ## 认证与权限 ### 认证方式 - **登录认证**:基于 Sa-Token,所有写操作需要登录态(`@SaCheckLogin`) - **权限控制**:管理接口需要相应权限(`@SaCheckPermission`) - **令牌格式**:`Authorization: Bearer ` ### 权限列表 - `chat:knowledge:*` - 知识库聊天权限 - `chat:session:*` - 会话管理权限 - `chat:message:*` - 消息管理权限 - `chat:config:*` - 配置管理权限 - `chat:model:*` - 模型管理权限 - `chat:token:*` - Token 统计权限 ### 统一网关权限 统一网关(`/api/ai/*`)需要相应的 AI 模块权限,如 `ai:chat:sync`、`ai:chat:stream` 等。 ## 监控和日志 ### 关键指标 - 会话创建数量 - 消息发送成功率 - 平均响应时间 - Token 使用量 - 错误率统计 - 知识库检索命中率 ### 日志配置 ```yaml logging: level: org.dromara.chat: DEBUG org.dromara.ai: INFO org.dromara.knowledge: INFO ``` ### 日志记录 - 所有接口调用记录(通过 `@Log` 注解) - 异常错误日志 - 性能监控日志 - Token 使用日志 ## 故障排除 ### 常见问题 1. **AI 服务不可用** - 检查 `ruoyi-ai` 模块状态 - 验证 API 密钥配置 - 查看网络连接 - 检查 Provider 配置 2. **知识库搜索失败** - 确认知识库 ID 有效 - 检查知识库内容是否已索引 - 验证搜索权限 - 查看向量服务状态 3. **会话创建失败** - 检查用户权限 - 验证数据库连接 - 查看参数格式 - 检查会话表结构 4. **SSE 流式响应中断** - 检查网络连接稳定性 - 查看超时配置 - 验证模型响应时间 - 检查服务器资源 5. **WebSocket 连接失败** - 检查 WebSocket 配置 - 验证 STOMP 端点路径 - 查看防火墙设置 - 检查客户端连接代码 ### 性能优化 1. **数据库优化** - 添加适当索引(session_id, user_id, create_time 等) - 定期清理历史数据 - 使用连接池 - 考虑分表策略(按时间或用户) 2. **缓存策略** - 缓存热门会话 - 缓存知识库搜索结果 - 使用 Redis 缓存会话信息 - 缓存模型配置信息 3. **异步处理** - 异步保存消息 - 后台统计计算 - 队列处理长任务 - 异步日志记录 4. **流式响应优化** - 调整缓冲区大小 - 优化模型响应时间 - 使用连接池管理 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 实时通信 ## 贡献指南 1. Fork 项目 2. 创建功能分支(`git checkout -b feature/AmazingFeature`) 3. 提交代码变更(`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支(`git push origin feature/AmazingFeature`) 5. 创建 Pull Request 6. 等待代码审查 ## 许可证 本项目采用 MIT 许可证,详见 LICENSE 文件。 ## 相关文档 - [RuoYi AI 模块文档](../ruoyi-ai/README.md) - [RuoYi Knowledge 模块文档](../ruoyi-knowledge/README.md) - [API 使用文档](./docs/API.md)