Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Il-Format JSONL, custom_id, u t-Tlugħ tal-Fajls

Lezzjoni 2 / 16 Aġġornat 3 ta’ Novembru 2026 Avvanzat
F'din il-paġna
  1. Il-Format JSONL: L-Għamara tal-Batch Inference
  2. L-Istruttura tat-Talba JSONL
  3. Il-Ġenerazzjoni ta’ Fajl JSONL f’Python
  4. It-Tlugħ tal-Fajl fuq Mistral
  5. Il-Validazzjoni tal-Fajl
  6. Limiti u Vincoli
  7. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru, 2026: Bis-SDK mistralai 3.7.0, files.upload jistenna file={"file_name": …, "content": …} (li tgħaddi tuple jqajjem ValidationError qabel 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:

  1. Mur fuq console.mistral.ai/build/files
  2. Ikklikkja “Upload”
  3. Agħżel il-fajl JSONL tiegħek
  4. 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_id uniku u body li 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=False għall-Franċiż u karattri aċċentwati