Batch API: apstrāde masveidā asinhroni
Šajā lapā
Atjaunināts 2026. gada 3. novembrī, pamatojoties uz Batch API rokasgrāmatu un Responses API atbildes struktūru: rezultātu lasīšana vairs nepieņem, ka
outputpirmais elements ir ziņojums (pirms tā var būt spriešanas elements), un kļūdas koda atslēga, rakstīta bez pēdiņām, izraisījaNameError. Avots: Batch API.
Apmaini latentumu pret izmaksām
Batch API darbojas pēc vienkārša tirgus principa: tu piekrīti, ka tavi pieprasījumi tiks apstrādāti asinhroni 24 stundu logā, un pretī saņem 50 % zemāku cenu. Viss, kam nav jākalpo cilvēkam, kas gaida pie ekrāna, ietilpst šajā kategorijā. Mērogā tas nav mikrooptimizējums; tas pārgriež tavu budžeta līniju uz pusēm.
Ieradums, kas jāieaudzina komandā, ir jautāt par katru jaunu apstrādes uzdevumu: vai kāds gaida rezultātu? Krājuma līgumu analīze, produktu lapu ģenerēšana katalogam, etalonu palaišana tūkstošiem testa gadījumu, sešu mēnešu biļešu uzkrājuma klasificēšana, lauku ekstrakcija no rēķinu partijas: visos šajos gadījumos atbilde nonāk informācijas panelī vai datubāzē, nevis sarunu saskarnē. Aizkave ir neredzama, bet ietaupījumi – nē.
Izveido un palaid partiju
Ievades formāts ir JSONL fails: viena rinda vienam pieprasījumam, kur katra rinda ir pilnīgs, neatkarīgs objekts. Lauks custom_id ir tas, kas ļauj katru atbildi saistīt atpakaļ ar sākotnējo pieprasījumu, jo nekas negarantē izejas faila secību. Izvēlies ID, kas ir stabils un jēdzīgs – dokumenta ID no tavas datubāzes, nevis iterācijas numurs – pretējā gadījumā saskaņošanas posms pārvērtīsies murgā.
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)
]
# Raksta JSONL failu
with open("batch_input.jsonl", "w") as f:
for request in requests:
f.write(json.dumps(request) + "\n")
Failu pēc tam augšupielādē un norāda, veidojot partiju. Metadatiem nav tehniska nolūka, taču tie glābs tevi dienā, kad paralēli darbojas trīs partijas un tev jānoskaidro, kura atbilst kurai uzvednes versijai.
import openai
client = openai.OpenAI()
# Augšupielādē failu
file_obj = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Izveido partiju
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}")
Uzraudzība ietver partijas aptauju, līdz tā iziet no „in-progress” stāvokļa, pēc tam lejupielādē izejas failu, kas arī ir JSONL formātā. Tālāk redzamais cikls nošķir trīs terminālos iznākumus – failed, expired, cancelled – un katram izvirza izņēmumu: beigusies partija ir tāda, kurā 24 stundu logs beidzies, pirms viss tika apstrādāts, un uzskatīt to par klusu daļēju panākumu būtu sliktākais variants.
import time
def wait_for_batch(batch_id: str, interval: int = 60) -> list:
"""Gaida, līdz partija pabeigta, un atgriež rezultātus."""
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)
# Lejupielādē rezultātus
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)
# Apstrādā rezultātus
for result in results:
custom_id = result["custom_id"]
response = result["response"]
if response["status_code"] == 200:
# output var saturēt citus elementus pirms ziņojuma
# (piemēram, spriešanu): meklē ziņojuma tekstu
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']}")
Plāno daļējas kļūmes
Lielā partijā daži pieprasījumi neizdosies: nocirsts dokuments, konteksta pārsniegums vai pārejoša servera kļūda. Tāpēc partija nekad nav vienkārši „veiksmīga” vai „neveiksmīga” – tā ir daļēji veiksmīga, un tev jāprot izolēt trūkstošo daļu. Pieņemamais paraugs ir uzreiz atdalīt veiksmīgos no neveiksmīgajiem un ģenerēt jaunu JSONL failu, kas gatavs atkārtotai palaišanai, nevis trīs dienas vēlāk rakņāties žurnālos, lai rekonstruētu trūkstošo.
def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
"""Atdala veiksmīgos no neveiksmīgajiem atkārtotai apstrādei."""
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ārraksta JSONL failu ar neveiksmīgajiem atkārtotai mēģinājumam
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
Reizini ietaupījumus
Apstrādes sesijā ar desmit tūkstošiem dokumentu, izmantojot GPT-5.6 Luna, sinhronais API ir bāzes izmaksas, Batch API ir puse no tām, un uzvednes kešošana nāk virsū, jo arī kešotie tokeni gūst labumu no savas samazināšanas. Abi mehānismi nesacenšas: ja tavi desmit tūkstoši pieprasījumu koplieto vienu un to pašu garo sistēmas uzvedni, strukturē to kā stabilu prefiksu, un tu reizināsi abus efektus.
Visbeidzot, ir jautājums par sadalīšanu. Partijai nevajadzētu būt bezgalīgai, un ērtāk ir uzraudzīt vairākas pārvaldāmas partijas, nevis vienu monolītu, kura kļūme izmaksā veselu dienu. Tālāk redzamā funkcija sadala pieprasījumu sarakstu ierobežota izmēra partijās.
def create_optimized_batches(
requests: list[dict],
max_size: int = 50_000,
) -> list[list[dict]]:
"""Sadalās optimāla izmēra partijās."""
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
Galvenās atziņas
- Batch API piedāvā 50 % samazinājumu apstrādei, kurai nav nepieciešams reāllaiks
- Sagatavo pieprasījumus JSONL failā ar unikālu
custom_idkatram pieprasījumam - Izplāno atkārtotas mēģināšanas mehānismu neveiksmīgiem pieprasījumiem
- Kombinē ar uzvednes kešošanu, lai maksimāli palielinātu ietaupījumus