weida_doc/接口文档.md

小维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): 上传的文件列表。

• 返回值:

  {
    "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 有效）。

• 返回值:

  {
    "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): 用户会话的唯一标识符（可选）。

• 返回值:

  {
    "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): 任务的唯一标识符。

• 返回值:

  {
    "code": 200,
    "message": "任务已完成",
    "status": "SUCCESS"
  }
  

  或：

  {
    "code": 200,
    "message": "后台任务正在运行",
    "status": "PENDING"
  }
  

---

5. /change_question

• 方法: POST

• 描述: 用户可以通过该端点更改问题的内容，系统会返回相关的问答记录。

• 请求参数:

  • qa_name (JSON): 问答库的名称（支持多个）。
  • query (JSON): 用户输入的问题。
  • cur_page (JSON): 当前页码（默认为 1）。

• 返回值:

  {
    "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): 关键字（可选）。

• 返回值:

  {
    "code": 1,
    "message": "操作成功",
    "data": [
      {
        "sys_id": "回答ID",
        "answer": "回答内容",
        "keywords": "相关关键字",
        "create_time": "创建时间"
      }
    ]
  }
  

---

7. /transfer_qa

• 方法: POST

• 描述: 将问答记录从一个知识库转移到另一个知识库。

• 请求参数:

  • token (Header): 用户的身份验证令牌。
  • target_qa (JSON): 目标知识库的名称。
  • qa_ids (JSON): 要转移的问答记录 ID 列表。

• 返回值:

  {
    "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): 新的分类。

• 返回值:

  {
    "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 服务和本服务分别更新其数据库。

graph TD;
A[前端应用] -->|发送请求| B[Java 服务]
B -->|处理请求| C[本服务]
C -->|返回结果| B
B -->|返回结果| A
A -->|用户输入| B
B -->|更新数据库| D[Java 服务数据库]
C -->|更新数据库| E[本服务数据库]

在上述代码中，涉及 异步操作 的部分主要集中在需要执行时间较长的任务，例如文件处理、向量化、模型预测等。以下是需要前端轮询 task_status 以获取任务完成状态的部分，以及每个部分的详细说明。

---

异步操作

1. upload_qa 方法的异步任务

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 方法的异步任务

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 接口

@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。
     • 响应示例：

       {
         "code": 200,
         "message": "后台任务已完成",
         "status": "SUCCESS"
       }
       

---