Formát JSONL, custom_id a nahrávanie súborov
Na tejto strane
Aktualizované 3. novembra 2026: Pri SDK
mistralai3.7.0 očakávafiles.uploadparameterfile={"file_name": …, "content": …}(odovzdanie tuple vyvoláValidationErrorešte pred odoslaním akýchkoľvek dát) a veľkosť súboru je dostupná vsize_bytes.
Formát JSONL: Chrbtová kosť dávkového odvodzovania
JSONL (JSON Lines) je štandardný formát, ktorý Mistral používa na štruktúrovanie dávkových požiadaviek. Každý riadok v súbore predstavuje samostatný objekt JSON zodpovedajúci jednej požiadavke. Tento dizajn je zámerný: môžeš generovať milión-riadkový súbor prúdením (streaming) bez toho, aby si ho celý načítal do pamäte, čítať ho späť riadok po riadku a manuálne kontrolovať konkrétne záznamy, keď požiadavka zlyhá. Na rozdiel od jedného obrovského poľa JSON, ktoré ťa núti načítať celý súbor len na overenie jedného záznamu, JSONL ti umožňuje pracovať na úrovni riadkov.
Štruktúra požiadavky v JSONL
Každý riadok v tvojom súbore JSONL musí obsahovať dve povinné polia:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Summarize this document in 3 points."}
]
}
}
custom_id je jedinečný identifikátor, ktorý definuješ ty pre každú požiadavku. Práve vďaka nemu sú výsledky použiteľné. Mistral nezaručuje poradie spracovania: výstupný súbor môže začínať požiadavkou číslo 8 472. Bez custom_id skončíš s kopou odpovedí a bez spôsobu, ako zistiť, ktorému dokumentu ktorá zodpovedá. Zvykni si odvodiť toto ID z vlastného referenčného systému – napríklad doc-001, email-2024-03-15-042, product-sku-ABC123 – namiesto použitia anonymného počítadla. Keď odpoveď spôsobí problémy, dokážeš ju vystopovať späť k zdroju bez potreby spúšťať SQL dotaz. Platia tu dve praktické pravidlá: ID musia byť v rámci súboru jedinečné, inak spracovanie vráti chybu, a mali by byť primerane krátke, pretože 200-znakový identifikátor robí logy nečitateľnými.
Pole body nevyžaduje žiadne nové učenie: obsahuje presne tú istú štruktúru, ktorú by si použil pri synchronnom volaní API na cieľový koncový bod. Ak cieliš na /v1/chat/completions, telo požiadavky je identické s tým, čo by si odovzdal vo volaní client.chat.complete(). Prompt overený interaktívne sa priamo prekladá do dávkovej úlohy.
Generovanie súboru JSONL v Pythone
Takto programovo vygeneruješ súbor JSONL zo zoznamu dokumentov:
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")
Všimni si parameter ensure_ascii=False. Bez neho funkcia json.dumps escapuje znaky s diakritikou ako sekvencie \uXXXX. Súbor zostane platný, ale stane sa pre ľudí nečitateľným, čím sa akékoľvek ladenie na francúzskom korpuse zmení na cvičenie v dešifrovaní. Urob z tohto nastavenia svoj štandard hneď od prvého riadku kódu.
Nahrávanie súboru do Mistralu
V produkčnom prostredí nahraj súbor cez Python API:
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}")
Parameter purpose="batch" hovorí Mistralu, že tento súbor je určený na dávkové spracovanie, nie na iné funkcie, ako je jemné doladenie (fine-tuning) alebo RAG. Toto vyhlásenie o zámere určuje, čo sa stane ďalej: súbor nahraný s nesprávnym účelom bude úlohou odmietnutý.
Pre rýchly test alebo pre netechnické tímy ponúka AI Studio rovnakú službu cez grafické rozhranie:
- Prejdi na
console.mistral.ai/build/files - Klikni na „Upload“
- Vyber svoj súbor JSONL
- Zvoľ účel „Batch Processing“
Rozhranie vráti file_id, presne ako API, a toto je identifikátor, ktorý použiješ na vytvorenie dávkovej úlohy.
Validácia súboru
Dávková úloha s miliónom riadkov, ktorá zlyhá na riadku 300 kvôli duplicitnému custom_id, ťa pripraví o celý čakací cyklus. Pár sekúnd lokálnej validácie tejto strate predíde. Nasledujúci skript vykoná jeden prechod súborom, aby skontroloval platnosť JSON, prítomnosť dvoch povinných polí a jedinečnosť 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.")
Urob z tohto systematický krok v svojom prípravnom pipeline, ktorý sa vykoná tesne pred nahraním.
Limity a obmedzenia
Dávkovanie súborov je obmedzené na jeden milión riadkov na súbor, čo znamená, že väčšie korpusy musíš rozdeliť na viacero odovzdaní. Kódovanie musí byť UTF-8 a formát striktne vyžaduje jeden objekt JSON na riadok: objekt JSON rozprestretý cez viacero riadkov, ako vznikne pri nevhodnom použití json.dumps(..., indent=2), rozbije parsovanie na strane servera. Nakoniec si pamätaj na dve už spomenuté pravidlá, pretože ich porušenie spôsobí zlyhanie úlohy: custom_id musí byť v rámci súboru jedinečné a body musí zodpovedať schéme cieľového koncového bodu.
Kľúčové poznatky
- JSONL štruktúruje tvoje dávkové požiadavky s jedným objektom JSON na riadok
- Každá požiadavka vyžaduje jedinečné
custom_idabodyzodpovedajúce cieľovému koncovému bodu - Nahraj súbor cez Python API (
client.files.upload) alebo prostredníctvom AI Studio - Vždy validuj svoj súbor pred odoslaním, aby si sa vyhol chybám pri spracovaní
- Použi
ensure_ascii=Falsepre francúzštinu a znaky s diakritikou