JSONL-format, custom_id og filupload
På denne side
Opdateret 3. november 2026: Med SDK
mistralai3.7.0 forventerfiles.uploadparametretfile={"file_name": …, "content": …}(hvis du sender en tuple, udløses enValidationError, før nogen data sendes), og filstørrelsen er tilgængelig isize_bytes.
JSONL-formatet: Rygraden i batch-inferens
JSONL (JSON Lines) er standardformatet, som Mistral bruger til at strukturere batch-anmodninger. Hver linje i filen er et selvstændigt JSON-objekt, der repræsenterer en enkelt anmodning. Dette design er bevidst valgt: Du kan streame-generere en fil med en million linjer uden at indlæse hele filen i hukommelsen, læse den tilbage linje for linje og manuelt inspicere specifikke poster, hvis en anmodning fejler. I modsætning til et enkelt massivt JSON-array, som tvinger dig til at indlæse hele filen blot for at verificere én post, giver JSONL dig mulighed for at arbejde på linjeniveau.
Struktur for JSONL-anmodninger
Hver linje i din JSONL-fil skal indeholde to påkrævede felter:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Summarize this document in 3 points."}
]
}
}
custom_id er en unik identifikator, som du definerer for hver anmodning. Det er dette felt, der gør resultaterne brugbare. Mistral garanterer ikke behandlingsrækkefølgen: Outputfilen kan starte med anmodning 8.472. Uden et custom_id ender du med en bunke svar uden mulighed for at vide, hvilket dokument hvert svar svarer til. Gør det til en vane at udlede denne ID fra dit eget referencesystem – f.eks. doc-001, email-2024-03-15-042, product-sku-ABC123 – i stedet for at bruge en anonym tæller. Når et svar giver problemer, kan du spore det tilbage til kilden uden at skulle køre en SQL-forespørgsel. To praktiske regler gælder her: ID’er skal være unikke inden for filen, ellers returnerer behandlingen en fejl, og de bør være rimeligt korte, da en identifikator på 200 tegn gør logs ulæselige.
Feltet body kræver ingen ny læring: Det indeholder nøjagtig den struktur, du ville bruge til et synkront API-kald til mål-endpointet. Hvis du retter dig mod /v1/chat/completions, er body identisk med det, du ville sende i et client.chat.complete()-kald. En prompt, der er valideret interaktivt, oversættes direkte til et batch-job.
Generering af en JSONL-fil i Python
Sådan genererer du programmatisk en JSONL-fil fra en liste over dokumenter:
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")
Bemærk parameteren ensure_ascii=False. Uden denne vil json.dumps escape’e accenterede tegn som \uXXXX-sekvenser. Filen forbliver gyldig, men bliver umulig for mennesker at læse, hvilket gør enhver fejlsøgning på et fransk korpus til en dekrypteringsøvelse. Gør dette til din standard fra første linje kode.
Upload af filen til Mistral
I produktion uploader du via Python-API’et:
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}")
Parameteren purpose="batch" fortæller Mistral, at denne fil er beregnet til batch-behandling og ikke til andre funktioner som fine-tuning eller RAG. Denne hensigtserklæring dikterer, hvad der sker derefter: En fil uploadet med forkert formål vil blive afvist af jobbet.
Til en hurtig test eller for ikke-tekniske teams tilbyder AI Studio den samme service via GUI’en:
- Gå til
console.mistral.ai/build/files - Klik på „Upload”
- Vælg din JSONL-fil
- Vælg formålet „Batch Processing”
Grænsefladen returnerer et file_id, præcis som API’et, og dette er den identifikator, du bruger til at oprette batch-jobbet.
Filvalidering
Et batch på en million linjer, der fejler ved linje 300 på grund af et duplikeret custom_id, koster dig en hel ventecyklus. Få sekunders lokal validering forhindrer dette tab. Følgende script udfører et enkelt gennembløb for at tjekke JSON-gyldighed, tilstedeværelsen af de to påkrævede felter og ID-unikitet:
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.")
Gør dette til et systematisk trin i din forberedelsespipeline, udført lige før upload.
Grænser og begrænsninger
Fil-batching er begrænset til én million linjer pr. fil, hvilket betyder, at du skal opdele større korpusser i flere indsendelser. Kodningen skal være UTF-8, og formatet kræver strengt ét JSON-objekt pr. linje: Et JSON-objekt fordelt over flere linjer, som produceret af en fejlplaceret json.dumps(..., indent=2), bryder server-side parsing. Husk endelig de to regler, der allerede er nævnt, da overtrædelse af dem får jobbet til at fejle: custom_id skal være unikt inden for filen, og body skal matche skemaet for mål-endpointet.
Vigtige pointer
- JSONL strukturerer dine batch-anmodninger med ét JSON-objekt pr. linje
- Hver anmodning kræver et unikt
custom_idog enbody, der matcher mål-endpointet - Upload via Python-API’et (
client.files.upload) eller gennem AI Studio - Valider altid din fil før indsendelse for at undgå behandlingsfejl
- Brug
ensure_ascii=Falsetil franske og accenterede tegn