Formāts JSONL, custom_id un failu augšupielāde
Šajā lapā
Atjaunināts 2026. gada 3. novembrī: Ar SDK
mistralai3.7.0 versijufiles.uploadsagaidafile={"file_name": …, "content": …}(korteža nodošana izraisaValidationErrorpirms jebkādu datu nosūtīšanas), un faila izmērs ir pieejams laukāsize_bytes.
Formāts JSONL: masveida secinājumu mugurkauls
JSONL (JSON Lines) ir standarta formāts, ko Mistral izmanto masveida pieprasījumu strukturēšanai. Katra rinda failā ir neatkarīgs JSON objekts, kas apzīmē vienu pieprasījumu. Šis dizains ir apzināts: tu vari ģenerēt miljona rindu failu plūsmas režīmā, neielādējot to visu atmiņā, nolasīt to atpakaļ pa vienai rindai un manuāli pārbaudīt konkrētus ierakstus, ja pieprasījums neizdodas. Atšķirībā no viena milzīga JSON masīva, kas liek ielādēt visu failu, lai pārbaudītu tikai vienu ierakstu, JSONL ļauj strādāt rindu līmenī.
JSONL pieprasījuma struktūra
Katrai rindai tavā JSONL failā jābūt diviem obligātiem laukiem:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Summarize this document in 3 points."}
]
}
}
custom_id ir unikāls identifikators, ko tu definē katram pieprasījumam. Tieši tas padara rezultātus lietojamus. Mistral negarantē apstrādes secību: izvades fails var sākties ar 8472. pieprasījumu. Bez custom_id tev būs kaudze atbilžu, bet nekāda veida, kā zināt, kuram dokumentam katra no tām atbilst. Pieradini sevi šo ID atvasināt no savas atsauces sistēmas — doc-001, email-2024-03-15-042, product-sku-ABC123 — nevis izmantot anonīmu skaitītāju. Ja atbilde rada problēmas, tu vari izsekot tai līdz avotam, neveicot SQL vaicājumu. Šeit attiecas divi praktiski noteikumi: ID failā ir jābūt unikāliem, pretējā gadījumā apstrāde atgriezīs kļūdu, un tiem jābūt saprātīgi īsiem, jo 200 zīmju identifikators padara žurnālus nelasāmus.
Laukam body nav nepieciešamas jaunas zināšanas: tas satur tieši tādu pašu struktūru, ko izmantotu sinhronam API izsaukumam uz mērķa galapunktu. Ja mērķis ir /v1/chat/completions, ķermenis ir identisks tam, ko nodotu client.chat.complete() izsaukumā. Interaktīvi validēts uzvednes teksts tieši pārvēršas par masveida uzdevumu.
JSONL faila ģenerēšana Python valodā
Lūk, kā programmiski ģenerēt JSONL failu no dokumentu saraksta:
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")
Ņem vērā parametru ensure_ascii=False. Bez tā json.dumps kodē akcentētās zīmes kā \uXXXX sekvences. Fails paliek derīgs, bet kļūst cilvēkiem nelasāms, pārvēršot jebkuru atkļūdošanu franču valodas korpusā par dešifrēšanas vingrinājumu. Padari to par savu noklusējumu jau no pirmās koda rindas.
Faila augšupielāde Mistral vidē
Produkcijas vidē augšupielādi veic, izmantojot Python API:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Augšupielādē JSONL failu
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}")
Parametrs purpose="batch" norāda Mistral, ka šis fails ir paredzēts masveida apstrādei, nevis citām funkcijām, piemēram, smalkai noregulēšanai vai RAG. Šis nodoma paziņojums diktē turpmākos notikumus: fails, kas augšupielādēts ar nepareizu nolūku, tiks noraidīts uzdevuma izpildes laikā.
Ātrai testēšanai vai netehniskām komandām AI Studio piedāvā to pašu pakalpojumu, izmantojot grafisko saskarni:
- Dodies uz
console.mistral.ai/build/files - Noklikšķini uz „Upload”
- Atlasī savu JSONL failu
- Izvēlies nolūku „Batch Processing”
Saskarne atgriež file_id, tieši tāpat kā API, un šis ir identifikators, ko izmanto masveida uzdevuma izveidei.
Faila validācija
Miljona rindu masveida uzdevums, kas neizdodas 300. rindā dublikāta custom_id dēļ, tev izmaksā pilnu gaidīšanas ciklu. Dažas sekundes lokālai validācijai novērš šos zaudējumus. Turpmākais skripts veic vienu caurlaidi, lai pārbaudītu JSON derīgumu, divu obligāto lauku esamību un ID unikalitāti:
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
# Pārbauda obligātos laukus
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")
# Pārbauda custom_id unikalitāti
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.")
Padari to par sistemātisku soli savā sagatavošanas procesā, kas tiek izpildīts tieši pirms augšupielādes.
Limiti un ierobežojumi
Failu grupēšana ir ierobežota līdz vienam miljonam rindu vienā failā, kas nozīmē, ka lielāki korpusi ir jāsadala vairākos iesniegumos. Kodējumam ir jābūt UTF-8, un formāts stingri pieprasa vienu JSON objektu vienā rindā: JSON objekts, kas izvietots vairākās rindās, kā to rada nepareizi novietots json.dumps(..., indent=2), sabojā servera puses parsēšanu. Visbeidzot, atceries divus jau minētos noteikumus, jo to pārkāpšana izraisa uzdevuma neveiksmi: custom_id failā ir jābūt unikālam, un body ir jāatbilst mērķa galapunkta shēmai.
Galvenās atziņas
- JSONL strukturē tavus masveida pieprasījumus ar vienu JSON objektu vienā rindā
- Katram pieprasījumam ir nepieciešams unikāls
custom_idunbody, kas atbilst mērķa galapunktam - Augšupielādi veic, izmantojot Python API (
client.files.upload) vai caur AI Studio - Vienmēr validē savu failu pirms iesniegšanas, lai izvairītos no apstrādes kļūdām
- Izmanto
ensure_ascii=Falsefranču valodai un akcentētām zīmēm