Indeling JSONL, custom_id en uploaden van bestanden
Op deze pagina
Bijgewerkt op 3 november 2026: Met SDK
mistralai3.7.0 verwachtfiles.uploadde parameterfile={"file_name": …, "content": …}(het doorgeven van een tuple leidt tot eenValidationErrorvoordat er gegevens worden verzonden), en is de bestandsgrootte beschikbaar viasize_bytes.
De JSONL-indeling: de ruggengraat van batch-inferentie
JSONL (JSON Lines) is de standaardindeling die Mistral gebruikt om batch-aanvragen te structureren. Elke regel in het bestand is een op zichzelf staand JSON-object dat één enkele aanvraag vertegenwoordigt. Dit ontwerp is bewust gekozen: u kunt een bestand met een miljoen regels stream-genereren zonder het volledig in het geheugen te laden, het regel voor regel teruglezen en specifieke items handmatig inspecteren wanneer een aanvraag mislukt. In tegenstelling tot één enorm JSON-array, waarbij u het volledige bestand moet laden om slechts één item te verifiëren, stelt JSONL u in staat om op regelniveau te werken.
Structuur van een JSONL-aanvraag
Elke regel in uw JSONL-bestand moet twee verplichte velden bevatten:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Summarize this document in 3 points."}
]
}
}
De custom_id is een unieke identificatiecode die u zelf definieert voor elke aanvraag. Dit is wat de resultaten bruikbaar maakt. Mistral garandeert geen verwerkingsvolgorde: het uitvoerbestand kan beginnen met aanvraag 8.472. Zonder een custom_id houdt u een stapel antwoorden over zonder enige manier om te weten welk document bij welk antwoord hoort. Maak er een gewoonte van om deze ID af te leiden uit uw eigen referentiesysteem—doc-001, email-2024-03-15-042, product-sku-ABC123—in plaats van een anonieme teller te gebruiken. Wanneer een antwoord problemen veroorzaakt, kunt u dit terug traceren naar de bron zonder een SQL-query uit te voeren. Twee praktische regels zijn hier van toepassing: ID’s moeten uniek zijn binnen het bestand, anders retourneert de verwerking een fout, en ze moeten redelijk kort zijn, aangezien een identificatiecode van 200 tekens logs onleesbaar maakt.
Het veld body vereist geen nieuwe kennis: het bevat exact dezelfde structuur die u zou gebruiken voor een synchrone API-aanroep naar het doeleindpunt. Als u richt op /v1/chat/completions, is de body identiek aan wat u zou doorgeven in een client.chat.complete()-aanroep. Een prompt die interactief is gevalideerd, vertaalt zich direct naar een batchtaak.
Programmatisch genereren van een JSONL-bestand in Python
Hier ziet u hoe u programmatisch een JSONL-bestand genereert vanuit een lijst met documenten:
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")
Let op de parameter ensure_ascii=False. Zonder deze parameter escaleert json.dumps tekens met accenten als \uXXXX-reeksen. Het bestand blijft geldig, maar wordt onleesbaar voor mensen, waardoor elke debugging op een Frans corpus verandert in een decodeeroefening. Maak dit vanaf de eerste regel code tot uw standaard.
Het bestand uploaden naar Mistral
In productieomgevingen uploadt u via de Python-API:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Upload het JSONL-bestand
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}")
De parameter purpose="batch" vertelt Mistral dat dit bestand bestemd is voor batchverwerking en niet voor andere functies zoals fine-tuning of RAG. Deze intentieverklaring bepaalt wat er vervolgens gebeurt: een bestand dat met het verkeerde doel wordt geüpload, wordt door de taak geweigerd.
Voor een snelle test of voor niet-technische teams biedt AI Studio dezelfde service via de grafische interface:
- Ga naar
console.mistral.ai/build/files - Klik op “Upload”
- Selecteer uw JSONL-bestand
- Kies het doel “Batch Processing”
De interface retourneert een file_id, precies zoals de API, en dit is de identificatiecode die u gebruikt om de batchtaak aan te maken.
Validatie van bestanden
Een batch van een miljoen regels die faalt op regel 300 vanwege een dubbele custom_id, kost u een volledige wachtcyclus. Een paar seconden lokale validatie voorkomt dit verlies. Het volgende script voert één pass uit om de JSON-geldigheid, de aanwezigheid van de twee verplichte velden en de uniciteit van de ID’s te controleren:
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
# Controleer verplichte velden
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")
# Controleer uniciteit van custom_id
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.")
Maak dit tot een systematische stap in uw voorbereidingspijplijn, uitgevoerd vlak voor het uploaden.
Limieten en beperkingen
Bestandsbatching is beperkt tot één miljoen regels per bestand, wat betekent dat u grotere corpora moet splitsen in meerdere inzendingen. De codering moet UTF-8 zijn en de indeling vereist strikt één JSON-object per regel: een JSON-object dat over meerdere regels is verspreid, zoals geproduceerd door een misplaatste json.dumps(..., indent=2), verbreekt de parsing aan de serverzijde. Onthoud tot slot de twee reeds genoemde regels, aangezien overtreding ervan ervoor zorgt dat de taak mislukt: de custom_id moet uniek zijn binnen het bestand en de body moet overeenkomen met het schema van het doeleindpunt.
Belangrijkste punten
- JSONL structureert uw batch-aanvragen met één JSON-object per regel
- Elke aanvraag vereist een unieke
custom_iden eenbodydie overeenkomt met het doeleindpunt - Upload via de Python-API (
client.files.upload) of via AI Studio - Valideer uw bestand altijd voordat u het indient om verwerkingsfouten te voorkomen
- Gebruik
ensure_ascii=Falsevoor Franse teksten en tekens met accenten