LAS 为您提供多个在线算子 API，您可单个调用对应算子 API，同时，LAS 也为您提供了批量提交算子任务的批任务（Batch Task） API，通过 Batch Task API，您可通过一次批任务同时提交多个算子子任务，可减少 submit/poll API 使用次数，减少等待时 client 端资源占。本文为您介绍 Batch Task 涉及的 API 列表、参数介绍及使用示例。 # 背景信息 ## Batch Task 处理链路 Batch Task 为您提供了 submit、get、list 等接口，通过 Batch Task 的 submit 接口提交批任务时，您可以指定本次批任务包含哪些算子处理的子任务。批任务支持 JSONL 和 Lance 两种输入类型：使用 JSONL 时，Batch Task 读取 TOS 中的子任务列表，并将处理结果写回指定的 TOS 输出路径；使用 Lance 时，Batch Task 根据字段映射读取 Lance 表中的数据，并将算子处理结果写回 Lance 表的指定列。 ![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/934e23d032694073b301e1818af5c5d9~tplv-goo7wpa0wc-topic.webp) ## 术语 * **批任务（Batch Task）** ：一次离线批处理作业的顶层实体，包含输入文件、输出目录、目标算子、状态、统计计数与运行参数等。 * **子任务（Subtask）** ：批任务拆分后的最小执行单元，通常对应输入 JSONL 或 Lance 表中的一行；每个子任务最终会关联一个底层 `task_id`（复用现有 submit/poll 异步任务）。 * **结果文件（Result File）** ：批任务完成后写入 TOS 的 `results.jsonl` 与 `errors.jsonl`。 * **Lance 字段映射**：用于建立 Lance 字段与算子参数之间的对应关系。输入字段映射将 Lance 字段转换为算子请求参数，输出字段映射将算子返回结果写入 Lance 表的指定列。 ## 批任务优先级调度创建批任务时，可通过 `priority` 设置任务在当前账号内的调度优先级。优先级从高到低依次为 `HIGH`、`NORMAL`、`LOW`，不传时默认为 `NORMAL`。 * 当账号内存在更高优先级的非终态批任务时，低优先级批任务暂停分发新的子任务；已经提交的子任务不会被终止，仍会执行至终态并正常写入结果。 * 同一优先级的批任务互不抢占，共享当前账号的并发额度。 * 更高优先级任务进入终态后，被暂停的低优先级任务自动恢复分发。 * 重跑失败子任务时沿用原批任务的优先级。批任务创建后暂不支持通过 update 接口修改优先级。 ## 接口性能 * 每个批任务的子任务并发限制：默认为10，如果您希望提高子任务并发数，可[提交工单](https://console.volcengine.com/workorder/create?step=1)联系技术支持人员，提高子任务并发度。 * 批任务的并发限制：默认 10 # 输入与输出规范 ### 输入：input.jsonl 批任务以“文件驱动”的方式运行：您需要上传输入文件到 TOS，服务端负责拆分、编排、聚合。 |细分 |详细说明 | |---|---| |格式规范 |输入文件为 JSONL，每行是一个 JSON 对象（一个算子子任务）。以 PDF 算子为例：

```JSON```
```{"custom_id":"000001","data":{"url": "https://las-ai-cn-shanghai-online.tos-cn-shanghai.volces.com/v1/pdf-sample.pdf", "parse_mode": "normal" }}```
```{"custom_id":"000002","data":{"url": "https://las-ai-cn-shanghai-online.tos-cn-shanghai.volces.com/v1/pdf-sample-02.pdf", "parse_mode": "normal" }}```

字段说明：

* `custom_id`：文件内唯一，用于将本次批任务中的每个子任务的输入行与输出行关联。

* `data`：当前子任务对应的“算子调用参数体”（算子 API 的 submit 接口中 data 部分的请求参数）。其结构以具体 operator 为准。 | |输入文件限制 |* 单文件大小：不超过 **1G**

* 总行数：不超过 **100 万行** | |输入 TOS 路径 |通过批任务的 `input_tos_url` 请求参数指定输入文件的 TOS 路径。

