查看和更新表格存储知识库文档切片（ListChunks、UpdateChunks）-阿里云帮助中心

文档上传后由系统自动切片（Chunk）。每个 Chunk 存储向量数据和原文内容，是检索的最小单元。通过以下接口查看和调整切片内容。

查看切片

调用 list_chunks 分页查询指定文档的切片列表。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	string	子空间名称。开启 subspace 时必填
`docId`	string	文档 ID。与 `ossKey` 二选一
`ossKey`	string	OSS 路径。与 `docId` 二选一
`maxResults`	int	返回数量。默认为 10，最大 1000
`nextToken`	string	翻页 token

代码示例

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

for chunk in resp["data"]["chunkDetails"]:
    print(f"[Chunk {chunk['chunkId']}] ({chunk['status']}) {chunk['content'][:80]}...")

响应说明

字段	类型	说明
`chunkDetails[].subspace`	string	所属子空间
`chunkDetails[].chunkId`	int	切片 ID
`chunkDetails[].content`	string	切片内容
`chunkDetails[].title`	string	切片标题
`chunkDetails[].chunkType`	string	切片类型，如 `TEXT`
`chunkDetails[].status`	string	`active`（可检索）或 `inactive`（不可检索）
`chunkDetails[].docId`	string	所属文档 ID
`chunkDetails[].ossKey`	string	所属文档 OSS 路径
`chunkDetails[].createdAt`	int	创建时间戳
`chunkDetails[].updatedAt`	int	更新时间戳
`nextToken`	string	翻页 token，为空表示最后一页

更新切片

调用 update_chunks 批量更新切片的标题、内容或状态。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	string	子空间名称。开启 subspace 时必填
`chunks`	list<object>	要更新的切片列表（必填）。单次最多 10 个
`chunks[].docId`	string	文档 ID。与 `ossKey` 二选一
`chunks[].ossKey`	string	OSS 路径。与 `docId` 二选一
`chunks[].chunkId`	int	切片 ID（必填）
`chunks[].title`	string	更新标题，最大 100 Token
`chunks[].content`	string	更新内容，最大 320 Token
`chunks[].status`	string	修改状态：`active`（可检索）或 `inactive`（不可检索）

代码示例

修改切片内容：

resp = client.update_chunks({
    "knowledgeBaseName": "product_docs_kb",
    "chunks": [
        {
            "docId": "fc6ed97f-...",
            "chunkId": 1,
            "title": "更新后的标题",
            "content": "更新后的内容"
        }
    ]
})

屏蔽不准确的切片（设为不可检索）：

resp = client.update_chunks({
    "knowledgeBaseName": "product_docs_kb",
    "chunks": [
        {
            "docId": "fc6ed97f-...",
            "chunkId": 0,
            "status": "inactive"
        }
    ]
})

响应说明

字段	类型	说明
`updateDetails[].docId`	string	文档 ID
`updateDetails[].ossKey`	string	OSS 路径
`updateDetails[].chunkId`	int	切片 ID
`updateDetails[].updateStatus`	string	`succeed` 或 `failed`
`updateDetails[].failureReason`	string	失败原因，仅 failed 时

注意事项

将切片的 status 设为 inactive 后，该切片不会出现在 Retrieve 结果中。可用于临时屏蔽不准确的内容，无需删除整个文档。
单次请求最多更新 10 个切片。