Il-Format JSONL, custom_id, u t-Tlugħ tal-Fajls
F'din il-paġna
Aġġornat fit-3 ta’ Novembru, 2026: Bis-SDK
mistralai3.7.0,files.uploadjistennafile={"file_name": …, "content": …}(li tgħaddi tuple jqajjemValidationErrorqabel ma tintbagħat kwalunkwe data), u d-daqs tal-fajl huwa disponibbli f’size_bytes.
Il-Format JSONL: L-Għamara tal-Batch Inference
JSONL (JSON Lines) huwa l-format standard li Mistral juża biex jistruttura t-talbiet bil-batch. Kull linja fil-fajl hija oġġett JSON awtonomu li jirrappreżenta talba waħda. Dan id-disinn huwa intenzjonali: tista’ tiġġenera fajl ta’ miljun linja b’mod kontinwu mingħajr ma ttellgħu kollu fil-memorja, taqrah lura linja b’linja, u tispezzjona entrati speċifiċi manwalment meta talba tfalli. Kuntrarjament għal array JSON wieħed enormi, li jfurzalek ittella’ l-fajl kollu biex tivverifika entrata waħda biss, JSONL jħallik taħdem fil-livell tal-linja.
L-Istruttura tat-Talba JSONL
Kull linja fil-fajl JSONL tiegħek trid fiha żewġ oqsma meħtieġa:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Summarize this document in 3 points."}
]
}
}
Il-custom_id huwa identifikatur uniku li inti tiddefinixxi għal kull talba. Huwa dan li jagħmel ir-riżultati użabbli. Mistral ma jiggarantixxix l-ordni tal-ipproċessar: il-fajl tal-output jista’ jibda bit-talba 8,472. Mingħajr custom_id, tispiċċa b’munzell ta’ tweġibiet mingħajr ebda mod kif tkun taf liema dokument jikkorrispondi għal kull waħda. Agħmilha drawwa li tidderieġi dan l-ID mis-sistema ta’ referenza tiegħek stess—doc-001, email-2024-03-15-042, product-sku-ABC123—minflok ma tuża kontatur anonimu. Meta tweġiba tikkawża problemi, tista’ ttraċċaha lura għas-sors mingħajr ma tmexxi query SQL. Hawnhekk japplikaw żewġ regoli prattiċi: l-IDs iridu jkunu uniċi fil-fajl, inkella l-ipproċessar jirritorna żball, u għandhom ikunu raġonevolment qosra, peress li identifikatur ta’ 200 karattru jagħmel il-logs illegibbli.
Il-qasam body ma jeħtieġ l-ebda tagħlim ġdid: fih l-istruttura eżatta li tuża għal sejħa API sinkrona lejn l-endpoint fil-mira. Jekk qed timmira lejn /v1/chat/completions, il-body huwa identiku għal dak li tgħaddi f’sejħa client.chat.complete(). Prompt ivvalidat b’mod interattiv jittrasla direttament f’job bil-batch.
Il-Ġenerazzjoni ta’ Fajl JSONL f’Python
Hekk kif tiġġenera programmatakament fajl JSONL minn lista ta’ dokumenti:
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")
Innota l-parametru ensure_ascii=False. Mingħajru, json.dumps jiskappja karattri aċċentwati bħala sekwenzi \uXXXX. Il-fajl jibqa’ validu, iżda jsir impossibbli għall-bniedem biex jaqrah, u jbiddel kwalunkwe debug fuq corpus Franċiż f’eżerċizzju ta’ deċifrar. Agħmel dan id-default tiegħek mill-ewwel linja ta’ kodiċi.
It-Tlugħ tal-Fajl fuq Mistral
Fil-produzzjoni, ittella’ permezz tal-API ta’ Python:
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}")
Il-parametru purpose="batch" jgħid lil Mistral li dan il-fajl huwa maħsub għall-ipproċessar bil-batch, mhux għal karatteristiċi oħra bħal fine-tuning jew RAG. Din id-dikjarazzjoni ta’ intenzjoni tiddeċiedi x’jiġri wara: fajl imtella’ bl-iskop żbaljat jiġi miċħud mill-job.
Għal test mgħaġġel jew għal timijiet mhux tekniċi, AI Studio joffri l-istess servizz permezz tal-GUI:
- Mur fuq
console.mistral.ai/build/files - Ikklikkja “Upload”
- Agħżel il-fajl JSONL tiegħek
- Agħżel l-iskop “Batch Processing”
L-interfaċċa tirritorna file_id, eżattament bħall-API, u dan huwa l-identifikatur li tuża biex toħloq il-job bil-batch.
Il-Validazzjoni tal-Fajl
Batch ta’ miljun linja li jfalli fil-linja 300 minħabba custom_id duplikat jiswikek ċiklu sħiħ ta’ stennija. Ftit sekondi ta’ validazzjoni lokali jipprevjenu din it-telfa. L-iskritt li ġej iwettaq pass wieħed biex jiċċekkja l-validità tal-JSON, il-preżenza taż-żewġ oqsma meħtieġa, u l-unikità tal-ID:
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.")
Agħmel dan pass sistematiku fil-pipeline ta’ tħejjija tiegħek, eżegwit eżatt qabel it-tlugħ.
Limiti u Vincoli
Il-batching tal-fajls huwa limitat għal miljun linja kull fajl, li jfisser li trid taqsam korpora akbar f’diversi sottomissjonijiet. Il-kodifika trid tkun UTF-8, u l-format jeħtieġ strettament oġġett JSON wieħed kull linja: oġġett JSON mifrux fuq bosta linji, kif prodott minn json.dumps(..., indent=2) misplaced, ikisser il-parsing fuq is-server. Fl-aħħar nett, ftakar iż-żewġ regoli diġà msemmija, peress li l-ksur tagħhom jikkawża l-falliment tal-job: il-custom_id irid ikun uniku fil-fajl, u l-body irid jaqbel mal-iskema tal-endpoint fil-mira.
Punti Ewlenin
- JSONL jistruttura t-talbiet bil-batch tiegħek b’oġġett JSON wieħed kull linja
- Kull talba teħtieġ
custom_iduniku ubodyli jaqbel mal-endpoint fil-mira - Ittella’ permezz tal-API ta’ Python (
client.files.upload) jew permezz ta’ AI Studio - Dejjem ivvalida l-fajl tiegħek qabel is-sottomissjoni biex tevita żbalji fl-ipproċessar
- Uża
ensure_ascii=Falsegħall-Franċiż u karattri aċċentwati