GeminiBatch APIWorkflowError Handling

Gemini 批处理结束了,先逐条对账再补跑

Gemini Batch API 的作业完成不等于每条请求成功。用稳定 key 保存输入与结果,区分错误、缺失和待审核项,避免创建请求重试导致整批重复执行。

查看接入文档
Gemini 批处理结束了,先逐条对账再补跑

Gemini Batch API 适合不必立即交付的摘要、分类与离线评估。官方说明,其费用为相应模型标准交互费用的 50%,目标完成时间为 24 小时。但作业显示完成,并不代表每条业务记录都有可用答案。

把批处理接进工作流,最先要做的是保存输入清单和作业名,完成后按 key 对账。明确失败的项再判断是否补跑,成功结果保留,缺失结果先查原因;不要看到一个错误就把整批重新创建。

本文于 2026 年 11 月 19 日核对 Batch API 指南的输入文件、作业状态、结果处理与最佳实践。没有提交真实批处理,以下 JSONL 与对账记录都是公开合成例子,不提供任务耗时或节省金额的实测。

为什么同一个作业里会有成功和失败?

Batch 是把多条请求异步安排到一个作业里,不是一个保证整体成功或整体回滚的数据库事务。官方要求作业完成后检查 batchStats.failedRequestCount,文件输出还要逐行判断是模型响应还是对应请求的错误。

当前指南明确:此功能使用 generateContent API,不要把 Interactions 的请求体直接写进批处理文件。支持哪些模型与模态要查各模型页面;交互调用支持某个工具,也需要确认该批处理路径的具体限制。

准备不可变输入,创建并保存作业名,等待终态,再逐条检查结果

输入可以直接内联,小批量总请求体保持在 20MB 以下;更大的任务可用 JSONL 输入文件,单个文件上限为 2GB。24 小时是官方的目标周转时间,不是你的业务必须准时完成的承诺。急着给在线用户回复的流程,应保留同步路径。

一条输入该留下什么标识?

JSONL 每行包含自定义 key 和一份完整请求。选择能回到业务记录的稳定标识,把文档版本、提示版本与模型另存到本地清单,不把姓名或邮件等隐私直接塞进 key。

下面保存为 requests.jsonl,两行都是公开教学素材:

{"key":"demo-a-v1","request":{"contents":[{"role":"user","parts":[{"text":"用一句话概括:这是一份介绍公开公园开放时间的演示说明。"}]}]}}
{"key":"demo-b-v1","request":{"contents":[{"role":"user","parts":[{"text":"用一句话概括:这是一份介绍公开图书馆借阅规则的演示说明。"}]}]}}

官方会在结果中带回 key,用它匹配原请求。不要把“输出第 10 行”当作“输入第 10 行”的业务标识;按 key 建立映射也便于处理遗漏、重复下载和后续补跑。

以下为官方 SDK 的文件提交形状,需要本地 GEMINI_API_KEY。示例没有执行。运行前先保存清单并确保只有一个提交者;提交成功后立即保存 job.name。

from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
uploaded = client.files.upload(
    file="requests.jsonl",
    config=types.UploadFileConfig(
        display_name="public-summary-input-v1",
        mime_type="application/jsonl",
    ),
)
job = client.batches.create(
    model="gemini-4-hydrogen",
    src=uploaded.name,
    config={"display_name": "public-summary-v1"},
)
Path("batch-name.txt").write_text(job.name)
print(job.name)

这段代码展示提交形状,不是可反复运行的恢复脚本。官方明确说明创建作业不具备幂等性:同一创建请求发送两次会生成两个作业。若提交结果不明,或服务接受后本地写文件失败,先核对服务端记录,不直接重跑 batches.create。display_name 只是便于识别的名称,不是防重复提交的保证。

作业成功后,怎么找出真正需要处理的项?

先保存原始输出文件,再分开处理四类:有模型响应、明确错误、没有出现的 key、出现了但业务验证不通过的结果。

按 key 对账,把模型响应、错误对象与缺失记录分开,业务校验后才算成功

