Batch API: Masivní asynchronní zpracování
Na této stránce
Aktualizováno 3. listopadu 2026 na základě příručky Batch API a struktury odpovědí Responses API: čtení výsledků již nepředpokládá, že prvním prvkem
outputje zpráva (může jí předcházet prvek s odůvodněním) a klíč kódu chyby, zapsaný bez uvozovek, vyvolávalNameError. Zdroj: Batch API.
Vyměň latenci za cenu
Batch API funguje na jednoduchém tržním principu: přijmeš fakt, že tvé požadavky budou zpracovány asynchronně v okně až dvaceti čtyř hodin, a výměnou za to zaplatíš o padesát procent méně. Do této kategorie spadá vše, co nemusí obsluhovat člověka čekajícího před obrazovkou. Ve velkém měřítku to není mikrooptimalizace; řeže tvůj rozpočet napůl.
Navykni si v týmu na to, že u každého nového úkolu zpracování se zeptáš, zda někdo čeká na výsledek. Analýza zásoby smluv, generování produktových listů pro katalog, spuštění benchmarku na tisících testovacích případů, klasifikace půlročního backlogu ticketů, extrakce polí z dávky faktur: ve všech těchto případech odpověď končí v dashboardu nebo databázi, nikoliv v konverzačním rozhraní. Zpoždění je neviditelné, ale úspory nikoliv.
Sestavení a spuštění dávky
Vstupním formátem je soubor JSONL: jeden řádek na požadavek, kde každý řádek je kompletní, nezávislý objekt. Pole custom_id je to, co ti umožní spojit každou odpověď zpět s původním požadavkem, protože nic nezaručuje pořadí výstupního souboru. Zvol ID, které je stabilní a smysluplné – ID dokumentu z tvé databáze spíše než číslo iterace – jinak se fáze sesazování změní v noční můru.
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)
]
# Zápis souboru JSONL
with open("batch_input.jsonl", "w") as f:
for request in requests:
f.write(json.dumps(request) + "\n")
Soubor je následně nahrán a reference na něj použita při vytváření dávky. Metadata nemají žádný technický účel, ale zachrání ti kůži, když poběží paralelně tři dávky a budeš muset zjistit, která odpovídá které verzi promptu.
import openai
client = openai.OpenAI()
# Nahrání souboru
file_obj = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Vytvoření dávky
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}")
Monitorování zahrnuje dotazování (polling) dávky, dokud neopustí stav probíhajícího zpracování, a následné stažení výstupního souboru, který je rovněž ve formátu JSONL. Níže uvedená smyčka rozlišuje tři koncové výsledky – failed, expired, cancelled – a pro každý z nich vyvolá výjimku: vypršelá dávka je taková, kde uplynulo dvacet čtyři hodin před dokončením všeho zpracování, a považovat ji za tichý částečný úspěch by byla ta nejhorší možnost.
import time
def wait_for_batch(batch_id: str, interval: int = 60) -> list:
"""Čeká na dokončení dávky a vrací výsledky."""
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)
# Stažení výsledků
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)
# Zpracování výsledků
for result in results:
custom_id = result["custom_id"]
response = result["response"]
if response["status_code"] == 200:
# output může obsahovat jiné prvky před zprávou
# (například odůvodnění): hledej text zprávy
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čítej s částečnými selháními
U velké dávky některé požadavky selžou: useknutý dokument, přetečení kontextu nebo přechodná chyba na straně serveru. Dávka tedy nikdy není jednoduše „úspěšná“ nebo „neúspěšná“ – je částečně úspěšná a ty musíš umět izolovat chybějící část. Vzorem, který je třeba adoptovat, je okamžité oddělení úspěchů od selhání a regenerace souboru JSONL připraveného k opětovnému spuštění, místo aby ses o tři dny později hrabal v logách a rekonstruoval, co chybí.
def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
"""Odděluje úspěchy od selhání pro opětovné zpracování."""
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)}")
# Přepsání souboru JSONL se selháními pro opakování
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 své úspory
Při zpracování deseti tisíc dokumentů s modelem GPT-5.6 Luna představuje synchronní API základní náklady, Batch API polovinu toho a ke tomu se přidává ukládání promptů do mezipaměti (prompt caching), protože tokeny v mezipaměti také těží z vlastní redukce. Tyto dva mechanismy si nekonkurují: pokud tvých deset tisíc požadavků sdílí stejný dlouhý systémový prompt, strukturovej jej jako stabilní prefix a oba efekty se ti násobně sčítají.
Nakonec tu je otázka rozdělování. Dávka by neměla být nekonečná a je pohodlnější monitorovat několik zvládnutelných dávek než jeden monolit, jehož selhání stojí celý den. Následující funkce krájí seznam požadavků na dávky o omezené velikosti.
def create_optimized_batches(
requests: list[dict],
max_size: int = 50_000,
) -> list[list[dict]]:
"""Rozděluje na dávky optimální velikosti."""
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
Klíčové poznatky
- Batch API nabízí 50% snížení ceny pro zpracování mimo reálný čas
- Připrav své požadavky v souboru JSONL s unikátním
custom_idpro každý požadavek - Naplánuj mechanismus opakování pro selhané požadavky
- Zkombinuj s ukládáním promptů do mezipaměti pro maximalizaci úspor