For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主要導覽

批次處理 API

使用批次處理 API 非同步處理作業。

瞭解如何使用 OpenAI 的批次處理 API,以非同步方式成批傳送請求,享有降低 50% 的成本、獨立且大幅提高的速率額度,以及明確的 24 小時完成期限。這項服務非常適合處理不需要立即回應的作業。你也可以直接在此瀏覽 API 參考文件

概覽

雖然 OpenAI 平台的部分用途需要傳送同步請求,但在許多情況下,請求不需要立即回應,或是速率限制讓你無法快速執行大量查詢。批次處理作業通常適用於以下使用案例:

  1. 執行評估
  2. 分類大型資料集
  3. 為內容庫建立嵌入向量
  4. 將大型離線影片算圖作業排入佇列

批次處理 API 提供一組易於使用的端點,讓你將多個請求彙整到單一檔案中,啟動批次處理作業來執行這些請求,在請求執行期間查詢批次狀態,並在批次完成後取得彙整的結果。

相較於直接使用標準端點,批次處理 API 具備以下優點:

  1. 更低的成本: 相較於同步 API,費用減少 50%
  2. 更高的速率限制: 相較於同步 API,可用額度大幅增加
  3. 快速完成: 每個批次都會在 24 小時內完成(而且通常更快)

開始使用

1. 準備批次檔案

批次處理從一個 .jsonl 檔案開始,其中每一行都包含單一 API 請求的詳細資訊。目前可用的端點如下:

在輸入檔案中,每一行的 body 欄位所用的參數,都與對應端點的參數相同。每個請求都必須包含唯一的 custom_id 值,讓你在完成後用來查找對應結果。以下是包含 2 個請求的輸入檔案範例。請注意,每個輸入檔案只能包含對單一模型的請求。

使用批次處理生成影片時:

  • 批次處理目前僅支援 POST /v1/videos
  • 影片的批次處理請求必須使用 JSON,不能使用 multipart。
  • 請預先上傳素材,並在請求主體中傳入支援的素材參照,不要使用 multipart 上傳。
  • 在批次處理中以圖像引導生成時,請使用 input_reference。在 JSON 請求中,請將 input_reference 以包含 file_idimage_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 檔案。

上傳批次處理 API 所需的檔案
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 時,已完成的批次作業結果會包含已達最終狀態的影片物件,例如 completedfailedexpired。批次作業結束後,你可以立即使用傳回的影片 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. 取得所有批次作業的清單

你可以隨時查看所有批次作業。如果批次作業數量較多,可以使用 limitafter 參數分頁取得結果。

取得所有批次作業的清單
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 有三種速率限制:

  1. 每個批次作業的限制: 單一批次作業最多可包含 50,000 個請求,批次輸入檔案的大小上限為 200 MB。請注意,/v1/embeddings 批次作業還有另一項限制:批次作業內所有請求的嵌入輸入總數不得超過 50,000 筆。
  2. 各模型可排入佇列的提示詞 Token 數: 每個模型都有可排入批次處理佇列的提示詞 Token 數量上限。你可以在平台設定頁面查看這些限制。
  3. 批次作業建立速率限制: 每小時最多可建立 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."}}