如果你平时在做数据处理、内容生成或者知识库构建大概率已经跟各家大模型的 API 打过交道。很多人一开始都是老老实实一条条实时调用等任务量上来之后才发现钱包消耗的速度比任务进度还快。今天聊的批量 APIBatch就是专门治这个毛病的把大量请求打包成一个文件提交上去让平台异步处理完你再一次性把结果拉回来。官方通常直接按实时价格的五折计费我自己在真实项目里跑下来大批量场景确实能省差不多一半成本同时还能把系统从同步等待里解放出来稳定性肉眼可见地变好。这篇文章会从批量 API 的工作原理、完整实操流程、成本测算、结果对账再到我踩过的一堆坑一次性讲清楚。想用批量接口省钱、想把线上同步调用改造成异步批处理的读者可以直接照着做每一步都给你写明白了。1. 先搞懂 Batch API 的原理才知道钱省在哪里1.1 一次性搞清同步接口与批量接口的差别日常用的实时 API 调用本质上是同步请求你发一条 HTTP 请求过去服务器排队处理然后把这条请求的结果返回给你。这种模式适合聊天、客服、实时审核这类必须立刻出结果的场景。缺点是每条请求都要占用一次完整往返服务器需要为你维持连接、调度资源不管你有没有用到满这部分开销都已经花出去了。批量 API 的思路完全反过来。它不要求每条请求立刻返回而是让你先把一堆请求写到同一个文件里一次性上传上去平台拿到之后会在自己的调度系统里排队等计算资源有空闲了再逐个处理。处理完以后平台把结果也打包成一个文件你下载下来自己解析就行。类比一下实时 API 就像是专门为你叫的专车随叫随走但单价高批量 API 更像是定时班车或者拼车你得等它按点发车但票价便宜一半甚至更多。对不着急出结果的任务来说这笔账怎么算都划算。1.2 平台凭什么给你打五折成本逻辑和适用边界平台愿意给批量接口打折不是因为做慈善而是因为批量任务能帮平台填平算力低谷。大模型服务的算力需求波动很厉害白天高峰时段 GPU 可能满载凌晨可能闲置一大片。实时请求没法挑时间平台只能随时准备好资源伺候着。但批量任务可以缓存排队平台就能把这类任务安排在算力空闲的时间段处理把原本闲置的 GPU 利用起来。所以批量 API 的定价逻辑很简单用户牺牲实时性平台换取调度弹性省下来的算力成本双方对半分。多数平台直接给到五折少部分平台还会根据任务窗口给更深的折扣。明白了这个逻辑你就能判断自己的业务适不适合用批量 API 了。适合的场景很清晰批量翻译、文章批量润色、知识库向量化之前的文本清洗、大规模数据打标、离线评测集跑分、定时生成日报周报、历史日志分析这些任务的特点是量大、不要求秒回、容忍几小时甚至一天内有结果。不适合的场景也很清晰用户发消息之后的实时对话、在线客服应答、需要立刻反馈的交互式操作这些还是老老实实走实时接口不要为了省钱牺牲产品体验。2. 实操把第一批任务真正跑通2.1 准备输入文件JSONL 格式和几个隐藏要求批量 API 的输入文件格式基本是业界统一的 JSONL每行是一个独立的 JSON 对象代表着一次完整的请求。下面是个具体例子{custom_id: request-0001, method: POST, url: /v1/chat/completions, body: {model: gpt-4o-mini, messages: [{role: user, content: 请把这句话翻译成英文批量API怎么用}], max_tokens: 200}} {custom_id: request-0002, method: POST, url: /v1/chat/completions, body: {model: gpt-4o-mini, messages: [{role: user, content: 总结下面这段文本的核心要点不超过100字...}], max_tokens: 150}}第一眼看上去很简单但有几个隐藏要求值得注意。custom_id必须是一个字符串而且在同一个批量任务内必须全局唯一最终下载结果的时候你全靠它来识别每一行对应的结果。我建议从一开始就建立一套命名规则比如用“业务名-批次-序号”的格式既方便排查问题也方便后续和业务数据做关联。url字段通常写的是接口路径而不是完整地址比如/v1/chat/completions或/v1/embeddings。域名部分由平台自动拼接不用你管。body里的内容和你平时调用实时接口传的参数一模一样模型名、消息内容、temperature、max_tokens 都可以写进去。文件编码统一用 UTF-8不要带 BOM。有同事曾经用 Windows 记事本编辑过 JSONL 文件存出来带了个 BOM 头平台解析第一行的时候直接报格式错误排查了半天才发现是编码问题。另外还要注意每行必须是一个完整的 JSON 对象不能用数组把所有请求包起来也不能在行尾多加逗号。2.2 上传、建任务、查状态三步操作的完整流程第一步把 JSONL 文件上传到平台的存储系统拿到一个文件 ID。第二步用这个文件 ID 创建一个批量任务指定要访问的接口和期望完成时间。第三步定期查任务状态等状态变成 completed 之后下载结果文件。以 OpenAI 兼容接口为例用官方 Python SDK 写出来大概是这样的import time from openai import OpenAI client OpenAI(api_key你的API Key) # 1. 上传输入文件 with open(batch_input.jsonl, rb) as f: file_resp client.files.create(filef, purposebatch) file_id file_resp.id print(file_id:, file_id) # 2. 创建批量任务 batch_resp client.batches.create( input_file_idfile_id, endpoint/v1/chat/completions, completion_window24h, ) batch_id batch_resp.id print(batch_id:, batch_id) # 3. 轮询任务状态 while True: status client.batches.retrieve(batch_id) print(status.status) if status.status in [completed, failed, expired, cancelled]: break time.sleep(60) # 4. 任务完成后下载结果 if status.status completed: result_file client.files.content(status.output_file_id) with open(batch_output.jsonl, wb) as f: f.write(result_file.content) print(结果已保存到 batch_output.jsonl)如果不想用官方 SDK直接拿 requests 请求接口也可以。核心就三个接口上传文件、创建批次、查询批次状态。很多国内平台的批量接口也兼容这套格式SDK 版本不同字段名可能略有差异但大方向是一样的。轮询的时间间隔不要写死成每 5 秒跑一次尤其任务数量大的时候频繁轮询除了浪费自己服务器资源没有别的好处。建议任务刚提交时 1 分钟查一次运行一段时间后改成 2 到 5 分钟查一次如果平台提供了回调或者 webhook 功能优先用回调比轮询优雅得多。2.3 completion_window 不是乱填的怎么选才稳妥创建批量任务时有个参数叫completion_window常见值是24h部分平台也支持1h。这个字段代表你给平台的期望完成时间在这个时间内处理完就行。你可能会觉得选个短窗口拿结果更快但实际用下来发现窗口越短平台调度的约束越强任务排进紧俏时段的概率反而降低并不一定更快。而且价格通常不因窗口长短而改变所以没必要为了心理上的快感选短窗口。我的建议很简单业务要求多久出结果就选多大的窗口。能做 T1 的任务统一用 24h让平台自己慢慢排只有被产品经理盯着必须尽快出结果的才缩窗口。另外特别提醒一句这个窗口是硬约束如果平台在窗口内来不及处理任务会直接变成 expired 状态结果没跑完还白花了上传文件的功夫。所以选窗口之前先评估一下你的任务量和平台当前的调度压力。2.4 常见疑问一个批量任务能塞多少请求单个批量任务能放多少请求不同平台限制不一样。不少平台限制一次任务最多几万条请求文件大小也有上限超出部分需要拆成多个提交。我自己习惯是单个文件控制在 50000 行以内文件大小不超过 200MB这样不管切到哪个平台都能兼容。如果你的数据量特别大比如要处理 1000 万条文本拆成 200 个小批量文件分批提交每个文件独立一个任务这样即使某一个小批失败也不会拖垮全局排查问题也只定位到具体文件比一次性塞一个巨型文件稳妥得多。3. 成本测算与大规模改造的关键判断3.1 算一笔账批量 API 到底能省多少纸上谈兵没有感觉直接算一笔账。假设当前使用的模型实时价格是输入 1 美元/百万 tokens输出 3 美元/百万 tokens批量接口价格是五折即输入 0.5 美元/百万 tokens输出 1.5 美元/百万 tokens。假设你的业务每天要处理 100 万输入 tokens产出 20 万输出 tokens计费项实时接口价格批量接口价格每日实时成本每日批量成本输入 tokens100万1.0 美元/百万0.5 美元/百万1.0 美元0.5 美元输出 tokens20万3.0 美元/百万1.5 美元/百万0.6 美元0.3 美元合计--1.6 美元0.8 美元每天省 0.8 美元看起来不多但把规模放大到 1000 万输入 tokens、200 万输出 tokens每天就能省 8 美元一个月就是 240 美元一年接近 3000 美元。对于做 to B 服务或者长期跑数据管线的团队来说这不是小钱。还有一个容易被忽略的好处批量任务的限流阈值通常比实时接口宽松得多即使你的业务量短时间内翻倍也不会马上触发 429 限流错误。这一点在应对业务突发流量时尤其重要省钱之外还省了运维压力。3.2 架构怎么改从同步请求到异步批处理管线把同步实时调用改造成批量任务不是简单换个接口就行整个调用链路的思维模式都要变。实时调用的思路是“请求-响应”批量调用则是“投递-回执”。我建议的架构方案是上游业务把需要处理的文本写进消息队列或者业务表一个定时任务定时拉取待处理数据组装成请求行写入 JSONL 文件上传后创建批量任务。任务完成之后再有一个下载任务把结果落库同步更新业务表里的对账状态。这个流水线里最关键的设计是状态机。每个业务批次至少要有这几个状态待提交、已提交、运行中、已完成、部分失败、彻底失败。用一张批次表记录批量任务 ID、文件 ID、结果文件 ID、提交时间、完成时间。这样才能做到失败可重试、进度可追踪而不是把一切交给大脑记忆。整个改造成本并不高一个小团队一两周就能搭建完。但收益是实打实的线上系统不再被长耗时的大模型调用拖住主链路响应更快离线任务在大半夜慢慢跑也没人管。3.3 什么时候不该用批量 API省钱是好事但不能为了省而省。如果单次业务量每天只有几十条请求建议别折腾批量 API。因为批量 API 有固定的管理成本准备文件、上传、轮询、下载、对账这些步骤的开发和维护工作量不可忽视。每天几十条请求用实时接口可能花不到 1 美元省下五毛钱却要维护一条完整管线不划算。实时交互场景更不能用批量 API。用户问一句话等 3 秒还能接受等 3 个小时肯定连产品都保不住。批量 API 替代的是那些“等得起、量大、重复性高”的任务找准自己的业务边界才能发挥它最大的价值。4. 结果文件解析与错误定位4.1 拿到输出文件后怎么正确对账批量任务完成后你下载到的输出文件也是 JSONL 格式每一行对应输入文件中的一条请求。一个成功的结果行大概长这样{id: batch_req_8a1c2d, custom_id: request-0001, response: {status_code: 200, request_id: req_9f3e2a, body: {id: chatcmpl-xxx, choices: [{message: {role: assistant, content: ...}}], usage: {prompt_tokens: 32, completion_tokens: 78, total_tokens: 110}}}, error: null}response.status_code是 HTTP 状态码200 表示成功response.body里的内容和实时接口返回的格式一致choices里就是模型生成的正文usage里有 token 消耗数据。error字段在成功时是 null失败时则包含错误码和错误信息。对账的时候有个非常容易踩的坑输出文件里的行顺序不一定和输入文件一致。平台多线程并发处理谁先跑完谁先落盘所以绝对不要按行号去对应输入输出。正确做法是把输出文件按custom_id建立索引再和输入文件的custom_id做关联这样哪怕顺序打乱也能准确对上。我见过不止一个同事想当然按顺序逐行读取结果数据全部错位教训深刻。还有一点要提醒如果批量任务里有一部分请求失败平台可能不会把失败记录放在正常输出文件里而是单独生成一个错误文件。创建任务返回结果里通常有error_file_id字段记得检查这个文件否则你会以为任务全成功了实际上有漏网之鱼。4.2 常见的 API 错误码和应对策略批量任务的结果文件和实时调用的错误码是同一套体系但处理策略不太一样。实时调用出错你当场就能重试批量任务出错可能几十分钟后才发现。我把常见的错误码整理成了一张表状态码/错误可能原因处理建议200请求正常直接解析 body 用结果400请求参数错误比如模型名不对、消息格式有问题、JSON Schema 校验失败检查对应请求行的 body 参数修完重新提交401API Key 无效或过期检查鉴权配置换了 Key 后重跑失败批次403账户权限不足或者模型未开通检查平台控制台的权限和模型白名单404接口路径或者模型不存在核对 Endpoint 路径和 model 名别自己瞎拼429触发限流或者账户余额不足增大退避时间充值后再重试5xx平台临时故障稍后重试该批次一般都能恢复批量接口相对实时接口要宽容一些单条请求失败不会让整个任务崩掉。但是你要建立一条处理链路拿回输出文件后先过滤所有非 200 的状态码把失败请求单独存起来做成可重试的队列。我习惯做法是给失败请求打上错误类型标签如果是参数错误就修数据如果是限流就排到下个批次分级处理效率高很多。4.3 一个隐蔽坑custom_id 设计与幂等去重custom_id不只是用来关联结果它还承担着幂等去重的职责。如果你的数据在业务层面本身有唯一 ID比如订单号、用户 ID、文档 ID我强烈建议直接把业务 ID 拼进custom_id里比如order-20250101-0001或者doc-xxxxx-part-3。为什么强调这一点因为批量任务失败后最常见的行为就是整批重跑。如果custom_id是随机生成的重跑后你根本分辨不了哪些结果已经入库了只能全部删掉重新处理。但如果你用业务 ID下载结果后直接 upsert 到数据库即使任务重跑也不会产生重复数据实现天然幂等。我见过最惨的例子是同事用毫秒级时间戳做 custom_id某个批量任务因为平台故障重跑了三次结果库里多了两倍的数据最后只能靠生成时间倒推去重折腾了一整天。前车之鉴大家一定别偷懒。5. 我在实战里踩过的几个重坑5.1 模型名写错导致 400接口文档并不会替你把关批量接口对模型名称的校验非常严格你在 body 里填的 model 必须是当前平台支持的模型名一个字符都不能差。我就多次收到这种报错400 the supported api model names are deepseek-flash, deepseek-v4字面意思很清楚你填的模型名不在支持列表里但问题在于不同平台的模型命名规则并不统一同一家平台不同时期的模型名还会变。你别指望报错信息会给出完整支持列表有些平台只在文档里写报错信息里不提示。正确做法是提交批量任务之前先用实时接口小规模试调用一次确认模型名、参数格式都能通再放心去组批量。这一步能挡掉一大半低级错误。5.2 鉴权信息冲突一套代码里塞了两个 Key有一段时间我调用某个第三方兼容接口时始终报认证失败日志显示服务端认为是鉴权信息冲突。后来排查才发现配置文件里同时配置了一个主 Key 和一个备用 KeySDK 自动同时加载了两套认证头其中一个是给 Anthropic 风格的另一个是 OpenAI 风格的服务端一检测到两个认证字段同时存在就直接拒绝。这类报错通常带着auth conflict: both a token (anthropic_auth_token) and an api key这类信息看到之后别怀疑平台先检查自己的代码和配置。一个问题排查原则认证相关的报错90% 的根源在客户端配置不在服务端。5.3 function calling 的 schema 校验失败正则差点把我搞疯有一次给批量任务加函数调用功能提交后收到一条 400 错误invalid schema for function artifact: ^(?!.*$)[^\p{cc}\p{c,batch...。第一次看到这个报错说实话我愣了半天因为报错信息被截断得非常奇怪看起来像是正则表达式里混入了二进制字符。排查到最后发现问题出在参数定义的 JSON Schema 里写的正则表达式不合法。我原本想在字符串校验里用\p{Cc}这类 Unicode 属性来排除控制字符但平台使用的 JSON Schema 校验器并不支持这种简写形式而且字符串里反斜杠需要双重转义稍不注意就会把 JSON 结构弄坏。这个坑让我总结了三条经验。第一函数参数定义尽量用 JSON Schema 的标准关键字如minLength、maxLength、pattern不要一上来就写复杂正则。第二凡是涉及正则在提交前先用本地代码解析一遍 JSON确保语法正确。第三小批量试跑永远值得做你永远不知道平台的 schema 校验会比本地严格多少。5.4 批量任务过期了才想起来去取结果批量任务的窗口是硬约束24 小时窗口就是最多 24 小时超时任务直接进入 expired 状态。我有一个项目因为团队休假提交完任务没人盯状态等回来发现任务早就过期了所有请求要重新提交一遍白白浪费了时间。从这里我学到两个教训。一是批量任务提交后要有自动告警任务完成或者失败要第一时间通知到人不能只靠人去轮询。二是窗口用完之前如果发现任务可能跑不完可以先手动取消再重新提交不要傻等着它过期。取消之后再提交至少能保留一部分已完成的结果比全部作废强。5.5 本地 Docker 环境连接失败和批量接口无关的干扰项排查问题时要学会区分前后端问题。有次我在本地调试批量任务脚本一运行就报failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen直觉以为是 API 调用链路出问题了折腾了半天才发现是我本地的 Docker Desktop 服务没启动脚本里有个依赖服务跑在 Docker 容器里和云端 API 一点关系都没有。这类连不上本地服务、认证失败、端口占用的问题建议先排查环境再怀疑接口。给自己定个规矩看到连接类型报错先看服务状态看到认证类型报错先查配置看到参数类型报错再查代码逻辑。按这个顺序排查效率会高很多。6. 成本再优化三个进阶玩法6.1 控制输出 token 与请求体积批量 API 只打了五折但真正的省钱大头是在源头控制请求体积。输出 token 的单价通常比输入 token 贵好几倍所以在构造请求时一定要给max_tokens设置一个合理上限。很多人为了让模型一次性输出更完整的内容习惯把max_tokens调到很大结果模型真的生成了大量冗余内容费用直线上升。我建议根据业务需求估算每个请求需要的输出长度留出 20% 的余量作为上限。比如要求生成 100 字以内的摘要max_tokens设 150 到 200 就足够了没必要设成 1000。另外 prompt 本身也不要写太多无关的思考链和示例能在提示词里压缩的内容尽量压缩输入 token 积少成多也是一笔不小的开支。6.2 对重复请求做缓存很多批量任务里天然存在大量重复请求。比如知识库构建时同一份文档可能被多个上游任务重复触发预处理内容打标时同一段新闻文本会被多个不同标签任务重复调用。对这些重复请求最好的优化就是做缓存。缓存的粒度可以按custom_id对应的业务主键来处理前先查库里有没有这个主键的已有结果有就直接跳过。还可以对请求内容做哈希相同哈希的请求直接复用之前的结果。这两个策略实现成本很低但能显著减少实际消耗的 token 数效果往往比批量五折更明显。6.3 实时与批量混合一个务实的架构方案最后说一个组合拳的思路。如果业务里既有必须实时返回的请求又有可以等待的离线请求不要一刀切全部走实时也不要全部切到批量。我的推荐方案是用户主动触发、需要即时反馈的单独走实时接口后台任务、定时任务、数据预处理的全部走批量接口。实时接口的并发能力留给真正重要的交互场景批量接口负责消化大量非紧急请求两者互不干扰。这个方案还有一个额外的好处实时调用出现的 429 限流会明显减少因为流量被批量任务分流了。整体成本能控制在原来的 60% 左右系统稳定性还比原来好一举两得。我在实际项目里连续跑了半年多批量任务最大的体会是批量 API 带来的不只是账面上的成本折半它更重要的是改变了你设计系统的方式把一个一个的同步请求变成了一条可观测、可重试、可追溯的异步管线。最后再分享一个保存了很久的经验不管任务看起来多简单都先提交一个 10 条以内的小文件试跑确认结果结构和预期一致再放开全量。这一步能帮你躲掉至少一半的返工时间我每次都是这么干的。