Évaluations hors ligne

Le SDK d'Évaluation (mistralai-evaluations) permet d'exécuter des évaluations hors ligne sur vos pipelines LLM en quelques lignes de Python. Définissez un jeu de données, une tâche et des fonctions de scoring pour obtenir des résultats dans votre terminal et dans Studio. Pour lancer une évaluation en quelques minutes, suivez Guide de démarrage : exécuter votre première évaluation.

Information

Les évaluations hors ligne sont en préversion publique et sont réservées aux organisations disposant du niveau Entreprise, comme le reste de Observabilité. Si votre organisation ne dispose pas du niveau Entreprise, contactez votre interlocuteur Mistral.

Le SDK repose sur une structure simple :

Dataset  →  Task  →  Evaluators  →  Results

Dataset  →  Task  →  Evaluators  →  Results

Jeu de données : une liste d'enregistrements d'entrée (dictionnaires) contenant vos cas de test, ou un jeu de données Studio.
Tâche : une fonction asynchrone ou synchrone qui reçoit un TaskContext et produit une sortie.
Évaluateurs : des fonctions qui reçoivent un ScorerContext et attribuent un score à chaque sortie.
Résultats : des statistiques et des scores par enregistrement, affichés dans le terminal et téléchargés vers Studio.

Installation

Prérequis : Python 3.12+ et une clé API Mistral.

Installez le package depuis PyPI :

pip install mistralai-evaluations

pip install mistralai-evaluations

Le SDK fonctionne avec mistralai 2.7.1 ou une version ultérieure, dans les branches 2.x et 3.x (mistralai>=2.7.1,<4). L'installation du SDK installe une version compatible de mistralai si vous n'en avez pas. Le passage de 2.x à 3.x ne nécessite aucune modification.

Définissez votre clé API :

export MISTRAL_API_KEY=<your-api-key>

export MISTRAL_API_KEY=<your-api-key>

Pour évaluer un agent créé avec le SDK Agents, installez également mistralai-agents 1.1.0 ou une version ultérieure (pip install -U mistralai-agents). Consultez Évaluer les agents du SDK Agents.

Authentification sans clé API

Un client s'authentifie généralement avec une clé API (Mistral(api_key=...) ou MISTRAL_API_KEY). Certains environnements n'ont pas de clé. Par exemple, un déploiement géré fournit à son worker un token de compte de service renouvelé régulièrement comme seul identifiant d'authentification.

Mistral accepte un client sans clé API lorsque son client HTTP définit l'en-tête Authorization sur chaque requête. C'est le cas du client renvoyé par get_mistral_client() dans mistralai.workflows.client : passez un client créé de cette manière et les appels à Studio transmettent le token du worker, sans configuration supplémentaire. En l'absence de clé et d'un tel client HTTP, la création du client lève l'erreur No API key found.

Pour exécuter des évaluations dans un workflow, utilisez le Plugin d'évaluation de workflow, qui effectue cette configuration pour vous.

Guide de démarrage

Créez un fichier eval.py :

import asyncio
import os

from mistralai.evaluations import (
    Evaluation, Evaluator, Goal, Mistral, Project, ScorerContext, System, TaskContext,
)

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

dataset = [
    {"sentence": "Hello, how are you?", "groundtruth": "English"},
    {"sentence": "Bonjour, comment ça va?", "groundtruth": "French"},
    {"sentence": "Hola, ¿cómo estás?", "groundtruth": "Spanish"},
]

async def task(ctx: TaskContext) -> str:
    response = await client.chat.complete_async(
        model=str(ctx.system.params["model"]),
        messages=[
            {"role": "system", "content": str(ctx.system.params["system_prompt"])},
            {"role": "user", "content": ctx.input_record["sentence"]},
        ],
    )
    return str(response.choices[0].message.content)

def scorer(ctx: ScorerContext) -> int:
    return 1 if ctx.input_record["groundtruth"].lower() == str(ctx.output).lower() else 0

