RAGFlow 知识库 API 手册

目录

• 通用说明
• 知识库管理
• 文档管理
• 元数据管理
• 文档解析
• 切片管理
• 知识库检索
• 使用量统计
• 重新向量化
• 错误码说明

通用说明

| 项目 | 说明 |

|------|------|

| API 前缀 | SDK 接口统一前缀 /api/v1，代码注册在 api/apps/sdk/ |

| 认证方式 | Authorization: Bearer （token_required 装饰器）；部分接口使用 session 认证（login_required 装饰器），会在接口处标注 |

| 成功响应 | { "code": 0, "data": {...} }（成功时不含 message） |

| 错误响应 | { "code": <非0>, "message": "错误描述" } |

| 分页默认值 | page=1, page_size=30 |

| 排序默认值 | orderby=create_time, desc=true |

知识库管理

创建知识库

POST /api/v1/datasets

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 默认值 | 说明 |

|------|------|------|--------|------|

| name | string | ✅ | - | 知识库名称（若重复，服务端自动追加 (N) 后缀，不报错） |

| description | string | 否 | "" | 知识库描述 |

| avatar | string | 否 | - | Base64 编码的头像图片 |

| embedding_model | string | 否 | 租户默认模型 | 向量化模型名称，格式为 @（如 BAAI/bge-large-zh-v1.5@Xinference） |

| permission | string | 否 | "me" | 可见性：me（私有）/ team（团队） |

| chunk_method | string | 否 | "naive" | 切片方法，可选值见下方枚举 |

| parser_config | object | 否 | 服务端默认 | 解析器配置 |

| auto_metadata_config | object | 否 | - | 自动元数据配置（包含 enabled 和 fields） |

| parse_type | integer | 否 | - | 解析类型（0~64），与 pipeline_id 配合使用，不可与 chunk_method 同时指定 |

| pipeline_id | string | 否 | - | 流水线 ID（32 位十六进制字符串），与 parse_type 配合使用，不可与 chunk_method 同时指定 |

chunk_method 可选值: naive, book, email, laws, manual, one, paper, picture, presentation, qa, table, tag, parent_child

parser_config 通用配置项

| 字段 | 类型 | 默认值 | 说明 |

|------|------|--------|------|

| chunk_token_num | integer | 128（naive）/ 512（laws/paper/one） | 切片大小（token 数） |

| delimiter | string | "\n!?。；！？" | 切片分隔符 |

| layout_recognize | string | "DeepDOC" | 布局识别方式，可选："DeepDOC" / "TCADP Parser" / "Docling" / "MinerU" / "PaddleOCR" / false（关闭） |

| overlapped_percent | integer | 0 | 切片重叠百分比（0~100） |

| pages | array | [[1, 1000000]] | 解析页码范围，如 [[1, 10], [20, 30]] |

| auto_keywords | integer | - | 自动提取关键词数量 |

| auto_questions | integer | - | 自动生成问题数量 |

| auto_summary | boolean | - | 是否自动摘要 |

| enable_metadata | boolean | false | 是否启用元数据提取 |

| metadata | object | {} | 元数据字段配置 |

| filename_embd_weight | float | 0.1 | 文件名嵌入权重（0~1） |

| table_context_size | integer | 0 | 表格上下文大小（附加前后 N 个切片作为表格上下文） |

| image_context_size | integer | 0 | 图片上下文大小（附加前后 N 个切片作为图片上下文） |

| children_delimiter | string | - | 子切片分隔符（naive 模式下的二级切分） |

| analyze_hyperlink | boolean | false | 是否解析超链接并抓取链接内容（支持 PDF/DOCX） |

| hyperlink_urls | boolean | false | 是否解析 Markdown 中的超链接 |

| html4excel | boolean | false | 是否将 Excel 以 HTML 表格方式解析 |

| video_prompt | string | "" | 视频解析时的自定义提示词（chunk_method="picture" 时生效） |

| llm_id | string | - | 指定用于解析的 LLM 模型 ID |

parser_config TCADP 解析器专用（layout_recognize="TCADP Parser"）

| 字段 | 类型 | 默认值 | 说明 |

|------|------|--------|------|

| table_result_type | string | "1" | 表格结果类型 |

| markdown_image_response_type | string | "1" | Markdown 图片响应类型 |

parser_config 父子切片专用（chunk_method="parent_child"）

| 字段 | 类型 | 默认值 | 说明 |

|------|------|--------|------|

| parent_mode | string | "paragraph" | 父切片模式：paragraph / full_doc |

| parent_chunk_size | integer | 1024 | 父切片大小（token 数） |

| parent_delimiter | string | "\n\n" | 父切片分隔符 |

| child_chunk_size | integer | 256 | 子切片大小（token 数） |

| child_delimiter | string | "\n" | 子切片分隔符 |

| chunk_overlap | integer | 50 | 切片重叠 token 数 |

parser_config Tag 切片专用（chunk_method="tag"）

| 字段 | 类型 | 默认值 | 说明 |

|------|------|--------|------|

| tag_kb_ids | array\ | [] | 标签来源知识库 ID 列表 |

| topn_tags | integer | 3 | 每个切片提取的标签数量 |

parser_config RAPTOR 配置（知识库级别，嵌套在 raptor 字段下）

| 字段 | 类型 | 默认值 | 约束 | 说明 |

|------|------|--------|------|------|

| use_raptor | boolean | false | - | 是否启用 RAPTOR 层次化摘要 |

| prompt | string | - | 长度 ≥ 1 | 摘要生成提示词 |

