470 lines
8.9 KiB
Markdown
470 lines
8.9 KiB
Markdown
# Chat 模块接口文档
|
||
|
||
## 概述
|
||
|
||
Chat 模块提供了一组 API，用于创建和管理对话。这包括创建新对话、发送消息、接收回答、查询历史记录等功能。所有接口都基于 REST 风格设计。
|
||
|
||
## 认证
|
||
|
||
除特殊说明外，所有接口都需要认证。请在请求头中添加认证信息：
|
||
|
||
```
|
||
Authorization: Bearer <jwt_token>
|
||
```
|
||
|
||
或
|
||
|
||
```
|
||
Authorization: Token <token>
|
||
```
|
||
|
||
## REST API接口列表
|
||
|
||
### 1. 创建会话
|
||
|
||
创建一个新的对话会话。
|
||
|
||
- **URL**: `/api/chat-history/create_conversation/`
|
||
- **方法**: `POST`
|
||
- **认证**: 不需要认证
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "会话创建成功",
|
||
"data": {
|
||
"conversation_id": "uuid-string"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 发送消息并接收回答
|
||
|
||
发送用户问题并获取 AI 回答。
|
||
|
||
- **URL**: `/api/chat-history/`
|
||
- **方法**: `POST`
|
||
- **参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| conversation_id | string | 是 | 会话 ID |
|
||
| question | string | 是 | 用户问题 |
|
||
| title | string | 否 | 会话标题，默认为 "New chat" |
|
||
| stream | boolean | 否 | 是否使用流式响应，默认为 true |
|
||
|
||
- **响应** (非流式):
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"id": "记录ID",
|
||
"conversation_id": "会话ID",
|
||
"title": "会话标题",
|
||
"role": "assistant",
|
||
"content": "AI回答内容",
|
||
"created_at": "创建时间"
|
||
}
|
||
}
|
||
```
|
||
|
||
- **响应** (流式):
|
||
|
||
返回 `text/event-stream` 类型的响应，包含多个 data 事件：
|
||
|
||
```
|
||
data: {"code": 200, "message": "开始流式传输", "data": {"id": "记录ID", "conversation_id": "会话ID", "content": "", "is_end": false}}
|
||
|
||
data: {"code": 200, "message": "partial", "data": {"id": "记录ID", "conversation_id": "会话ID", "title": "标题", "content": "部分内容", "is_end": false}}
|
||
|
||
...
|
||
|
||
data: {"code": 200, "message": "完成", "data": {"id": "记录ID", "conversation_id": "会话ID", "title": "标题", "role": "assistant", "content": "完整内容", "created_at": "时间", "is_end": true}}
|
||
```
|
||
|
||
### 3. 获取对话列表
|
||
|
||
获取用户的所有对话列表。
|
||
|
||
- **URL**: `/api/chat-history/`
|
||
- **方法**: `GET`
|
||
- **参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| page | integer | 否 | 页码，默认为 1 |
|
||
| page_size | integer | 否 | 每页条数，默认为 10 |
|
||
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"total": 总记录数,
|
||
"page": 当前页码,
|
||
"page_size": 每页条数,
|
||
"results": [
|
||
{
|
||
"conversation_id": "会话ID",
|
||
"message_count": 消息数量,
|
||
"last_message": "最后一条消息内容",
|
||
"last_time": "最后更新时间"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 获取对话详情
|
||
|
||
获取特定对话的所有消息。
|
||
|
||
- **URL**: `/api/chat-history/conversation_detail/`
|
||
- **方法**: `GET`
|
||
- **参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| conversation_id | string | 是 | 会话 ID |
|
||
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"conversation_id": "会话ID",
|
||
"title": "会话标题",
|
||
"created_at": "创建时间",
|
||
"messages": [
|
||
{
|
||
"id": "消息ID",
|
||
"role": "用户角色(user/assistant)",
|
||
"content": "消息内容",
|
||
"created_at": "创建时间"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 搜索聊天记录
|
||
|
||
根据关键词搜索聊天记录。
|
||
|
||
- **URL**: `/api/chat-history/search/`
|
||
- **方法**: `GET`
|
||
- **参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| keyword | string | 否 | 搜索关键词 |
|
||
| start_date | string | 否 | 开始日期，格式为 YYYY-MM-DD |
|
||
| end_date | string | 否 | 结束日期，格式为 YYYY-MM-DD |
|
||
| page | integer | 否 | 页码，默认为 1 |
|
||
| page_size | integer | 否 | 每页条数，默认为 10 |
|
||
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "搜索成功",
|
||
"data": {
|
||
"total": 总记录数,
|
||
"page": 当前页码,
|
||
"page_size": 每页条数,
|
||
"results": [
|
||
{
|
||
"id": "记录ID",
|
||
"conversation_id": "会话ID",
|
||
"role": "角色",
|
||
"content": "内容",
|
||
"created_at": "创建时间",
|
||
"metadata": {},
|
||
"highlights": {
|
||
"content": "高亮后的内容"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. 删除会话
|
||
|
||
删除整个会话及其所有消息。
|
||
|
||
- **URL**: `/api/chat-history/delete_conversation/`
|
||
- **方法**: `DELETE`
|
||
- **参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| conversation_id | string | 是 | 要删除的会话 ID |
|
||
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "删除成功",
|
||
"data": {
|
||
"conversation_id": "会话ID",
|
||
"deleted_count": 删除的消息数量
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7. 更新消息内容
|
||
|
||
更新单条消息的内容。
|
||
|
||
- **URL**: `/api/chat-history/{id}/`
|
||
- **方法**: `PUT` 或 `PATCH`
|
||
- **参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| content | string | 否 | 更新的消息内容 |
|
||
| metadata | object | 否 | 更新的元数据 |
|
||
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "更新成功",
|
||
"data": {
|
||
"id": "记录ID",
|
||
"conversation_id": "会话ID",
|
||
"role": "角色",
|
||
"content": "更新后的内容",
|
||
"metadata": {},
|
||
"updated_at": "更新时间"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8. 删除单条消息
|
||
|
||
删除单条消息（软删除）。
|
||
|
||
- **URL**: `/api/chat-history/{id}/`
|
||
- **方法**: `DELETE`
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "删除成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 9. 更新会话标题
|
||
|
||
设置或更新会话的标题。
|
||
|
||
- **URL**: `/api/chat-history/generate-conversation-title/`
|
||
- **方法**: `GET`
|
||
- **参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| conversation_id | string | 是 | 会话 ID |
|
||
| title | string | 是 | 新标题 |
|
||
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "更新会话标题成功",
|
||
"data": {
|
||
"conversation_id": "会话ID",
|
||
"title": "新标题"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 10. 获取可用知识库
|
||
|
||
获取系统中可用的知识库列表。
|
||
|
||
- **URL**: `/api/chat-history/available_datasets/`
|
||
- **方法**: `GET`
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": []
|
||
}
|
||
```
|
||
|
||
### 11. 根据ID获取达人信息
|
||
|
||
根据达人ID获取单个达人的详细信息。
|
||
|
||
- **URL**: `/api/chat-history/get_creator_by_id/`
|
||
- **方法**: `GET`
|
||
- **参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| id | integer | 是 | 达人ID |
|
||
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "Michelle",
|
||
"avatar_url": "http://example.com/avatar.jpg",
|
||
"category": "Clothing & Accessories",
|
||
"mcn": "--",
|
||
"pricing": "$100/video",
|
||
"collab": ["SUNLINK", "ARZOPA"]
|
||
}
|
||
}
|
||
```
|
||
|
||
- **错误响应**:
|
||
|
||
缺少参数时：
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "缺少必要参数: id",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
达人不存在时：
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "未找到该达人信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## WebSocket API
|
||
|
||
除了REST API之外，Chat模块还提供了WebSocket接口，用于实时流式获取对话回答。
|
||
|
||
### 1. 建立WebSocket连接
|
||
|
||
- **URL**: `ws://yourdomain:port/ws/chat/stream/?token=<your_token>`
|
||
- **认证**: 需要在URL参数中提供token
|
||
- **说明**: token是用户的认证token，即登录接口获取的token，通过UserToken模型验证
|
||
- **获取token**: 通过API登录接口获取token：
|
||
```
|
||
POST /api/user/login/
|
||
{
|
||
"email": "用户邮箱",
|
||
"password": "用户密码"
|
||
}
|
||
```
|
||
成功登录后，响应将返回token字段值
|
||
|
||
### 2. 发送消息
|
||
|
||
连接建立后，可以向WebSocket发送JSON格式的消息：
|
||
|
||
```json
|
||
{
|
||
"conversation_id": "会话ID",
|
||
"question": "用户问题"
|
||
}
|
||
```
|
||
|
||
### 3. 接收响应
|
||
|
||
WebSocket会返回以下JSON格式的消息：
|
||
|
||
1. 开始流式传输：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "开始流式传输",
|
||
"data": {
|
||
"id": "记录ID",
|
||
"conversation_id": "会话ID",
|
||
"content": "",
|
||
"is_end": false
|
||
}
|
||
}
|
||
```
|
||
|
||
2. 部分内容：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "partial",
|
||
"data": {
|
||
"id": "记录ID",
|
||
"conversation_id": "会话ID",
|
||
"content": "部分内容",
|
||
"is_end": false
|
||
}
|
||
}
|
||
```
|
||
|
||
3. 完成响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "完成",
|
||
"data": {
|
||
"id": "记录ID",
|
||
"conversation_id": "会话ID",
|
||
"title": "会话标题",
|
||
"role": "assistant",
|
||
"content": "完整内容",
|
||
"created_at": "时间",
|
||
"is_end": true
|
||
}
|
||
}
|
||
```
|
||
|
||
4. 错误响应：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "错误信息",
|
||
"data": {
|
||
"is_end": true
|
||
}
|
||
}
|
||
```
|
||
|
||
## 错误响应
|
||
|
||
所有接口在出错时都会返回类似的错误响应结构：
|
||
|
||
```json
|
||
{
|
||
"code": 错误代码,
|
||
"message": "错误描述",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
常见错误代码：
|
||
- 400: 请求参数错误
|
||
- 401: 未认证或认证失败
|
||
- 404: 资源不存在
|
||
- 500: 服务器内部错误
|