zcbot/DOCUMENT_SEARCH_API.md

文档搜索API使用说明

概述

本文档介绍了文档搜索API接口，该接口提供文档检索、知识库列表查询和文档下载功能。

基础URL: https://ai.ctc-zc.com:8100/api

认证方式: Bearer Token（除健康检查接口外）

Authorization: Bearer <your-api-key>

API端点

1. 搜索文档

接口地址: POST /document_search/search

需要认证: 是

请求头:

Content-Type: application/json
Authorization: Bearer <api-key>

请求体参数:

参数名	类型	必填	默认值	描述
query	string	是	-	搜索查询词
classification_ids	array[int]	否	[]	分类ID列表
kb_names	array[string]	否	["mu_34_1740625285897"]	知识库名称列表，支持多个知识库
max_documents	integer	否	6	最大返回文档数 (1-20)

响应格式:

{
  "code": 200,
  "msg": "success",
  "data": {
    "documents": [
      {
        "id": 371633,
        "kb_name": "mu_34_1740625285897",
        "file_name": "example.pdf",
        "file_ext": ".pdf",
        "file_version": 1,
        "document_loader": "PyPDFLoader",
        "text_splitter": "MarkdownHeaderTextSplitter",
        "create_time": "2025-01-01T00:00:00",
        "file_mtime": "2025-01-01T00:00:00",
        "file_size": 1024000,
        "custom_docs": false,
        "docs_count": 50,
        "character_count": 100000,
        "md_filename": "example.md",
        "md_content": "文档的Markdown内容...",
        "classification_ids": [1, 2],
        "url": "https://ai.ctc-zc.com:8100/api/document_search/download_doc?knowledge_base_name=mu_34_1740625285897&file_name=example.pdf"
      }
    ],
    "total_count": 15,
    "query": "混凝土材料性能",
    "classification_ids": [1, 2, 3],
    "kb_names": ["mu_34_1740625285897", "mu_34_1740625318986"]
  }
}

响应字段说明:

字段名	类型	描述
code	integer	响应状态码
msg	string	响应消息
data	object	响应数据
data.documents	array	文档列表（直接返回 kb_file 对象）
data.total_count	integer	文档总数
data.query	string	原始查询词
data.classification_ids	array[int]	使用的分类IDs
data.kb_names	array[string]	使用的知识库名称列表

Document (kb_file) 字段说明:

字段名	类型	描述
id	integer	文档ID
kb_name	string	知识库名称
file_name	string	原始文件名
file_ext	string	文件扩展名
file_version	integer	文件版本
document_loader	string	文档加载器名称
text_splitter	string	文本分割器名称
create_time	datetime	创建时间
file_mtime	datetime	文件修改时间
file_size	integer	文件大小（字节）
custom_docs	boolean	是否自定义文档
docs_count	integer	文档块数量
character_count	integer	字符总数
md_filename	string	Markdown文件名
md_content	string	Markdown内容
classification_ids	array[int]	分类ID列表
url	string	下载URL（自动拼接）

---

2. 下载知识库文档

接口地址: GET /document_search/download_doc

需要认证: 是

请求头:

Authorization: Bearer <api-key>

查询参数:

参数名	类型	必填	默认值	描述
knowledge_base_name	string	是	-	知识库名称
file_name	string	是	-	文件名称（可以是原始文件名或Markdown文件名）
preview	boolean	否	false	是否在线预览（true: 浏览器内预览；false: 下载）

功能说明:

• 支持通过原始文件名（如 example.pdf）或 Markdown 文件名（如 example.md）下载
• 如果直接查找失败，系统会自动从数据库查询文件详情并尝试使用原始文件名
• 确保文件路径安全，防止目录遍历攻击

请求示例:

GET /document_search/download_doc?knowledge_base_name=mu_34_1740625285897&file_name=example.pdf&preview=false

响应:

• 成功: 返回文件流（FileResponse）
• 失败: 返回JSON错误信息

错误响应示例:

{
  "detail": "文件不存在: example.pdf"
}

---

3. 获取知识库列表

接口地址: GET /document_search/list_knowledge_bases

需要认证: 是

请求头:

Authorization: Bearer <api-key>

功能说明:

• 只返回在ID映射关系中存在的知识库（分类ID 1-7对应的知识库）
• 过滤掉其他无效的知识库
• 返回有效的kb_name列表供参考

响应格式:

{
  "code": 200,
  "msg": "success",
  "data": {
    "knowledge_bases": [
      {
        "id": 1,
        "kb_name": "mu_34_1740625285897",
        "ch_name": "材料分类1",
        "kb_info": "知识库描述",
        "customer_id": 34,
        "classification_type": 0,
        "create_time": "2025-01-01T00:00:00",
        "file_count": 100
      }
    ],
    "total_count": 7,
    "valid_kb_names": [
      "mu_34_1740625285897",
      "mu_34_1740625318986",
      "mu_34_1740625346474",
      "mu_34_1740625303475",
      "mu_34_1740625365079",
      "mu_34_1740625355308",
      "mu_34_1740625376621"
    ]
  }
}

响应字段说明:

字段名	类型	描述
code	integer	响应状态码
msg	string	响应消息
data	object	响应数据
data.knowledge_bases	array	知识库列表
data.total_count	integer	知识库总数
data.valid_kb_names	array[string]	有效的知识库名称列表

KnowledgeBase 字段说明:

字段名	类型	描述
id	integer	知识库ID
kb_name	string	知识库名称
ch_name	string	中文名称
kb_info	string	知识库描述
customer_id	integer	客户ID
classification_type	integer	分类类型
create_time	string	创建时间（ISO格式）
file_count	integer	文件数量

---

4. 健康检查

接口地址: GET /document_search/health

需要认证: 否（公开访问）

响应格式:

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": "healthy",
    "service": "document_search_api"
  }
}

## 错误处理

API可能返回以下错误：

### HTTP状态码

| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数格式错误 |
| 401 | 缺少认证信息或认证格式错误 |
| 403 | API密钥无效或非法访问 |
| 404 | 资源不存在（知识库或文件未找到） |
| 500 | 服务器内部错误 |

### 错误响应格式

```json
{
  "detail": "错误描述信息"
}

常见错误信息

错误信息	说明
Missing authorization header	缺少Authorization头
Invalid authorization header format. Expected 'Bearer <api_key>'	Authorization头格式错误
API key is required	API密钥为空
Invalid API key for document search service	API密钥无效
Don't attack me	非法的知识库名称
未找到知识库 {name}	知识库不存在
文件不存在: {filename}	文件不存在
文档搜索失败: {error}	搜索过程中发生错误
文件下载失败: {error}	下载过程中发生错误