Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Batch API: Ipproċessar Asinkronu Massiv

Lezzjoni 6 / 20 Aġġornat 3 ta’ Novembru 2026 Avvanzat
F'din il-paġna
  1. Ibbidla bejn il-Latenza u l-Ispejjeż
  2. Ibni u Niedi Lott (Batch)
  3. Ippjana għal Fallimenti Parzjali
  4. Immultiplika l-Iffrankar Tiegħek
  5. Punti Ewlenin

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’ output huwa l-messaġġ (element ta’ raġunament jista’ jippreċedih), u ċ-ċavetta tal-kodiċi tal-iżball, miktuba mingħajr virgoli, qajmet NameError. 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_id uniku għal kull talba
  • Ippjana mekkaniżmu ta’ retry għat-talbiet li jfallu
  • Ikkombina mal-caching tal-prompt biex timmassimizza l-iffrankar