JSONL-vorming, custom_id ja faili üleslaadimine
Sellel lehel
Uuendatud 3. novembril 2026: Alates SDK
mistralaiversioonist 3.7.0 eeldabfiles.uploadparameetritfile={"file_name": …, "content": …}(korteeži edastamine põhjustabValidationErrorvea enne andmete saatmist) ja faili suurus on kättesaadav väljalsize_bytes.
JSONL-vorming: hulgipäringute selgroog
JSONL (JSON Lines) on standardvorming, mida Mistral kasutab hulgipäringute struktureerimiseks. Iga rida failis on iseseisev JSON-objekt, mis tähistab üht päringut. See disain on tahtlik: saad genereerida miljoni reaga faili voogedastusena, laadimata kogu sisu mällu, lugeda seda tagasi rida-realt ja kontrollida konkreetseid kirjeid käsitsi, kui päring ebaõnnestub. Erinevalt ühest hiiglaslikust JSON-massiivist, mis sunnib sind kogu faili laadima vaid ühe kirje kontrollimiseks, võimaldab JSONL töötada rea tasandil.
JSONL-päringu struktuur
Iga rida sinu JSONL-failis peab sisaldama kahte kohustuslikku välja:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Summarize this document in 3 points."}
]
}
}
custom_id on unikaalne identifikaator, mille sina määratled iga päringu jaoks. Just see muudab tulemused kasutatavaks. Mistral ei garanteeri töötlemise järjekorda: väljundfail võib alata päringuga number 8472. Ilma custom_id-ta lõpetad hunniku vastustega, teadmata, millisele dokumendiga igaüks neist seotud on. Võta harjumuseks tuletada see ID omaenda viitesüsteemist – näiteks doc-001, email-2024-03-15-042, product-sku-ABC123 – selle asemel, et kasutada anonüümset loendurit. Kui vastus põhjustab probleeme, saad selle allikani jälitada ilma SQL-päringut käivitamata. Siin kehtivad kaks praktilist reeglit: ID-d peavad failis olema unikaalsed, vastasel juhul tagastab töötlemine vea, ja need peaksid olema mõistlikult lühikesed, sest 200-märgiline identifikaator muudab logid loetamatuks.
Väli body ei nõua uusi teadmisi: see sisaldab täpselt sama struktuuri, mida kasutaksid sünkroonse API-kutsu jaoks sihtotstarbelises lõpp-punktis. Kui sihid lõpp-punkti /v1/chat/completions, on body identne sellega, mida edastaksid client.chat.complete() kutsus. Interaktiivselt valideeritud vihje tõlgitakse otse hulgitööks.
JSONL-faili genereerimine Pythonis
Siin on näide, kuidas programmeeritult genereerida JSONL-fail dokumentide loendist:
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")
Pane tähele parameetrit ensure_ascii=False. Ilma selleta kodeerib json.dumps täpitähed \uXXXX jadadeks. Fail jääb kehtivaks, kuid muutub inimestele loetamatuks, muutes prantsuskeelse korpuse silumise dešifreerimisharjutuseks. Tee sellest oma vaikimisi valik juba koodi esimesest reast alates.
Faili üleslaadimine Mistrali
Tootmises laadi fail üles Pythoni API kaudu:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Laadi JSONL-fail üles
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}")
Parameeter purpose="batch" annab Mistralile teada, et see fail on mõeldud hulgitöötluseks, mitte muudeks funktsioonideks nagu peenhäälestus või RAG. See kavatsuse deklaratsioon dikteerib järgnevat: vale eesmärgiga üles laetud fail lükatakse töö poolt tagasi.
Kiireks testiks või mitte-tehniliste meeskondade jaoks pakub AI Studio sama teenust graafilise kasutajaliidese (GUI) kaudu:
- Mine aadressile
console.mistral.ai/build/files - Klõpsa nuppu “Upload”
- Vali oma JSONL-fail
- Vali eesmärgiks “Batch Processing”
Liides tagastab file_id, täpselt nagu API, ja see on identifikaator, mida kasutad hulgitöö loomiseks.
Faili valideerimine
Miljoni reaga hulk, mis ebaõnnestub real 300 topelt custom_id tõttu, maksab sulle terve ooteaja. Mõni sekund kohalikku valideerimist hoiab selle kaotuse ära. Järgnev skript teeb ühe läbimise, et kontrollida JSON-i kehtivust, kahe kohustusliku välja olemasolu ja ID-de unikaalsust:
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
# Kontrolli kohustuslikke välju
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")
# Kontrolli custom_id unikaalsust
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.")
Tee sellest süstemaatiline samm oma ettevalmistustorustikus, mis käivitatakse vahetult enne üleslaadimist.
Piirangud ja tingimused
Failide hulgistamine on piiratud ühe miljoni reaga faili kohta, mis tähendab, et suuremad korpused tuleb jagada mitmeks esituseks. Kodeering peab olema UTF-8 ja vorming nõuab rangelt ühte JSON-objekti rea kohta: mitmele reale venitatud JSON-objekt, nagu tekib valesti paigutatud json.dumps(..., indent=2) tulemusena, rikub serveripoolse parsimise. Lõpuks pea meeles kahte juba mainitud reeglit, kuna nende rikkumine põhjustab töö ebaõnnestumise: custom_id peab olema failis unikaalne ja body peab vastama sihtlõpp-punkti skeemile.
Peamised punktid
- JSONL struktureerib sinu hulgipäringud ühe JSON-objektiga rea kohta
- Iga päring nõuab unikaalset
custom_idjabody, mis vastab sihtlõpp-punktile - Laadi üles Pythoni API (
client.files.upload) kaudu või AI Studio abil - Valideeri oma fail enne esitamist alati, et vältida töötlemisvigu
- Kasuta prantsuse keele ja täpitähtede jaoks parameetrit
ensure_ascii=False