Von Jerry Fan

Das JSONL-Format der OpenAI Batch API

So strukturieren Sie JSONL-Dateien für die OpenAI Batch API und sparen 50 % der Kosten

Was ist die OpenAI Batch API?

Mit der OpenAI Batch API senden Sie große Mengen an API-Anfragen als einen einzigen Batch-Job. Statt Tausende einzelner API-Aufrufe auszuführen, laden Sie eine JSONL-Datei mit allen Anfragen hoch. OpenAI verarbeitet diese dann asynchron innerhalb von 24 Stunden.

Der größte Vorteil sind die Kosten: Batch-Anfragen sind 50 % günstiger als API-Aufrufe in Echtzeit. Damit eignet sich die Batch API besonders für Aufgaben, bei denen Sie keine sofortige Antwort benötigen, etwa das Generieren von Inhalten, die Klassifizierung von Daten, die Berechnung von Embeddings und Evaluationspipelines.

Batch-Dateien vorbereiten

Mit unseren kostenlosen Tools können Sie Ihre JSONL-Batch-Dateien erstellen, validieren und prüfen, bevor Sie sie an OpenAI senden.

JSONL-Format für Anfragen

Jede Zeile der JSONL-Eingabedatei für einen Batch steht für eine API-Anfrage. Sie muss drei Pflichtfelder enthalten und einer festgelegten Struktur entsprechen.

custom_id — Eine eindeutige ID für jede Anfrage, über die Sie Antworten den zugehörigen Anfragen zuordnen. Erlaubt ist ein beliebiger String mit bis zu 512 Zeichen.
method — Die HTTP-Methode. Derzeit wird nur POST unterstützt.
url — Der Pfad des API-Endpunkts: /v1/chat/completions für Chat Completions und /v1/embeddings für Embeddings.
body — Der Request-Body im selben Format wie beim entsprechenden API-Endpunkt.
Grundstruktur einer Anfrage
{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}

Chat Completions im Batch verarbeiten

Am häufigsten wird die Batch API verwendet, um mehrere Chat-Completion-Anfragen zu senden. Jede Zeile enthält eine vollständige Anfrage mit Modell, Nachrichten und optionalen Parametern wie max_tokens oder temperature.

Einzelne Anfrage

Jede Zeile enthält eine vollständige Chat-Completion-Anfrage mit Modell, Nachrichten und optionalen Parametern.

Einzelne Anfrage
{"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-Datei mit mehreren Anfragen

Eine Batch-Datei enthält in der Regel Hunderte oder Tausende Anfragen. Das folgende Beispiel zeigt eine Datei mit drei verschiedenen Aufgaben: Zusammenfassen, Klassifizieren und Übersetzen.

JSONL-Datei mit mehreren Anfragen
{"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 im Batch berechnen

Die Batch API unterstützt auch Embedding-Anfragen, etwa für die Verarbeitung großer Dokumentensammlungen. Batches für Embeddings verwenden dieselbe JSONL-Struktur, richten die Anfragen aber an den Endpunkt /v1/embeddings.

Embedding-Anfragen haben einen einfacheren Request-Body mit Modell und Eingabetext.

Format für Embedding-Anfragen
{"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."}}

Antwortformat

Sobald ein Batch-Job abgeschlossen ist, stellt OpenAI eine JSONL-Ausgabedatei bereit. Jede Zeile enthält die Antwort auf eine Anfrage. Über die ursprüngliche custom_id in der Antwort können Sie diese der zugehörigen Anfrage zuordnen.

Erfolgreiche Antwort

Bei einer erfolgreichen Anfrage enthält die Antwort die custom_id, den Statuscode und den vollständigen Body der API-Antwort.

Erfolgreiche Antwort
{"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}

Fehlerantwort

Bei fehlgeschlagenen Anfragen enthält die Antwort ein Fehlerobjekt mit einem Fehlercode und einer Meldung, die die Ursache beschreibt.

Fehlerantwort
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}

Der vollständige Workflow mit der Batch API

Der folgende Workflow zeigt in fünf Schritten, wie Sie die Batch API mit dem Python-SDK verwenden: vom Erstellen der JSONL-Datei bis zum Herunterladen und Parsen der Ergebnisse.

  1. 1Erstellen Sie eine JSONL-Datei mit einer Anfrage pro Zeile.
  2. 2Laden Sie die Datei über die Files API hoch und setzen Sie purpose auf batch.
  3. 3Erstellen Sie einen Batch-Job, der auf die ID der hochgeladenen Datei verweist.
  4. 4Fragen Sie den Batch-Status regelmäßig ab, bis er completed, failed oder cancelled lautet.
  5. 5Laden Sie die JSONL-Ausgabedatei herunter und parsen Sie sie, um die Ergebnisse auszulesen.
Der vollständige Workflow mit der Batch API
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 und Echtzeit-API im Vergleich

Wenn Sie wissen, wann sich die Batch API und wann sich die normale Echtzeit-API eignet, können Sie Kosten und Leistung gezielt optimieren.

Merkmal
Batch API
Echtzeit-API
Kosten
50 % Rabatt
Standardpreise
Latenz
Bis zu 24 Stunden
Sekunden
Rate Limits
Höhere Limits
Standard-Limits
Eingabeformat
Upload einer JSONL-Datei
Einzelne API-Aufrufe
Ideal für
Massenverarbeitung, Evaluation, Generierung von Daten
Interaktive Apps, Echtzeit-Chat, Streaming

Details zum JSONL-Format für das Fine-Tuning mit OpenAI finden Sie in unserem Leitfaden zum JSONL-Format für OpenAI.

JSONL-Dateien online bearbeiten

JSONL-Dateien bis zu 1 GB direkt im Browser anzeigen, validieren und konvertieren. Ohne Upload, 100 % privat.

Häufig gestellte Fragen

Quellen