Een batchtaak maken, de status volgen en resultaten downloaden
Op deze pagina
Bijgewerkt op 3 november 2026: Addendum voor 3 november:
files.downloadretourneert een HTTP-respons (httpx2.Response); lees de inhoud met.read()voordat u.decode()aanroept. Upload verwachtfile={"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 hetbody-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:
| Status | Beschrijving |
|---|---|
QUEUED | In de wachtrij, nog niet gestart |
RUNNING | Verwerking bezig |
SUCCESS | Succesvol voltooid |
FAILED | Verwerking mislukt |
TIMEOUT_EXCEEDED | Uitvoeringstijdslimiet overschreden |
CANCELLATION_REQUESTED | Annulering aangevraagd |
CANCELLED | Geannuleerd |
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