Suivi

Introduction

Trackio vous aide à organiser vos expériences au sein d’un projet. Un projet est un ensemble de runs, où chaque run représente une exécution unique de votre code avec un jeu de paramètres et de résultats spécifiques.

Initialisation

Pour commencer à suivre une expérience avec Trackio, vous devez d'abord initialiser un projet à l'aide de la fonction init() :

import trackio

trackio.init(project="my_project")

Si le projet existe déjà, il sera chargé.
Sinon, Trackio en créera un nouveau.

Dans les deux cas, une nouvelle exécution est automatiquement lancée, prête à enregistrer vos données.

Nommer votre exécution

Il est judicieux d’attribuer à chaque exécution un nom significatif pour faciliter l’organisation et la référence ultérieure. Vous pouvez définir un nom à l’aide du paramètre name :

trackio.init(project="my_project", name="my_first_run")

Si aucun nom n'est fourni, Trackio en génère un par défaut.

Regroupement des exécutions

Vous pouvez organiser les exécutions connexes en groupes à l’aide du paramètre group. Cela est particulièrement utile lorsque vous lancez plusieurs expériences avec des configurations différentes mais que vous souhaitez les comparer ensemble :

# Group runs by experiment type
trackio.init(project="my_project", name="baseline_run_1", group="baseline")
trackio.init(project="my_project", name="augmented_run_1", group="augmented")
trackio.init(project="my_project", name="tuned_run_1", group="tuned")

Les exécutions portant le même nom de groupe peuvent être regroupées dans la barre latérale, ce qui facilite la comparaison d’expériences liées. Vous pouvez également regrouper les exécutions selon tout autre paramètre de configuration (voir Configuration du suivi ci-dessous).

Journalisation à distance (Espace Hugging Face ou serveur auto-hébergé)

Par défaut, les métriques sont stockées localement et vous ouvrez le tableau de bord sur votre machine. Vous pouvez à la place envoyer les métriques à :

Un Espace Hugging Face, en transmettant space_id (ou en définissant TRACKIO_SPACE_ID). Trackio peut créer ou réutiliser l'Espace et y synchroniser les données.
Un serveur Trackio auto-hébergé (HTTP ou HTTPS), en transmettant server_url (ou en définissant TRACKIO_SERVER_URL). Utilisez l’URL d’accès en écriture issue de trackio.show() (éventuellement avec write_token dans la requête), ou une URL de base accompagnée de TRACKIO_WRITE_TOKEN. Le client s’authentifie avec le même jeton d’écriture que celui utilisé par le tableau de bord (et non votre jeton Hugging Face).

Si un Space et une URL auto-hébergée sont configurés (space_id / TRACKIO_SPACE_ID ainsi que server_url / TRACKIO_SERVER_URL), le Space a la priorité et l'URL auto-hébergée est ignorée. Les options telles que dataset_id (obsolète ; utilisez bucket_id à la place) et bucket_id s'appliquent aux déploiements Hugging Face ; lorsque seul server_url est actif, configurez le stockage sur l'hôte qui exécute le serveur (voir Variables d'environnement).

