371 lines
10 KiB
Markdown
371 lines
10 KiB
Markdown
# 小维AI问答系统接口文档
|
||
|
||
## 1. /upload_qa
|
||
|
||
- **方法**: POST
|
||
- **描述**: 该端点用于上传问答文件。上传的文件可以是 `.txt`, `.md`, `.xls`, `.xlsx` 格式。系统会对上传的文件进行以下处理：
|
||
- 文本分割：将大文本拆分为小段落以提高向量化的效率。
|
||
- 向量化：使用嵌入模型将文本转化为向量。
|
||
- 存储：将向量和元数据存储到数据库和本地向量文件中。
|
||
- **异步处理**：若上传文件较大，处理可能耗时较长，任务会以异步方式执行，前端需通过 `/task_status/<task_id>` 查询任务状态。
|
||
|
||
- **请求参数**:
|
||
- `token` (Header): 用户的身份验证令牌。
|
||
- `method` (FormData): 上传操作的类型，如 `create` 或 `delete`。
|
||
- `qa_name` (FormData): 问答库的名称。
|
||
- `private_flag` (FormData): 问答库的私有标志（整数，1 表示私有，0 表示公开）。
|
||
- `files` (FormData): 上传的文件列表。
|
||
|
||
- **返回值**:
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"message": "任务已提交",
|
||
"task_id": "unique-task-id",
|
||
"qa_name": "知识库名称",
|
||
"time_left": "预计剩余时间（秒）"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. /operate_qa
|
||
|
||
- **方法**: POST
|
||
- **描述**: 该端点用于操作向量库，包括以下功能：
|
||
- 查询问答库中的文件或内容。
|
||
- 编辑现有问答记录。
|
||
- 删除指定问答内容。
|
||
- 新增问答记录。
|
||
|
||
- **请求参数**:
|
||
- `token` (Header): 用户的身份验证令牌。
|
||
- `method` (JSON): 操作类型，支持以下值：
|
||
- `list_qa_files`: 列出问答库中的文件。
|
||
- `list_qa_content`: 列出问答内容。
|
||
- `query_qa_content`: 根据条件查询问答内容。
|
||
- `edit_qa_content`: 编辑问答内容。
|
||
- `delete_qa_content`: 删除指定问答内容。
|
||
- `add_qa_content`: 新增问答内容。
|
||
- `query_fields` (JSON): 查询条件字段（用于精确匹配）。
|
||
- `fuzzy_fields` (JSON): 模糊查询字段（仅对 `query_qa_content` 有效）。
|
||
- `edit_fields` (JSON): 编辑字段（仅对 `edit_qa_content` 有效）。
|
||
|
||
- **返回值**:
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"message": "操作成功",
|
||
"records": [
|
||
{
|
||
"sys_id": "记录ID",
|
||
"question": "问题内容",
|
||
"answer": "回答内容",
|
||
"qa_name": "知识库名称",
|
||
"source": "来源文件名",
|
||
"raw_text": "原始文本",
|
||
"score": "相似度分数"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. /chat_qa
|
||
|
||
- **方法**: POST
|
||
- **描述**: 用户可以通过该端点与问答系统进行交互。系统会根据用户输入的问题，从向量库中查找最相关的问答记录并返回结果。
|
||
|
||
- **请求参数**:
|
||
- `token` (Header): 用户的身份验证令牌。
|
||
- `qa_name` (JSON): 问答库的名称（支持多个）。
|
||
- `query` (JSON): 用户输入的问题。
|
||
- `uuid` (JSON): 用户会话的唯一标识符（可选）。
|
||
|
||
- **返回值**:
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"message": "问题答案",
|
||
"qa_name": "相关知识库",
|
||
"source": "来源文件名",
|
||
"flag": true,
|
||
"related_content": [
|
||
{
|
||
"question": "相关问题",
|
||
"answer": "相关回答",
|
||
"qa_name": "知识库名称",
|
||
"source": "来源文件名",
|
||
"score": "相似度分数"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. /task_status/<task_id>
|
||
|
||
- **方法**: GET
|
||
- **描述**: 查询后台任务的状态。通过任务 ID 检查任务的执行情况。
|
||
|
||
- **请求参数**:
|
||
- `task_id` (Path): 任务的唯一标识符。
|
||
|
||
- **返回值**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "任务已完成",
|
||
"status": "SUCCESS"
|
||
}
|
||
```
|
||
或：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "后台任务正在运行",
|
||
"status": "PENDING"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. /change_question
|
||
|
||
- **方法**: POST
|
||
- **描述**: 用户可以通过该端点更改问题的内容，系统会返回相关的问答记录。
|
||
|
||
- **请求参数**:
|
||
- `qa_name` (JSON): 问答库的名称（支持多个）。
|
||
- `query` (JSON): 用户输入的问题。
|
||
- `cur_page` (JSON): 当前页码（默认为 1）。
|
||
|
||
- **返回值**:
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"message": "",
|
||
"flag": true,
|
||
"related_content": [
|
||
{
|
||
"question": "相关问题",
|
||
"answer": "相关回答",
|
||
"qa_name": "知识库名称",
|
||
"source": "来源文件名",
|
||
"score": "相似度分数"
|
||
}
|
||
],
|
||
"question_counts": "相关问题总数",
|
||
"cur_page": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. /default_answers
|
||
|
||
- **方法**: POST
|
||
- **描述**: 管理默认回答，包括新增、更新、删除和查询。
|
||
|
||
- **请求参数**:
|
||
- `token` (Header): 用户的身份验证令牌。
|
||
- `method` (JSON): 操作类型（`add`, `update`, `delete`, `list`）。
|
||
- `qa_name` (JSON): 知识库的名称。
|
||
- `answer` (JSON): 默认回答内容（新增或更新时必填）。
|
||
- `keywords` (JSON): 关键字（可选）。
|
||
|
||
- **返回值**:
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"message": "操作成功",
|
||
"data": [
|
||
{
|
||
"sys_id": "回答ID",
|
||
"answer": "回答内容",
|
||
"keywords": "相关关键字",
|
||
"create_time": "创建时间"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. /transfer_qa
|
||
|
||
- **方法**: POST
|
||
- **描述**: 将问答记录从一个知识库转移到另一个知识库。
|
||
|
||
- **请求参数**:
|
||
- `token` (Header): 用户的身份验证令牌。
|
||
- `target_qa` (JSON): 目标知识库的名称。
|
||
- `qa_ids` (JSON): 要转移的问答记录 ID 列表。
|
||
|
||
- **返回值**:
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"message": "成功转移 3 条问答对",
|
||
"data": {
|
||
"transferred_records": [
|
||
{
|
||
"sys_id": "记录ID",
|
||
"question": "问题",
|
||
"answer": "答案",
|
||
"source_qa": "源知识库"
|
||
}
|
||
],
|
||
"target_qa": "目标知识库"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. /update_qa_fields
|
||
|
||
- **方法**: POST
|
||
- **描述**: 更新问答记录的字段。
|
||
|
||
- **请求参数**:
|
||
- `token` (Header): 用户的身份验证令牌。
|
||
- `sys_id` (JSON): 要更新的问答记录的 ID。
|
||
- `answer_type` (JSON): 新的答案类型。
|
||
- `category` (JSON): 新的分类。
|
||
|
||
- **返回值**:
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"message": "更新成功",
|
||
"data": {
|
||
"sys_id": "记录ID",
|
||
"question": "问题",
|
||
"answer_type": "新答案类型",
|
||
"category": "新分类"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 数据结构描述
|
||
|
||
### 数据库结构
|
||
- **Roles**: 用户角色表，包含角色 ID 和角色名称。
|
||
- **Users**: 用户表，包含用户 ID、账号、密码哈希和角色 ID。
|
||
- **QAKnowledge**: 问答知识库表，包含问题、答案、来源、知识库名称等。
|
||
- **DefaultAnswers**: 默认回答表，包含默认回答 ID、回答内容、关键字等。
|
||
- **DefaultAnswerConfig**: 默认回答配置表，包含配置的回答 ID 列表、随机使用标志等。
|
||
|
||
---
|
||
|
||
## 交互逻辑
|
||
|
||
1. **前端应用**: 用户通过前端应用发送请求。
|
||
2. **Java 服务**: 接收请求并调用本服务的 API。
|
||
3. **本服务**: 处理 API 请求并返回结果。
|
||
4. **数据库更新**: Java 服务和本服务分别更新其数据库。
|
||
|
||
```mermaid
|
||
graph TD;
|
||
A[前端应用] -->|发送请求| B[Java 服务]
|
||
B -->|处理请求| C[本服务]
|
||
C -->|返回结果| B
|
||
B -->|返回结果| A
|
||
A -->|用户输入| B
|
||
B -->|更新数据库| D[Java 服务数据库]
|
||
C -->|更新数据库| E[本服务数据库]
|
||
```
|
||
|
||
在上述代码中，涉及 **异步操作** 的部分主要集中在需要执行时间较长的任务，例如文件处理、向量化、模型预测等。以下是需要前端轮询 `task_status` 以获取任务完成状态的部分，以及每个部分的详细说明。
|
||
|
||
---
|
||
|
||
## **异步操作**
|
||
### 1. **`upload_qa` 方法的异步任务**
|
||
```python
|
||
future = executor.submit(add_qa_task_, upload_path, vs_path, create_id, private_flag, file_list, hash_list, qa_name)
|
||
tasks[task_id] = future
|
||
```
|
||
|
||
**描述**：
|
||
- 在 `upload_qa` 接口中，`add_qa_task_` 函数通过 `ThreadPoolExecutor` 异步执行。
|
||
- 该任务负责对上传的文件进行处理，包括文本加载、拆分、向量化、存储和数据库操作。
|
||
- 返回的 `task_id` 供前端使用，通过轮询 `/task_status/<task_id>` 获取任务进度。
|
||
|
||
**需要轮询字段**：
|
||
- `task_id`: 任务唯一标识。
|
||
- 状态值包括：
|
||
- `PENDING`: 正在处理。
|
||
- `SUCCESS`: 完成。
|
||
- `ERROR`: 出错。
|
||
|
||
---
|
||
|
||
### 2. **`test_qa` 方法的异步任务**
|
||
```python
|
||
future = executor.submit(add_qa_task_, upload_path, vs_path, 3, False, file_list, hash_list, 'test')
|
||
tasks[task_id] = future
|
||
```
|
||
|
||
**描述**：
|
||
- 用于测试上传和处理文件的功能，逻辑与 `upload_qa` 类似。
|
||
- 前端需要通过 `task_id` 查询任务状态。
|
||
|
||
**需要轮询字段**：
|
||
- 同上，`task_id` 是关键字段。
|
||
|
||
---
|
||
|
||
### **通用异步任务的状态查询接口**
|
||
#### `task_status` 接口
|
||
```python
|
||
@app.route('/task_status/<task_id>', methods=['GET'])
|
||
def task_status(task_id):
|
||
...
|
||
if task.done():
|
||
...
|
||
ret_dict['status'] = "SUCCESS" if result else "ERROR"
|
||
else:
|
||
ret_dict['status'] = "PENDING"
|
||
```
|
||
|
||
**描述**：
|
||
- 通用接口，用于查询所有异步任务的状态。
|
||
- 返回值 `status` 表示任务的当前状态：
|
||
- `PENDING`: 任务尚未完成。
|
||
- `SUCCESS`: 任务成功完成。
|
||
- `ERROR`: 任务失败。
|
||
|
||
---
|
||
|
||
### **轮询场景详细说明**
|
||
1. **轮询间隔**：
|
||
- 前端每隔 1-2 秒向 `/task_status/<task_id>` 发起一次请求。
|
||
- 使用任务完成 (`SUCCESS` 或 `ERROR`) 的响应作为停止轮询的标志。
|
||
|
||
2. **任务完成后的操作**：
|
||
- **任务成功 (`SUCCESS`)**：
|
||
- 显示任务处理完成的消息。
|
||
- 根据任务结果更新页面数据或触发后续操作。
|
||
- **任务失败 (`ERROR`)**：
|
||
- 显示失败原因，允许用户重新发起任务。
|
||
|
||
3. **接口使用示例**：
|
||
- `GET /task_status/<task_id>`：
|
||
- **请求参数**：`task_id`。
|
||
- **响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "后台任务已完成",
|
||
"status": "SUCCESS"
|
||
}
|
||
```
|
||
|
||
---
|