Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Formát JSONL, custom_id a nahrávání souborů

Lekce 2 z 16 Aktualizováno 3. listopadu 2026 Pokročilý
Na této stránce
  1. Formát JSONL: Páteř dávkového odvozování (Batch Inference)
  2. Struktura požadavku v JSONL
  3. Generování souboru JSONL v Pythonu
  4. Nahrání souboru do Mistralu
  5. Validace souboru
  6. Limity a omezení
  7. Klíčové poznatky

Aktualizováno 3. listopadu 2026: U SDK mistralai verze 3.7.0 očekává metoda files.upload parametr file={"file_name": …, "content": …} (předání n-tice vyvolá chybu ValidationError ještě před odesláním jakýchkoli dat) a velikost souboru je dostupná v atributu size_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í:

  1. Přejdi na console.mistral.ai/build/files
  2. Klikni na „Upload“
  3. Vyber svůj soubor JSONL
  4. 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_id a body odpoví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