Skill Évaluateur Arize

Ce skill couvre la conception, la création et l'exécution d'évaluateurs LLM-as-judge sur Arize. Un évaluateur définit le juge ; une tâche est la façon dont vous l'exécutez sur des données réelles.

Prérequis

Procédez directement avec la tâche — exécutez la commande ax dont vous avez besoin. N'effectuez PAS de vérification de versions, de variables d'environnement ou de profils au préalable.

Si une commande ax échoue, dépannez en fonction de l'erreur :

• command not found ou erreur de version → voir references/ax-setup.md
• 401 Unauthorized / clé API manquante → exécutez ax profiles show pour inspecter le profil actuel. Si le profil est manquant ou la clé API est incorrect : vérifiez .env pour ARIZE_API_KEY et utilisez-la pour créer/mettre à jour le profil via references/ax-profiles.md. Si .env n'a pas non plus de clé, demandez à l'utilisateur sa clé API Arize (https://app.arize.com/admin > API Keys)
• Space ID inconnu → vérifiez .env pour ARIZE_SPACE_ID, ou exécutez ax spaces list -o json, ou demandez à l'utilisateur
• L'appel au fournisseur LLM échoue (OPENAI_API_KEY / ANTHROPIC_API_KEY manquant) → vérifiez .env, chargez-le s'il est présent, sinon demandez à l'utilisateur

Concepts

Qu'est-ce qu'un évaluateur ?

Un évaluateur est une définition LLM-as-judge. Il contient :

Les évaluateurs sont versionnés — chaque modification de prompt ou de modèle crée une nouvelle version immuable. La version la plus récente est active.

Qu'est-ce qu'une tâche ?

Une tâche est la façon dont vous exécutez un ou plusieurs évaluateurs sur des données réelles. Les tâches sont attachées à un projet (traces/spans en direct) ou à un dataset (exécutions d'expérience). Une tâche contient :

Granularité des données

Le flag --data-granularity contrôle l'unité de données que l'évaluateur évalue. Il est défini par défaut sur span et s'applique uniquement aux tâches de projet (pas aux tâches dataset/expérience — celles-ci évaluent les exécutions d'expérience directement).

Comment fonctionne l'agrégation de trace et de session

Pour la granularité trace, les spans partageant le même context.trace_id sont regroupés. Les valeurs de colonne utilisées par le template de l'évaluateur sont jointes par des virgules dans une seule chaîne (chaque valeur tronquée à 100 000 caractères) avant d'être passées au modèle juge.

Pour la granularité session, le même regroupement au niveau des traces se produit d'abord, puis les traces sont triées par start_time et regroupées par attributes.session.id. Les valeurs au niveau de la session sont limitées à 100 000 caractères au total.

La variable de template {conversation}

À la granularité de session, {conversation} est une variable de template spéciale qui se rend sous forme de tableau JSON de tours {input, output} sur tous les traces de la session, construit à partir de attributes.input.value / attributes.llm.input_messages (côté entrée) et attributes.output.value / attributes.llm.output_messages (côté sortie).

À la granularité de span ou de trace, {conversation} est traité comme une variable de template régulière et résolu via les mappages de colonnes comme n'importe quel autre.

Tâches multi-évaluateurs

Une tâche peut contenir des évaluateurs de granularités différentes. À l'exécution, le système utilise la granularité la plus élevée (session > trace > span) pour la récupération de données et se divise automatiquement en une exécution enfant par évaluateur. Le query_filter par évaluateur dans le JSON des évaluateurs de la tâche affine davantage les spans inclus (p. ex., uniquement les spans d'appels d'outils dans une session).

CRUD basique

Intégrations IA

Les intégrations IA stockent les identifiants de fournisseur LLM que l'évaluateur utilise. Pour le CRUD complet — énumération, création pour tous les fournisseurs (OpenAI, Anthropic, Azure, Bedrock, Vertex, Gemini, NVIDIA NIM, personnalisé), mise à jour et suppression — utilisez le skill arize-ai-provider-integration.

Référence rapide pour le cas courant (OpenAI) :

# Vérifiez d'abord l'existence d'une intégration
ax ai-integrations list --space-id SPACE_ID

# Créez-en une si aucune n'existe
ax ai-integrations create \
  --name "My OpenAI Integration" \
  --provider openAI \
  --api-key $OPENAI_API_KEY

Copiez l'ID d'intégration renvoyé — il est obligatoire pour ax evaluators create --ai-integration-id.

Évaluateurs

# Énumérer / Obtenir
ax evaluators list --space-id SPACE_ID
ax evaluators get EVALUATOR_ID
ax evaluators list-versions EVALUATOR_ID
ax evaluators get-version VERSION_ID

# Créer (crée l'évaluateur et sa première version)
ax evaluators create \
  --name "Answer Correctness" \
  --space-id SPACE_ID \
  --description "Judges if the model answer is correct" \
  --template-name "correctness" \
  --commit-message "Initial version" \
  --ai-integration-id INT_ID \
  --model-name "gpt-4o" \
  --include-explanations \
  --use-function-calling \
  --classification-choices '{"correct": 1, "incorrect": 0}' \
  --template 'You are an evaluator. Given the user question and the model response, decide if the response correctly answers the question.

User question: {input}

Model response: {output}

Respond with exactly one of these labels: correct, incorrect'

# Créer une nouvelle version (pour les modifications de prompt ou de modèle — les versions sont immuables)
ax evaluators create-version EVALUATOR_ID \
  --commit-message "Added context grounding" \
  --template-name "correctness" \
  --ai-integration-id INT_ID \
  --model-name "gpt-4o" \
  --include-explanations \
  --classification-choices '{"correct": 1, "incorrect": 0}' \
  --template 'Updated prompt...

{input} / {output} / {context}'

# Mettre à jour les métadonnées uniquement (nom, description — pas le prompt)
ax evaluators update EVALUATOR_ID \
  --name "New Name" \
  --description "Updated description"

# Supprimer (permanent — supprime toutes les versions)
ax evaluators delete EVALUATOR_ID

Flags clés pour create :

Tâches

# Énumérer / Obtenir
ax tasks list --space-id SPACE_ID
ax tasks list --project-id PROJ_ID
ax tasks list --dataset-id DATASET_ID
ax tasks get TASK_ID

# Créer (projet — continu)
ax tasks create \
  --name "Correctness Monitor" \
  --task-type template_evaluation \
  --project-id PROJ_ID \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --is-continuous \
  --sampling-rate 0.1

# Créer (projet — une seule fois / backfill)
ax tasks create \
  --name "Correctness Backfill" \
  --task-type template_evaluation \
  --project-id PROJ_ID \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --no-continuous

# Créer (expérience / dataset)
ax tasks create \
  --name "Experiment Scoring" \
  --task-type template_evaluation \
  --dataset-id DATASET_ID \
  --experiment-ids "EXP_ID_1,EXP_ID_2" \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"output": "output"}}]' \
  --no-continuous

