Compétence Dataset Arize

Concepts

• Dataset = une collection versionnée d'exemples utilisés pour l'évaluation et l'expérimentation
• Dataset Version = un snapshot d'un dataset à un moment donné ; les mises à jour peuvent être in-place ou créer une nouvelle version
• Example = un seul enregistrement dans un dataset avec des champs arbitraires définis par l'utilisateur (par ex. question, answer, context)
• Space = un conteneur organisationnel ; les datasets appartiennent à un space

Les champs gérés par le système sur les exemples (id, created_at, updated_at) sont auto-générés par le serveur -- ne les incluez jamais dans les payloads de création ou d'ajout.

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 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 Datasets : ax datasets list

Parcourez les datasets dans un space. La sortie va vers stdout.

ax datasets list
ax datasets list --space-id SPACE_ID --limit 20
ax datasets list --cursor CURSOR_TOKEN
ax datasets list -o json

Flags

Obtenir un Dataset : ax datasets get

Recherche rapide de métadonnées -- retourne le nom du dataset, le space, les timestamps et la liste des versions.

ax datasets get DATASET_ID
ax datasets get DATASET_ID -o json

Flags

Champs de réponse

Exporter un Dataset : ax datasets export

Téléchargez tous les exemples dans un fichier. Utilisez --all pour les datasets plus grands que 500 exemples (export en masse illimité).

ax datasets export DATASET_ID
# -> dataset_abc123_20260305_141500/examples.json

ax datasets export DATASET_ID --all
ax datasets export DATASET_ID --version-id VERSION_ID
ax datasets export DATASET_ID --output-dir ./data
ax datasets export DATASET_ID --stdout
ax datasets export DATASET_ID --stdout | jq '.[0]'

Flags

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

Vérification de complétude d'export : Après exportation, confirmez que le nombre de lignes correspond à celui signalé par le serveur :

# Obtenir le nombre signalé par le serveur depuis les métadonnées du dataset
ax datasets get DATASET_ID -o json | jq '.versions[-1] | {version: .id, examples: .example_count}'

# Comparer à ce qui a été exporté
jq 'length' dataset_*/examples.json

# Si les nombres diffèrent, réexportez avec --all

La sortie est un array JSON d'objets exemples. Chaque exemple a des champs système (id, created_at, updated_at) plus tous les champs définis par l'utilisateur :

[
  {
    "id": "ex_001",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z",
    "question": "What is 2+2?",
    "answer": "4",
    "topic": "math"
  }
]

Créer un Dataset : ax datasets create

Créez un nouveau dataset à partir d'un fichier de données.

ax datasets create --name "My Dataset" --space-id SPACE_ID --file data.csv
ax datasets create --name "My Dataset" --space-id SPACE_ID --file data.json
ax datasets create --name "My Dataset" --space-id SPACE_ID --file data.jsonl
ax datasets create --name "My Dataset" --space-id SPACE_ID --file data.parquet

Flags

Passer des données via stdin

Utilisez --file - pour piper les données directement -- pas besoin de fichier temporaire :

echo '[{"question": "What is 2+2?", "answer": "4"}]' | ax datasets create --name "my-dataset" --space-id SPACE_ID --file -

# Ou avec un heredoc
ax datasets create --name "my-dataset" --space-id SPACE_ID --file - << 'EOF'
[{"question": "What is 2+2?", "answer": "4"}]
EOF

Pour ajouter des lignes à un dataset existant, utilisez ax datasets append --json '[...]' à la place -- pas besoin de fichier.

Formats de fichier supportés

Pièges de format :

• CSV : Perd les informations de type -- les dates deviennent des strings, null devient une string vide. Utilisez JSON/Parquet pour préserver les types.
• JSONL : Chaque ligne est un objet JSON séparé. Un array JSON ([{...}, {...}]) dans un fichier .jsonl échouera -- utilisez l'extension .json à la place.
• Parquet : Préserve les types de colonne. Requiert pandas/pyarrow pour lire localement : pd.read_parquet("examples.parquet").

Ajouter des Exemples : ax datasets append

Ajoutez des exemples à un dataset existant. Deux modes d'entrée -- utilisez celui qui convient.

JSON inline (agent-friendly)

Générez le payload directement -- pas besoin de fichiers temporaires :

ax datasets append DATASET_ID --json '[{"question": "What is 2+2?", "answer": "4"}]'

ax datasets append DATASET_ID --json '[
  {"question": "What is gravity?", "answer": "A fundamental force..."},
  {"question": "What is light?", "answer": "Electromagnetic radiation..."}
]'

Depuis un fichier

