Datasets : construire des jeux d'évaluation et itérer

Leçon réécrite le 2 novembre 2026 d’après la page Datasets de Mistral et le SDK mistralai 3.7.0 : un enregistrement porte un payload libre et des properties, les datasets s’alimentent par saisie, import de fichier ou depuis les spans de l’Explorer, et se passent tels quels aux évaluations hors ligne. La méthode import_from_explorer de l’ancienne version n’existe pas. Sources : Datasets · Explore traces.

Le maillon final de la boucle d’itération

Un dataset est l’ensemble des cas de test qui pilote une évaluation hors ligne. C’est lui qui donne de la mémoire à votre démarche qualité : chaque incident observé en production peut y devenir un cas de test, et chaque nouvelle version de l’application s’y mesure. Sans dataset stable, on compare des impressions ; avec, on compare des chiffres.

Structure d’un enregistrement

Dans Studio, chaque enregistrement contient un payload — un objet JSON dont vous choisissez les clés — et des properties, des métadonnées qui ne sont pas transmises à la tâche évaluée. Lors d’une évaluation, le payload devient tel quel l’enregistrement d’entrée (ctx.input_record).

{"payload": {"ticket": "Ma facture d'octobre compte deux fois le même abonnement.", "categorie": "facturation"}, "properties": {"source": "incident-2026-10-14"}}

Cette ligne est aussi le format d’import JSONL des datasets de Studio : un objet par ligne, avec payload et properties.

Les sources de données

Un dataset s’alimente de plusieurs façons :

• Saisie directe, dans Studio ou par l’API, enregistrement par enregistrement
• Import d’un fichier JSONL au format ci-dessus
• Depuis l’Explorer : un span, ou jusqu’à 500 spans sélectionnés, deviennent des enregistrements (leçon 12)
• Depuis le Playground de Studio ou depuis un autre dataset

from mistralai.client import Mistral

client = Mistral(api_key="votre-cle-api")
datasets = client.beta.observability.datasets

# Créer le dataset
dataset = datasets.create(
    name="Tickets support — jeu de référence",
    description="Cas de classement de tickets validés à la main",
)
print(f"Dataset : {dataset.id} ({dataset.slug})")

# Ajouter des enregistrements
cas = [
    {"ticket": "Je n'arrive plus à me connecter depuis ce matin.", "categorie": "acces"},
    {"ticket": "L'export PDF plante dès que le rapport dépasse 50 pages.", "categorie": "bug"},
]
for payload in cas:
    datasets.create_record(
        dataset_id=dataset.id,
        payload=payload,
        properties={"origine": "saisie manuelle"},
    )

Pour un gros volume, import_from_file importe un fichier JSONL déjà téléversé (par son file_id), et import_from_spans reprend des spans de traces : ces imports tournent en tâche de fond, dont fetch_task suit l’avancement.

Relire et exporter

list_records parcourt les enregistrements page par page (page_size, page), et export_to_jsonl produit un export dont la réponse donne l’adresse de téléchargement (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)

Évaluer sur un dataset de Studio

Une évaluation hors ligne lit un dataset de Studio par son slug ou par son identifiant :

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

run = await client.evaluation.run(
    project=Project(name="Tri des tickets"),
    evaluation=Evaluation(name="Jeu de référence"),
    dataset=Dataset(slug="tickets-support-jeu-de-reference"),
    task=tache,
    evaluators=[Evaluator(name="exactitude", scorer=exactitude)],
)

Ici, client est le client du SDK d’évaluation, et tache et exactitude sont ceux de la leçon 14. Passez exactement l’un de slug et id ; sélectionner un dataset par son slug ne le crée jamais. Deux règles à connaître : un run lit les enregistrements présents à son démarrage, jusqu’à 10 000 — un dataset n’est pas un instantané, et le modifier n’affecte que les runs suivants — et si des enregistrements sont ajoutés ou retirés pendant la lecture, le run échoue avant de commencer plutôt que de tourner sur un ensemble incohérent.

Bonnes pratiques de gestion

Gardez un jeu de référence stable. Un dataset qui change à chaque run rend les comparaisons impossibles. Créez un jeu de référence que vous ne modifiez que délibérément, et des datasets de travail à côté.

Nourrissez-le de la production. Les cas les plus utiles sont ceux qui ont réellement posé problème : un span repéré dans l’Explorer, dont vous corrigez la sortie attendue, vaut mieux que dix cas inventés.

Documentez la provenance. Les properties (origine, date, incident lié) ne sont pas vues par la tâche, mais elles vous diront dans six mois pourquoi un cas existe.

Équilibrez. Un dataset qui ne contient que des cas faciles flatte votre système ; un dataset qui ne contient que des pièges le décourage. Visez la répartition réelle de votre trafic, plus une poignée de cas limites assumés.

Points clés à retenir

• Un enregistrement de dataset = un payload (l’entrée de la tâche) et des properties (métadonnées)
• Saisie, import JSONL, spans de l’Explorer, Playground : plusieurs sources pour un même dataset
• Le SDK expose create, create_record, import_from_file, import_from_spans, list_records et export_to_jsonl
• Les évaluations lisent un dataset par Dataset(slug=...) ou Dataset(id=...), jusqu’à 10 000 enregistrements
• Un dataset n’est pas un instantané : gardez un jeu de référence stable pour comparer les versions