Format JSONL, custom_id i prijenos datoteka
Na ovoj stranici
Ažurirano 3. studenog 2026.: Uz SDK
mistralai3.7.0,files.uploadočekujefile={"file_name": …, "content": …}(prosljeđivanje tuplea izazivaValidationErrorprije slanja bilo kakvih podataka), a veličina datoteke dostupna je usize_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:
- Idi na
console.mistral.ai/build/files - Klikni „Upload“
- Odaberi svoju JSONL datoteku
- 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_idibodykoji 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=Falseza francuske i akcentirane znakove