Python 批次請求:OpenAI 相容 LLM API
進行 LLM API Python 批次工作不需要特殊的批次端點:你需要一個遵守速率限制的工作池、一個處理 HTTP 429 的重試規則,以及一個可以從中恢復的結果檔案。本指南使用指向你 Base URL 的 OpenAI SDK 建立這三者。

重點摘要
- API 有兩種方法:聊天完成與模型,因此批次處理是在你的端透過並行請求池來完成。
- 完整金鑰允許 8 個並行請求和每分鐘 300 個;試用金鑰允許 2 個和每分鐘 60 個。調整你的池大小以符合這些限制。
- 使用 Retry-After 標頭處理 429,並區分速率限制與並行限制。
- 每當請求完成時將結果寫入 JSONL 檔案,這樣當機只會損失幾分鐘,而不是整個批次。
此處的批次處理運作方式
該端點與 OpenAI 相容,提供 POST /v1/chat/completions 與 GET /v1/models。沒有單獨的提交工作端點來接收檔案並稍後回傳結果。因此,批次處理是針對一般請求的迴圈,以並行方式執行,且限額已內建於你的程式碼中。這比聽起來簡單,且你能在請求完成時立即取得結果,而非等到最後。
影響設計的數字是限制。完整金鑰允許 8 個並行請求和每分鐘 300 個請求。試用金鑰允許 2 個並行和每分鐘 60 個。最大請求主體為 8 MB。串流請求會佔用並行槽位直到串流結束,因此對於批次工作,請關閉串流輸出。
為什麼不一次性發送所有請求?因為批次是一個有上限的吞吐量問題,而上限由你來遵守。一個以 Python 能產生的最快速度發送 5,000 個請求的迴圈,會收到一堆 429 回應,在重試上浪費時間,並將有用的錯誤掩埋在雜訊中。一個最多保持 8 個請求在執行的池,會以服務允許的速度保持線程流動,且無論你有 50 行還是 500,000 行,程式碼都是一樣的。規劃三個部分:有界池、一個重試規則和一個僅追加的結果檔案。
模型 ID 為 uncensored,驗證為 Authorization: Bearer <key>,Base URL 為 https://api.unfilteredvideo.com/v1。如果你還沒有金鑰,API 金鑰頁面提供一鍵 $0.50 試用。
安裝與設定
你需要 Python 3.9 或更新版本以及官方的 openai 套件。將金鑰放在環境變數中,而不是放在腳本中。
pip install openai
export API_KEY="paste-your-key-here"
# quick check that the key and base URL work
curl https://api.unfilteredvideo.com/v1/models -H "Authorization: Bearer $API_KEY"
模型列表應顯示 uncensored。現在準備你的輸入為 JSONL 檔案,每行一個物件,包含 id 和要處理的文字。id 是用於稍後恢復的關鍵。
{"id": "r001", "text": "Summarise this product review in one sentence: ..."}
{"id": "r002", "text": "Summarise this product review in one sentence: ..."}
保持在限制內的執行緒池
對於大多數腳本,ThreadPoolExecutor 是最簡捷的路徑。OpenAI 用戶端在執行緒間共享是安全的,且工作屬於網路密集型,因此執行緒很適合。將池大小設定為你的並行限制,不要更高:額外的工作執行緒只會收集 429 錯誤。
import json, os
from concurrent.futures import ThreadPoolExecutor, as_completed
from openai import OpenAI
client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
WORKERS = 8 # use 2 on a trial key
def run_one(row):
resp = client.chat.completions.create(
model=MODEL,
temperature=0.2,
max_tokens=200,
messages=[{"role": "user", "content": row["text"]}],
)
return {
"id": row["id"],
"output": resp.choices[0].message.content,
"in": resp.usage.prompt_tokens,
"out": resp.usage.completion_tokens,
}
rows = [json.loads(line) for line in open("input.jsonl")]
with ThreadPoolExecutor(max_workers=WORKERS) as pool, open("output.jsonl", "a") as out:
futures = [pool.submit(run_one, r) for r in rows]
for f in as_completed(futures):
out.write(json.dumps(f.result()) + "\n")
out.flush()
這個版本沒有重試和恢復功能,因此它只是一個起點。客戶端是使用 max_retries=0 在客戶端層級建立的,因為 SDK 預設會自行重試,而你希望由單一位置來管理重試規則。接下來的兩個章節將加入該規則和恢復邏輯。
正確處理 429
此 API 有三種 429 錯誤,需要稍微不同的反應:
rate_limited:你在一分鐘內發送了太多請求。減慢速度。減少工作執行緒數量或短暫睡眠即可解決。concurrency:同時處於傳輸狀態的請求過多。你的執行緒池大於你的限制,或者你有忘記關閉的串流。- 暫時過載:帶有
Retry-After: 5標頭的 429。你的程式碼沒有問題。等待指定的時間並重試。
一個重試輔助函數涵蓋所有三種情況。當存在 Retry-After 時會等待,否則會以少量抖動進行指數退避。失敗和遭拒的請求不會計費,因此重試是免費的。
import random, time
import openai
from openai import OpenAI
client = OpenAI(api_key=__import__("os").environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
def call_with_retry(messages, attempts=6):
for n in range(attempts):
try:
return client.chat.completions.create(model=MODEL, messages=messages, max_tokens=200)
except openai.RateLimitError as e:
wait = e.response.headers.get("Retry-After")
delay = float(wait) if wait else min(60, 2 ** n) + random.random()
print("429", getattr(e, "code", None), "waiting", round(delay, 1), "s")
time.sleep(delay)
except (openai.APIConnectionError, openai.APITimeoutError):
time.sleep(min(30, 2 ** n))
raise RuntimeError("gave up after %d attempts" % attempts)
不要對每個錯誤盲目重試。400 表示你的請求有誤,例如主體超過 8 MB 或訊息格式錯誤,再次發送會以相同方式失敗。記錄該行 id 並跳過。
帶有訊號量的非同步版本
如果你的腳本已在事件迴圈中運行,或者你想為 Web 服務提供數據,請使用 AsyncOpenAI 和 asyncio.Semaphore 來限制進行中的請求。訊號量扮演池大小的角色。
import asyncio, json, os
from openai import AsyncOpenAI
client = AsyncOpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
sem = asyncio.Semaphore(8)
async def run_one(row, out):
async with sem:
resp = await client.chat.completions.create(
model=MODEL,
max_tokens=200,
messages=[{"role": "user", "content": row["text"]}],
)
out.write(json.dumps({"id": row["id"], "output": resp.choices[0].message.content}) + "\n")
out.flush()
async def main():
rows = [json.loads(l) for l in open("input.jsonl")]
with open("output.jsonl", "a") as out:
await asyncio.gather(*(run_one(r, out) for r in rows))
asyncio.run(main())
將呼叫包裝在上述重試邏輯中,使用 await asyncio.sleep 代替 time.sleep。一個注意事項:gather 與數萬個協程會一次性建立它們。對於非常大的輸入,請以幾千行為單位處理檔案切片。
使執行可恢復
長時間作業會以枯燥的方式失敗:筆記型電腦進入睡眠、連線中斷、你按下 Ctrl+C。因為每個完成的行都以 id 追加到 output.jsonl,恢復意味著跳過你已經有的 id。
import json, os
from openai import OpenAI
client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1")
MODEL = "uncensored"
def done_ids(path="output.jsonl"):
if not os.path.exists(path):
return set()
return {json.loads(line)["id"] for line in open(path) if line.strip()}
finished = done_ids()
todo = [r for r in map(json.loads, open("input.jsonl")) if r["id"] not in finished]
print(len(finished), "done,", len(todo), "to go")
將 todo 餵送給上述任一池。以追加模式開啟輸出檔案,不要使用寫入模式,否則重新啟動會擦除你的進度。也將錯誤寫入第二個檔案 errors.jsonl,以便在閱讀失敗原因後只重試失敗項。
為了在重跑時獲得可重複的輸出,請傳遞固定的 seed 和低 temperature。seed 會與 top_p、stop 和懲罰一起傳遞給模型。
先在小範圍測試
在運行 20,000 行之前先運行 20 行。選擇包含你最壞情況的行:最長的輸入、包含奇怪字符的輸入、空白的輸入。肉眼檢查輸出,檢查 usage 是否符合你的成本估算,並通過將工作計數暫時提高到限制以上來確認重試輔助函數的行為。你應該在日誌中看到帶有代碼 concurrency 的 429、等待以及成功的重試。在 20 行中看到這些比在第 9,000 行發現要好得多。
如果作業需要結構化輸出,請使用 response_format={"type": "json_object"} 新增 JSON 模式,在提示詞中描述鍵,並在 try 區塊內解析每個回覆。在測試切片中計算解析失敗次數。如果失敗率高於一兩個百分比,通常表示提示詞需要更清晰的架構,現在修復比稍後重跑更便宜。解析失敗的行會以 id 進入 errors.jsonl,恢復邏輯將它們視為未完成。
最後,設定一個適合你預期最長輸出的客戶端超時。SDK 接受客戶端或每個請求的 timeout=60;否則,一個卡住且永不返回的請求將佔用你的 8 個槽位之一,直到它停在那裡。
設定池大小與估算時間
吞吐量受兩件事限制:並行數除以單個請求耗時,以及每分鐘請求數上限。完整金鑰的上限是每分鐘 300 個,即每秒 5 個。如果典型請求耗時 2 秒,8 個工作程式每秒產生 8 / 2 = 4 個請求,或每分鐘 240 個,這低於上限。如果請求耗時 1 秒,8 個工作程式將嘗試每秒 8 個請求並達到上限,因此請增加少量延遲或接受偶爾的 429,由你的重試輔助函數吸收。
以每秒 4 個請求的速度,10,000 行需要 2,500 秒,約 42 分鐘。在試用金鑰上,以 2 個並行請求和每分鐘 60 個為限制,上限為每秒 1 個,因此相同的 10,000 行將需要 10,000 秒,近 2 小時 47 分鐘。實際上,$0.50 試用額度會在那之前耗盡,這使其成為在幾百行上測試腳本的好地方,而不是運行生產環境的地方。
大型批次的成本
定價為每 1M 輸入 token $0.15,每 1M 輸出 token $0.50。考慮分類類型的作業:50,000 行,每行約 200 個輸入 token 和 100 個輸出 token。
- 輸入:50,000 × 200 = 10,000,000 token,即 10 × $0.15 = $1.50。
- 輸出:50,000 × 100 = 5,000,000 token,即 5 × $0.50 = $2.50。
- 總計:$4.00,或每行 $0.00008。
上述腳本為每行記錄 in 和 out,因此你可以從實際運行中計算相同的數字。X-Balance-USD 回應標頭也顯示剩餘額度,X-Request-Id 是在 文件或支援頁面尋求協助時應引用的內容。
額度採整數儲值,金額從 $20 到 $500,儲值 $50 加贈 5%、$100 加贈 10%、$200 加贈 15%,以加密貨幣(TRC20 上的 USDT 或 Base 上的 USDC)支付。額度永不過期。定價頁面有完整資訊。針對敏感資料集的一項說明:提示詞不會用於訓練。
更多指南
問答
API 有批次端點嗎?
沒有。它提供聊天完成和模型列表。你可以透過自己的程式碼並行執行多個一般請求來進行批次處理,上限為 8 個並行請求,每分鐘 300 個請求(針對完整金鑰)。
我應該使用多少個執行緒?
針對完整金鑰使用 8 個工作執行緒,針對試用金鑰使用 2 個,以符合並行限制。更多的工作執行緒只會導致程式碼並行時的 429 錯誤。
收到 HTTP 429 時該怎麼辦?
如果回應中包含 Retry-After 值,請等待該時間;否則,暫停幾秒後再重試。失敗的請求不會計費,因此重試不會產生額外費用。
我可以在批次工作中串流輸出回應嗎?
你可以,但不建議。串流請求會佔用並行槽位直到串流結束,這會降低吞吐量。批次工作請關閉串流輸出。