Évaluations hors ligne

Le SDK d’évaluation (mistralai-evaluations) vous permet d’exécuter des évaluations hors ligne sur vos pipelines LLM en quelques lignes de Python. Définissez un ensemble de données, une tâche et des fonctions de scoring pour obtenir les résultats dans votre terminal et dans Studio.

Information

Les évaluations hors ligne sont disponibles uniquement pour les organisations avec le plan Enterprise. Contactez votre représentant Mistral pour les activer pour votre organisation.

Le SDK repose sur un modèle mental simple :

Dataset  →  Task  →  Evaluators  →  Results

Dataset  →  Task  →  Evaluators  →  Results

Ensemble de données : une liste d'enregistrements d'entrée (dicts) avec vos cas de test, ou un ensemble 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 notent chaque sortie.
Résultats : des statistiques et des notes 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

Définiasez votre clé API :

export MISTRAL_API_KEY=<your-api-key>

export MISTRAL_API_KEY=<your-api-key>

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 Observabilité → Évaluer → Évaluations.

Concepts de base

Une tâche est une fonction async (ou sync) qui reçoit un TaskContext et renvoie une sortie. C'est le code que vous voulez é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 dicts. Le SDK sérialise la sortie pour le téléchargement.

Attention

Préférez les tâches async pour les traitements longs

Une tâche sync s'exécute sur l'event loop, qui envoie aussi le heartbeat de l'exécution à Studio. Un appel sync qui bloque pendant plusieurs minutes prive le heartbeat, et Studio peut alors marquer une exécution en cours comme annulée. Utilisez une tâche async, ou déléguez les traitements bloquants avec await asyncio.to_thread(...).

TaskContext vous donne un accès typé à ctx.input_record (l'enregistrement courant de l'ensemble de données), ctx.system (la config System de evaluation.run()) et ctx.metadata (les métadonnées de l'exécution).

Organiser les exécutions dans Studio

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

Projet : regroupe les évaluations liées pour un système (par exemple, « Détection de la langue »).
Évaluation : une évaluation spécifique au sein d’un projet (par exemple, « Évaluation de la précision »).
Exécution : chaque appel à evaluation.run() crée une nouvelle exécution sous l’évaluation.

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 slug :

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

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

Les balises 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. Cela est utile pour des itérations rapides 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")

Un workflow de développement typique :

Itérer en local : définissez local=True et ajustez votre tâche et vos évaluateurs jusqu’à obtenir des résultats satisfaisants.
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 à 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

Exportez en JSON pour un traitement ultérieur :

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

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

Résultats dans Studio

Une fois qu’une exécution est terminée, les résultats sont disponibles dans Observabilité → Évaluer → Évaluations dans Studio. Chaque exécution télécharge automatiquement ses scores, statistiques et métadonnées.

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

Graphiques d’évolution : moyennes des scores au fil du temps avec des bandes min/max, afin de repérer les régressions entre les exécutions.
Graphiques de distribution : camemberts et graphiques en aires empilées affichant la répartition des scores entre les enregistrements et les exécutions.
Filtres modulables : filtrez par étiquette, ID d’exécution ou seuil métrique pour isoler des sous-ensembles spécifiques.
Vue détaillée de l’exécution : ouvrez n’importe quelle exécution pour inspecter les entrées, les sorties et les scores par enregistrement, avec des détails de génération expansibles lorsque num_generations > 1.

Les valeurs des cellules s’affichent automatiquement en fonction de leur type : texte brut, objets JSON et tableaux de conversations LLM bénéficient chacun de leur propre format d’affichage.

Explorer les documents

Travaillez les briques de base 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 ensemble de données Studio.
Configurer les paramètres système : externalisez la configuration des tâches pour une comparaison côte à côte dans Studio.
Évaluateurs : définissez des fonctions de notation pour chaque métrique — fonctions basées sur des règles ou LLM-as-judge.
Définir des objectifs : définissez des seuils de réussite ou d’échec, ainsi que la direction et la normalisation sur les évaluateurs.
Configurer les statistiques : choisissez les valeurs au niveau de l’exécution (moyennes, totaux, percentiles) qu’un évaluateur expose.
Optimiser les prompts et paramètres : recherchez automatiquement de meilleurs prompts et paramètres système.

Guides avancés :

Utiliser les objets de contexte : TaskContext, ScorerContext et les références des contextes de métadonnées.
Évaluateurs multiples : exécutez plusieurs scorers en une seule exécution, avec une combinaison de juges fondés sur des règles et de juges LLM.
Utiliser les évaluateurs au niveau des exécutions : métriques agrégées (F1, portails personnalisés) calculées après que tous les enregistrements ont été notés.
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éessayer les enregistrements en échec : réexécutez uniquement les enregistrements en erreur, corrigez les résultats en place.
Renoter les 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 relances automatiques.

Références :

Référence API : evaluation.run() et les types principaux.
Historique des versions sur PyPI : modifications par version.

FAQ

Évaluations hors ligne

Installation

guide de démarrage

Concepts de base

Organiser les exécutions dans Studio

Mode local

Afficher les résultats

Résultats dans Studio

Explorer les documents

FAQ

Quelle version de Python est requise ?

Puis-je utiliser des fonctions synchrones pour les tâches et les évaluateurs ?

Comment utiliser un LLM en tant que juge ?

Puis-je exécuter plusieurs évaluateurs en une seule exécution ?

Comment comparer deux versions de modèle ?