Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Batch API: Massiivinen asynkroninen käsittely

Oppitunti 6 / 20 Päivitetty 3. marraskuuta 2026 Edistynyt
Tällä sivulla
  1. Vaihda viive kustannussäästöihin
  2. Batchin rakentaminen ja käynnistäminen
  3. Varaudu osittaisiin epäonnistumisiin
  4. Kerää säästöt
  5. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 Batch API -oppaan ja Responses API:n vastausrakenteen perusteella: tulosten lukeminen ei enää oleta, että output-kentän ensimmäinen elementti on viesti (sitä voi edeltää päättelyelementti), ja lainausmerkeittä kirjoitettu virhekoodin avain aiheutti NameError-virheen. Lähde: Batch API.

Vaihda viive kustannussäästöihin

Batch API toimii yksinkertaisen markkinaperiaatteen mukaisesti: hyväksyt, että pyyntösi käsitellään asynkronisesti enintään 24 tunnin aikavälillä, ja vastineeksi maksat 50 prosenttia vähemmän. Kaikki, mikä ei vaadi ihmisen odottamista näytön ääressä, kuuluu tähän kategoriaan. Laajassa mittakaavassa tämä ei ole mikrosäätöä; se puolittaa budjettisi.

Tiimissä kannattaa omaksua tapa kysyä jokaisen uuden käsittelytehtävän kohdalla, odottaako joku tulosta. Osakekannan analysointi, tuotekorttien generointi luetteloon, benchmarkien suorittaminen tuhansille testitapauksille, kuuden kuukauden tukipyyntöruuhkan luokittelu tai kenttien ekstraktio laskuerästä: kaikissa näissä tapauksissa vastaus päätyy kojelautaan tai tietokantaan, ei keskustelukäyttöliittymään. Viive on näkymätön, mutta säästöt eivät ole.

Batchin rakentaminen ja käynnistäminen

Syötemuoto on JSONL-tiedosto: yksi rivi pyyntöä kohti, jossa jokainen rivi on täydellinen, itsenäinen objekti. custom_id-kenttä on se, jonka avulla voit yhdistää jokaisen vastauksen alkuperäiseen pyyntöönsä, sillä mikään ei takaa tulostiedoston järjestystä. Valitse ID, joka on vakaa ja merkityksellinen – esimerkiksi tietokantasi dokumenttitunnus iteraationumeron sijaan – muuten täsmäytysvaiheesta tulee painajainen.

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

Tiedosto ladataan ja siihen viitataan batchia luotaessa. Metatiedoilla ei ole teknistä tarkoitusta, mutta ne pelastavat tilanteen, kun kolme batchia pyörii rinnakkain ja sinun on selvitettävä, mikä niistä vastaa mitäkin kehysversiota.

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

Seuranta tarkoittaa batchin kyselyä, kunnes se poistuu käynnissä-olevasta tilasta, minkä jälkeen ladataan tulostiedosto, joka on myös JSONL-muodossa. Alla oleva silmukka erottaa kolme lopputilaa – failed, expired, cancelled – ja nostaa poikkeuksen kullekin: vanhentunut batch on sellainen, jossa 24 tunnin ikkuna umpeutui ennen kuin kaikki oli käsitelty, ja sen kohtelu hiljaisena osittaisena onnistumisena olisi pahin vaihtoehto.

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

Varaudu osittaisiin epäonnistumisiin

Laajassa batchissa jotkin pyynnöt epäonnistuvat: typistynyt dokumentti, kontekstin ylivuoto tai ohimenevä palvelinvirhe. Batch ei siis ole koskaan yksinkertaisesti “onnistunut” tai “epäonnistunut” – se on osittain onnistunut, ja sinun on osattava eristää puuttuva osa. Omaksuttava malli on erottaa onnistumiset ja epäonnistumiset välittömästi ja generoida uudelleen JSONL-tiedosto, joka on valmis uudelleenkäynnistykseen, sen sijaan että kaivelisit lokeja kolme päivää myöhemmin rekonstruoidaksesi puuttuvat tiedot.

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

Kerää säästöt

Kymmenen tuhannen dokumentin käsittelyajossa GPT-5.6 Luna -mallilla synkroninen API edustaa peruskustannusta, Batch API puolta siitä, ja kehysvälimuisti (prompt caching) lisää säästöjä päälle, sillä välimuistitetut tokenit hyötyvät omasta alennuksestaan. Nämä kaksi mekanismia eivät kilpaile keskenään: jos kymmenentuhatta pyyntöäsi jakavat saman pitkän järjestelmäkehyksen, rakenna se vakaaksi etuliitteeksi, jolloin saat molempien vaikutukset kertymään.

Lopuksi on kysymys pilkkomisesta. Batchin ei pitäisi olla ääretön, ja useamman hallittavan batchin seuraaminen on mukavampaa kuin yhden monoliitin, jonka epäonnistuminen maksaa kokonaisen päivän. Seuraava funktio pilkkoo pyyntölistan rajoitetun kokoisiin batcheihin.

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

Keskeiset asiat

  • Batch API tarjoaa 50 % alennuksen ei-realiaikaiseen käsittelyyn
  • Valmistele pyyntösi JSONL-tiedostoon, jossa on uniikki custom_id kutakin pyyntöä kohti
  • Suunnittele uudelleenyrittämismekanismi epäonnistuneille pyynnöille
  • Yhdistä kehysvälimuistiin maksimoidaksesi säästöt