結論先說
- 價格直接打五折:官方 Batch API 的輸入與輸出 token 單價均為標準實時調用價格的 50%,不要求毫秒級響應的離線任務都值得切過來。
- 目標完成時間在
24 小時以內:任務提交後進入後台異步隊列,大多數中小型批次幾分鐘到幾十分鐘就能跑完,但不承諾實時返回,不能拿來接在線聊天框。 - 小批量用內聯列表,大批量傳
JSONL文件:總請求體小於20 MB的幾百條數據可直接傳數組;幾萬條規模的大任務先用 Files API 上載.jsonl(最大2 GB),跑完下載結果文件按key對齊。 - 文本生成與 Embeddings 向量都支持批處理:除了
generateContent批任務,官方文檔也提供了批量生成向量的異步接口。 - 谷歌帳號準備與多工具訂閱入口:使用 Gemini、Google AI Studio 與 Antigravity 需具備符合地區與年齡要求的個人谷歌帳號,缺號可查看本站 谷歌帳號購買說明(含帶 2FA 的 谷歌電郵成品號),跨平台付費訂閱總覽見 AI 會員充值中心。

圖:本站根據 Gemini API 官方文檔:Batch API 整理的示意圖
本文根據 Google AI for Developers 官方文檔《Batch API》《Gemini Developer API pricing》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Google 官方網站。
適用於誰
- 要批量處理幾千到幾十萬條商品打標、文本翻譯、情感分類、數據集蒸餾或離線評測的開發者;
- 經常在並發跑腳本時撞上同步接口
429 RESOURCE_EXHAUSTED速率限制,想改成異步隊列穩妥跑完的人; - 搜「gemini api batch 批量請求」,想對比內聯請求(Inline)與
.jsonl文件兩種寫法怎麼選的人。
一、什麼時候該用 Batch Mode,兩種提交方式怎麼選
在實時接口裏開多線程硬刷大批量數據,既容易觸發每分鐘請求數(RPM)限流,又要付全價。只要業務符合「結果晚幾十分鐘甚至幾小時出來也不影響」的特徵——例如夜間定時清洗評論庫、給全站舊文章補摘要、跑模型提示詞基準評測——就應該改走 client.batches。
官方 SDK 提供兩種入參方式,選型標準很明確:
| 對比項 | 內聯提交(Inline Requests) | JSONL 文件提交(File Input) |
|---|---|---|
| 傳入方式 | 代碼裏直接傳請求字典列表 | 先拼 .jsonl 文件,經 Files API 上載後傳文件引用 |
| 體積邊界 | 適合總載荷 小於 20 MB 的輕量批次 | 單文件支持最大 2 GB,適合生產級海量數據 |
| 結果對齊 | 按返回數組順序一一對應 | 每行自帶唯一 key,輸出亂序也能精準還原 |
| 結果獲取 | 直接讀 batch_job.dest.inlined_responses | 調用 client.files.download 下載輸出 .jsonl |
如果你同時也在評估其他大模型的離線批處理接口,可以橫向對照本站整理過的 OpenAI Batch API 批量請求教學 與 Claude API Message Batches 教學。
二、寫法一:幾百條小任務直接用內聯請求
還沒配置好運行環境的開發者,請先完成 Gemini API Python SDK 安裝與密鑰配置。數據量不大時,不用落盤寫臨時文件,直接把多條請求塞進 src 列表創建任務即可:
python
import time
from google import genai
client = genai.Client()
inline_requests = [
{"contents": [{"parts": [{"text": "把這段評價歸類為正面或負面:發貨很快,包裝嚴實。"}]}]},
{"contents": [{"parts": [{"text": "把這段評價歸類為正面或負面:用了兩天就充不進電了。"}]}]},
]
batch_job = client.batches.create(
model="gemini-2.5-flash",
src=inline_requests,
config={"display_name": "review-sentiment-demo"},
)
print("已創建批任務:", batch_job.name)
completed_states = {"JOB_STATE_SUCCEEDED", "JOB_STATE_FAILED", "JOB_STATE_CANCELLED", "JOB_STATE_EXPIRED"}
while batch_job.state.name not in completed_states:
time.sleep(15)
batch_job = client.batches.get(name=batch_job.name)
if batch_job.state.name == "JOB_STATE_SUCCEEDED":
for idx, resp in enumerate(batch_job.dest.inlined_responses):
print(f"第 {idx + 1} 條結果:", resp.response.text)
谷歌開發帳號與主力編程訂閱提示:若當前帳號卡在地區不支持、手機核驗或工作空間限制,可在本站選購已配置兩步驗證的 谷歌帳號成品號(即時發貨,質保首登,到手請按指引先登後改密);日常搭配主力模型開發,也可同步了解免境外卡自助兌換的 ChatGPT Plus 與 Claude Pro。
三、寫法二:生產級大批量用 JSONL 文件提交與取回

