限制与错误
容量、文件格式与失败处理。
容量
以下为当前 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 个候选；搜索不提供下一页。
文件格式与处理耗时
知识库可以入库以下类型（按文件服务识别的类型判断）：
| 类型 | 入库内容 |
|---|---|
| 文档文本 | |
| 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 | 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 天后的清除尚未端到端观察。实测也未得到可用于承诺的知识库每秒请求额度。