调用 OpenAI Batch API 处理批量文本任务时，最推荐的方式是将请求打包为 JSONL 文件并通过 Files API 上传，随后创建 Batch 任务异步执行。该方案适合非实时性的大规模数据处理场景，能有效降低网络开销并简化错误管理，但需注意任务执行存在延迟且不支持流式输出。

命令速用版

批量任务文件必须采用 JSONL 格式，每行一个 JSON 对象。以下是一个标准的请求文件示例：

{"custom_id": "task-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o", "messages": [{"role": "user", "content": "总结这段文本"}]}}
{"custom_id": "task-002", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o", "messages": [{"role": "user", "content": "分析情感倾向"}]}}

使用 Python SDK 提交任务的核心代码如下：

file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
batch = client.batches.create(input_file_id=file.id, endpoint="/v1/chat/completions", completion_window="24h")

为什么会这样

Batch API 的核心优势在于异步任务机制，系统将大量请求打包成单一任务进行调度。

传统串行请求需要客户端等待每个响应完成后才能发起下一个，网络延迟会线性累积。批量处理将请求上传后，服务端在后台排队处理，客户端无需维持长连接等待，从而显著减少网络开销和客户端资源占用。此外，单个请求失败不会影响整个任务，系统提供了集中的错误处理机制。

分步处理

实施批量处理主要分为准备数据、上传文件、创建任务和获取结果四个阶段。

第一步：准备任务数据

创建符合规范的 JSONL 格式文件，每行包含一个 API 请求。关键参数包括 custom_id（唯一标识符）、method（仅支持 POST）、url（API 端点）和 body（请求参数）。

第二步：上传任务文件

使用 OpenAI 客户端库的 Files 接口上传文件，purpose 参数必须设置为 batch。上传成功后会返回文件 ID。

第三步：创建批量任务

调用 Batches 接口，传入输入文件 ID、端点路径（如/v1/chat/completions）和处理时间窗口（如 24h）。

第四步：轮询与下载

定期检查任务状态，当状态变为 completed 后，通过输出文件 ID 下载结果文件。结果文件中包含每个 custom_id 对应的响应或错误信息。

怎么验证是否生效

任务提交后，通过检索批量任务接口查看 status 字段。

若 status 显示为 completed，表示任务已结束。下载输出文件后，检查文件中每一行的响应是否包含预期的 content 字段。若某行包含 error 对象，说明该特定请求失败，需根据错误码排查。

常见坑

1. 文件格式错误：文件必须是 UTF-8 编码的 JSONL，不能包含 BOM 标记，否则上传会失败。

2. custom_id 重复：每个请求的 custom_id 必须唯一，否则结果匹配时会发生冲突。

3. 超时设置：批量任务有处理时间窗口限制，超出窗口未完成的任务可能会被取消。

4. 实时性误解：Batch API 是异步的，不适合需要立即返回结果的聊天机器人前端。

常见问题

批量处理比单次调用便宜吗？

社区教程指出批量处理可能降低网络开销和 API 调用成本，但具体比例取决于任务类型和规模。

任务失败后怎么重试？

下载结果文件后，提取失败的请求行，修正错误后重新上传为新任务文件提交。

支持哪些模型？

支持大多数通过 Chat Completions 接口调用的模型，具体需在请求 body 中指定 model 参数。

参考来源

• 5 步掌握 OpenAI 批量处理：从效率瓶颈到性能突破
• Python 调用 OpenAI 兼容 API 批量处理文本教程：摘要、分类、标题生成
• OpenAI API 批量操作终极指南：快速提升 10 倍处理效率
• OpenAI-OpenAPI 批量操作指南：高效处理大量 API 请求