| max_token | integer | - | 1 ~ 2048 | 摘要最大 token 数 |

| threshold | float | - | 0.0 ~ 1.0 | 聚类相似度阈值 |

| max_cluster | integer | - | 1 ~ 1024 | 最大聚类数 |

| random_seed | integer | - | ≥ 0 | 随机种子 |

parser_config GraphRAG 配置（知识库级别，嵌套在 graphrag 字段下）

| 字段 | 类型 | 默认值 | 约束 | 说明 |

|------|------|--------|------|------|

| use_graphrag | boolean | false | - | 是否启用知识图谱增强 |

| method | string | "light" | "light" / "general" | 知识图谱提取方法 |

| entity_types | array\ | [] | - | 实体类型列表（如 ["age", "sex"]） |

| community | boolean | false | - | 是否启用社区检测 |

| resolution | boolean | false | - | 是否启用实体消歧 |

响应字段

| 字段 | 类型 | 说明 |

|------|------|------|

| id | string | 知识库 ID |

| name | string | 知识库名称 |

| avatar | string | 头像（Base64 编码） |

| description | string | 知识库描述 |

| tenant_id | string | 租户 ID |

| embedding_model | string | 向量化模型名称 |

| permission | string | 可见性：me / team |

| chunk_method | string | 切片方法 |

| parser_config | object | 解析器配置 |

| chunk_count | integer | 切片总数 |

| document_count | integer | 文档总数 |

| token_num | integer | Token 总数 |

| language | string | 语言 |

| create_time | integer | 创建时间戳（毫秒） |

| update_time | integer | 更新时间戳（毫秒） |

curl 示例

curl -X POST http://localhost/api/v1/datasets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的知识库",
    "chunk_method": "naive",
    "embedding_model": "BAAI/bge-large-zh-v1.5@Xinference"
  }'

响应示例

{
  "code": 0,
  "data": {
    "id": "kb_123456",
    "name": "我的知识库",
    "avatar": "",
    "description": "",
    "tenant_id": "t_abc123",
    "embedding_model": "BAAI/bge-large-zh-v1.5@Xinference",
    "permission": "me",
    "chunk_method": "naive",
    "parser_config": {},
    "chunk_count": 0,
    "document_count": 0,
    "token_num": 0,
    "language": "Chinese",
    "create_time": 1739876543210,
    "update_time": 1739876543210
  }
}

知识库列表

GET /api/v1/datasets

请求参数（Query）

| 参数 | 类型 | 必填 | 默认值 | 说明 |

|------|------|------|--------|------|

| page | integer | 否 | 1 | 页码 |

| page_size | integer | 否 | 30 | 每页数量 |

| orderby | string | 否 | create_time | 排序字段 |

| desc | boolean | 否 | true | 是否降序 |

| id | string | 否 | - | 按知识库 ID 精确过滤 |

| name | string | 否 | - | 按名称精确过滤 |

响应字段

返回对象包含 data（数据集数组）和 total_datasets（总数）。每个数据集元素包含与「创建知识库」响应相同的字段结构。

curl 示例

# 分页查询
curl "http://localhost/api/v1/datasets?page=1&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 按 ID 查询详情
curl "http://localhost/api/v1/datasets?id=kb_123456" \
  -H "Authorization: Bearer YOUR_API_KEY"

编辑知识库

PUT /api/v1/datasets/{dataset_id}

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| name | string | 否 | 新名称（不可与已有重复） |

| description | string | 否 | 新描述 |

| avatar | string | 否 | 新头像（Base64 编码） |

| embedding_model | string | 否 | 新模型（仅 chunk_count=0 时可修改） |

| chunk_method | string | 否 | 新切片方法。可选值与创建知识库相同：naive, book, email, laws, manual, one, paper, picture, presentation, qa, table, tag, parent_child |

| permission | string | 否 | me / team |

| parser_config | object | 否 | 解析器配置（增量合并） |

| pagerank | integer | 否 | PageRank 值（仅 Elasticsearch 引擎） |

| auto_metadata_config | object | 否 | 自动元数据配置 |

curl 示例

curl -X PUT http://localhost/api/v1/datasets/kb_123456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "新名称", "description": "更新描述"}'

删除知识库

DELETE /api/v1/datasets

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| ids | array\ \| null | ✅ | 知识库 ID 列表。null 删除全部，[] 不删除 |

> ⚠️ 删除知识库会级联删除其下所有文档、切片、文件及向量索引。

curl 示例

curl -X DELETE http://localhost/api/v1/datasets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["kb_123456"]}'

自动元数据配置

获取自动元数据配置

GET /api/v1/datasets/{dataset_id}/auto_metadata

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

响应字段

| 字段 | 类型 | 说明 |

|------|------|------|

| enabled | boolean | 是否启用自动元数据提取 |

| fields | array | 元数据字段配置列表 |

curl 示例

curl "http://localhost/api/v1/datasets/kb_123456/auto_metadata" \
  -H "Authorization: Bearer YOUR_API_KEY"

更新自动元数据配置

PUT /api/v1/datasets/{dataset_id}/auto_metadata

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| enabled | boolean | 否 | 是否启用自动元数据提取 |

| fields | array | 否 | 元数据字段配置列表 |

fields 元素字段

| 字段 | 类型 | 说明 |

|------|------|------|

| name | string | 字段名称 |

| type | string | 字段类型 |

| description | string | 字段描述 |

| examples | array | 示例值 |

| restrict_values | boolean | 是否限制值为预定义值 |

