Claude 的批量处理是开发者从跑通一次调用走向稳定自动化时最先遇到的一道坎。单独发一条请求返回慢一点、报个错手动重试一次就行但当你面对几百条、几千条待处理文本或者要让模型批量完成分类、改写、抽取、摘要这些任务整套逻辑就会从“模型能不能答对”变成“脚本能不能跑完、结果能不能对上、失败能不能恢复”。这篇是 Zero to Claude Certified Architect 系列的批量处理部分适合已经能完成单次 Claude API 调用、但还没系统设计过批量的开发者。我会把批量处理拆成三种做法给出从最小请求到批量循环、再到异步批处理和排错的完整路径。先说明一个容易混淆的点Claude 批量处理不是一个单一功能。不同任务、不同规模、不同实时性要求对应完全不同的方案。选错方案后面所有优化都是在错误方向上打补丁。1. 先分清你要做的是请求批量、任务自动化还是异步批处理1.1 三种做法适用场景完全不同Claude 相关开发里常说的“批量处理”至少包含三种不能混为一谈。第一种是同步批量请求。脚本按顺序或并发地调用 API一条一条拿结果。适合几十到几百条、结果需要立刻使用的场景。开发成本最低逻辑也最直观。第二种是异步批处理。把大量请求统一打包提交给服务端由服务端排队处理客户端拿到批次 ID 后轮询状态最后统一取结果。适合几千条以上、允许等待几十分钟甚至几小时的场景。它的核心优势不是快而是稳定和省事。第三种是任务自动化。把多步骤、需要读写文件、可能调用工具的流程写成一个任务脚本交给命令行工具或自己的编排代码执行。适合的不只是“发一段文本拿一段输出”而是需要操作文件、执行命令、串联多个模型调用的复杂任务。三者之间的选择依据其实很直接任务量多大、是不是要实时返回、单条任务是否只是纯模型调用。1.2 判断标准任务量、实时性和复杂度我常用的判断顺序是这样的任务量在几百条以内实时性要求高直接写同步批量循环。任务量上千且不要求立刻拿到全部结果优先考虑异步批处理。任务不只是一次模型调用而是需要读文件、写文件、跑多步、甚至调用其他工具那就该用任务自动化或者自己写流程编排。一个很常见的误区是默认所有批量都要靠并发拉满来缩短时间。实际上对几千条任务来说稳定性和可恢复性远比瞬时速度重要。跑完一半崩掉比跑得慢但一次成功更让人头疼。1.3 为什么顺序很重要很多新手一上来就写 for 循环把全部任务一次性发出去跑到一半遇到限流前面的结果也没落盘等于白跑。正确顺序是单条跑通小批量验证再全量提交。每一步都要有明确的验证标准而不是只看“有没有报错”。2. 环境准备先跑通最小请求再谈循环2.1 需要准备什么批量处理不是一个独立的工具它建立在 API 调用的基础上所以环境准备和单次请求完全一致只是要求更高。首先是 API Key。建议放到环境变量里不要写死在代码和仓库里。其次是 Python 环境建议 3.9 以上安装官方 SDK或者直接用 requests 调用 HTTP 接口。再次是网络确保运行环境能正常访问对应的 API 服务。最后是本地磁盘批量结果要落盘日志和结果文件分开放预留足够空间。安装依赖的命令很简单pip install anthropic环境变量在 Linux 或 macOS 下可以这样设置export ANTHROPIC_API_KEY你的_API_KEYWindows 下放到用户环境变量设置完记得重开终端。2.2 最小请求长什么样批量循环之前我永远先跑通一个最小请求。这是最省时间的做法因为批量代码里的大部分 Bug其实都能在单条请求里提前暴露。from anthropic import Anthropic client Anthropic() # 默认读取 ANTHROPIC_API_KEY 环境变量 resp client.messages.create( modelMODEL_NAME, # 换成你的账号实际可用的模型 ID max_tokens1024, messages[ {role: user, content: 请用一句话解释什么是批处理。} ], ) print(resp.content[0].text)这里有两个新手容易踩的坑。第一个模型 ID 必须和账号可用模型对上不同版本、不同权限下可用的 ID 不完全一样。第二个SDK 版本不同时响应对象结构可能略有差异。先打印一下 resp 看看结构再写解析逻辑不要想当然。2.3 命令行工具报“无法识别”先查环境变量和 PATH很多人想在终端里运行 claude 相关命令结果报“无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”或者“claude 不是内部或外部命令”。这类错误的本质是命令没有加入 PATH或者安装没有真正完成不是模型本身的问题。处理顺序是这样的重开终端让环境变量重新加载。确认命令行工具的实际安装路径把它加入系统 PATH。输入带版本参数的命令验证能输出版本号就说明安装成功。Windows PowerShell 下最容易出现这个问题因为新装的全局命令经常要在重启终端后才能生效。先做这一步不要急着怀疑模型配置。2.4 先单条验证再谈批量最小请求跑通之后我会先用一小批 5 到 10 条数据做冒烟测试。看三件事输入能不能被正确读取输出能不能正常解析日志能不能清楚记录每一条的成功失败。这三件事任何一个没做好批量放大后都会被无限放大。3. 同步批量循环并发、重试、落盘是关键3.1 一个能落盘的顺序循环不要只在内存里攒结果最后一次性写文件。批量任务一旦中途崩溃前面的结果就全丢了。更稳妥的做法是每处理完一条就追加写入一行 JSONLimport json from anthropic import Anthropic client Anthropic() def process_one(item): resp client.messages.create( modelMODEL_NAME, max_tokens1024, messages[{role: user, content: item[prompt]}], ) return {id: item[id], result: resp.content[0].text} with open(results.jsonl, a, encodingutf-8) as f: for item in test_items: try: r process_one(item) f.write(json.dumps(r, ensure_asciiFalse) \n) f.flush() except Exception as e: print(ftask {item[id]} failed: {e})为什么这样写因为 flush 之后即使脚本中断已处理的结果仍然存在。下次可以从尚未完成的 ID 继续而不需要从头再来。对批量任务来说“能断点续跑”比“单次跑得飞快”重要得多。3.2 并发要加上限不要一上来拉满顺序循环的缺点是慢尤其是每条约需要几秒时几百条就会拖很久。于是很多人会引入线程池或异步并发。这一步本身没错但要注意两点第一并发数不是越大越好第二API 服务有速率限制超过后会有 429 限流或 529 服务过载之类的响应。我建议从 2 到 4 个并发开始跑观察稳定后再慢慢加。对纯文本摘要这类轻任务常规环境里 4 到 8 个并发通常已经够用如果每条任务本身就很重并发反而会让响应变慢、超时变多。from concurrent.futures import ThreadPoolExecutor, as_completed with ThreadPoolExecutor(max_workers4) as pool: futures [pool.submit(process_one, item) for item in test_items] for future in as_completed(futures): r future.result() # 每拿到一条结果就写入文件并记录状态不要一上来就把并发调到 20、30。原因很简单批量任务最怕的不是慢而是被限流后陷入大量重试最后把系统资源耗在失败请求上。3.3 重试和退避面对限流的基本操作批量跑的时候偶尔出现 529 或网络抖动非常正常。正确的处理是给每个请求设置超时并且做有限次数的指数退避重试import time def call_with_retry(item, max_retries4, base_delay2): for attempt in range(max_retries): try: resp client.messages.create( modelMODEL_NAME, max_tokens1024, messages[{role: user, content: item[prompt]}], ) return resp.content[0].text except Exception as e: if attempt max_retries - 1: raise time.sleep(base_delay * (2 ** attempt))第一次失败后等 2 秒第二次等 4 秒第三次等 8 秒。这样既给了服务端恢复时间也不会因为反复重试把限流状态越搞越严重。注意重试次数不能无限大超过上限就应该把任务标记为失败写进日志最后统一人工处理。3.4 关键参数建议参数建议初始值说明并发数2-4稳定后再调大不要一开始就给满单次超时30-120 秒根据模型响应速度和 max_tokens 调整重试次数3-5超过就标记失败别死循环退避基础间隔2 秒指数增长避免瞬时恢复单批测试条数5-10 条先验证输入输出和日志4. 大规模任务用异步批处理重点是可恢复4.1 异步批处理是怎么工作的当任务量到几千条以上还一条一条同步请求就不太划算了。异步批处理的思路是把请求统一打包提交服务端排队处理客户端拿到一个批次 ID过一段时间再查状态等所有任务完成后统一导出结果。整个过程不需要保持长连接也不需要在本地持续占用资源。这类接口通常要求请求按 JSONL 格式提供每条包含一个唯一 ID 和完整的调用参数。例如{custom_id: task_0001, model: MODEL_NAME, max_tokens: 1024, messages: [{role: user, content: 第一段要处理的文本}]} {custom_id: task_0002, model: MODEL_NAME, max_tokens: 1024, messages: [{role: user, content: 第二段要处理的文本}]}具体字段名和请求格式要以你使用的接口文档为准这里给的是通用约定。异步批处理通常会把实时性换成更低的成本或更高的吞吐适合非交互式场景但价格和时效要以官方文档为准。4.2 提交、查询、导出三步走流程一般是这样构造任务文件。给每条任务一个唯一 ID确保输出能和输入对上。提交批次。拿到批次 ID把它存在本地文件里。轮询状态。每隔一段时间查一次直到批次完成或失败。导出结果。按批次 ID 拉取结果再按任务 ID 合并回原始数据。这里最核心的一点是批次 ID 是唯一凭证。一定要把它连同提交时间、任务数一起记录下来。脚本崩溃了、机器重启了靠批次 ID 还能继续查结果而不是重新提交一遍。4.3 什么时候不要用异步批处理异步批处理不是万能的。如果任务量很小、结果要立刻返回或者需求方在等结果做下一步判断那就应该用同步请求。另外如果只是几十条数据提交批次、轮询、导出的开发成本可能比直接跑循环还高没必要硬上异步。判断标准很简单能不能接受从几分钟到几十分钟的等待时间。能接受且任务量大异步划算不能接受就同步。4.4 断点恢复设计不管用哪种方式我都建议在本地维护一个处理清单记录每条任务的 ID 和状态pending、done、failed。每次启动脚本时先读取清单只处理 pending 和 failed。这样即使中途断电也能从断点继续而不是从头重跑。5. 输出组织和验证批量处理最容易翻车的地方5.1 结果验证不能只看有没有返回批量任务最常见的翻车方式不是报错而是“看起来成功了实际结果不对”。我总结了一个验证清单每条结果是否都有对应输入 ID顺序错乱时能不能还原。输出是否为空字符串是否为固定重复的句子。是否被截断。max_tokens 不够时输出会在中间断掉。格式是否符合预期。要 JSON 输出时是否真的返回了可解析的 JSON。失败任务是否都进了日志而不是被静默吞掉。检查顺序也很重要先看失败率再看重复率最后抽查内容质量。失败率异常时先别急着调模型参数大概率是输入或环境问题。5.2 成本和 Token 估算批量跑之前先估算成本否则结果出来账单可能吓一跳。估算方式不复杂取一小批样例统计输入 token 和输出 token 的平均值乘上任务总数再乘上对应模型的价格。注意两个坑中文内容的 token 统计和英文不一样max_tokens 设置过大时即使实际输出短也会影响计费和响应耗时。我一般会在代码里记录每个任务的 input_tokens 和 output_tokens写入结果文件。这样跑完可以直接统计总量也能发现哪些任务异常消耗 token比如某条输入特别长导致成本偏高。5.3 输出文件命名和目录规划批量跑几次之后最让人头疼的不是代码而是文件混乱。建议从一开始就固定目录结构batch_20250101_1200/ input.jsonl results.jsonl failed.jsonl logs/每次运行使用独立目录文件名带上时间戳。这样后续想复现、排查、对比都方便。这里不用追求特别复杂的调度系统先把命名和落盘做好。5.4 给脚本加停止条件给脚本加一个停止条件统计当前失败率如果连续失败超过阈值就暂停而不是继续硬跑。也建议先跑一个小批次用实际 token 消耗反推总成本再决定是否全量执行。这些不是功能需求但批量任务里它们比模型参数更影响落地体验。6. 常见报错与排查顺序先看现象再看配置6.1 高频报错对照结合日常开发中经常被问到的报错我整理了一个排查对照表报错或现象常见原因优先排查点无法将 claude 项识别为 cmdlet / 不是内部或外部命令命令未加入 PATH或安装未完成重开终端检查安装路径验证版本参数... is not a model this version of claude code recognizes配置中的模型名和当前版本不匹配打开配置文件核对模型 ID 和版本兼容情况529 / overloaded服务端负载高或触发限流指数退避重试降低并发错峰执行Failed to start Claudes workspace工作目录权限、配置文件路径、磁盘空间检查工作区目录权限和配置路径请求一直超时网络不稳定或单次调用过重先看日志确认耗时再调超时和重试输出为空或重复输入格式问题、模型参数问题、结果解析问题先打印原始响应再排查输入和解析6.2 通用排查顺序遇到批量任务出问题我建议按这个顺序查不要一上来就改模型参数看现象。是报错、卡住还是输出不对。看日志。最近一条失败任务的完整错误是什么。看输入。文本编码、格式、路径、任务 ID 是否完整。看环境。依赖版本、API Key 是否有效、目录权限、磁盘空间。看参数。并发数、重试次数、超时、max_tokens 是否合理。看工具版本。SDK 或命令行工具的版本是否和配置项匹配。这里面最容易误判的是把配置问题当成模型问题。比如模型名不识别大多数情况是配置文件里的模型 ID 和当前版本不一致或者配置的模型名写法不被当前工具版本认可。先想到配置而不是怀疑模型能力。6.3 账号和权限问题单独处理如果报错里出现 organization、subscription、access 这样的关键词说明问题不是脚本代码而是账号或组织权限。这时候不需要改代码应该确认订阅状态、组织策略、API Key 权限以及当前命令或接口是否被组织限制。这类问题在本地重试多少次都是一样的结果先找对层面再决定是联系管理员还是调整权限配置。6.4 从能跑到稳定的三个习惯最后说三个让批量任务稳定的小习惯。第一每次只改一个参数。跑完看结果再改下一个避免同时动并发、模型、超时出了问题没法定位。第二任务清单和结果文件分开保存处理状态必须可查。哪怕只是本地文本文件也比全靠内存强。第三跑大批量之前用小样本完整走一遍提交、轮询、导出、校验的流程确认没有问题再放量。批量处理真正的难点从来不是把请求发出去而是让几千条任务在有限时间内稳定跑完并且每一条的结果都能对上输入。如果你刚开始接触先把单条请求、顺序循环、小批量测试这三步做扎实等任务量真的上来了再引入异步批处理、断点恢复和成本统计。踩过几次坑之后你会发现很多批量任务失败的根源不是模型能力不够而是输入没清理、输出没落盘、失败没记录。把这几个基础问题解决掉批量处理就成功了一大半。
Claude批量处理实战：从同步循环到异步批处理
Claude 的批量处理是开发者从跑通一次调用走向稳定自动化时最先遇到的一道坎。单独发一条请求返回慢一点、报个错手动重试一次就行但当你面对几百条、几千条待处理文本或者要让模型批量完成分类、改写、抽取、摘要这些任务整套逻辑就会从“模型能不能答对”变成“脚本能不能跑完、结果能不能对上、失败能不能恢复”。这篇是 Zero to Claude Certified Architect 系列的批量处理部分适合已经能完成单次 Claude API 调用、但还没系统设计过批量的开发者。我会把批量处理拆成三种做法给出从最小请求到批量循环、再到异步批处理和排错的完整路径。先说明一个容易混淆的点Claude 批量处理不是一个单一功能。不同任务、不同规模、不同实时性要求对应完全不同的方案。选错方案后面所有优化都是在错误方向上打补丁。1. 先分清你要做的是请求批量、任务自动化还是异步批处理1.1 三种做法适用场景完全不同Claude 相关开发里常说的“批量处理”至少包含三种不能混为一谈。第一种是同步批量请求。脚本按顺序或并发地调用 API一条一条拿结果。适合几十到几百条、结果需要立刻使用的场景。开发成本最低逻辑也最直观。第二种是异步批处理。把大量请求统一打包提交给服务端由服务端排队处理客户端拿到批次 ID 后轮询状态最后统一取结果。适合几千条以上、允许等待几十分钟甚至几小时的场景。它的核心优势不是快而是稳定和省事。第三种是任务自动化。把多步骤、需要读写文件、可能调用工具的流程写成一个任务脚本交给命令行工具或自己的编排代码执行。适合的不只是“发一段文本拿一段输出”而是需要操作文件、执行命令、串联多个模型调用的复杂任务。三者之间的选择依据其实很直接任务量多大、是不是要实时返回、单条任务是否只是纯模型调用。1.2 判断标准任务量、实时性和复杂度我常用的判断顺序是这样的任务量在几百条以内实时性要求高直接写同步批量循环。任务量上千且不要求立刻拿到全部结果优先考虑异步批处理。任务不只是一次模型调用而是需要读文件、写文件、跑多步、甚至调用其他工具那就该用任务自动化或者自己写流程编排。一个很常见的误区是默认所有批量都要靠并发拉满来缩短时间。实际上对几千条任务来说稳定性和可恢复性远比瞬时速度重要。跑完一半崩掉比跑得慢但一次成功更让人头疼。1.3 为什么顺序很重要很多新手一上来就写 for 循环把全部任务一次性发出去跑到一半遇到限流前面的结果也没落盘等于白跑。正确顺序是单条跑通小批量验证再全量提交。每一步都要有明确的验证标准而不是只看“有没有报错”。2. 环境准备先跑通最小请求再谈循环2.1 需要准备什么批量处理不是一个独立的工具它建立在 API 调用的基础上所以环境准备和单次请求完全一致只是要求更高。首先是 API Key。建议放到环境变量里不要写死在代码和仓库里。其次是 Python 环境建议 3.9 以上安装官方 SDK或者直接用 requests 调用 HTTP 接口。再次是网络确保运行环境能正常访问对应的 API 服务。最后是本地磁盘批量结果要落盘日志和结果文件分开放预留足够空间。安装依赖的命令很简单pip install anthropic环境变量在 Linux 或 macOS 下可以这样设置export ANTHROPIC_API_KEY你的_API_KEYWindows 下放到用户环境变量设置完记得重开终端。2.2 最小请求长什么样批量循环之前我永远先跑通一个最小请求。这是最省时间的做法因为批量代码里的大部分 Bug其实都能在单条请求里提前暴露。from anthropic import Anthropic client Anthropic() # 默认读取 ANTHROPIC_API_KEY 环境变量 resp client.messages.create( modelMODEL_NAME, # 换成你的账号实际可用的模型 ID max_tokens1024, messages[ {role: user, content: 请用一句话解释什么是批处理。} ], ) print(resp.content[0].text)这里有两个新手容易踩的坑。第一个模型 ID 必须和账号可用模型对上不同版本、不同权限下可用的 ID 不完全一样。第二个SDK 版本不同时响应对象结构可能略有差异。先打印一下 resp 看看结构再写解析逻辑不要想当然。2.3 命令行工具报“无法识别”先查环境变量和 PATH很多人想在终端里运行 claude 相关命令结果报“无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”或者“claude 不是内部或外部命令”。这类错误的本质是命令没有加入 PATH或者安装没有真正完成不是模型本身的问题。处理顺序是这样的重开终端让环境变量重新加载。确认命令行工具的实际安装路径把它加入系统 PATH。输入带版本参数的命令验证能输出版本号就说明安装成功。Windows PowerShell 下最容易出现这个问题因为新装的全局命令经常要在重启终端后才能生效。先做这一步不要急着怀疑模型配置。2.4 先单条验证再谈批量最小请求跑通之后我会先用一小批 5 到 10 条数据做冒烟测试。看三件事输入能不能被正确读取输出能不能正常解析日志能不能清楚记录每一条的成功失败。这三件事任何一个没做好批量放大后都会被无限放大。3. 同步批量循环并发、重试、落盘是关键3.1 一个能落盘的顺序循环不要只在内存里攒结果最后一次性写文件。批量任务一旦中途崩溃前面的结果就全丢了。更稳妥的做法是每处理完一条就追加写入一行 JSONLimport json from anthropic import Anthropic client Anthropic() def process_one(item): resp client.messages.create( modelMODEL_NAME, max_tokens1024, messages[{role: user, content: item[prompt]}], ) return {id: item[id], result: resp.content[0].text} with open(results.jsonl, a, encodingutf-8) as f: for item in test_items: try: r process_one(item) f.write(json.dumps(r, ensure_asciiFalse) \n) f.flush() except Exception as e: print(ftask {item[id]} failed: {e})为什么这样写因为 flush 之后即使脚本中断已处理的结果仍然存在。下次可以从尚未完成的 ID 继续而不需要从头再来。对批量任务来说“能断点续跑”比“单次跑得飞快”重要得多。3.2 并发要加上限不要一上来拉满顺序循环的缺点是慢尤其是每条约需要几秒时几百条就会拖很久。于是很多人会引入线程池或异步并发。这一步本身没错但要注意两点第一并发数不是越大越好第二API 服务有速率限制超过后会有 429 限流或 529 服务过载之类的响应。我建议从 2 到 4 个并发开始跑观察稳定后再慢慢加。对纯文本摘要这类轻任务常规环境里 4 到 8 个并发通常已经够用如果每条任务本身就很重并发反而会让响应变慢、超时变多。from concurrent.futures import ThreadPoolExecutor, as_completed with ThreadPoolExecutor(max_workers4) as pool: futures [pool.submit(process_one, item) for item in test_items] for future in as_completed(futures): r future.result() # 每拿到一条结果就写入文件并记录状态不要一上来就把并发调到 20、30。原因很简单批量任务最怕的不是慢而是被限流后陷入大量重试最后把系统资源耗在失败请求上。3.3 重试和退避面对限流的基本操作批量跑的时候偶尔出现 529 或网络抖动非常正常。正确的处理是给每个请求设置超时并且做有限次数的指数退避重试import time def call_with_retry(item, max_retries4, base_delay2): for attempt in range(max_retries): try: resp client.messages.create( modelMODEL_NAME, max_tokens1024, messages[{role: user, content: item[prompt]}], ) return resp.content[0].text except Exception as e: if attempt max_retries - 1: raise time.sleep(base_delay * (2 ** attempt))第一次失败后等 2 秒第二次等 4 秒第三次等 8 秒。这样既给了服务端恢复时间也不会因为反复重试把限流状态越搞越严重。注意重试次数不能无限大超过上限就应该把任务标记为失败写进日志最后统一人工处理。3.4 关键参数建议参数建议初始值说明并发数2-4稳定后再调大不要一开始就给满单次超时30-120 秒根据模型响应速度和 max_tokens 调整重试次数3-5超过就标记失败别死循环退避基础间隔2 秒指数增长避免瞬时恢复单批测试条数5-10 条先验证输入输出和日志4. 大规模任务用异步批处理重点是可恢复4.1 异步批处理是怎么工作的当任务量到几千条以上还一条一条同步请求就不太划算了。异步批处理的思路是把请求统一打包提交服务端排队处理客户端拿到一个批次 ID过一段时间再查状态等所有任务完成后统一导出结果。整个过程不需要保持长连接也不需要在本地持续占用资源。这类接口通常要求请求按 JSONL 格式提供每条包含一个唯一 ID 和完整的调用参数。例如{custom_id: task_0001, model: MODEL_NAME, max_tokens: 1024, messages: [{role: user, content: 第一段要处理的文本}]} {custom_id: task_0002, model: MODEL_NAME, max_tokens: 1024, messages: [{role: user, content: 第二段要处理的文本}]}具体字段名和请求格式要以你使用的接口文档为准这里给的是通用约定。异步批处理通常会把实时性换成更低的成本或更高的吞吐适合非交互式场景但价格和时效要以官方文档为准。4.2 提交、查询、导出三步走流程一般是这样构造任务文件。给每条任务一个唯一 ID确保输出能和输入对上。提交批次。拿到批次 ID把它存在本地文件里。轮询状态。每隔一段时间查一次直到批次完成或失败。导出结果。按批次 ID 拉取结果再按任务 ID 合并回原始数据。这里最核心的一点是批次 ID 是唯一凭证。一定要把它连同提交时间、任务数一起记录下来。脚本崩溃了、机器重启了靠批次 ID 还能继续查结果而不是重新提交一遍。4.3 什么时候不要用异步批处理异步批处理不是万能的。如果任务量很小、结果要立刻返回或者需求方在等结果做下一步判断那就应该用同步请求。另外如果只是几十条数据提交批次、轮询、导出的开发成本可能比直接跑循环还高没必要硬上异步。判断标准很简单能不能接受从几分钟到几十分钟的等待时间。能接受且任务量大异步划算不能接受就同步。4.4 断点恢复设计不管用哪种方式我都建议在本地维护一个处理清单记录每条任务的 ID 和状态pending、done、failed。每次启动脚本时先读取清单只处理 pending 和 failed。这样即使中途断电也能从断点继续而不是从头重跑。5. 输出组织和验证批量处理最容易翻车的地方5.1 结果验证不能只看有没有返回批量任务最常见的翻车方式不是报错而是“看起来成功了实际结果不对”。我总结了一个验证清单每条结果是否都有对应输入 ID顺序错乱时能不能还原。输出是否为空字符串是否为固定重复的句子。是否被截断。max_tokens 不够时输出会在中间断掉。格式是否符合预期。要 JSON 输出时是否真的返回了可解析的 JSON。失败任务是否都进了日志而不是被静默吞掉。检查顺序也很重要先看失败率再看重复率最后抽查内容质量。失败率异常时先别急着调模型参数大概率是输入或环境问题。5.2 成本和 Token 估算批量跑之前先估算成本否则结果出来账单可能吓一跳。估算方式不复杂取一小批样例统计输入 token 和输出 token 的平均值乘上任务总数再乘上对应模型的价格。注意两个坑中文内容的 token 统计和英文不一样max_tokens 设置过大时即使实际输出短也会影响计费和响应耗时。我一般会在代码里记录每个任务的 input_tokens 和 output_tokens写入结果文件。这样跑完可以直接统计总量也能发现哪些任务异常消耗 token比如某条输入特别长导致成本偏高。5.3 输出文件命名和目录规划批量跑几次之后最让人头疼的不是代码而是文件混乱。建议从一开始就固定目录结构batch_20250101_1200/ input.jsonl results.jsonl failed.jsonl logs/每次运行使用独立目录文件名带上时间戳。这样后续想复现、排查、对比都方便。这里不用追求特别复杂的调度系统先把命名和落盘做好。5.4 给脚本加停止条件给脚本加一个停止条件统计当前失败率如果连续失败超过阈值就暂停而不是继续硬跑。也建议先跑一个小批次用实际 token 消耗反推总成本再决定是否全量执行。这些不是功能需求但批量任务里它们比模型参数更影响落地体验。6. 常见报错与排查顺序先看现象再看配置6.1 高频报错对照结合日常开发中经常被问到的报错我整理了一个排查对照表报错或现象常见原因优先排查点无法将 claude 项识别为 cmdlet / 不是内部或外部命令命令未加入 PATH或安装未完成重开终端检查安装路径验证版本参数... is not a model this version of claude code recognizes配置中的模型名和当前版本不匹配打开配置文件核对模型 ID 和版本兼容情况529 / overloaded服务端负载高或触发限流指数退避重试降低并发错峰执行Failed to start Claudes workspace工作目录权限、配置文件路径、磁盘空间检查工作区目录权限和配置路径请求一直超时网络不稳定或单次调用过重先看日志确认耗时再调超时和重试输出为空或重复输入格式问题、模型参数问题、结果解析问题先打印原始响应再排查输入和解析6.2 通用排查顺序遇到批量任务出问题我建议按这个顺序查不要一上来就改模型参数看现象。是报错、卡住还是输出不对。看日志。最近一条失败任务的完整错误是什么。看输入。文本编码、格式、路径、任务 ID 是否完整。看环境。依赖版本、API Key 是否有效、目录权限、磁盘空间。看参数。并发数、重试次数、超时、max_tokens 是否合理。看工具版本。SDK 或命令行工具的版本是否和配置项匹配。这里面最容易误判的是把配置问题当成模型问题。比如模型名不识别大多数情况是配置文件里的模型 ID 和当前版本不一致或者配置的模型名写法不被当前工具版本认可。先想到配置而不是怀疑模型能力。6.3 账号和权限问题单独处理如果报错里出现 organization、subscription、access 这样的关键词说明问题不是脚本代码而是账号或组织权限。这时候不需要改代码应该确认订阅状态、组织策略、API Key 权限以及当前命令或接口是否被组织限制。这类问题在本地重试多少次都是一样的结果先找对层面再决定是联系管理员还是调整权限配置。6.4 从能跑到稳定的三个习惯最后说三个让批量任务稳定的小习惯。第一每次只改一个参数。跑完看结果再改下一个避免同时动并发、模型、超时出了问题没法定位。第二任务清单和结果文件分开保存处理状态必须可查。哪怕只是本地文本文件也比全靠内存强。第三跑大批量之前用小样本完整走一遍提交、轮询、导出、校验的流程确认没有问题再放量。批量处理真正的难点从来不是把请求发出去而是让几千条任务在有限时间内稳定跑完并且每一条的结果都能对上输入。如果你刚开始接触先把单条请求、顺序循环、小批量测试这三步做扎实等任务量真的上来了再引入异步批处理、断点恢复和成本统计。踩过几次坑之后你会发现很多批量任务失败的根源不是模型能力不够而是输入没清理、输出没落盘、失败没记录。把这几个基础问题解决掉批量处理就成功了一大半。
