导入文档

在知识库详情页选择上传文档上传本地文件，或选择导入网址添加网页/YouTube URL。上传只是把文件存到知识库并创建一条 pending 记录；必须再执行处理，文档才会被解析、切分、嵌入并进入检索。

支持的格式

上传文件

1. 在知识库详情页选择上传文档。
2. 拖放文件到对话框，或点击选择文件（可多选）。
3. 前端会逐文件校验扩展名与大小，不合格的文件会立即报错并从队列中移除。
4. 点击上传，界面显示上传进度。
5. 每个文件生成一条文档，状态为 pending。

前端校验只是为了尽早报错，服务端会再次校验扩展名与文件大小：超限返回 file_too_large，不支持的格式返回 invalid_document_type。

上传限制

• 单文件默认上限 50MB，由站点设置 kb_document_max_upload_size_mb 控制，可调范围 1-1024MB。
• 上传对话框会读取该站点设置并显示当前值（最大文件大小：50MB），因此在管理员调整后应刷新页面。
• 限制是单文件的：可以一次选择多个文件，但每个文件单独计数、单独创建文档。
• 不支持 ZIP 打包上传，也没有知识库级存储配额；存储占用按团队层面观察。

状态与处理阶段

上传/导入 → 提取文本 → 清理 → 分块 → 生成嵌入 → 建立全文索引 → completed

处理方式有三种，按需要选择：

• 快速处理：直接按知识库（或文档）现有分块设置处理，不经过预览。
• 开始处理（预览页）：先用预览分块确认甚至编辑分块，再提交这些分块生成嵌入。
• 批量处理：在文档表格中勾选多个文档，用选择工具栏批量快速处理等待中文档。

从网址导入

1. 在知识库详情页选择导入网址。
2. 填写完整的 http:// 或 https:// 地址，以及文档名称（1-255 字符）。界面把名称标为可选，但接口的 name 字段是必填的，留空提交会被校验拒绝并回显字段错误，建议一并填写。
3. 点击导入——系统先对目标地址做安全校验（拒绝内网、回环与云元数据地址），通过后创建 url 类型文档并跳转到预览页。
4. 在预览页生成分块预览后提交处理：URL 内容由服务端在此时抓取，因此导入不会自动开始处理。

导入失败时（地址不可达、内容为空、解析失败），文档会保留错误信息，可查看源网址或删除后重试。

失败与重试

重试失败分段只对状态为 error 且存在失败分块的文档可用；如果原文本身没问题（例如只是模型临时故障），这比重新处理更省成本，因为不会丢弃已成功的分块。

通过 API 导入

知识库端点只接受 JWT 用户会话（Authorization: Bearer <ACCESS_TOKEN>），不接受 API Key：

# 上传文件（multipart，字段名固定为 file）
curl -X POST "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/documents/upload" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@./handbook.pdf"

# 导入网址（可选 name）
curl -X POST "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/documents/url" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Release Notes", "source_url": "https://example.com/releases"}'

# 处理文档（可选覆盖分块设置）
curl -X POST "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/documents/$DOC_ID/process" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chunk_size": 1000, "chunk_overlap": 100, "clean_text": true}'

相关页面

• 分块与文档处理 — 预览、处理与编辑分块
• 浏览文档与元数据 — 状态、字段与元数据
• 知识库设置参考 — 上传上限与分块字段