Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

JSONL-Format, custom_id und Datei-Upload

Lektion 2 von 16 Aktualisiert am 3. November 2026 Fortgeschritten
Auf dieser Seite
  1. Das JSONL-Format: Das Rückgrat der Batch-Inferenz
  2. Struktur einer JSONL-Anfrage
  3. Generierung einer JSONL-Datei in Python
  4. Hochladen der Datei bei Mistral
  5. Datei-Validierung
  6. Limits und Einschränkungen
  7. Kernaussagen

Aktualisiert am 3. November 2026: Mit der SDK-Version mistralai 3.7.0 erwartet files.upload das Format file={"file_name": …, "content": …} (das Übergeben eines Tupels führt zu einer ValidationError, bevor Daten gesendet werden), und die Dateigröße ist in size_bytes verfügbar.

Das JSONL-Format: Das Rückgrat der Batch-Inferenz

JSONL (JSON Lines) ist das Standardformat, das Mistral verwendet, um Batch-Anfragen zu strukturieren. Jede Zeile in der Datei ist ein eigenständiges JSON-Objekt, das eine einzelne Anfrage darstellt. Dieses Design ist beabsichtigt: Sie können eine Datei mit einer Million Zeilen streamweise generieren, ohne sie vollständig in den Arbeitsspeicher zu laden. Sie können sie Zeile für Zeile wieder einlesen und bei fehlerhaften Anfragen spezifische Einträge manuell inspizieren. Im Gegensatz zu einem einzelnen riesigen JSON-Array, der Sie zwingt, die gesamte Datei zu laden, um nur einen Eintrag zu überprüfen, ermöglicht JSONL die Arbeit auf Zeilenebene.

Struktur einer JSONL-Anfrage

Jede Zeile in Ihrer JSONL-Datei muss zwei erforderliche Felder enthalten:

{
  "custom_id": "req-001",
  "body": {
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Fassen Sie dieses Dokument in 3 Punkten zusammen."}
    ]
  }
}

Die custom_id ist eine eindeutige Kennzeichnung, die Sie für jede Anfrage definieren. Sie ist der Schlüssel, der die Ergebnisse nutzbar macht. Mistral garantiert keine Verarbeitungsreihenfolge: Die Ausgabe-Datei könnte mit der Anfrage 8.472 beginnen. Ohne eine custom_id landen Sie mit einem Stapel von Antworten, ohne zu wissen, welchem Dokument jede entspricht. Machen Sie es zur Gewohnheit, diese ID aus Ihrem eigenen Referenzsystem abzuleiten – doc-001, email-2024-03-15-042, product-sku-ABC123 – anstatt einen anonymen Zähler zu verwenden. Wenn eine Antwort Probleme verursacht, können Sie sie zurückverfolgen, ohne eine SQL-Abfrage auszuführen. Hier gelten zwei praktische Regeln: IDs müssen innerhalb der Datei eindeutig sein, sonst wird die Verarbeitung einen Fehler zurückgeben, und sie sollten angemessen kurz sein, da eine 200-Zeichen-Identifizierung die Protokolle unlesbar macht.

Das body-Feld erfordert kein neues Lernen: Es enthält die exakte Struktur, die Sie für einen synchronen API-Aufruf an das Ziel-Endpunkt verwenden würden. Wenn Sie auf /v1/chat/completions abzielen, ist das body identisch mit dem, was Sie in einem client.chat.complete()-Aufruf übergeben würden. Ein interaktiv validierter Prompt übersetzt sich direkt in einen Batch-Job.

Generierung einer JSONL-Datei in Python

So generieren Sie programmatisch eine JSONL-Datei aus einer Liste von Dokumenten:

import json

documents = [
    {"id": "doc-001", "text": "Künstliche Intelligenz transformiert..."},
    {"id": "doc-002", "text": "Tiefe neuronale Netze..."},
    {"id": "doc-003", "text": "Verarbeitung natürlicher Sprache..."},
]

with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
    for doc in documents:
        request = {
            "custom_id": doc["id"],
            "body": {
                "model": "mistral-small-latest",
                "max_tokens": 200,
                "messages": [
                    {
                        "role": "system",
                        "content": "Sie sind ein Assistent, der Texte zusammenfasst."
                    },
                    {
                        "role": "user",
                        "content": f"Fassen Sie diesen Text zusammen: {doc['text']}"
                    }
                ]
            }
        }
        f.write(json.dumps(request, ensure_ascii=False) + "\n")

