Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Batch API: Massale Asynchrone Verwerking

Les 6 van 20 Bijgewerkt op 3 november 2026 Gevorderd
Op deze pagina
  1. Ruil Latentie in voor Kosten
  2. Een Batch Opbouwen en Starten
  3. Anticipeer op Gedeeltelijke Mislukkingen
  4. Vermeerder Uw Besparingen
  5. Belangrijkste punten

Bijgewerkt op 3 november 2026 op basis van de Batch API-gids en de responsstructuur van de Responses API: het lezen van resultaten gaat er niet langer van uit dat het eerste element van output het bericht is (een redeneerelement kan eraan voorafgaan), en de sleutel voor de foutcode, geschreven zonder aanhalingstekens, veroorzaakte een NameError. Bron: Batch API.

Ruil Latentie in voor Kosten

De Batch API werkt volgens een simpel marktprincipe: u accepteert dat uw verzoeken asynchroon worden verwerkt binnen een venster van maximaal vierentwintig uur, en krijgt daarvoor vijftig procent korting. Alles waarvoor geen mens wachtend achter zijn scherm zit, valt in deze categorie. Op schaal is dit geen micro-optimalisatie; het halveert uw begrotingslijn.

De gewoonte die u binnen een team moet ontwikkelen, is om bij elke nieuwe verwerkingstaak te vragen of iemand op het resultaat wacht. Het analyseren van een voorraad contracten, het genereren van productfiches voor een catalogus, het uitvoeren van een benchmark op duizenden testcases, het classificeren van een achterstand van zes maanden aan tickets, het extraheren van velden uit een batch facturen: in al deze gevallen belandt het antwoord in een dashboard of een database, niet in een conversatie-interface. De vertraging is onzichtbaar, maar de besparingen zijn dat niet.

Een Batch Opbouwen en Starten

Het invoerformaat is een JSONL-bestand: één regel per verzoek, waarbij elke regel een compleet, onafhankelijk object is. Het veld custom_id is wat u in staat stelt elke respons aan het oorspronkelijke verzoek te koppelen, aangezien niets de volgorde van het uitvoerbestand garandeert. Kies een ID die stabiel en betekenisvol is—een document-ID uit uw database in plaats van een iteratienummer—anders wordt de reconciliatiefase een nachtmerrie.

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

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

Het bestand wordt vervolgens geüpload en gebruikt als referentie bij het aanmaken van de batch. Metadata dient geen technisch doel, maar zal u redden wanneer er drie batches parallel draaien en u moet uitzoeken welke bij welke promptversie hoort.

import openai

client = openai.OpenAI()

# Upload het bestand
file_obj = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

# Maak de batch aan
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}")

Monitoring houdt in dat u de batch peilt totdat deze de status ‘in-progress’ verlaat, waarna u het uitvoerbestand downloadt, dat eveneens in JSONL-formaat is. De onderstaande lus onderscheidt drie einduitkomsten—failed, expired, cancelled—en gooit voor elk een uitzondering: een verlopen batch is er een waarbij het venster van vierentwintig uur verstreken is voordat alles verwerkt was, en dit behandelen als een stille gedeeltelijke succes zou de slechtste optie zijn.

import time

def wait_for_batch(batch_id: str, interval: int = 60) -> list:
    """Wacht tot een batch voltooid is en geeft de resultaten terug."""
    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 resultaten
    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)

# Verwerk resultaten
for result in results:
    custom_id = result["custom_id"]
    response = result["response"]
    if response["status_code"] == 200:
        # output kan andere elementen bevatten voordat het bericht komt
        (bijvoorbeeld redeneren): zoek de berichttekst
        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']}")

Anticipeer op Gedeeltelijke Mislukkingen

Bij een grote batch zullen sommige verzoeken mislukken: een afgekapt document, een contextoverflow of een tijdelijke serverfout. Een batch is daarom nooit simpelweg “geslaagd” of “mislukt”—deze is gedeeltelijk geslaagd, en u moet weten hoe u het ontbrekende deel isoleert. Het patroon dat u moet volgen, is om successen en mislukkingen onmiddellijk te scheiden en een JSONL-bestand te regenereren dat klaar is om opnieuw te worden gestart, in plaats van drie dagen later door logs te wroeten om te reconstrueren wat er ontbreekt.

def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
    """Scheidt successen van mislukkingen voor herverwerking."""
    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)}")
        # Herschrijf een JSONL-bestand met mislukkingen voor 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

Vermeerder Uw Besparingen

Bij een verwerkingsrun van tienduizend documenten met GPT-5.6 Luna vormt de synchrone API de basiskost, vertegenwoordigt de Batch API de helft daarvan, en komt prompt caching daar nog bovenop omdat gecachete tokens ook profiteren van hun eigen reductie. De twee mechanismen concurreren niet: als uw tienduizend verzoeken dezelfde lange systeemprompt delen, structureer deze dan als een stabiel prefix en zult u beide effecten cumuleren.

Tot slot is er de kwestie van opsplitsen. Een batch moet niet oneindig zijn, en het is comfortabeler om meerdere beheersbare batches te monitoren dan één monoliet waarvan een mislukking een hele dag kost. De volgende functie splitst een lijst met verzoeken op in batches van begrensde grootte.

def create_optimized_batches(
    requests: list[dict],
    max_size: int = 50_000,
) -> list[list[dict]]:
    """Splitst op in batches van optimale grootte."""
    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

Belangrijkste punten

  • De Batch API biedt een reductie van 50% voor niet-realtijdverwerking
  • Bereid uw verzoeken voor in een JSONL-bestand met een unieke custom_id per verzoek
  • Voorzie een retry-mechanisme voor mislukte verzoeken
  • Combineer met prompt caching om besparingen te maximaliseren