Skill d'Annotation Arize

Ce skill se concentre sur les configs d'annotation — le schéma pour les retours humains — et sur l'annotation programmatique des spans de projet via le SDK Python. L'examen humain dans l'interface Arize (incluant les files d'annotation, les datasets et les expériences) dépend toujours de ces configs ; il n'existe pas encore de CLI ax pour les files.

Direction : L'étiquetage humain dans Arize attache les valeurs définies par les configs aux spans, exemples de dataset, enregistrements liés aux expériences et éléments de file dans l'interface du produit. Ce qui est documenté ici : ax annotation-configs et les mises à jour de spans en masse avec ArizeClient.spans.update_annotations.

Prérequis

Procédez directement à la tâche — exécutez la commande ax dont vous avez besoin. Ne vérifiez PAS les versions, les variables d'environnement ou les 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 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 de clé non plus, 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

Concepts

Qu'est-ce qu'une Config d'Annotation ?

Une config d'annotation définit le schéma pour un seul type de label de retour humain. Avant que quiconque puisse annoter un span, un enregistrement de dataset, une sortie d'expérience ou un élément de file, une config doit exister pour ce label dans le space.

Où les labels sont appliqués (surfaces)

Assurez-vous toujours que la config d'annotation pertinente existe dans le space avant de vous attendre à ce que les labels persistent.

CRUD de base : Configs d'Annotation

List

ax annotation-configs list --space-id SPACE_ID
ax annotation-configs list --space-id SPACE_ID -o json
ax annotation-configs list --space-id SPACE_ID --limit 20

Create — Categorical

Les configs categorical présentent un ensemble fixe de labels parmi lesquels les relecteurs peuvent choisir.

ax annotation-configs create \
  --name "Correctness" \
  --space-id SPACE_ID \
  --type categorical \
  --values '[{"label": "correct", "score": 1}, {"label": "incorrect", "score": 0}]' \
  --optimization-direction maximize

Paires de labels binaires courantes :

• correct / incorrect
• helpful / unhelpful
• safe / unsafe
• relevant / irrelevant
• pass / fail

Create — Continuous

Les configs continuous permettent aux relecteurs d'entrer un score numérique dans une plage définie.

ax annotation-configs create \
  --name "Quality Score" \
  --space-id SPACE_ID \
  --type continuous \
  --minimum-score 0 \
  --maximum-score 10 \
  --optimization-direction maximize

Create — Freeform

Les configs freeform collectent des retours textuels ouverts. Aucun flag supplémentaire n'est nécessaire au-delà du nom, du space et du type.

ax annotation-configs create \
  --name "Reviewer Notes" \
  --space-id SPACE_ID \
  --type freeform

Get

ax annotation-configs get ANNOTATION_CONFIG_ID
ax annotation-configs get ANNOTATION_CONFIG_ID -o json

Delete

ax annotation-configs delete ANNOTATION_CONFIG_ID
ax annotation-configs delete ANNOTATION_CONFIG_ID --force   # ignorer la confirmation

Note : La suppression est irréversible. Toutes les associations de files d'annotation à cette config sont également supprimées dans le produit (les files peuvent subsister ; corriger les associations dans l'interface Arize si nécessaire).

Application d'Annotations aux Spans (SDK Python)

Utilisez le SDK Python pour appliquer en masse des annotations aux project spans quand vous avez déjà des labels (par ex. à partir d'une export de review ou d'un outil d'étiquetage externe).

import pandas as pd
from arize import ArizeClient

import os

client = ArizeClient(api_key=os.environ["ARIZE_API_KEY"])

# Construire un DataFrame avec des colonnes d'annotation
# Requis : context.span_id + au moins une annotation.<name>.label ou annotation.<name>.score
annotations_df = pd.DataFrame([
    {
        "context.span_id": "span_001",
        "annotation.Correctness.label": "correct",
        "annotation.Correctness.updated_by": "reviewer@example.com",
    },
    {
        "context.span_id": "span_002",
        "annotation.Correctness.label": "incorrect",
        "annotation.Correctness.updated_by": "reviewer@example.com",
    },
])

response = client.spans.update_annotations(
    space_id=os.environ["ARIZE_SPACE_ID"],
    project_name="your-project",
    dataframe=annotations_df,
    validate=True,
)

Schéma de colonne DataFrame :

Limitation : Les annotations s'appliquent uniquement aux spans dans les 31 jours avant la soumission.

Dépannage

Skills Connexes

• arize-trace : Exporter les spans pour trouver les IDs de span et les plages temporelles
• arize-dataset : Trouver les IDs de dataset et les IDs d'exemple
• arize-evaluator : LLM automatisé en tant que juge aux côtés de l'annotation humaine
• arize-experiment : Expériences liées aux datasets et workflows d'évaluation
• arize-link : Liens profonds vers les configs d'annotation et les files dans l'interface Arize

Enregistrer les Credentials pour une Utilisation Future

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