Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Werkstroom in vier stappen

Les 2 van 12 Bijgewerkt op 2 november 2026 Ontwikkelaar
Op deze pagina
  1. De levenscyclus van een batch
  2. Stap 1: Een batch aanmaken
  3. Stap 2: Verzoeken toevoegen
  4. Stap 3: Voortgang bewaken
  5. Stap 4: Resultaten ophalen
  6. De werkstroom in de praktijk
  7. Foutafhandeling in de werkstroom
  8. Belangrijkste punten

Bijgewerkt op 2 november 2026 op basis van de xAI-documentatie: de batch-korting bedraagt 20% op in aanmerking komende tekstmodellen (niet 50%); de voorbeelden gebruiken de REST API en de officiële xai-sdk (client.batch.*; de Batch API van xAI volgt niet het formaat van OpenAI, dus de OpenAI SDK is niet van toepassing); en de Responses API heeft voorrang boven Chat Completions, een verouderd eindpunt bij xAI. Bronnen: Batch API · REST-referentie · Batch-prijzen.

De levenscyclus van een batch

Elke batch doorloopt dezelfde cyclus: aanmaken, verzoeken toevoegen, verwerken, resultaten ophalen. Het is essentieel deze cyclus te begrijpen voordat u overgaat tot implementatie, omdat elke stap zijn eigen beperkingen en beste praktijken heeft.

Stap 1: Een batch aanmaken

Alles begint met een POST /v1/batches-aanroep, met één verplicht veld: de naam van de batch. De API retourneert een unieke identificatie (batch_id) die u voor alle daaropvolgende bewerkingen gebruikt.

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer_review_analysis"}'

Het antwoord bevat ook de aanmaak- en vervaldatum van de batch (create_time, expire_time) en een state-object waarvan de tellers allemaal nog op nul staan.

Stap 2: Verzoeken toevoegen

Er zijn twee methoden:

Via de API: u verzendt verzoeken met POST /v1/batches/{batch_id}/requests. Elke aanroep bevat een lijst met verzoeken en u kunt deze blijven toevoegen zolang de batch niet is geannuleerd. Dit is de route voor batches die geleidelijk worden opgebouwd.

Via een JSONL-bestand: u bereidt een bestand voor met al uw verzoeken, uploadt dit via de Files API en maakt vervolgens de batch aan op basis van dat bestand. De batch is dan afgesloten: toevoegingen zijn niet meer mogelijk. Dit is de route voor grote volumes die vooraf zijn voorbereid.

Elk verzoek heeft een unieke identificatie binnen de batch: batch_request_id in de API, custom_id in het JSONL-bestand. Als u dit in de API weglaat, genereert xAI een UUID; geef in plaats daarvan uw eigen identificatie op (bijvoorbeeld een database-ID): deze dient als koppelingssleutel tussen uw gegevens en de resultaten, en garandeert dat een verzoek slechts één keer wordt verwerkt.

Stap 3: Voortgang bewaken

De verwerking start zodra verzoeken binnenkomen; er is geen aparte “start”-stap. Ondertussen retourneert GET /v1/batches/{batch_id} het state-object en de bijbehorende tellers: num_requests (totaal), num_pending (in behandeling), num_success (geslaagd), num_error (mislukt) en num_cancelled (geannuleerd).

curl https://api.x.ai/v1/batches/$BATCH_ID \
  -H "Authorization: Bearer $XAI_API_KEY"

Wanneer num_pending op nul zakt, zijn alle verzoeken verwerkt, al dan niet succesvol. Periodiek peilen is voldoende: een paar seconden voor een kleine testbatch, een paar minuten voor een grote batch.

Stap 4: Resultaten ophalen

Resultaten worden gelezen met GET /v1/batches/{batch_id}/results, zonder te wachten tot de batch is voltooid: elk verzoek is beschikbaar zodra het is verwerkt. Het antwoord is gepagineerd: limit stelt de paginagrootte in (maximaal 1.000) en de geretourneerde pagination_token wordt gebruikt om de volgende pagina op te vragen; deze is leeg op de laatste pagina.

curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
  -H "Authorization: Bearer $XAI_API_KEY"

Elk resultaat bevat de batch_request_id van het bijbehorende verzoek: hiermee kunt u de koppeling tussen uw invoergegevens en de antwoorden van Grok reconstrueren.

De werkstroom in de praktijk

In een productieomgeving vertaalt de werkstroom zich doorgaans in twee afzonderlijke processen:

  • Een indieningsproces dat de batch aanmaakt, verzoeken voorbereidt en toevoegt, en vervolgens de batch_id opslaat
  • Een ophaalproces dat periodiek de tellers controleert en resultaten downloadt zodra deze beschikbaar komen

Deze scheiding stelt u in staat de Batch API te integreren in event-driven architecturen of bestaande datapipelines (cron-jobs, Apache Airflow, wachtrijen).

Foutafhandeling in de werkstroom

Een batch heeft geen globale status “geslaagd” of “mislukt”: u leest dit via de tellers. Een mislukt verzoek verhoogt num_error en verschijnt in de resultaten met de bijbehorende foutmelding, zonder de andere verzoeken te blokkeren. U moet daarom elk resultaat onderzoeken en storingen geval per geval afhandelen.

Twee gebeurtenissen beïnvloeden de volledige batch. De eerste is annulering, door u of door xAI, die dit vervolgens toelicht in het veld cancel_by_xai_message. Dit gebeurt bijvoorbeeld wanneer een regel in een JSONL-bestand ongeldig is. De andere is verloop (expire_time), waarna resultaten niet meer toegankelijk zijn: haal ze tijdig op.

Belangrijkste punten

  • De werkstroom volgt de volgorde: aanmaken (met een naam), toevoegen, bewaken, ophalen
  • De verzoek-identificatie (batch_request_id, of custom_id in JSONL) is uw koppelingssleutel
  • De voortgang leest u uit de state-tellers; alles is verwerkt wanneer num_pending nul is
  • Resultaten zijn gepagineerd (limit, pagination_token) en beschikbaar naarmate ze worden verwerkt
  • Fouten worden per verzoek afgehandeld; annulering en verloop beïnvloeden de volledige batch