Batch API: massiline asünkroonne töötlemine
Sellel lehel
Uuendatud 3. novembril 2026, lähtudes Batch API juhendist ja Responses API vastuse struktuurist: tulemuste lugemisel ei eeldata enam, et
outputesimene element on sõnum (sellele võib eelneda põhjenduse element), ja veakoodi võti, mis oli kirjutatud ilma jutumärkideta, põhjustasNameError-i. Allikas: Batch API.
Vaheta latentsus kulude vastu
Batch API põhineb lihtsal turuprintsiibil: nõustud, et sinu päringuid töödeldakse asünkroonselt kuni 24-tunnises aknas, ja vastutasuks maksad 50% vähem. Kõik, mis ei pea teenindama inimest, kes ootab tulemust ekraani ees, kuulub sellesse kategooriasse. Suures mastaabis ei ole see mikrooptimeerimine; see lõikab sinu eelarverea pooleks.
Harjumus, mille meeskonnas kujundada, on küsida iga uue töötlemisülesande puhul, kas keegi ootab tulemust. Aktsiate lepingute analüüs, tootelehtede genereerimine kataloogi jaoks, võrdlustestide käivitamine tuhandete testjuhtumitega, kuuekuuse pileti järjekorra klassifitseerimine, väljade eraldamine arvete partiist: kõigil neil juhtudel maandub vastus armatuurlaual või andmebaasis, mitte vestlusliideses. Viivitus on nähtamatu, kuid sääst ei ole.
Koosta ja käivita partii
Sisendformaadiks on JSONL-fail: üks rida päringu kohta, kus iga rida on täielik ja sõltumatu objekt. Väli custom_id on see, mis võimaldab sul iga vastuse siduda algse päringuga, kuna väljundfaili järjekord ei ole garanteeritud. Vali ID, mis on stabiilne ja tähendusrikas – näiteks dokumendi ID sinu andmebaasist, mitte iteratsiooni number – vastasel juhul muutub vastavusse viimise faas õudusunenäoks.
import json
requests = [
{
"custom_id": f"doc-{i}",
"method": "POST",
"url": "/v1/responses",
"body": {
"model": "gpt-5.6-luna",
"input": f"Summarize this document in 3 key points: {doc}",
"max_output_tokens": 500,
},
}
for i, doc in enumerate(documents_list)
]
# Kirjuta JSONL-fail
with open("batch_input.jsonl", "w") as f:
for request in requests:
f.write(json.dumps(request) + "\n")
Seejärel laaditakse fail üles ja sellele viidatakse partii loomisel. Metaandmetel puudub tehniline eesmärk, kuid need päästavad su nahka, kui kolm partiid töötavad paralleelselt ja pead välja selgitama, milline neist vastab millisele vihje (prompt) versioonile.
import openai
client = openai.OpenAI()
# Laadi fail üles
file_obj = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Loo partii
batch = client.batches.create(
input_file_id=file_obj.id,
endpoint="/v1/responses",
completion_window="24h",
metadata={"project": "contract-analysis", "version": "2.1"},
)
print(f"Batch created: {batch.id}")
print(f"Status: {batch.status}")
Jälgimine hõlmab partii pärimist seni, kuni see lahkub olekust „käimas“, seejärel laaditakse alla väljundfail, mis on samuti JSONL-formaadis. Allpool olev tsükkel eristab kolme lõppolekut – failed, expired, cancelled – ja tõstab ühegi korral erindi: aegunud partii on selline, kus 24-tunnine aken möödus enne, kui kõik oli töödeldud, ja selle käsitlemine vaikiva osalise õnnestumisena oleks halvim variant.
import time
def wait_for_batch(batch_id: str, interval: int = 60) -> list:
"""Ootab partii lõppemist ja tagastab tulemused."""
while True:
batch = client.batches.retrieve(batch_id)
print(
f"Status: {batch.status} | "
f"Completed: {batch.request_counts.completed}/"
f"{batch.request_counts.total} | "
f"Failed: {batch.request_counts.failed}"
)
if batch.status == "completed":
break
elif batch.status in ("failed", "expired", "cancelled"):
raise RuntimeError(f"Batch failed: {batch.status}")
time.sleep(interval)
# Laadi tulemused alla
content = client.files.content(batch.output_file_id)
results = []
for line in content.text.strip().split("\n"):
results.append(json.loads(line))
return results
results = wait_for_batch(batch.id)
# Töötle tulemused
for result in results:
custom_id = result["custom_id"]
response = result["response"]
if response["status_code"] == 200:
# output võib sisaldada enne sõnumit muid elemente
(näiteks põhjendus): otsi sõnumi teksti
text = next(
part["text"]
for item in response["body"]["output"] if item["type"] == "message"
for part in item["content"] if part["type"] == "output_text"
)
print(f"{custom_id}: {text[:100]}...")
else:
print(f"{custom_id}: ERROR {response['status_code']}")
Planeeri osalised tõrked
Suures partiis ebaõnnestuvad mõned päringud: lühendatud dokument, konteksti ületäitumine või mööduv serveripoolne viga. Seetõttu ei ole partii kunagi lihtsalt „õnnestunud“ või „ebaõnnestunud“ – see on osaliselt õnnestunud ja sa pead oskama puuduva osa isoleerida. Kasutatav muster on kohe eraldada õnnestumised ebaõnnestumistest ja genereerida uuesti JSONL-fail, mis on valmis uuesti käivitamiseks, selle asemel et kolm päeva hiljem logides kaevata, et rekonstrueerida, mis puudu on.
def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
"""Eraldab õnnestumised ebaõnnestumistest uuesti töötlemiseks."""
successes = []
failures = []
for r in results:
if r["response"]["status_code"] == 200:
successes.append(r)
else:
failures.append(r)
if failures:
print(f"Warning: {len(failures)} failed requests out of {len(results)}")
# Kirjuta uuesti JSONL-fail ebaõnnestunutega kordamiseks
with open("batch_retry.jsonl", "w") as f:
for failure in failures:
original_request = {
"custom_id": failure["custom_id"],
"method": "POST",
"url": "/v1/responses",
"body": failure["request"]["body"],
}
f.write(json.dumps(original_request) + "\n")
return successes, failures
Korruta oma säästu
Kümne tuhande dokumendi töötlemisel mudeliga GPT-5.6 Luna tähistab sünkroonne API baaskulu, Batch API poolt sellest ja vihje vahemällu salvestamine (prompt caching) lisandub sellele, kuna vahemällu salvestatud tokenid saavad kasu omaenda vähendusest. Need kaks mehhanismi ei konkureeri: kui sinu kümme tuhat päringut jagavad sama pikka süsteemset vihjet, struktureeri see stabiilse prefiksina ja sa saad mõlemad efektid korrutada.
Lõpuks tekib küsimus tükeldamisest. Partii ei tohiks olla lõpmatu ja mugavam on jälgida mitut hallatavat partiid kui ühtainsat monoliiti, mille ebaõnnestumine maksab terve päeva. Järgnev funktsioon lõikab päringute loendi piiratud suurusega partiideks.
def create_optimized_batches(
requests: list[dict],
max_size: int = 50_000,
) -> list[list[dict]]:
"""Jagab optimaalse suurusega partiideks."""
batches = []
current_batch = []
for request in requests:
current_batch.append(request)
if len(current_batch) >= max_size:
batches.append(current_batch)
current_batch = []
if current_batch:
batches.append(current_batch)
return batches
Peamised punktid
- Batch API pakub 50% vähendust mitte-reaalajas töötlemiseks
- Valmista oma päringud ette JSONL-failis, kasutades iga päringu jaoks unikaalset
custom_id - Planeeri ebaõnnestunud päringute jaoks kordusmehhanism
- Kombineeri vihje vahemällu salvestamisega, et maksimeerida säästu