别人还在一条一条循环调用 API 的时候我这边已经靠批量 APIBatch API把单月账单砍掉了将近一半。这篇文章就把我实际跑通批量任务的全过程和避坑心得完整写出来从计费逻辑到请求文件构造再到延迟与成本怎么权衡一次性讲透。很多人对批量 API 的理解就是把多个请求放在一起发这个说法没错但远远不够。真正接手一个批量任务之后你会发现它改的不只是请求方式而是整套调用模型从同步等待变成了异步提交从按次计费变成了任务式计费从实时返回变成了文件输出。理解不了这层变化后面大概率会在结果解析、任务状态管理上反复踩坑。1. 批量 API 到底改了什么一次一请求变成了整包交付1.1 常规调用的旧模式每次都像打一次专车先看最常见的单条调用。你发起一个 POST 请求带上参数服务器处理完把结果同步返回给你。整个过程就像在路边打专车你招手车停上车到目的地下车付款。这种模式的好处是即时性高适合用户点击按钮立刻要结果的场景。坏处也明显每一次请求都是一次完整的网络往返都要做鉴权、路由、模型推理、结果返回哪怕你只是想把一万条商品评论做情感分类也得老老实实循环调用一万次。我见过不少团队这么干写个 for 循环一条一条发请求每条约一两百毫秒一万条跑下来将近半小时。期间还要处理限流、超时、重试、并发控制代码写得比业务逻辑还复杂。更难受的是这种高频高并发调用在计费上是按条算的平台并不会因为你量大就给折扣反而可能因为触发了限流策略直接返回 429。1.2 批量调用的新模式提交一个文件去干别的事批量 API 完全是另一套玩法。你不再是逐条发送请求而是把所有要处理的请求提前写进一个文件一次上传平台会创建一个任务然后在后台慢慢跑。拿我刚做过的评论分类项目举例。十万条评论我只需要生成一个包含十万行请求的 JSONL 文件上传、创建批量任务、设置 24 小时完成窗口然后就可以关掉终端去干别的。平台会在后台调度算力分批次处理跑完之后给你一个结果文件下载回来按 custom_id 拼接回业务数据就行。这个模型有点像把一堆快递一次性丢给物流公司你把包裹集中到转运仓物流公司按自己的路线和运力慢慢派送最后统一签收。你不会中途打电话催快递必须一秒钟送到但换来的是单件运送成本大幅下降。1.3 用延迟换成本这笔买卖到底值不值搞懂了新旧模式的差异核心问题就来了为什么平台愿意给批量接口打折答案很简单——你让出了实时性。单条接口为了保证用户等待体验平台必须预留足够的实时算力高峰低谷都得扛着。而批量任务不需要立即响应平台可以把这些请求塞进低峰期的空闲算力里或者用更灵活的调度策略慢慢处理。对平台来说边际成本低得多自然愿意用更低的价格吸引你把非紧急任务切过来。但代价也很明显批量任务通常需要排队等待短则几分钟长则几小时极端情况下甚至到第二天才完成。所以值不值完全取决于业务场景如果是数据清洗、离线分析、批量生成那这笔买卖非常划算如果是用户在页面上等你返回结果那就别碰批量接口延迟会让你被用户骂死。2. 省一半成本不是噱头计费逻辑和平台设计2.1 为什么平台愿意打五折我最早看到批量 API 的价格时也怀疑过单条 0.002 美元一次批量直接降到 0.001 美元五折凭什么后来琢磨明白了背后的成本结构差异非常大。平台处理单条请求时要维持一个实时推理服务请求来了必须立刻响应算力必须时刻准备着。而批量任务可以先把请求文件存到对象存储里后台用一个异步队列慢慢消费服务端可以按最大吞吐量去跑而不是按最短响应时间去跑。这种离线批处理模式在工程上能够把 GPU 利用率提升很多空闲时间少了单位请求分摊的硬件成本自然降下来。另外文件化输入输出也帮了大忙。单条接口要处理海量小请求的鉴权、路由、网络开销批量任务把这些开销摊到了一个文件上整体网络和 IO 压力小得多。2.2 请求文件格式为什么几乎都是 JSONL目前主流平台的批量 API 请求文件几乎统一采用 JSONL 格式。很多第一次接触的人会问为什么不用 JSON 数组答案要从处理角度理解。JSONL 的意思是每一行都是一个独立的 JSON 对象行与行之间完全独立。对于十万条请求的文件来说如果整体是一个 JSON 数组服务端必须完整读取、解析整个文件才能开始处理内存开销巨大。JSONL 则可以边读边处理逐行解析遇到坏行也能精确定位不会让整个文件解析失败。另一个原因是流式处理友好。批量任务的后端通常对接消息队列一条一条消费比一次性载入数组更符合业务模型。所以你在构造请求文件时也要记住一个原则每一行都必须是一个自包含的完整请求不要把多条请求合并在同一行里也不要在文件末尾多留空行。2.3 各平台 Batch 能力的差异怎么快速看清坦白讲批量 API 的设计在各大平台之间已经趋同但细节差异仍然存在。我用过的几个平台核心差异集中在四个维度比较维度常见差异范围需要重点确认的地方单任务文件大小限制多数平台限制在 50MB 到 200MB 之间你的请求文件是否会超过上限超过就需要拆分成多个任务批内请求数量上限常见上限从 3 万到 10 万不等量特别大的业务要做分片策略不能一口气硬塞任务有效期完成窗口常见 24 小时或 48 小时平台会在超时后取消任务窗口越长越保险计费单位与折扣有的按请求次数有的按 token 数按 token 计费时请求文件里的提示词长度直接决定成本我建议切任何批量 API 之前不要急着写代码先把三样东西从文档里找出来请求文件格式示例、任务状态字段说明、结果文件结构。这三个搞明白了后面整个流程都不会有大问题。另外注意有些平台的批量任务只支持特定接口比如对话补全、向量化不支持所有在线接口提前确认你的业务负载能不能走批量。3. 手把手跑通一个批量任务10 万条评论情感分类实战3.1 准备阶段把业务数据转成 JSONL 请求文件先搭个实际场景有一份包含十万条用户评论的数据表每行有review_id和text两个字段我希望用大模型给每条评论打一个正面、负面、中性的情感标签。第一步是把业务数据转成批量请求文件。以 OpenAI 风格的批量接口为例每一行请求长这样{custom_id: review-10001, method: POST, url: /v1/chat/completions, body: {model: gpt-4o-mini, messages: [{role: system, content: 你是文本情感分析助手只输出正面、负面、中性三个词之一。}, {role: user, content: 分析这句话的情感这个商品质量出乎意料地好包装也精致物流很快。}], max_tokens: 5}}注意custom_id是唯一标识结果文件里会原样返回它这是后面把预测结果映射回业务数据的关键。url和body就对应你要调用的接口和参数。各平台字段名略有差异有的平台把请求体放在input里但整体思路完全一致。用 Python 生成这个文件很简单重点是保持每行独立、UTF-8 编码、不要有多余字符import json with open(reviews.jsonl, r, encodingutf-8) as f: for line in f: review json.loads(line) with open(batch_requests.jsonl, w, encodingutf-8) as out: for review in reviews: req { custom_id: freview-{review[id]}, method: POST, url: /v1/chat/completions, body: { model: gpt-4o-mini, messages: [ {role: system, content: 你是文本情感分析助手只输出正面、负面、中性三个词之一。}, {role: user, content: f分析这句话的情感{review[text]}} ], max_tokens: 5 } } out.write(json.dumps(req, ensure_asciiFalse) \n)这里我多说一句为什么max_tokens要调小。情感分类只需要模型输出一个词把max_tokens从默认值调到 5 能大幅降低生成阶段的计算量。批量接口按 token 计费时这个参数直接决定了账单金额。很多人在批量调用里直接抄在线接口的参数结果生成了一堆不需要的废话钱多花了还没拿到干净结果。3.2 创建任务上传文件、指定接口、设置有效期请求文件生成好之后一般用 SDK 或者 HTTP 客户端上传拿到文件 ID再基于文件 ID 创建批量任务。from openai import OpenAI client OpenAI() uploaded_file client.files.create( fileopen(batch_requests.jsonl, rb), purposebatch ) batch client.batches.create( input_file_iduploaded_file.id, endpoint/v1/chat/completions, completion_window24h ) print(batch.id)completion_window就是前面说的完成窗口常见值是 24h 或 48h。窗口越长平台调度越从容你的任务越不容易因为排队压力被取消。如果业务对时间要求不高选更长的窗口往往还能提高任务成功率。有些平台要求先上传到指定 OSS 或者对象存储桶再提交任务本质没有区别核心都是先有文件、再开任务。创建成功后会返回一个任务 ID之后所有状态查询都以这个 ID 为索引。3.3 等待阶段轮询状态与错误排查批量任务创建后处于validating状态平台会校验文件格式和内容是否合法。校验通过后进入in_progress开始真正执行请求。全部完成之后变成completed同时会生成一个结果文件。我一般写这样一个轮询逻辑import time while True: status client.batches.retrieve(batch.id) print(status.status, status.request_counts) if status.status in (completed, failed, expired, cancelled): break time.sleep(60)request_counts是个字典包含total、completed、failed三个数字用来看任务内部到底执行了多少条。比较常见的坑是文件校验阶段失败任务直接变成failed这时候通常是 JSONL 里某一行格式写错了。处理方法是把文件逐行读出来用json.loads逐行解析定位到报错行号尽快修复重传不需要把整个文件扔掉。这里建议轮询间隔不要小于 60 秒。批量任务本身就是异步设计的就算你每秒查一次平台也不会给你额外提速反而可能因为频繁调用批量任务状态接口触发限流。3.4 结果阶段按 custom_id 把答案拼回业务表任务变成completed后先取结果文件 ID再下载内容。结果文件同样是 JSONL每一行对应一个请求的响应custom_id会和请求时保持一致。result_file_id status.output_file_id result client.files.content(result_file_id) import json results_map {} for line in result.text.splitlines(): obj json.loads(line) custom_id obj[custom_id] body obj[response][body] content body[choices][0][message][content].strip() results_map[custom_id] content # 与原始业务数据合并 with open(reviews_labeled.csv, w, encodingutf-8) as out: out.write(review_id,sentiment\n) for review in reviews: key freview-{review[id]} out.write(f{review[id]},{results_map.get(key, error)}\n)这一步是整个流程里最容易出问题的地方。有些平台的结果文件行顺序和请求顺序并不完全一致如果直接按行号去对应原请求数据就全错位了。正确做法永远是用custom_id做关联把结果存成字典再拼接。另外结果文件里除了正常响应还可能有包含error字段的行对应执行失败的请求。有人下载完结果文件就直接写进数据库事后才发现有一批数据是空的。我的习惯是解析完先统计一下results_map的条数跟原始请求条数是否一致不一致就把缺失的 ID 找出来重跑这样才稳。3.5 意外情况处理任务失败、文件过期、结果不完整批量任务虽然省事但不是百分百可靠。我实测中遇到过几种情况一是任务卡在in_progress很久不动大概率是单条请求超时率过高个别请求反复重试拖慢了整体进度二是任务到了窗口末尾还没完成直接被平台标记为expired三是结果文件里部分请求失败。针对这些问题我现在的策略是大任务不要只开一个而是拆成几个子任务并行跑每个子任务控制和平台并发上限匹配的量。这样即使某个子任务失败也只影响一部分数据重试代价小得多。另外下载结果文件要趁早不管平台规定结果文件保留多久我都会当天拉取到本地再备份一份防止文件过期被清理。4. 值不值得切把成本账和延迟账一起算明白4.1 成本账单条价 0.002 美元 vs 批量价 0.001 美元意味着什么先做一道小学数学题。假设你每天要调用一百万次接口单条接口价格 0.002 美元一次批量接口五折一次 0.001 美元。单条方案1,000,000 × 0.002 2000 美元/天。批量方案1,000,000 × 0.001 1000 美元/天。一天就差 1000 美元一个月差 3 万美元。这还只是简单按次计费的情况如果接口按 token 计费批量接口的折扣同样直接对 token 单价打折量大的时候差距更夸张。但这里必须诚实提醒一句真实业务里不可能所有请求全走批量。用户在前端的每次交互都是同步调用你不可能让用户在页面转圈等到批量任务完成。所以更合理的做法是统计业务里的同步调用量和可异步批量量前者维持原价后者切批量再算总账。4.2 业务量阈值一个月省不到一杯咖啡钱就别折腾切批量是有迁移成本的。你得改造调用代码、写文件生成逻辑、做结果回填还要处理失败重试。如果业务量很小比如一个月调用几千次省下来的钱可能就几十块连开发调试的时间成本都覆盖不了。我个人的经验阈值是日调用量低于几万次先别急着动架构。因为日几万次单条价 0.002 美元一天也就几十美元即使打五折一天省几十美元一个月省一千美元折算人民币七千左右。对于小团队来说这个收益是值得的但如果你只是个人接个小项目月调用量一两万次那省的钱还抵不上你折腾半天的时间。等到日调用量进入十万、百万级别批量 API 就不是优化项而是必选项了。这时候你的同步接口大概率已经在被限流循环调用不仅慢还会触发平台的并发策略批量改造反而是解药。4.3 延迟敏感场景别拿批量 API 做在线接口批量任务的延迟波动很大。运气好时几分钟就跑完运气不好排队一两个小时也很正常。凡是用户操作后需要立即反馈的场景比如聊天机器人、实时翻译、表单校验一律不要走批量。这个道理很多人其实知道但还是会在实际架构里犯迷糊。最常见的情况是业务方说这个数据晚一点出也行结果你做了批量产品又改成用户点一下就要立刻看到最后只能推翻重做。我建议在技术选型阶段就问清楚三个问题数据最晚多久要到用户能不能接受分钟级延迟如果批量失败有没有兜底方案这些问题有了明确答案再决定是否引入批量 API。4.4 混合调度的最佳实践热数据走同步、冷数据走批量一个成熟系统的常态是同步接口和批量接口共存。我的做法是用一条规则区分用户在线交互触发的请求走同步 API离线数据加工类需求走批量 API。具体到评论分类这个案例用户新提交的一条评论可以立刻走同步调用打标签存库对历史十万条评论的整体情感分布统计就走批量任务批量补齐。这样既保证用户在端上的体验实时又能在离线分析场景把成本压下来。我用这个混合方案改造之后同步调用量下降了一大半账单上的平均单价也明显下降整体的调用成功率还比纯循环高了不少因为不再频繁触发限流了。5. 批量任务翻车实录踩过的坑和躲坑技巧5.1 结果顺序不是按请求顺序返回的第一次跑批量任务我打开结果文件就愣住了第一行是review-40023第二行是review-00117请求顺序完全被打乱。当时还以为是平台出 bug 了后来才意识到结果文件内部行的处理顺序是并行的只要数量对上顺序没有任何保证。从那时起我就给自己立了一条规矩结果解析绝不使用行号获取对应数据永远基于custom_id构造字典。这不仅能避免错乱还能天然应对部分请求失败时缺失某一行的场景。5.2 同一批任务里塞了太多请求失败后整批重来早前我图省事一次性把十万个请求全塞进一个批次结果执行到一半因为某几条请求反复超时把整个任务拖到过期。十万条请求全部白费重新跑去重成本很高。错误的根源在于只考虑了文件总量没有把控任务的内部执行粒度。批量任务里的请求越多只要有一条梗在里面重试机制就可能把整批的节奏打乱。后来我改成每批不超过两三万条宁可多创建几个批次并行跑也不要一个超大批次赌运气。多批次并行还有一个好处就是可以随时从成功批次里拿结果先验证不用等所有任务都完成。5.3 上传和校验阶段的隐蔽错误批量任务创建后最先进入validating阶段很多新人对这个阶段不够重视上传完文件就直接返回也不看任务状态。实际上这个阶段的失败率不低常见原因包括文件不是严格的 UTF-8 编码、JSONL 末尾多了一个空白行、custom_id重复、URL 字段拼错导致接口不存在。校验失败时的报错信息往往只告诉你第几行有问题不会明确告诉你这个行里少了哪个字段。我处理过最隐蔽的一次是max_tokens写成了字符串5不是数字 5平台直接报格式错误。格式字段的类型都必须和文档严格一致这是批量 API 里最容易被忽视的地方。5.4 超时、过期、窗口制度文件放久了会作废批量 API 几乎都引入了文件有效期机制请求文件和结果文件都不会永久保存在平台上。文件本身有保留期限批量任务也有过期机制。我见过最惨的情况是任务完成了结果文件没及时下载等到想起来去取时文件已经离开生命周期平台返回的下载链接失效整批结果只能重跑。所以现在我把批量任务的执行流程分成两段任务状态一变成completed立马下载结果文件到本地并且做一个带时间戳的备份。如果当天只跑到一半也要先下载已完成的子任务结果再继续跑下一个批次。文件过期这种问题不属于偶发故障而是平台存储策略的一部分早晚会踩到早做防御比事后补救划算得多。5.5 个人习惯总结做了这么多轮的批量任务我的默认策略已经固定下来凡是 T1 能交差的非交互任务一律走批量凡是用户点按钮就要看到结果的老老实实走同步接口。批量任务的代码写起来其实就那几个步骤——生成文件、上传、创建任务、轮询、下载结果难点从来都在数据边界和异常处理上。每次新建一个批量任务前我会花一分钟过一遍清单请求文件是不是严格 JSONLcustom_id是否全局唯一文件大小是否在平台限制内该子任务的请求量是否控制在合理范围结果文件的下载是否安排了备份失败请求有没有自动重跑的机制。这一遍过完再去提交基本不会出大问题。