curl 示例

curl -X PUT http://localhost/api/v1/datasets/kb_123456/auto_metadata \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "fields": [
      {"name": "author", "type": "string", "description": "文档作者"}
    ]
  }'

文档管理

上传文件文档

POST /api/v1/datasets/{dataset_id}/documents

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

方式一：文件上传（FormData）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| file | file | ✅ | 文档文件（支持多文件），格式：PDF/DOCX/TXT/MD/HTML/XLSX/PPTX/图片 |

| parent_path | string | 否 | 父路径，/ 分隔（用于文件夹嵌套） |

| img2text | string | 否 | 是否对图片进行 OCR 识别，默认 "true" |

> 限制：单次最多上传 256 个文件，文件名（UTF-8）不超过 255 字节。

方式二：URL 上传（Body JSON）

请求 Content-Type 为 application/json 时，走 URL 上传路径。

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| url | string | ✅ | 网页 URL，服务端通过 URL Service 抓取内容并转为 Markdown |

| filename | string | 否 | 自定义文档名称（不传则使用 URL Service 返回的默认名称） |

| parent_path | string | 否 | 父路径，/ 分隔（用于文件夹嵌套） |

| img2text | boolean | 否 | 是否对图片进行 OCR 识别，默认 true |

响应字段（数组，每个元素）

| 字段 | 类型 | 说明 |

|------|------|------|

| id | string | 文档 ID |

| name | string | 文档名称 |

| chunk_count | integer | 切片数量（新上传为 0） |

| token_count | integer | Token 数量（新上传为 0） |

| dataset_id | string | 所属知识库 ID |

| chunk_method | string | 切片方法 |

| run | string | 处理状态：UNSTART |

curl 示例

# 文件上传
curl -X POST http://localhost/api/v1/datasets/kb_123456/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf"

# URL 上传
curl -X POST http://localhost/api/v1/datasets/kb_123456/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "filename": "示例文章.md"
  }'

上传 URL 文档

> ⚠️ 此接口使用 session 认证（login_required），无法通过 API Key 调用。

POST /v1/document/web_crawl

请求参数（FormData）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| kb_id | string | ✅ | 知识库 ID |

| name | string | ✅ | 文档名称 |

| url | string | ✅ | 网页 URL |

文档列表

GET /api/v1/datasets/{dataset_id}/documents

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

请求参数（Query）

| 参数 | 类型 | 必填 | 默认值 | 说明 |

|------|------|------|--------|------|

| page | integer | 否 | 1 | 页码 |

| page_size | integer | 否 | 30 | 每页数量 |

| orderby | string | 否 | create_time | 排序字段，支持 total_hits（🆕 统计扩展） |

| desc | boolean | 否 | true | 是否降序 |

| id | string | 否 | - | 按文档 ID 精确过滤 |

| name | string | 否 | - | 按名称精确过滤 |

| keywords | string | 否 | "" | 关键词搜索 |

| run | array\ | 否 | - | 按状态过滤，支持文本格式 UNSTART/RUNNING/CANCEL/DONE/FAIL 或数字格式 0/1/2/3/4 |

| suffix | array\ | 否 | - | 按文件后缀过滤（如 ["pdf","txt"]） |

| create_time_from | integer | 否 | 0 | 创建时间起始（Unix 时间戳），0 表示不限 |

| create_time_to | integer | 否 | 0 | 创建时间截止（Unix 时间戳），0 表示不限 |

| metadata_condition | string(JSON) | 否 | - | 元数据过滤条件（JSON 字符串） |

响应字段

| 字段 | 类型 | 说明 |

|------|------|------|

| total | integer | 文档总数 |

| docs | array | 文档列表 |

docs 数组元素字段

| 字段 | 类型 | 说明 |

|------|------|------|

| id | string | 文档 ID |

| name | string | 文档名称 |

| thumbnail | string | 缩略图（Base64 编码） |

| chunk_count | integer | 切片数量 |

| token_count | integer | Token 数量 |

| dataset_id | string | 所属知识库 ID |

| chunk_method | string | 切片方法 |

| parser_config | object | 解析器配置 |

| source_type | string | 来源类型 |

| type | string | 文件类型 |

| size | integer | 文件大小（字节） |

| suffix | string | 文件后缀 |

| location | string | 文件路径 |

| run | string | 处理状态：UNSTART/RUNNING/CANCEL/DONE/FAIL |

| progress | float | 解析进度（0.0 ~ 1.0） |

| progress_msg | string | 进度消息 |

| process_begin_at | string | 处理开始时间 |

| process_duration | float | 处理耗时（秒） |

| created_by | string | 创建者 |

| create_time | integer | 创建时间戳（毫秒） |

| update_time | integer | 更新时间戳（毫秒） |

| stats | object | 🆕 使用量统计（统计功能启用后） |

stats 对象字段（🆕 统计功能扩展）

| 字段 | 类型 | 说明 |

|------|------|------|

| total_hits | integer | 该文档所有切片被召回次数总和 |

| zero_hit_chunks | integer | 该文档中从未被召回的切片数量 |

| last_hit_time | integer \| null | 最后一次命中时间戳（毫秒），从未命中为 null |

curl 示例

# 分页查询
curl "http://localhost/api/v1/datasets/kb_123456/documents?page=1&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 按状态过滤
curl "http://localhost/api/v1/datasets/kb_123456/documents?run=DONE&run=RUNNING" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 🆕 按调用次数排序
curl "http://localhost/api/v1/datasets/kb_123456/documents?orderby=total_hits&desc=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

