Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Een batchtaak maken, de status volgen en resultaten downloaden

Les 3 van 16 Bijgewerkt op 3 november 2026 Gevorderd
Op deze pagina
  1. Van JSONL-bestand naar resultaten: de volledige levenscyclus
  2. Een batchtaak maken
  3. Statussen van batchtaken
  4. Voortgang volgen
  5. Resultaten downloaden
  6. Uw taken bekijken en beheren
  7. End-to-end workflow
  8. Belangrijkste punten

Bijgewerkt op 3 november 2026: Addendum voor 3 november: files.download retourneert een HTTP-respons (httpx2.Response); lees de inhoud met .read() voordat u .decode() aanroept. Upload verwacht file={"file_name": …, "content": …}. De API-sleutel is niet langer hardgecodeerd.

Van JSONL-bestand naar resultaten: de volledige levenscyclus

Uw JSONL-bestand is voorbereid en geüpload, en u beschikt over een file_id. De volgende stap is het omzetten van dat slapende bestand in bruikbare resultaten: maak de batchtaak, bewaak de voortgang gedurende de minuten of uren die de verwerking in beslag neemt, en haal vervolgens de antwoorden op en stem ze af. Deze les leidt u stap voor stap door de end-to-end Python-code in de exacte volgorde waarin u deze zult schrijven.

Een batchtaak maken

Voor het maken is slechts één aanroep vereist. U geeft het bronbestand, het model en het doeleindpunt op:

from mistralai.client import Mistral
import time

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

# Create the batch job
job = client.batch.jobs.create(
    input_files=[batch_file.id],   # ID of the uploaded file
    model="mistral-small-latest",
    endpoint="/v1/chat/completions",
    metadata={"project": "document-analysis", "version": "1.0"}
)

print(f"Job created: {job.id}")
print(f"Initial status: {job.status}")

Elke parameter verdient een toelichting:

  • input_files — Een lijst met ID’s van geüploade bestanden. U kunt meerdere bestanden aan één taak koppelen.
  • model — Het te gebruiken Mistral-model. Slechts één model per batchtaak.
  • endpoint — Het doel-API-eindpunt (moet overeenkomen met het body-formaat in uw JSONL).
  • metadata — Een optionele woordenlijst met aangepaste metadata om uw taken te organiseren en op te halen.

De beperking van één model per taak bepaalt hoe u uw werk opsplitst: als u twee modellen op dezelfde corpus wilt vergelijken, dient u twee afzonderlijke taken in die naar hetzelfde bestand verwijzen. Wat metadata betreft, lijkt dit misschien bijkomstig totdat u dertig taken in uw geschiedenis hebt; het bovenstaande project/versie-paar stelt u dan in staat om binnen drie seconden de batch te vinden die twijfelachtige data heeft gegenereerd.

Statussen van batchtaken

Een batchtaak doorloopt verschillende staten tijdens zijn levenscyclus:

StatusBeschrijving
QUEUEDIn de wachtrij, nog niet gestart
RUNNINGVerwerking bezig
SUCCESSSuccesvol voltooid
FAILEDVerwerking mislukt
TIMEOUT_EXCEEDEDUitvoeringstijdslimiet overschreden
CANCELLATION_REQUESTEDAnnulering aangevraagd
CANCELLEDGeannuleerd

Vier van deze zeven staten zijn definitief: SUCCESS, FAILED, TIMEOUT_EXCEEDED en CANCELLED. Dit onderscheid stuurt de monitoringslus: zolang de status niet in deze set zit, is de taak nog actief en moet u wachten. CANCELLATION_REQUESTED is in het bijzonder geen gestopte staat, maar een overgangsfase; code die dit als definitief behandelt, zou de lus te vroeg verlaten.

Voortgang volgen

Het onderstaande polling-patroon vat deze logica exact samen, met een bewakingsmechanisme voor de maximale duur om te voorkomen dat een vergeten script oneindig blijft draaien:

def wait_for_batch(client, job_id, poll_interval=10, max_wait=3600):
    """Wait for a batch job to complete using polling."""
    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} still running after {max_wait}s")

# Usage
completed_job = wait_for_batch(client, job.id)
print(f"Final result: {completed_job.status}")

Een interval van tien seconden werkt voor een batch die enkele minuten duurt; voor een nachtelijke run die enkele honderdduizenden regels verwerkt, verhoogt u dit naar een minuut of meer. Grotere polling-nauwkeurigheid voegt daar geen waarde toe en leidt alleen tot onnodige API-aanroepen.

Resultaten downloaden

Zodra de status SUCCESS bereikt, stelt de taak een output_file beschikbaar dat u downloadt en regel voor regel parseert:

import json

if completed_job.status == "SUCCESS":
    # Get the output file ID
    output_file_id = completed_job.output_file

    # Download the content
    result_data = client.files.download(file_id=output_file_id)

    # Parse JSONL results
    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

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

Het resultatenbestand is eveneens in JSONL-formaat en elke regel bevat de oorspronkelijke custom_id samen met het volledige antwoord van het model. Hier werpt de naaminspanning van de vorige les zijn vruchten af: indexeren op custom_id in een woordenlijst volstaat om antwoorden af te stemmen op uw brondocumenten, ongeacht de volgorde waarin ze terugkeren. Het weergeven van de eerste drie items, ingekort tot 200 tekens, is een nuttige sanity check voordat u begint met schrijven naar uw database.

Uw taken bekijken en beheren

U kunt de takeninventaris filteren op status, zodat u op elk moment ziet wat er daadwerkelijk op uw account draait:

# List all currently running jobs
running_jobs = client.batch.jobs.list(status="RUNNING")
for j in running_jobs.data:
    print(f"Job {j.id} - Model: {j.model} - Created: {j.created_at}")

En wanneer een taak sleurt of u na indiening een prompt-fout ontdekt, voorkomt annulering dat u betaalt voor nutteloze verwerking:

# Cancel a job that is taking too long
client.batch.jobs.cancel(job_id="job-abc123")

Annulering is asynchroon: de status gaat eerst naar CANCELLATION_REQUESTED en vervolgens naar CANCELLED zodra de stop effectief is. Beschouw de resource niet als onmiddellijk vrijgegeven zodra de aanroep terugkeert.

End-to-end workflow

Samengevoegd vormen deze vier stappen een kort script dat u direct in een planner kunt plaatsen:

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

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

# 1. Upload the file
with open("batch_requests.jsonl", "rb") as f:
    batch_file = client.files.upload(
        file={"file_name": "batch_requests.jsonl", "content": f},
        purpose="batch"
    )

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

# 3. Wait for completion
completed = wait_for_batch(client, job.id)

# 4. Download and parse results
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 failed: {completed.status}")

Hergebruik dit skelet op uw eigen corpus met slechts tien regels: u valideert de volledige keten in enkele minuten voordat u overgaat tot het volledige volume.

Belangrijkste punten

  • Maak een batchtaak met client.batch.jobs.create() door het bestand, model en eindpunt op te geven
  • Zeven mogelijke statussen, waaronder drie definitieve: SUCCESS, FAILED, CANCELLED
  • Pollen met een interval is het standaardpatroon voor het volgen van de voortgang
  • Resultaten zijn in JSONL-formaat, gekoppeld aan verzoeken via custom_id
  • U kunt uw taken op elk moment bekijken, inspecteren en annuleren