Home
Vibe
Studio

Évaluations hors ligne

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

i
Information

Les évaluations hors ligne sont réservées aux organisations de niveau Enterprise. Contactez votre représentant Mistral pour obtenir l’accès au package mistralai-observability.

Le SDK repose sur un modèle mental simple :

Dataset  →  Task  →  Evaluators  →  Results
  • Jeu de données : une liste d’enregistrements d’entrée (dictionnaires) contenant vos cas de test.
  • 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

Installation

Prérequis : Python 3.12 ou version ultérieure, uv et une clé API Mistral.

Après avoir reçu votre jeton d’autorisation de Mistral, configurez vos identifiants :

export UV_INDEX_CLOUDSMITH_USERNAME=token
export UV_INDEX_CLOUDSMITH_PASSWORD=<your-entitlement-token>

Ajoutez le package et le dépôt privé Mistral à votre fichier pyproject.toml :

[project]
name = "my-eval-project"
version = "0.1.0"
dependencies = ["mistralai-observability"]

[[tool.uv.index]]
name = "cloudsmith"
url = "https://dl.cloudsmith.io/basic/mistral-ai/sdk-distribution/python/simple/"

Puis installez-le :

uv sync

Définiasez votre clé API :

export MISTRAL_API_KEY=<your-api-key>
guide de démarrage

guide de démarrage

Créez un fichier eval.py :

import asyncio
import os

from mistralai.observability 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

Les résultats s’affichent dans votre terminal et sont téléchargés vers Studio sous Observabilité → Évaluer → Évaluations.

Concepts de base

Concepts de base

Une tâche est une fonction asynchrone (ou synchrone) qui reçoit un TaskContext et retourne une sortie. C’est le code que vous souhaitez évaluer :

from mistralai.observability 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 retourner 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.

TaskContext vous donne un accès typé à ctx.input_record (l’enregistrement du jeu de données en cours), ctx.system (la configuration System de evaluation.run()) et ctx.metadata (métadonnées d’exécution).

Organiser les exécutions dans Studio

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=[...],
)

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

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"},
)
Mode local

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")

Un workflow de développement typique :

  1. Itérer en local : définissez local=True et ajustez votre tâche et vos évaluateurs jusqu’à obtenir des résultats satisfaisants.
  2. Envoyer vers Studio : supprimez local=True et ajoutez project et evaluation pour suivre les résultats dans le temps.
Afficher les résultats

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

Exportez en JSON pour un traitement ultérieur :

run.show(mode="json", level="records")
Résultats dans Studio

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.

Guides

Guides

FAQ

FAQ