知识存储服务文档导入与管理-表格存储 Tablestore(Tablestore)-阿里云帮助中心

管理知识库中的文档，包括导入、查询、列出、更新和删除操作。

前提条件

已创建 AgentStorage 实例并获取访问地址（endpoint）和实例名
已创建知识库，参见知识库管理。
如需从本地上传文档，账号下需有与实例同地域的 OSS Bucket 并完成 OSS 授权；SDK 初始化时需额外提供 OSS 配置（AccessKey 与 OSS Endpoint/Bucket）。

支持文档格式

单次请求最多 10 个文档，单文件最大 50MB。

如需提升请提交工单或加入表格存储技术交流群 36165029092 后联系技术支持。

图片入库与多模态检索需在创建知识库时开启多模态，开启后不可修改；未开启多模态的知识库上传图片将无法进行图片向量化与检索。

类型	扩展名
PDF	`.pdf`
Word	`.doc`、`.docx`
Excel	`.xls`、`.xlsx`
PowerPoint	`.ppt`、`.pptx`
纯文本	`.txt`
Markdown	`.md`
结构化文本	`.csv`、`.xml`、`.html`、`.json`
图片	`.jpeg`、`.png`、`.bmp`、`.webp`、`.gif`、`.tiff`

文档状态流转

文档从上传到可检索，经历以下状态：

状态	说明	可执行的操作
`Pending`	上传任务已接收，等待处理	查询状态、删除
`Indexing`	正在解析、切片和向量化	查询状态、删除
`Completed`	索引完成，可被检索	检索、更新元数据、删除、查看切片
`Failed`	索引失败	查看失败原因、删除、重新上传
`Deleting`	文档及其切片正在删除	等待删除完成

文档上传后处于 Pending 或 Indexing 状态时无法被检索到。必须等到状态变为 Completed 才能检索。

导入文档

将文档导入知识库。系统自动完成解析、切片、Embedding 向量化和索引构建。相同 ossKey 重复上传会覆盖原有文档，提供三种导入方式：

方式	说明
上传本地文件	指定本地文件路径，SDK 自动上传至 OSS 后添加到知识库
添加 OSS 文件	指定已存在的 OSS 文件路径
OSS 目录批量导入	指定 OSS 目录路径，系统递归扫描所有文件

控制台

登录Agent Storage控制台，打开目标知识库卡片，进入文档管理，点击上传文档。
选择导入方式：
- 上传文件：选择上传位置（OSS Bucket），再选择本地文件上传。
- 上传文件夹：按目录批量上传，可设置是否递归以及包含、排除的文件扩展名。
- 从 OSS 导入：选择数据源 Bucket 后，导入 OSS 中已有的文件或目录。
点击确定开始导入。

若知识库定义了元数据模式，上传面板会显示第 3 步「Metadata（可选）」，可为文档填写对应字段；未定义元数据模式的知识库无此步骤。

文件类型、单文件大小和批量数量限制以上传面板为准。文档上传后需经过解析和切片，状态变为已完成后才能检索。若出现 OSS 授权提示，请先完成授权再继续。

SDK

Python

上传本地文件

使用 upload_documents 时，初始化 AgentStorageClient 需同时提供 oss_endpoint 和 oss_bucket_name，否则抛出 ValueError。

from tablestore_agent_storage import AgentStorageClient

# 上传本地文件需配置 OSS（SDK 会先把文件上传至 OSS，再触发切片与向量化）
client = AgentStorageClient(
    access_key_id="<AccessKey ID>",
    access_key_secret="<AccessKey Secret>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
    oss_endpoint="https://oss-<region>.aliyuncs.com",
    oss_bucket_name="<bucket-name>",
)

resp = client.upload_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "filePath": "/home/user/docs/product_manual.pdf",
            "metadata": {"author": "张三", "category": "产品文档"}
        },
        {
            "filePath": "/home/user/docs/faq.docx",
            "metadata": {"author": "李四", "category": "FAQ"}
        }
    ]
})

for detail in resp["data"]["documentDetails"]:
    print(detail["ossKey"], detail["status"])

添加 OSS 文件

文件已在 OSS 上时，直接指定 ossKey，使用 API Key 认证即可。

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.add_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "ossKey": "oss://example-bucket/docs/product_manual.pdf",
            "metadata": {"author": "张三"}
        }
    ]
})

OSS 目录批量导入

指定 OSS 目录路径，系统递归扫描目录下所有文件。通过 inclusionFilters 和 exclusionFilters 按文件名模式过滤。

