Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Formato dati: conversazioni JSONL

Lezione 3 di 16 Aggiornata il 2 novembre 2026 Avanzato
In questa pagina
  1. Il formato JSONL
  2. Struttura della conversazione
  3. Conversazioni multi-turno
  4. Ponderazione con weight
  5. Script per la creazione di file JSONL
  6. Punti chiave

Aggiornamento 2 novembre 2026 — Disponibilità del fine-tuning. Il servizio di fine-tuning self-service di OpenAI sta venendo dismesso: dal 7 maggio 2026, le organizzazioni che non lo hanno mai utilizzato non possono più creare job; dal 2 luglio, devi aver usato un modello sottoposto a fine-tuning negli ultimi 60 giorni; e a partire dal 6 gennaio 2027, nessun cliente potrà avviare nuovi job. I modelli già addestrati rimangono utilizzabili fino al pensionamento del loro modello base. Questo corso resta utile per comprendere e sfruttare un modello esistente; per i nuovi progetti, dai priorità al prompt engineering, al RAG e alle valutazioni.

Il formato JSONL

JSONL (JSON Lines) è il formato richiesto dall’API di fine-tuning di OpenAI. Ogni riga del file è un oggetto JSON indipendente che rappresenta un esempio di addestramento completo. Questa struttura ti permette di trasmettere in streaming un corpus di decine di migliaia di esempi senza dover mai caricare l’intero file in memoria.

