管理分段和处理任务¶

维护知识库数据源的当前分段快照，并查询或协调数据处理任务。

前提条件¶

准备可访问目标工作区的凭据、目标知识库和数据源的标识。有关服务地址、认证和通用请求格式，请参阅调用前准备。

开始前先确认数据源已加入知识库。分段写入要求文件来源已有 kb_file_id 且向量索引可用；表来源不支持分段写入。

调用顺序¶

先查询知识库处理任务列表，确认来源处理状态，再查询知识库文档详情取得当前分段和 data.etag。
创建、更新、启停或删除分段时，将 ETag 传入请求体 if_match 或 If-Match 请求头；非空请求体值优先。
修改成功后使用 data.document.etag 继续操作。遇到 409 和 ErrConflict 时，重新读取快照并确认修改内容后再提交。
需要重算当前分段向量时，调用重新向量化，完成写入后取得文档快照。处理任务状态异常时使用协调动作，再查询处理任务确认结果。

API 操作¶

管理当前分段¶

要完成的事	API 操作	何时使用
创建分段	创建文档分段	已确定数据源和分段内容时使用。
更新分段	更新文档分段	已取得目标分段标识，需要修改内容或配置时使用。
启用或停用分段	启用或停用文档分段	调整分段是否参与当前使用时使用。
删除分段	删除文档分段	删除前先在动作页确认影响和条件。

处理和重新处理数据¶

要完成的事	API 操作	何时使用
查询数据处理任务	查询知识库处理任务列表	查看处理任务及后续确认结果时使用。
协调数据处理任务	修复知识库处理任务状态	需要协调目标数据源的处理任务时使用。
重新向量化	重新向量化知识库数据源	需要重新向量化目标数据源时使用。

结果确认¶

协调处理任务后，使用查询知识库处理任务列表查看目标任务。分段写入和重新向量化返回完整文档快照；可通过查询知识库文档详情回查内容和启用状态。

限制和注意事项¶

删除和停用分段会改变检索结果。删除不可恢复，且来源必须保留至少一个分段。详情中的 next_cursor 用于读取后续分段页，ETag 用于整个当前快照的条件写入。

旧批量导入和版本切换接口已移除。创建分段每次处理一个分段，多次调用不具备批量导入的原子性；启用或停用分段也不能恢复历史内容。

下一步¶

最后更新于 2026 年 10 月 19 日