GPT-5.6 批处理 API — 24 小时内任务节省 50% 成本

什么是 Batch API

Batch API 是 OpenAI 提供的异步批量处理接口。它允许你：

• 提交一批 API 请求（最多 256K 条，或总大小 200MB）
• OpenAI 在 24 小时内 完成所有请求
• 完成后通知你或让你主动查询结果
• 输入和输出各节省 50%

成本节省对比

适合的场景

Batch API 适合非实时性的任务：

✅ 适合

• 批量文档总结
• 大规模数据标注
• 代码库批量审查
• 产品描述批量生成
• 客户支持历史分析
• 数据清洗和结构化提取
• A/B 测试模型提示词

❌ 不适合

• 实时对话（需要秒级响应）
• 用户交互过程中的 API 调用
• 必须快速迭代的开发任务
• 结果需要马上用于下游的生产流程

使用步骤

1. 准备批量请求文件

创建一个 .jsonl 文件（每行一个 JSON 对象）：

{"custom_id": "request-001", "method": "POST", "url": "/v1/responses", "body": {"model": "gpt-5.6-terra", "input": [{"role": "user", "content": "总结这段文本：..."}]}}
{"custom_id": "request-002", "method": "POST", "url": "/v1/responses", "body": {"model": "gpt-5.6-terra", "input": [{"role": "user", "content": "总结这段文本：..."}]}}
{"custom_id": "request-003", "method": "POST", "url": "/v1/responses", "body": {"model": "gpt-5.6-terra", "input": [{"role": "user", "content": "总结这段文本：..."}]}}

每个请求需要：

• custom_id：你的追踪 ID，用于结果映射
• method：固定 POST
• url：固定 /v1/responses
• body：标准的 Responses API 请求体

2. 提交批量任务

batch = client.batches.create(
    input_file_id="file-xxx",  # 先上传 jsonl 文件获取 file_id
    endpoint="/v1/responses",
    completion_window="24h"
)
print(batch.id)  # batch_xxx

3. 轮询进度

import time

while True:
    status = client.batches.retrieve(batch.id)
    print(f"状态: {status.status}, 完成: {status.request_counts.completed}/{status.request_counts.total}")
    
    if status.status in ("completed", "failed", "cancelled"):
        break
    
    time.sleep(60)  # 每分钟检查一次

4. 下载结果

if status.status == "completed":
    # 下载输出文件
    output_file = client.files.content(status.output_file_id)
    
    # 或者直接获取内容
    content = client.files.content(status.output_file_id).read()
    print(content.decode())

输出也是 .jsonl 格式，每行对应一个输入请求的结果。

完整示例

from openai import OpenAI
import json

client = OpenAI()

# 1. 准备批量输入
requests = [
    {"custom_id": f"task-{i}",
     "method": "POST",
     "url": "/v1/responses",
     "body": {
         "model": "gpt-5.6-luna",  # 高吞吐场景用 Luna
         "input": [{"role": "user", "content": text}],
         "reasoning": {"effort": "low"}
     }}
    for text in text_list  # 几千段待处理的文本
]

# 2. 写入 jsonl 文件
with open("batch_input.jsonl", "w") as f:
    for req in requests:
        f.write(json.dumps(req) + "\n")

# 3. 上传文件
with open("batch_input.jsonl", "rb") as f:
    file = client.files.create(file=f, purpose="batch")

# 4. 提交批量任务
batch = client.batches.create(
    input_file_id=file.id,
    endpoint="/v1/responses",
    completion_window="24h"
)

# 5. 等待完成（生产环境可以用 Webhook 通知）
while True:
    status = client.batches.retrieve(batch.id)
    if status.status == "completed":
        break
    time.sleep(60)

# 6. 下载和解析结果
results = client.files.content(status.output_file_id).read()
for line in results.decode().split("\n"):
    result = json.loads(line)
    print(result["custom_id"], result["response"]["output_text"])

限制和注意事项

24 小时窗口

Batch API 的 SLA 是 24 小时内完成。实际上 OpenAI 通常更快（数小时内），但不要指望秒级或分钟级。

请求数量限制

每个 batch 最多：

• 256,000 个请求
• 或 200MB 总大小
• 每个请求最多 64MB

错误处理

如果某个请求失败（如模型不可用、内容被拦截），不会影响其他请求。失败的请求会在结果中标记状态，你可以单独重试。

模型选择

Batch API 对所有 GPT-5.6 系列模型都可用。对于批量任务，推荐：

• Luna 做大规模轻量任务（最高吞吐、最低成本）
• Terra 做中等复杂度的批量任务
• Sol 做需要深度推理的批量分析

什么时候用 Batch API vs 标准 API

经验法则：如果任务可以等 1 小时以上，而且数量大于 100 个，一定用 Batch API。50% 的成本节省是实质性的。