* 您需要将子任务文件上传至与当前 LAS 服务同主账号、同地域的 TOS Bucket 后，提供输入文件的 TOS 路径，格式参考：`tos://bucket_name/demo/`。 | ### 输出：results.jsonl / errors.jsonl 批任务完成后在指定 TOS 输出目录下写入标准化结果文件。 |细分 |详细说明 | |---|---| |格式规范 |`results.jsonl`：成功结果集合，每行是一个成功子任务的处理结果。

```JSON```
```{"id": "batch-task-123", "custom_id": "000001", "metadata": {"task_id": "xxx", "task_status": "COMPLETED", "business_code": 0}, "data": {"markdown": "我的小狗 \\n我家有一只可爱的小狗,它的名字叫小白｡", "detail": [{"page_id": 1, "page_md": "我的小狗 \\n我家有一只可爱的小狗,它的名字叫小白｡", "page_image_hw": {"h": 3508, "w": 2480}, "text_blocks":[]}]}}```
```{"id": "batch-task-123", "custom_id": "000002", "metadata": {"task_id": "xxx", "task_status": "COMPLETED", "business_code": 0}, "data": {"markdown": "我的小狗 \\n我家有一只可爱的小狗,它的名字叫小白｡", "detail": [{"page_id": 1, "page_md": "我的小狗 \\n我家有一只可爱的小狗,它的名字叫小白｡", "page_image_hw": {"h": 3508, "w": 2480}, "text_blocks":[]}]}}```

处理结果文件中包含：

* `id`：当前批任务的任务id。

* 本次批任务中，对应子任务的处理结果，包含`custom_id`（子任务的id标识） + `data`（子任务处理结果） + `metadata`（子任务元数据信息）。 | ||`errors.jsonl`：失败结果集合，每行是一个失败任务的失败返回。

```JSON```
```{"id": "batch-task-123", "custom_id": "000001", "metadata": {"task_id": "xxx", "task_status": "FAILED", "business_code": "Parameter.Invalid", "error_msg": "Url is invalid"}}```

处理结果文件中包含：

* `id`：当前批任务的任务id。

* 失败任务的返回结果，包含： `custom_id` （子任务的id标识）+ `metadata`（含 `task_status`、`business_code`、`error_msg` 等）。 | |输出 TOS 路径 |通过批任务的 `output_tos_url` 请求参数指定输出文件的 TOS 路径。

* 需要提供与 LAS 服务同主账号、同地域的 TOS Bucket 路径，格式参考：`tos://bucket_name/demo/`。

* 实际生成结果文件时，会在指定路径下分别创建成功结果、失败结果目录，并写入结果文件：

* `results.jsonl`：`{OutputDir}/{batch_task_id}/output/results.jsonl`

