第7章：消息批处理API

文档：消息批处理

7.1 概述

消息批处理API允许您提交批量请求进行异步处理：

属性	值
节省	与同步调用相比节省50%
处理窗口	最长24小时（无延迟SLA保证）
多轮工具调用	不支持（一个请求=一个响应）
关联	custom_id字段用于关联请求和响应

7.2 何时使用批处理API与同步API

任务	API	原因
合并前PR检查	同步	开发者在等待；24小时不可接受
隔夜技术债务报告	批处理	早上需要结果；节省50%
每周安全审计	批处理	不紧急；节省50%
交互式代码审查	同步	需要立即响应
处理10,000个文档	批处理	批量处理；节省显著

7.3 使用 custom_id

{
  "custom_id": "doc-invoice-2024-001",
  "params": {
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "从以下内容提取数据：..."}]
  }
}

custom_id 允许您：

• 将结果关联到原始文档
• 在失败时，仅重新提交失败的文档
• 避免重新处理成功的文档

7.4 处理批处理中的失败

1. 提交100个文档的批次
2. 95个成功；5个失败（超出上下文限制）
3. 通过custom_id识别失败项
4. 修改策略（例如，将长文档分割成块）
5. 仅重新提交5个失败的文档

7.5 SLA规划

如果您需要在30小时内得到结果，而批处理API最长需要24小时：

• 提交窗口：30 - 24 = 6小时
• 批次必须在截止时间前至少24小时提交
• 对于频繁提交，分割为4小时窗口

---