Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Dataset: costruire set di valutazione e iterare

Lezione 15 di 16 Aggiornata il 2 novembre 2026 Avanzato
In questa pagina
  1. L’anello finale del ciclo di iterazione
  2. Struttura del record
  3. Fonti dei dati
  4. Revisione ed esportazione
  5. Valutare su un dataset di Studio
  6. Migliori pratiche di gestione
  7. Punti chiave

Lezione riscritta il 2 novembre 2026 sulla base della pagina Datasets di Mistral e dell’SDK mistralai 3.7.0: un record contiene un payload a forma libera e delle properties; i dataset vengono popolati tramite inserimento manuale, importazione di file o span dall’Explorer e vengono passati così come sono alle valutazioni offline. Il metodo import_from_explorer della versione precedente non esiste più. Fonti: Datasets · Explore traces.

L’anello finale del ciclo di iterazione

Un dataset è la raccolta di casi di test che guida una valutazione offline. Dona memoria al tuo processo di qualità: ogni incidente osservato in produzione può diventare un caso di test e ogni nuova versione dell’applicazione viene misurata rispetto ad esso. Senza un dataset stabile, confronti delle impressioni; con un dataset, confronti dei numeri.

Struttura del record

In Studio, ogni record contiene un payload—un oggetto JSON in cui definisci le chiavi—e delle properties, che sono metadati non passati al task valutato. Durante una valutazione, il payload diventa il record di input esattamente così com’è (ctx.input_record).

{"payload": {"ticket": "My October invoice lists the same subscription twice.", "category": "billing"}, "properties": {"source": "incident-2026-10-14"}}

Questa riga rappresenta anche il formato di importazione JSONL per i dataset di Studio: un oggetto per riga, contenente payload e properties.

Fonti dei dati

Puoi popolare un dataset in diversi modi:

  • Inserimento manuale, in Studio o tramite API, record per record
  • Importazione di file JSONL utilizzando il formato sopra indicato
  • Dall’Explorer: un singolo span, o fino a 500 span selezionati, diventano record (Lezione 12)
  • Dal Playground di Studio o da un altro dataset
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")
datasets = client.beta.observability.datasets

# Creare il dataset
dataset = datasets.create(
    name="Support tickets — reference set",
    description="Manually validated ticket classification cases",
)
print(f"Dataset: {dataset.id} ({dataset.slug})")

# Aggiungere record
cases = [
    {"ticket": "I haven't been able to log in since this morning.", "category": "access"},
    {"ticket": "The PDF export crashes whenever the report exceeds 50 pages.", "category": "bug"},
]
for payload in cases:
    datasets.create_record(
        dataset_id=dataset.id,
        payload=payload,
        properties={"origin": "manual entry"},
    )

Per grandi volumi, import_from_file importa un file JSONL già caricato (tramite il suo file_id) e import_from_spans acquisisce gli span delle tracce: queste importazioni vengono eseguite come task in background e puoi monitorarne l’avanzamento con fetch_task.

Revisione ed esportazione

list_records itera attraverso i record pagina per pagina (page_size, page), mentre export_to_jsonl genera un’esportazione la cui risposta fornisce l’URL di download (file_url):

page = datasets.list_records(dataset_id=dataset.id, page_size=50, page=1)
export = datasets.export_to_jsonl(dataset_id=dataset.id)
print(export.file_url)

Valutare su un dataset di Studio

Una valutazione offline legge un dataset di Studio tramite il suo slug o ID:

from mistralai.evaluations import Dataset, Evaluation, Evaluator, Project

run = await client.evaluation.run(
    project=Project(name="Ticket sorting"),
    evaluation=Evaluation(name="Reference set"),
    dataset=Dataset(slug="support-tickets-reference-set"),
    task=tache,
    evaluators=[Evaluator(name="exactitude", scorer=exactitude)],
)

Qui, client è il client SDK di valutazione, mentre tache ed exactitude sono definiti nella Lezione 14. Passa esattamente uno tra slug o id; selezionare un dataset tramite il suo slug non ne crea mai uno nuovo. Tieni a mente due regole: un’esecuzione legge i record presenti all’avvio, fino a 10.000—un dataset non è un’istantanea, quindi modificarlo influisce solo sulle esecuzioni successive—e se i record vengono aggiunti o rimossi durante la lettura, l’esecuzione fallisce prima di iniziare invece di eseguirsi su un set incoerente.

Migliori pratiche di gestione

Mantieni un set di riferimento stabile. Un dataset che cambia a ogni esecuzione rende impossibile il confronto. Crea un set di riferimento che modifichi solo deliberatamente e mantieni dataset di lavoro separati accanto ad esso.

Alimentalo dalla produzione. I casi più utili sono quelli che hanno effettivamente causato problemi: uno span individuato nell’Explorer, dove correggi l’output atteso, vale più di dieci casi inventati.

Documenta la provenienza. Le properties (origine, data, incidente correlato) non sono viste dal task, ma ti diranno tra sei mesi perché esiste un determinato caso.

Bilancia i tuoi dati. Un dataset contenente solo casi semplici lusinga il tuo sistema; uno contenente solo trappole lo scoraggia. Punta alla distribuzione effettiva del tuo traffico, più una manciata di casi limite riconosciuti.

Punti chiave

  • Un record del dataset = un payload (input del task) e delle properties (metadati)
  • Inserimento manuale, importazione JSONL, span dall’Explorer, Playground: molteplici fonti per un unico dataset
  • L’SDK espone create, create_record, import_from_file, import_from_spans, list_records ed export_to_jsonl
  • Le valutazioni leggono un dataset tramite Dataset(slug=...) o Dataset(id=...), fino a 10.000 record
  • Un dataset non è un’istantanea: mantieni un set di riferimento stabile per confrontare le versioni