Format JSONL, custom_id et téléversement de fichier
På denna sida
Mis à jour le 3 novembre 2026 : Avec le SDK
mistralai3.7.0,files.uploadattendfile={"file_name": …, "content": …}(passer un tuple déclenche uneValidationErroravant tout envoi de données), et la taille du fichier est disponible danssize_bytes.
Le format JSONL : la colonne vertébrale de l’inférence par lots
Le JSONL (JSON Lines) est le format standard utilisé par Mistral pour structurer les requêtes par lots. Chaque ligne du fichier constitue un objet JSON autonome représentant une seule requête. Cette conception est volontaire : tu peux générer en flux un fichier d’un million de lignes sans le charger entièrement en mémoire, le relire ligne par ligne et inspecter manuellement des entrées spécifiques lorsqu’une requête échoue. Contrairement à un unique tableau JSON massif, qui t’oblige à charger l’intégralité du fichier juste pour vérifier une entrée, le JSONL te permet de travailler au niveau de la ligne.
Structure d’une requête JSONL
Chaque ligne de ton fichier JSONL doit contenir deux champs obligatoires :
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Summarize this document in 3 points."}
]
}
}
Le custom_id est un identifiant unique que tu définis pour chaque requête. C’est ce qui rend les résultats exploitables. Mistral ne garantit pas l’ordre de traitement : le fichier de sortie peut commencer par la requête 8 472. Sans custom_id, tu te retrouves avec un tas de réponses et aucun moyen de savoir à quel document chacune correspond. Prends l’habitude de dériver cet ID de ton propre système de référence — doc-001, email-2024-03-15-042, product-sku-ABC123 — plutôt que d’utiliser un compteur anonyme. Lorsqu’une réponse pose problème, tu peux la retracer jusqu’à sa source sans exécuter de requête SQL. Deux règles pratiques s’appliquent ici : les ID doivent être uniques au sein du fichier, sinon le traitement renverra une erreur, et ils doivent rester raisonnablement courts, car un identifiant de 200 caractères rend les logs illisibles.
Le champ body ne nécessite aucun nouvel apprentissage : il contient exactement la structure que tu utiliserais pour un appel API synchrone vers le point de terminaison cible. Si tu cibles /v1/chat/completions, le corps est identique à celui que tu passerais dans un appel client.chat.complete(). Une invite validée en interactif se traduit directement en tâche par lots.
Générer un fichier JSONL en Python
Voici comment générer programmatiquement un fichier JSONL à partir d’une liste de documents :
import json
documents = [
{"id": "doc-001", "text": "Artificial intelligence is transforming..."},
{"id": "doc-002", "text": "Deep neural networks..."},
{"id": "doc-003", "text": "Natural language processing..."},
]
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": "You are an assistant that summarizes texts."
},
{
"role": "user",
"content": f"Summarize this text: {doc['text']}"
}
]
}
}
f.write(json.dumps(request, ensure_ascii=False) + "\n")
Note le paramètre ensure_ascii=False. Sans lui, json.dumps échappe les caractères accentués sous forme de séquences \uXXXX. Le fichier reste valide, mais devient impossible à lire pour un humain, transformant tout débogage sur un corpus français en exercice de décryptage. Fais-en ton défaut dès la première ligne de code.
Téléverser le fichier vers Mistral
En production, effectue le téléversement via l’API Python :
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Upload the JSONL file
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"Uploaded file: {batch_file.id}")
print(f"Size: {batch_file.size_bytes} bytes")
print(f"Purpose: {batch_file.purpose}")
Le paramètre purpose="batch" indique à Mistral que ce fichier est destiné au traitement par lots, et non à d’autres fonctionnalités comme le fine-tuning ou le RAG. Cette déclaration d’intention dicte la suite : un fichier téléversé avec un mauvais objectif sera rejeté par la tâche.
Pour un test rapide ou pour des équipes non techniques, AI Studio propose le même service via l’interface graphique :
- Rends-toi sur
console.mistral.ai/build/files - Clique sur « Upload »
- Sélectionne ton fichier JSONL
- Choisis l’objectif « Batch Processing »
L’interface renvoie un file_id, exactement comme l’API, et c’est cet identifiant que tu utilises pour créer la tâche par lots.
Validation du fichier
Un lot d’un million de lignes qui échoue à la ligne 300 à cause d’un custom_id en double te coûte un cycle d’attente complet. Quelques secondes de validation locale évitent cette perte. Le script suivant effectue un passage unique pour vérifier la validité JSON, la présence des deux champs requis et l’unicité des ID :
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"Line {line_num}: Invalid JSON - {e}")
continue
# Check required fields
if "custom_id" not in data:
errors.append(f"Line {line_num}: missing custom_id")
if "body" not in data:
errors.append(f"Line {line_num}: missing body")
# Check custom_id uniqueness
cid = data.get("custom_id")
if cid in seen_ids:
errors.append(f"Line {line_num}: duplicate custom_id '{cid}'")
seen_ids.add(cid)
if errors:
print(f"{len(errors)} error(s) found:")
for e in errors:
print(f" - {e}")
else:
print(f"File valid: {len(seen_ids)} requests ready.")
Fais de cette étape une procédure systématique dans ton pipeline de préparation, exécutée juste avant le téléversement.
Limites et contraintes
Le lot de fichiers est limité à un million de lignes par fichier, ce qui signifie que tu dois diviser les corpus plus volumineux en plusieurs soumissions. L’encodage doit être UTF-8 et le format exige strictement un objet JSON par ligne : un objet JSON réparti sur plusieurs lignes, comme produit par un json.dumps(..., indent=2) mal placé, brise l’analyse côté serveur. Enfin, rappelle-toi les deux règles déjà mentionnées, car leur violation entraîne l’échec de la tâche : le custom_id doit être unique dans le fichier et le body doit correspondre au schéma du point de terminaison cible.
Viktiga punkter
- Le JSONL structure tes requêtes par lots avec un objet JSON par ligne
- Chaque requête nécessite un
custom_idunique et unbodycorrespondant au point de terminaison cible - Téléverse via l’API Python (
client.files.upload) ou via AI Studio - Valide toujours ton fichier avant soumission pour éviter les erreurs de traitement
- Utilise
ensure_ascii=Falsepour le français et les caractères accentués