Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Einen Batch-Job erstellen, den Status verfolgen und Ergebnisse herunterladen

Lektion 3 von 16 Aktualisiert am 3. November 2026 Fortgeschritten
Auf dieser Seite
  1. Vom JSONL-Datei zu Ergebnissen: Der vollständige Lebenszyklus
  2. Einen Batch-Job erstellen
  3. Batch-Job-Status
  4. Fortschritt verfolgen
  5. Ergebnisse herunterladen
  6. Ihre Jobs auflisten und verwalten
  7. End-to-End-Arbeitsablauf
  8. Kernaussagen

Aktualisiert am 3. November 2026: Ergänzung zum 3. November: files.download gibt eine HTTP-Antwort (httpx2.Response) zurück; lesen Sie den Inhalt mit .read() auf, bevor Sie .decode() aufrufen. Das Upload-Verfahren erwartet file={"file_name": …, "content": …}. Der API-Schlüssel ist nicht mehr hartkodiert.

Vom JSONL-Datei zu Ergebnissen: Der vollständige Lebenszyklus

Ihre JSONL-Datei ist vorbereitet und hochgeladen, und Sie verfügen über eine file_id. Der nächste Schritt besteht darin, diese inaktive Datei in verwertbare Ergebnisse zu verwandeln: Erstellen Sie den Batch-Job, überwachen Sie seinen Fortschritt über die Minuten oder Stunden, die die Verarbeitung dauert, und holen Sie die Antworten ab sowie führen Sie eine Abgleichprüfung durch. Diese Lektion führt Sie durch den Python-Code von Anfang bis Ende in der exakten Reihenfolge, in der Sie ihn schreiben werden.

Einen Batch-Job erstellen

Die Erstellung erfordert einen einzigen Aufruf. Sie geben die Quelldatei, das Modell und das Ziel-Endpunkt vor:

from mistralai.client import Mistral
import time

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

# Erstellen Sie den Batch-Job
job = client.batch.jobs.create(
    input_files=[batch_file.id],   # ID der hochgeladenen Datei
    model="mistral-small-latest",
    endpoint="/v1/chat/completions",
    metadata={"project": "document-analysis", "version": "1.0"}
)

print(f"Job erstellt: {job.id}")
print(f"Initialer Status: {job.status}")

Jeder Parameter verdient eine Anmerkung:

  • input_files — Eine Liste von hochgeladenen Datei-IDs. Sie können mehrere Dateien an einen einzigen Job übergeben.
  • model — Das Mistral-Modell, das verwendet werden soll. Pro Batch-Job nur ein Modell.
  • endpoint — Das Ziel-API-Endpunkt (muss dem body-Format in Ihrer JSONL-Datei entsprechen).
  • metadata — Ein optionales Wörterbuch mit benutzerdefinierten Metadaten, um Ihre Jobs zu organisieren und wiederzufinden.

Die Beschränkung auf ein Modell pro Job strukturiert, wie Sie Ihre Arbeit aufteilen: Wenn Sie zwei Modelle am selben Korpus vergleichen möchten, reichen Sie zwei getrennte Jobs ein, die auf dieselbe Datei zeigen. Was die Metadaten betrifft, scheint dies zunächst nebensächlich, bis Sie dreißig Jobs in Ihrer Historie haben; das oben gezeigte Projekt-/Versions-Paar ermöglicht es Ihnen dann, den Batch, der fragwürdige Daten erzeugt hat, in drei Sekunden flach zu finden.

Batch-Job-Status

Ein Batch-Job durchläuft während seines Lebenszyklus mehrere Zustände:

StatusBeschreibung
QUEUEDIn der Warteschlange, noch nicht gestartet
RUNNINGVerarbeitung läuft
SUCCESSErfolgreich abgeschlossen
FAILEDVerarbeitung fehlgeschlagen
TIMEOUT_EXCEEDEDAusführungszeitüberschreitung
CANCELLATION_REQUESTEDStornierung angefordert
CANCELLEDStorniert

Vier dieser sieben Zustände sind terminal – SUCCESS, FAILED, TIMEOUT_EXCEEDED und CANCELLED – und diese Unterscheidung steuert den Überwachungszyklus: Solange der Status nicht in dieser Menge ist, ist der Job noch aktiv, und Sie müssen warten. CANCELLATION_REQUESTED ist insbesondere kein gestoppter Zustand, sondern ein Übergangszustand; Code, der ihn als terminal behandelt, würde den Zyklus zu früh verlassen.

Fortschritt verfolgen

Das untenstehende Polling-Muster fasst diese Logik exakt zusammen, mit einer maximalen Dauer als Schutzvorkehrung, um zu verhindern, dass ein vergessenes Skript unendlich lange läuft:

def wait_for_batch(client, job_id, poll_interval=10, max_wait=3600):
    """Warten Sie, bis ein Batch-Job abgeschlossen ist, indem Sie abfragen."""
    elapsed = 0
    terminal_states = {"SUCCESS", "FAILED", "TIMEOUT_EXCEEDED", "CANCELLED"}

    while elapsed < max_wait:
        job = client.batch.jobs.get(job_id=job_id)
        print(f"[{elapsed}s] Status: {job.status}")

        if job.status in terminal_states:
            return job

        time.sleep(poll_interval)
        elapsed += poll_interval

    raise TimeoutError(f"Job {job_id} läuft nach {max_wait}s immer noch")