圖:本站根據 Gemini API 官方文檔:Batch API 整理的示意圖
跑成千上萬條記錄時,建議用 JSON Lines(.jsonl)格式:一行一個獨立 JSON 對象,包含自定義業務主鍵 key(如訂單號)和標準 request 體。注意同一批次所有行共用創建作業時指定的模型:
json
{"key": "item-1001", "request": {"contents": [{"parts": [{"text": "提取關鍵詞:無線降噪藍牙耳機續航40小時"}]}]}}
{"key": "item-1002", "request": {"contents": [{"parts": [{"text": "提取關鍵詞:機械鍵盤紅軸熱插拔三模連接"}]}]}}
上載文件、啟動批處理並在完成後下載解析結果的完整代碼:
python
import json, time
from google import genai
from google.genai import types
client = genai.Client()
uploaded_input = client.files.upload(
file="batch_input.jsonl",
config=types.UploadFileConfig(display_name="product-kw-input", mime_type="jsonl"),
)
job = client.batches.create(
model="gemini-2.5-flash",
src=uploaded_input.name,
config={"display_name": "product-kw-job"},
)
done_states = {"JOB_STATE_SUCCEEDED", "JOB_STATE_FAILED", "JOB_STATE_CANCELLED", "JOB_STATE_EXPIRED"}
while job.state.name not in done_states:
time.sleep(30)
job = client.batches.get(name=job.name)
if job.state.name == "JOB_STATE_SUCCEEDED":
raw_bytes = client.files.download(file=job.dest.file_name)
for line in raw_bytes.decode("utf-8").splitlines():
if not line.strip():
continue
row = json.loads(line)
if "response" in row:
text = row["response"]["candidates"][0]["content"]["parts"][0]["text"]
print(row.get("key"), "=>", text.strip())
else:
print(row.get("key"), "單條失敗:", row.get("error"))
由於後台分佈式並發執行,輸出文件行順序不一定與輸入一致,解析時請按每行的 key 字段回寫數據庫。
四、任務管理、計費前提與注意事項
- 計費層級與預付費準備:Batch API 面向開啟結算的項目提供高吞吐配額與五折單價;開通計費、預充值(Prepay)與設預算上限見 Gemini API 計費與預付費設定教學,各模型價格見 Gemini API 價格速查。需要準備獨立谷歌帳號綁定項目時,可參考本站 谷歌帳號購買頁。
- 取消與清理:任務還在排隊時可調用
client.batches.cancel(name=job.name)取消;跑完後用client.batches.delete(name=job.name)清理記錄。 - 及時下載結果文件:Files API 託管文件預設保留期有限(通常 48 小時),任務變為
JOB_STATE_SUCCEEDED後請及時把結果下載落盤。
常見問題
問:一批 JSONL 裏如果混進了幾條異常數據,會導致整批全部失敗嗎?
答:不會整批作廢。只要輸入 JSONL 語法合法成功入隊,單條請求失敗會在輸出對應行返回 error 對象,其餘正常行照常返回 response。
問:Batch Mode 裏能用結構化 JSON 輸出(response_schema)和系統指令嗎?
答:可以。在每行 request 對象的配置與 system_instruction 字段裏按標準結構寫入即可,批量抽取字段建議加上 JSON Schema。
問:為什麼提交後一直顯示 JOB_STATE_PENDING?
答:這代表作業正在異步資源池排隊。官方目標週轉窗口是 24 小時內,高峰期排隊數十分鐘至數小時均屬正常;若超 24 小時未完成則會過期且不對未完成部分扣費。
問:沒有可用的個人谷歌帳號,或者同時想開其他主流 AI 會員怎麼辦?
答:本站提供即買即發的 谷歌電郵成品號(登入方法見 谷歌帳號購買頁),同時支持支付寶、微信支付與 AlipayHK 自助充值 ChatGPT Plus、Claude Code 等主流服務,實時價格與質保細則以各商品頁說明為準。
相關教學
- Gemini API 怎麼收費:按 token 計費、預付費充值與支出上限設定
- Gemini API 價格:各模型每百萬 tokens 多少錢、免費層和付費層差在哪
- Gemini API 429 錯誤怎麼解決:RESOURCE_EXHAUSTED 原因與排查表
- OpenAI Batch API 批量請求怎麼用:50% 折扣與 24 小時規則對比
- Claude API 批量請求(Message Batches)用法與計費規則
參考資料
- Gemini API 官方文檔:Batch API — https://ai.google.dev/gemini-api/docs/batch-api
- Gemini Developer API pricing — https://ai.google.dev/gemini-api/docs/pricing
0 條評論
還沒有評論,來搶沙發~