# Déclencher une exécution (tâche de projet — utiliser la fenêtre de données)
ax tasks trigger-run TASK_ID \
  --data-start-time "2026-03-20T00:00:00" \
  --data-end-time "2026-03-21T23:59:59" \
  --wait

# Déclencher une exécution (tâche d'expérience — utiliser les ID d'expérience)
ax tasks trigger-run TASK_ID \
  --experiment-ids "EXP_ID_1" \
  --wait

# Surveiller
ax tasks list-runs TASK_ID
ax tasks get-run RUN_ID
ax tasks wait-for-run RUN_ID --timeout 300
ax tasks cancel-run RUN_ID --force

Format de temps pour trigger-run : 2026-03-21T09:00:00 — pas de Z à la fin.

Flags supplémentaires pour trigger-run :

Guide de statut d'exécution :

Workflow A : Créer un évaluateur pour un projet

À utiliser quand l'utilisateur dit quelque chose comme "create an evaluator for my Playground Traces project".

Étape 1 : Résoudre le nom du projet en ID

ax spans export nécessite un ID de projet, pas un nom — passer un nom provoque une erreur de validation. Recherchez toujours l'ID en premier :

ax projects list --space-id SPACE_ID -o json

Trouvez l'entrée dont le "name" correspond (insensible à la casse). Copiez son "id" (une chaîne base64).

