Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Batch API: masinis asinchroninis apdorojimas

Paskaita 6 iš 20 Atnaujinta 2026 m. lapkričio 3 d. Pažengusiems
Šiame puslapyje
  1. Keiskite delsą į kainą
  2. Sukurkite ir paleiskite partiją
  3. Planuokite dalinius gedimus
  4. Dauginkite savo sutaupymus
  5. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 3 d. pagal Batch API gairę ir Responses API atsako struktūrą: rezultatų skaitymas nebelaiko, kad pirmasis output elementas yra žinutė (prieš ją gali būti samprotavimo elementas), o klaidos kodo raktas, parašytas be kabučių, sukėlė NameError. Šaltinis: Batch API.

Keiskite delsą į kainą

Batch API veikia pagal paprastą rinkos principą: jūs sutinkate, kad jūsų užklausos bus apdorotos asinchroniškai per iki dvidešimt keturių valandų langą, o mainais mokate penkiasdešimčia procentų mažiau. Viskas, ko nereikia pateikti žmogui, laukiančiam prie ekrano, patenka į šią kategoriją. Dideliu mastu tai nėra mikrooptimizacija; tai perpus sumažina jūsų biudžetą.

Įprotis, kurį turite ugdyti komandoje: kiekvienai naujai apdorojimo užduočiai klauskite, ar kas nors laukia rezultato. Akcijų portfelio analizė, produkto aprašymų generavimas katalogui, tūkstančių testų atvejų etaloninis vertinimas, šešių mėnesių bilietų eilės klasifikavimas, laukų ištraukimas iš sąskaitų faktūrų partijos: visais šiais atvejais atsakymas atsiduria skydellyje arba duomenų bazėje, o ne pokalbio sąsajoje. Delsa nematoma, o sutaupymai – akivaizdūs.

Sukurkite ir paleiskite partiją

Įvesties formatas yra JSONL failas: viena eilutė vienai užklausai, kur kiekviena eilutė yra pilnas, nepriklausomas objektas. Laukas custom_id leidžia susieti kiekvieną atsaką su originalia užklausa, nes niekas negarantuoja išvesties failo eiliškumo. Pasirinkite stabilų ir prasmingą ID – dokumento ID iš savo duomenų bazės, o ne iteracijos numerį – kitaip suderinimo etapas taps кошmaru.

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

Tada failas įkeliamas ir nurodomas kuriant partiją. Metaduomenys neturi techninės paskirties, tačiau jie jums labai pravers, kai trys partijos veiks lygiagrečiai ir reikės išsiaiškinti, kuri iš jų atitinka kurią raginimo (prompt) versiją.

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

Stebėjimas apima partijos būsenos tikrinimą, kol ji išeina iš „vykdoma“ būsenos, tada atsisiunčiamas išvesties failas, kuris taip pat yra JSONL formato. Toliau pateikta kilpa išskiria tris galutines baigtis – failed, expired, cancelled – ir kiekvienai iš jų išmeta išimtį: pasibaigusi partija yra ta, kurios dvidešimt keturių valandų langas baigėsi prieš viską apdorojant, ir laikyti tai tyliu daliniu sėkmingumu būtų blogiausias pasirinkimas.

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

Planuokite dalinius gedimus

Didelėje partijoje kai kurios užklausos nepavyks: nutrūkęs dokumentas, konteksto perpildymas arba laikina serverio klaida. Todėl partija niekada nėra tiesiog „sėkminga“ arba „nepavykusi“ – ji yra iš dalies sėkminga, ir jūs turite mokėti išskirti trūkstamą dalį. Priimtinas modelis yra iškart atskirti sėkmes nuo nesėkmių ir sugeneruoti JSONL failą, paruoštą paleisti iš naujo, o ne po trijų dienų knaisiotis žurnaluose, norint rekonstruoti, ko trūksta.

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

Dauginkite savo sutaupymus

Apdorojant dešimt tūkstančių dokumentų su GPT-5.6 Luna, sinchroninis API yra bazinė kaina, Batch API sudaro jos pusę, o raginimų talpykla (prompt caching) pridedama viršuje, nes talpykloje esantys tokenai taip pat gauna savo sumažinimą. Šie du mechanizmai nekonkuruoja: jei jūsų dešimt tūkstančių užklausų dalijasi tuo pačiu ilgu sistemos raginimu, sustruktūruokite jį kaip stabilų priešdėlį ir gausite abiejų efektų sumą.

Galiausiai kyla skaidymo klausimas. Partija neturi būti begalinė, ir patogiau stebėti kelias valdomas partijas nei vieną monolitą, kurio gedimas kainuoja visą dieną. Toliau pateikta funkcija suskaido užklausų sąrašą į riboto dydžio partijas.

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

Svarbiausi punktai

  • Batch API siūlo 50 % sumažinimą ne realiuoju laiku vykdomam apdorojimui
  • Paruoškite savo užklausas JSONL faile su unikaliu custom_id kiekvienai užklausai
  • Suplanuokite kartojimo mechanizmą nepavykusioms užklausoms
  • Derinkite su raginimų talpykla (prompt caching), kad maksimaliai padidintumėte sutaupymus