QAnything项目API接口详解与使用指南

QAnything项目API接口详解与使用指南

QAnything 项目地址: https://gitcode.com/gh_mirrors/qa/QAnything

项目概述

QAnything是一款基于本地文档的知识库问答系统，能够帮助用户快速构建知识库，并对上传的文档内容进行智能问答。本文将全面解析QAnything提供的API接口，帮助开发者快速集成和使用该系统。

全局参数说明

在调用QAnything的所有API时，都需要注意以下全局参数：

• user_id：用于区分不同用户的标识符
  • 必须以字母开头
  • 只能包含字母、数字或下划线
  • 当设置为"zzp"时，API操作会与前端页面互通
  • 如果需要区分不同用户，请传入不同的user_id值

核心API功能详解

1. 知识库管理

1.1 新建知识库

接口地址：/api/local_doc_qa/new_knowledge_base

请求方法：POST

参数说明：

• kb_name：知识库名称（必填）
• kb_id：可选参数，用于指定知识库ID（通常用于FAQ知识库）
• quick：布尔值，表示是否为快速开始模式（默认为False）

使用场景：

• 当需要创建一个新的知识库时调用
• 可以指定知识库ID用于特殊用途（如FAQ知识库）

响应示例：

{
  "code": 200,
  "msg": "success create knowledge base KBd728811ed16b46f9a2946e28dd5c9939",
  "data": {
    "kb_id": "KB4c50de98d6b548af9aa0bc5e10b2e3a7",
    "kb_name": "kb_test",
    "timestamp": "202401251057"
  }
}

1.2 查看知识库列表

接口地址：/api/local_doc_qa/list_knowledge_base

请求方法：POST

参数说明：

• user_id：用户ID（必填）

使用场景：

• 获取当前用户下的所有知识库列表
• 用于展示知识库或选择特定知识库进行操作

2. 文件管理

2.1 上传文件

接口地址：/api/local_doc_qa/upload_files

请求方法：POST（Content-Type: multipart/form-data）

参数说明：

• files：文件二进制数据（支持多文件上传）
• kb_id：目标知识库ID（必填）
• mode：上传模式（soft/strong，默认为soft）
• chunk_size：文件切片大小（默认为800 tokens）

支持文件类型：

• md, txt, pdf, jpg, png, jpeg, docx, xlsx, pptx, eml, csv

使用技巧：

• 对于大文件批量上传，建议使用异步方式
• 注意HTTP协议限制，单次请求数据不应超过100MB

2.2 上传网页内容

接口地址：/api/local_doc_qa/upload_weblink

请求方法：POST

参数说明：

• url：单个网页URL
• urls+titles：多个网页URL和对应标题的组合
• 其他参数与文件上传类似

注意事项：

• 仅支持无需登录且无反爬虫的网站
• 不支持递归解析多级页面

2.3 获取文件列表

接口地址：/api/local_doc_qa/list_files

请求方法：POST

参数说明：

• kb_id：知识库ID（必填）
• file_id：可选，指定文件ID获取单个文件状态
• page_offset+page_limit：分页参数

响应字段说明：

• status_count：汇总各状态文件数量
• details：文件详细信息，包括：
  • 文件ID、名称、大小
  • 状态（green/red/yellow/gray）
  • 切片数量、内容长度等

3. 问答功能

接口地址：/api/local_doc_qa/local_doc_chat

请求方法：POST

参数说明：

• kb_id：知识库ID（必填）
• question：用户提问内容（必填）
• stream：是否使用流式响应（默认为False）

使用场景：

• 基于知识库内容进行问答
• 支持流式和非流式两种响应方式

响应示例（非流式）：

{
  "code": 200,
  "msg": "success",
  "data": {
    "answer": "这是根据知识库内容生成的回答...",
    "docs": "相关文档片段..."
  }
}

4. 知识库维护

4.1 删除文件

接口地址：/api/local_doc_qa/delete_files

请求方法：POST

参数说明：

• kb_id：知识库ID（必填）
• file_ids：要删除的文件ID列表

4.2 删除知识库

接口地址：/api/local_doc_qa/delete_knowledge_base

请求方法：POST

参数说明：

• kb_ids：要删除的知识库ID列表

4.3 清理知识库

接口地址：/api/local_doc_qa/clean_files_by_status

请求方法：POST

参数说明：

• kb_id：知识库ID（必填）
• status：要清理的文件状态（如red/yellow）

5. Bot管理（高级功能）

QAnything还提供了Bot管理功能，可以创建、配置和管理问答机器人：

• 创建Bot：/api/local_doc_qa/create_bot
• 获取Bot信息：/api/local_doc_qa/get_bot_info
• 修改Bot信息：/api/local_doc_qa/update_bot_info
• 删除Bot：/api/local_doc_qa/delete_bot

最佳实践建议

1. 文件上传优化：

   • 对于大量文件，建议分批上传
   • 监控文件状态（gray表示正在处理）
   • 根据文件大小调整chunk_size参数

2. 知识库管理：

   • 定期清理失败状态的文件
   • 使用分页参数管理大型知识库

3. 问答体验优化：

   • 对于实时性要求高的场景使用流式响应
   • 结合文件列表API实现问答结果溯源

4. 错误处理：

   • 检查API响应中的code字段
   • 合理处理各种文件状态（red/yellow等）

总结

QAnything提供了一套完整的API接口，涵盖了知识库管理、文件上传、智能问答等核心功能。通过合理使用这些接口，开发者可以轻松构建基于文档的知识问答系统。在实际应用中，建议根据具体需求选择合适的接口组合，并注意API的性能优化和错误处理。

QAnything 项目地址: https://gitcode.com/gh_mirrors/qa/QAnything