Étape 2 : Comprendre ce qu'il faut évaluer

Si l'utilisateur a spécifié le type d'évaluateur (hallucination, correction, pertinence, etc.) → passez à l'étape 3.

Si non, échantillonnez les spans récents pour baser l'évaluateur sur des données réelles :

ax spans export PROJECT_ID --space-id SPACE_ID -l 10 --days 30 --stdout

Inspectez attributes.input, attributes.output, les types de span et les annotations existantes. Identifiez les modes d'échec (p. ex. faits hallucination, réponses hors sujet, contexte manquant) et proposez 1–3 idées d'évaluateur concrètes. Laissez l'utilisateur choisir.

Chaque suggestion doit inclure : le nom de l'évaluateur (gras), une description d'une phrase de ce qu'il juge, et la paire d'étiquettes binaires entre parenthèses. Formatez chacun comme :

1. Nom — Description de ce qui est jugé. (étiquette_a / étiquette_b)

Exemple :

1. Response Correctness — Does the agent's response correctly address the user's financial query? (correct / incorrect)
2. Hallucination — Does the response fabricate facts not grounded in retrieved context? (factual / hallucinated)

Étape 3 : Confirmer ou créer une intégration IA

ax ai-integrations list --space-id SPACE_ID -o json

Si une intégration appropriée existe, notez son ID. Si non, créez-en une en utilisant le skill arize-ai-provider-integration. Demandez à l'utilisateur quel fournisseur/modèle il souhaite pour le juge.

Étape 4 : Créer l'évaluateur

Utilisez les meilleures pratiques de conception de template ci-dessous. Gardez le nom de l'évaluateur et les variables génériques — la tâche (étape 6) gère le câblage spécifique au projet via column_mappings.

ax evaluators create \
  --name "Hallucination" \
  --space-id SPACE_ID \
  --template-name "hallucination" \
  --commit-message "Initial version" \
  --ai-integration-id INT_ID \
  --model-name "gpt-4o" \
  --include-explanations \
  --use-function-calling \
  --classification-choices '{"factual": 1, "hallucinated": 0}' \
  --template 'You are an evaluator. Given the user question and the model response, decide if the response is factual or contains unsupported claims.

User question: {input}

Model response: {output}

Respond with exactly one of these labels: hallucinated, factual'

Étape 5 : Demander — backfill, continu ou les deux ?

Avant de créer la tâche, demandez :

"Would you like to: (a) Run a backfill on historical spans (one-time)? (b) Set up continuous evaluation on new spans going forward? (c) Both — backfill now and keep scoring new spans automatically?"

Étape 6 : Déterminer les mappages de colonnes à partir de données de span réels

Ne devinez pas les chemins. Tirez un échantillon et inspectez les champs réellement présents :

ax spans export PROJECT_ID --space-id SPACE_ID -l 5 --days 7 --stdout

Pour chaque variable de template ({input}, {output}, {context}), trouvez le chemin JSON correspondant. Points de départ courants — vérifiez toujours sur vos données réelles avant d'utiliser :

Valider l'alignement du type de span : Si le prompt de l'évaluateur suppose du texte final LLM mais la tâche cible des spans CHAIN (ou vice versa), les exécutions peuvent être annulées ou évaluer le mauvais texte. Assurez-vous que le query_filter sur la tâche correspond au type de span que vous avez mappé.

Exemple complet de JSON --evaluators :

