Salt la conținutul principal
Română— Alege o limbă
Meniu

Formatul JSONL, custom_id și încărcarea fișierelor

Lecția 2 din 16 Actualizată 3 noiembrie 2026 Avansat
Pe această pagină
  1. Formatul JSONL: Coloana vertebrală a inferenței în lot
  2. Structura unei cereri JSONL
  3. Generarea unui fișier JSONL în Python
  4. Încărcarea fișierului la Mistral
  5. Validarea fișierului
  6. Limite și constrângeri
  7. Puncte cheie

Actualizat la 3 noiembrie 2026: Odată cu SDK-ul mistralai 3.7.0, files.upload așteaptă file={"file_name": …, "content": …} (transmiterea unui tuplu declanșează o eroare ValidationError înainte de trimiterea oricăror date), iar dimensiunea fișierului este disponibilă în size_bytes.

Formatul JSONL: Coloana vertebrală a inferenței în lot

JSONL (JSON Lines) este formatul standard utilizat de Mistral pentru structurarea cererilor în lot. Fiecare linie din fișier este un obiect JSON independent care reprezintă o singură cerere. Această concepție este intenționată: puteți genera prin streaming un fișier de un milion de linii fără a-l încărca integral în memorie, îl puteți reciti linie cu linie și inspecta manual intrările specifice atunci când o cerere eșuează. Spre deosebire de un singur array JSON masiv, care vă obligă să încărcați întregul fișier doar pentru a verifica o singură intrare, JSONL vă permite să lucrați la nivel de linie.

Structura unei cereri JSONL

Fiecare linie din fișierul dumneavoastră JSONL trebuie să conțină două câmpuri obligatorii:

{
  "custom_id": "req-001",
  "body": {
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Summarize this document in 3 points."}
    ]
  }
}

custom_id este un identificator unic pe care dumneavoastră îl definiți pentru fiecare cerere. Acesta este elementul care face rezultatele utilizabile. Mistral nu garantează ordinea de procesare: fișierul de ieșire ar putea începe cu cererea 8.472. Fără un custom_id, vă veți trezi cu o grămadă de răspunsuri și fără nicio modalitate de a ști cărui document îi corespunde fiecare. Obișnuiți-vă să derivați acest ID din propriul sistem de referință—doc-001, email-2024-03-15-042, product-sku-ABC123—în loc să folosiți un contor anonim. Când un răspuns cauzează probleme, îl puteți urmări până la sursă fără a rula o interogare SQL. Două reguli practice se aplică aici: ID-urile trebuie să fie unice în cadrul fișierului, altfel procesarea va returna o eroare, iar acestea ar trebui să fie rezonabil de scurte, deoarece un identificator de 200 de caractere face jurnalele ilizibile.

Câmpul body nu necesită nicio învățare nouă: conține exact structura pe care ați folosi-o pentru un apel API sincron către endpoint-ul țintă. Dacă vizați /v1/chat/completions, corpul este identic cu ceea ce ați transmite într-un apel client.chat.complete(). Un prompt validat interactiv se traduce direct într-un job în lot.

Generarea unui fișier JSONL în Python

Iată cum să generați programatic un fișier JSONL dintr-o listă de documente:

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")

Rețineți parametrul ensure_ascii=False. Fără acesta, json.dumps va scăpa caracterele accentuate sub formă de secvențe \uXXXX. Fișierul rămâne valid, dar devine imposibil de citit pentru oameni, transformând orice depanare pe un corpus în franceză într-un exercițiu de decriptare. Faceți din aceasta regula dumneavoastră implicită încă de la prima linie de cod.

Încărcarea fișierului la Mistral

În producție, încărcați fișierul prin API-ul 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}")

Parametrul purpose="batch" indică Mistral că acest fișier este destinat procesării în lot, nu altor funcționalități precum fine-tuning sau RAG. Această declarație de intenție dictează ce se întâmplă mai departe: un fișier încărcat cu un scop greșit va fi respins de job.

Pentru un test rapid sau pentru echipele non-tehnice, AI Studio oferă același serviciu prin interfața grafică:

  1. Accesați console.mistral.ai/build/files
  2. Faceți clic pe „Upload“
  3. Selectați fișierul dumneavoastră JSONL
  4. Alegeți scopul „Batch Processing“

Interfața returnează un file_id, exact ca API-ul, iar acesta este identificatorul pe care îl utilizați pentru a crea jobul în lot.

Validarea fișierului

Un lot de un milion de linii care eșuează la linia 300 din cauza unui custom_id duplicat vă costă un ciclu complet de așteptare. Câteva secunde de validare locală previn această pierdere. Scriptul următor efectuează o singură trecere pentru a verifica validitatea JSON, prezența celor două câmpuri obligatorii și unicitatea ID-urilor:

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.")

Transformați acest pas într-o etapă sistematică a pipeline-ului dumneavoastră de pregătire, executată chiar înainte de încărcare.

Limite și constrângeri

Loturile de fișiere sunt limitate la un milion de linii per fișier, ceea ce înseamnă că trebuie să divizați corpusurile mai mari în mai multe submiteri. Codificarea trebuie să fie UTF-8, iar formatul impune strict un obiect JSON per linie: un obiect JSON întins pe mai multe linii, așa cum produce un json.dumps(..., indent=2) plasat greșit, va strica parsarea latoarea serverului. În final, amintiți-vă cele două reguli menționate deja, deoarece încălcarea lor duce la eșecul jobului: custom_id trebuie să fie unic în cadrul fișierului, iar body trebuie să corespundă schemei endpoint-ului țintă.

Puncte cheie

  • JSONL structurează cererile dumneavoastră în lot cu un obiect JSON per linie
  • Fiecare cerere necesită un custom_id unic și un body care corespunde endpoint-ului țintă
  • Încărcați fișierul prin API-ul Python (client.files.upload) sau prin AI Studio
  • Validați întotdeauna fișierul înainte de submitere pentru a evita erorile de procesare
  • Utilizați ensure_ascii=False pentru caracterele franceze și accentuate