Batch API: Ipproċessar Asinkronu Massiv
F'din il-paġna
Aġġornat fit-3 ta’ Novembru 2026 abbażi tal-gwida tal-Batch API u l-istruttura tar-rispons tal-API tar-Risposti: il-qari tar-riżultati ma jassumix aktar li l-ewwel element ta’
outputhuwa l-messaġġ (element ta’ raġunament jista’ jippreċedih), u ċ-ċavetta tal-kodiċi tal-iżball, miktuba mingħajr virgoli, qajmetNameError. Sors: Batch API.
Ibbidla bejn il-Latenza u l-Ispejjeż
Il-Batch API taħdem fuq prinċipju tas-suq sempliċi: taċċetta li t-talbiet tiegħek se jiġu pproċessati b’mod asinkronu fi ħdan tieqa ta’ sa erbgħa u għoxrin siegħa, u bi skambju, tħallas nofs inqas. Kull ħaġa li ma teħtiġx isservi bniedem li qed jistenna quddiem l-iskrin jaqa’ f’din il-kategorija. Fuq skala kbira, din mhix mikro-ottimizzazzjoni; taqta’ l-linja tal-baġit tiegħek bin-nofs.
Id-drawwa li għandek tibni fi ħdan it-tim hija li tistaqsi, għal kull kompitu ġdid ta’ pproċessar, jekk hemmx xi ħadd qed jistenna r-riżultat. L-analiżi ta’ stokk ta’ kuntratti, il-ġenerazzjoni ta’ skedi tal-prodott għal katalogu, it-tħaddim ta’ benchmark fuq eluf ta’ każijiet ta’ test, il-klassifikazzjoni ta’ backlog ta’ sitt xhur ta’ biljetti, l-estrazzjoni ta’ oqsma minn lott ta’ fatturi: fil-każijiet kollha dawn, it-tweġiba tispiċċa f’dashboard jew f’database, mhux f’interfaċċa konversazzjonali. Id-dewmien huwa inviżibbli, iżda l-iffrankar le.
Ibni u Niedi Lott (Batch)
Il-format tal-input huwa fajl JSONL: linja waħda għal kull talba, fejn kull linja hija oġġett sħiħ u indipendenti. Il-qasam custom_id huwa dak li jippermettilek tgħaqqad kull rispons mal-ħaġa oriġinali tiegħu, peress li xejn ma jiggarantixxi l-ordni tal-fajl tal-output. Agħżel ID li huwa stabbli u sinifikanti—ID ta’ dokument mill-database tiegħek minflok numru ta’ iterazzjoni—inkella l-fażi ta’ rikonċiljazzjoni se ssir nightmare.
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")
Il-fajl imbagħad jitgħabba u jiġi referenzjat meta tinħoloq il-batch. Il-metadata ma sservi l-ebda skop tekniku, iżda se ssavvak il-ġurnata meta jkunu qed jaħdmu tliet batches paralleli u jkollok bżonn issib liema waħda tikkorrispondi ma’ liema verżjoni tal-prompt.
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}")
Il-monitoraġġ jinvolvi li tagħmel polling tal-batch sakemm toħroġ mill-istat “in-progress”, imbagħad tniżżel il-fajl tal-output, li huwa wkoll fil-format JSONL. Il-linja hawn taħt tiddistingwi tliet riżultati terminali—failed, expired, cancelled—u tqajjem eċċezzjoni għal kull wieħed: batch skaduta hija waħda fejn it-tieqa ta’ erbgħa u għoxrin siegħa għaddiet qabel ma kollox ġie pproċessat, u t-trattament tagħha bħala suċċess parzjali silenzjuż ikun l-agħar għażla.
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']}")
Ippjana għal Fallimenti Parzjali
Fuq batch kbira, xi talbiet se jfallu: dokument imqatta’, overflow tal-kuntest, jew żball tranżitorju fuq in-naħa tas-server. Għalhekk, batch qatt ma tkun sempliċiment “suċċess” jew “falliment”—hija parzjalment suċċess, u trid tkun taf kif tiżola l-parti nieqsa. Il-mudell li għandek tadotta huwa li minnufih tissepara s-suċċessi mill-fallimenti u terġa’ tiġġenera fajl JSONL lest biex jerġa’ jitnieda, minflok ma tfittex fil-logs tlett ijiem wara biex tirrikostruwixxi x’inhu nieqes.
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
Immultiplika l-Iffrankar Tiegħek
Fuq ġirja ta’ pproċessar ta’ għaxart elef dokument b’GPT-5.6 Luna, l-API sinkrona tirrappreżenta l-ispiża bażi, il-Batch API tirrappreżenta nofs dik, u l-caching tal-prompt jiżdied fuqhom peress li t-tokens cached jibbenefikaw ukoll mit-tnaqqis tagħhom stess. Iż-żewġ mekkaniżmi ma jikkompetux: jekk l-għaxart elef talba tiegħek jaqsmu l-istess prompt tas-sistema twil, strutturah bħala prefiss stabbli u se timmultiplika ż-żewġ effetti.
Fl-aħħar nett, hemm il-mistoqsija tad-diviżjoni. Batch m’għandhiex tkun infinita, u huwa aktar komdu li timmonitorja diversi batches maniġġabbli minflok monolit wieħed li l-falliment tiegħu jiswa ġurnata sħiħa. Il-funzjoni li ġejja taqsam lista ta’ talbiet f’batches ta’ daqs limitat.
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
Punti Ewlenin
- Il-Batch API toffri tnaqqis ta’ 50% għall-ipproċessar mhux f’ħin reali
- Ipprepara t-talbiet tiegħek f’fajl JSONL b’
custom_iduniku għal kull talba - Ippjana mekkaniżmu ta’ retry għat-talbiet li jfallu
- Ikkombina mal-caching tal-prompt biex timmassimizza l-iffrankar