Batch Processing 是 Claude API 面向非实时任务的异步批处理能力。它适合一次性提交大量 Messages 请求，由后台异步处理，再统一下载结果。相比实时 API，它通常能以更低价格完成大规模任务。
什么任务适合 Batch？
适合：
- 批量翻译文章
- 批量摘要文档
- 内容分类与标签生成
- 离线评测模型输出
- 客服记录质检
- 数据清洗和结构化抽取
- 大规模 SEO 标题/摘要生成
不适合：
- 聊天机器人实时回复
- 用户正在等待的交互式请求
- 需要立即调用工具的 Agent 循环
- 强依赖请求之间顺序的任务
核心概念
一个 batch 由多个独立请求组成。每个请求通常包含：
custom_id：你自己的任务 ID，用来关联结果params：一次 Messages API 请求参数
提交后，服务端异步执行。你轮询 batch 状态，完成后下载结果。
请求结构示例
json
{
"requests": [
{
"custom_id": "article-001",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "Summarize this article..."
}
]
}
},
{
"custom_id": "article-002",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "Classify this support ticket..."
}
]
}
}
]
}custom_id 很重要。结果顺序不一定等于提交顺序，必须用它把输出写回自己的数据库。
结果处理
每条结果通常有三种情况：
- 成功：返回正常 message response
- 请求级失败：输入格式、上下文过长等问题
- 系统级失败：临时服务错误，需要重试
生产系统建议：
- 每个任务保存状态：pending/running/succeeded/failed
- 失败请求单独重试，不要整个 batch 重跑
- 把
custom_id设计成可追溯 ID，例如ticket_123_summary_v2 - 记录模型、Prompt 版本和输入 hash，便于复现
与 Prompt Caching 的组合
批量任务经常有大量共享上下文，比如同一套分类规则、同一份产品文档、同一批工具说明。
推荐：
- 把稳定规则放在请求前部
- 使用 Prompt Caching 缓存长上下文
- 每条任务只变化短输入
这样可以叠加批处理折扣和缓存收益。
成本控制建议
- 对任务按模型分层：简单分类用更便宜模型，复杂分析用更强模型
- 先抽样跑 100 条评估质量，再扩大到全量
- 限制
max_tokens，避免异常长输出 - 输出要求结构化，减少后处理成本
- 用
custom_id追踪每条任务的 token 用量
最佳实践清单
- 每条请求独立可重试
- 输入和 Prompt 版本都要可追溯
- 下载结果后立即持久化
- 对失败类型分类处理
- 批量任务不要依赖返回顺序
- 大任务拆成多个 batch，便于恢复和监控
来源：Anthropic 官方文档 - Batch processing | 整理：ClaudeEagle