Batch API: masszív aszinkron feldolgozás
Ezen az oldalon
Frissítve: 2026. november 3. a Batch API útmutató és a Responses API válaszstruktúrája alapján: az eredmények olvasása során már nem feltételezzük, hogy az
outputelső eleme az üzenet (megelőzheti egy következtetési elem), továbbá az idézőjelek nélküli hibakód-kulcsNameErrorkivételt dobott. Forrás: Batch API.
Késleltetés cserébe költségcsökkentésért
A Batch API egy egyszerű piaci elven működik: elfogadod, hogy a kéréseid aszinkron módon, legfeljebb huszonnégy órás időablakon belül kerülnek feldolgozásra, cserébe pedig ötven százalékkal kevesebbet fizetsz. Minden olyan feladat ebbe a kategóriába esik, ahol nem kell egy képernyő előtt várakozó embernek azonnal szolgálnia a választ. Nagy léptékben ez nem mikro-optimalizálás; ez a költségvetési sor felére csökkentése.
A csapatban kialakítandó szokás, hogy minden új feldolgozási feladatnál megkérdezd: vár valaki az eredményre? Szerződéskészlet elemzése, termékleírások generálása egy katalógushoz, benchmark futtatása ezerrel tesztelési eseten, hat hónapos jegybacklog osztályozása, mezők kinyerése számlakötegekből: mindezekben az esetekben a válasz egy irányítópulton vagy adatbázisban landol, nem pedig egy beszélgetési felületen. A késés láthatatlan, de a megtakarítás nem.
Köteg létrehozása és indítása
A bemeneti formátum egy JSONL-fájl: soronként egy kérés, ahol minden sor egy teljes, független objektum. A custom_id mező teszi lehetővé, hogy minden választ visszavezess az eredeti kéréshez, mivel semmi nem garantálja a kimeneti fájl sorrendjét. Olyan azonosítót válassz, amely stabil és jelentéssel bír – például egy dokumentumazonosítót az adatbázisodból, ne iterációs számot –, különben az egyeztetési fázis rémálommá válik.
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)
]
# JSONL-fájl írása
with open("batch_input.jsonl", "w") as f:
for request in requests:
f.write(json.dumps(request) + "\n")
A fájlt ezután feltöltöd, és a köteg létrehozásakor hivatkozol rá. A metaadatoknak nincs technikai céljuk, de megmentenek majd, ha három köteg fut párhuzamosan, és ki kell derítened, melyik melyik promptverzióhoz tartozik.
import openai
client = openai.OpenAI()
# Fájl feltöltése
file_obj = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Köteg létrehozása
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}")
A monitorozás addig lekérdezi (polling) a köteget, amíg az ki nem lép a folyamatban lévő állapotból, majd letölti a kimeneti fájlt, amely szintén JSONL formátumú. Az alábbi ciklus három végállapotot különböztet meg – failed, expired, cancelled –, és mindegyikre kivételt dob: a lejárt köteg olyan, ahol a huszonnégy órás ablak letelt, mielőtt mindent feldolgoztak volna, és ezt csendes részleges sikernek kezelni lenne a legrosszabb opció.
import time
def wait_for_batch(batch_id: str, interval: int = 60) -> list:
"""Megvárja, amíg egy köteg befejeződik, és visszaadja az eredményeket."""
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)
# Eredmények letöltése
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)
# Eredmények feldolgozása
for result in results:
custom_id = result["custom_id"]
response = result["response"]
if response["status_code"] == 200:
# az output tartalmazhat más elemeket is az üzenet előtt
# (például következtetés): keressük meg az üzenet szövegét
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']}")
Tervezz részleges hibákra
Nagy kötegeknél egyes kérések sikertelenek lesznek: csonka dokumentum, kontextustúllépés vagy átmeneti szerveroldali hiba miatt. Egy köteg tehát sosem egyszerűen „sikeres“ vagy „sikertelen“ – részlegesen sikeres, és tudnod kell izolálni a hiányzó részt. Az alkalmazandó minta, hogy azonnal szétválaszd a sikereseket a sikertelenektől, és generálj egy újraindítható JSONL-fájlt, ahelyett, hogy három nap múlva naplókat bújnál a hiányzók rekonstruálásához.
def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
"""Szétválasztja a sikereseket és a sikerteleneket az újrafeldolgozáshoz."""
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)}")
# JSONL-fájl újraírása a sikertelenekkel az újrapróbálkozáshoz
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
Halmozd a megtakarítást
Tízezer dokumentum feldolgozása során GPT-5.6 Luna modellel a szinkron API jelenti az alapköltséget, a Batch API ennek a felét, a prompt-gyorsítótárazás pedig ráépül, mivel a gyorsítótárazott tokenek is saját csökkentésben részesülnek. A két mechanizmus nem versenyez egymással: ha a tízezer kérésed ugyanazt a hosszú rendszerpromptot használja, strukturáld azt stabil prefixként, és mindkét hatást halmozni fogod.
Végül ott a felosztás kérdése. Egy köteg ne legyen végtelen, és kényelmesebb több kezelhető köteget monitorozni, mint egyetlen monolitot, amelynek kudarca egy egész napba kerül. Az alábbi függvény kérések listáját vágja fel korlátozott méretű kötegekre.
def create_optimized_batches(
requests: list[dict],
max_size: int = 50_000,
) -> list[list[dict]]:
"""Optimális méretű kötegekre bontja a listát."""
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
Főbb megállapítások
- A Batch API 50%-os költségcsökkentést kínál a nem valós idejű feldolgozáshoz
- Készítsd elő a kéréseidet egy JSONL-fájlban, minden kéréshez egyedi
custom_id-vel - Tervezz újrapróbálkozási mechanizmust a sikertelen kérésekhez
- Kombináld prompt-gyorsítótárazással a maximális megtakarítás érdekében