{
  "code": 0,
  "data": {
    "total": 100,
    "docs": [
      {
        "id": "doc_987654",
        "name": "技术文档.pdf",
        "thumbnail": "",
        "chunk_count": 150,
        "token_count": 8500,
        "dataset_id": "kb_123456",
        "chunk_method": "naive",
        "parser_config": {},
        "source_type": "local",
        "type": "pdf",
        "size": 1024000,
        "suffix": "pdf",
        "location": "",
        "run": "DONE",
        "progress": 1.0,
        "progress_msg": "",
        "process_begin_at": "2024-01-01 12:00:00",
        "process_duration": 30.5,
        "created_by": "user_123",
        "create_time": 1739876543210,
        "update_time": 1739876543210,
        "stats": {
          "total_hits": 150,
          "zero_hit_chunks": 1,
          "last_hit_time": 1698765432000
        }
      }
    ]
  }
}

编辑文档

PUT /api/v1/datasets/{dataset_id}/documents/{document_id}

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

| document_id | string | ✅ | 文档 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| name | string | 否 | 新文件名（后缀不可变更，不可与同知识库内已有重复） |

| chunk_method | string | 否 | 新切片方法（修改后需重新解析）。可选值：naive, manual, qa, table, paper, book, laws, presentation, picture, one, knowledge_graph, email, tag, parent_child |

| parser_config | object | 否 | 解析器配置（字段同创建知识库的 parser_config，文档级配置会覆盖知识库默认值） |

| enabled | boolean | 否 | 文档启用状态 |

| meta_fields | object | 否 | 元数据字段（键值对） |

> 💡 同一知识库下的不同文档可以使用不同的 chunk_method 和 parser_config。知识库级别的配置仅作为新文档的默认值，每个文档可独立覆盖。修改 chunk_method 或 parser_config 后需重新触发解析才会生效。

curl 示例

# 修改文档名称
curl -X PUT http://localhost/api/v1/datasets/kb_123456/documents/doc_987654 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "新文档名.pdf"}'

# 为单个文档设置不同的切片策略（覆盖知识库默认值）
curl -X PUT http://localhost/api/v1/datasets/kb_123456/documents/doc_987654 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chunk_method": "paper",
    "parser_config": {
      "chunk_token_num": 1024,
      "layout_recognize": "DeepDOC"
    }
  }'

下载文档

GET /api/v1/datasets/{dataset_id}/documents/{document_id}

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

| document_id | string | ✅ | 文档 ID |

返回文件二进制流（Content-Type: application/octet-stream）。

curl 示例

curl -o output.pdf \
  "http://localhost/api/v1/datasets/kb_123456/documents/doc_987654" \
  -H "Authorization: Bearer YOUR_API_KEY"

下载文档（简化接口）

GET /api/v1/documents/{document_id}

> ⚠️ 此接口使用 beta token 认证，通过 Authorization: Bearer 调用，与标准 API Key 不同。

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| document_id | string | ✅ | 文档 ID |

返回文件二进制流（Content-Type: application/octet-stream）。

curl 示例

curl -o output.pdf \
  "http://localhost/api/v1/documents/doc_987654" \
  -H "Authorization: Bearer YOUR_BETA_TOKEN"

删除文档

DELETE /api/v1/datasets/{dataset_id}/documents

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| ids | array\ | 否 | 文档 ID 列表，不传则删除该知识库下全部文档 |

curl 示例

curl -X DELETE http://localhost/api/v1/datasets/kb_123456/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["doc_987654"]}'

元数据管理

获取元数据摘要

GET /api/v1/datasets/{dataset_id}/metadata/summary

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| doc_ids | array\ | 否 | 文档 ID 列表，不传则返回整个知识库的元数据摘要 |

响应字段

| 字段 | 类型 | 说明 |

|------|------|------|

| summary | object | 元数据摘要信息 |

curl 示例

curl "http://localhost/api/v1/datasets/kb_123456/metadata/summary" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

批量更新元数据

POST /api/v1/datasets/{dataset_id}/metadata/update

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| selector | object | 否 | 选择器，用于筛选目标文档 |

| updates | array | 否 | 更新操作列表 |

| deletes | array | 否 | 删除操作列表 |

selector 对象字段

| 字段 | 类型 | 说明 |

|------|------|------|

| document_ids | array\ | 文档 ID 列表 |

| metadata_condition | object | 元数据过滤条件（与检索接口的 metadata_condition 格式相同） |

updates 数组元素字段

| 字段 | 类型 | 必填 | 说明 |

|------|------|------|------|

| key | string | ✅ | 要更新的字段名 |

| value | any | ✅ | 新值 |

| match | any | 否 | 仅当当前值匹配时才更新（条件更新） |

deletes 数组元素字段

| 字段 | 类型 | 必填 | 说明 |

|------|------|------|------|

| key | string | ✅ | 要删除的字段名 |

| value | any | 否 | 指定要删除的值（用于列表字段中删除特定值） |

响应字段

| 字段 | 类型 | 说明 |

|------|------|------|

| updated | integer | 更新的元数据条数 |

| matched_docs | integer | 匹配的文档数 |

curl 示例

curl -X POST http://localhost/api/v1/datasets/kb_123456/metadata/update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selector": {
      "document_ids": ["doc_987654"]
    },
    "updates": [
      {"key": "author", "value": "张三"}
    ],
    "deletes": [
      {"key": "deprecated_field"}
    ]
  }'

响应示例

