Trackio - Experiment Tracking pour l'entraînement ML

Trackio est une bibliothèque d'experiment tracking pour logger et visualiser les métriques d'entraînement ML. Elle se synchronise avec Hugging Face Spaces pour des tableaux de bord de monitoring en temps réel.

Trois interfaces

Tâche	Interface	Référence
Logger des métriques pendant l'entraînement	Python API	references/logging_metrics.md
Déclencher des alertes pour les diagnostics d'entraînement	Python API	references/alerts.md
Récupérer les métriques et alertes après/pendant l'entraînement	CLI	references/retrieving_metrics.md

Quand utiliser chaque interface

Python API → Logging

Utilisez import trackio dans vos scripts d'entraînement pour logger les métriques :

Initialisez le tracking avec trackio.init()
Loggez les métriques avec trackio.log() ou utilisez report_to="trackio" de TRL
Finalisez avec trackio.finish()

Concept clé : Pour l'entraînement distant/cloud, passez space_id — les métriques se synchronisent avec un tableau de bord Space afin de persister après la fin de l'instance.

→ Consultez references/logging_metrics.md pour l'installation, l'intégration TRL et les options de configuration.

Python API → Alerts

Insérez des appels trackio.alert() dans le code d'entraînement pour signaler les événements importants — comme insérer des print statements pour déboguer, mais structurés et interrogeables :

trackio.alert(title="...", level=trackio.AlertLevel.WARN) — déclencher une alerte
Trois niveaux de sévérité : INFO, WARN, ERROR
Les alertes sont imprimées au terminal, stockées dans la base de données, affichées dans le tableau de bord et éventuellement envoyées à des webhooks (Slack/Discord)

Concept clé pour les agents LLM : Les alertes sont le mécanisme principal pour l'itération autonome d'expériences. Un agent doit insérer des alertes dans le code d'entraînement pour les conditions de diagnostic (pics de loss, gradients NaN, faible précision, entraînement bloqué). Puisque les alertes s'impriment au terminal, un agent qui surveille la sortie du script d'entraînement les verra automatiquement. Pour les exécutions en arrière-plan ou détachées, l'agent peut consulter via CLI à la place.

→ Consultez references/alerts.md pour l'API complète des alertes, la configuration des webhooks et les workflows d'agents autonomes.

CLI → Retrieving

Utilisez la commande trackio pour interroger les métriques et alertes loggées :

trackio list projects/runs/metrics — découvrir ce qui est disponible
trackio get project/run/metric — récupérer les résumés et valeurs
trackio list alerts --project <name> --json — récupérer les alertes
trackio show — lancer le tableau de bord
trackio sync — synchroniser avec HF Space

Concept clé : Ajoutez --json pour une sortie programmatique adaptée à l'automatisation et aux agents LLM.

→ Consultez references/retrieving_metrics.md pour toutes les commandes, workflows et formats de sortie JSON.

Installation minimale pour le logging

import trackio

trackio.init(project="my-project", space_id="username/trackio")
trackio.log({"loss": 0.1, "accuracy": 0.9})
trackio.log({"loss": 0.09, "accuracy": 0.91})
trackio.finish()

Récupération minimale

trackio list projects --json
trackio get metric --project my-project --run my-run --metric loss --json

Workflow autonome d'expériences ML

Lors de l'exécution d'expériences de manière autonome en tant qu'agent LLM, le workflow recommandé est :

Configurer l'entraînement avec des alertes — insérer des appels trackio.alert() pour les conditions de diagnostic
Lancer l'entraînement — exécuter le script en arrière-plan
Consulter les alertes — utiliser trackio list alerts --project <name> --json --since <timestamp> pour vérifier les nouvelles alertes
Lire les métriques — utiliser trackio get metric ... pour inspecter des valeurs spécifiques
Itérer — en fonction des alertes et métriques, arrêter la run, ajuster les hyperparamètres et lancer une nouvelle run

import trackio

trackio.init(project="my-project", config={"lr": 1e-4})

for step in range(num_steps):
    loss = train_step()
    trackio.log({"loss": loss, "step": step})

    if step > 100 and loss > 5.0:
        trackio.alert(
            title="Loss divergence",
            text=f"Loss {loss:.4f} still high after {step} steps",
            level=trackio.AlertLevel.ERROR,
        )
    if step > 0 and abs(loss) < 1e-8:
        trackio.alert(
            title="Vanishing loss",
            text="Loss near zero — possible gradient collapse",
            level=trackio.AlertLevel.WARN,
        )

trackio.finish()

Puis consultez depuis un terminal/processus séparé :

trackio list alerts --project my-project --json --since "2025-01-01T00:00:00"

huggingface-trackio