resp = client.add_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "ossKey": "oss://example-bucket/docs/",
            "inclusionFilters": ["*.pdf", "*.docx"],
            "exclusionFilters": ["*draft*"]
        }
    ]
})

TypeScript

上传本地文件

TypeScript 上传本地文件需使用 NodeAgentStorageClient，并提供 OSS 配置。

import { NodeAgentStorageClient } from '@tablestore/agent-storage/node';

const client = new NodeAgentStorageClient({
  accessKeyId: '<AccessKey ID>',
  accessKeySecret: '<AccessKey Secret>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
  ossEndpoint: 'https://oss-<region>.aliyuncs.com',
  ossBucketName: '<bucket-name>',
  ossAccessKeyId: '<AccessKey ID>',
  ossAccessKeySecret: '<AccessKey Secret>',
});

const resp = await client.uploadDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    {
      filePath: '/home/user/docs/product_manual.pdf',
      metadata: { author: '张三', category: '产品文档' },
    },
  ],
});

for (const detail of resp.data.documentDetails) {
  console.log(detail.ossKey, detail.status);
}

添加 OSS 文件

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.addDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    {
      ossKey: 'oss://example-bucket/docs/product_manual.pdf',
      metadata: { author: '张三' },
    },
  ],
});

OSS 目录批量导入

const resp = await client.addDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    {
      ossKey: 'oss://example-bucket/docs/',
      inclusionFilters: ['*.pdf', '*.docx'],
      exclusionFilters: ['*draft*'],
    },
  ],
});

API

调用 AddDocuments 导入文档。完整请求字段与响应说明参见导入文档。

HTTP 200 + code: SUCCESS 不代表所有文档都处理成功。必须逐个检查 documentDetails 中每个文档的 status 字段。
status: "succeed" 表示上传任务已接收，并非索引完成。必须等到文档状态变为 Completed 才能被检索。
知识库开启 subspace 后必须传 subspace 参数，否则报 INVALID_PARAMETER。
metadata 日期格式需使用支持的格式（如 yyyy-MM-dd HH:mm:ss），不支持的格式会导致文档 failed。

查询索引状态

文档上传后经过异步处理才能被检索。如需确认文档是否索引完成，建议采用指数退避轮询。

控制台

在文档管理列表的“状态”列查看每个文档的当前状态，也可用列表上方的状态筛选（全部/待处理/索引中/已完成/失败/删除中）快速定位。点击操作列的详情查看文档ID、OSS路径、状态、切片数等完整信息。状态为已完成即表示可检索。

SDK

Python

import time

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

def wait_for_document(client, kb_name, doc_id, max_interval=30):
    """指数退避轮询文档状态，等待索引完成。"""
    interval = 3
    while True:
        resp = client.get_document({
            "knowledgeBaseName": kb_name,
            "docId": doc_id
        })
        status = resp["data"][0]["status"]
        if status == "Completed":
            print(f"索引完成，切片数: {resp['data'][0].get('chunkNum', 'N/A')}")
            return resp
        elif status == "Failed":
            raise Exception(f"索引失败: {resp['data'][0].get('failedDetails')}")
        print(f"当前状态: {status}，{interval}s 后重试...")
        time.sleep(interval)
        interval = min(interval * 2, max_interval)

wait_for_document(client, "product_docs_kb", "fc6ed97f-...")

文档处理时间受文件大小、类型和数量影响，小文件通常几秒完成，大文件或批量导入可能需要数分钟。

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

async function waitForDocument(kbName: string, docId: string, maxInterval = 30) {
  let interval = 3;
  while (true) {
    const resp = await client.getDocument({
      knowledgeBaseName: kbName,
      docId,
    });
    const doc = resp.data[0];
    if (doc.status === 'Completed') {
      console.log(`索引完成，切片数: ${doc.chunkNum ?? 'N/A'}`);
      return resp;
    } else if (doc.status === 'Failed') {
      throw new Error(`索引失败: ${doc.failedDetails}`);
    }
    console.log(`当前状态: ${doc.status}，${interval}s 后重试...`);
    await new Promise((r) => setTimeout(r, interval * 1000));
    interval = Math.min(interval * 2, maxInterval);
  }
}

await waitForDocument('product_docs_kb', 'fc6ed97f-...');

API

调用 GetDocument 查询文档状态。完整字段参见查询文档。

查询文档

查询指定文档的详细信息，包括处理状态、切片数量和元数据。docId 与 ossKey 二选一。

控制台

在文档管理列表中点击目标文档操作列的详情，查看文档ID、名称、OSS路径、状态、切片数、子空间、ETag、创建时间和更新时间。