{
  "code": 0,
  "data": {
    "updated": 1,
    "matched_docs": 1
  }
}

文档解析

解析文档

POST /api/v1/datasets/{dataset_id}/chunks

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| document_ids | array\ | ✅ | 要解析的文档 ID 列表 |

> 解析为异步操作，通过文档列表接口的 run（状态）和 progress（进度）字段查询。

curl 示例

curl -X POST http://localhost/api/v1/datasets/kb_123456/chunks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["doc_987654"]}'

停止解析

DELETE /api/v1/datasets/{dataset_id}/chunks

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| document_ids | array\ | ✅ | 要停止解析的文档 ID 列表 |

切片管理

切片列表

GET /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

| document_id | string | ✅ | 文档 ID |

请求参数（Query）

| 参数 | 类型 | 必填 | 默认值 | 说明 |

|------|------|------|--------|------|

| page | integer | 否 | 1 | 页码 |

| page_size | integer | 否 | 30 | 每页数量 |

| id | string | 否 | "" | 指定切片 ID（精确查询单个切片） |

| keywords | string | 否 | "" | 关键词搜索（高亮匹配） |

| sort_by | string | 否 | - | 🆕 排序方式，支持 hits_desc（按召回次数降序） |

响应字段

| 字段 | 类型 | 说明 |

|------|------|------|

| total | integer | 切片总数 |

| chunks | array | 切片列表 |

| doc | object | 所属文档信息 |

chunks 数组元素字段

| 字段 | 类型 | 说明 |

|------|------|------|

| id | string | 切片 ID |

| content | string | 切片文本内容（关键词搜索时含高亮标记） |

| document_id | string | 所属文档 ID |

| dataset_id | string | 所属知识库 ID |

| docnm_kwd | string | 文档名称关键词 |

| important_keywords | array\ | 重要关键词列表 |

| questions | array\ | 关联问题列表 |

| image_id | string | 关联图片 ID（无图片为 "" ） |

| available | boolean | 是否启用 |

| positions | array\\> | 位置信息（每组 5 个整数） |

| chunk_type | string | 切片类型（父子切片模式下：parent/child/"" ） |

| parent_id | string | 父切片 ID（非父子切片为 "" ） |

| child_ids | array\ | 子切片 ID 列表 |

| retrieval_hits | integer | 🆕 累计被检索召回次数 |

| citation_hits | integer | 🆕 累计被大模型引用次数 |

| is_noise | boolean | 🆕 是否为噪音切片（retrieval_hits > 50 且引用率 < 10%） |

| last_hit_time | integer \| null | 🆕 最后一次命中时间戳（毫秒） |

doc 对象字段

| 字段 | 类型 | 说明 |

|------|------|------|

| id | string | 文档 ID |

| name | string | 文档名称 |

| chunk_count | integer | 切片总数 |

| token_count | integer | Token 总数 |

| dataset_id | string | 所属知识库 ID |

| chunk_method | string | 切片方法 |

| run | string | 处理状态 |

curl 示例

# 分页查询
curl "http://localhost/api/v1/datasets/kb_123456/documents/doc_987654/chunks?page=1&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 关键词搜索
curl "http://localhost/api/v1/datasets/kb_123456/documents/doc_987654/chunks?keywords=考勤制度" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 🆕 按召回次数排序
curl "http://localhost/api/v1/datasets/kb_123456/documents/doc_987654/chunks?sort_by=hits_desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

{
  "code": 0,
  "data": {
    "total": 150,
    "chunks": [
      {
        "id": "chunk_888",
        "content": "这是切片的文本内容...",
        "document_id": "doc_987654",
        "dataset_id": "kb_123456",
        "docnm_kwd": "技术文档.pdf",
        "important_keywords": ["API", "接口"],
        "questions": [],
        "image_id": "",
        "available": true,
        "positions": [],
        "chunk_type": "",
        "parent_id": "",
        "child_ids": [],
        "retrieval_hits": 45,
        "citation_hits": 12,
        "is_noise": false,
        "last_hit_time": 1698765432000
      }
    ],
    "doc": {
      "id": "doc_987654",
      "name": "技术文档.pdf",
      "chunk_count": 150,
      "token_count": 8500,
      "dataset_id": "kb_123456",
      "chunk_method": "naive",
      "run": "DONE"
    }
  }
}

添加切片

POST /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

| document_id | string | ✅ | 文档 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| content | string | ✅ | 切片文本内容 |

| important_keywords | array\ | 否 | 重要关键词 |

| questions | array\ | 否 | 关联问题 |

删除切片

DELETE /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

| document_id | string | ✅ | 文档 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| chunk_ids | array\ | 否 | 切片 ID 列表。不传则删除该文档下全部切片 |

curl 示例

curl -X DELETE http://localhost/api/v1/datasets/kb_123456/documents/doc_987654/chunks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chunk_ids": ["chunk_888"]}'

编辑切片

PUT /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

| document_id | string | ✅ | 文档 ID |

| chunk_id | string | ✅ | 切片 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| content | string | 否 | 更新后的切片文本内容 |

| important_keywords | array\ | 否 | 更新后的重要关键词 |

| questions | array\ | 否 | 更新后的关联问题 |

| available | boolean | 否 | 切片启用状态 |

| positions | array | 否 | 位置信息 |

curl 示例

curl -X PUT http://localhost/api/v1/datasets/kb_123456/documents/doc_987654/chunks/chunk_888 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "更新后的切片内容",
    "important_keywords": ["关键词1", "关键词2"],
    "available": true
  }'

