Skill Expérience Arize

Concepts

• Experiment = une exécution d'évaluation nommée contre une version spécifique de dataset, contenant un run par exemple
• Experiment Run = le résultat du traitement d'un exemple du dataset -- inclut la sortie du modèle, les évaluations optionnelles et les métadonnées optionnelles
• Dataset = une collection versionnée d'exemples ; chaque experiment est lié à un dataset et à une version spécifique du dataset
• Evaluation = une métrique nommée attachée à un run (par ex. correctness, relevance), avec étiquette optionnelle, score et explication

Le flux typique : exporter un dataset → traiter chaque exemple → collecter les sorties et évaluations → créer un experiment avec les runs.

Prérequis

Procédez directement à la tâche — exécutez la commande ax dont vous avez besoin. NE vérifiez PAS les versions, variables d'env, ou profils en amont.

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 absent ou la clé API est incorrecte : 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
• Project flou → vérifiez .env pour ARIZE_DEFAULT_PROJECT, ou demandez, ou exécutez ax projects list -o json --limit 100 et présentez comme options sélectionnables

Lister les Experiments : ax experiments list

Parcourez les experiments, optionnellement filtrés par dataset. La sortie va vers stdout.

ax experiments list
ax experiments list --dataset-id DATASET_ID --limit 20
ax experiments list --cursor CURSOR_TOKEN
ax experiments list -o json

Flags

Obtenir un Experiment : ax experiments get

Recherche rapide de métadonnées -- retourne le nom de l'experiment, le dataset/version lié, et les horodatages.

ax experiments get EXPERIMENT_ID
ax experiments get EXPERIMENT_ID -o json

Flags

Champs de réponse

Exporter un Experiment : ax experiments export

Téléchargez tous les runs dans un fichier. Par défaut utilise l'API REST ; passez --all pour utiliser Arrow Flight pour le transfert en masse.

ax experiments export EXPERIMENT_ID
# -> experiment_abc123_20260305_141500/runs.json

ax experiments export EXPERIMENT_ID --all
ax experiments export EXPERIMENT_ID --output-dir ./results
ax experiments export EXPERIMENT_ID --stdout
ax experiments export EXPERIMENT_ID --stdout | jq '.[0]'

Flags

REST vs Flight (--all)

• REST (défaut) : Friction faible -- pas de dépendance Arrow/Flight, ports HTTPS standards, fonctionne à travers n'importe quel proxy d'entreprise ou pare-feu. Limité à 500 runs par page.
• Flight (--all) : Requis pour les experiments avec plus de 500 runs. Utilise gRPC+TLS sur un hôte/port séparé (flight.arize.com:443) que certains réseaux d'entreprise peuvent bloquer.

Règle d'escalade auto-agent : Si un export REST retourne exactement 500 runs, le résultat est probablement tronqué. Réexécutez avec --all pour obtenir le dataset complet.

La sortie est un tableau JSON d'objets run :

[
  {
    "id": "run_001",
    "example_id": "ex_001",
    "output": "The answer is 4.",
    "evaluations": {
      "correctness": { "label": "correct", "score": 1.0 },
      "relevance": { "score": 0.95, "explanation": "Directly answers the question" }
    },
    "metadata": { "model": "gpt-4o", "latency_ms": 1234 }
  }
]

Créer un Experiment : ax experiments create

Créez un nouvel experiment avec des runs à partir d'un fichier de données.

ax experiments create --name "gpt-4o-baseline" --dataset-id DATASET_ID --file runs.json
ax experiments create --name "claude-test" --dataset-id DATASET_ID --file runs.csv

Flags

Passer des données via stdin

Utilisez --file - pour piloter les données directement -- pas de fichier temporaire nécessaire :

echo '[{"example_id": "ex_001", "output": "Paris"}]' | ax experiments create --name "my-experiment" --dataset-id DATASET_ID --file -

# Ou avec un heredoc
ax experiments create --name "my-experiment" --dataset-id DATASET_ID --file - << 'EOF'
[{"example_id": "ex_001", "output": "Paris"}]
EOF

Colonnes requises dans le fichier runs

Les colonnes supplémentaires sont transmises comme additionalProperties sur le run.

Supprimer un Experiment : ax experiments delete

ax experiments delete EXPERIMENT_ID
ax experiments delete EXPERIMENT_ID --force   # ignorer l'invite de confirmation

Flags

Schéma Experiment Run

Chaque run correspond à un exemple du dataset :

