繁中 ▾

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 值,請等待該時間;否則,暫停幾秒後再重試。失敗的請求不會計費,因此重試不會產生額外費用。

我可以在批次工作中串流輸出回應嗎?

你可以,但不建議。串流請求會佔用並行槽位直到串流結束,這會降低吞吐量。批次工作請關閉串流輸出。

你的金鑰只差一步即可取得

建立帳號、複製金鑰、更改基礎 URL。這就是整個設定過程。

取得 API 金鑰