async def main():
    run = await client.evaluation.run(
        project=Project(name="Language Detection"),
        evaluation=Evaluation(name="Accuracy Eval"),
        system=System(name="mistral-small", params={
            "model": "mistral-small-latest",
            "system_prompt": "What language is this sentence in? Reply with ONLY the language name.",
        }),
        dataset=dataset,
        task=task,
        evaluators=[
            Evaluator(
                name="accuracy",
                description="1 if the detected language matches the groundtruth, 0 otherwise.",
                scorer=scorer,
                goal=Goal.gte(0.8),
            ),
        ],
    )
    run.show(level="records")

asyncio.run(main())

import asyncio
import os

from mistralai.evaluations import (
    Evaluation, Evaluator, Goal, Mistral, Project, ScorerContext, System, TaskContext,
)

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

dataset = [
    {"sentence": "Hello, how are you?", "groundtruth": "English"},
    {"sentence": "Bonjour, comment ça va?", "groundtruth": "French"},
    {"sentence": "Hola, ¿cómo estás?", "groundtruth": "Spanish"},
]

async def task(ctx: TaskContext) -> str:
    response = await client.chat.complete_async(
        model=str(ctx.system.params["model"]),
        messages=[
            {"role": "system", "content": str(ctx.system.params["system_prompt"])},
            {"role": "user", "content": ctx.input_record["sentence"]},
        ],
    )
    return str(response.choices[0].message.content)

def scorer(ctx: ScorerContext) -> int:
    return 1 if ctx.input_record["groundtruth"].lower() == str(ctx.output).lower() else 0

async def main():
    run = await client.evaluation.run(
        project=Project(name="Language Detection"),
        evaluation=Evaluation(name="Accuracy Eval"),
        system=System(name="mistral-small", params={
            "model": "mistral-small-latest",
            "system_prompt": "What language is this sentence in? Reply with ONLY the language name.",
        }),
        dataset=dataset,
        task=task,
        evaluators=[
            Evaluator(
                name="accuracy",
                description="1 if the detected language matches the groundtruth, 0 otherwise.",
                scorer=scorer,
                goal=Goal.gte(0.8),
            ),
        ],
    )
    run.show(level="records")

asyncio.run(main())

Exécutez-le :

uv run eval.py

uv run eval.py

Les résultats s'affichent dans votre terminal et sont téléchargés vers Studio sous Évaluer > Évaluations > Hors ligne.

Concepts clés

Une tâche est une fonction asynchrone (ou synchrone) qui reçoit un TaskContext et renvoie une sortie. Il s'agit du code que vous souhaitez évaluer :

from mistralai.evaluations import TaskContext

async def task(ctx: TaskContext) -> str:
    response = await client.chat.complete_async(
        model=str(ctx.system.params["model"]),
        messages=[
            {"role": "system", "content": str(ctx.system.params["system_prompt"])},
            {"role": "user", "content": ctx.input_record["prompt"]},
        ],
    )
    return str(response.choices[0].message.content)

from mistralai.evaluations import TaskContext

async def task(ctx: TaskContext) -> str:
    response = await client.chat.complete_async(
        model=str(ctx.system.params["model"]),
        messages=[
            {"role": "system", "content": str(ctx.system.params["system_prompt"])},
            {"role": "user", "content": ctx.input_record["prompt"]},
        ],
    )
    return str(response.choices[0].message.content)

La tâche peut renvoyer n'importe quel type : chaînes de caractères, modèles Pydantic ou dictionnaires. Le SDK sérialise la sortie pour le téléchargement.

Avertissement

Privilégiez les tâches asynchrones pour les traitements longs. Une tâche synchrone s'exécute sur la boucle d'événements, qui envoie également à Studio le signal périodique d'activité de l'exécution. Un appel synchrone qui bloque pendant plusieurs minutes empêche l'envoi de ce signal. Studio peut alors marquer comme annulée une exécution toujours en cours. Utilisez une tâche asynchrone ou déportez le traitement bloquant avec await asyncio.to_thread(...).

