文档中心

上下文搜索

多模态搜索

通过 API 添加 TOS 文件

本文介绍如何通过 API 将火山引擎对象存储（TOS）中的文件导入多模态搜索场景的知识空间。提交入库任务后，系统将自动解析并导入文件，您可以通过查询任务接口查看处理进度和结果。

前提条件

操作步骤

提交入库任务

调用 POST /v1/spaces/{space_id}/ingest 接口提交入库任务，将 TOS 文件地址传入系统。

请求头参数说明

参数	是否必选	说明
X-Admin-Token	是	管理接口鉴权 Token。
X-Caller-Id	是	业务方用户标识，可传入任意字符串值。示例：my-app-user-001。
Content-Type	是	固定值 application/json。

请求体参数说明

参数	类型	是否必选	说明
urls	Array	是	待导入的 TOS 文件列表。每个元素包含 url 字段和可选的 custom_data 字段。
urls[].url	String	是	TOS 文件地址，格式为 tos://bucket/path/filename。
urls[].custom_data	Object	否	自定义键值对，可附加业务元数据到文档。
connector_type	String	是	固定值 tos，表示从对象存储导入。
authz_provider	String	否	权限控制方式，默认 local。
authz_visibility	String	否	文档可见性，可选值如下： public（公开） restricted（受限） no_search（不被检索）默认值为 restricted。
authz_subject_keys	Array	否	可访问主体列表，当 authz_visibility 为 restricted 时生效。格式示例：["user:123", "dept:engineering"]。

请求示例

返回示例

说明

接口提交成功后，仅表示任务已创建，并不代表文件已经完成导入。请使用返回的 task_id 查询任务执行状态。

查询任务状态

调用 GET /v1/spaces/{space_id}/tasks/{task_id} 查询任务状态，确认文件解析和入库是否完成。入库任务为异步执行。提交任务后，通过该接口查询任务详情和每个文档的处理结果。

请求头参数说明

参数	是否必选	说明
X-Admin-Token	是	管理接口鉴权 Token。

请求体参数说明

请求示例

返回示例

返回参数说明

参数	说明
task_id	任务唯一标识。
status	任务整体状态，可选值如下： pending（等待中） running（执行中） succeeded（全部成功） failed（存在失败）由于导入任务异步执行，建议间隔 2～5 秒轮询一次，直到 status 为 succeeded 或 failed。
item_total	提交的文档总数。
item_succeeded	处理成功的文档数。
item_failed	处理失败的文档数。
affected_doc_ids	入库成功后生成的文档 ID 列表。
items	每个文档的处理详情，包含 source_url、doc_id、status、error_code 和 error_message。

当任务状态为 succeeded 后，表示文件已完成解析和入库，可在多模态搜索场景中进行检索。

常见问题

返回 401 ADMIN_TOKEN_REQUIRED

检查请求头中是否正确传入了 X-Admin-Token。

返回 503 ADMIN_TOKEN_NOT_CONFIGURED

服务端尚未配置 Admin Token，请联系管理员完成配置。

任务状态长时间为 pending

确认场景已完成发布且服务处于运行中状态。

文件解析失败（item status 为 failed）

检查 TOS 文件路径是否正确、文件格式是否受支持、TOS 权限是否已授予 ContextSearch 服务读取。

最近更新时间：2026.08.06 10:51:10

这个页面对您有帮助吗？

有用

无用