Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Format JSONL, custom_id i prijenos datoteka

Lekcija 2 od 16 Ažurirano 3. studenoga 2026. Napredno
Na ovoj stranici
  1. Format JSONL: Temelj batch inferencije
  2. Struktura JSONL zahtjeva
  3. Generiranje JSONL datoteke u Pythonu
  4. Prijenos datoteke na Mistral
  5. Validacija datoteke
  6. Ograničenja i ograničenja
  7. Ključne točke

Ažurirano 3. studenog 2026.: Uz SDK mistralai 3.7.0, files.upload očekuje file={"file_name": …, "content": …} (prosljeđivanje tuplea izaziva ValidationError prije slanja bilo kakvih podataka), a veličina datoteke dostupna je u size_bytes.

Format JSONL: Temelj batch inferencije

JSONL (JSON Lines) standardni je format koji Mistral koristi za strukturiranje batch zahtjeva. Svaki redak u datoteci samostalni je JSON objekt koji predstavlja jedan zahtjev. Ovaj dizajn namjeran je: možeš generirati datoteku od milijun redaka u streamu bez učitavanja cijele datoteke u memoriju, čitati je redak po redak i ručno pregledavati specifične unose kada zahtjev ne uspije. Za razliku od jednog golemog JSON polja koje te prisiljava učitati cijelu datoteku samo da bi provjerio jedan unos, JSONL ti omogućuje rad na razini retka.

Struktura JSONL zahtjeva

Svaki redak u tvojoj JSONL datoteci mora sadržavati dva obavezna polja:

{
  "custom_id": "req-001",
  "body": {
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Summarize this document in 3 points."}
    ]
  }
}

custom_id jedinstveni je identifikator koji ti definiraš za svaki zahtjev. On je ono što rezultate čini upotrebljivima. Mistral ne jamči redoslijed obrade: izlazna datoteka može započeti zahtjevom broj 8.472. Bez custom_id-a završavaš s hrpom odgovora i nemaš načina znati kojem dokumentu koji odgovor pripada. Uvedi si naviku da ovaj ID izvodiš iz vlastitog referentnog sustava—doc-001, email-2024-03-15-042, product-sku-ABC123—umjesto korištenja anonimnog brojača. Kada odgovor izazove probleme, možeš ga pratiti natrag do izvora bez pokretanja SQL upita. Ovdje vrijede dva praktična pravila: ID-ovi moraju biti jedinstveni unutar datoteke, inače će obrada vratiti pogrešku, i trebali bi biti razumno kratki jer identifikator od 200 znakova čini zapise nečitkima.

Polje body ne zahtijeva novo učenje: sadrži točnu strukturu koju bi koristio za sinkroni API poziv ciljanom endpointu. Ako ciljaš /v1/chat/completions, tijelo je identično onome što bi proslijedio u pozivu client.chat.complete(). Upit validiran interaktivno izravno se prevodi u batch posao.

Generiranje JSONL datoteke u Pythonu

Evo kako programski generirati JSONL datoteku iz popisa dokumenata:

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")

Obrati pažnju na parametar ensure_ascii=False. Bez njega, json.dumps escapeira akcentirane znakove kao sekvence \uXXXX. Datoteka ostaje valjana, ali postaje nemoguća za ljudsko čitanje, pretvarajući svako otklanjanje grešaka na francuskom korpusu u vježbu dešifriranja. Neka ti ovo bude zadana postavka od prvog retka koda.

Prijenos datoteke na Mistral

U produkciji prijenos vrši putem Python API-ja:

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}")

Parametar purpose="batch" govori Mistralu da je ova datoteka namijenjena batch obradi, a ne drugim značajkama poput finog podešavanja (fine-tuning) ili RAG-a. Ova deklaracija namjere diktira što se događa dalje: datoteka prenesena s pogrešnom namjenom bit će odbijena od strane posla.

Za brzi test ili za netehničke timove, AI Studio nudi istu uslugu putem grafičkog sučelja:

  1. Idi na console.mistral.ai/build/files
  2. Klikni „Upload“
  3. Odaberi svoju JSONL datoteku
  4. Odaberi namjenu „Batch Processing“

Sučelje vraća file_id, točno kao i API, a to je identifikator koji koristiš za stvaranje batch posla.

Validacija datoteke

Batch od milijun redaka koji ne uspije na retku 300 zbog dupliciranog custom_id-a košta te cijeli ciklus čekanja. Nekoliko sekundi lokalne validacije sprječava ovaj gubitak. Sljedeća skripta obavlja jedan prolaz kako bi provjerila valjanost JSON-a, prisutnost dva obavezna polja i jedinstvenost ID-ova:

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.")

Neka ovo bude sustavan korak u tvom pripremnom procesu, koji se izvršava neposredno prije prijenosa.

Ograničenja i ograničenja

Batchiranje datoteka ograničeno je na milijun redaka po datoteci, što znači da moraš podijeliti veće korpuse na više podnošenja. Kodiranje mora biti UTF-8, a format strogo zahtijeva jedan JSON objekt po retku: JSON objekt raspoređen na više redaka, kao što proizvodi pogrešno postavljeno json.dumps(..., indent=2), ruši parsersku obradu na strani poslužitelja. Konačno, zapamti dva već spomenuta pravila, jer njihovo kršenje uzrokuje neuspjeh posla: custom_id mora biti jedinstven unutar datoteke, a body mora odgovarati shemi ciljanog endpointa.

Ključne točke

  • JSONL strukturira tvoje batch zahtjeve s jednim JSON objektom po retku
  • Svaki zahtjev zahtijeva jedinstveni custom_id i body koji odgovara ciljanom endpointu
  • Prijenos vrši putem Python API-ja (client.files.upload) ili kroz AI Studio
  • Uvijek validiraj svoju datoteku prije podnošenja kako bi izbjegao pogreške u obradi
  • Koristi ensure_ascii=False za francuske i akcentirane znakove