# 限制与错误 (/docs/cloud/services/knowledge/limits-and-errors)



## 容量 [#容量]

以下为当前 API 上限。下方耗时来自样例实测，不是服务保证。

| 项目                       | 上限                         |
| ------------------------ | -------------------------- |
| 每个组织的未删除知识库              | 100                        |
| 每个知识库的文件                 | 10,000                     |
| 单个源文件                    | 100,000,000 bytes (100 MB) |
| 单个文件估算 token             | 5,000,000                  |
| 每批文件                     | 1–500                      |
| 知识库名称                    | 256 characters             |
| metadata / attributes 键数 | 16                         |
| 键长度 / 字符串值长度             | 64 / 512 characters        |
| 静态分段大小                   | 100–4096 tokens            |
| 默认分段 / 重叠                | 800 / 400 tokens           |
| 分段重叠上限                   | ≤ ½ chunk size             |
| 搜索返回结果数（兼容接口按文件、原生接口按分段） | 1–50; default 10           |
| 列表每页条数                   | 1–100; default 20          |
| 过期天数                     | 1–365                      |
| JSON 请求体                 | 1,000,000 bytes            |
| 入库截止时间                   | 30 minutes                 |
| 处理重试次数                   | 3                          |
| 删除后保留                    | 7 days                     |

metadata 的值只能是字符串；attributes 的值可以是字符串、数字或布尔值。筛选条件在根条件以下最多嵌套 20 层。语义和关键词检索各取最多 50 个候选；搜索不提供下一页。

## 文件格式与处理耗时 [#文件格式与处理耗时]

知识库可以入库以下类型（按文件服务识别的类型判断）：

| 类型                    | 入库内容               |
| --------------------- | ------------------ |
| PDF                   | 文档文本               |
| DOCX、PPTX、XLSX        | 文档文本               |
| PNG、JPEG、GIF、WebP     | 模型生成的画面描述，不是逐字 OCR |
| HTML                  | 可见文本，去掉脚本和样式       |
| 纯文本、Markdown、CSV、JSON | 原文                 |

能上传不代表能入库。文件服务接受、但知识库不能入库的类型有：音频（MP3、WAV、FLAC、OGG、M4A）、视频（MP4、WebM）、NDJSON、XML、YAML、SVG，以及识别为 Python、JavaScript 的源代码文件。它们加入知识库时不会被拒绝，而是在异步入库阶段失败，文件 status 为 failed，`last_error.code` 为 unsupported\_file。加密的 PDF 或 Office 文件同样在入库阶段失败（invalid\_file）。空文件、ZIP 和其他二进制文件在上传时就被文件服务拒绝。

2026-10-11 develop 实测：文本与文档约 4–21 秒入库完成；单张图片约 4–11 秒，7 个文件同时入库时一张 PNG 用了约 87 秒。

## HTTP 错误 [#http-错误]

| HTTP | code                                                                                                        | 处理建议                               |
| ---- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| 400  | INVALID\_PARAMS / LIMIT\_EXCEEDED                                                                           | 修正参数或减少数量。                         |
| 401  | UNAUTHENTICATED                                                                                             | 检查 API Key；兼容响应 code 为 null。       |
| 404  | VECTOR\_STORE\_NOT\_FOUND / FILE\_NOT\_FOUND / FILE\_NOT\_IN\_STORE / BATCH\_NOT\_FOUND / CHUNK\_NOT\_FOUND | 核对资源 ID 与所属知识库。                    |
| 409  | VECTOR\_STORE\_INVALID\_STATE / FILE\_INVALID\_STATE                                                        | 检查删除、过期或文件处理状态。                    |
| 413  | PAYLOAD\_TOO\_LARGE                                                                                         | JSON 请求超过 1 MB；兼容响应 code 可能为 null。 |
| 429  | RATE\_LIMITED                                                                                               | 稍后重试。                              |
| 500  | — / null                                                                                                    | 服务内部错误；保留请求 ID 并稍后重试。              |
| 501  | NOT\_IMPLEMENTED                                                                                            | 当前不支持该操作。                          |
| 503  | PROVIDER\_UNAVAILABLE                                                                                       | 处理服务暂不可用，稍后重试。                     |

原生错误通常包含 `error.code`、`error.message` 与 `error.details`。兼容错误包含 `error.message`、`error.type`、`error.param` 与 `error.code`，官方 SDK 按 HTTP 状态抛出对应异常。未知路径可能没有 code，401 可能没有 details，路径编码错误也可能返回 HTML。

## 异步失败 [#异步失败]

文件 status 为 failed 时查看 `last_error.code`：unsupported\_file 表示无法解析该格式；invalid\_file 表示内容无效、为空或加密；server\_error 表示处理失败或超时。超过估算 token 上限当前映射为 invalid\_file，但尚未实测超限文件。添加成功后仍应检查文件状态。原生 API 支持重试 failed 文件；本次实测未覆盖失败后的成功重试。

真正过期及删除 7 天后的清除尚未端到端观察。实测也未得到可用于承诺的知识库每秒请求额度。

[完整错误对象 →](/docs/api/native/knowledge/errors) · [搜索限制 →](/docs/cloud/services/knowledge/concepts)