* `errors.jsonl`：`{OutputDir}/{batch_task_id}/error/errors.jsonl` | ### 输入与输出：Lance 使用 Lance 数据集作为批任务输入时，将 `input_type` 设置为 `LANCE`，并通过 `lance_params` 配置唯一键、输入字段映射和输出字段映射。Lance 数据集需要存储在当前账号可访问的 TOS 路径中。 > **Lance 参数校验** > 提交 Lance 批任务时，系统会预检 Lance 数据集是否可访问、唯一键列和映射字段是否存在，以及输出字段是否可写。`lance_params` 缺少必填字段、字段映射格式不正确或引用的字段不存在时，请求校验不通过。读取数据时，如果 `lance_key_field` 对应列包含空值或重复值，批任务无法继续初始化。 * **唯一键**：`lance_key_field` 指定的列必须存在，且列值唯一、非空。系统将该列的值作为子任务的 `custom_id`，用于结果写回、幂等去重和断点续写。 * **输入字段映射**：`input_field_mappings` 将 Lance 字段映射为算子 Submit 接口 `data` 中的请求参数。`lance_field` 和 `operator_field` 均支持使用 `.` 访问嵌套字段，使用 `[num]` 访问数组中的指定元素。 * **输出字段映射**：`output_field_mappings` 将算子返回结果写入 Lance 表的指定列。输出列不存在时由系统创建；输出列已存在时，系统按照唯一键更新对应行。 * **失败信息写回**：配置 `lance_error_field` 后，失败子任务的错误信息会写入该列；该列不存在时由系统创建。 * **结果文件**：Lance 模式仍会在 `output_tos_url` 指定的路径中生成 `results.jsonl` 和 `errors.jsonl`，用于结果审计和异常排查。字段映射示例： ```JSON { "lance_key_field": "doc_id", "lance_write_batch_size": 1000, "lance_error_field": "parse_error", "input_field_mappings": [ {"lance_field": "tos_url", "operator_field": "url"}, {"lance_field": "parse_config.mode", "operator_field": "parse_mode"} ], "output_field_mappings": [ {"lance_field": "parse_result", "operator_field": "data.detail"}, {"lance_field": "markdown_content", "operator_field": "data.markdown"} ] } ``` #### 数组子字段映射字段路径中的数组下标从 `0` 开始。您可以将 `.` 与 `[num]` 组合使用，精确读取 Lance 数组字段、构造算子请求中的数组子字段，或提取算子返回结果中的数组元素。`[num]` 表示固定位置的单个元素，不会自动遍历或展开整个数组。 |使用位置 |路径示例 |含义 | |---|---|---| |输入映射的 `lance_field` |`materials[0].url` |读取 Lance 当前行 `materials` 数组中第 1 个元素的 `url`。 | |输入映射的 `operator_field` |`config[0].mode` |将映射值写入算子请求 `{"config":[{"mode":"<映射值>"}]}`。 | |输出映射的 `operator_field` |`data.detail[0]` |从算子返回结果中提取 `data.detail` 数组的第 1 个元素并写入目标 Lance 列。 | 以下示例同时演示 Lance 数组元素读取和算子参数数组子字段构造。实际使用时，`operator_field` 必须符合目标算子 Submit API 的参数结构。 ```JSON { "input_field_mappings": [ { "lance_field": "materials[0].url", "operator_field": "inputs[0].url" }, { "lance_field": "parse_config.mode", "operator_field": "inputs[0].config.mode" } ], "output_field_mappings": [ { "lance_field": "first_detail", "operator_field": "data.detail[0]" } ] } ``` # 准备工作 |细分项 |准备工作说明 | |---|---| |获取 LAS API Key |提交批任务前，您需要先生成算子调用的API Key，并建议将API Key配置为环境变量，便于更安全地调用算子，详情请参见[获取 API Key 并配置](https://docs.volcengine.com/docs/6492/2191994)。 | |获取 BaseURL |提交批任务前，您需要先根据您当前使用的LAS服务所在地域，了解算子调用的BaseURL，用于配置算子调用路径参数取值。