[
  {
    "evaluator_id": "EVAL_ID",
    "query_filter": "span_kind = 'LLM'",
    "column_mappings": {
      "input": "attributes.input.value",
      "output": "attributes.llm.output_messages.0.message.content",
      "context": "attributes.retrieval.documents.contents"
    }
  }
]

Incluez un mappage pour chaque variable que le template référence. Ommettre un entraîne les exécutions à ne produire aucun score valide.

Étape 7 : Créer la tâche

Backfill uniquement (a) :

ax tasks create \
  --name "Hallucination Backfill" \
  --task-type template_evaluation \
  --project-id PROJECT_ID \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --no-continuous

Continu uniquement (b) :

ax tasks create \
  --name "Hallucination Monitor" \
  --task-type template_evaluation \
  --project-id PROJECT_ID \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --is-continuous \
  --sampling-rate 0.1

Les deux (c) : Utilisez --is-continuous à la création, puis déclenchez également une exécution de backfill à l'étape 8.

Étape 8 : Déclencher une exécution de backfill (si demandé)

D'abord trouvez la plage horaire qui a des données :

ax spans export PROJECT_ID --space-id SPACE_ID -l 100 --days 1 --stdout   # essayez d'abord les dernières 24h
ax spans export PROJECT_ID --space-id SPACE_ID -l 100 --days 7 --stdout   # élargissez si vide

Utilisez les champs start_time / end_time des spans réels pour définir la fenêtre. Utilisez les données les plus récentes pour votre première exécution de test.

ax tasks trigger-run TASK_ID \
  --data-start-time "2026-03-20T00:00:00" \
  --data-end-time "2026-03-21T23:59:59" \
  --wait

Workflow B : Créer un évaluateur pour une expérience

À utiliser quand l'utilisateur dit quelque chose comme "create an evaluator for my experiment" ou "evaluate my dataset runs".

Si l'utilisateur dit "dataset" mais n'a pas d'expérience : Une tâche doit cibler une expérience (pas un dataset nu). Demandez :

"Evaluation tasks run against experiment runs, not datasets directly. Would you like help creating an experiment on that dataset first?"

Si oui, utilisez le skill arize-experiment pour en créer un, puis revenez ici.

Étape 1 : Résoudre le dataset et l'expérience

ax datasets list --space-id SPACE_ID -o json
ax experiments list --dataset-id DATASET_ID -o json

Notez l'ID du dataset et l'ID ou les IDs d'expérience à évaluer.

Étape 2 : Comprendre ce qu'il faut évaluer

Si l'utilisateur a spécifié le type d'évaluateur → passez à l'étape 3.

Si non, inspectez une exécution d'expérience récente pour baser l'évaluateur sur des données réelles :

ax experiments export EXPERIMENT_ID --stdout | python3 -c "import sys,json; runs=json.load(sys.stdin); print(json.dumps(runs[0], indent=2))"

Regardez les champs output, input, evaluations et metadata. Identifiez les lacunes (métriques que l'utilisateur se soucie mais n'a pas encore) et proposez 1–3 idées d'évaluateur. Chaque suggestion doit inclure : le nom de l'évaluateur (gras), une description d'une phrase et la paire d'étiquettes binaires entre parenthèses — même format que Workflow A, étape 2.

Étape 3 : Confirmer ou créer une intégration IA

Même que Workflow A, étape 3.

Étape 4 : Créer l'évaluateur

Même que Workflow A, étape 4. Gardez les variables génériques.

Étape 5 : Déterminer les mappages de colonnes à partir de données d'exécution réelles

La forme des données d'exécution diffère des données de span. Inspectez :

ax experiments export EXPERIMENT_ID --stdout | python3 -c "import sys,json; runs=json.load(sys.stdin); print(json.dumps(runs[0], indent=2))"

Mappage courant pour les exécutions d'expérience :

• output → "output" (champ au niveau supérieur sur chaque exécution)
• input → vérifiez s'il est sur l'exécution ou intégré dans les exemples du dataset lié

Si input n'est pas sur le JSON d'exécution, exportez les exemples du dataset pour trouver le chemin :

