Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

JSONL-Format und Upload über die Files API

Lektion 6 von 12 Aktualisiert am 2. November 2026 Entwickler
Auf dieser Seite
  1. Massenvverarbeitung mit JSONL
  2. Struktur der JSONL-Datei
  3. Generieren einer JSONL-Datei in Python
  4. Upload über die Files API
  5. Batch aus der Datei erstellen
  6. JSONL-Format-Grenzen
  7. Generieren einer JSONL-Datei in JavaScript
  8. Validierung und Debugging
  9. Kernaussagen

Aktualisiert am 2. November 2026 basierend auf der xAI-Dokumentation: Der Batch-Rabatt beträgt 20 % für berechtigte Textmodelle (nicht 50 %), die Beispiele folgen dem REST-API-Standard und dem offiziellen xai-sdk (client.batch.*; die Batch API von xAI verwendet nicht das Format von OpenAI, sodass das OpenAI SDK nicht anwendbar ist), und die Responses API geht der Chat Completions API vor, einem veralteten Endpunkt bei xAI. Quellen: Batch API · REST-Referenz · Batch-Preise.

Massenvverarbeitung mit JSONL

Für große Volumina, die im Voraus vorbereitet werden, ist eine JSONL-Datei der einfachste Weg. Sie schreiben alle Ihre Anfragen in eine Datei, laden diese über die Files API hoch und erstellen den Batch aus dieser Datei. Eine einzelne Datei kann bis zu 50.000 Anfragen enthalten.

Struktur der JSONL-Datei

Eine JSONL (JSON Lines)-Datei enthält pro Zeile ein JSON-Objekt. Jede Zeile stellt eine vollständige Anfrage mit vier Feldern dar:

{"custom_id": "req-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Fassen Sie diesen Text in einem Satz zusammen: ..."}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Klassifizieren Sie diesen Ticket: Fehler, Feature oder Frage. ..."}]}}
{"custom_id": "req-3", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "grok-4.3", "messages": [{"role": "user", "content": "Übersetzen Sie dies ins Englische: ..."}]}}
  • custom_id: eine eindeutige Kennzeichnung innerhalb der Datei; sie wird zur batch_request_id in den Ergebnissen
  • method: immer "POST"
  • url: das Ziel-Endpoint, einer der sieben akzeptierten
  • body: der Anforderungskörper, der der API-Referenz für diesen Endpunkt entspricht

Jede Zeile muss gültiges, eigenständiges JSON sein: kein Trennkomma, keine umschließenden Klammern. Endpunkte können in derselben Datei gemischt werden; jede Anfrage wird unabhängig geroutet.

Generieren einer JSONL-Datei in Python

import json

documents = [
    {"id": "doc-001", "text": "Erster Artikel zur Zusammenfassung..."},
    {"id": "doc-002", "text": "Zweiter Artikel zur Zusammenfassung..."},
    # ... bis zu 50.000 Dokumente pro Datei
]

with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
    for doc in documents:
        ligne = {
            "custom_id": doc["id"],
            "method": "POST",
            "url": "/v1/responses",
            "body": {
                "model": "grok-4.3",
                "input": [
                    {"role": "system", "content": "Fassen Sie in drei Sätzen zusammen."},
                    {"role": "user", "content": doc["text"]},
                ],
            },
        }
        f.write(json.dumps(ligne, ensure_ascii=False) + "\n")

Upload über die Files API

Sie laden die Datei über den Endpunkt /v1/files hoch, ohne weitere Parameter:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F file="@batch_requests.jsonl"

Mit dem Python SDK:

from xai_sdk import Client

client = Client()

with open("batch_requests.jsonl", "rb") as f:
    fichier = client.files.upload(f, filename="batch_requests.jsonl")
print(f"Hochgeladene Datei: {fichier.id}")

Batch aus der Datei erstellen

