Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Batch API: obdelava velikih količin podatkov asinhrono

Lekcija 6 od 20 Posodobljeno 3. november 2026 Napredni
Na tej strani
  1. Zamenjaj zakasnitev za stroške
  2. Izgradi in zaženi paket (Batch)
  3. Načrtuj delne napake
  4. Pomnoži svoje prihranke
  5. Ključne ugotovitve

Posodobljeno 3. novembra 2026 na podlagi vodnika Batch API in strukture odgovorov Responses API: branje rezultatov ne predpostavlja več, da je prvi element v output sporočilo (pred njim je lahko element za razmišljanje), ključ kode napake pa je bil zapisan brez narekovajev, kar je povzročilo NameError. Vir: Batch API.

Zamenjaj zakasnitev za stroške

Batch API deluje na preprostem tržnem načelu: sprejmeš, da bodo tvoji zahtevki obdelani asinhrono v časovnem oknu do štiriindvajset ur, v zameno pa plačaš petdeset odstotkov manj. Vse, kar ne potrebuje takojšnjega odziva za človeka, ki čaka pred zaslonom, spada v to kategorijo. Pri velikem obsegu to ni mikroomilitev; tvoj proračun prepolovi.

Navada, ki jo moraš vzgojiti v ekipi, je, da se pri vsaki novi nalogi obdelave vprašaš, ali nekdo čaka na rezultat. Analiza zaloge pogodb, generiranje opisov izdelkov za katalog, izvajanje benchmarka na tisočih testnih primerih, razvrščanje šestmesečnega zaostanka vstopnic, ekstrakcija polj iz serije računov: v vseh teh primerih odgovor pristane v nadzorni plošči ali bazi podatkov, ne v pogovornem vmesniku. Zakasnitev je nevidna, prihranki pa ne.

Izgradi in zaženi paket (Batch)

Vhodni format je datoteka JSONL: ena vrstica na zahtevek, kjer je vsaka vrstica popoln, neodvisen objekt. Polje custom_id je tisto, ki ti omogoča povezavo vsakega odgovora z njegovim izvirnim zahtevkom, saj nič ne zagotavlja vrstnega reda izhodne datoteke. Izberi ID, ki je stabilen in smiseln – ID dokumenta iz tvoje baze podatkov namesto številke iteracije – sicer bo faza usklajevanja postala 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)
]

# Zapiši datoteko JSONL
with open("batch_input.jsonl", "w") as f:
    for request in requests:
        f.write(json.dumps(request) + "\n")

Datoteko nato naložiš in nanjo sklicuješ pri ustvarjanju paketa. Metapodatki nimajo tehničnega namena, rešili pa ti bodo kožo, ko bodo vzporedno tekli trije paketi in boš moral ugotoviti, kateri ustreza kateri različici poziva.

import openai

client = openai.OpenAI()

# Naloži datoteko
file_obj = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

# Ustvari paket
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}")

Spremljanje vključuje periodično preverjanje stanja paketa, dokler ne zapusti stanja „v teku”, nato pa prenos izhodne datoteke, ki je prav tako v formatu JSONL. Spodnja zanka razlikuje tri končne izide – failed, expired, cancelled – in za vsakega sproži izjemo: potekel paket je tisti, pri katerem je štiriindvajseturno okno preteklo, preden je bilo vse obdelano, in obravnavanje tega kot tihega delnega uspeha bi bila najslabša možnost.

import time

def wait_for_batch(batch_id: str, interval: int = 60) -> list:
    """Počaka, da se paket konča, in vrne rezultate."""
    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)

    # Prenesi rezultate
    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)

# Obdelaj rezultate
for result in results:
    custom_id = result["custom_id"]
    response = result["response"]
    if response["status_code"] == 200:
        # output lahko vsebuje druge elemente pred sporočilom
        # (npr. razmišljanje): poišči besedilo sporočila
        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']}")

Načrtuj delne napake

Pri velikem paketu bodo nekateri zahtevki spodleteli: okrnjen dokument, prekoračitev konteksta ali prehodna napaka na strani strežnika. Paket zato nikoli ni preprosto „uspešen” ali „neuspešen” – delno je uspešen in znati moraš izolirati manjkajoči del. Vzorec, ki ga moraš sprejeti, je takojšnje ločevanje uspehov od napak in ponovno generiranje datoteke JSONL, pripravljene za ponovni zagon, namesto da bi tri dni kasneje brskal po dnevnikih, da bi rekonstruiral manjkajoče.

def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
    """Loči uspehe od napak za ponovno obdelavo."""
    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)}")
        # Znova zapiši datoteko JSONL z napakami za ponovni poskus
        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

Pomnoži svoje prihranke

Pri obdelavi desetih tisoč dokumentov z modelom GPT-5.6 Luna sinhroni API predstavlja osnovni strošek, Batch API polovico tega, predpomnjenje pozivov (prompt caching) pa doda še dodatne prihranke, saj imajo tudi predpomnjeni žetoni svojo stopnjo znižanja. Ta dva mehanizma si ne nasprotujeta: če tvojih deset tisoč zahtevkov deli isti dolg sistemski poziv, ga strukturiraj kot stabilno predpono in tako združiš oba učinka.

Na koncu je tu še vprašanje razdeljevanja. Paket ne sme biti neskončen in lažje je spremljati več obvladljivih paketov kot en sam monolit, katerega napaka stane cel dan. Naslednja funkcija razreže seznam zahtevkov na pakete omejene velikosti.

def create_optimized_batches(
    requests: list[dict],
    max_size: int = 50_000,
) -> list[list[dict]]:
    """Razdeli na pakete optimalne velikosti."""
    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 ugotovitve

  • Batch API ponuja 50-odstotno znižanje za obdelavo, ki ni v realnem času
  • Pripravi svoje zahtevke v datoteki JSONL z edinstvenim custom_id za vsak zahtevek
  • Načrtuj mehanizem za ponovni poskus za neuspele zahtevke
  • Združi s predpomnjenjem pozivov za največje prihranke