# Verwendung
completed_job = wait_for_batch(client, job.id)
print(f"Endergebnis: {completed_job.status}")

Ein Intervall von zehn Sekunden funktioniert für einen Batch, der nur wenige Minuten dauert; für eine nächtliche Ausführung, die mehrere hunderttausend Zeilen verarbeitet, erhöhen Sie es auf eine Minute oder mehr. Eine höhere Polling-Präzision bringt dort keinen Mehrwert und häuft nur unnötige API-Aufrufe an.

Ergebnisse herunterladen

Sobald der Status SUCCESS erreicht, stellt der Job eine output_file bereit, die Sie herunterladen und Zeile für Zeile parsen können:

import json

if completed_job.status == "SUCCESS":
    # ID der Ausgabe-Datei erhalten
    output_file_id = completed_job.output_file

    # Inhalt herunterladen
    result_data = client.files.download(file_id=output_file_id)

    # JSONL-Ergebnisse parsen
    results = {}
    for line in result_data.read().decode("utf-8").strip().split("\n"):
        entry = json.loads(line)
        custom_id = entry["custom_id"]
        response = entry["response"]
        results[custom_id] = response

    # Ein Beispiel anzeigen
    for cid, resp in list(results.items())[:3]:
        content = resp["body"]["choices"][0]["message"]["content"]
        print(f"\n--- {cid} ---")
        print(content[:200])

Die Ergebnisdatei ist ebenfalls im JSONL-Format, und jede Zeile enthält die ursprüngliche custom_id zusammen mit der vollständigen Antwort des Modells. Hier zahlt sich die Namensgebung aus der vorherigen Lektion aus: Das Indizieren nach custom_id in einem Wörterbuch reicht aus, um Antworten mit Ihren Quelldokumenten abzugleichen, unabhängig von der Reihenfolge, in der sie zurückkehren. Die Anzeige der ersten drei Einträge, auf 200 Zeichen gekürzt, ist eine nützliche Plausibilitätsprüfung, bevor Sie mit dem Schreiben in Ihre Datenbank beginnen.

Ihre Jobs auflisten und verwalten

Sie können die Job-Inventur nach Status filtern, sodass Sie jederzeit sehen können, was tatsächlich auf Ihrem Konto läuft:

# Alle aktuell laufenden Jobs auflisten
running_jobs = client.batch.jobs.list(status="RUNNING")
for j in running_jobs.data:
    print(f"Job {j.id} - Modell: {j.model} - Erstellt: {j.created_at}")

Und wenn ein Job zu lange dauert oder Sie nach der Einreichung einen Prompt-Fehler feststellen, verhindert die Stornierung, dass Sie für nutzlose Verarbeitung bezahlen:

# Einen Job stornieren, der zu lange dauert
client.batch.jobs.cancel(job_id="job-abc123")

Die Stornierung ist asynchron: Der Status wechselt zunächst zu CANCELLATION_REQUESTED und dann zu CANCELLED, sobald die Stoppaktion wirksam ist. Betrachten Sie die Ressource nicht sofort nach dem Rückgabewert des Aufrufs als freigegeben.

End-to-End-Arbeitsablauf

Zusammengesetzt bilden diese vier Schritte ein kurzes Skript, das Sie direkt in einen Scheduler einfügen können:

from mistralai.client import Mistral
import json
import os
import time

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# 1. 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"
    )

# 2. Job erstellen
job = client.batch.jobs.create(
    input_files=[batch_file.id],
    model="mistral-small-latest",
    endpoint="/v1/chat/completions"
)

# 3. Auf Abschluss warten
completed = wait_for_batch(client, job.id)

# 4. Ergebnisse herunterladen und parsen
if completed.status == "SUCCESS":
    data = client.files.download(file_id=completed.output_file)
    for line in data.read().decode("utf-8").strip().split("\n"):
        entry = json.loads(line)
        print(f"{entry['custom_id']}: OK")
else:
    print(f"Batch fehlgeschlagen: {completed.status}")

Nutzen Sie dieses Grundgerüst für Ihr eigenes Korpus mit nur zehn Zeilen: Sie werden die gesamte Kette innerhalb weniger Minuten validieren, bevor Sie sich für das volle Volumen entscheiden.

Kernaussagen

  • Erstellen Sie einen Batch-Job mit client.batch.jobs.create(), indem Sie Datei, Modell und Endpunkt angeben
  • Sieben mögliche Zustände, darunter drei terminal: SUCCESS, FAILED, CANCELLED
  • Polling mit einem Intervall ist das Standardmuster zur Verfolgung des Fortschritts
  • Ergebnisse liegen im JSONL-Format vor und sind über custom_id mit den Anfragen verknüpft
  • Sie können Ihre Jobs jederzeit auflisten, prüfen und stornieren