AddDocuments 导入文档-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 AddDocuments 接口将文档导入知识库。系统自动完成解析、切片、向量化和索引构建。相同 `ossKey` 重复上传会覆盖原有文档。

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
导入前需准备同地域 OSS Bucket 并完成读取授权。AddDocuments 接口支持 API Key 认证；使用 SDK 从本地上传文件时，还需提供用于访问 OSS 的 RAM AccessKey 或临时凭证。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	string	子空间名称，最大 128 UTF-8 字节。开启 subspace 时必填
`documents`	list<object>	文档列表（必填）。单次最多 10 个
`documents[].filePath`	string	仅用于 SDK 的 upload_documents 本地上传方法，不是 AddDocuments HTTP 请求参数。本地文件需先上传至 OSS，再通过 ossKey 导入
`documents[].ossKey`	string	OSS 文件或目录路径，长度 1--256。调用 AddDocuments 时必填
`documents[].metadata`	object	文档元数据，必须与知识库定义的 metadata schema 一致
`documents[].inclusionFilters`	list<string>	包含过滤器，支持首尾 `` 通配符（如 `.pdf`），用于 OSS 目录扫描
`documents[].exclusionFilters`	list<string>	排除过滤器，支持首尾 `` 通配符（如 `draft*`）

请求示例

使用 API Key 认证时，通过 x-ots-instancename 和 x-ots-apikey 请求头传入实例名和 API Key。

### 从 OSS 导入单个文件

curl -X POST https://<endpoint>/AddDocuments \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": "default",
  "documents": [
    {
      "ossKey": "oss://example-bucket/docs/manual.pdf",
      "metadata": {"author": "张三", "date": "2026-01-22 10:00:59", "score": 80}
    }
  ]
}'

### 从 OSS 目录批量导入

ossKey 指定为目录路径（以 / 结尾），系统递归扫描目录下所有文件，通过 inclusionFilters 和 exclusionFilters 按文件名模式过滤。

curl -X POST https://<endpoint>/AddDocuments \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": "default",
  "documents": [
    {
      "ossKey": "oss://example-bucket/docs/",
      "inclusionFilters": ["*.pdf", "*.docx"],
      "exclusionFilters": ["*draft*"]
    }
  ]
}'

响应

字段	类型	说明
`documentDetails`	list<object>	每个文档的受理结果。HTTP 200 且 code 为 SUCCESS 不代表全部文档成功，必须逐项检查 status。succeed 仅表示任务已接收，不代表索引完成；failed 时检查该项的 failureReason。对成功受理的文档，使用返回的 docId 调用 GetDocument 查询状态（开启子空间时传入相同 subspace），等待 completed 后再检索。查询到 failed 时处理失败原因，轮询应设置总超时。
`documentDetails[].docId`	string	文档 ID
`documentDetails[].ossKey`	string	文档 OSS 路径
`documentDetails[].status`	string	succeed` 或 `failed
`documentDetails[].failureReason`	string	失败原因（仅 failed 时）

{
  "code": "SUCCESS",
  "data": {
    "documentDetails": [
      {
      "docId": "fc6ed97f-28ad-4dc0-9b73-bf4a7d67ab65", 
      "status": "succeed", 
      "ossKey": "oss://example-bucket/docs/manual.pdf"
      }
    ]
  },
  "message": "succeed"
}