Dataset: costruire set di valutazione e iterare
In questa pagina
Lezione riscritta il 2 novembre 2026 sulla base della pagina Datasets di Mistral e dell’SDK
mistralai3.7.0: un record contiene unpayloada forma libera e delleproperties; i dataset vengono popolati tramite inserimento manuale, importazione di file o span dall’Explorer e vengono passati così come sono alle valutazioni offline. Il metodoimport_from_explorerdella 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 delleproperties(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_recordsedexport_to_jsonl - Le valutazioni leggono un dataset tramite
Dataset(slug=...)oDataset(id=...), fino a 10.000 record - Un dataset non è un’istantanea: mantieni un set di riferimento stabile per confrontare le versioni