Claude Code 学习站

批处理策略

考点 4.5 · Batch processing · 所属域权重 20% · 提示工程与结构化输出

本页目录5

这个考点是什么

批处理策略考的是「什么时候该用 Message Batches API 而不是同步的 Messages API」这一取舍判断,以及批次部分失败后如何正确重提。

核心机制是:通过批量提交请求,所有 token 用量按标准同步 input/output 价格的 50% 计费,但代价是放弃实时性——请求异步处理,大多数批次在一小时内完成,但没有延迟 SLA,系统只承诺在全部请求完成、或 24 小时处理窗口耗尽(以先到者为准)后返回结果,届时仍未完成的请求会以 expired 状态收场。

结构上,单个批次的上限是 100,000 个请求或 256 MB,以先达到者为准;批内不支持流式返回,每个请求以非流式参数提交;每个请求必须带一个 custom_id,结果要靠这个 ID 而非提交顺序去对应——这是本考点里最容易被忽视、也最容易出错的一环,因为批处理结果不保证按提交顺序返回。

批次里每个请求最终落在四种终态之一:succeedederroredcanceledexpired。当部分请求失败时,正确做法是靠 custom_id 精确定位失败项,只把这些失败项重新打包成新批次重提,而不是重跑整批(白白重付已成功部分的费用),也不是不假思索地无脑重试(有些错误如请求本身格式/大小的问题,重试无法改变结果)。

为什么考

这一考点常见两类出题角度:一类是「批处理 API 客观参数」多选题(50% 折扣、24 小时处理窗口、单批次请求数/大小上限、不支持流式),考的是对官方文档细节的准确记忆,并会设置「适合低延迟实时对话」这类明显违背批处理定位的干扰项。

另一类更常见,是给出具体业务场景(CI 流水线里的阻塞检查 vs 隔夜报表、周度合规审计、大规模文档抽取),让考生判断「该不该批处理」以及「批次部分失败后怎么重提」,干扰项通常故意混淆「用 custom_id 精确重提失败项」与「按结果顺序位置对应」「重跑整个批次/子批次」「不区分错误类型无脑退避重试」这几种看似合理、实则会多花钱或选错文档的做法。

核心辨析

  1. 1

    批处理换来的是成本而非速度确定性

    50% 折扣的代价是没有延迟 SLA。要分清「大多数批次一小时内完成」是经验描述,「24 小时处理窗口」才是硬约束——超时未完成的请求以 expired 收场,而不是继续处理下去。因此批处理适合有充裕等待时间的任务(隔夜报表、周度审计),不适合需要立刻拿到结果的阻塞路径(如合并前检查)。

  2. 2

    custom_id 是重提时唯一可靠的对应依据,不能按响应在结果文件里出现的顺序或位置去匹配原始请求,因为批处理结果不保证按提交顺序返回。混淆这一点会导致把响应错配给错误的原始文档,重提对象也随之出错。

  3. 3

    四种终态(succeeded/errored/canceled/expired)对应的处理方式不同:

    • 只有服务端类 errored 和 expired 值得重提;

    • canceled 仅发生在主动取消尚未开始处理的请求上,不代表处理失败;

    • 而请求本身格式或内容有问题(比如输入超出上下文窗口)导致的错误,不会因为重试或退避而改变结果,必须先修正请求本身(如对超长文档分块)再重提。

  4. 4

    重提的粒度要精确到失败的单个请求,而不是重跑整个批次或整个子批次

    重跑已经 succeeded 的请求既重复计费又违背批处理省钱的初衷,是最容易丢分的一类干扰项。

  5. 5

    批处理不是无限规模的容器

    100,000 个请求或 256 MB(先达到者为准)的单批上限意味着超大规模任务要提前规划分批;批内也不支持流式,每个请求以非流式参数提交,这个限制常被误当成接口缺陷,其实是异步批处理架构的必然结果。

  6. 6

    当小样本测试暴露出较高比例的提示词失败或需要反复调整时,正确顺序是先在小样本上交互式迭代提示词、把首次通过率打磨到位,再把优化后的提示词一次性投入全量批处理,而不是带着未成熟的提示词直接批量跑、再大规模重提造成双倍开销。

反模式对照

常见做法

把有阻塞时效要求的流程(如合并前检查)也切到批处理去省成本

正确做法

只对没有实时性要求、有充裕等待窗口的任务(隔夜报表、周度审计)使用批处理,阻塞路径继续用同步调用

批处理没有延迟 SLA,只保证「全部完成或 24 小时到期,以先到者为准」才返回结果,用在阻塞路径上会让流程随时被卡住。

常见做法

批次部分失败后,按结果文件里的出现顺序去对应原始请求列表来定位失败项

正确做法

用每个请求自带的 custom_id 去匹配结果,精确定位哪些失败

批处理结果不保证按提交顺序返回,按位置对应会把响应错配给错误的文档,导致重提错误的对象。

常见做法

批次里出现失败就重跑整个批次或所在子批次

正确做法

只提取 custom_id 标记为失败的那部分请求,单独打包成新批次重提

重跑整批会对已经 succeeded 的请求重复计费,吃掉批处理本该省下的那部分成本。

常见做法

不区分错误类型,对所有 errored 请求一律做退避重试

正确做法

先看错误类型——请求本身的问题(如超长输入)要先修正(如分块)再重提,只对服务端类错误和 expired 做重试

请求格式或大小本身的问题不会因为等待或重试而消失,盲目退避只会浪费 24 小时处理窗口。

练这个考点