Format JSONL, custom_id in nalaganje datotek
Na tej strani
Posodobljeno 3. novembra 2026: Pri SDK
mistralairazličice 3.7.0 metodafiles.uploadpričakujefile={"file_name": …, "content": …}(podajanje terca sprožiValidationError, preden se pošljejo kakršni koli podatki), velikost datoteke pa je na voljo vsize_bytes.
Format JSONL: hrbtenica serijskega sklepanja
JSONL (JSON Lines) je standardni format, ki ga Mistral uporablja za strukturiranje serijskih zahtevkov. Vsaka vrstica v datoteki je samostojen objekt JSON, ki predstavlja en sam zahtevek. Ta zasnova je namerna: datoteko z milijonom vrstic lahko ustvarite s pretokom, ne da bi jo celotno naložili v pomnilnik, jo ponovno prebrali vrstico za vrstico in ročno pregledali specifične vnose, ko zahtevek odpove. Za razliko od enega samega ogromnega polja JSON, ki vas prisili, da naložite celotno datoteko zgolj za preverjanje enega vnosa, vam JSONL omogoča delo na ravni vrstice.
Struktura zahtevka JSONL
Vsaka vrstica v vaši datoteki JSONL mora vsebovati dve obvezni polji:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Povzemi ta dokument v 3 točkah."}
]
}
}
custom_id je edinstven identifikator, ki ga določiš ti za vsak zahtevek. Prav to omogoča uporabnost rezultatov. Mistral ne zagotavlja vrstnega reda obdelave: izhodna datoteka se lahko začne z zahtevkom št. 8.472. Brez custom_id končaš z kupom odgovorov in brez načina, da bi vedel, kateremu dokumentu pripada kateri odgovor. Naj ti postane navada, da ta ID izpelješ iz lastnega referenčnega sistema – doc-001, email-2024-03-15-042, product-sku-ABC123 – namesto uporabe anonimnega števca. Ko odgovor povzroči težave, ga lahko izslediš nazaj do vira brez zagona poizvedbe SQL. Tu veljata dve praktični pravili: ID-ji morajo biti znotraj datoteke edinstveni, sicer bo obdelava vrnila napako, in morajo biti razumno kratki, saj identifikator z 200 znaki naredi dnevnike neberljive.
Polje body ne zahteva novega učenja: vsebuje točno strukturo, ki bi jo uporabil za sinhroni klic API-ja do ciljne končne točke. Če ciljaš na /v1/chat/completions, je telo identično tistemu, ki bi ga podal v klicu client.chat.complete(). Poziv, validiran interaktivno, se neposredno prevede v serijsko opravilo.
Programsko ustvarjanje datoteke JSONL v Pythonu
Tako programsko ustvariš datoteko JSONL iz seznama dokumentov:
import json
documents = [
{"id": "doc-001", "text": "Umetna inteligenca spreminja..."},
{"id": "doc-002", "text": "Globoke nevronske mreže..."},
{"id": "doc-003", "text": "Obdelava naravnega jezika..."},
]
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": "Si pomočnik, ki povzema besedila."
},
{
"role": "user",
"content": f"Povzemi to besedilo: {doc['text']}"
}
]
}
}
f.write(json.dumps(request, ensure_ascii=False) + "\n")
Upoštevaj parameter ensure_ascii=False. Brez njega json.dumps ubežne znake z naglasi pretvori v zaporedja \uXXXX. Datoteka ostane veljavna, a postane za ljudi neberljiva, kar vsako razhroščevanje na francoskem korpusu spremeni v vadbo dešifriranja. To naj bo tvoja privzeta nastavitev že od prve vrstice kode.
Nalaganje datoteke v Mistral
V produkcijskem okolju nalaganje izvedi prek API-ja Python:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Naloži datoteko JSONL
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"Naložena datoteka: {batch_file.id}")
print(f"Velikost: {batch_file.size_bytes} bajtov")
print(f"Namen: {batch_file.purpose}")
Parameter purpose="batch" pove Mistralu, da je ta datoteka namenjena serijski obdelavi, ne drugim funkcijam, kot sta fino uglaševanje ali RAG. Ta izjava o namenu določa, kaj se zgodi nato: datoteka, naložena z napačnim namenom, bo zavrnjena s strani opravila.
Za hiter test ali za netehnične ekipe AI Studio ponuja isto storitev prek grafičnega vmesnika:
- Pojdi na
console.mistral.ai/build/files - Klikni „Upload”
- Izberi svojo datoteko JSONL
- Izberi namen „Batch Processing”
Vmesnik vrne file_id, popolnoma kot API, in to je identifikator, ki ga uporabiš za ustvarjanje serijskega opravila.
Validacija datoteke
Serijsko opravilo z milijonom vrstic, ki odpove pri vrstici 300 zaradi podvojenega custom_id, te stane celoten čakalni cikel. Nekaj sekund lokalne validacije prepreči to izgubo. Naslednja skripta opravi en sam prehod za preverjanje veljavnosti JSON, prisotnosti dveh obveznih polj in edinstvenosti ID-jev:
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"Vrstica {line_num}: Neveljaven JSON - {e}")
continue
# Preveri obvezna polja
if "custom_id" not in data:
errors.append(f"Vrstica {line_num}: manjka custom_id")
if "body" not in data:
errors.append(f"Vrstica {line_num}: manjka body")
# Preveri edinstvenost custom_id
cid = data.get("custom_id")
if cid in seen_ids:
errors.append(f"Vrstica {line_num}: podvojen custom_id '{cid}'")
seen_ids.add(cid)
if errors:
print(f"Najdenih {len(errors)} napak:")
for e in errors:
print(f" - {e}")
else:
print(f"Datoteka veljavna: {len(seen_ids)} zahtevkov pripravljenih.")
To naj bo sistematičen korak v tvojem pripravljalnem procesu, ki se izvede tik pred nalaganjem.
Omejitve in omejevalni dejavniki
Serijsko združevanje datotek je omejeno na milijon vrstic na datoteko, kar pomeni, da moraš večje korpuse razdeliti na več predložitev. Kodiranje mora biti UTF-8, format pa strogo zahteva en objekt JSON na vrstico: objekt JSON, razpet čez več vrstic, kot ga proizvede neustrezno postavljen json.dumps(..., indent=2), poruši strežniško razčlenjevanje. Nazadnje, zapomni si dve že omenjeni pravili, saj njuna kršitev povzroči neuspeh opravila: custom_id mora biti znotraj datoteke edinstven, body pa se mora ujemati s shemo ciljne končne točke.
Ključne ugotovitve
- JSONL strukturira tvoje serijske zahtevke z enim objektom JSON na vrstico
- Vsak zahtevek zahteva edinstven
custom_idinbody, ki ustreza ciljni končni točki - Naloži prek API-ja Python (
client.files.upload) ali prek AI Studio - Pred predložitvijo vedno validiraj svojo datoteko, da se izogneš napakam pri obdelavi
- Uporabi
ensure_ascii=Falseza francoske in druge znake z naglasi