Die Datei wird nicht einem bestehenden Batch hinzugefügt: Sie geben sie zum Zeitpunkt der Erstellung mit input_file_id an:

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "article_summaries", "input_file_id": "file-abc123"}'
batch = client.batch.create(batch_name="article_summaries", input_file_id=fichier.id)
print(f"Batch erstellt: {batch.batch_id}")

Die Datei wird im Hintergrund gelesen. Wenn auch nur eine Zeile ungültig ist, wird der Batch mit einer Fehlermeldung abgebrochen. Das Verfolgen und Abrufen der Ergebnisse funktioniert dann exakt wie bei einem Batch, der über die API übermittelt wurde.

JSONL-Format-Grenzen

  • Maximum 50.000 Anfragen pro Datei
  • Maximum 200 MB pro Datei
  • eine eindeutige custom_id pro Zeile
  • ein aus einer Datei erstellter Batch ist versiegelt: Sie können ihm später nicht über die API hinzufügen

Wenn Ihr Batch diese Grenzen überschreitet, teilen Sie ihn in mehrere Dateien auf und erstellen Sie einen Batch pro Datei. Es gibt keine Obergrenze für die Anzahl der Batches pro Team.

Generieren einer JSONL-Datei in JavaScript

import fs from "fs";

const documents = [
  { id: "doc-001", text: "Erster Artikel..." },
  { id: "doc-002", text: "Zweiter Artikel..." },
];

const lines = documents.map(doc => JSON.stringify({
  custom_id: doc.id,
  method: "POST",
  url: "/v1/responses",
  body: {
    model: "grok-4.3",
    input: [
      { role: "user", content: `Zusammenfassung: ${doc.text}` }
    ]
  }
}));

fs.writeFileSync("batch_requests.jsonl", lines.join("\n") + "\n");

Validierung und Debugging

Eine ungültige Zeile bricht den gesamten Batch ab: Validieren Sie die Datei, bevor Sie sie hochladen. Ein einfaches Skript deckt die wesentlichen Punkte ab:

import json
import os

ENDPOINTS = {
    "/v1/responses", "/v1/chat/completions",
    "/v1/images/generations", "/v1/images/edits",
    "/v1/videos/generations", "/v1/videos", "/v1/videos/edits", "/v1/videos/extensions",
}

def valider_jsonl(chemin: str) -> list[str]:
    erreurs, ids = [], set()
    if os.path.getsize(chemin) > 200 * 1024 * 1024:
        erreurs.append("Datei größer als 200 MB")
    with open(chemin, encoding="utf-8") as f:
        for i, ligne in enumerate(f, 1):
            try:
                obj = json.loads(ligne)
            except json.JSONDecodeError as e:
                erreurs.append(f"Zeile {i}: ungültiges JSON ({e})")
                continue
            cid = obj.get("custom_id")
            if not cid or cid in ids:
                erreurs.append(f"Zeile {i}: fehlende oder doppelte custom_id")
            ids.add(cid)
            if obj.get("method") != "POST" or obj.get("url") not in ENDPOINTS:
                erreurs.append(f"Zeile {i}: ungültige Methode oder URL")
            if not isinstance(obj.get("body"), dict):
                erreurs.append(f"Zeile {i}: fehlender body")
    if len(ids) > 50_000:
        erreurs.append("mehr als 50.000 Anfragen")
    return erreurs

print(valider_jsonl("batch_requests.jsonl") or "Datei ist gültig")

Kernaussagen

  • Das JSONL-Format enthält pro Zeile ein JSON-Objekt: custom_id, method, url, body
  • Sie laden die Datei über /v1/files hoch und geben sie beim Erstellen des Batches an (input_file_id)
  • Maximum 50.000 Anfragen und 200 MB pro Datei; darüber hinaus ein Batch pro Datei
  • Ein aus einer Datei erstellter Batch ist versiegelt, und eine ungültige Zeile bricht ihn vollständig ab
  • Validieren Sie die Datei, bevor Sie sie hochladen