Achten Sie auf den Parameter ensure_ascii=False. Ohne ihn entfährt json.dumps akzentuierte Zeichen als \uXXXX-Sequenzen. Die Datei bleibt zwar gültig, wird aber für Menschen unlesbar, wodurch jede Fehlersuche an einem französischen Korpus zu einer Entschlüsselungsübung wird. Machen Sie dies zur Vorgabe ab der ersten Zeile des Codes.

Hochladen der Datei bei Mistral

In der Produktion laden Sie die Datei über die Python-API hoch:

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# JSONL-Datei hochladen
with open("batch_requests.jsonl", "rb") as f:
    batch_file = client.files.upload(
        file={"file_name": "batch_requests.jsonl", "content": f},
        purpose="batch"
    )

print(f"Hochgeladene Datei: {batch_file.id}")
print(f"Größe: {batch_file.size_bytes} Bytes")
print(f"Zweck: {batch_file.purpose}")

Der Parameter purpose="batch" signalisiert Mistral, dass diese Datei für die Batch-Verarbeitung bestimmt ist und nicht für andere Funktionen wie Feinabstimmung oder RAG. Diese Absichtserklärung bestimmt, was als Nächstes passiert: Eine Datei, die mit dem falschen Zweck hochgeladen wird, wird vom Job abgelehnt.

Für einen schnellen Test oder für nicht-technische Teams bietet AI Studio denselben Service über die Benutzeroberfläche an:

  1. Gehen Sie zu console.mistral.ai/build/files
  2. Klicken Sie auf “Upload”
  3. Wählen Sie Ihre JSONL-Datei aus
  4. Wählen Sie den Zweck “Batch Processing”

Die Oberfläche gibt eine file_id zurück, genau wie die API, und dies ist die Kennzeichnung, die Sie verwenden, um den Batch-Job zu erstellen.

Datei-Validierung

Ein Batch mit einer Million Zeilen, der in Zeile 300 wegen einer doppelten custom_id fehlschlägt, kostet Sie einen kompletten Wartezyklus. Ein paar Sekunden lokale Validierung verhindern diesen Verlust. Der folgende Skript führt einen einzigen Durchlauf durch, um die JSON-Gültigkeit, das Vorhandensein der beiden erforderlichen Felder und die Eindeutigkeit der IDs zu prüfen:

import json

errors = []
seen_ids = set()

with open("batch_requests.jsonl", "r", encoding="utf-8") as f:
    for line_num, line in enumerate(f, 1):
        try:
            data = json.loads(line)
        except json.JSONDecodeError as e:
            errors.append(f"Zeile {line_num}: Ungültiges JSON - {e}")
            continue

        # Erforderliche Felder prüfen
        if "custom_id" not in data:
            errors.append(f"Zeile {line_num}: fehlende custom_id")
        if "body" not in data:
            errors.append(f"Zeile {line_num}: fehlendes body")

        # Eindeutigkeit von custom_id prüfen
        cid = data.get("custom_id")
        if cid in seen_ids:
            errors.append(f"Zeile {line_num}: doppelte custom_id '{cid}'")
        seen_ids.add(cid)

if errors:
    print(f"{len(errors)} Fehler gefunden:")
    for e in errors:
        print(f"  - {e}")
else:
    print(f"Datei gültig: {len(seen_ids)} Anfragen bereit.")

Machen Sie dies zu einem systematischen Schritt in Ihrem Vorbereitungspipeline, der direkt vor dem Upload ausgeführt wird.

Limits und Einschränkungen

Das Batch-Filing ist auf eine Million Zeilen pro Datei begrenzt, was bedeutet, dass Sie größere Korpora in mehrere Einreichungen aufteilen müssen. Die Kodierung muss UTF-8 sein, und das Format erfordert strikt ein JSON-Objekt pro Zeile: Ein JSON-Objekt, das über mehrere Zeilen verteilt ist, wie es durch ein falsch platziertes json.dumps(..., indent=2) erzeugt wird, bricht die serverseitige Analyse. Denken Sie schließlich an die beiden bereits erwähnten Regeln, da deren Verletzung dazu führt, dass der Job fehlschlägt: Die custom_id muss innerhalb der Datei eindeutig sein, und das body muss dem Schema des Ziel-Endpunkts entsprechen.

Kernaussagen

  • JSONL strukturiert Ihre Batch-Anfragen mit einem JSON-Objekt pro Zeile
  • Jede Anfrage erfordert eine eindeutige custom_id und ein body, das dem Ziel-Endpunkt entspricht
  • Laden Sie die Datei über die Python-API (client.files.upload) oder über AI Studio hoch
  • Validieren Sie Ihre Datei immer vor der Einreichung, um Verarbeitungsfehler zu vermeiden
  • Verwenden Sie ensure_ascii=False für französische und akzentuierte Zeichen