TaskContext vous donne un accès typé à ctx.input_record (l'enregistrement courant du jeu de données), ctx.system (la configuration System de evaluation.run()) et ctx.metadata (les métadonnées de l'exécution). Annotez le paramètre avec TaskContext : le SDK transmet un objet de contexte uniquement lorsque le paramètre unique de la fonction porte cette annotation. Sans cette annotation, la fonction reçoit l'enregistrement brut.

Organiser les exécutions dans Studio

Utilisez les Projets et les Évaluations pour organiser les exécutions :

Projet : regroupe les évaluations liées à un système (par exemple, "Language Detection").
Évaluation : une évaluation spécifique au sein d'un projet (par exemple, "Accuracy Eval").
Exécution : chaque appel à evaluation.run() avec une evaluation crée une nouvelle exécution au sein de celle-ci. Sans evaluation, l'exécution reste locale et n'est pas enregistrée.

run = await client.evaluation.run(
    project=Project(name="My Project"),       # created if it doesn't exist
    evaluation=Evaluation(name="My Eval"),    # created if it doesn't exist
    dataset=dataset,
    task=task,
    evaluators=[...],
)

run = await client.evaluation.run(
    project=Project(name="My Project"),       # created if it doesn't exist
    evaluation=Evaluation(name="My Eval"),    # created if it doesn't exist
    dataset=dataset,
    task=task,
    evaluators=[...],
)

Vous pouvez également référencer des entités existantes par leur slug :

project=Project(slug="my-project")
evaluation=Evaluation(slug="my-eval")

project=Project(slug="my-project")
evaluation=Evaluation(slug="my-eval")

Les tags et les métadonnées vous aident à filtrer et à comparer les exécutions dans Studio :

run = await client.evaluation.run(
    ...
    tags=["model:mistral-small", "prompt:v2"],
    metadata={"commit": "abc123"},
)

run = await client.evaluation.run(
    ...
    tags=["model:mistral-small", "prompt:v2"],
    metadata={"commit": "abc123"},
)

Mode local

Utilisez local=True pour exécuter des évaluations sans télécharger les résultats vers Studio. Ce mode permet d'itérer rapidement pendant le développement :

run = await client.evaluation.run(
    dataset=dataset,
    task=task,
    evaluators=[Evaluator(name="accuracy", scorer=scorer)],
    local=True,  # no upload, no project/evaluation required
)
run.show(level="records")

run = await client.evaluation.run(
    dataset=dataset,
    task=task,
    evaluators=[Evaluator(name="accuracy", scorer=scorer)],
    local=True,  # no upload, no project/evaluation required
)
run.show(level="records")

L'omission de evaluation conserve également l'exécution en local, même sans local=True.

Un workflow de développement type :

Itérer en local : définissez local=True et ajustez votre tâche et vos fonctions de scoring jusqu'à obtenir les résultats attendus.
Envoyer vers Studio : supprimez local=True et ajoutez project et evaluation pour suivre les résultats dans le temps.

Afficher les résultats

La méthode run.show() affiche les résultats avec différents niveaux de détail :

run.show(level="run")          # Summary statistics only
run.show(level="records")      # Per-record results
run.show(level="generations")  # Per-generation details
run.show(level="scores")       # Full score breakdown

run.show(level="run")          # Summary statistics only
run.show(level="records")      # Per-record results
run.show(level="generations")  # Per-generation details
run.show(level="scores")       # Full score breakdown

Pour afficher les résultats au format JSON, passez mode="json" :

run.show(mode="json", level="records")

run.show(mode="json", level="records")

show() affiche les résultats et ne renvoie rien. Pour traiter les résultats dans votre code, lisez directement les champs de l'exécution renvoyée (par exemple run.statistics et run.output_records), ou redirigez la sortie standard pour récupérer le JSON.

Résultats dans Studio

Une fois l'exécution terminée, les résultats sont disponibles sous Évaluer > Évaluations > Hors ligne dans Studio. Chaque exécution télécharge automatiquement ses scores, ses statistiques et ses métadonnées.

L'interface de Studio propose quatre façons d'explorer les résultats :