知识库检索

检索

POST /api/v1/retrieval

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 默认值 | 说明 |

|------|------|------|--------|------|

| dataset_ids | array\ | ✅ | - | 知识库 ID 列表（所有知识库必须使用相同 embedding 模型） |

| question | string | ✅ | - | 查询内容（空字符串返回空结果） |

| document_ids | array\ | 否 | [] | 限定文档范围 |

| page | integer | 否 | 1 | 页码 |

| page_size | integer | 否 | 30 | 每页数量 |

| similarity_threshold | float | 否 | 0.2 | 相似度阈值 |

| vector_similarity_weight | float | 否 | 0.3 | 向量权重（0=纯全文检索，1=纯向量检索） |

| top_k | integer | 否 | 1024 | 初筛数量 |

| highlight | boolean | 否 | false | 是否高亮匹配内容 |

| rerank_id | string | 否 | - | 重排模型 ID（启用后增加约 100-500ms 延迟） |

| use_kg | boolean | 否 | false | 是否启用知识图谱增强 |

| toc_enhance | boolean | 否 | false | 是否启用目录增强 |

| cross_languages | array\ | 否 | [] | 跨语言检索语言列表 |

| keyword | boolean | 否 | false | 是否启用关键词提取增强 |

| metadata_condition | object | 否 | - | 元数据过滤条件 |

响应字段

| 字段 | 类型 | 说明 |

|------|------|------|

| total | integer | 匹配切片总数 |

| chunks | array | 切片结果列表 |

| doc_aggs | array | 文档聚合统计 |

chunks 数组元素字段

| 字段 | 类型 | 说明 |

|------|------|------|

| id | string | 切片 ID |

| content | string | 切片内容（高亮时含标记） |

| document_id | string | 所属文档 ID |

| document_keyword | string | 文档名称 |

| dataset_id | string | 所属知识库 ID |

| important_keywords | array\ | 重要关键词 |

| questions | array\ | 关联问题 |

| similarity | float | 综合相似度分数 |

| vector_similarity | float | 向量相似度分数 |

| term_similarity | float | 全文相似度分数 |

doc_aggs 数组元素字段

| 字段 | 类型 | 说明 |

|------|------|------|

| doc_name | string | 文档名称 |

| doc_id | string | 文档 ID |

| count | integer | 该文档命中切片数 |

curl 示例

curl -X POST http://localhost/api/v1/retrieval \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_ids": ["kb_123456"],
    "question": "合同付款条件是什么？",
    "similarity_threshold": 0.2,
    "vector_similarity_weight": 0.3,
    "top_k": 1024
  }'

响应示例

{
  "code": 0,
  "data": {
    "total": 50,
    "chunks": [
      {
        "id": "chunk_888",
        "content": "合同付款条件为...",
        "document_id": "doc_987654",
        "document_keyword": "采购合同.pdf",
        "dataset_id": "kb_123456",
        "important_keywords": ["付款", "合同"],
        "similarity": 0.89,
        "vector_similarity": 0.85,
        "term_similarity": 0.92
      }
    ],
    "doc_aggs": [
      {"doc_name": "采购合同.pdf", "doc_id": "doc_987654", "count": 15}
    ]
  }
}

使用量统计

提供知识库、文档、切片的检索调用热度分析能力，用于 RAG 召回效果调优。数据通过 Redis 异步采集，存在约 5 分钟延迟。

数据大盘总览

GET /api/v1/datasets/statistics/overview

请求参数（Query）

| 参数 | 类型 | 必填 | 默认值 | 说明 |

|------|------|------|--------|------|

| dataset_id | string | 否 | - | 知识库 ID。不传返回当前租户下所有知识库的汇总数据 |

> 数据来源：从 Tenant_Statistics 汇总维表读取预计算数据，不执行实时全表扫描。

响应字段

| 字段路径 | 类型 | 说明 |

|----------|------|------|

| capacity.total_kbs | integer | 知识库总数 |

| capacity.total_docs | integer | 文档总数 |

| capacity.total_chunks | integer | 切片总数 |

| capacity.total_storage_bytes | integer | 物理存储占用（字节） |

| usage.total_retrieval_hits | integer | 累计检索召回次数 |

| anomaly.noise_chunks_count | integer | 噪音切片数量（retrieval_hits > 50 且引用率 < 10%） |

| anomaly.zero_hit_docs_count | integer | 从未被召回的文档数（沉默资产） |

| anomaly.zero_hit_chunks_count | integer | 从未被召回的切片数 |

| anomaly.coverage_warning | boolean | 零召回率超过 50% 时为 true |

curl 示例

# 租户级汇总
curl "http://localhost/api/v1/datasets/statistics/overview" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 指定知识库
curl "http://localhost/api/v1/datasets/statistics/overview?dataset_id=kb_123456" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

{
  "code": 0,
  "data": {
    "capacity": {
      "total_kbs": 5,
      "total_docs": 128,
      "total_chunks": 15420,
      "total_storage_bytes": 104857600
    },
    "usage": {
      "total_retrieval_hits": 45210
    },
    "anomaly": {
      "noise_chunks_count": 23,
      "zero_hit_docs_count": 34,
      "zero_hit_chunks_count": 8900,
      "coverage_warning": false
    }
  }
}

调用趋势分析

GET /api/v1/datasets/statistics/trend

请求参数（Query）

| 参数 | 类型 | 必填 | 默认值 | 说明 |

|------|------|------|--------|------|

| start_date | string | ✅ | - | 开始日期，格式 YYYY-MM-DD（如 2024-01-01） |

