Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Batch API: massiline asünkroonne töötlemine

Õppetund 6 / 20 Värskendatud 3. november 2026 Edasijõudnutele
Sellel lehel
  1. Vaheta latentsus kulude vastu
  2. Koosta ja käivita partii
  3. Planeeri osalised tõrked
  4. Korruta oma säästu
  5. Peamised punktid

Uuendatud 3. novembril 2026, lähtudes Batch API juhendist ja Responses API vastuse struktuurist: tulemuste lugemisel ei eeldata enam, et output esimene element on sõnum (sellele võib eelneda põhjenduse element), ja veakoodi võti, mis oli kirjutatud ilma jutumärkideta, põhjustas NameError-i. Allikas: Batch API.

Vaheta latentsus kulude vastu

Batch API põhineb lihtsal turuprintsiibil: nõustud, et sinu päringuid töödeldakse asünkroonselt kuni 24-tunnises aknas, ja vastutasuks maksad 50% vähem. Kõik, mis ei pea teenindama inimest, kes ootab tulemust ekraani ees, kuulub sellesse kategooriasse. Suures mastaabis ei ole see mikrooptimeerimine; see lõikab sinu eelarverea pooleks.

Harjumus, mille meeskonnas kujundada, on küsida iga uue töötlemisülesande puhul, kas keegi ootab tulemust. Aktsiate lepingute analüüs, tootelehtede genereerimine kataloogi jaoks, võrdlustestide käivitamine tuhandete testjuhtumitega, kuuekuuse pileti järjekorra klassifitseerimine, väljade eraldamine arvete partiist: kõigil neil juhtudel maandub vastus armatuurlaual või andmebaasis, mitte vestlusliideses. Viivitus on nähtamatu, kuid sääst ei ole.

Koosta ja käivita partii

Sisendformaadiks on JSONL-fail: üks rida päringu kohta, kus iga rida on täielik ja sõltumatu objekt. Väli custom_id on see, mis võimaldab sul iga vastuse siduda algse päringuga, kuna väljundfaili järjekord ei ole garanteeritud. Vali ID, mis on stabiilne ja tähendusrikas – näiteks dokumendi ID sinu andmebaasist, mitte iteratsiooni number – vastasel juhul muutub vastavusse viimise faas õudusunenäoks.

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)
]

# Kirjuta JSONL-fail
with open("batch_input.jsonl", "w") as f:
    for request in requests:
        f.write(json.dumps(request) + "\n")

Seejärel laaditakse fail üles ja sellele viidatakse partii loomisel. Metaandmetel puudub tehniline eesmärk, kuid need päästavad su nahka, kui kolm partiid töötavad paralleelselt ja pead välja selgitama, milline neist vastab millisele vihje (prompt) versioonile.

import openai

client = openai.OpenAI()

# Laadi fail üles
file_obj = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

# Loo partii
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}")

Jälgimine hõlmab partii pärimist seni, kuni see lahkub olekust „käimas“, seejärel laaditakse alla väljundfail, mis on samuti JSONL-formaadis. Allpool olev tsükkel eristab kolme lõppolekut – failed, expired, cancelled – ja tõstab ühegi korral erindi: aegunud partii on selline, kus 24-tunnine aken möödus enne, kui kõik oli töödeldud, ja selle käsitlemine vaikiva osalise õnnestumisena oleks halvim variant.

import time

def wait_for_batch(batch_id: str, interval: int = 60) -> list:
    """Ootab partii lõppemist ja tagastab tulemused."""
    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)

    # Laadi tulemused alla
    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)

# Töötle tulemused
for result in results:
    custom_id = result["custom_id"]
    response = result["response"]
    if response["status_code"] == 200:
        # output võib sisaldada enne sõnumit muid elemente
        (näiteks põhjendus): otsi sõnumi teksti
        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']}")

Planeeri osalised tõrked

Suures partiis ebaõnnestuvad mõned päringud: lühendatud dokument, konteksti ületäitumine või mööduv serveripoolne viga. Seetõttu ei ole partii kunagi lihtsalt „õnnestunud“ või „ebaõnnestunud“ – see on osaliselt õnnestunud ja sa pead oskama puuduva osa isoleerida. Kasutatav muster on kohe eraldada õnnestumised ebaõnnestumistest ja genereerida uuesti JSONL-fail, mis on valmis uuesti käivitamiseks, selle asemel et kolm päeva hiljem logides kaevata, et rekonstrueerida, mis puudu on.

def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
    """Eraldab õnnestumised ebaõnnestumistest uuesti töötlemiseks."""
    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)}")
        # Kirjuta uuesti JSONL-fail ebaõnnestunutega kordamiseks
        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

Korruta oma säästu

Kümne tuhande dokumendi töötlemisel mudeliga GPT-5.6 Luna tähistab sünkroonne API baaskulu, Batch API poolt sellest ja vihje vahemällu salvestamine (prompt caching) lisandub sellele, kuna vahemällu salvestatud tokenid saavad kasu omaenda vähendusest. Need kaks mehhanismi ei konkureeri: kui sinu kümme tuhat päringut jagavad sama pikka süsteemset vihjet, struktureeri see stabiilse prefiksina ja sa saad mõlemad efektid korrutada.

Lõpuks tekib küsimus tükeldamisest. Partii ei tohiks olla lõpmatu ja mugavam on jälgida mitut hallatavat partiid kui ühtainsat monoliiti, mille ebaõnnestumine maksab terve päeva. Järgnev funktsioon lõikab päringute loendi piiratud suurusega partiideks.

def create_optimized_batches(
    requests: list[dict],
    max_size: int = 50_000,
) -> list[list[dict]]:
    """Jagab optimaalse suurusega partiideks."""
    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

Peamised punktid

  • Batch API pakub 50% vähendust mitte-reaalajas töötlemiseks
  • Valmista oma päringud ette JSONL-failis, kasutades iga päringu jaoks unikaalset custom_id
  • Planeeri ebaõnnestunud päringute jaoks kordusmehhanism
  • Kombineeri vihje vahemällu salvestamisega, et maksimeerida säästu