SDK

同一个 ossKey 经历创建→删除→创建后，get_document 可能返回多条记录（含历史记录）。请根据 status 字段判断有效文档，取 Completed 状态的记录。

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.get_document({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-..."
})

doc = resp["data"][0]
print(f"状态: {doc['status']}, 切片数: {doc.get('chunkNum', 'N/A')}")

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.getDocument({
  knowledgeBaseName: 'product_docs_kb',
  docId: 'fc6ed97f-...',
});

const doc = resp.data[0];
console.log(`状态: ${doc.status}, 切片数: ${doc.chunkNum ?? 'N/A'}`);

API

调用 GetDocument 查询文档详情。完整字段参见查询文档。

列出文档

分页查询知识库下的文档列表。

控制台

进入知识库的文档管理页面，列表展示文档名称、创建时间、更新时间、切片数和状态，可用列表上方的状态筛选（全部/待处理/索引中/已完成/失败/删除中）快速定位。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

# 获取第一页
resp = client.list_documents({
    "knowledgeBaseName": "product_docs_kb",
    "maxResults": 20
})
for doc in resp["data"]["documentDetails"]:
    print(f"[{doc['status']}] {doc['ossKey']} (切片数: {doc.get('chunkNum', '-')})")

# 翻页
next_token = resp["data"].get("nextToken")
if next_token:
    resp = client.list_documents({
        "knowledgeBaseName": "product_docs_kb",
        "maxResults": 20,
        "nextToken": next_token
    })

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.listDocuments({
  knowledgeBaseName: 'product_docs_kb',
  maxResults: 20,
});
for (const doc of resp.data.documentDetails) {
  console.log(`[${doc.status}] ${doc.ossKey} (切片数: ${doc.chunkNum ?? '-'})`);
}

API

调用 ListDocuments 列出文档。完整字段参见列出文档。

maxResults 默认 10，最大 1000。
subspace 参数支持多值列表，最多 10 个，超过会报错；开启 subspace 时必填。

更新文档元数据

更新指定文档的 metadata。仅 Completed 状态的文档可更新元数据，对其他状态调用会报错。

metadata 采用覆盖式更新，传入的值会全量替换原有 metadata。如果只想更新一个字段，必须把所有字段都带上。
传入 "metadata": null 会清空所有 metadata；不传 metadata 字段则保留原值。
metadata 总大小（key + value）最大 4KB，字段数最多 200 个。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.update_document({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-...",
    "metadata": {"author": "张三", "category": "技术文档", "version": 2}
})

print(f"更新状态: {resp['data']['updateStatus']}")  # UPDATED 或 NO_OP

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.updateDocument({
  knowledgeBaseName: 'product_docs_kb',
  docId: 'fc6ed97f-...',
  metadata: { author: '张三', category: '技术文档', version: 2 },
});

console.log(`更新状态: ${resp.data.updateStatus}`); // UPDATED 或 NO_OP

API

调用 UpdateDocument 更新文档元数据。完整字段参见更新文档。

删除文档

重要

删除文档会同时删除其所有切片数据，操作不可逆。

控制台

在文档管理列表中勾选一个或多个文档后点击批量删除，或点击单行操作列的删除。弹出确认框后，点击确定完成删除。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.delete_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {"docId": "fc6ed97f-..."},
        {"ossKey": "oss://example-bucket/docs/faq.docx"}
    ]
})

# 逐个检查删除结果
for detail in resp["data"]["documentDetails"]:
    print(f"{detail['ossKey']}: {detail['status']}")

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.deleteDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    { docId: 'fc6ed97f-...' },
    { ossKey: 'oss://example-bucket/docs/faq.docx' },
  ],
});

// 逐个检查删除结果
for (const detail of resp.data.documentDetails) {
  console.log(`${detail.ossKey}: ${detail.status}`);
}

API

调用 DeleteDocuments 删除文档。完整字段参见删除文档。

前提条件

支持文档格式

文档状态流转

导入文档

控制台

SDK

Python

上传本地文件

添加 OSS 文件

OSS 目录批量导入

TypeScript

上传本地文件

添加 OSS 文件

OSS 目录批量导入

API

查询索引状态

控制台

SDK

Python

TypeScript

API

查询文档

控制台

SDK

Python

TypeScript

API

列出文档

控制台

SDK

Python

TypeScript

API

更新文档元数据

SDK

Python

TypeScript

API

删除文档

控制台

SDK

Python

TypeScript

API

相关文档