Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Format JSONL, custom_id et téléversement de fichier

Lektion 2 av 16 Uppdaterad 3 november 2026 Avancerad
På denna sida
  1. Le format JSONL : la colonne vertébrale de l’inférence par lots
  2. Structure d’une requête JSONL
  3. Générer un fichier JSONL en Python
  4. Téléverser le fichier vers Mistral
  5. Validation du fichier
  6. Limites et contraintes
  7. Viktiga punkter

Mis à jour le 3 novembre 2026 : Avec le SDK mistralai 3.7.0, files.upload attend file={"file_name": …, "content": …} (passer un tuple déclenche une ValidationError avant tout envoi de données), et la taille du fichier est disponible dans size_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 :

  1. Rends-toi sur console.mistral.ai/build/files
  2. Clique sur « Upload »
  3. Sélectionne ton fichier JSONL
  4. 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_id unique et un body correspondant 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=False pour le français et les caractères accentués