瞭解如何使用 OpenAI 的批次處理 API,以非同步方式成批傳送請求,享有降低 50% 的成本、獨立且大幅提高的速率額度,以及明確的 24 小時完成期限。這項服務非常適合處理不需要立即回應的作業。你也可以直接在此瀏覽 API 參考文件。
概覽
雖然 OpenAI 平台的部分用途需要傳送同步請求,但在許多情況下,請求不需要立即回應,或是速率限制讓你無法快速執行大量查詢。批次處理作業通常適用於以下使用案例:
- 執行評估
- 分類大型資料集
- 為內容庫建立嵌入向量
- 將大型離線影片算圖作業排入佇列
批次處理 API 提供一組易於使用的端點,讓你將多個請求彙整到單一檔案中,啟動批次處理作業來執行這些請求,在請求執行期間查詢批次狀態,並在批次完成後取得彙整的結果。
相較於直接使用標準端點,批次處理 API 具備以下優點:
- 更低的成本: 相較於同步 API,費用減少 50%
- 更高的速率限制: 相較於同步 API,可用額度大幅增加
- 快速完成: 每個批次都會在 24 小時內完成(而且通常更快)
開始使用
1. 準備批次檔案
批次處理從一個 .jsonl 檔案開始,其中每一行都包含單一 API 請求的詳細資訊。目前可用的端點如下:
/v1/responses(Responses API)/v1/chat/completions(Chat Completions API)/v1/embeddings(嵌入向量 API)/v1/completions(Completions API)/v1/moderations(內容審核指南)/v1/images/generations(Images API)/v1/images/edits(Images API)/v1/videos(影片生成指南)
在輸入檔案中,每一行的 body 欄位所用的參數,都與對應端點的參數相同。每個請求都必須包含唯一的 custom_id 值,讓你在完成後用來查找對應結果。以下是包含 2 個請求的輸入檔案範例。請注意,每個輸入檔案只能包含對單一模型的請求。
使用批次處理生成影片時:
- 批次處理目前僅支援
POST /v1/videos。 - 影片的批次處理請求必須使用 JSON,不能使用 multipart。
- 請預先上傳素材,並在請求主體中傳入支援的素材參照,不要使用 multipart 上傳。
- 在批次處理中以圖像引導生成時,請使用
input_reference。在 JSON 請求中,請將input_reference以包含file_id或image_url的物件形式傳入。 - 批次處理不支援以 multipart 上傳
input_reference,包括影片參照輸入。 - 批次處理生成的影片,在批次完成後最多可供下載
24小時。
向 /v1/moderations 傳送請求時,每個請求主體都必須包含 input 欄位。使用 omni-moderation-latest 時,批次處理接受純文字輸入,以及包含文字或圖像輸入的內容陣列。批次處理工作程序會拒絕設定 stream=true 的請求,這與同步內容審核端點的行為一致。
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-3.5-turbo-0125", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-3.5-turbo-0125", "messages": [{"role": "system", "content": "You are an unhelpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}
內容審核輸入範例
純文字請求:
{
"custom_id": "moderation-text-1",
"method": "POST",
"url": "/v1/moderations",
"body": {
"model": "omni-moderation-latest",
"input": "This is a harmless test sentence."
}
}
包含文字與圖像輸入的請求:
{
"custom_id": "moderation-mm-1",
"method": "POST",
"url": "/v1/moderations",
"body": {
"model": "omni-moderation-latest",
"input": [
{
"type": "text",
"text": "Describe this image"
},
{
"type": "image_url",
"image_url": {
"url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg"
}
}
]
}
}
建議使用 image_url 參照遠端素材(而非 base64 資料區塊),
讓 .jsonl 檔案大小遠低於批次處理的 200 MB 上傳上限,
尤其是在傳送多模態內容審核請求時。
2. 上傳批次輸入檔案
與我們的微調 API 類似,你必須先上傳輸入檔案,才能在啟動批次時正確參照該檔案。請使用 Files API 上傳 .jsonl 檔案。
import fs from "fs";
import OpenAI from "openai";
const openai = new OpenAI();
const file = await openai.files.create({
file: fs.createReadStream("fixtures/batchinput.jsonl"),
purpose: "batch",
});
console.log(file);3. 建立批次
成功上傳輸入檔案後,你可以使用該輸入檔案的 File 物件 ID 建立批次。在此範例中,假設檔案 ID 為 file-abc123。目前,完成時限只能設為 24h。你也可以透過選用的 metadata 參數提供自訂中繼資料。
import OpenAI from "openai";
const openai = new OpenAI();
const batch = await openai.batches.create({
input_file_id: "file-abc123",
endpoint: "/v1/chat/completions",
completion_window: "24h",
});
console.log(batch);這個請求會傳回一個 Batch 物件,其中包含批次的中繼資料:
{
"id": "batch_abc123",
"object": "batch",
"endpoint": "/v1/chat/completions",
"errors": null,
"input_file_id": "file-abc123",
"completion_window": "24h",
"status": "validating",
"output_file_id": null,
"error_file_id": null,
"created_at": 1714508499,
"in_progress_at": null,
"expires_at": 1714536634,
"completed_at": null,
"failed_at": null,
"expired_at": null,
"request_counts": {
"total": 0,
"completed": 0,
"failed": 0
},
"metadata": null
}
4. 檢查批次狀態
你可以隨時檢查批次狀態,這項操作也會傳回一個 Batch 物件。
import OpenAI from "openai";
const openai = new OpenAI();
const batch = await openai.batches.retrieve("batch_abc123");
console.log(batch);Batch 物件的狀態可能是下列其中一種:
| 狀態 | 說明 |
|---|---|
validating | 正在驗證輸入檔案,驗證通過後才能開始批次處理 |
failed | 輸入檔案未通過驗證 |
in_progress | 輸入檔案已通過驗證,批次目前正在執行 |
finalizing | 批次已完成,正在準備結果 |
completed | 批次已完成,結果已備妥 |
expired | 批次未能在 24 小時的時限內完成 |
cancelling | 正在取消批次作業(最多可能需要 10 分鐘) |
cancelled | 批次作業已取消 |
5. 取得結果
批次作業完成後,你可以使用 Batch 物件中的 output_file_id 欄位向 Files API 發送請求,下載輸出內容並寫入電腦上的檔案;本例中的檔案為 batch_output.jsonl
import OpenAI from "openai";
const openai = new OpenAI();
const fileResponse = await openai.files.content("file-xyz123");
const fileContents = await fileResponse.text();
console.log(fileContents);輸出的 .jsonl 檔案中,每一行回應都對應輸入檔案中一行處理成功的請求。批次作業中所有失敗請求的錯誤資訊都會寫入錯誤檔案,你可以透過該批次作業的 error_file_id 找到這個檔案。
使用 /v1/videos 時,已完成的批次作業結果會包含已達最終狀態的影片物件,例如 completed、failed 或 expired。批次作業結束後,你可以立即使用傳回的影片 ID 下載最終成品。
請注意,輸出檔案的行順序 可能與輸入檔案不同 。 處理結果時,請使用 custom_id 欄位,而不要依賴行順序。 輸出檔案的每一行都會包含這個欄位, 讓你可以將輸入中的請求與輸出中的結果對應起來。
{"id": "batch_req_123", "custom_id": "request-2", "response": {"status_code": 200, "request_id": "req_123", "body": {"id": "chatcmpl-123", "object": "chat.completion", "created": 1711652795, "model": "gpt-3.5-turbo-0125", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello."}, "logprobs": null, "finish_reason": "stop"}], "usage": {"prompt_tokens": 22, "completion_tokens": 2, "total_tokens": 24}, "system_fingerprint": "fp_123"}}, "error": null}
{"id": "batch_req_456", "custom_id": "request-1", "response": {"status_code": 200, "request_id": "req_789", "body": {"id": "chatcmpl-abc", "object": "chat.completion", "created": 1711652789, "model": "gpt-3.5-turbo-0125", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello! How can I assist you today?"}, "logprobs": null, "finish_reason": "stop"}], "usage": {"prompt_tokens": 20, "completion_tokens": 9, "total_tokens": 29}, "system_fingerprint": "fp_3ba"}}, "error": null}
輸出檔案會在批次作業完成 30 天後自動刪除。
6. 取消批次作業
如有需要,你可以取消進行中的批次作業。批次作業的狀態會變為 cancelling,直到處理中的請求完成(最多需要 10 分鐘),之後狀態就會變為 cancelled。
import OpenAI from "openai";
const openai = new OpenAI();
const batch = await openai.batches.cancel("batch_abc123");
console.log(batch);7. 取得所有批次作業的清單
你可以隨時查看所有批次作業。如果批次作業數量較多,可以使用 limit 和 after 參數分頁取得結果。
import OpenAI from "openai";
const openai = new OpenAI();
const list = await openai.batches.list();
for await (const batch of list) {
console.log(batch);
}支援的模型
我們大多數模型都支援批次處理 API,但並非全部。請參閱模型參考文件,確認你使用的模型支援批次處理 API。
速率限制
批次處理 API 的速率限制與現有的各模型速率限制分開計算。批次處理 API 有三種速率限制:
- 每個批次作業的限制: 單一批次作業最多可包含 50,000 個請求,批次輸入檔案的大小上限為 200 MB。請注意,
/v1/embeddings批次作業還有另一項限制:批次作業內所有請求的嵌入輸入總數不得超過 50,000 筆。 - 各模型可排入佇列的提示詞 Token 數: 每個模型都有可排入批次處理佇列的提示詞 Token 數量上限。你可以在平台設定頁面查看這些限制。
- 批次作業建立速率限制: 每小時最多可建立 2,000 個批次作業。如果需要提交更多請求,請增加每個批次作業中的請求數量。
批次處理 API 目前沒有輸出 Token 數量限制。由於批次處理 API 使用一組新增且獨立的速率配額, 使用批次處理 API 不會占用各模型標準速率限制中的 Token 配額,因此你可以透過這個便利的方式,在呼叫我們的 API 時增加請求數量與處理的 Token 數量。
批次作業逾期
未能及時完成的批次作業最終會進入 expired 狀態;該批次作業中尚未完成的請求會被取消,而已完成請求的回應則可透過批次作業的輸出檔案取得。所有已完成請求所消耗的 Token 都會計費。
逾期的請求會連同下方所示的訊息一起寫入錯誤檔案。你可以使用 custom_id 取得逾期請求的資料。
{"id": "batch_req_123", "custom_id": "request-3", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}
{"id": "batch_req_123", "custom_id": "request-7", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}