Guide de démarrage : attribuez un score à votre premier span avec les évaluations en ligne

Dans ce guide de démarrage, vous créez un juge d'analyse des sentiments, l'associez à des spans de conversation, envoyez un span et récupérez son score.

Avant de commencer, vous avez besoin de :

Une clé API utilisateur pour un espace de travail qui remplit les prérequis. Les clés de compte de service ne permettent pas de créer d'évaluations en direct.
curl pour les étapes 1, 2 et 4.
Python 3.12 ou version ultérieure pour l'étape 3.

export MISTRAL_API_KEY=<your-api-key>
export MISTRAL_BASE_URL=https://api.mistral.ai

export MISTRAL_API_KEY=<your-api-key>
export MISTRAL_BASE_URL=https://api.mistral.ai

1. Créer un évaluateur

curl -s -X POST "$MISTRAL_BASE_URL/v1/observability/scorers" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sentiment judge",
    "kind": "llm_judge",
    "config": {
      "model": "mistral-small-latest",
      "prompt_template": "Classify the sentiment of the following conversation as either good or bad.\n\n{{ conversation }}",
      "output_spec": { "type": "categorical", "labels": ["good", "bad"] }
    }
  }'

curl -s -X POST "$MISTRAL_BASE_URL/v1/observability/scorers" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sentiment judge",
    "kind": "llm_judge",
    "config": {
      "model": "mistral-small-latest",
      "prompt_template": "Classify the sentiment of the following conversation as either good or bad.\n\n{{ conversation }}",
      "output_spec": { "type": "categorical", "labels": ["good", "bad"] }
    }
  }'

La réponse contient le slug généré pour l'évaluateur (par exemple sentiment-judge-3f9a1c2e) et latest_version.variables, qui liste les variables du modèle trouvées dans le prompt (ici ["conversation"]).

export SCORER_SLUG=<slug from the response>

export SCORER_SLUG=<slug from the response>

2. Créer une évaluation en direct

Sélectionnez les spans de conversation et associez la variable conversation à la transcription formatée de chaque span :

curl -s -X POST "$MISTRAL_BASE_URL/v1/observability/pipelines" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Chat sentiment",
    "selectors": [
      { "source_kind": "span", "filter": "gen_ai.operation.name = \"chat\"" }
    ],
    "definitions": [
      { "slug": "'"$SCORER_SLUG"'", "mapping": { "conversation": "transcript" } }
    ]
  }'

curl -s -X POST "$MISTRAL_BASE_URL/v1/observability/pipelines" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Chat sentiment",
    "selectors": [
      { "source_kind": "span", "filter": "gen_ai.operation.name = \"chat\"" }
    ],
    "definitions": [
      { "slug": "'"$SCORER_SLUG"'", "mapping": { "conversation": "transcript" } }
    ]
  }'

Les évaluations en direct sont activées dès leur création. La réponse contient une entrée dans pipeline_configs pour chaque évaluateur associé. Conservez son slug, car il permet d'identifier les résultats :

export CONFIG_SLUG=<pipeline_configs[0].slug from the response>
export PIPELINE_ID=<id from the response>

export CONFIG_SLUG=<pipeline_configs[0].slug from the response>
export PIPELINE_ID=<id from the response>

3. Envoyer un span

Ce juge lit la conversation. Créez donc l'opération avec include_content=True pour enregistrer les messages dans le span :

pip install "mistralai-otel-observability[mistral]"

pip install "mistralai-otel-observability[mistral]"

import os

from mistralai.client import Mistral
from mistralai.observability.otel import observability
from mistralai.observability.otel import semconv_constants as genai

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
observability.configure_mistral(service_name="my-app")  # reads MISTRAL_API_KEY

messages = [{"role": "user", "content": "I love this!"}]

with observability.operation(
    genai.OPERATION_NAME_CHAT,
    model="mistral-large-latest",
    provider=genai.PROVIDER_NAME_MISTRAL_AI,
    include_content=True,
) as chat:
    response = client.chat.complete(model="mistral-large-latest", messages=messages)
    chat.mistral_completion(response, messages=messages)