{
  "example_id": "required -- liens vers l'exemple du dataset",
  "output": "required -- la sortie du modèle/système pour cet exemple",
  "evaluations": {
    "metric_name": {
      "label": "optional string label (e.g., 'correct', 'incorrect')",
      "score": "optional numeric score (e.g., 0.95)",
      "explanation": "optional freeform text"
    }
  },
  "metadata": {
    "model": "gpt-4o",
    "temperature": 0.7,
    "latency_ms": 1234
  }
}

Champs d'évaluation

Au moins l'un de label, score, ou explanation devrait être présent par évaluation.

Workflows

Exécuter un experiment contre un dataset

1. Trouvez ou créez un dataset :

   ax datasets list
   ax datasets export DATASET_ID --stdout | jq 'length'

2. Exportez les exemples du dataset :

   ax datasets export DATASET_ID

3. Traitez chaque exemple à travers votre système, en collectant les sorties et évaluations
4. Construisez un fichier runs (tableau JSON) avec example_id, output, et evaluations optionnelles :

   [
     {"example_id": "ex_001", "output": "4", "evaluations": {"correctness": {"label": "correct", "score": 1.0}}},
     {"example_id": "ex_002", "output": "Paris", "evaluations": {"correctness": {"label": "correct", "score": 1.0}}}
   ]

5. Créez l'experiment :

   ax experiments create --name "gpt-4o-baseline" --dataset-id DATASET_ID --file runs.json

6. Vérifiez : ax experiments get EXPERIMENT_ID

Comparer deux experiments

1. Exportez les deux experiments :

   ax experiments export EXPERIMENT_ID_A --stdout > a.json
   ax experiments export EXPERIMENT_ID_B --stdout > b.json

2. Comparez les scores d'évaluation par example_id :

   # Score correctness moyen pour l'experiment A
   jq '[.[] | .evaluations.correctness.score] | add / length' a.json
   
   # Idem pour l'experiment B
   jq '[.[] | .evaluations.correctness.score] | add / length' b.json

3. Trouvez les exemples où les résultats diffèrent :

   jq -s '.[0] as $a | .[1][] | . as $run |
     {
       example_id: $run.example_id,
       b_score: $run.evaluations.correctness.score,
       a_score: ($a[] | select(.example_id == $run.example_id) | .evaluations.correctness.score)
     }' a.json b.json

4. Distribution des scores par évaluateur (comptages pass/fail/partial) :

   # Comptage par label pour l'experiment A
   jq '[.[] | .evaluations.correctness.label] | group_by(.) | map({label: .[0], count: length})' a.json

5. Trouvez les régressions (exemples qui réussissaient en A mais échouent en B) :

   jq -s '
     [.[0][] | select(.evaluations.correctness.label == "correct")] as $passed_a |
     [.[1][] | select(.evaluations.correctness.label != "correct") |
       select(.example_id as $id | $passed_a | any(.example_id == $id))
     ]
   ' a.json b.json

Note sur la signification statistique : Les comparaisons de scores sont les plus fiables avec ≥ 30 exemples par évaluateur. Avec moins d'exemples, traitez le delta comme directionnel uniquement -- une différence de 5% sur n=10 peut être du bruit. Rapportez la taille de l'échantillon aux côtés des scores : jq 'length' a.json.

Télécharger les résultats de l'experiment pour l'analyse

1. ax experiments list --dataset-id DATASET_ID -- trouvez les experiments
2. ax experiments export EXPERIMENT_ID -- téléchargez dans un fichier
3. Analysez : jq '.[] | {example_id, score: .evaluations.correctness.score}' experiment_*/runs.json

Piloter l'export vers d'autres outils

# Compter les runs
ax experiments export EXPERIMENT_ID --stdout | jq 'length'

# Extraire tous les outputs
ax experiments export EXPERIMENT_ID --stdout | jq '.[].output'

# Obtenir les runs avec des scores faibles
ax experiments export EXPERIMENT_ID --stdout | jq '[.[] | select(.evaluations.correctness.score < 0.5)]'

# Convertir en CSV
ax experiments export EXPERIMENT_ID --stdout | jq -r '.[] | [.example_id, .output, .evaluations.correctness.score] | @csv'

Skills Associées

• arize-dataset : Créez ou exportez le dataset contre lequel cet experiment s'exécute → utilisez arize-dataset en premier
• arize-prompt-optimization : Utilisez les résultats de l'experiment pour améliorer les prompts → l'étape suivante est arize-prompt-optimization
• arize-trace : Inspectez les traces de spans individuelles pour les runs d'experiment échoués → utilisez arize-trace
• arize-link : Générez des liens UI cliquables vers les traces depuis les runs d'experiment → utilisez arize-link

Dépannage

Enregistrer les Identifiants pour Utilisation Future

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