管理批处理任务

提交异步批量请求并查询批处理执行状态。

通过 OpenAI 兼容的 Batch API 跨受支持的模型接口提交异步批量处理请求。

POST/openai/v1/batches

请求体

字段类型必填说明
input_file_idstring是用途设为 batch 的已上传文件唯一标识符。
endpointstring是目标调用接口(/v1/chat/completions、/v1/completions、/v1/responses 或 /v1/embeddings)。
completion_windowstring是任务完成时间窗口,目前固定为 24h。
metadataobject否用于追踪与检索的可选键值对元数据。

输入文件必须为 UTF-8 编码的 JSONL 格式,单文件最多 50,000 条条目,文件体积上限为 200 MiB。每行必须为合法的 JSON 对象,包含唯一的非空 custom_id、值为 POST 的 method、与批处理 endpoint 一致的 url,以及对象类型的 body(针对严格的原生预付费批处理,body 中必须包含 model 字段)。针对原生预付费批处理,网关在资金准入前对存储文件校验和及各条目执行策略进行校验;各条目预扣额度在供应商派发前原子化提交。整体资金不足时返回 HTTP 402 且不执行部分派发。同一个批处理内无法拆分不兼容的供应商配置,且不执行条目级跨供应商故障转移。

批处理生命周期

GET/openai/v1/batches/{batch_id}
POST/openai/v1/batches/{batch_id}/cancel
  • validating:验证输入文件格式、JSONL 语法及条目数据规范。
  • in_progress:正在使用绑定的供应商凭据执行批量推理任务,不发生跨渠道漂移。
  • finalizing:汇总各条目推理产物并记录用量与账务结算凭据。
  • completed:批处理完成,生成 output_file_id 以及可选的 error_file_id。
  • failed:输入文件校验或批处理调度全局失败时记录的终止异常状态。
  • cancelling:收到取消请求,正在优雅终止处理并流转状态。
  • cancelled:批处理在全部完成前被主动终止。失败、取消或缺失的结果项不自动代表零上游成本;账务结算将保留预扣资金以待与供应商账单核对。AnyInt 中的规范状态标识为 cancelled。
  • expired:处理时间超出 24 小时完成窗口;未确认或运行中的执行项需依据供应商记录进行对账,不自动代表零上游成本。

批处理操作与结果下载

GET/openai/v1/batches
  • 列出批次:通过 GET /openai/v1/batches 查询当前授权组织或项目下的历史与活跃批处理任务。
  • 对象存储与下载:接收 purpose: "batch" 的文件上传与运行批处理任务依赖集群共享对象存储(OBJECT_STORE_MODE)。任务完成后,输出结果与错误 JSONL 文件可通过文件接口 GET /openai/v1/files/{file_id}/content 获取。

兼容路径

  • 网关兼容接收 /v1/batches 路径;建议新集成统一使用 /openai/v1/batches。