Formát JSONL, custom_id a nahrávání souborů
Na této stránce
Aktualizováno 3. listopadu 2026: U SDK
mistralaiverze 3.7.0 očekává metodafiles.uploadparametrfile={"file_name": …, "content": …}(předání n-tice vyvolá chybuValidationErrorještě před odesláním jakýchkoli dat) a velikost souboru je dostupná v atributusize_bytes.
Formát JSONL: Páteř dávkového odvozování (Batch Inference)
JSONL (JSON Lines) je standardní formát, který Mistral používá ke strukturování dávkových požadavků. Každý řádek v souboru představuje samostatný objekt JSON odpovídající jedinému požadavku. Tento návrh je záměrný: můžeš generovat milionřádkový soubor proudově, aniž bys ho musel celý načíst do paměti, číst ho zpět řádek po řádku a ručně kontrolovat konkrétní záznamy v případě selhání požadavku. Na rozdíl od jednoho obrovského pole JSON, které tě nutí načíst celý soubor jen pro ověření jedné položky, ti JSONL umožňuje pracovat na úrovni řádků.
Struktura požadavku v JSONL
Každý řádek v tvém souboru JSONL musí obsahovat dvě povinná pole:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Summarize this document in 3 points."}
]
}
}
custom_id je unikátní identifikátor, který ty definuješ pro každý požadavek. Právě ten činí výsledky použitelnými. Mistral nezaručuje pořadí zpracování: výstupní soubor může začít požadavkem číslo 8 472. Bez custom_id skončíš s hromadou odpovědí a nebudeš mít způsob, jak zjistit, ke kterému dokumentu která patří. Zvykni si odvozovat toto ID z vlastního referenčního systému – doc-001, email-2024-03-15-042, product-sku-ABC123 – místo používání anonymního čítače. Když odpověď způsobí problémy, dokážeš ji vysledovat zpět ke zdroji bez nutnosti spouštět dotaz SQL. Platí zde dvě praktická pravidla: ID musí být v rámci souboru unikátní, jinak zpracování vrátí chybu, a měla by být přiměřeně krátká, protože identifikátor o délce 200 znaků činí logy nečitelnými.
Pole body nevyžaduje žádné nové znalosti: obsahuje přesně stejnou strukturu, jakou bys použil pro synchronní volání API na cílový koncový bod. Pokud cílíš na /v1/chat/completions, tělo požadavku je totožné s tím, co bys předal ve volání client.chat.complete(). Prompt ověřený interaktivně se přímo převádí na dávkovou úlohu.
Generování souboru JSONL v Pythonu
Zde je ukázka, jak programově vygenerovat soubor JSONL ze seznamu dokumentů:
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 parametru ensure_ascii=False. Bez něj by json.dumps escapoval znaky s diakritikou jako sekvence \uXXXX. Soubor by sice zůstal platný, ale stal by se pro člověka nečitelným, čímž by se jakékoli ladění na francouzském korpusu změnilo v luštění šifer. Udělej z toho svůj výchozí postup hned od prvního řádku kódu.
Nahrání souboru do Mistralu
V produkčním prostředí nahraj soubor prostřednictvím 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}")
Parametr purpose="batch" sděluje Mistralu, že tento soubor je určen pro dávkové zpracování, nikoli pro jiné funkce, jako je jemné ladění (fine-tuning) nebo RAG. Toto prohlášení o záměru určuje, co se stane dál: soubor nahraný se špatným účelem bude úlohou odmítnut.
Pro rychlý test nebo pro netechnické týmy nabízí AI Studio stejnou službu prostřednictvím grafického rozhraní:
- Přejdi na
console.mistral.ai/build/files - Klikni na „Upload“
- Vyber svůj soubor JSONL
- Zvol účel „Batch Processing“
Rozhraní vrátí file_id, přesně jako API, a tento identifikátor použiješ k vytvoření dávkové úlohy.
Validace souboru
Dávková úloha o milionu řádcích, která selže na řádku 300 kvůli duplicitnímu custom_id, tě připraví o celý čekací cyklus. Několik sekund lokální validace této ztrátě předejde. Následující skript provede jediný průchod souborem, aby zkontroloval platnost JSON, přítomnost dvou povinných polí a unikátnost 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.")
Udělej z tohoto kroku systematickou součást svého přípravného pipeline, která se spustí těsně před nahráním.
Limity a omezení
Dávkování souborů je omezeno na jeden milion řádků na soubor, což znamená, že větší korpusy musíš rozdělit do více odeslání. Kódování musí být UTF-8 a formát striktně vyžaduje jeden objekt JSON na řádek: objekt JSON rozložený do více řádků, jak vznikne při misplaced json.dumps(..., indent=2), rozbije parsování na straně serveru. Nakonec si pamatuj dvě již zmíněná pravidla, jejichž porušení způsobí selhání úlohy: custom_id musí být v rámci souboru unikátní a body musí odpovídat schématu cílového koncového bodu.
Klíčové poznatky
- JSONL strukturuje tvé dávkové požadavky s jedním objektem JSON na řádek
- Každý požadavek vyžaduje unikátní
custom_idabodyodpovídající cílovému koncovému bodu - Nahrávej prostřednictvím Python API (
client.files.upload) nebo přes AI Studio - Před odesláním vždy validuj svůj soubor, abys předešel chybám při zpracování
- Pro francouzštinu a znaky s diakritikou používej
ensure_ascii=False