Batch API: Masívne asynchrónne spracovanie
Na tejto strane
Aktualizované 3. novembra 2026 na základe príručky Batch API a štruktúry odpovede Responses API: čítanie výsledkov už nepredpokladá, že prvým prvkom v
outputje správa (môže mu predchádzať prvok s odôvodnením) a kľúč kódu chyby, zapísaný bez úvodzoviek, vyvolával výnimkuNameError. Zdroj: Batch API.
Vymeň latenciu za cenu
Batch API funguje na jednoduchom trhovom princípe: akceptuješ, že tvoje požiadavky budú spracované asynchrónne v okne až dvadsiatich štyroch hodín, a výmenou za to zaplatíš o päťdesiat percent menej. Všetko, čo nemusí obslúžiť človeka čakajúceho pred obrazovkou, spadá do tejto kategórie. Vo veľkom meradle to nie je mikrooptimalizácia; prereže ti rozpočtovú líniu napoly.
Návyk, ktorý si musíš v tíme vybudovať, je pýtať sa pri každej novej úlohe spracovania, či niekto čaká na výsledok. Analýza zásob zmlúv, generovanie produktových listov pre katalóg, spustenie benchmarku na tisíckach testovacích prípadov, klasifikácia šesťmesačného backlogu ticketov, extrakcia polí z dávky faktúr: vo všetkých týchto prípadoch končí odpoveď v dashboarde alebo databáze, nie v konverzačnom rozhraní. Oneskorenie je neviditeľné, ale úspory nie.
Vytvorenie a spustenie dávky
Vstupný formát je súbor JSONL: jeden riadok na požiadavku, kde každý riadok je úplný, nezávislý objekt. Pole custom_id je to, čo ti umožňuje prepojiť každú odpoveď späť s pôvodnou požiadavkou, keďže nič nezaručuje poradie vo výstupnom súbore. Vyber ID, ktoré je stabilné a zmysluplné – ID dokumentu z tvojej databázy namiesto čísla iterácie – inak sa fáza zosúladenia zmení na nočnú moru.
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)
]
# Write the JSONL file
with open("batch_input.jsonl", "w") as f:
for request in requests:
f.write(json.dumps(request) + "\n")
Súbor sa následne nahraje a použije pri vytváraní dávky. Metadáta nemajú žiadny technický účel, ale zachránia ti deň, keď budú bežať tri dávky paralelne a budeš potrebovať zistiť, ktorá zodpovedá ktorej verzii promptu.
import openai
client = openai.OpenAI()
# Upload the file
file_obj = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Create the batch
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}")
Monitorovanie zahŕňa periodické zisťovanie stavu dávky (polling), kým neopustí stav prebiehajúceho spracovania, a následné stiahnutie výstupného súboru, ktorý je tiež vo formáte JSONL. Nižšie uvedená slučka rozlišuje tri konečné výsledky – failed, expired, cancelled – a pre každý z nich vyvolá výnimku: expirovaná dávka je taká, kde uplynulo dvadsaťštyrihodinové okno skôr, než sa všetko spracovalo, a považovať to za tichý čiastočný úspech by bola najhoršia možnosť.
import time
def wait_for_batch(batch_id: str, interval: int = 60) -> list:
"""Waits for a batch to finish and returns the results."""
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)
# Download results
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)
# Process results
for result in results:
custom_id = result["custom_id"]
response = result["response"]
if response["status_code"] == 200:
# output may contain other elements before the message
# (reasoning, for example): look for the message text
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']}")
Počítaj s čiastočnými zlyhaniami
Pri veľkej dávke niektoré požiadavky zlyhajú: orezaný dokument, prekročenie kontextu alebo prechodná chyba na strane servera. Dávka preto nikdy nie je jednoducho „úspešná“ alebo „neúspešná“ – je čiastočne úspešná a musíš vedieť, ako izolovať chýbajúcu časť. Vzorec, ktorý treba adoptovať, je okamžité oddelenie úspechov od zlyhaní a regenerácia súboru JSONL pripraveného na opätovné spustenie, namiesto hrabania sa v logoch o tri dni neskôr, aby si zrekonštruoval, čo chýba.
def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
"""Separates successes from failures for reprocessing."""
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)}")
# Rewrite a JSONL file with failures for retry
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
Násob svoje úspory
Pri behu spracovania desiatich tisíc dokumentov s modelom GPT-5.6 Luna predstavuje synchronné API základnú cenu, Batch API predstavuje polovicu z toho a kešovanie promptov pridáva ďalšie úspory navyše, keďže aj kešované tokeny benefitujú z vlastného zníženia. Tieto dva mechanizmy si nekonkurujú: ak sa tvojich desaťtisíc požiadaviek delí o rovnaký dlhý systémový prompt, štruktúruj ho ako stabilnú predponu a dosiahneš kumulatívny efekt oboch mechanizmov.
Nakoniec tu je otázka rozdelenia. Dávka by nemala byť nekonečná a je pohodlnejšie monitorovať niekoľko zvládnuteľných dávok než jeden monolit, ktorého zlyhanie stojí celý deň. Nasledujúca funkcia rozdeľuje zoznam požiadaviek na dávky ohraničenej veľkosti.
def create_optimized_batches(
requests: list[dict],
max_size: int = 50_000,
) -> list[list[dict]]:
"""Splits into batches of optimal size."""
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
Kľúčové poznatky
- Batch API ponúka 50 % zníženie ceny pre spracovanie, ktoré nie je v reálnom čase
- Priprav svoje požiadavky v súbore JSONL s jedinečným
custom_idpre každú požiadavku - Naplánuj si mechanizmus opakovania pre zlyhané požiadavky
- Skombinuj to s kešovaním promptov pre maximalizáciu úspor