Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Batch API: Masovna asinkrona obrada

Lekcija 6 od 20 Ažurirano 3. studenoga 2026. Napredno
Na ovoj stranici
  1. Zamijeni kašnjenje troškom
  2. Izgradi i pokreni batch
  3. Planiraj djelomične neuspjehe
  4. Umnoži svoje uštede
  5. Ključne točke

Ažurirano 3. studenoga 2026. na temelju vodiča za Batch API i strukture odgovora Responses API-ja: čitanje rezultata više ne pretpostavlja da je prvi element u output poruka (ispred nje može stajati element za rezoniranje), a ključ koda pogreške, zapisan bez navodnika, izazivao je NameError. Izvor: Batch API.

Zamijeni kašnjenje troškom

Batch API funkcionira na jednostavnom tržišnom načelu: prihvaćaš da će se tvoji zahtjevi obrađivati asinkrono unutar vremenskog okvira od do dvadeset i četiri sata, a zauzvrat plaćaš pedeset posto manje. Sve što ne mora služiti čovjeku koji čeka ispred ekrana spada u ovu kategoriju. U velikim razmjerima to nije mikrooptimizacija; to prepolavlja tvoj proračun.

Navika koju trebaš izgraditi u timu jest da za svaki novi zadatak obrade zapitaš čeka li netko na rezultat. Analiza zalihe ugovora, generiranje specifikacija proizvoda za katalog, pokretanje benchmarka na tisućama testnih slučajeva, klasifikacija šestomjesečne zaostale liste tiketa, ekstrakcija polja iz serije računa: u svim tim slučajevima odgovor završava na nadzornoj ploči ili u bazi podataka, a ne u sučelju za razgovor. Kašnjenje je nevidljivo, ali uštede nisu.

Izgradi i pokreni batch

Ulazni format je JSONL datoteka: jedan redak po zahtjevu, gdje je svaki redak potpun i neovisan objekt. Polje custom_id ono je što ti omogućuje povezivanje svakog odgovora s izvornim zahtjevom, jer ništa ne jamči redoslijed izlazne datoteke. Odaberi ID koji je stabilan i smislen – ID dokumenta iz tvoje baze podataka umjesto broja iteracije – inače će faza usklađivanja postati noćna mora.

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

Datoteka se zatim učitava i referencira prilikom stvaranja batcha. Metapodaci nemaju tehničku svrhu, ali spasit će ti dan kada tri batcha rade paralelno, a trebaš otkriti koji odgovara kojoj verziji prompta.

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}")

Praćenje uključuje ispitivanje (polling) batcha dok ne izađe iz stanja „u tijeku“, a zatim preuzimanje izlazne datoteke, koja je također u JSONL formatu. Donja petlja razlikuje tri završna ishoda – failed, expired, cancelled – i za svaki podiže iznimku: istekli batch je onaj kod kojeg je dvadesetčetverosatni prozor istekao prije nego što je sve obrađeno, a tretiranje toga kao tihe djelomične uspješnosti bila bi najgora opcija.

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']}")

Planiraj djelomične neuspjehe

U velikom batchu neki će zahtjevi neuspjeti: skraćeni dokument, prelazak konteksta ili prolazna pogreška na strani poslužitelja. Batch stoga nikada nije jednostavno „uspješan“ ili „neuspješan“ – on je djelomično uspješan, i moraš znati izolirati onaj dio koji nedostaje. Uzorak koji trebaš usvojiti jest trenutno odvajanje uspjeha od neuspjeha i ponovno generiranje JSONL datoteke spremne za ponovno pokretanje, umjesto da tri dana kasnije kopaš po zapisnicima kako bi rekonstruirao što nedostaje.

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

Umnoži svoje uštede

Tijekom obrade deset tisuća dokumenata s GPT-5.6 Luna, sinkroni API predstavlja osnovni trošak, Batch API predstavlja polovicu toga, a keširanje prompta dodaje se na to jer i keširani tokeni imaju korist od vlastitog smanjenja. Ta dva mehanizma se ne natječu: ako tvojih deset tisuća zahtjeva dijeli isti dugi sistemski prompt, strukturiraj ga kao stabilni prefiks i umnožit ćeš oba efekta.

Konačno, tu je pitanje dijeljenja. Batch ne smije biti beskonačan, a ugodnije je pratiti nekoliko upravljivih batcheva nego jedan monolit čiji neuspjeh košta cijeli dan. Sljedeća funkcija reže popis zahtjeva na batcheve ograničene veličine.

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

Ključne točke

  • Batch API nudi smanjenje od 50 % za obradu koja nije u stvarnom vremenu
  • Pripremi svoje zahtjeve u JSONL datoteci s jedinstvenim custom_id za svaki zahtjev
  • Planiraj mehanizam ponovnog pokušaja za neuspjele zahtjeve
  • Kombiniraj s keširanjem prompta kako bi maksimizirao uštede