批量接口是什么
批量接口（Batch API）是面向离线任务的异步通道：把请求写成 JSONL（每行一个请求，带唯一 custom_id）上传为文件，再用它创建批任务，平台在时限内完成（多数为 24 小时窗口），并普遍给出约五折的价格折扣。它用折扣换时效性，因此只适合标注、批量摘要、批量抽取与离线评测，不能放进用户等待的同步链路。结果按 custom_id 逐行对应，失败行可以单独重试。
基本信息
| 流程 | 上传 JSONL → 创建 batch → 轮询状态 → 下载结果 |
|---|---|
| 完成窗口 | 通常 24 小时，具体以厂商文档为准 |
| 价格 | 常见约五折，各厂商不同 |
| 适配任务 | 离线批量、可容忍延迟 |
| 不适用 | 实时交互、强时效链路 |
| 结果对齐 | 按 custom_id 逐行匹配 |
典型使用场景
- 语料打标：给历史工单、评论批量分类与打标签
- 批量摘要：把积压的长文档一次性生成摘要
- 离线评测：用大批量题目跑模型对比，成本只有实时调用的几分之一
- 数据抽取：对存量合同、票据做结构化字段抽取
- 内容改写：把旧文章批量改写成新风格，无需即时返回
批量任务全流程
批量任务全流程
# 1) 准备 JSONL：每行一个请求，custom_id 必须唯一且可追溯
# {"custom_id":"doc-0001","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"给这篇文档写三行摘要"}]}}
# 2) 上传输入文件并记下 file_id
curl -s https://api.openai.com/v1/files -H "Authorization: Bearer $OPENAI_API_KEY" -F purpose=batch -F file=@batch_input.jsonl
# 3) 创建批任务（引用上一步的 file_id）
curl -s https://api.openai.com/v1/batches -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d @batch_create.json
# 4) 按间隔轮询状态，完成后下载 output_file_id 对应结果并校验行数批任务状态机怎么读
| 状态 | 含义 | 该做什么 |
|---|---|---|
| validating | 输入文件校验中 | 等待；失败会产出错误文件 |
| in_progress | 处理中 | 按分钟级间隔轮询，避免高频打接口 |
| completed | 处理完成 | 下载结果文件，核对行数与失败行 |
| failed / expired | 失败或超时 | 看错误文件定位原因，必要时拆小重提 |
批处理不保证完成顺序，唯一可靠的对应关系是 custom_id。生成 custom_id 时就带上业务主键，结果回来才能直接落库。
提交前先用 10-20 行做小批试跑，确认请求体格式、模型标识与结果结构都正确，再提交整批，避免等满窗口才发现格式错误。