observability.shutdown()  # flushes pending telemetry before exit

import os

from mistralai.client import Mistral
from mistralai.observability.otel import observability
from mistralai.observability.otel import semconv_constants as genai

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
observability.configure_mistral(service_name="my-app")  # reads MISTRAL_API_KEY

messages = [{"role": "user", "content": "I love this!"}]

with observability.operation(
    genai.OPERATION_NAME_CHAT,
    model="mistral-large-latest",
    provider=genai.PROVIDER_NAME_MISTRAL_AI,
    include_content=True,
) as chat:
    response = client.chat.complete(model="mistral-large-latest", messages=messages)
    chat.mistral_completion(response, messages=messages)

observability.shutdown()  # flushes pending telemetry before exit

4. Consulter le score

Le score est disponible quelques secondes après l'envoi du span.

curl -s -X POST "$MISTRAL_BASE_URL/v1/observability/spans/evaluations/search" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"search_expression\": \"evaluation_name = 'judge:$CONFIG_SLUG'\" }"

curl -s -X POST "$MISTRAL_BASE_URL/v1/observability/spans/evaluations/search" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"search_expression\": \"evaluation_name = 'judge:$CONFIG_SLUG'\" }"

La réponse liste les scores dans span_evaluations.results, du plus récent au plus ancien :

{
  "span_evaluations": {
    "results": [
      {
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "span_id": "00f067aa0ba902b7",
        "timestamp": "2026-11-03T16:42:11.125403Z",
        "evaluation_name": "judge:sentiment-judge-3f9a1c2e-7b04d1aa",
        "score_label": "good",
        "explanation": "The user expresses clear satisfaction."
      }
    ]
  }
}

{
  "span_evaluations": {
    "results": [
      {
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "span_id": "00f067aa0ba902b7",
        "timestamp": "2026-11-03T16:42:11.125403Z",
        "evaluation_name": "judge:sentiment-judge-3f9a1c2e-7b04d1aa",
        "score_label": "good",
        "explanation": "The user expresses clear satisfaction."
      }
    ]
  }
}

La réponse contient plus de champs que ceux présentés ici. Voir L'enregistrement de résultat.

Le même résultat s'affiche sur la page de l'évaluation en direct, sous Évaluer → Évaluations → En direct dans AI Studio, ainsi que sur le span dans la vue des traces.

Nettoyer

curl -s -X DELETE "$MISTRAL_BASE_URL/v1/observability/pipelines/$PIPELINE_ID" \
  -H "Authorization: Bearer $MISTRAL_API_KEY"

curl -s -X DELETE "$MISTRAL_BASE_URL/v1/observability/pipelines/$PIPELINE_ID" \
  -H "Authorization: Bearer $MISTRAL_API_KEY"

Les évaluateurs n'ont pas d'endpoint de suppression. Conserver un évaluateur ne coûte rien dès lors qu'aucune évaluation en direct ne l'utilise.

Si aucun résultat ne s'affiche

Point à vérifier	Explication
Le span contient `gen_ai.input.messages` ou `gen_ai.output.messages`	Sans ces attributs, `transcript` est vide et la variable reste non définie.
Le filtre correspond au span	Les clés du filtre sont les noms bruts des attributs. Consultez Évaluations en direct.
L'évaluation en direct et ses configurations ont `enabled: true`	Les évaluations en direct mises en pause ne sélectionnent aucun span.
Vous avez utilisé le slug de la configuration du pipeline pour la recherche	`judge:<scorer-slug>` et `judge:<live-eval-slug>` ne correspondent jamais aux résultats.
La période de votre requête inclut le span	Par défaut, la recherche porte sur la dernière heure.
La trace d'évaluation affiche une erreur	L'appel au juge ou le rendu du prompt a échoué. Le span `evaluation judge:<slug>` contient l'erreur.