Référence API

Références des types principaux du SDK d'évaluation et du point d'entrée principal evaluation.run(). Pour les références des méthodes des opérations avancées, consultez Relancer les enregistrements en échec, Recalculer les scores des exécutions enregistrées et Optimiser les prompts et les paramètres. Pour les limites de taille et les erreurs API, consultez Limites.

Le point d'entrée principal pour lancer des évaluations.

run = await client.evaluation.run(
    dataset=...,
    task=...,
    evaluators=...,
    # optional parameters below
)

run = await client.evaluation.run(
    dataset=...,
    task=...,
    evaluators=...,
    # optional parameters below
)

La fonction renvoie un EvaluationRun :

run() attribue le statut "running" à l'exécution pendant son traitement, puis "completed". Si l'exécution lève une exception, elle reçoit le statut "failed" ; si elle est interrompue, "cancelled". Pendant le traitement, le SDK envoie un signal de présence à Studio. Ainsi, une exécution dont le processus s'arrête reçoit le statut "cancelled" au lieu de rester en cours.

Un projet regroupe des évaluations liées entre elles. Il fonctionne comme un dossier, par exemple « Tests qualité du chatbot » ou « Pipeline RAG ».

Project(name="My Project")       # create or get by name
Project(slug="my-project")       # get by slug

Project(name="My Project")       # create or get by name
Project(slug="my-project")       # get by slug

Vous devez fournir au moins l'un des paramètres name ou slug. Un projet sélectionné par son nom est créé s'il n'existe pas ; un projet sélectionné par son slug doit déjà exister.

Sélectionne un ensemble de données Studio par slug ou UUID. Le SDK récupère ses enregistrements avant le début de l'exécution. Consultez Utiliser un ensemble de données Studio.

from mistralai.evaluations import Dataset

Dataset(slug="customer-support-golden-set")
Dataset(id="018f879d-20cd-7e9f-a1bc-2f4f08b6f170")

from mistralai.evaluations import Dataset

Dataset(slug="customer-support-golden-set")
Dataset(id="018f879d-20cd-7e9f-a1bc-2f4f08b6f170")

Vous devez fournir exactement l'un des paramètres id ou slug, et id doit être un UUID valide. L'ensemble de données doit déjà exister : le sélectionner par son slug ne le crée jamais.

Une évaluation est un test nommé que vous exécutez régulièrement, par exemple « Précision sur les prompts French ». Chaque appel à evaluation.run() crée une nouvelle exécution dans cette évaluation. Vous pouvez ainsi suivre l'évolution des scores d'une exécution à l'autre.

Evaluation(name="My Eval")       # create or get by name
Evaluation(slug="my-eval")       # get by slug

Evaluation(name="My Eval")       # create or get by name
Evaluation(slug="my-eval")       # get by slug

Vous devez fournir au moins l'un des paramètres name ou slug. Une évaluation sélectionnée par son nom est créée dans le projet indiqué si elle n'existe pas ; une évaluation sélectionnée par son slug doit déjà exister.

Un évaluateur définit comment attribuer un score à chaque enregistrement. Il associe un nom à une fonction de scoring qui reçoit un ScorerContext et renvoie un score.

Evaluator(
    name="accuracy",
    scorer=my_scorer,
    description="Optional description",
    tags=["tag1"],
    num_scores=1,
    goal=Goal.gte(0.8),
)

Evaluator(
    name="accuracy",
    scorer=my_scorer,
    description="Optional description",
    tags=["tag1"],
    num_scores=1,
    goal=Goal.gte(0.8),
)

Une fonction de scoring peut renvoyer :

• int ou float — score numérique (statistiques : moyenne, minimum, maximum, écart-type, nombre).
• str ou bool — score catégoriel (statistiques : fréquences et mode, lorsque statistics est omis).
• Score(value=..., rationale=..., metadata=...) — score enrichi d'une explication et de données supplémentaires.

Un évaluateur d'exécution intervient sur l'ensemble des résultats une fois tous les enregistrements traités. Utilisez-le pour les métriques agrégées qui ne peuvent pas être calculées par enregistrement, comme le score F1, les critères globaux de réussite ou d'échec, ou l'analyse croisée des enregistrements.

RunEvaluator(
    name="accuracy_gate",
    scorer=my_run_scorer,
)

RunEvaluator(
    name="accuracy_gate",
    scorer=my_run_scorer,
)

La fonction de scoring reçoit un RunEvaluatorContext qui donne accès à tous les enregistrements, à leurs scores, aux statistiques agrégées et à la configuration du système. Consultez le guide des évaluateurs d'exécution pour des exemples.

Fabrique de spécifications d'objectifs. Consultez Définir des objectifs pour le guide complet.

from mistralai.evaluations import Goal

Goal.gte(0.8)             # gate: score >= 0.8
Goal.lte(0.1)             # gate: score <= 0.1
Goal.between(0.2, 0.8)    # gate: 0.2 <= score <= 0.8

from mistralai.evaluations import Goal

Goal.gte(0.8)             # gate: score >= 0.8
Goal.lte(0.1)             # gate: score <= 0.1
Goal.between(0.2, 0.8)    # gate: 0.2 <= score <= 0.8

Un Goal définit uniquement un critère de réussite. Pour indiquer le sens d'amélioration du score, définissez direction="maximize" / "minimize" sur l'évaluateur (ce sens est également déduit d'un objectif gte/lte).

Un système décrit la configuration utilisée par votre tâche : nom du modèle, température, prompt système, etc. Stocker ces valeurs sous forme de paramètres plutôt que de les coder en dur les rend visibles dans Studio. Vous pouvez ainsi comparer les exécutions avec différentes configurations. Consultez Configurer les paramètres du système pour en savoir plus.

from mistralai.evaluations import System

system = System(name="small-t0", params={"model": "mistral-small-latest", "temperature": 0})

from mistralai.evaluations import System

system = System(name="small-t0", params={"model": "mistral-small-latest", "temperature": 0})

Lorsque system est fourni, les tâches et les fonctions de scoring peuvent y accéder via ctx.system :

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

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

Consultez Utiliser les objets de contexte pour les références complètes du contexte.