Créer un job par lots, suivre son statut et télécharger les résultats
In questa pagina
Mis à jour le 3 novembre 2026 : Addendum du 3 novembre :
files.downloadrenvoie une réponse HTTP (httpx2.Response) ; lis son contenu avec.read()avant d’appeler.decode(). L’upload attendfile={"file_name": …, "content": …}. La clé API n’est plus codée en dur.
Du fichier JSONL aux résultats : le cycle de vie complet
Ton fichier JSONL est prêt et uploadé, et tu disposes d’un file_id. L’étape suivante consiste à transformer ce fichier dormant en résultats exploitables : créer le job par lots, surveiller sa progression pendant les minutes ou heures que dure le traitement, puis récupérer et réconcilier les réponses. Cette leçon parcourt le code Python de bout en bout, exactement dans l’ordre où tu l’écriras.
Créer un job par lots
La création nécessite un seul appel. Tu spécifies le fichier source, le modèle et le point de terminaison cible :
from mistralai.client import Mistral
import time
client = Mistral(api_key="your-api-key")
# Créer le job par lots
job = client.batch.jobs.create(
input_files=[batch_file.id], # ID du fichier uploadé
model="mistral-small-latest",
endpoint="/v1/chat/completions",
metadata={"project": "document-analysis", "version": "1.0"}
)
print(f"Job créé : {job.id}")
print(f"Statut initial : {job.status}")
Chaque paramètre mérite une note :
input_files— Une liste d’IDs de fichiers uploadés. Tu peux passer plusieurs fichiers à un seul job.model— Le modèle Mistral à utiliser. Un seul modèle par job par lots.endpoint— Le point de terminaison API cible (doit correspondre au formatbodyde ton JSONL).metadata— Un dictionnaire optionnel de métadonnées personnalisées pour organiser et retrouver tes jobs.
La contrainte d’un seul modèle par job structure la façon dont tu découpes ton travail : si tu veux comparer deux modèles sur le même corpus, soumets deux jobs distincts pointant vers le même fichier. Quant aux métadonnées, elles peuvent sembler anecdotiques jusqu’à ce que tu aies trente jobs dans ton historique ; la paire projet/version montrée ci-dessus te permet alors de trouver le lot ayant produit des données douteuses en trois secondes chrono.
Statuts des jobs par lots
Un job par lots traverse plusieurs états durant son cycle de vie :
| Statut | Description |
|---|---|
QUEUED | En file d’attente, pas encore démarré |
RUNNING | Traitement en cours |
SUCCESS | Terminé avec succès |
FAILED | Échec du traitement |
TIMEOUT_EXCEEDED | Délai d’exécution dépassé |
CANCELLATION_REQUESTED | Annulation demandée |
CANCELLED | Annulé |
Quatre de ces sept états sont terminaux — SUCCESS, FAILED, TIMEOUT_EXCEEDED et CANCELLED — et cette distinction pilote la boucle de surveillance : tant que le statut n’est pas dans cet ensemble, le job est toujours vivant et tu dois attendre. CANCELLATION_REQUESTED, en particulier, n’est pas un état d’arrêt mais un état de transition ; un code qui le traiterait comme terminal sortirait de la boucle trop tôt.
Suivre la progression
Le motif de sondage ci-dessous encapsule exactement cette logique, avec une garde-fou de durée maximale pour empêcher un script oublié de tourner indéfiniment :
def wait_for_batch(client, job_id, poll_interval=10, max_wait=3600):
"""Attendre qu'un job par lots se termine en utilisant le sondage."""
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] Statut : {job.status}")
if job.status in terminal_states:
return job
time.sleep(poll_interval)
elapsed += poll_interval
raise TimeoutError(f"Job {job_id} toujours en cours après {max_wait}s")
# Utilisation
completed_job = wait_for_batch(client, job.id)
print(f"Résultat final : {completed_job.status}")
Un intervalle de dix secondes fonctionne pour un lot durant quelques minutes ; pour une exécution nocturne traitant plusieurs centaines de milliers de lignes, augmente-le à une minute ou plus. Une précision de sondage accrue n’apporte aucune valeur dans ce cas et ne fait qu’accumuler des appels API inutiles.
Télécharger les résultats
Une fois le statut passé à SUCCESS, le job expose un output_file que tu télécharges et parses ligne par ligne :
import json
if completed_job.status == "SUCCESS":
# Récupérer l'ID du fichier de sortie
output_file_id = completed_job.output_file
# Télécharger le contenu
result_data = client.files.download(file_id=output_file_id)
# Parser les résultats JSONL
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
# Afficher un exemple
for cid, resp in list(results.items())[:3]:
content = resp["body"]["choices"][0]["message"]["content"]
print(f"\n--- {cid} ---")
print(content[:200])
Le fichier de résultats est également au format JSONL, et chaque ligne porte l’custom_id original alongside la réponse complète du modèle. C’est ici que l’effort de nommage de la leçon précédente porte ses fruits : l’indexation par custom_id dans un dictionnaire suffit à réconcilier les réponses avec tes documents sources, quel que soit l’ordre de leur retour. L’affichage des trois premières entrées tronquées à 200 caractères constitue une vérification de bon sens utile avant de commencer à écrire dans ta base de données.
Lister et gérer tes jobs
Tu peux filtrer l’inventaire des jobs par statut, ce qui te permet de voir à tout moment ce qui tourne réellement sur ton compte :
# Lister tous les jobs actuellement en cours d'exécution
running_jobs = client.batch.jobs.list(status="RUNNING")
for j in running_jobs.data:
print(f"Job {j.id} - Modèle : {j.model} - Créé : {j.created_at}")
Et lorsqu’un job traîne en longueur ou que tu repères une erreur de prompt après soumission, l’annulation évite de payer pour un traitement inutile :
# Annuler un job qui prend trop de temps
client.batch.jobs.cancel(job_id="job-abc123")
L’annulation est asynchrone : le statut passe d’abord à CANCELLATION_REQUESTED, puis à CANCELLED une fois l’arrêt effectif. Ne considère pas la ressource comme libérée immédiatement au retour de l’appel.
Flux de travail de bout en bout
Assemblées, ces quatre étapes forment un court script que tu peux placer directement dans un planificateur :
from mistralai.client import Mistral
import json
import os
import time
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Upload du fichier
with open("batch_requests.jsonl", "rb") as f:
batch_file = client.files.upload(
file={"file_name": "batch_requests.jsonl", "content": f},
purpose="batch"
)
# 2. Création du job
job = client.batch.jobs.create(
input_files=[batch_file.id],
model="mistral-small-latest",
endpoint="/v1/chat/completions"
)
# 3. Attente de la fin
completed = wait_for_batch(client, job.id)
# 4. Téléchargement et parsing des résultats
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"Échec du lot : {completed.status}")
Réutilise ce squelette sur ton propre corpus avec seulement dix lignes : tu valideras toute la chaîne en quelques minutes avant de t’engager sur le volume complet.
Punti chiave
- Crée un job par lots avec
client.batch.jobs.create()en spécifiant le fichier, le modèle et le point de terminaison - Sept statuts possibles, dont trois terminaux :
SUCCESS,FAILED,CANCELLED - Le sondage avec un intervalle est le motif standard pour suivre la progression
- Les résultats sont au format JSONL, liés aux requêtes via
custom_id - Tu peux lister, inspecter et annuler tes jobs à tout moment