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 表的指定列。

术语

批任务（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，如果您希望提高子任务并发数，可提交工单联系技术支持人员，提高子任务并发度。

批任务的并发限制：默认 10

输入与输出规范

输入：input.jsonl

批任务以“文件驱动”的方式运行：您需要上传输入文件到 TOS，服务端负责拆分、编排、聚合。

细分	详细说明
格式规范	输入文件为 JSONL，每行是一个 JSON 对象（一个算子子任务）。以 PDF 算子为例： {"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：成功结果集合，每行是一个成功子任务的处理结果。 {"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：失败结果集合，每行是一个失败任务的失败返回。 {"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_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，用于结果审计和异常排查。

字段映射示例：

数组子字段映射

字段路径中的数组下标从 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 的参数结构。

准备工作

细分项	准备工作说明
获取 LAS API Key	提交批任务前，您需要先生成算子调用的API Key，并建议将API Key配置为环境变量，便于更安全地调用算子，详情请参见获取 API Key 并配置。
获取 BaseURL	提交批任务前，您需要先根据您当前使用的LAS服务所在地域，了解算子调用的BaseURL，用于配置算子调用路径参数取值。详情请参见获取 Base URL，下文中的调用示例仅作为参考，实际调用时需替换为您对应地域的路径取值。
规划输入与输出 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 输入示例

Lance 输入示例

返回示例

查询任务进度（get）

调用 get，并传入 batch_task_id。

关注返回的 status 与 request_counts（total/completed/failed/terminated）。

当任务进入终态后，结合 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。

请求示例

返回示例

列表查询（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（不包含）或页码。

请求示例

返回示例

停止任务（stop）

当需要终止执行时：

调用 stop，传入 batch_task_id。

任务会进入 TERMINATING，最终到 TERMINATED。

请求参数

参数名称	参数类型	是否必须	说明
batch_task_id	String	是	批任务 ID

返回参数

参数名	参数类型	参数描述
batch_task_id	String	已接受停止操作的批任务 ID

请求示例

返回示例

重跑失败子任务（resume-failed）

当批任务中存在执行失败的子任务时，可调用 resume-failed 接口重新执行失败子任务。已成功的子任务不会重复执行，失败子任务继续使用原 custom_id 与输入数据关联。对于 Lance 批任务，重跑结果按照 lance_key_field 指定的唯一键幂等写回对应行。

请求参数

参数名称	参数类型	是否必须	说明
batch_task_id	String	是	需要重跑失败子任务的批任务 ID

返回参数

参数名	参数类型	参数描述
batch_task_id	String	已接受失败子任务重跑操作的批任务 ID

请求示例

返回示例

更新任务元信息（update）

update 用于更新批任务的元信息（如 name、description）。批任务创建后暂不支持修改 priority；重跑失败子任务时沿用原批任务的优先级。

请求参数

参数名称	参数类型	是否必须	说明
batch_task_id	String	是	批任务 ID
name	String	否	批任务名称
description	String	否	描述信息

返回参数

参数名	参数类型	参数描述
batch_task_id	String	批任务 ID

请求示例

返回示例

删除任务（delete）

delete 用于删除批任务（控制面操作），通常用于清理不再需要的任务记录。

请求参数

参数名称	参数类型	是否必须	说明
batch_task_id	String	是	批任务 ID

返回参数

参数名	参数类型	参数描述
batch_task_id	String	已接受删除操作的批任务 ID

请求示例

返回示例

参考

批任务状态参考

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 数据湖服务