Batch API 结果怎么核对？custom_id 配对、缺项与失败补偿
先确认批任务状态，再把输出和错误文件按 custom_id 与原输入逐条对齐，最后决定哪些结果可用、哪些需要核查或补偿。不要按文件行号覆盖原数据，也不要看到一部分失败就重发整批。批任务结束、HTTP 正常、业务结果合格，是三个不同的判断。
本文由云岚API整理，以 OpenAI Batch API 的文件格式为例，官方资料核对日期为 2026 年 10 月 24 日。它适合不需要即时返回的离线任务；不表示云岚API或任意 OpenAI 兼容端点已经支持 Batch。接入前须分别确认目标服务的文件上传、批任务、模型与结果下载能力。官方 Batch 指南
提交前：保存能还原每次尝试的输入清单
OpenAI Batch 使用 JSONL，每行一条请求，包含唯一的 custom_id。它用于对应结果；输出顺序可能与输入不同。批量执行前，先保存原始输入及版本，不能在等待过程中覆盖同一个文件。输入与结果格式
业务上另存一张映射表：业务记录 ID、输入版本、custom_id、批次 ID、模型、端点与尝试次数。业务记录可能重做多次，因此业务键和本次请求 ID 不宜混为一个概念。custom_id 也不能代替数据库的幂等控制。
例如同一篇文档首次摘要与修正后的摘要，应能找到各自输入和结果；如果只保留“文档 123 已处理”，就无法判断现在要写入的是哪一版。发现输入 ID 重复时先修清单，不靠输出顺序猜对应关系。
任务状态和逐条结果，分别看哪一层？
validating、in_progress、finalizing 等状态描述批任务进展；completed 表示结果已准备好。批对象还包含成功/失败请求计数，以及 output_file_id、error_file_id 等字段。要读取存在的两类文件，再逐条核对，不能只下载成功文件就宣布整批通过。批对象与计数定义
| 当前观察 | 应做的事 |
|---|---|
| 仍在运行或整理结果 | 保留批次 ID，按服务说明继续查询；缺项尚不能下结论 |
| completed | 对齐输出和错误文件，再验证每条内容 |
| failed | 先读批级错误，定位输入校验问题；不能假设有完整逐条结果 |
| expired 或 cancelled | 保存已经产生的结果，核对剩余项目，不直接全部重做 |
官方说明，过期或取消时已完成的工作仍可返回，并可能产生相应费用。因此“批次没有全部完成”不等于“此前请求都没执行”。过期与取消说明
对账时，把缺项、失败和结构异常分开
先建立原输入 ID 集合，把 output 与 error 文件一起读取。结果 ID 必须属于原批次且不能重复；重复项不能选最后一条静默覆盖。随后核对下面几类：
| 检查结果 | 含义与下一步 |
|---|---|
| 有唯一结果且 HTTP 正常 | 继续检查端点完成状态、拒绝、空内容和业务字段 |
| 有 HTTP 或请求级错误 | 保存原始错误，按原因决定修配置或有限补偿 |
| 外层字段缺失、类型错误或互相矛盾 | 回查文件来源与协议，不当作成功结果 |
| 原输入 ID 没有结果 | 先确认终态、两类文件和下载完整性，再查服务记录 |
| 重复或未知 ID | 隔离冲突，检查是否混入其他批次或重复下载文件 |
只比行数不够：两个重复 ID 加一个未知 ID，可能恰好凑齐原来的条数。应按唯一 ID 核对覆盖关系，再把已验收、失败和待确认的结果分别记录。HTTP 200 的正文仍可能被截断、拒绝或不符合要求，单条内容继续按JSON 与业务结果验收处理。
用本地核对器练一次，再处理真实文件
下载 Batch 结果核对器与记录表，解压后运行：
python3 reconcile.py input.synthetic.jsonl output.synthetic.jsonl errors.synthetic.jsonl --batch-status expired
示例是四条人工输入：一条 HTTP 正常但待业务检查、一条 HTTP 错误、一条请求级错误，以及一条缺项。程序只使用 Python 标准库，不读 Key、不调用 API、不重发请求，也不把人工结果当作模型效果测试。
它检查 ID 覆盖与选定的外层字段，不是完整 Batch SDK 或所有端点的 schema 验证器。mapping_complete 只表示 ID 一一对应；退出码 0 只表示报告生成成功，都不等于业务通过。--batch-status 是你填写的状态，工具没有联网确认。具体输入约定和标签说明见包内 README。
补偿前先冻结已合格结果，再列待处理项
把已验收结果及其输入版本保存下来。缺项先查证，明确失败再分原因：参数与权限问题修复后重做；临时错误结合服务记录、次数和预算上限决定是否补偿。单条 429 的原因继续按报错排查处理，不把所有失败都归为限流。
新批次应保存原任务与新尝试的映射，写入业务数据时按稳定业务键和版本做幂等控制。核对器只给分类，不自动生成重发清单。真实处理过程可填包内空白 CSV，记录补偿理由、新批次和尝试次数；失败与补偿用量也纳入任务成本核对。
常见问题
Batch 显示 completed，就代表每条都成功吗？
不能只看这个状态。还要读成功与失败计数、输出和错误文件，再核对每条结果及业务要求。
输出文件顺序变了，怎样匹配输入？
用原始清单中的 custom_id 配对，不按行号。发现重复、未知或缺失 ID 时先隔离核查，不能猜测归属。
expired 或 cancelled 后可以整批重发吗？
先核对已有结果与待确认项。部分工作可能已经完成；确认需要补偿的项目后再建立新批次，并记录成本与尝试次数。
复用同一个 custom_id 能保证不重复执行吗？
不能把配对 ID 当作跨批次幂等保证。仍需保存提交记录，并在业务落库时用稳定业务键、版本和执行状态防止重复处理。