OpenAI Batch API 怎样查询批处理任务状态

OpenAI Batch API 的任务状态查询，核心不是重新提交请求，而是保存创建批处理时返回的 batch_id，再调用 retrieve 接口读取 Batch 对象。重点看 status，同时结合 request_counts、output_file_id 和 error_file_id 判断是否可以继续轮询、读取结果或排查输入文件。

官方地址：https://developers.openai.com/api/docs/guides/batch

本文只讨论查询已有任务的状态，不重新创建 Batch，也不把输入文件 ID 当成批处理任务 ID。

先确认要查询的是 batch_id

创建 Batch 后，响应里的 id 才是后续查询对象，例如 batch_abc123。输入文件的 file-... 只用于提交批量请求；如果把它拼到批处理查询路径里，得到的就不是正确的任务对象。

一次状态查询返回的是完整 Batch 对象，而不是只有一个字符串。可以把它看成三组信息：任务当前阶段、请求处理计数、结果或错误文件引用。

用 retrieve 接口查询单个任务

查询单个任务的 REST 路径是 GET /v1/batches/{batch_id}。下面的 curl 示例只读取状态，不会改变任务，也不会触发取消操作。

# 把 batch_id 替换成创建 Batch 时返回的任务 ID
batch_id="batch_abc123"

# 只查询当前 Batch 对象，Authorization 使用环境变量中的密钥
curl "https://api.openai.com/v1/batches/${batch_id}" \
  -H "Authorization: Bearer ${OPENAI_API_KEY}" \
  -H "Content-Type: application/json"

如果使用 Python，可以把响应解析成字典，再只打印值班时真正关心的字段。示例中的异常处理用于区分网络/API 请求失败与 Batch 本身进入 failed 状态。

import os
from openai import OpenAI

# 从环境变量读取密钥，避免把凭据写进脚本
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
batch_id = "batch_abc123"

try:
    # retrieve 只读取已有任务，不会创建或取消 Batch
    batch = client.batches.retrieve(batch_id)
except Exception as exc:
    # 这里表示请求层失败，不能当成 Batch 的业务状态
    print(f"查询 Batch 请求失败：{exc}")
else:
    print(f"状态：{batch.status}")
    print(f"请求计数：{batch.request_counts}")
    print(f"输出文件：{batch.output_file_id}")
    print(f"错误文件：{batch.error_file_id}")

怎样解释 status 和 request_counts

status 是第一判断条件。validating 表示输入文件正在校验，in_progress 表示任务正在处理，finalizing 表示任务已完成处理但结果仍在准备；这三类状态通常继续按自己的轮询间隔查询即可。

completed 表示结果已经准备好，此时优先读取 output_file_id 对应的文件。failed 表示输入文件没有通过校验，expired 表示没有在 24 小时窗口内完成；这两类状态不应继续无条件轮询，应检查返回对象里的错误信息或输入文件。

cancelling 表示正在取消，cancelled 表示已经取消。取消期间可能需要等待正在执行的请求收尾，查询逻辑应记录状态变化，不要把它当成普通的 in_progress 重试。

request_counts 用来补充进度信息：它至少包含总请求数、已完成请求数和失败请求数。它适合写入日志或监控，但不能替代 status：即使失败计数为零，也要等状态变成 completed 后再读取输出文件。

按终态决定下一步

可以把处理策略压缩成下面这张表：

实际轮询器要保存上一次状态，只有状态变化或达到下一次查询时间才写日志。不要用短间隔无休止地打接口，也不要因为 request_counts.completed 增长就提前读取尚未准备好的输出文件。

常见问题

为什么查询时总是拿不到结果文件？

结果文件通常要等 status 变为 completed 后才可读取。中间态的 output_file_id 为空是正常现象，先保留任务 ID 并继续查询。

failed 和请求级失败是一回事吗？

不是。Batch 的 failed 通常表示批处理输入校验没有通过；即使 Batch 最终为 completed，其中某些请求仍可能在 request_counts.failed 中计数，后续还要按输出文件中的请求结果处理。

总结：保存好 batch_id，调用 GET /v1/batches/{batch_id}，先读 status 再读计数和文件字段。中间态继续查询，completed 读取输出，failed、expired 和取消态分别走对应的排障或收尾路径。