ax datasets append DATASET_ID --file new_examples.csv
ax datasets append DATASET_ID --file additions.json

Vers une version spécifique

ax datasets append DATASET_ID --json '[{"q": "..."}]' --version-id VERSION_ID

Flags

Exactement l'un de --json ou --file est requis.

Validation

• Chaque exemple doit être un objet JSON avec au moins un champ défini par l'utilisateur
• Maximum 100 000 exemples par demande

Validation de schéma avant ajout : Si le dataset a déjà des exemples, inspectez son schéma avant d'ajouter pour éviter les décalages de champs silencieux :

# Vérifier les noms de champs existants dans le dataset
ax datasets export DATASET_ID --stdout | jq '.[0] | keys'

# Vérifier que vos nouvelles données ont des noms de champs correspondants
echo '[{"question": "..."}]' | jq '.[0] | keys'

# Les deux sorties doivent montrer les mêmes champs définis par l'utilisateur

Les champs sont free-form : les champs supplémentaires dans les nouveaux exemples sont ajoutés, et les champs manquants deviennent null. Cependant, les fautes de frappe dans les noms de champs (par ex. queston vs question) créent silencieusement de nouvelles colonnes -- vérifiez l'orthographe avant d'ajouter.

Supprimer un Dataset : ax datasets delete

ax datasets delete DATASET_ID
ax datasets delete DATASET_ID --force   # sauter le prompt de confirmation

Flags

Workflows

Trouver un dataset par nom

Les utilisateurs font souvent référence aux datasets par nom plutôt que par ID. Résolvez un nom en ID avant d'exécuter d'autres commandes :

# Trouver l'ID du dataset par nom
ax datasets list -o json | jq '.[] | select(.name == "eval-set-v1") | .id'

# Si la liste est paginée, récupérez plus
ax datasets list -o json --limit 100 | jq '.[] | select(.name | test("eval-set")) | {id, name}'

Créer un dataset à partir d'un fichier pour l'évaluation

1. Préparez un fichier CSV/JSON/Parquet avec vos colonnes d'évaluation (par ex. input, expected_output)
   • Si vous générez des données inline, pilez-les via stdin en utilisant --file - (voir la section Create Dataset)
2. ax datasets create --name "eval-set-v1" --space-id SPACE_ID --file eval_data.csv
3. Vérifiez : ax datasets get DATASET_ID
4. Utilisez l'ID du dataset pour exécuter des expériences

Ajouter des exemples à un dataset existant

# Trouver le dataset
ax datasets list

# Ajouter inline ou depuis un fichier (voir la section Append Examples pour la syntaxe complète)
ax datasets append DATASET_ID --json '[{"question": "...", "answer": "..."}]'
ax datasets append DATASET_ID --file additional_examples.csv

Télécharger un dataset pour une analyse hors ligne

1. ax datasets list -- trouver le dataset
2. ax datasets export DATASET_ID -- télécharger vers fichier
3. Parser le JSON : jq '.[] | .question' dataset_*/examples.json

Exporter une version spécifique

# Lister les versions
ax datasets get DATASET_ID -o json | jq '.versions'

# Exporter cette version
ax datasets export DATASET_ID --version-id VERSION_ID

Itérer sur un dataset

1. Exporter la version actuelle : ax datasets export DATASET_ID
2. Modifier les exemples localement
3. Ajouter de nouvelles lignes : ax datasets append DATASET_ID --file new_rows.csv
4. Ou créer une nouvelle version : ax datasets create --name "eval-set-v2" --space-id SPACE_ID --file updated_data.json

Pipe export vers d'autres outils

# Compter les exemples
ax datasets export DATASET_ID --stdout | jq 'length'

# Extraire un seul champ
ax datasets export DATASET_ID --stdout | jq '.[].question'

# Convertir en CSV avec jq
ax datasets export DATASET_ID --stdout | jq -r '.[] | [.question, .answer] | @csv'

Schéma d'Exemple de Dataset

Les exemples sont des objets JSON free-form. Il n'y a pas de schéma fixe -- les colonnes sont quels que soient les champs que vous fournissez. Les champs gérés par le système sont ajoutés par le serveur :

Compétences Liées

• arize-trace : Exporter les spans de production pour comprendre quelles données mettre dans les datasets → utilisez arize-trace
• arize-experiment : Exécuter des évaluations contre ce dataset → prochaine étape est arize-experiment
• arize-prompt-optimization : Utiliser dataset + résultats d'expériences pour améliorer les prompts → utilisez arize-prompt-optimization

Dépannage

Enregistrer les Credentials pour une Utilisation Future

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