下面只完成结构对账,输入是原来的 requests.jsonl 与下载后的 results.jsonl。它拒绝重复或陌生 key;“有响应”仍需要检查安全反馈、结束原因、空答案与业务字段,不能直接标为交付完成。

import json
from pathlib import Path

inputs = [json.loads(line) for line in Path("requests.jsonl").read_text().splitlines() if line.strip()]
expected = {row["key"] for row in inputs}
if len(expected) != len(inputs):
    raise ValueError("Duplicate input key")
seen, response_keys, error_keys = set(), set(), set()
for line in Path("results.jsonl").read_text().splitlines():
    if not line.strip():
        continue
    row = json.loads(line)
    key = row["key"]
    if key not in expected or key in seen:
        raise ValueError(f"Unexpected or duplicate result: {key}")
    seen.add(key)
    if row.get("response") is not None and row.get("error") is None:
        response_keys.add(key)
    elif row.get("error") is not None and row.get("response") is None:
        error_keys.add(key)
    else:
        raise ValueError(f"Unrecognized result structure: {key}")
print("Needs content validation:", sorted(response_keys))
print("Inspect errors:", sorted(error_keys))
print("Missing, investigate first:", sorted(expected - seen))

缺失项不自动等于失败项。先确认作业已到终态、下载完整、读的是正确文件;如果结果文件损坏,重新下载同一结果比重建整批更合适。已经有响应但内容不合格的项,保留原答案和原因,再决定调整提示还是人工处理。

什么时候补跑,什么时候继续等?

官方状态包括 JOB_STATE_SUCCEEDED、JOB_STATE_FAILED、JOB_STATE_CANCELLED 和 JOB_STATE_EXPIRED 等。轮询失败不等于作业失败,应拿已保存的作业名继续查询;作业进入终态后,再按实际可取得结果对账。

对明确失败的单项,先区分能否通过重试解决:模型或参数不合法先修输入,暂时服务错误才考虑退避补跑。建新作业时只装入经过判断的补跑项,另存新的作业名和尝试记录。业务记录可以保留原 key,尝试编号放在本地清单中,避免把原始成功结果覆盖掉。

网络查询失败继续查旧作业;单项错误先分类;仅批准项进入新作业

取消也需要等状态确认,不能把“已发送取消请求”当作所有记录都从未处理。模型结果后面若接邮件、订单或数据库写入,还要独立防止业务动作重复;可参考n8n 的副作用恢复。

哪些工作适合先迁到 Batch?

先挑可以容忍等待、输入固定、输出能单独验收的工作,例如每天整理公开资料、批量生成候选摘要。不要把 24 小时目标塞进必须几秒内响应的客服流程,也别假设 Batch 自动消除了多层重试的风险。

带状态的任务可沿用自动化工作流的节点分工:准备、提交、查询、对账、发布各自保存结果。查询与下载失败时接着原作业做,发布失败时接着已保存的模型输出做,恢复位置才不会退回整批起点。

通过 Nbility 接入前,查Gemini 原生兼容文档并另核 Batch、Files 与结果下载能力。本篇只介绍 Google 官方流程,未验证这些异步资源能经过本站转发;普通对话接口可用不构成 Batch 支持证明。

相关文章

Gemini 转写开始听懂“把上一句改掉”
GeminiSpeech to TextVoice Editing

Gemini 转写开始听懂“把上一句改掉”

Gemini 3.5 Transcribe 的 Smart 模式加入语音编辑,可以改写已有 source_text。做录音输入时要区分逐字转写、整稿替换和多轮状态,确认修改后再保存或发送。

Gemini 4 Neon 来了,高频复杂任务多了一个选择
GeminiGemini 4 NeonModel Selection

Gemini 4 Neon 来了,高频复杂任务多了一个选择

Gemini 4 Neon 于 11 月 18 日正式发布,定位在 Hydrogen 与 Carbon 之间。迁移时要同时检查默认思考档位、共享上下文、缓存与长输出路径,再用完整任务判断是否值得换。

用 Nbility 跑通你的 Agent 工作流

获取 API Key,统一接入 OpenAI 兼容模型和开发工具。

获取 API Key