详情请参见[获取 Base URL](https://docs.volcengine.com/docs/6492/2191993)，下文中的调用示例仅作为参考，实际调用时需替换为您对应地域的路径取值。 | |规划输入与输出 JSON 文件的 TOS 路径 |提交批任务前，您需要先将本次批任务涉及的子任务，参考对应算子的 API 参数要求，整理好子任务的输入文件，并上传至 TOS；并规划好输出结果文件的输出 TOS 路径，用于提交批任务时配置。 | |准备 Lance 数据集和字段映射 |使用 Lance 输入时，请确认 Lance 数据集可访问，`lance_key_field` 指定的列存在且列值唯一、非空，并根据目标算子的 API 参数准备输入和输出字段映射。同一个 Lance 数据集同时仅支持一个活跃的写入任务。 | # API 接口调用 ## 创建批任务（submit）使用 submit 创建任务，返回 `batch_task_id`。 ### 请求参数 **name** string 必选 `示例值: demo_batch_task` 批任务名称。 **description** string `Optional` `示例值: batch task demo` 批任务描述信息。 **priority** string `Optional` `示例值: HIGH` 批任务在当前账号内的调度优先级，可选 `HIGH`、`NORMAL`、`LOW`，默认 `NORMAL`。当存在更高优先级的非终态批任务时，当前任务暂停分发新的子任务。 **operator_id** string 必选 `示例值: las_long_video_understand` 算子 ID。 **operator_version** string 必选 `示例值: v1` 算子版本。 **input_type** string `Optional` `示例值: JSONL` 批任务输入类型，支持 `JSONL`、`LANCE`，默认值为 `JSONL`。 **input_tos_url** string 必选 `示例值: tos://example-bucket/dataset/input.jsonl` 批量任务输入数据的 TOS 地址。使用 JSONL 时填写输入文件地址；使用 Lance 时填写 Lance 数据集地址。 **output_tos_url** string 必选 `示例值: tos://example-bucket/batch-task/output/` 批量任务输出目录的 TOS 地址。 **extra_params** object `Optional` `示例值: {"model_name":"doubao-seed-2-0-lite-260215"}` 批量任务公共参数。使用 JSONL 时，单行 `data` 中的同名参数优先；使用 Lance 时，字段映射生成的同名参数优先。 **lance_params** lance_params `Optional` Lance 数据集的读取、字段映射和结果写回配置。`input_type` 为 `LANCE` 时必填。 **lance_key_field** string 必选 `示例值: doc_id` Lance 表中用于定位行的唯一键列。列值必须唯一且非空，系统将其值作为子任务的 `custom_id`。 **lance_write_batch_size** integer `Optional` `示例值: 1000` 写回 Lance 的分批大小，单位为行，默认值为 `1000`。批次越大，版本提交次数越少，但单次写入耗时越长。 **input_field_mappings** list of field_mapping 必选 `示例值: [{"lance_field":"tos_url","operator_field":"url"}]` 输入字段映射列表。 **lance_field** string 必选 `示例值: parse_config.mode` Lance 字段路径，支持使用 `.` 访问嵌套字段，使用 `[num]` 访问数组中的指定元素。 **operator_field** string 必选 `示例值: parse_mode` 算子 Submit 接口 `data` 中的请求参数路径，支持使用 `.` 访问嵌套字段，使用 `[num]` 访问数组中的指定元素。 **output_field_mappings** list of field_mapping 必选 `示例值: [{"lance_field":"parse_result","operator_field":"data.detail"}]` 输出字段映射列表。 **lance_field** string 必选 `示例值: parse_result` 写回 Lance 表的列名。该列不存在时由系统创建，已存在时按照唯一键更新对应行。 **operator_field** string 必选 `示例值: data.detail` 算子返回字段路径，支持使用 `.` 访问嵌套字段，使用 `[num]` 访问数组中的指定元素；使用 `*` 表示完整算子返回结果。 **lance_error_field** string `Optional` `示例值: parse_error` 用于写回失败子任务错误信息的 Lance 列名。该列不存在时由系统创建。 **project_name** string `Optional` `示例值: default` 项目名，默认 `default`。 ### 返回参数 |参数名 |参数类型 |参数描述 | |---|---|---| |batch_task_id |String |批任务 ID | ### 请求示例 **JSONL 输入示例** ```Bash # submit curl --location "${BASE_URL}/api/v1/batch-task/submit" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${API_KEY}" \ --data '{ "name": "demo_batch_task", "description": "batch task demo", "priority": "HIGH", "operator_id": "las_long_video_understand", "operator_version": "v1", "input_tos_url": "tos://liuliu-test/batch_task_test/input_1.jsonl", "output_tos_url": "tos://liuliu-test/batch_task_test/output/", "extra_params": { "model_name": "doubao-seed-2-0-lite-260215" }, "project_name": "default" }' ``` **Lance 输入示例** ```Bash # submit curl --location "${BASE_URL}/api/v1/batch-task/submit" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${API_KEY}" \ --data '{ "name": "pdf_parse_lance_batch", "description": "parse PDF files in a Lance dataset", "priority": "NORMAL", "operator_id": "las_pdf_parse_doubao", "operator_version": "v1", "input_type": "LANCE", "input_tos_url": "tos://example-bucket/dataset/input.lance/", "output_tos_url": "tos://example-bucket/batch-task/output/", "lance_params": { "lance_key_field": "doc_id", "lance_write_batch_size": 1000, "lance_error_field": "parse_error", "input_field_mappings": [ {"lance_field": "tos_url", "operator_field": "url"}, {"lance_field": "parse_config.mode", "operator_field": "parse_mode"} ], "output_field_mappings": [ {"lance_field": "parse_result", "operator_field": "data.detail"}, {"lance_field": "markdown_content", "operator_field": "data.markdown"} ] }, "project_name": "default" }' ``` ### 返回示例 ```JSON { "batch_task_id": "bt-1234567890" } ``` ## 查询任务进度（get） 1. 调用 get，并传入 `batch_task_id`。 2. 关注返回的 `status` 与 `request_counts`（total/completed/failed/terminated）。 3. 当任务进入终态后，结合 `output_tos_url` 获取结果文件。 ### 请求参数 |参数名称 |参数类型 |是否必须 |默认值 |说明 | |---|---|---|---|---| |batch_task_id |String |是 | |批任务 ID | ### 返回参数 **batch_task_detail** BatchTaskDetail 必选批任务详情。 **batch_task_id** string 必选 `示例值: bt-1234567890` 批任务 ID。 **name** string 必选 `示例值: demo_batch_task` 批任务名称。 **description** string 必选 `示例值: batch task demo` 描述信息。 **input_tos_url** string 必选 `示例值: tos://example-bucket/batch-task/input.jsonl` 批量任务输入数据的 TOS 地址。 **output_tos_url** string 必选 `示例值: tos://example-bucket/batch-task/output/` 批量任务输出目录的 TOS 地址。 **status** string 必选 `示例值: RUNNING` 批任务状态，取值说明参见批任务状态参考。 **priority** string 必选 `示例值: HIGH` 批任务的调度优先级，可选 `HIGH`、`NORMAL`、`LOW`。 **preemptionState** string 必选 `示例值: NORMAL` 批任务的抢占状态。`NORMAL` 表示正常分发子任务；`PREEMPTED` 表示当前被同账号内更高优先级的批任务抢占，暂不分发新的子任务。已提交的子任务仍继续执行。 **request_counts** RequestCounts 必选批任务请求数量统计。 **total** integer 必选 `示例值: 100` 请求总数。 **completed** integer 必选 `示例值: 80` 已完成请求数。 **failed** integer 必选 `示例值: 2` 失败请求数。 **terminated** integer 必选 `示例值: 0` 已终止请求数。 **create_time** string 必选 `示例值: 2026-07-13T03:10:11Z` 创建时间。 **update_time** string 必选 `示例值: 2026-07-13T03:20:00Z` 更新时间。 **stop_time** string 必选停止时间；任务未停止时为空字符串。 **end_time** string 必选结束时间；任务未结束时为空字符串。 **error_message** string 必选错误信息；没有错误时为空字符串。 **owner_id** integer 必选 `示例值: 12345678` 创建者 ID。 ### 请求示例 ```Bash # get curl --location "${BASE_URL}/api/v1/batch-task/get" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${API_KEY}" \ --data "{\n \"batch_task_id\": \"${BATCH_TASK_ID}\"\n }" ``` ### 返回示例 ```JSON { "batch_task_detail": { "batch_task_id": "bt-1234567890", "name": "demo_batch_task", "description": "batch task demo", "input_tos_url": "tos://liuliu-test/batch_task_test/input_100.jsonl", "output_tos_url": "tos://liuliu-test/batch_task_test/output/", "status": "RUNNING", "priority": "HIGH", "preemptionState": "NORMAL", "request_counts": { "total": 100, "completed": 80, "failed": 2, "terminated": 0 }, "create_time": "2026-07-13T03:10:11Z", "update_time": "2026-07-13T03:20:00Z", "stop_time": "", "end_time": "", "error_message": "", "owner_id": 12345678 } } ``` ## 列表查询（list）用于批量查看任务列表。 ### 请求参数 |参数名称 |参数类型 |是否必须 |默认值 |说明 | |---|---|---|---|---| |batch_task_ids |Array |否 | |批任务 ID 过滤 | |batch_task_name |String |否 | |批任务名称过滤，支持模糊查询 | |statuses |Array |否 | |状态过滤 | |owner_ids |Array |否 | |创建者 ID 过滤 | |sort_order |String |否 |Desc |排序顺序 | |sort_by |String |否 | |排序字段 | |max_results |Integer |否 |10 |单页记录数 | |next_token |String |否 |0 |下一次查询起始 ID（不包含）或页码 | ### 返回参数 **items** list of BatchTaskSummary 必选批任务简要信息列表。 **batch_task_id** string 必选 `示例值: bt-1234567890` 批任务 ID。 **name** string 必选 `示例值: demo_batch_task` 批任务名称。 **description** string 必选 `示例值: batch task demo` 描述信息。 **output_tos_url** string 必选 `示例值: tos://example-bucket/batch-task/output/` 批量任务输出目录的 TOS 地址。 **status** string 必选 `示例值: RUNNING` 批任务状态，取值说明参见批任务状态参考。 **priority** string 必选 `示例值: NORMAL` 批任务的调度优先级，可选 `HIGH`、`NORMAL`、`LOW`。 **preemptionState** string 必选 `示例值: PREEMPTED` 批任务的抢占状态。`NORMAL` 表示正常分发子任务；`PREEMPTED` 表示当前被同账号内更高优先级的批任务抢占，暂不分发新的子任务。 **completion_window** integer 必选 `示例值: 24` 批量任务的最大等待时间，单位小时。 **request_counts** RequestCounts 必选批任务请求数量统计。 **total** integer 必选 `示例值: 100` 请求总数。 **completed** integer 必选 `示例值: 80` 已完成请求数。 **failed** integer 必选 `示例值: 2` 失败请求数。 **terminated** integer 必选 `示例值: 0` 已终止请求数。 **create_time** string 必选 `示例值: 2026-07-13T03:10:11Z` 创建时间。 **stop_time** string 必选停止时间；任务未停止时为空字符串。 **end_time** string 必选结束时间；任务未结束时为空字符串。 **error_message** string 必选错误信息；没有错误时为空字符串。 **owner_id** integer 必选 `示例值: 12345678` 创建者 ID。 **total_count** integer 必选 `示例值: 1` 总记录数。 **max_results** integer 必选 `示例值: 10` 单次查询可返回的最大记录数。 **next_token** string 必选 `示例值: 0` 下一次查询起始 ID（不包含）或页码。 ### 请求示例 ```Bash # list curl --location "${BASE_URL}/api/v1/batch-task/list" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${API_KEY}" \ --data "{\n \"batch_task_ids\": [\"batch_001\", \"batch_002\"],\n \"batch_task_name\": \"demo\",\n \"statuses\": [\"QUEUED\", \"RUNNING\", \"FAILED\"],\n \"owner_ids\": [12345678],\n \"sort_order\": \"Desc\",\n \"sort_by\": \"update_time\",\n \"max_results\": 10,\n \"next_token\": \"0\"\n }" ``` ### 返回示例 ```JSON { "items": [ { "batch_task_id": "bt-1234567890", "name": "demo_batch_task", "description": "batch task demo", "output_tos_url": "tos://liuliu-test/batch_task_test/output/", "status": "RUNNING", "priority": "NORMAL", "preemptionState": "PREEMPTED", "completion_window": 24, "request_counts": { "total": 100, "completed": 80, "failed": 2, "terminated": 0 }, "create_time": "2026-07-13T03:10:11Z", "stop_time": "", "end_time": "", "error_message": "", "owner_id": 12345678 } ], "total_count": 1, "max_results": 10, "next_token": "0" } ``` ## 停止任务（stop）当需要终止执行时： 1. 调用 stop，传入 `batch_task_id`。 2. 任务会进入 `TERMINATING`，最终到 `TERMINATED`。 > **说明** > 如果任务已生成部分结果，建议仍按 `custom_id` 规则消费已产出的 `results.jsonl` / `errors.jsonl`。 ### 请求参数 |参数名称 |参数类型 |是否必须 |说明 | |---|---|---|---| |batch_task_id |String |是 |批任务 ID | ### 返回参数 |参数名 |参数类型 |参数描述 | |---|---|---| |batch_task_id |String |已接受停止操作的批任务 ID | ### 请求示例 ```Bash # stop curl --location "${BASE_URL}/api/v1/batch-task/stop" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${API_KEY}" \ --data "{\n \"batch_task_id\": \"${BATCH_TASK_ID}\"\n }" ``` ### 返回示例 ```JSON { "batch_task_id": "bt-1234567890" } ``` ## 重跑失败子任务（resume\-failed）当批任务中存在执行失败的子任务时，可调用 resume\-failed 接口重新执行失败子任务。已成功的子任务不会重复执行，失败子任务继续使用原 `custom_id` 与输入数据关联。对于 Lance 批任务，重跑结果按照 `lance_key_field` 指定的唯一键幂等写回对应行。 ### 请求参数 |参数名称 |参数类型 |是否必须 |说明 | |---|---|---|---| |batch_task_id |String |是 |需要重跑失败子任务的批任务 ID | ### 返回参数 |参数名 |参数类型 |参数描述 | |---|---|---| |batch_task_id |String |已接受失败子任务重跑操作的批任务 ID | ### 请求示例 ```Bash # resume-failed curl --location "${BASE_URL}/api/v1/batch-task/resume-failed" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${API_KEY}" \ --data "{\n \"batch_task_id\": \"${BATCH_TASK_ID}\"\n }" ``` ### 返回示例 ```JSON { "batch_task_id": "bt-1234567890" } ``` ## 更新任务元信息（update） update 用于更新批任务的元信息（如 name、description）。批任务创建后暂不支持修改 `priority`；重跑失败子任务时沿用原批任务的优先级。 ### 请求参数 |参数名称 |参数类型 |是否必须 |说明 | |---|---|---|---| |batch_task_id |String |是 |批任务 ID | |name |String |否 |批任务名称 | |description |String |否 |描述信息 | ### 返回参数 |参数名 |参数类型 |参数描述 | |---|---|---| |batch_task_id |String |批任务 ID | ### 请求示例 ```Bash # update curl --location "${BASE_URL}/api/v1/batch-task/update" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${API_KEY}" \ --data "{\n \"batch_task_id\": \"${BATCH_TASK_ID}\",\n \"name\": \"demo_batch_task_updated\",\n \"description\": \"updated description\"\n }" ``` ### 返回示例 ```JSON { "batch_task_id": "bt-1234567890" } ``` ## 删除任务（delete） delete 用于删除批任务（控制面操作），通常用于清理不再需要的任务记录。 ### 请求参数 |参数名称 |参数类型 |是否必须 |说明 | |---|---|---|---| |batch_task_id |String |是 |批任务 ID | ### 返回参数 |参数名 |参数类型 |参数描述 | |---|---|---| |batch_task_id |String |已接受删除操作的批任务 ID | ### 请求示例 ```Bash # delete curl --location "${BASE_URL}/api/v1/batch-task/delete" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${API_KEY}" \ --data "{\n \"batch_task_id\": \"${BATCH_TASK_ID}\"\n }" ``` ### 返回示例 ```JSON { "batch_task_id": "bt-1234567890" } ``` # 参考 ## 批任务状态参考 |status |含义 | |---|---| |QUEUED |批任务当前在排队中 | |INITIALIZING |初始化中（拆分 JSONL、读取 Lance 数据集等准备阶段） | |RUNNING |运行中（提交/回调/轮询/聚合） | |FAILED |批任务失败（系统级失败或达到停止条件），例如 TOS 路径不存在等 | |TERMINATING |终止中 | |TERMINATED |已终止 | |DELETING |删除中 | |DELETED |已删除 | ## 常见问题与异常处理 |现象 |可能原因 |处理建议 | |---|---|---| |任务失败（status=FAILED） |输入文件不可读、TOS 权限错误、持续超时等系统级失败 |检查 `input_tos_url` 是否可读、`output_tos_url` 是否可写；必要时重新创建任务。 | |部分子任务失败（`errors.jsonl` 有记录） |单行参数非法、资源不可达、业务侧失败等 |可调用 resume\-failed 接口重跑失败子任务；如需排查失败原因，可按 `errors.jsonl` 中的 `custom_id` 定位输入数据。 | |批任务状态为 `RUNNING`，但 `preemptionState=PREEMPTED` |同账号内存在更高优先级的非终态批任务，当前任务暂停分发新的子任务 |等待更高优先级任务进入终态后自动恢复。已提交的子任务仍会继续执行，无需重新创建当前任务。 | |Lance 请求校验不通过 |`lance_params` 缺少必填字段、唯一键列或映射字段不存在、映射格式不正确，或 Lance 数据集不可访问 |检查 `input_type`、`input_tos_url` 和 `lance_params`，并确认字段名称与 Lance 表结构一致。 | |Lance 任务初始化失败 |`lance_key_field` 对应列包含空值或重复值，或同一个 Lance 数据集已有活跃的写入任务 |检查唯一键列的数据完整性；等待已有任务结束后再重新提交。 |

AI 数据湖服务