Pour les étapes de configuration (exécution de trackio show, liaison à 0.0.0.0, jetons d'écriture), voir Héberger le serveur vous-même.

Le tableau de bord intégré interroge les nouvelles exécutions et métriques toutes les 1 seconde sur localhost et toutes les 2 secondes lorsqu’il est ouvert sur un Hugging Face Space (*.hf.space), afin d’alléger les limites de débit sur l’URL du Space.

Journalisation des données

Une fois votre exécution initialisée, vous pouvez commencer à journaliser des données à l'aide de la fonction log() :

trackio.log({"loss": 0.05})

Trackio est conçu de manière défensive afin que les pannes côté Trackio ne compromettent jamais votre code d’expérience principal. En usage normal, les problèmes survenant dans les chemins de journalisation, de vidage ou de livraison de Trackio se traduisent par des avertissements et un tamponnage local, plutôt que par des exceptions dans votre boucle d’entraînement.

Chaque appel à log() incrémente automatiquement le compteur d'étapes. Si vous souhaitez enregistrer plusieurs métriques à la fois, passez-les ensemble :

trackio.log({
    "loss": 0.05,
    "accuracy": 0.95,
})

Tableaux de journalisation

Vous pouvez enregistrer des données tabulaires à l'aide de la classe Table. Cela est utile pour suivre des résultats tels que des prédictions, ou toute donnée structurée. Les tableaux peuvent inclure des colonnes d'images à l'aide de la classe Image.

import pandas as pd

df = pd.DataFrame(
    {
        "prompt": ["Trackio", "Logging is"],
        "completion": ["is great!", "easy and fun!"],
        "reward": [0.123, 0.456],
    }
)
trackio.log(
    {
        ...
        "texts": trackio.Table(dataframe=df),
    }
)

Rapports de journalisation (Markdown)

Vous pouvez enregistrer des rapports au format Markdown à l’aide de la classe Markdown. Les rapports sont affichés sur la page Rapports du tableau de bord, le plus récent apparaissant en premier.

trackio.log(
    {
        "training_report": trackio.Markdown(
            """# Training Report

Final validation accuracy: **0.92**

- Best epoch: 18
- Early stopping: enabled
"""
        )
    }
)

Vous pouvez enregistrer des rapports à plusieurs reprises au cours d'une exécution (par exemple, un rapport par point de contrôle), et Trackio conservera l'historique complet entre les étapes.

Pour un script exécutable complet, voir examples/training-with-report.py.

Journalisation des images

Vous pouvez enregistrer des images à l'aide de la classe Image.

trackio.log({"image": trackio.Image(value="path/to/image.png", caption="Image caption")})

Les images peuvent être journalisées à partir d'un chemin, d'un tableau numpy ou d'une image PIL.

Journalisation des vidéos

Vous pouvez enregistrer des vidéos à l'aide de la classe Video.

import trackio
import numpy as np

# Create a simple video from numpy array
frames = np.random.randint(0, 255, (10, 3, 64, 64), dtype=np.uint8)
video = trackio.Video(frames, caption="Random video", fps=30)
trackio.log({"my_video": video})

# Create a batch of videos
batch_frames = np.random.randint(0, 255, (3, 10, 3, 64, 64), dtype=np.uint8)
batch_video = trackio.Video(batch_frames, caption="Batch of videos", fps=15)
trackio.log({"batch_videos": batch_video})

# Create video from file path
video = trackio.Video("path/to/video.mp4", caption="Video from file")
trackio.log({"file_video": video})

Les vidéos peuvent être journalisées à partir d'un chemin de fichier ou d'un tableau numpy.

Exigences pour les tableaux NumPy :

Doit être de type np.uint8 avec des valeurs RGB comprises dans l'intervalle [0, 255]
La forme doit être l'une des suivantes :
- (frames, channels, height, width) pour une seule vidéo
- (batch, frames, channels, height, width) pour plusieurs vidéos (seront disposées en grille)

Journalisation audio

Vous pouvez enregistrer de l'audio à l'aide de la classe Audio.

import trackio
import numpy as np

# Generate a 1-second 440 Hz sine wave (mono)
sr = 16000
t = np.linspace(0, 1, sr, endpoint=False)
wave = 0.2 * np.sin(2 * np.pi * 440 * t)
audio = trackio.Audio(wave, caption="A4 sine", sample_rate=sr, format="wav")
trackio.log({"tone": audio})

# Stereo from numpy array (shape: samples, 2)
stereo = np.stack([wave, wave], axis=1)
audio = trackio.Audio(stereo, caption="Stereo", sample_rate=sr, format="mp3")
trackio.log({"stereo": audio})

# From an existing file
audio = trackio.Audio("path/to/audio.wav", caption="From file")
trackio.log({"file_audio": audio})

L'audio peut être journalisé à partir d'un chemin de fichier ou d'un tableau numpy.

Exigences pour les tableaux NumPy :

La forme doit être (samples,) pour le mono ou (samples, 2) pour le stéréo
sample_rate doit être fourni lors de la journalisation à partir d'un tableau numpy
Les valeurs peuvent être des nombres à virgule flottante ou des entiers ; les nombres à virgule flottante sont normalisés par rapport au pic et convertis en PCM 16 bits
format peut être "wav" ou "mp3" lors de la journalisation à partir d'un tableau numpy (par défaut "wav")

Journalisation d'objets 3D

Utilisez Object3D avec la même API trackio.log() que les autres médias :

import numpy as np
import trackio

trackio.log({"scene": trackio.Object3D("path/to/scene.glb", caption="Prediction")})

points = np.random.normal(size=(50_000, 3))
trackio.log({"point_cloud": trackio.Object3D.from_numpy(points)})

Format	Mesh	Nuage de points	Splat gaussien
`.glb` / `.gltf`	Oui	Via glTF	Non
`.obj`	Oui	Non	Non
`.stl`	Oui	Non	Non
`.ply`	Oui	Oui	Oui
`.splat`	Non	Non	Oui

Les tableaux NumPy doivent avoir l'une de ces formes :

(N, 3) pour les coordonnées XYZ.
(N, 4) pour XYZ plus une catégorie entière de 1 à 14. Trackio applique une palette de catégories déterministe.
(N, 6) pour les valeurs XYZ et RGB entières de 0 à 255.

Les coordonnées doivent être finies. Les nuages de points ordinaires sont limités de manière déterministe à 300 000 points rendus ; leurs compteurs d'origine et de rendu restent visibles. Trackio ne décime ni les maillages ni les splats gaussiens.

Les modèles doivent être autonomes. Les URI de données glTF intégrées sont prises en charge, mais les ressources glTF externes, les bibliothèques de matériaux OBJ et les textures PLY ne le sont pas. Chaque objet utilise la même structure <project>/<run>/<step>/<uuid>.<ext> que les images, les vidéos et les fichiers audio.

Les objets 3D fonctionnent également dans les tableaux :

table = trackio.Table(
    columns=["sample", "reconstruction"],
    data=[["chair", trackio.Object3D("chair.gltf")]],
)
trackio.log({"reconstructions": table})

Journalisation des éléments HTML et des figures

Vous pouvez journaliser du HTML à l'aide de la classe Html.

trackio.log({"report": trackio.Html("<h1>Results</h1>")})

Les figures Matplotlib et Plotly sont converties en HTML :

import plotly.express as px

fig = px.line(x=[1, 2, 3], y=[4, 5, 6])
trackio.log({"plot": fig})

Journalisation des métriques du système

Trackio peut enregistrer automatiquement les métriques système en arrière-plan. Il prend en charge les GPU NVIDIA et les Mac Apple Silicon (série M).

Installation :

# NVIDIA GPU monitoring
pip install trackio[gpu]

# Apple Silicon system monitoring
pip install trackio[apple-gpu]

Journalisation automatique (par défaut) :

Lorsque le package approprié est installé et qu'un matériel compatible est détecté, les métriques système sont enregistrées automatiquement en arrière-plan (toutes les 10 secondes par défaut) :

import trackio

# Auto-enabled when hardware is detected
trackio.init(project="my_project")

for step in range(100):
    # ... training code ...
    trackio.log({"loss": loss})
# System metrics are logged automatically in the background

trackio.finish()

Vous pouvez personnaliser l'intervalle ou désactiver la journalisation automatique :

# Custom interval
trackio.init(project="my_project", gpu_log_interval=5.0)

# Disable auto-logging
trackio.init(project="my_project", auto_log_gpu=False)

Journalisation manuelle :

Vous pouvez également enregistrer manuellement les métriques système à des moments précis à l'aide de log_gpu() :

import trackio

trackio.init(project="my_project", auto_log_gpu=False)

for step in range(100):
    # ... training code ...
    trackio.log({"loss": loss})
    trackio.log_gpu()  # Log system metrics at current time

trackio.finish()

Métriques GPU NVIDIA :

Métriques par GPU (gpu/{i}/{metric}) :

gpu/0/utilization - Taux d'utilisation du GPU (%)
gpu/0/memory_utilization - Taux d'utilisation du contrôleur mémoire (%)
gpu/0/allocated_memory - Mémoire allouée en GiB
gpu/0/total_memory - Mémoire totale en GiB
gpu/0/memory_usage - Taux d'utilisation de la mémoire (0-1)
gpu/0/temp - Température en degrés Celsius
gpu/0/power - Consommation électrique en watts
gpu/0/power_percent - Puissance en % de la limite
gpu/0/power_limit - Limite de puissance en watts
gpu/0/sm_clock - Vitesse d'horloge des SM en MHz
gpu/0/memory_clock - Vitesse de l'horloge mémoire en MHz
gpu/0/fan_speed - Vitesse du ventilateur (%)
gpu/0/performance_state - État de performance (P0-P15)
gpu/0/energy_consumed - Énergie consommée depuis le début de l'exécution, en joules
gpu/0/pcie_tx - bande passante de transmission PCIe en Mo/s
gpu/0/pcie_rx - bande passante de réception PCIe en Mo/s
gpu/0/throttle_thermal - Throttling thermique (0/1)
gpu/0/throttle_power - Limitation de la puissance (0/1)
gpu/0/throttle_hw_slowdown - Ralentissement matériel (0/1)
gpu/0/throttle_apps - Régulation de la fréquence des applications (0/1)
gpu/0/corrected_memory_errors - Erreurs ECC corrigées
gpu/0/uncorrected_memory_errors - erreurs ECC non corrigées

Métriques agrégées :

gpu/mean_utilization - Taux d'utilisation moyen des GPU sur l'ensemble des GPU
gpu/total_allocated_memory - Mémoire totale utilisée sur tous les GPU en Go
gpu/total_power - Consommation totale de tous les GPU
gpu/max_temp - Température maximale sur tous les GPU

Métriques Apple Silicon :

cpu/utilization - Taux d'utilisation global du CPU
cpu/{i}/utilization - Taux d'utilisation du CPU par cœur (%)
cpu/frequency - Fréquence actuelle du CPU en MHz
cpu/frequency_max - Fréquence maximale du CPU en MHz
memory/used - Mémoire utilisée en GiB
memory/total - Mémoire totale en GiB
memory/available - Mémoire disponible en GiB
memory/percent - Utilisation de la mémoire (%)
swap/used - Swap utilisé en GiB
swap/total - Total de swap en Go
swap/percent - Utilisation du swap en %
temp/{label} - Mesures du capteur de température en degrés Celsius (si disponible)
gpu/detected - Indique si un GPU Apple a été détecté (0/1)

Capturer la sortie de la console et la commande de lancement

Trackio enregistre la commande utilisée pour lancer chaque exécution (par exemple python train.py --lr 1e-3) et l’affiche en haut de la page de l’exécution dans le tableau de bord, avec un bouton pour la copier. Les valeurs des arguments dont les noms ressemblent à des secrets (tels que --hub_token, --api-key ou password=...) sont remplacées par REDACTED. La commande est stockée dans la configuration de l’exécution sous la clé réservée _Command.

Trackio peut également capturer tout ce que votre script écrit dans stdout et stderr, y compris les appels print(), la sortie de logging et les tracebacks, afin que vous puissiez suivre les journaux d’une exécution depuis le tableau de bord lorsque vous n’êtes pas devant le terminal. La capture de la console est désactivée par défaut. Activez-la avec capture_console=True :

import logging

import trackio

logging.basicConfig(level=logging.INFO)

trackio.init(project="my_project", capture_console=True)

for step in range(100):
    loss = ...
    logging.info("step %d loss=%.4f", step, loss)
    trackio.log({"loss": loss})

trackio.finish()

Ou activez-le sans modifier votre code en définissant la variable d'environnement TRACKIO_CAPTURE_CONSOLE :

TRACKIO_CAPTURE_CONSOLE=1 python train.py

La sortie capturée s’affiche dans la section Sortie de la console de la page de l’exécution (ouvrez une exécution depuis la page Exécutions). Elle se rafraîchit toutes les 10 secondes pendant que l’exécution est en cours, et le bouton Télécharger enregistre le journal complet sous forme de fichier texte. Chaque ligne est stockée avec l’heure UTC à laquelle elle a été écrite ; le tableau de bord l’affiche dans votre heure locale. La sortie est enregistrée toutes les 10 secondes et à la fin de l’exécution, fonctionne aussi bien pour les exécutions locales que pour les exécutions journalisées sur un Space ou un serveur auto-hébergé, et est limitée à 20 Mo par exécution.

Si le processus est arrêté avec SIGTERM (limite de temps Slurm, docker stop ou éviction Kubernetes), les données écrites depuis la dernière sauvegarde sont perdues. Définissez TRACKIO_HANDLE_SIGTERM=1 pour les sauvegarder avant la sortie du processus.

La capture de la console fonctionne en enveloppant la méthode write de sys.stdout et sys.stderr, elle capture donc également les gestionnaires de logging configurés avant l’appel de trackio.init(). Les sorties écrites directement sur les descripteurs de fichiers sous-jacents, comme les messages provenant d’extensions C ou de sous-processus, ne sont pas capturées.

Remarque : Si vous enregistrez les journaux dans un Space public, la sortie de console capturée est visible par toute personne pouvant consulter le tableau de bord. Assurez-vous que votre script n’affiche pas de secrets avant d’activer la capture de la console.

Finaliser une exécution

Lorsque votre exécution est terminée, finalisez-la avec finish(). Cela marque l’exécution comme terminée et enregistre toutes les données journalisées :

trackio.finish()

Reprendre une exécution

Trackio identifie les exécutions de manière interne à l’aide d’un run_id stable. Le name lisible par l’humain n’est plus tenu d’être unique, ce qui permet de créer plusieurs exécutions portant le même nom d’affichage.

Si vous devez reprendre la dernière exécution portant un nom donné (par exemple, après une interruption), appelez à nouveau init() avec le même nom de projet et d’exécution, et définissez resume="must" :

trackio.init(project="my_project", name="my_first_run", resume="must")

Cela chargera l’exécution la plus récente créée avec ce nom, afin que vous puissiez continuer à consigner des données en utilisant le même run_id. Mais si vous définissez resume="must" et qu’aucune exécution précédente n’existe avec le même nom, Trackio lèvera une erreur.

Pour plus de flexibilité, utilisez resume="allow". Cela reprendra la dernière exécution portant ce nom si elle existe, ou en créera une nouvelle dans le cas contraire.

La valeur par défaut est resume="never", ce qui crée toujours une nouvelle exécution avec un nouveau run_id, même si une autre exécution portant le même name existe déjà.

Suivi de la configuration

Vous pouvez également suivre les paramètres de configuration de vos exécutions. Cela est utile pour garder une trace des hyperparamètres ou d’autres réglages utilisés dans vos expériences. Vous pouvez enregistrer les données de configuration à l’aide du paramètre config dans la fonction init() :

for batch_size in [16, 32, 64]:
    for lr in [0.001, 0.01, 0.1]:
        trackio.init(
            project="hyperparameter_tuning",
            name=f"lr_{lr}_batch_{batch_size}_run",
            config={
                "learning_rate": lr,
                "batch_size": batch_size,
            }
        )
        # ... your training code ...
        trackio.finish()

Dans le tableau de bord, vous pouvez ensuite regrouper par « learning_rate » ou « batch_size » afin de comparer plus facilement les exécutions avec des hyperparamètres différents.

Update on GitHub