shuolol
ae14e54b8c
- 新增宠物医疗上下文实体类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模板
748 lines
24 KiB
Markdown
748 lines
24 KiB
Markdown
# 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 <token>" \
|
||
-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 <token>" \
|
||
-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 <token>" \
|
||
-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 <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. 获取聊天历史
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/chat/knowledge/history/1?limit=10" \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
### 6. 查询会话列表
|
||
|
||
```bash
|
||
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`
|
||
|
||
```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 <token>`
|
||
|
||
### 权限列表
|
||
|
||
- `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)
|