{"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}
{"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}

Regola fondamentale: una riga = un oggetto JSON = un esempio. Non includere interruzioni di riga all’interno dell’oggetto JSON stesso. In altre parole, il JSON “formattato” con indentazione del tuo editor romperà il file: questa è la causa più comune di rifiuto durante il caricamento.

Struttura della conversazione

Ogni esempio è un oggetto con una chiave messages contenente un array di messaggi. Ogni messaggio ha un role e un content. Sono accettati solo tre ruoli:

  • system: istruzioni globali per l’assistente (opzionale, ma consigliato)
  • user: il messaggio dell’utente
  • assistant: la risposta che il modello deve imparare a produrre

Il formato minimo consiste in un singolo scambio utente/assistente. Questo è sufficiente quando il comportamento desiderato non dipende da un contesto specifico, come nel caso di un modello dedicato a un singolo compito.

{
  "messages": [
    {"role": "user", "content": "Ciao, come stai?"},
    {"role": "assistant", "content": "Ciao! Sono pronto ad aiutarti. Cosa posso fare per te?"}
  ]
}

Non appena il modello deve adottare un ruolo specifico, aggiungi un messaggio di sistema e mantienilo identico in tutti i tuoi esempi. Nota nell’esempio sotto che l’istruzione “offri sempre un appuntamento demo” viene effettivamente rispettata nella risposta dell’assistente: il messaggio di sistema descrive un vincolo e l’esempio mostra come appare quando applicato.

{
  "messages": [
    {
      "role": "system",
      "content": "Sei un assistente alle vendite per TechCorp. Rispondi in modo conciso e professionale. Offri sempre un appuntamento demo."
    },
    {
      "role": "user",
      "content": "Sto cercando una soluzione CRM per il mio team di 50 persone."
    },
    {
      "role": "assistant",
      "content": "Il nostro CRM TechCorp è progettato per team da 20 a 200 persone, con gestione contatti, pipeline di vendita e reportistica integrata. Per un team di 50, consiglio il piano Business a 29€/utente/mese. Vorresti programmare una demo personalizzata questa settimana?"
    }
  ]
}

Conversazioni multi-turno

Puoi includere conversazioni con più scambi. Il modello impara così a mantenere la coerenza tra i vari turni: qui, la seconda risposta si basa sul passo 2 annunciato nel primo, qualcosa che un esempio isolato non potrebbe insegnare.

{
  "messages": [
    {
      "role": "system",
      "content": "Sei un assistente tecnico per un'API di pagamento."
    },
    {
      "role": "user",
      "content": "Come integro la vostra API di pagamento?"
    },
    {
      "role": "assistant",
      "content": "L'integrazione avviene in 3 passaggi: 1) Installa l'SDK con pip install paycorp-sdk, 2) Configura la tua chiave API, 3) Crea il tuo primo pagamento. Da quale passaggio vuoi iniziare?"
    },
    {
      "role": "user",
      "content": "Come configuro la chiave API?"
    },
    {
      "role": "assistant",
      "content": "Ottieni la tua chiave dalla dashboard (Impostazioni > Chiavi API), quindi configurala nel tuo codice:\n\nfrom paycorp import PayCorp\nclient = PayCorp(api_key=\"your_key\")\n\nUsa la chiave di test (prefisso sk_test_) in sviluppo e la chiave live (sk_live_) in produzione. Non committare mai le tue chiavi nel codice sorgente."
    }
  ]
}

Ponderazione con weight

Puoi indicare al modello quali messaggi dell’assistente sono più importanti aggiungendo un campo weight:

{
  "messages": [
    {"role": "user", "content": "Riassumi questo documento."},
    {"role": "assistant", "content": "Ecco il riassunto...", "weight": 1}
  ]
}

Un weight di 0 significa che il modello non si addestrerà su quel specifico messaggio dell’assistente; il valore predefinito è 1. Il caso d’uso tipico riguarda le conversazioni multi-turno in cui conta solo il turno finale: mantieni gli scambi precedenti perché forniscono il contesto necessario, ma non vuoi che il modello impari a riprodurli; imposta semplicemente il loro peso a 0.

Script per la creazione di file JSONL

Nella pratica, non scriverai mai questo file a mano. La funzione seguente serializza una lista di esempi e ti protegge dai due errori più comuni: dimenticare l’interruzione di riga finale e gestire male l’escaping degli accenti.

import json

def create_jsonl_file(examples: list[dict], path: str):
    """Crea un file JSONL da una lista di esempi."""
    with open(path, "w", encoding="utf-8") as f:
        for example in examples:
            line = json.dumps(example, ensure_ascii=False)
            f.write(line + "\n")
    print(f"File creato: {path} ({len(examples)} esempi)")

# I tuoi esempi
examples = [
    {
        "messages": [
            {"role": "system", "content": "Assistente supporto clienti TechCorp."},
            {"role": "user", "content": "Il mio account è bloccato."},
            {"role": "assistant", "content": "Capisco la tua frustrazione. Per sbloccare il tuo account, ho bisogno del tuo indirizzo email di registrazione. Controllerò lo stato e ti guiderò nel processo di riattivazione."}
        ]
    },
    {
        "messages": [
            {"role": "system", "content": "Assistente supporto clienti TechCorp."},
            {"role": "user", "content": "Come cambio la mia password?"},
            {"role": "assistant", "content": "Per cambiare la password: vai su Impostazioni > Sicurezza > Cambia Password. Inserisci la tua password attuale, poi quella nuova (minimo 12 caratteri, con maiuscola, numero e carattere speciale). Conferma e clicca Salva."}
        ]
    }
]

create_jsonl_file(examples, "training_data.jsonl")

Gli errori che incontrerai sono sempre gli stessi e tutti possono essere rilevati prima del caricamento. Un’interruzione di riga mancante tra due oggetti fonde due esempi in un’unica riga illeggibile. Un JSON malformato (virgoletta mancante, virgola extra) fa fallire l’intera riga. Un content vuoto genera un errore di validazione lato OpenAI, così come un ruolo inventato: sono accettati solo system, user e assistant. Infine, scrivi sempre in UTF-8 con ensure_ascii=False, altrimenti i tuoi caratteri accentati si trasformeranno in sequenze di escape che il modello imparerà coscienziosamente a riprodurre.

Punti chiave

  • Una riga JSONL = un oggetto JSON = una conversazione completa
  • Ogni conversazione contiene almeno un messaggio user e uno assistant
  • Il messaggio system è opzionale ma consigliato per la coerenza
  • Usa weight: 0 per escludere certi turni dall’addestramento nelle conversazioni multi-turno
  • Convalida sempre il tuo file JSONL prima del caricamento