J/daren

Fork 0

jlj bca9490fba 添加单个单人简易信息

2025-05-23 20:35:52 +08:00

8.9 KiB

Raw Blame History

Chat 模块接口文档

概述

Chat 模块提供了一组 API，用于创建和管理对话。这包括创建新对话、发送消息、接收回答、查询历史记录等功能。所有接口都基于 REST 风格设计。

认证

除特殊说明外，所有接口都需要认证。请在请求头中添加认证信息：

Authorization: Bearer <jwt_token>

或

Authorization: Token <token>

REST API接口列表

1. 创建会话

创建一个新的对话会话。

URL: /api/chat-history/create_conversation/
方法: POST
认证: 不需要认证
响应:

{
  "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

响应 (非流式):

{
  "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

响应:

{
  "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

响应:

{
  "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

响应:

{
  "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

响应:

{
  "code": 200,
  "message": "删除成功",
  "data": {
    "conversation_id": "会话ID",
    "deleted_count": 删除的消息数量
  }
}

7. 更新消息内容

更新单条消息的内容。

URL: /api/chat-history/{id}/
方法: PUT 或 PATCH
参数:

参数名	类型	必填	描述
content	string	否	更新的消息内容
metadata	object	否	更新的元数据

响应:

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": "记录ID",
    "conversation_id": "会话ID",
    "role": "角色",
    "content": "更新后的内容",
    "metadata": {},
    "updated_at": "更新时间"
  }
}

8. 删除单条消息

删除单条消息（软删除）。

URL: /api/chat-history/{id}/
方法: DELETE
响应:

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

9. 更新会话标题

设置或更新会话的标题。

URL: /api/chat-history/generate-conversation-title/
方法: GET
参数:

参数名	类型	必填	描述
conversation_id	string	是	会话 ID
title	string	是	新标题

响应:

{
  "code": 200,
  "message": "更新会话标题成功",
  "data": {
    "conversation_id": "会话ID",
    "title": "新标题"
  }
}

10. 获取可用知识库

获取系统中可用的知识库列表。

URL: /api/chat-history/available_datasets/
方法: GET
响应:

{
  "code": 200,
  "message": "获取成功",
  "data": []
}

11. 根据ID获取达人信息

根据达人ID获取单个达人的详细信息。

URL: /api/chat-history/get_creator_by_id/
方法: GET
参数:

参数名	类型	必填	描述
id	integer	是	达人ID

响应:

{
  "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"]
  }
}

错误响应:

缺少参数时：

{
  "code": 400,
  "message": "缺少必要参数: id",
  "data": null
}

达人不存在时：

{
  "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格式的消息：

{
  "conversation_id": "会话ID",
  "question": "用户问题"
}

3. 接收响应

WebSocket会返回以下JSON格式的消息：

开始流式传输：

{
  "code": 200,
  "message": "开始流式传输",
  "data": {
    "id": "记录ID",
    "conversation_id": "会话ID",
    "content": "",
    "is_end": false
  }
}

部分内容：

{
  "code": 200,
  "message": "partial",
  "data": {
    "id": "记录ID",
    "conversation_id": "会话ID",
    "content": "部分内容",
    "is_end": false
  }
}

完成响应：

{
  "code": 200,
  "message": "完成",
  "data": {
    "id": "记录ID",
    "conversation_id": "会话ID",
    "title": "会话标题",
    "role": "assistant",
    "content": "完整内容",
    "created_at": "时间",
    "is_end": true
  }
}

错误响应：

{
  "code": 500,
  "message": "错误信息",
  "data": {
    "is_end": true
  }
}

错误响应

所有接口在出错时都会返回类似的错误响应结构：

{
  "code": 错误代码,
  "message": "错误描述",
  "data": null
}

常见错误代码：

400: 请求参数错误
401: 未认证或认证失败
404: 资源不存在
500: 服务器内部错误

8.9 KiB Raw Blame History Unescape Escape