Graphiques de tendance : pour les évaluateurs dont les scores sont catégoriels, un graphique en aires empilées montre l'évolution de la part de chaque étiquette d'une exécution à l'autre, pour vous aider à repérer les régressions. Les évaluateurs numériques affichent leurs statistiques (par exemple la moyenne) pour chaque exécution dans le tableau des exécutions, plutôt que dans un graphique de tendance.
Graphiques de distribution : un diagramme circulaire représente la fréquence des étiquettes pour les évaluateurs catégoriels.
Filtres combinables : filtrez les exécutions par ID, tag, système, métadonnées, statut de l'objectif ou seuil de score pour isoler des sous-ensembles spécifiques.
Vue détaillée de l'exécution : ouvrez une exécution pour examiner les entrées, les sorties et les scores de chaque enregistrement. Les détails des générations peuvent être développés lorsque num_generations > 1.

Les valeurs des cellules s'affichent automatiquement selon leur type : textes, nombres, booléens, objets JSON et tableaux de conversations LLM disposent chacun de leur propre format d'affichage.

Explorer la documentation

Parcourez les composants dans l'ordre où vous les utilisez pour construire une évaluation :

Les ensembles de données : structurez vos cas de test sous forme d'enregistrements Python typés, ou utilisez un jeu de données Studio.
Configurer les paramètres système : séparez la configuration de la tâche de son code pour comparer les exécutions côte à côte dans Studio.
Évaluateurs : définissez des fonctions de scoring pour chaque métrique — fonctions basées sur des règles ou LLM utilisé comme juge.
Définir des objectifs : définissez des seuils de réussite ou d'échec et configurez le sens et la normalisation des scores sur les évaluateurs.
Configurer les statistiques : choisissez les valeurs calculées à l'échelle de l'exécution (moyennes, totaux, percentiles) qu'un évaluateur fournit.
Évaluer les agents du SDK Agents : évaluez, comparez et optimisez un agent créé avec le SDK Agents.
Optimiser les prompts et les paramètres : recherchez automatiquement de meilleurs prompts et paramètres système.

Guides avancés :

Utiliser les objets de contexte : référence de TaskContext, de ScorerContext et des contextes de métadonnées.
Utiliser plusieurs évaluateurs : exécutez plusieurs fonctions de scoring dans une même exécution, en combinant notamment des évaluateurs basés sur des règles et des LLM utilisés comme juges.
Utiliser des évaluateurs à l'échelle de l'exécution : métriques agrégées (F1, critères personnalisés) calculées après l'attribution d'un score à tous les enregistrements.
Itérer en local : itérez sans télécharger les résultats vers Studio.
Réduire la variance avec plusieurs générations : réduisez la variance en exécutant chaque enregistrement N fois.
Réexécuter les enregistrements en échec : réexécutez uniquement les enregistrements qui ont produit une erreur et mettez à jour les résultats existants.
Recalculer les scores des exécutions enregistrées : itérez sur les fonctions de scoring sans réexécuter la tâche.

Exécuter dans Mistral Workflows :

Plugin d'évaluation de workflow : exécutez les mêmes évaluations dans un workflow, avec des activités Temporal parallèles et des tentatives automatiques en cas d'échec.

Références :

Référence API : evaluation.run() et les types principaux.
Limites : limites de taille des données transmises, de parallélisme et de batch, et interprétation des erreurs API.
Historique des versions sur PyPI : modifications par version.

FAQ

Évaluations hors ligne

Installation

Authentification sans clé API

Guide de démarrage

Concepts clés

Organiser les exécutions dans Studio

Mode local

Afficher les résultats

Résultats dans Studio

Explorer la documentation

FAQ

Quelle version de Python est requise ?

Quelles versions de mistralai sont prises en charge ?

Puis-je exécuter des évaluations sans clé API ?

Puis-je utiliser des fonctions synchrones pour les tâches et les fonctions de scoring ?

Comment utiliser un LLM comme juge ?

Puis-je utiliser plusieurs évaluateurs dans une même exécution ?

Comment comparer deux versions de modèle ?