| end_date | string | ✅ | - | 结束日期，格式 YYYY-MM-DD（如 2024-01-07） |

| interval | string | 否 | day | 聚合粒度：day（按天）/ week（按周） |

| dataset_id | string | 否 | - | 知识库 ID，不传返回租户级汇总 |

> dates 数组保证连续完整（Zero-filling 补零），无数据日期填充 0，不跳过。

响应字段

| 字段路径 | 类型 | 说明 |

|----------|------|------|

| dates | array\ | 连续日期数组（格式 YYYY-MM-DD），与 series 一一对应 |

| series.retrieval_hits | array\ | 每天/周的检索召回总次数 |

| series.queries_count | array\ | 每天/周的用户提问次数（对比参考） |

curl 示例

curl "http://localhost/api/v1/datasets/statistics/trend?start_date=2024-01-01&end_date=2024-01-07&interval=day" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

{
  "code": 0,
  "data": {
    "dates": ["2024-01-01", "2024-01-02", "2024-01-03", "2024-01-04", "2024-01-05", "2024-01-06", "2024-01-07"],
    "series": {
      "retrieval_hits": [120, 150, 0, 80, 200, 310, 95],
      "queries_count": [45, 50, 0, 30, 80, 100, 40]
    }
  }
}

热点与异常排行

GET /api/v1/datasets/statistics/rankings

请求参数（Query）

| 参数 | 类型 | 必填 | 默认值 | 说明 |

|------|------|------|--------|------|

| target | string | ✅ | - | 排行目标：document（文档级）/ chunk（切片级） |

| order_by | string | ✅ | - | 排序方式：hits_desc（热门）/ hits_asc（冷门，用于发现沉默资产） |

| limit | integer | 否 | 10 | 返回条数（1 ~ 100） |

| dataset_id | string | 否 | - | 知识库 ID，不传返回租户级排行 |

响应字段（target=chunk）

| 字段 | 类型 | 说明 |

|------|------|------|

| list | array | 排行列表 |

list 元素字段（chunk 排行）

| 字段 | 类型 | 说明 |

|------|------|------|

| chunk_id | string | 切片 ID |

| doc_id | string | 所属文档 ID |

| doc_name | string | 所属文档名称 |

| content_snippet | string | 切片内容预览（截断） |

| retrieval_hits | integer | 历史被召回次数 |

| citation_hits | integer | 被大模型实际引用次数 |

| citation_rate | float | 引用率（citation_hits / retrieval_hits） |

| is_noise | boolean | 是否为噪音切片（retrieval_hits > 50 且 citation_rate < 10%） |

| last_hit_time | integer \| null | 最后一次被调用的时间戳（毫秒） |

响应字段（target=document）

list 元素字段（document 排行）

| 字段 | 类型 | 说明 |

|------|------|------|

| doc_id | string | 文档 ID |

| doc_name | string | 文档名称 |

| total_retrieval_hits | integer | 文档下所有切片召回次数总和 |

| chunk_count | integer | 切片总数 |

| zero_hit_chunks_count | integer | 从未被召回的切片数 |

| last_hit_time | integer \| null | 最后一次被调用的时间戳（毫秒） |

curl 示例

# 热门切片 Top 10
curl "http://localhost/api/v1/datasets/statistics/rankings?target=chunk&order_by=hits_desc&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 沉默文档（冷门排序）
curl "http://localhost/api/v1/datasets/statistics/rankings?target=document&order_by=hits_asc&limit=20&dataset_id=kb_123456" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例（target=chunk, order_by=hits_desc）

{
  "code": 0,
  "data": {
    "list": [
      {
        "chunk_id": "chk_8a9b0c",
        "doc_id": "doc_12345",
        "doc_name": "员工手册.pdf",
        "content_snippet": "第一章：考勤制度。本公司规定每天早上...",
        "retrieval_hits": 856,
        "citation_hits": 12,
        "is_noise": true,
        "last_hit_time": 1698765432000
      }
    ]
  }
}

响应示例（target=document, order_by=hits_asc）

{
  "code": 0,
  "data": {
    "list": [
      {
        "doc_id": "doc_67890",
        "doc_name": "过期政策.pdf",
        "total_retrieval_hits": 0,
        "chunk_count": 45,
        "zero_hit_chunks_count": 45,
        "last_hit_time": null
      }
    ]
  }
}

> 💡 如果某切片 retrieval_hits 极高但 citation_hits 极低（is_noise=true），说明该切片是"高频干扰噪音切片"，建议降权或删除以提升 RAG 回答质量。

重新向量化

重新向量化文档

POST /api/v1/datasets/{dataset_id}/documents/re-embedding

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 默认值 | 说明 |

|------|------|------|--------|------|

| document_ids | array\ | ✅ | - | 文档 ID 列表（最多 1000 个） |

| embedding_model | string | 否 | 知识库当前模型 | 指定 Embedding 模型名称 |

| batch_size | integer | 否 | 10 | 批处理大小（1 ~ 100） |

| force | boolean | 否 | false | 是否强制重新向量化（忽略已完成状态） |

响应字段

| 字段 | 类型 | 说明 |

|------|------|------|

| task_id | string | 任务 ID（用于查询进度和取消） |

| dataset_id | string | 知识库 ID |

| document_count | integer | 待处理文档数 |

| estimated_time | integer | 预估耗时（秒） |

| status | string | 任务状态：queued |

curl 示例

