如果你要一次摘要上千份文件、分類大量客服紀錄,或跑一整套模型評測,逐筆呼叫 API、每次都等答案回來,可能不是最合適的工作方式。Batch API(批次 API)讓你先提交一組彼此獨立的模型請求,服務端以非同步工作處理,再於稍後取回結果。它適合可以等待的批量作業,不是即時聊天或需要馬上回覆的互動功能。
Batch API 和一般同步呼叫差在哪裡?
一般同步 API 是「送出一筆請求,等待這一筆回應」;Batch API 則是「整理多筆請求、建立批次工作、追蹤工作狀態、完成後取回結果」。工作一旦提交,程式不必在同一個連線中一直等到所有內容完成;可以保存工作識別碼,稍後再查詢或接收通知。
OpenAI 的 Batch API 文件以 JSONL 檔案逐行放置請求,讓使用者建立批次並查詢工作狀態;文件也提醒每筆請求要有獨一無二的 custom_id,用來把回覆配回原始工作資料。批次回覆不保證依輸入順序排列,因此不能只靠第幾行對第幾行。

最重要的實務:每筆資料都要有自己的識別碼
假設你把一千筆商品資料送去產生摘要,完成後需要知道每段摘要屬於哪個商品。為每筆請求放入資料庫主鍵、商品 ID 或其他穩定唯一值,比單純記住檔案行號可靠。以 OpenAI 的 JSONL 格式為例,以下只是單筆請求示意:
{"custom_id":"product-00821","method":"POST","url":"/v1/responses","body":{"model":"your-model-id","input":"請將這筆商品資料摘要成一句話。"}}
提交工作時,也要保存服務端回傳的批次 ID、來源資料版本、模型名稱、提交時間和預期筆數。取回結果時,以 custom_id 配回原始記錄;不要假設完成順序和送出順序一致,也不要把缺少回覆的資料默默當成成功。
批次完成不代表每一筆都成功
把批次工作想成一個裝著很多獨立任務的郵袋:郵袋完成分揀,不表示每封信都送達。OpenAI 文件會提供成功結果與錯誤結果檔案;Anthropic 的 Message Batches 指南也說明其中請求分別處理,一筆失敗不會自動讓其他請求全部失敗。Google Gemini 的 Batch API 文件則建議作業完成後檢查失敗請求數,並在輸出中辨識個別請求錯誤。
因此至少要逐筆檢查:結果是否存在、HTTP 或模型狀態是否成功、輸出格式能否解析、內容是否符合用途。只對失敗的記錄採取適當重試,並先確認失敗原因。若整個批次重送,容易重複產生結果、覆寫資料或再次計費;要以穩定的記錄 ID 和冪等寫回流程避免副作用。

哪些工作適合批次處理?
- 大量摘要或分類:例如產品描述整理、客服訊息主題分類、文件標籤產生。
- 模型評測:對固定測試集跑同一組問題,再整理正確率、格式錯誤或失敗樣本。
- 批量嵌入或內容分析:一次處理文件庫或資料匯入工作,避免把同步等待塞進前台流程。
- 離線內容生成:例如夜間產生初稿、商品文案或內部報表摘要,再由工作人員檢查。
相對地,使用者正在等候的聊天回覆、需要即時串流顯示的應用、具有嚴格即時期限的自動化流程,通常應選同步或串流介面。批次的目標完成時間和可用模型、端點、單一工作限制都會因供應商而異:OpenAI 文件列出 24 小時完成視窗;Gemini 文件稱目標周轉時間為 24 小時;Anthropic 文件則指出多數批次較快完成,但工作仍可能依負載延長。這些是各自服務的說明,不是所有 Batch API 共用的 SLA。
不同供應商的 Batch API 不是完全相同的規格
有些服務要求先上傳 JSONL 請求檔,有些也允許較小工作直接內嵌請求;查詢批次狀態、取回結果、錯誤格式、資料保留時間、費率和支援端點亦可能不同。以 Gemini 為例,官方文件目前描述 Batch API 用於 generateContent,並提供檔案輸入或小型內嵌請求等方式。整合前先查你選定平台的最新文件,並用少量測試資料確認模型、端點和輸出結構可用,不要假設換一家供應商只需改 URL。
建立 Batch API 流程前的檢查清單
- 確認任務真的可延後:標示哪些使用情境必須即時回覆,避免把互動流程誤放進離線工作。
- 建立穩定的 custom_id:每筆輸入都能重新連結回原始資料,並將識別碼保存到自己的資料庫。
- 先試少量請求:確認 JSONL 格式、模型支援、權限和輸出解析,再逐步放大。
- 記錄批次工作生命週期:保存工作 ID 和狀態,設計輪詢或使用服務提供的 webhook,不要靠人工猜測工作是否完成。
- 逐筆核對和安全重試:統計成功、失敗和缺漏,僅重送確認需要重試的資料,並避免重複寫入。
- 管理輸入與結果檔:批次檔可能含客戶或內部資料;依組織政策限制存取、設定保存期限並妥善刪除。
結語:把非即時任務交給工作佇列,不要丟掉追蹤能力
Batch API 的價值不只是一次送很多提示,而是把大量獨立請求變成可追蹤的非同步工作。先替每筆資料設定穩定 ID,保存工作狀態,完成後逐筆配對、檢查錯誤,再安全地寫回結果。當任務可以等候且輸入量大時,批次處理能讓流程更有條理;但若需要即時回應,仍應選擇符合時效需求的 API 模式。