Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Formato JSONL, custom_id e caricamento file

Lezione 2 di 16 Aggiornata il 3 novembre 2026 Avanzato
In questa pagina
  1. Il formato JSONL: la spina dorsale dell’inferenza batch
  2. Struttura della richiesta JSONL
  3. Generazione di un file JSONL in Python
  4. Caricamento del file su Mistral
  5. Validazione del file
  6. Limiti e vincoli
  7. Punti chiave

Aggiornato il 3 novembre 2026: Con l’SDK mistralai 3.7.0, files.upload si aspetta file={"file_name": …, "content": …} (passare una tupla solleva un ValidationError prima dell’invio di qualsiasi dato) e la dimensione del file è disponibile in size_bytes.

Il formato JSONL: la spina dorsale dell’inferenza batch

Il JSONL (JSON Lines) è il formato standard che Mistral utilizza per strutturare le richieste batch. Ogni riga del file è un oggetto JSON autonomo che rappresenta una singola richiesta. Questa scelta progettuale è intenzionale: puoi generare in streaming un file da un milione di righe senza caricarlo tutto in memoria, leggerlo riga per riga e ispezionare manualmente voci specifiche quando una richiesta fallisce. A differenza di un unico enorme array JSON, che ti costringe a caricare l’intero file solo per verificare una voce, il JSONL ti permette di lavorare a livello di riga.

Struttura della richiesta JSONL

Ogni riga del tuo file JSONL deve contenere due campi obbligatori:

{
  "custom_id": "req-001",
  "body": {
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Riassumi questo documento in 3 punti."}
    ]
  }
}

Il custom_id è un identificativo univoco che tu definisci per ogni richiesta. È ciò che rende i risultati utilizzabili. Mistral non garantisce l’ordine di elaborazione: il file di output potrebbe iniziare con la richiesta 8.472. Senza un custom_id, ti ritroveresti con una pila di risposte e nessun modo per sapere a quale documento corrisponda ciascuna. Prendi l’abitudine di derivare questo ID dal tuo sistema di riferimento interno—doc-001, email-2024-03-15-042, product-sku-ABC123—invece di usare un contatore anonimo. Quando una risposta causa problemi, puoi risalire alla fonte senza dover eseguire una query SQL. Qui valgono due regole pratiche: gli ID devono essere univoci all’interno del file, altrimenti l’elaborazione restituirà un errore, e devono essere ragionevolmente brevi, poiché un identificativo di 200 caratteri rende i log illeggibili.

Il campo body non richiede nuovi apprendimenti: contiene esattamente la struttura che useresti per una chiamata API sincrona all’endpoint di destinazione. Se il tuo target è /v1/chat/completions, il body è identico a quello che passeresti in una chiamata client.chat.complete(). Un prompt validato interattivamente si traduce direttamente in un job batch.

Generazione di un file JSONL in Python

Ecco come generare programmaticamente un file JSONL a partire da una lista di documenti:

import json

documents = [
    {"id": "doc-001", "text": "L'intelligenza artificiale sta trasformando..."},
    {"id": "doc-002", "text": "Le reti neurali profonde..."},
    {"id": "doc-003", "text": "L'elaborazione del linguaggio naturale..."},
]

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": "Sei un assistente che riassume testi."
                    },
                    {
                        "role": "user",
                        "content": f"Riassumi questo testo: {doc['text']}"
                    }
                ]
            }
        }
        f.write(json.dumps(request, ensure_ascii=False) + "\n")

Nota il parametro ensure_ascii=False. Senza di esso, json.dumps esegue l’escape dei caratteri accentati come sequenze \uXXXX. Il file rimane valido, ma diventa impossibile da leggere per un essere umano, trasformando qualsiasi debug su un corpus francese in un esercizio di decrittazione. Rendilo il tuo default dalla prima riga di codice.

Caricamento del file su Mistral

In produzione, effettua il caricamento tramite le API Python:

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# Carica il file JSONL
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"File caricato: {batch_file.id}")
print(f"Dimensione: {batch_file.size_bytes} byte")
print(f"Scopo: {batch_file.purpose}")

Il parametro purpose="batch" indica a Mistral che questo file è destinato all’elaborazione batch e non ad altre funzionalità come il fine-tuning o il RAG. Questa dichiarazione di intenti determina cosa succede dopo: un file caricato con lo scopo sbagliato verrà rifiutato dal job.

Per un test rapido o per team non tecnici, AI Studio offre lo stesso servizio tramite interfaccia grafica:

  1. Vai su console.mistral.ai/build/files
  2. Clicca su “Upload”
  3. Seleziona il tuo file JSONL
  4. Scegli lo scopo “Batch Processing”

L’interfaccia restituisce un file_id, esattamente come le API, e questo è l’identificativo che userai per creare il job batch.

Validazione del file

Un batch da un milione di righe che fallisce alla riga 300 a causa di un custom_id duplicato ti costa un intero ciclo di attesa. Pochi secondi di validazione locale prevengono questa perdita. Lo script seguente esegue un singolo passaggio per verificare la validità del JSON, la presenza dei due campi obbligatori e l’unicità degli 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"Riga {line_num}: JSON non valido - {e}")
            continue

        # Controlla i campi obbligatori
        if "custom_id" not in data:
            errors.append(f"Riga {line_num}: custom_id mancante")
        if "body" not in data:
            errors.append(f"Riga {line_num}: body mancante")

        # Controlla l'unicità del custom_id
        cid = data.get("custom_id")
        if cid in seen_ids:
            errors.append(f"Riga {line_num}: custom_id duplicato '{cid}'")
        seen_ids.add(cid)

if errors:
    print(f"{len(errors)} errore(i) trovati:")
    for e in errors:
        print(f"  - {e}")
else:
    print(f"File valido: {len(seen_ids)} richieste pronte.")

Rendi questo passaggio sistematico nella tua pipeline di preparazione, eseguendolo immediatamente prima del caricamento.

Limiti e vincoli

Il batching di file ha un limite di un milione di righe per file, il che significa che devi suddividere i corpus più grandi in più invii. La codifica deve essere UTF-8 e il formato richiede rigorosamente un oggetto JSON per riga: un oggetto JSON distribuito su più righe, come prodotto da un errato json.dumps(..., indent=2), rompe il parsing lato server. Infine, ricorda le due regole già menzionate, poiché violarle causa il fallimento del job: il custom_id deve essere univoco all’interno del file e il body deve corrispondere allo schema dell’endpoint di destinazione.

Punti chiave

  • Il JSONL struttura le tue richieste batch con un oggetto JSON per riga
  • Ogni richiesta richiede un custom_id univoco e un body corrispondente all’endpoint di destinazione
  • Carica i file tramite le API Python (client.files.upload) o attraverso AI Studio
  • Valida sempre il tuo file prima dell’invio per evitare errori di elaborazione
  • Usa ensure_ascii=False per gestire correttamente i caratteri accentati