Batch API：減少頻寬浪費並提升 API 效率

開發者在發送數千個獨立的 API 請求時，經常面臨回應速度慢、網路成本高的問題。Batch API 透過將多個獨立請求合併為單一操作來解決這個問題，降低延遲、頻寬使用量以及連線開銷。

本文將說明什麼是 Batch API、它與標準 API 的差異，以及 Novita AI 的 Batch API 如何透過結構化的 JSONL 輸入、高效的文件處理以及可靠的錯誤追蹤，實現大規模非同步推論。同時也會介紹成本、延遲、吞吐量等關鍵效率因素，並提供簡潔的實作與監控指南。

[立即以 5 折優惠試用批次推論

使用支援的模型更快、更便宜地執行大規模預測：
qwen/qwen3-vl-235b-a22b-instruct、openai/gpt-oss-120b、deepseek/deepseek-r1-0528、qwen/qwen3-4b-fp8。](https://novita.ai/docs/guides/llm-batch-api)

立即以 5 折優惠試用批次推論

使用支援的模型更快、更便宜地執行大規模預測：
qwen/qwen3-vl-235b-a22b-instruct、openai/gpt-oss-120b、deepseek/deepseek-r1-0528、qwen/qwen3-4b-f

什麼是 Batch API？

Batch API：將多個獨立的 API 請求（例如 GET、POST、PUT、DELETE）合併為單一 HTTP 請求。
Response Structure：伺服器會依序回傳所有子請求的結果，並標註每個請求的成功或失敗狀態。

Batch API 與標準 API 的關鍵差異

Nomal Requests

Client
 ├──► Request 1 (/user/1)
 │       └──► Server Response 1
 ├──► Request 2 (/user/2)
 │       └──► Server Response 2
 └──► Request 3 (/order)
         └──► Server Response 3

Batch Request

Client
 └──► Single Request (/batch)
          ├─ Sub-request 1: GET /user/1
          ├─ Sub-request 2: GET /user/2
          └─ Sub-request 3: POST /order
          ↓
       Server processes all
          ↓
       Combined Response:
          [Result1, Result2, Result3]

Batch API 可以帶來以下好處：

降低網路延遲：發送單一合併請求而非多個請求，減少往返時間。

降低頻寬與連線開銷：因為請求頭與握手過程可以共享。

提升客戶端效能：尤其對於行動裝置或網路較慢的環境效果顯著。

簡化交易邏輯：支援統一的錯誤處理或回滾機制。

優化 API 閘道吞吐量：避免請求泛洪造成的負載壓力。

Batch API 的典型使用場景

場景	說明
1. 批量資料查詢	一次取得多個使用者、商品或文章，避免重複發送請求。
2. 批量寫入或更新	單一操作中建立或更新多筆記錄（例如批量上傳、庫存更新）。
3. 前端效能優化	減少瀏覽器或行動應用程式發出的 HTTP 請求數量，加快載入速度。
4. 後端任務聚合	在微服務系統中，將多個內部 API 請求合併為單一外部請求。
5. 資料同步	同步多個資源狀態或執行批次操作（例如標記、刪除）。
6. 速率限制優化	透過整合請求降低 API 閘道負載，節省頻寬。

影響 Batch API 效率的關鍵因素

與即時 API 相比，Batch API 能省下多少成本？

產業分析（Growth-onomics）顯示，Batch API 能帶來約 20–45% 的成本降低，主要來自更少的網路往返次數、更低的連線開銷，以及集中處理；實際節省幅度則取決於呼叫頻率、批次大小與系統設計。

那延遲呢？Batch API 真的能保證在 24 小時內完成嗎？

Batch API 通常以非同步方式執行，延遲遠高於即時 API；許多系統會每小時或每天執行一次，因此「24 小時內完成」取決於服務水準協議（SLA），而非絕對保證。

批次大小或檔案大小會影響速度嗎？

會的。較大的批次（例如更多的 JSONL 行數）會幾乎線性地增加傳輸與解析時間；雖然吞吐量會提升，但每個批次的總完成時間也會隨之增長。

為什麼 Batch API 更適合高吞吐量工作負載？

透過將數千個請求聚合為單一處理流程，Batch API 能降低每次請求的開銷，並支援平行執行或快取重複使用，在大規模操作中通常能提升 17–92% 的吞吐量，但代價是更高的延遲。

如何使用 Batch API？

Novita 的 Batch API 與 OpenAI 介面高度相容，支援 /v1/chat/completions 與 /v1/completions 端點，現有程式碼只需少量修改即可重複使用。它接受 .jsonl 格式的輸入檔案，每行代表對相同模型的一個獨立請求，並透過唯一的 custom_id 標識以便追蹤。輸出同樣為 JSONL 格式，能輕鬆實現大規模後處理、分析與整合。

立即試用 Novita AI 的 Batch API 服務！

1. 準備批次輸入檔案

建立一個 .jsonl 檔案，每行為一個 JSON 格式的 API 請求。
範例（batch_input.jsonl）：

{"custom_id": "req-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Summarize: batch API basics"}], "max_tokens": 200}}
{"custom_id": "req-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are concise."},{"role": "user", "content": "List 3 batch API use cases"}], "max_tokens": 150}}

