Gids voor het JSONL-formaat van de OpenAI Batch API
Leer hoe je JSONL-bestanden opbouwt voor de Batch API van OpenAI en 50% op je kosten bespaart
Wat is de OpenAI Batch API?
Met de OpenAI Batch API verstuur je grote aantallen API-requests in één batchtaak. In plaats van duizenden afzonderlijke API-aanroepen te doen, upload je een JSONL-bestand met al je requests. OpenAI verwerkt die vervolgens asynchroon binnen 24 uur.
Het grootste voordeel is de prijs: batchrequests zijn 50% goedkoper dan realtime API-aanroepen. Daarmee is de Batch API ideaal voor taken waarbij je niet direct een antwoord nodig hebt, zoals content genereren, data classificeren, embeddings berekenen en evaluatiepipelines uitvoeren.
JSONL-formaat voor requests
Elke regel in het JSONL-invoerbestand voor een batch bevat één API-request. Elke regel moet drie verplichte velden bevatten en een vaste structuur volgen.
custom_id — Een unieke identifier voor elke request, waarmee je requests aan responses koppelt. Dit mag elke string van maximaal 512 tekens zijn.method — De HTTP-methode. Momenteel wordt alleen POST ondersteund.url — Het pad van het API-endpoint. Voor chat completions: /v1/chat/completions. Voor embeddings: /v1/embeddings.body — De requestbody, in hetzelfde formaat als de requestbody van het bijbehorende API-endpoint.{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}Chat completions in batches
De Batch API wordt het vaakst gebruikt om meerdere requests voor chat completions te versturen. Elke regel bevat een volledige request met model, messages en optionele parameters zoals max_tokens of temperature.
Eén request
Elke regel bevat een volledige request voor een chat completion met model, messages en optionele parameters.
{"custom_id": "task-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the benefits of renewable energy."}], "max_tokens": 500}}JSONL-bestand met meerdere requests
Een batchbestand bevat meestal honderden of duizenden requests. Dit voorbeeldbestand bevat drie verschillende taken: samenvatten, classificeren en vertalen.
{"custom_id": "summary-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Summarize: Solar energy is a renewable source of power that harnesses sunlight using photovoltaic cells."}], "max_tokens": 200}}
{"custom_id": "classify-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Classify this review as positive or negative: Great product, works perfectly!"}], "max_tokens": 50}}
{"custom_id": "translate-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Translate to French: Hello, how are you today?"}], "max_tokens": 100}}Embeddings in batches
De Batch API ondersteunt ook requests voor embeddings. Dat is handig als je grote verzamelingen documenten wilt verwerken. Batches voor embeddings gebruiken dezelfde JSONL-structuur, maar sturen de requests naar het endpoint /v1/embeddings.
Requests voor embeddings hebben een eenvoudiger opgebouwde body met model en de invoertekst.
{"custom_id": "embed-001", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL is a text format for storing structured data."}}
{"custom_id": "embed-002", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "Each line contains one valid JSON object."}}
{"custom_id": "embed-003", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL files use the .jsonl extension."}}Formaat van de responses
Zodra een batchtaak is afgerond, stelt OpenAI een JSONL-uitvoerbestand beschikbaar. Elke regel bevat de response op één request. De response bevat de oorspronkelijke custom_id, zodat je responses aan requests kunt koppelen.
Geslaagde response
Een geslaagde response bevat de custom_id, de statuscode van de response en de volledige body van de API-response.
{"id": "batch_req_abc123", "custom_id": "task-001", "response": {"status_code": 200, "body": {"id": "chatcmpl-xyz", "object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Renewable energy provides numerous benefits including reduced greenhouse gas emissions, lower long-term costs, and energy independence."}}]}}, "error": null}Foutresponse
Bij mislukte requests bevat de response een error-object met een code en een bericht dat aangeeft wat er is misgegaan.
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}Volledige workflow voor de Batch API
Hieronder zie je in vijf stappen hoe je de Batch API met de Python SDK gebruikt: van het aanmaken van het JSONL-bestand tot het downloaden en parsen van de resultaten.
- 1Maak een JSONL-bestand met één request per regel
- 2Upload het bestand via de Files API en stel purpose in op batch
- 3Maak een batchtaak die verwijst naar de ID van het geüploade bestand
- 4Vraag de batchstatus periodiek op totdat die completed, failed of cancelled is
- 5Download en parse het JSONL-uitvoerbestand om de resultaten uit te lezen
from openai import OpenAI
import json
import time
client = OpenAI()
# Step 1: Create the JSONL batch file
prompts = [
"Summarize the benefits of renewable energy.",
"Classify this text as positive or negative: Great product!",
"Translate to French: Hello, how are you?",
]
requests = [
{
"custom_id": f"req-{i}",
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": prompt}],
"max_tokens": 200,
},
}
for i, prompt in enumerate(prompts)
]
with open("batch_input.jsonl", "w") as f:
for req in requests:
f.write(json.dumps(req) + "\n")
# Step 2: Upload the file
batch_file = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Step 3: Create the batch
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
print(f"Batch created: {batch.id}")
# Step 4: Poll for completion
while True:
status = client.batches.retrieve(batch.id)
print(f"Status: {status.status}")
if status.status in ("completed", "failed", "cancelled"):
break
time.sleep(60)
# Step 5: Download results
if status.output_file_id:
content = client.files.content(status.output_file_id)
with open("batch_output.jsonl", "wb") as f:
f.write(content.read())Batch API versus realtime API
Door voor elke taak de juiste keuze te maken tussen de Batch API en de standaard realtime API, kun je zowel je kosten als je prestaties optimaliseren.
Meer over het JSONL-formaat voor fine-tuning bij OpenAI lees je in onze gids voor het JSONL-formaat van OpenAI.
Bereid je batchbestanden voor
Gebruik onze gratis tools om je JSONL-batchbestanden te maken, te valideren en te bekijken voordat je ze naar OpenAI verstuurt.
Een complete handleiding om JSONL-bestanden voor OpenAI voor te bereiden. Met uitleg over het dataformaat voor fine-tuning, Batch API-requests, veelgemaakte fouten en tips voor validatie.
Splits grote JSONL-bestanden op regelnummer in kleinere, beheersbare delen.
Valideer JSONL-bestanden regel voor regel. Spoor syntaxfouten, tekencoderingsproblemen en fouten in het formaat direct op.
Strategieën om gigabytes aan JSONL-data te verwerken. Met aandacht voor lezen via streaming, geheugenbeheer, het splitsen van bestanden, compressie en online tools.
Leer hoe je JSONL-trainingsdata voorbereidt voor fine-tuning van AI/ML-modellen. Met uitleg over de datasetformaten van OpenAI, Anthropic Claude en HuggingFace, validatie en pipelines om data voor te bereiden.