curl -X POST http://localhost/api/v1/datasets/kb_123456/documents/re-embedding \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": ["doc_987654", "doc_111222"],
    "batch_size": 10,
    "force": false
  }'

响应示例

{
  "code": 0,
  "data": {
    "task_id": "re_emb_20240309120000",
    "dataset_id": "kb_123456",
    "document_count": 2,
    "estimated_time": 120,
    "status": "queued"
  }
}

批量重新向量化（知识库级）

POST /api/v1/datasets/{dataset_id}/re-embedding

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| dataset_id | string | ✅ | 知识库 ID |

请求参数（Body JSON）

| 参数 | 类型 | 必填 | 默认值 | 说明 |

|------|------|------|--------|------|

| scope | string | 否 | all | 范围：all（全部）/ modified（已修改）/ filtered（按条件过滤）/ documents（指定文档） |

| filter_config | object | 否 | {} | 过滤条件（scope=filtered 时使用） |

| embedding_model | string | 否 | 知识库当前模型 | 指定 Embedding 模型名称 |

| batch_size | integer | 否 | 10 | 批处理大小（1 ~ 100） |

| force | boolean | 否 | false | 是否强制执行 |

响应字段：与「重新向量化文档」相同。

curl 示例

curl -X POST http://localhost/api/v1/datasets/kb_123456/re-embedding \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": "all", "batch_size": 20}'

查询任务进度

GET /api/v1/tasks/{task_id}/progress

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| task_id | string | ✅ | 任务 ID |

响应字段

| 字段 | 类型 | 说明 |

|------|------|------|

| task_id | string | 任务 ID |

| status | string | 任务状态：queued / running / completed / failed / cancelled |

| progress | float | 总进度（0.0 ~ 1.0） |

| total_documents | integer | 待处理文档总数 |

| processed_documents | integer | 已处理文档数 |

| total_chunks | integer | 待处理切片总数 |

| processed_chunks | integer | 已处理切片数 |

| current_document | object \| null | 当前处理中的文档信息 |

| current_document.document_id | string | 文档 ID |

| current_document.document_name | string | 文档名称 |

| current_document.progress | float | 当前文档进度 |

| elapsed_time | integer | 已耗时（秒） |

| estimated_remaining_time | integer | 预估剩余时间（秒） |

| errors | array | 错误列表 |

| error_count | integer | 错误数量 |

curl 示例

curl "http://localhost/api/v1/tasks/re_emb_20240309120000/progress" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

{
  "code": 0,
  "data": {
    "task_id": "re_emb_20240309120000",
    "status": "running",
    "progress": 0.45,
    "total_documents": 100,
    "processed_documents": 45,
    "total_chunks": 5000,
    "processed_chunks": 2250,
    "current_document": {
      "document_id": "doc_123",
      "document_name": "test.pdf",
      "progress": 0.8
    },
    "elapsed_time": 300,
    "estimated_remaining_time": 300,
    "errors": [],
    "error_count": 0
  }
}

取消任务

POST /api/v1/tasks/{task_id}/cancel

路径参数

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| task_id | string | ✅ | 任务 ID |

响应字段

| 字段 | 类型 | 说明 |

|------|------|------|

| cancelled | boolean | 是否取消成功 |

| task_id | string | 任务 ID |

curl 示例

curl -X POST "http://localhost/api/v1/tasks/re_emb_20240309120000/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

{
  "code": 0,
  "data": {
    "cancelled": true,
    "task_id": "re_emb_20240309120000"
  }
}

错误码说明

| 错误码 | 常量名 | 含义 | 常见场景 |

|--------|--------|------|----------|

| 0 | SUCCESS | 成功 | - |

| 10 | NOT_EFFECTIVE | 未生效 | 操作未产生实际效果 |

| 100 | EXCEPTION_ERROR | 异常错误 | 通用异常 |

| 101 | ARGUMENT_ERROR | 参数错误 | 缺少必填参数、参数类型不匹配、值超出范围 |

| 102 | DATA_ERROR | 数据错误 | 数据不存在、数据冲突 |

| 103 | OPERATING_ERROR | 操作错误 | 操作执行失败 |

| 105 | CONNECTION_ERROR | 连接错误 | 外部服务连接失败 |

| 106 | RUNNING | 运行中 | 任务正在执行 |

| 108 | PERMISSION_ERROR | 权限不足 | 无权访问指定知识库/文档 |

| 109 | AUTHENTICATION_ERROR | 认证错误 | API Key 无效、Token 过期 |

| 400 | BAD_REQUEST | 请求错误 | 请求格式不合法 |

| 401 | UNAUTHORIZED | 未授权 | 未提供认证信息 |

| 403 | FORBIDDEN | 禁止访问 | 无权执行该操作 |

| 404 | NOT_FOUND | 资源不存在 | 知识库/文档/切片 ID 不存在 |

| 409 | CONFLICT | 冲突 | 资源冲突 |

| 500 | SERVER_ERROR | 服务器错误 | 内部异常 |

注意事项

1. 单个文件建议不超过 100MB，文件名（UTF-8）不超过 255 字节
2. 同一知识库内所有文档必须使用相同的 embedding 模型
3. 混合检索（vector_similarity_weight=0.3）通常效果最佳
4. 启用 rerank 会增加约 100-500ms 延迟
5. 使用量统计数据通过 Redis 异步采集，存在约 5 分钟延迟
6. 统计功能的 retrieval_hits 仅存储在 MySQL 中，不存入向量数据库
7. 噪音切片判定阈值（默认 50 次）可在配置文件中修改