規則：

• 每行只有一個請求。
• 所有請求必須使用相同的模型。
• 每行必須包含唯一的 custom_id。

2. 上傳輸入檔案並建立批次

使用 Python 或 curl 上傳檔案並立即啟動批次任務。

Python

from openai import OpenAI

client = OpenAI(base_url="https://api.novita.ai/openai/v1", api_key="YOUR_API_KEY")

# Upload + create batch
uploaded = client.files.create(file=open("batch_input.jsonl", "rb"), purpose="batch")

batch = client.batches.create(
    input_file_id=uploaded.id,
    endpoint="/v1/chat/completions",
    completion_window="48h"
)

print("file_id:", uploaded.id)
print("batch_id:", batch.id)

curl

export API_KEY="YOUR_API_KEY"

# Upload file
upload_response=$(curl -s -X POST \
  -H "Authorization: Bearer ${API_KEY}" \
  -F 'file=@batch_input.jsonl' -F 'purpose=batch' \
  https://api.novita.ai/openai/v1/files)

# Extract file_id and start batch
file_id=$(echo $upload_response | jq -r '.id')

curl -X POST https://api.novita.ai/openai/v1/batches \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"input_file_id\": \"$file_id\", \"endpoint\": \"/v1/chat/completions\", \"completion_window\": \"48h\"}"

檢查您的 API 金鑰

3. 檢查批次狀態

您可以隨時透過批次 ID 檢查執行進度。

batch = client.batches.retrieve("batch_xxx")
print(batch.status)

狀態包括：

• VALIDATING – 正在檢查輸入檔案
• PROGRESS – 執行中
• COMPLETED – 成功完成
• FAILED – 執行失敗
• EXPIRED – 超過 48 小時執行視窗

4. 取回結果

完成後，您可以透過 output_file_id 下載結果檔案：

output = client.files.content("file_xxx")
print(output.read().decode("utf-8"))

輸出的每一行對應一個輸入請求，透過 custom_id 進行配對。

提示：

僅支援 deepseek/deepseek-r1-0528

每個批次最多支援 50,000 個請求

輸入檔案大小上限為 100 MB

執行視窗固定為 48 小時

輸出結果保留 30 天

Batch API 中失敗的請求該如何處理？

批次處理過程中遇到的錯誤會記錄在獨立的 錯誤檔案 中，可透過 error_file_id 欄位存取。每個失敗的子請求都會包含錯誤碼與描述，常見情況如下：

錯誤碼	說明	解決方案
400	請求格式無效	檢查 JSONL 語法與必要欄位
401	認證失敗	驗證 API 金鑰是否正確
404	找不到批次	檢查批次 ID 是否正確
429	超過速率限制	降低請求頻率
500	伺服器錯誤	聯繫供應商或稍後重試

開發人員應使用重試佇列或較小的後續批次，只重新處理失敗的條目，而无需重新提交整個原始檔案。

Novita AI 提供哪些 Batch API 操作的端點？

端點	用途
建立批次	提交包含多個請求的新批次任務。
取回批次	透過批次 ID 取得特定批次的狀態或結果。
取消批次	在批次完成前停止正在執行的批次任務。
列出批次	列出帳戶下所有已提交的批次任務。
上傳檔案	上傳輸入資料檔案（例如 JSONL）。
列出檔案	查看所有已上傳的檔案。
取回檔案	透過檔案 ID 取得檔案中繼資料。
刪除檔案	刪除已上傳的檔案。
取回檔案內容	下載檔案的實際內容（例如結果或錯誤日誌）。

Batch API 能將多個小型請求整合為單一高效的工作流程。透過使用 Novita AI 的 Batch API，開發人員最多能降低 45% 的網路成本，每個批次最多可擴展至 50,000 個請求的吞吐量，並透過內建的日誌記錄與取回端點簡化錯誤處理。雖然它會犧牲即時速度，但對於批量推論、同步與資料處理工作負載來說，能提供卓越的效率。

Novita AI 是一個 AI 雲端平台，為開發者提供簡單的 API 來部署 AI 模型，同時也提供實惠且可靠的 GPU 雲端服務，用於建構與擴展 AI 應用。

推薦閱讀

• 提示快取：使用 Novita AI 實現穩定低成本快取
• 比較 Kimi K2-0905 API 供應商：為什麼 NovitaAI 脫穎而出
• 如何存取 Qwen3-VL-235B-A22B 並建構更智慧的程式碼演示