Batch API: masinis asinchroninis apdorojimas
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 3 d. pagal Batch API gairę ir Responses API atsako struktūrą: rezultatų skaitymas nebelaiko, kad pirmasis
outputelementas yra žinutė (prieš ją gali būti samprotavimo elementas), o klaidos kodo raktas, parašytas be kabučių, sukėlėNameError. Šaltinis: Batch API.
Keiskite delsą į kainą
Batch API veikia pagal paprastą rinkos principą: jūs sutinkate, kad jūsų užklausos bus apdorotos asinchroniškai per iki dvidešimt keturių valandų langą, o mainais mokate penkiasdešimčia procentų mažiau. Viskas, ko nereikia pateikti žmogui, laukiančiam prie ekrano, patenka į šią kategoriją. Dideliu mastu tai nėra mikrooptimizacija; tai perpus sumažina jūsų biudžetą.
Įprotis, kurį turite ugdyti komandoje: kiekvienai naujai apdorojimo užduočiai klauskite, ar kas nors laukia rezultato. Akcijų portfelio analizė, produkto aprašymų generavimas katalogui, tūkstančių testų atvejų etaloninis vertinimas, šešių mėnesių bilietų eilės klasifikavimas, laukų ištraukimas iš sąskaitų faktūrų partijos: visais šiais atvejais atsakymas atsiduria skydellyje arba duomenų bazėje, o ne pokalbio sąsajoje. Delsa nematoma, o sutaupymai – akivaizdūs.
Sukurkite ir paleiskite partiją
Įvesties formatas yra JSONL failas: viena eilutė vienai užklausai, kur kiekviena eilutė yra pilnas, nepriklausomas objektas. Laukas custom_id leidžia susieti kiekvieną atsaką su originalia užklausa, nes niekas negarantuoja išvesties failo eiliškumo. Pasirinkite stabilų ir prasmingą ID – dokumento ID iš savo duomenų bazės, o ne iteracijos numerį – kitaip suderinimo etapas taps кошmaru.
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")
Tada failas įkeliamas ir nurodomas kuriant partiją. Metaduomenys neturi techninės paskirties, tačiau jie jums labai pravers, kai trys partijos veiks lygiagrečiai ir reikės išsiaiškinti, kuri iš jų atitinka kurią raginimo (prompt) versiją.
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}")
Stebėjimas apima partijos būsenos tikrinimą, kol ji išeina iš „vykdoma“ būsenos, tada atsisiunčiamas išvesties failas, kuris taip pat yra JSONL formato. Toliau pateikta kilpa išskiria tris galutines baigtis – failed, expired, cancelled – ir kiekvienai iš jų išmeta išimtį: pasibaigusi partija yra ta, kurios dvidešimt keturių valandų langas baigėsi prieš viską apdorojant, ir laikyti tai tyliu daliniu sėkmingumu būtų blogiausias pasirinkimas.
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']}")
Planuokite dalinius gedimus
Didelėje partijoje kai kurios užklausos nepavyks: nutrūkęs dokumentas, konteksto perpildymas arba laikina serverio klaida. Todėl partija niekada nėra tiesiog „sėkminga“ arba „nepavykusi“ – ji yra iš dalies sėkminga, ir jūs turite mokėti išskirti trūkstamą dalį. Priimtinas modelis yra iškart atskirti sėkmes nuo nesėkmių ir sugeneruoti JSONL failą, paruoštą paleisti iš naujo, o ne po trijų dienų knaisiotis žurnaluose, norint rekonstruoti, ko trūksta.
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
Dauginkite savo sutaupymus
Apdorojant dešimt tūkstančių dokumentų su GPT-5.6 Luna, sinchroninis API yra bazinė kaina, Batch API sudaro jos pusę, o raginimų talpykla (prompt caching) pridedama viršuje, nes talpykloje esantys tokenai taip pat gauna savo sumažinimą. Šie du mechanizmai nekonkuruoja: jei jūsų dešimt tūkstančių užklausų dalijasi tuo pačiu ilgu sistemos raginimu, sustruktūruokite jį kaip stabilų priešdėlį ir gausite abiejų efektų sumą.
Galiausiai kyla skaidymo klausimas. Partija neturi būti begalinė, ir patogiau stebėti kelias valdomas partijas nei vieną monolitą, kurio gedimas kainuoja visą dieną. Toliau pateikta funkcija suskaido užklausų sąrašą į riboto dydžio partijas.
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
Svarbiausi punktai
- Batch API siūlo 50 % sumažinimą ne realiuoju laiku vykdomam apdorojimui
- Paruoškite savo užklausas JSONL faile su unikaliu
custom_idkiekvienai užklausai - Suplanuokite kartojimo mechanizmą nepavykusioms užklausoms
- Derinkite su raginimų talpykla (prompt caching), kad maksimaliai padidintumėte sutaupymus