ax datasets export DATASET_ID --stdout | python3 -c "import sys,json; ex=json.load(sys.stdin); print(json.dumps(ex[0], indent=2))"

Étape 6 : Créer la tâche

ax tasks create \
  --name "Experiment Correctness" \
  --task-type template_evaluation \
  --dataset-id DATASET_ID \
  --experiment-ids "EXP_ID" \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"output": "output"}}]' \
  --no-continuous

Étape 7 : Déclencher et surveiller

ax tasks trigger-run TASK_ID \
  --experiment-ids "EXP_ID" \
  --wait

ax tasks list-runs TASK_ID
ax tasks get-run RUN_ID

Meilleures pratiques pour la conception de template

1. Utiliser des noms de variables génériques et portables

Utilisez {input}, {output} et {context} — pas des noms liés à un projet ou attribut de span spécifique (p. ex. ne pas utiliser {attributes_input_value}). L'évaluateur lui-même reste abstrait ; le column_mappings de la tâche est l'endroit où vous le câblez aux champs réels dans un projet ou expérience spécifique. Cela permet au même évaluateur de s'exécuter sur plusieurs projets et expériences sans modification.

2. Utiliser par défaut des étiquettes binaires

Utilisez exactement deux étiquettes de chaîne claires (p. ex. hallucinated / factual, correct / incorrect, pass / fail). Les étiquettes binaires sont :

• Les plus faciles pour le modèle juge à produire de façon cohérente
• Les plus courantes dans l'industrie
• Les plus simples à interpréter dans les tableaux de bord

Si l'utilisateur insiste pour plus de deux choix, c'est bien — mais recommandez d'abord le binaire et expliquez le compromis (plus d'étiquettes → plus d'ambiguïté → fiabilité inter-évaluateurs inférieure).

3. Soyez explicite sur ce que le modèle doit retourner

Le template doit dire au modèle juge de répondre avec uniquement la chaîne d'étiquette — rien d'autre. Les chaînes d'étiquette dans le prompt doivent correspondre exactement aux étiquettes dans --classification-choices (même orthographe, même casse).

Bien :

Respond with exactly one of these labels: hallucinated, factual

Mauvais (trop ouvert) :

Is this hallucinated? Answer yes or no.

4. Garder la température basse

Passez --invocation-params '{"temperature": 0}' pour un score reproductible. Des températures plus élevées introduisent du bruit dans les résultats d'évaluation.

5. Utiliser --include-explanations pour le débogage

Lors de la configuration initiale, toujours inclure les explications afin que vous puissiez vérifier que le juge raisonne correctement avant de faire confiance aux étiquettes à l'échelle.

6. Passer le template entre guillemets simples dans bash

Les guillemets simples empêchent le shell d'interpoler les placeholders {variable}. Les guillemets doubles poseront problème :

# Correct
--template 'Judge this: {input} → {output}'

# Mauvais — le shell peut interpréter { } ou échouer
--template "Judge this: {input} → {output}"

7. Toujours définir --classification-choices pour correspondre à vos étiquettes de template

Les étiquettes dans --classification-choices doivent correspondre exactement aux étiquettes référencées dans --template (même orthographe, même casse). Ommettre --classification-choices provoque l'échec des exécutions de tâche avec "missing rails and classification choices."

Dépannage

Skills associés

• arize-ai-provider-integration: CRUD complet pour les intégrations de fournisseur LLM (créer, mettre à jour, supprimer les identifiants)
• arize-trace: Exportez les spans pour découvrir les chemins de colonne et les plages horaires
• arize-experiment: Créer des expériences et exporter des exécutions pour les mappages de colonnes d'expérience
• arize-dataset: Exportez les exemples du dataset pour trouver les champs d'entrée quand les exécutions les omettent
• arize-link: Liens profonds vers les évaluateurs et les tâches dans l'IU Arize

Enregistrer les identifiants pour une utilisation future

Voir references/ax-profiles.md § Save Credentials for Future Use.