Trackio documentation

Référence de l'API

Trackio

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Référence de l'API

Exécuter

classe trackio.Run

( url: str | Noneproject: strclient: typing.Optional[typing.Any]name: str | None = Nonerun_id: str | None = Nonegroup: str | None = Noneconfig: dict | None = Nonespace_id: str | None = Nonebucket_id: str | None = Noneserver_base_url: str | None = Nonewrite_token: str | None = Noneexisting_runs: list[str] | None = Noneinitial_last_step: int | None = Noneauto_log_gpu: bool = Falsegpu_log_interval: float = 10.0auto_log_cpu: bool = Falsecpu_log_interval: float = 10.0webhook_url: str | None = Nonewebhook_min_level: trackio.alerts.AlertLevel | str | None = Nonecapture_console: bool = False )

link_artifact

( artifact: Artifacttarget_path: straliases: list[str] | None = Nonebucket_id: str | None = None )

Paramètres

artifact (Artifact) — La version de l’artifact à lier. Doit être un Artifact qui a été journalisé ou récupéré. Pour lier une version existante spécifique, récupérez-la d’abord avec use_artifact("my-model:v3") et liez le résultat. Un artifact qui n’a jamais été journalisé est d’abord journalisé dans le projet de cette exécution.
target_path (str) — La collection à lier, au format "registry-<registry>/<collection>", par exemple "registry-models/my-model". Le registre doit déjà exister (voir trackio.Api().create_registry). La collection est créée lors du premier lien et adopte le type de l’artefact ; les liens ultérieurs doivent correspondre à ce type.
aliases (list[str], facultatif) — Alias à placer sur la version liée, par exemple ["staging"]. Un alias pointe vers une version par collection, donc l’attribution d’un alias détenu par une autre version le déplace. latest est géré automatiquement et suit toujours la version liée la plus récente ; le passer ici n’a aucun effet.
bucket_id (str, facultatif) — Bucket Hugging Face contenant le registre, par exemple "my-org/models-registry". Requis pour lier depuis une exécution qui journalise vers un Space ou un serveur auto-hébergé. À omettre pour un registre local ; par défaut, TRACKIO_REGISTRY_BUCKET_ID si celui-ci est défini.

Lier une version d’artefact à une collection de registre.

Un lien est un pointeur vers la version source : aucun fichier n’est copié. Le lien reçoit le numéro de version suivant dans la collection (v0, v1, …), indépendamment des numéros de version de l’artefact source. Lier une version déjà présente dans la collection n’en crée pas une nouvelle : vous obtenez la version existante, et les aliases que vous passez se déplacent toujours.

Un registre local enregistre le lien avec les données de l’exécution, il n’est donc disponible que pour les exécutions sur cette machine. Passez bucket_id pour publier dans un registre adossé à un bucket — c’est aussi ainsi qu’une exécution qui journalise vers un Space ou un serveur auto-hébergé publie, car le bucket est accessible des deux côtés.

use_artifact

( artifact_or_name: trackio.artifact.Artifact | strtype: str | None = None )

Résoudre un artefact et enregistrer cette exécution en tant que consommateur de celui-ci.

La spécification est soit un artefact de projet ("name", "name:vN", "name:alias"), soit un emplacement de registre ("registry-<registry>/<collection>[:vN|:alias]"), qui se résout via les liens de la collection vers la version source qu’il pointe.

init

trackio.init

( project: strname: str | None = Nonegroup: str | None = Nonespace_id: str | None = Noneserver_url: str | None = Nonedataset_id: str | None = Nonebucket_id: str | None = Noneconfig: dict | None = Noneresume: str = 'never'settings: typing.Any = Noneprivate: bool | None = Noneembed: bool = Trueauto_log_gpu: bool | None = Nonegpu_log_interval: float = 10.0auto_log_cpu: bool | None = Nonecpu_log_interval: float = 10.0webhook_url: str | None = Nonewebhook_min_level: trackio.alerts.AlertLevel | str | None = Nonecapture_console: bool | None = None ) → Run

Paramètres

project (str) — Le nom du projet (peut être un projet existant pour continuer le suivi ou un nouveau projet pour démarrer le suivi de zéro).
name (str, facultatif) — Le nom de l'exécution (si non fourni, un nom par défaut sera généré).
group (str, facultatif) — Le nom du groupe auquel cette exécution appartient, afin de faciliter l’organisation des exécutions associées. Vous pouvez basculer la visibilité de l’ensemble du groupe dans le tableau de bord.
space_id (str, facultatif) — Si fourni, le projet sera journalisé dans un Space Hugging Face au lieu d'un répertoire local. Doit être un nom de Space complet comme « username/reponame » ou « orgname/reponame », ou simplement « reponame », auquel cas le Space sera créé dans l'espace de noms de l'utilisateur Hugging Face actuellement connecté. Si le Space n'existe pas, il sera créé. Si le Space existe déjà, le projet y sera journalisé. Peut également être défini via la variable d'environnement TRACKIO_SPACE_ID. Il est impossible de journaliser dans un Space qui a été gelé (converti en SDK statique) ; utilisez trackio.sync(..., sdk="static") uniquement après avoir terminé la journalisation. Prévoit la priorité sur server_url et TRACKIO_SERVER_URL si plus d'une de ces valeurs est définie.
server_url (str, facultatif) — URL de base d’un serveur Trackio auto-hébergé (http:// ou https://), ou l’URL d’accès en écriture fournie par trackio.show(), qui peut inclure un paramètre de requête write_token. Le client envoie ce jeton à chaque requête (X-Trackio-Write-Token) ; vous pouvez également définir TRACKIO_WRITE_TOKEN au lieu d’intégrer le jeton dans l’URL. Lorsqu’il est défini, les métriques sont envoyées à ce serveur via HTTP au lieu de créer ou de synchroniser avec un Space Hugging Face. Peut également être défini via la variable d’environnement TRACKIO_SERVER_URL. Ignoré si space_id ou TRACKIO_SPACE_ID est défini.
dataset_id (str, facultatif) — Obsolète : la persistance des données trackio dans un Dataset Hugging Face sera supprimée dans une future version de trackio. Utilisez bucket_id (un Bucket Hugging Face) à la place.
bucket_id (str, facultatif) — L'identifiant du Bucket Hugging Face à utiliser pour la persistance des métriques. Par défaut, lorsqu'un space_id est fourni et que bucket_id n'est pas explicitement défini, un bucket est généré automatiquement à partir du space_id. Les buckets offrent un stockage de type S3 sans la surcharge de git - la base de données SQLite est stockée directement via hf-mount dans le Space. Spécifiez un Bucket avec un nom de la forme “username/bucketname” ou simplement “bucketname”.
config (dict, facultatif) — Un dictionnaire d'options de configuration. Fourni pour la compatibilité avec wandb.init().
resume (str, facultatif, par défaut “never) — Contrôle la reprise d'une exécution. Peut prendre l'une des valeurs suivantes :
- « must » : Reprendre l’exécution portant le nom indiqué ; une erreur est levée si l’exécution n’existe pas
- “allow” : reprendre l’exécution si elle existe, sinon créer une nouvelle exécution
- « never » : ne jamais reprendre une exécution, toujours en créer une nouvelle
private (bool, facultatif) — Indique s'il faut rendre le Space privé. Si la valeur est None (par défaut), le dépôt sera public, sauf si le paramètre par défaut de l'organisation est privé. Cette valeur est ignorée si le dépôt existe déjà.
settings (Any, facultatif) — Non utilisé. Fourni pour la compatibilité avec wandb.init().
embed (bool, facultatif, par défaut True) — Lors de l'exécution dans un notebook Jupyter/Colab, indique si le tableau de bord doit être automatiquement intégré dans la cellule lorsque trackio.init() est appelé. Pour les exécutions locales, cela lance un tableau de bord Trackio local et l'intègre. Pour les exécutions sur Space, cela intègre l'URL du Space. Dans Colab, le tableau de bord local sera accessible via une URL de partage publique lorsque share=True.
auto_log_gpu (bool ou None, facultatif, valeur par défaut None) — Contrôle l’enregistrement automatique des métriques GPU. Si None (par défaut), l’enregistrement des métriques GPU est activé automatiquement lorsque nvidia-ml-py est installé et qu’un GPU NVIDIA ou une puce Apple M series est détecté. Définissez True pour forcer l’activation ou False pour la désactiver.
gpu_log_interval (float, facultatif, par défaut 10.0) — L'intervalle en secondes entre les journaux automatiques des métriques GPU. Utilisé uniquement lorsque auto_log_gpu=True.
auto_log_cpu (bool ou None, facultatif, valeur par défaut None) — Contrôle l’enregistrement automatique des métriques CPU et RAM (utilisation, mémoire, I/O disque, I/O réseau et capteurs). Si None (par défaut), l’enregistrement CPU est activé automatiquement lorsque psutil est installé. Définissez True pour forcer l’activation ou False pour la désactiver.
cpu_log_interval (float, facultatif, par défaut 10.0) — L'intervalle en secondes entre les journaux automatiques des métriques CPU. Utilisé uniquement lorsque la journalisation automatique du CPU est activée.
webhook_url (str, facultatif) — Une URL de webhook vers laquelle envoyer les charges utiles d’alerte par requête POST lorsque trackio.alert() est appelé. Prend en charge nativement les URL de webhook Slack et Discord (les charges utiles sont formatées automatiquement). Peut également être défini via la variable d’environnement TRACKIO_WEBHOOK_URL. Des alertes individuelles peuvent remplacer cette URL en passant webhook_url à trackio.alert().
webhook_min_level (AlertLevel ou str, facultatif) — Niveau d’alerte minimal qui doit déclencher la livraison du webhook. Par exemple, AlertLevel.WARN n’envoie que les alertes WARN et ERROR à la destination du webhook. Peut également être défini via TRACKIO_WEBHOOK_MIN_LEVEL.
capture_console (bool ou None, facultatif, valeur par défaut None) — Indique s'il faut capturer tout ce que le script écrit sur stdout et stderr (y compris la sortie de print() et de logging) et le stocker avec l'exécution. La sortie est affichée sur la page de l'exécution dans le tableau de bord, où elle peut également être téléchargée. Si None (par défaut), la capture de la console est activée uniquement lorsque la variable d'environnement TRACKIO_CAPTURE_CONSOLE est définie sur 1 ou true.

Retourne

Exécuter

Un objet [Run] qui peut être utilisé pour consigner des métriques et terminer l'exécution.

Crée un nouveau projet Trackio et renvoie un objet [Run].

log

trackio.log

( metrics: dictstep: int | None = None )

Paramètres

metrics (dict) — Un dictionnaire de métriques à consigner.
step (int, facultatif) — Le numéro d'étape. S'il n'est pas fourni, l'étape sera incrémentée automatiquement.

Enregistre les métriques dans l'exécution en cours.

log_gpu

trackio.log_gpu

( run: trackio.run.Run | None = Nonedevice: int | None = None ) → dict

Paramètres

run — Instance Run facultative. Si None, utilise l'exécution actuelle du contexte.
device — Index de l’appareil CUDA à partir duquel collecter les métriques (GPU NVIDIA uniquement). Si la valeur est None, les métriques sont collectées à partir de tous les GPU visibles par ce processus. Ce paramètre est ignoré pour les GPU Apple.

Retourne

dict

Les métriques GPU qui ont été journalisées.

Journalise les métriques GPU dans l’exécution actuelle ou spécifiée en tant que métriques système. Détecte automatiquement si un GPU NVIDIA ou Apple est disponible et appelle la méthode de journalisation appropriée.

Exemple :

import trackio

run = trackio.init(project="my-project")
trackio.log({"loss": 0.5})
trackio.log_gpu()
trackio.log_gpu(device=0)

log_system

trackio.log_system

( metrics: dict )

Paramètres

metrics (dict) — Un dictionnaire de métriques système à consigner.

Enregistre les métriques système (GPU, etc.) dans l’exécution actuelle en utilisant des horodatages plutôt que des étapes.

log_artifact

trackio.log_artifact

( artifact_or_path: trackio.artifact.Artifact | str | pathlib.Pathname: str | None = Nonetype: str | None = Nonealiases: list[str] | None = Noneoverwrite: bool = False )

Paramètres

artifact_or_path (Artifact, str ou Path) — L’artefact à journaliser (au moins un fichier doit y avoir été ajouté via add_file ou add_dir), ou un chemin vers un fichier ou un répertoire à journaliser en tant que nouvel artefact.
name (str, facultatif) — Nom de l’artefact lors de l’enregistrement d’un chemin. La valeur par défaut est run-<run_id>-<basename>. Ne doit pas être transmis avec un Artifact.
type (str, facultatif) — Type d’artefact lors de l’enregistrement d’un chemin (par ex. "model", "dataset"). Valeur par défaut : "unspecified". Ne doit pas être transmis avec un Artifact.
aliases (list[str], facultatif) — Alias à associer à la version résultante, en plus de latest (qui est attribué automatiquement à chaque création d'une nouvelle version). Vos alias sont associés à la version même lorsque le contenu identique est dédoublonné.
overwrite (bool, facultatif) — Si True, supprime toutes les autres versions de cet artefact après l’enregistrement du nouveau contenu. Les blobs encore utilisés par d’autres artefacts sont conservés, et les numéros de version continuent d’augmenter. Valeur par défaut : False.

Journalise un artefact en tant que sortie de l'exécution en cours.

use_artifact

trackio.use_artifact

( artifact_or_name: trackio.artifact.Artifact | strtype: str | None = None )

Paramètres

artifact_or_name (Artifact ou str) — Un Artifact déjà journalisé, ou le nom d’un artefact. Un nom simple ("my-model") est résolu vers :latest ; vous pouvez également épingler une version ("my-model:v3") ou résoudre un alias ("my-model:prod").
type (str, facultatif) — Si fourni, vérifié par rapport au type d’artefact stocké, et une exception est levée en cas de non-correspondance.

Récupère un artefact et l'enregistre en tant qu'entrée de l'exécution en cours.

terminer

trackio.finish

( )

Termine l'exécution en cours.

afficher

trackio.show

( project: str | None = Nonedashboard: str | None = Nonetheme: typing.Any = Nonemcp_server: bool | None = Nonefooter: bool = Truecolor_palette: list[str] | None = Noneopen_browser: bool = Trueblock_thread: bool | None = Nonehost: str | None = Noneshare: bool | None = Noneserver_port: int | None = Nonefrontend_dir: str | pathlib.Path | None = None ) → app

Paramètres

project (str, facultatif) — Le nom du projet dont les exécutions doivent être affichées. S’il n’est pas fourni, tous les projets seront affichés et l’utilisateur pourra en sélectionner un.
dashboard (str, facultatif) — Définir sur "registry" pour afficher le tableau de bord autonome du registre. La valeur par défaut est le tableau de bord du projet.
theme (Any, facultatif) — Ignoré. Conservé pour la compatibilité ascendante ; Trackio n’utilise plus les thèmes Gradio.
mcp_server (bool, facultatif) — Si True, le tableau de bord expose un serveur MCP sur /mcp lorsque la dépendance facultative trackio[mcp] est installée. Si None (par défaut), la variable d’environnement GRADIO_MCP_SERVER est utilisée (par exemple sur Spaces).
footer (bool, facultatif, par défaut True) — Indique s'il faut inclure footer=false dans l'URL du jeton d'écriture lorsque la valeur est False. Cela peut également être contrôlé via le paramètre de requête footer dans l'URL.
color_palette (list[str], facultatif) — Une liste de codes couleur hexadécimaux à utiliser pour les lignes du graphique. Si aucune n’est fournie, la variable d’environnement TRACKIO_COLOR_PALETTE sera utilisée (codes hexadécimaux séparés par des virgules), ou, si celle-ci n’est pas définie, la palette de couleurs par défaut sera utilisée. Exemple : ['#FF0000', '#00FF00', '#0000FF']
open_browser (bool, facultatif, par défaut True) — Si True et que l'on n'est pas dans un notebook, un nouvel onglet de navigateur sera ouvert avec le tableau de bord. Si False, le navigateur ne sera pas ouvert.
block_thread (bool, facultatif) — Si True, le thread principal sera bloqué jusqu’à la fermeture du tableau de bord. Si None (comportement par défaut), le thread principal ne sera pas bloqué si le tableau de bord est lancé dans un notebook, sinon le thread principal sera bloqué.
host (str, facultatif) — Hôte auquel lier le serveur. S'il n'est pas fourni, la valeur par défaut est '127.0.0.1' (localhost uniquement). Définissez-le sur '0.0.0.0' pour autoriser l'accès à distance.
share (bool, facultatif) — Si True, crée une URL publique temporaire (tunnel compatible Gradio). Sur Colab ou les notebooks hébergés, la valeur par défaut est True sauf si elle est remplacée.
server_port (int, facultatif) — Port à lier. Si non défini, la recherche démarre à partir de GRADIO_SERVER_PORT (7860 par défaut).
frontend_dir (str | Path, facultatif) — Répertoire contenant un frontend statique personnalisé. Doit contenir index.html. S'il n'est pas fourni, Trackio vérifie TRACKIO_FRONTEND_DIR, puis la configuration persistante de Trackio, puis le frontend intégré. Si un frontend_dir explicite pointe vers un répertoire manquant ou vide, Trackio copie le modèle de démarrage et sert ce répertoire.

Retourne

app

Le gestionnaire du tableau de bord (.close() arrête le serveur). url : l’URL locale du tableau de bord. share_url : l’URL de partage publique, le cas échéant. full_url : l’URL complète incluant le jeton d’écriture (URL de partage en cas de partage, sinon locale).

Lance le tableau de bord Trackio.

sync

trackio.sync

( project: strspace_id: str | None = Noneprivate: bool | None = Noneforce: bool = Falserun_in_background: bool = Falsesdk: str = 'gradio'dataset_id: str | None = Nonebucket_id: str | None = Nonefrontend_dir: str | pathlib.Path | None = None ) → str

Paramètres

project (str) — Le nom du projet à téléverser.
space_id (str, facultatif) — L'identifiant de l'Espace vers lequel effectuer le téléversement (par exemple, “username/space_id”). S'il n'est pas fourni, les métadonnées du projet sont d'abord vérifiées, puis un space_id aléatoire est généré.
private (bool, facultatif) — Indique si le Space doit être privé. Si la valeur est None (par défaut), le dépôt sera public, sauf si le paramètre par défaut de l’organisation est privé. Cette valeur est ignorée si le dépôt existe déjà. Non pris en charge avec sdk="static", car les tableaux de bord Trackio statiques lisent les données de l’instantané directement depuis le navigateur.
force (bool, facultatif, par défaut False) — Si True, écrase la base de données existante sans demander de confirmation. Si False, demande à l'utilisateur de confirmer avant d'écraser une base de données existante.
run_in_background (bool, facultatif, par défaut False) — Si True, la création de l’espace et le téléchargement de la base de données seront exécutés dans un thread en arrière-plan. Si False, toutes les étapes seront exécutées de manière synchrone.
sdk (str, facultatif, par défaut “gradio”) — Le type d’espace à déployer. “gradio” déploie un espace Gradio avec un serveur en direct. “static” fige l’espace : déploie un espace statique qui lit depuis un bucket HF (aucun serveur n’est nécessaire).
dataset_id (str, facultatif) — Obsolète : la persistance des données trackio dans un Dataset Hugging Face sera supprimée dans une future version de trackio. Utilisez bucket_id (un Bucket Hugging Face) à la place.
bucket_id (str, facultatif) — L’identifiant du Bucket HF vers lequel synchroniser. Par défaut, un bucket est généré automatiquement à partir de space_id.

Retourne

str

L'ID de l'espace du projet synchronisé.

Synchronise la base de données d’un projet Trackio local vers un Space Hugging Face. Si le Space n’existe pas, il sera créé. Les données locales ne sont jamais supprimées.

Gel : Passer sdk="static" déploie un Space statique adossé à un Bucket HF (tableau de bord en lecture seule, sans serveur Gradio). Vous pouvez resynchroniser le même projet plus tard pour rafraîchir ce Space statique. Si vous souhaitez créer un instantané unique d'un Space Gradio existant, utilisez plutôt freeze().

freeze

trackio.freeze

( space_id: strproject: strnew_space_id: str | None = Noneprivate: bool | None = Nonebucket_id: str | None = Nonefrontend_dir: str | pathlib.Path | None = None ) → str

Paramètres

space_id (str) — L'identifiant de l'espace Gradio source (par exemple, "username/my-space" ou un nom de dépôt court avec l'espace de noms de l'utilisateur connecté déduit, comme init()). Doit être un espace Gradio avec un bucket monté sur /data.
project (str) — Le nom du projet dont les données doivent être incluses dans l’Espace figé.
new_space_id (str, facultatif) — L’identifiant de la nouvelle Space statique. S’il n’est pas fourni, la valeur par défaut est "{space_id}_static".
private (bool, facultatif) — Non pris en charge. Les tableaux de bord statiques figés lisent les données de l'instantané directement depuis le navigateur, l'instantané de destination doit donc être public.
bucket_id (str, facultatif) — L’identifiant du Bucket HF pour le stockage des données de la nouvelle Space statique. S’il n’est pas fourni, un identifiant est généré automatiquement à partir de l’identifiant de la nouvelle Space.

Retourne

str

L'ID de l'Espace statique nouvellement créé.

Crée un nouvel espace Hugging Face statique contenant un instantané en lecture seule des données du projet spécifié à partir de l'espace Gradio source. Les données sont lues depuis le bucket associé à l'espace source au moment de la fige. L'espace d'origine n'est pas modifié, et le nouvel espace statique ne reflète pas automatiquement les métriques téléversées dans l'espace Gradio d'origine après la fin de la fige.

delete_project

trackio.delete_project

( project: strforce: bool = False ) → bool

Paramètres

project (str) — Le nom du projet à supprimer.
force (bool, facultatif, par défaut False) — Si True, supprime le projet sans demander de confirmation. Si False, demande à l'utilisateur de confirmer avant la suppression.

Retourne

bool

True si le projet a été supprimé, False sinon.

Supprime un projet en supprimant sa base de données SQLite locale.

import_csv

trackio.import_csv

( csv_path: str | pathlib.Pathproject: strname: str | None = Nonespace_id: str | None = Nonedataset_id: str | None = Noneprivate: bool | None = Noneforce: bool = False )

Paramètres

csv_path (str ou Path) — La chaîne de caractères ou le chemin vers le fichier CSV à importer.
project (str) — Le nom du projet dans lequel importer le fichier CSV. Ne doit pas être un projet existant.
name (str, facultatif) — Le nom de la Run dans laquelle importer le fichier CSV. S'il n'est pas fourni, un nom par défaut sera généré.
name (str, facultatif) — Le nom de l'exécution (si non fourni, un nom par défaut sera généré).
space_id (str, facultatif) — Si fourni, le projet sera enregistré dans un Space Hugging Face au lieu d'un répertoire local. Doit être un nom de Space complet comme "username/reponame" ou "orgname/reponame", ou simplement "reponame", auquel cas le Space sera créé dans l'espace de noms de l'utilisateur Hugging Face actuellement connecté. Si le Space n'existe pas, il sera créé. Si le Space existe déjà, le projet y sera enregistré.
dataset_id (str, facultatif) — Obsolète : la persistance des données trackio dans un Dataset Hugging Face sera supprimée dans une future version de trackio. Utilisez bucket_id (un Bucket Hugging Face) à la place.
private (bool, facultatif) — Indique s'il faut rendre le Space privé. Si la valeur est None (par défaut), le dépôt sera public, sauf si le paramètre par défaut de l'organisation est privé. Cette valeur est ignorée si le dépôt existe déjà.

Importe un fichier CSV dans un projet Trackio. Le fichier CSV doit contenir une colonne "step", peut éventuellement contenir une colonne "timestamp", et toute autre colonne sera traitée comme une métrique. Il doit également inclure une ligne d’en-tête avec les noms des colonnes.

TODO : appeler init() et retourner un objet Run afin que l'utilisateur puisse continuer à consigner des métriques.

import_tf_events

trackio.import_tf_events

( log_dir: str | pathlib.Pathproject: strname: str | None = Nonespace_id: str | None = Nonedataset_id: str | None = Noneprivate: bool | None = Noneforce: bool = False )

Paramètres

log_dir (str ou Path) — La chaîne de caractères ou le chemin vers le répertoire contenant les fichiers d'événements TensorFlow.
project (str) — Le nom du projet dans lequel importer les fichiers TensorFlow Events. Ne doit pas être un projet existant.
name (str, facultatif) — Préfixe de nom pour les exécutions (si non fourni, les noms de répertoires seront utilisés). Chaque sous-répertoire créera une exécution distincte.
space_id (str, facultatif) — Si fourni, le projet sera enregistré dans un Space Hugging Face au lieu d'un répertoire local. Doit être un nom de Space complet comme "username/reponame" ou "orgname/reponame", ou simplement "reponame", auquel cas le Space sera créé dans l'espace de noms de l'utilisateur Hugging Face actuellement connecté. Si le Space n'existe pas, il sera créé. Si le Space existe déjà, le projet y sera enregistré.
dataset_id (str, facultatif) — Obsolète : la persistance des données trackio dans un Dataset Hugging Face sera supprimée dans une future version de trackio. Utilisez bucket_id (un Bucket Hugging Face) à la place.
private (bool, facultatif) — Indique s'il faut rendre le Space privé. Si la valeur est None (par défaut), le dépôt sera public, sauf si le paramètre par défaut de l'organisation est privé. Cette valeur est ignorée si le dépôt existe déjà.

Importe les fichiers TensorFlow Events d'un répertoire dans un projet Trackio. Chaque sous-répertoire du répertoire de journalisation sera importé comme une exécution distincte.

save

trackio.save

( glob_str: str | pathlib.Pathproject: str | None = None ) → str

Paramètres

glob_str (str ou Path) — Le chemin du fichier ou le motif glob à enregistrer. Peut être un fichier unique ou un motif correspondant à plusieurs fichiers (par exemple, "*.py", "models/**/*.pth").
project (str, facultatif) — Le nom du projet dans lequel enregistrer les fichiers. S'il n'est pas fourni, utilise le projet actuel de trackio.init(). Si aucun projet n'est initialisé, lève une erreur.

Retourne

str

Le chemin où le(s) fichier(s) a/ont été enregistré(s) (répertoire des fichiers du projet).

Enregistre des fichiers dans un projet (non liés à une exécution spécifique). Si Trackio est exécuté localement, le(s) fichier(s) sera(ont) copié(s) dans le répertoire des fichiers du projet. Si Trackio est exécuté dans un Space, le(s) fichier(s) sera(ont) téléversé(s) dans le répertoire des fichiers du Space.

Exemple :

import trackio

trackio.init(project="my-project")
trackio.save("config.yaml")
trackio.save("models/*.pth")

Artefact

classe trackio.Artifact

( name: strtype: strdescription: str | None = Nonemetadata: dict | None = None )

Paramètres

name (str) — Nom de l’artefact, unique au sein du projet. Doit correspondre à ^[A-Za-z0-9._-]+$ (lettres, chiffres, point, tiret bas, tiret).
type (str) — Catégorie libre telle que "model" ou "dataset", utilisée pour regrouper les artefacts.
description (str, facultatif) — Description lisible par un humain de l’artefact.
metadata (dict, facultatif) — Métadonnées JSON sérialisables arbitraires stockées avec la version.

Un ensemble de fichiers et de références nommé et versionné, associé à un projet.

Construisez un Artifact, ajoutez-y des fichiers avec add_file / add_dir (les octets sont mis en attente dans le stockage adressé par contenu) ou add_reference (un URI externe est enregistré sans copier d'octets), puis persistez-le avec trackio.log_artifact. L'enregistrement fige l'artefact et remplit ses champs en lecture seule version, aliases, size et manifest.

add_dir

( local_dir: str | pathlib.Pathname: str | None = None )

Paramètres

local_dir (str ou Path) — Chemin vers un répertoire existant dont les fichiers sont ajoutés.
name (str, facultatif) — Préfixe de chemin logique pour les fichiers ajoutés. Par défaut, aucun préfixe n’est appliqué, les fichiers conservent donc leurs chemins relatifs à local_dir.

Établir l’empreinte de chaque fichier régulier sous un répertoire, de manière récursive.

Les liens symboliques sont ignorés.

add_file

( local_path: str | pathlib.Pathname: str | None = None )

Paramètres

local_path (str ou Path) — Chemin vers un fichier régulier existant à ajouter.
name (str, facultatif) — Chemin logique sous lequel le fichier est stocké dans l’artefact. Par défaut, c’est le nom de base du fichier.

Mettre un fichier unique en attente pour son inclusion dans l’artefact.

add_reference

( uri: strname: str | None = Nonechecksum: bool = Truemax_objects: int | None = None )

Paramètres

uri (str) — Emplacement des données référencées, encodé en pourcentage (construisez des URI locales avec pathlib.Path.as_uri()). file://, http(s):// et hf:// sont résolus et récupérés nativement ; tout autre schéma (s3://, gs://, URL de blob Azure, …) nécessite un ReferenceHandler personnalisé enregistré via trackio.register_reference_handler — consultez la documentation des artefacts pour des exemples complets — et lève une erreur dans le cas contraire.
name (str, facultatif) — Chemin logique sous lequel la référence est stockée. Par défaut, il s’agit du dernier segment de uri ; pour un préfixe développé (se terminant par /), il s’agit du préfixe sous lequel le chemin relatif de chaque objet est imbriqué.
checksum (bool, facultatif, valeur par défaut True) — Lorsque True, interroge la source pour en déduire sa taille et un checksum (et pour déployer un répertoire/préfixe) : file:// est haché en flux vers un sha256, hf:// utilise son sha256 LFS ou son identifiant de blob git, et http(s):// utilise le ETag du serveur. Cela peut lire le système de fichiers ou effectuer des requêtes réseau. Lorsqu’aucun checksum ne peut être obtenu pour une source distante (par ex. pas d’ETag), l’URI elle-même est utilisée comme digest et un avertissement est émis. Un chemin local file:// qui n’existe pas lève une exception à la place. Passez checksum=False pour ignorer complètement l’interrogation des sources distantes.
max_objects (int, facultatif) — Limite du nombre d'objets dans lesquels un répertoire/préfixe peut se déployer (valeur par défaut : 10 000) ; une exception est levée en cas de dépassement.

Stocker une référence vers des données externes, sans copier aucun octet.

Contrairement à add_file/add_dir, une référence enregistre l’URI des données (ainsi que, le cas échéant, une taille et un checksum) sans stocker les octets dans le magasin à adressage par contenu. C’est ainsi que vous versionnez et suivez la lignée de grands jeux de données ou de données déjà stockées de manière durable, qui ne doivent pas être dupliquées.

Une URI qui désigne un répertoire (file://, hf:// ou un préfixe développé par un gestionnaire personnalisé) est développée en une entrée par objet, limitée par max_objects. Les octets de référence ne sont jamais téléversés vers un Space ou un bucket.

L’URI est stockée telle quelle dans le manifeste de l’artefact, et les manifestes peuvent être synchronisés avec un jeu de données Hugging Face partagé — une URI signée déclenche donc un avertissement pour des raisons de sécurité ; veuillez privilégier l’URI non signée canonique de l’objet (par exemple s3://bucket/key).

télécharger

( root: str | pathlib.Path | None = None )

Paramètres

root (str ou Path, facultatif) — Répertoire dans lequel écrire les fichiers. Par défaut, ./.trackio/artifact-downloads/<project>/<name>_v<version>/, indexé par projet afin que les artefacts de même nom provenant de projets différents ne se chevauchent jamais, et par la version résolue afin qu'un alias mobile comme latest ne laisse jamais derrière lui des fichiers obsolètes d'une version précédente.

Matérialiser les fichiers de l’artefact dans un répertoire local.

Les fichiers sont copiés depuis le cache adressé par contenu de Trackio (et récupérés depuis le distant s’ils sont absents localement), de sorte que les appels répétés sont peu coûteux et idempotents.

Les entrées de référence ajoutées via add_reference sont également récupérées ici : l’objet situé à chaque URI de référence est téléchargé dans le répertoire (via le httpx2 inclus pour http(s)://, huggingface_hub pour hf://, et le ReferenceHandler personnalisé enregistré pour tout autre schéma). Chaque objet est écrit de manière atomique et les appels sont idempotents. Étant donné que les digests de référence sont opaques (un ETag du fournisseur ou l’URI lui-même), un fichier présent est considéré comme à jour et n’est pas re-vérifié par rapport à la source, et une source dont la somme de contrôle re-sondée ne correspond plus à celle enregistrée est téléchargée de toute façon avec un avertissement. Le téléchargement peut transférer une grande quantité de données ; pour travailler avec les URI sans les télécharger, lisez-les plutôt depuis la propriété references ou get_entry_uri. Une source manquante, un serveur inaccessible ou un schéma sans gestionnaire enregistré provoque une exception.

get_entry_uri

( name: str )

Retourne l'URI enregistrée pour l'entrée de référence au chemin logique name, ou None s'il n'existe pas d'entrée de référence portant ce nom.

lien

( target_path: straliases: list[str] | None = Nonebucket_id: str | None = None )

Paramètres

target_path (str) — La collection à lier, sous la forme "registry-<registry>/<collection>". Le registre doit déjà exister.
aliases (list[str], facultatif) — Alias à placer sur la version liée. latest est géré automatiquement ; le transmettre n’a aucun effet.
bucket_id (str, facultatif) — Bucket contenant le registre, par exemple "my-org/models-registry". À omettre pour un registre local ; par défaut, TRACKIO_REGISTRY_BUCKET_ID si celui-ci est défini.

Lier cette version d'artefact à une collection de registre.

Un lien est un pointeur vers cette version : aucun fichier n’est copié. Consultez Run.link_artifact pour la sémantique complète (versionnage des collections, alias et artefact lié retourné).

L’artefact doit déjà être journalisé ou récupéré ; contrairement à Run.link_artifact, cette méthode ne journalise pas d’artefact en brouillon pour vous, et le lien ne consigne aucune exécution de publication. Un artefact récupéré depuis un Space ou un serveur auto-hébergé ne peut être lié qu’à un registre adossé à un bucket, car un registre local n’est pas accessible depuis l’endroit où se trouvent ses octets.

délier

( )

Supprimez ce lien de registre.

Appelée sur l’artefact lié renvoyé par link ou Run.link_artifact, et non sur une version d’artefact source. L’artefact source et ses fichiers restent intacts ; seule l’appartenance à la collection est supprimée. Les alias pointant vers le lien sont supprimés avec lui, et le numéro de version de la collection n’est jamais réutilisé. Si la version détenait latest, cet alias est déplacé vers la version restante la plus élevée.

wait

( timeout: int | None = None )

No-op : trackio journalise les artefacts de manière synchrone, de sorte que l’artefact est déjà commit au moment où log_artifact retourne.

Registre

classe trackio.Registry

( name: strbucket_id: str | None = None )

Paramètres

name (str) — Nom du registre, par exemple "models". Doit correspondre à ^[A-Za-z0-9_-]+$ (lettres, chiffres, tiret bas, tiret).
bucket_id (str, facultatif) — Bucket Hugging Face contenant le registre, par exemple "my-org/models-registry". À omettre pour un registre local. Par défaut, TRACKIO_REGISTRY_BUCKET_ID si cette variable est définie.

Un accès à un registre d'artefacts.

Un registre est un catalogue partagé de versions d’artefacts, organisé en collections. Vous y publiez avec Run.link_artifact et vous promouvez des versions en déplaçant des alias tels que "staging" ou "production". Consultez le guide du Registre pour une vue d’ensemble.

Vous ne construisez pas vous-même un Registry. Créez un registre avec trackio.Api().create_registry(name) ou récupérez un registre existant avec trackio.Api().registry(name) ; les deux renvoient ce gestionnaire.

Exemple :

import trackio

registry = trackio.Api().create_registry("models")
registry.create_collection(
    "my-model", artifact_type="model", description="My favorite model"
)

run = trackio.init(project="my-experiments")
artifact = trackio.log_artifact("model.pt", name="resnet", type="model")
run.link_artifact(artifact, "registry-models/my-model", aliases=["staging"])
trackio.finish()

registry.collection("my-model").links

collection

( name: str )

Décrivez une collection.

Retourne None si le registre ou la collection n'existe pas.

collections

( )

Liste les collections du registre, liens inclus.

Retourne une liste vide si le registre n'existe pas.

create_collection

( name: strartifact_type: strdescription: str | None = None )

Paramètres

name (str) — Nom de la collection, unique au sein du registre. Doit correspondre à ^[A-Za-z0-9._-]+$.
artifact_type (str) — Le type d’artefact accepté par la collection, par exemple "model" ou "dataset". Le type est fixé à la création ; lier un artefact d’un type différent provoque une erreur.
description (str, facultatif) — Description lisible par un humain de la collection.

Créer une collection dans ce registre.

Les collections sont également créées automatiquement lors du premier lien, ce qui est donc principalement utile pour définir une description à l'avance. Si la collection existe déjà, elle est renvoyée telle quelle et une description non nulle est appliquée.

événements

( )

Retourner le journal d’audit du registre, en commençant par l’événement le plus ancien.

Chaque événement possède un id, un horodatage ts, un kind ("create", "link", "promote", "update" ou "unlink") et un payload décrivant la mutation. Un create payload sans clé collection enregistre la création du registre lui-même.

Collection

classe trackio.Collection

( name: strtype: strdescription: str | Nonecreated_at: strnum_links: intlatest_version: int | Nonelinks: list[dict] )

Un instantané en lecture seule d'une collection de registre.

Retourné par Registry.create_collection, Registry.collection et Registry.collections.

Image

classe trackio.TrackioImage

( value: str | pathlib.Path | numpy.ndarray | PIL.Image.Imagecaption: str | None = None )

Paramètres

value (str, Path, numpy.ndarray ou PIL.Image, facultatif) — Un chemin vers une image, une image PIL ou un tableau numpy de forme (hauteur, largeur, canaux). S'il s'agit d'un tableau numpy, il doit être de type np.uint8 avec des valeurs RGB comprises dans l'intervalle [0, 255].
caption (str, facultatif) — Une légende en chaîne de caractères pour l'image.

Initialise un objet Image.

Exemple :

import trackio
import numpy as np
from PIL import Image

# Create an image from numpy array
image_data = np.random.randint(0, 255, (64, 64, 3), dtype=np.uint8)
image = trackio.Image(image_data, caption="Random image")
trackio.log({"my_image": image})

# Create an image from PIL Image
pil_image = Image.new('RGB', (100, 100), color='red')
image = trackio.Image(pil_image, caption="Red square")
trackio.log({"red_image": image})

# Create an image from file path
image = trackio.Image("path/to/image.jpg", caption="Photo from file")
trackio.log({"file_image": image})

Vidéo

classe trackio.TrackioVideo

( value: str | pathlib.Path | numpy.ndarraycaption: str | None = Nonefps: int | None = Noneformat: typing.Optional[typing.Literal['gif', 'mp4', 'webm']] = None )

Paramètres

value (str, Path ou numpy.ndarray, facultatif) — Un chemin vers un fichier vidéo, ou un tableau numpy. S’il s’agit d’un tableau numpy, il doit être de type np.uint8 avec des valeurs RGB comprises dans l’intervalle [0, 255]. Sa forme est attendue soit (frames, channels, height, width), soit (batch, frames, channels, height, width). Dans le second cas, les vidéos seront disposées en grille.
caption (str, facultatif) — Une légende en chaîne de caractères pour la vidéo.
fps (int, facultatif) — Images par seconde de la vidéo. Utilisé uniquement lorsque la valeur est un ndarray. La valeur par défaut est 24.
format (Literal["gif", "mp4", "webm"], facultatif) — Format de la vidéo (« gif », « mp4 » ou « webm »). Utilisé uniquement lorsque la valeur est un ndarray. La valeur par défaut est « gif ».

Initialise un objet Video.

Exemple :

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)

# 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)

# Create video from file path
video = trackio.Video("path/to/video.mp4", caption="Video from file")

write_video

( file_path: str | pathlib.Pathvideo: ndarrayfps: floatcodec: typing.Literal['h264', 'vp9', 'gif'] )

RGB uint8 uniquement, forme (F, H, W, 3).

Audio

classe trackio.TrackioAudio

( value: str | pathlib.Path | numpy.ndarraycaption: str | None = Nonesample_rate: int | None = Noneformat: typing.Optional[typing.Literal['wav', 'mp3']] = None )

Paramètres

value (str, Path ou numpy.ndarray, facultatif) — Un chemin vers un fichier audio, ou un tableau numpy. Le tableau doit avoir la forme (samples,) pour le mono ou (samples, 2) pour le stéréo. Les tableaux de type flottant seront normalisés par pic et convertis en PCM 16 bits ; les tableaux entiers seront convertis en PCM 16 bits si nécessaire.
caption (str, facultatif) — Une légende en texte pour l'audio.
sample_rate (int, facultatif) — Taux d'échantillonnage en Hz. Requis lorsque value est un tableau numpy.
format (Literal["wav", "mp3"], facultatif) — Format audio utilisé lorsque value est un tableau numpy. La valeur par défaut est « wav ».

Initialise un objet Audio.

Exemple :

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})

ensure_int16_pcm

( data: ndarray )

Convertit le tableau d'audio d'entrée en PCM int16 contigu. Une normalisation de crête est appliquée aux entrées flottantes.

Object3D

classe trackio.TrackioObject3D

( path_or_array: str | pathlib.Path | numpy.ndarraycaption: str | None = None )

Html

classe trackio.TrackioHtml

( data: typing.Anyinject: bool = Truedata_is_not_path: bool = Falsecaption: str | None = None )

Paramètres

data (str, Path, objet de type fichier, figure Plotly ou figure Matplotlib) — HTML brut, un chemin vers un fichier .html, un objet de type fichier, ou une figure Plotly ou Matplotlib.
inject (bool, facultatif) — Enveloppe les fragments HTML dans un document stylé. La valeur par défaut est True.
data_is_not_path (bool, facultatif) — Accepté pour la compatibilité avec wandb.Html mais ignoré.
caption (str, facultatif) — Une légende en chaîne de caractères pour le HTML.

Initialise un objet Html.

Exemple :

import trackio

trackio.init(project="my-project")

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

# Plotly figure
import plotly.express as px

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

# Matplotlib figure
import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4])
trackio.log({"chart": trackio.Html(plt)})

Tableau

classe trackio.Table

( columns: list[str] | None = Nonedata: list[list[typing.Any]] | None = Nonedataframe: typing.Optional[typing.Any] = Nonerows: list[list[typing.Any]] | None = Noneoptional: bool | list[bool] = Trueallow_mixed_types: bool = Falselog_mode: typing.Optional[typing.Literal['IMMUTABLE', 'MUTABLE', 'INCREMENTAL']] = 'IMMUTABLE' )

Paramètres

columns (list[str], facultatif) — Noms des colonnes du tableau. Facultatif si data est fourni. Non attendu si dataframe est fourni. Actuellement ignoré.
data (list[list[Any]], facultatif) — Tableau 2D orienté lignes de valeurs. Chaque valeur peut être un nombre, une chaîne de caractères (traitée comme du Markdown et tronquée si trop longue) ou un objet Trackio.Image ou une liste d'objets Trackio.Image.
dataframe (pandas.DataFrame, facultatif) — DataFrame utilisé pour créer le tableau. S’il est défini, les arguments data et columns sont ignorés.
rows (list[list[Any]], facultatif) — Actuellement ignoré.
optional (bool ou list[bool], facultatif, valeur par défaut True) — Actuellement ignoré.
allow_mixed_types (bool, facultatif, valeur par défaut False) — Actuellement ignoré.
log_mode — (Literal["IMMUTABLE", "MUTABLE", "INCREMENTAL"] ou None, facultatif, valeur par défaut "IMMUTABLE") : Actuellement ignoré.

Initialise un objet Table.

Les tableaux peuvent être utilisés pour consigner des données tabulaires, y compris des images, des nombres et du texte.

to_display_format

( table_data: list[dict] ) → list[dict]

Paramètres

table_data (list[dict]) — Liste de dictionnaires représentant les lignes du tableau (issues de _value stocké).

Retourne

list[dict]

Données du tableau avec des images converties en syntaxe Markdown et du texte long tronqué.

Convertit les données de table stockées au format d’affichage pour le rendu de l’interface utilisateur.

Note : Cela n'utilise pas l'attribut self.data, mais utilise à la place le paramètre table_data, qui est ce que l'interface utilisateur reçoit.

Trace

classe trackio.Trace

( messages: list[dict[str, Any]]metadata: dict | None = Nonespans: list[dict[str, Any]] | None = None )

Paramètres

messages (list[dict[str, Any]]) — Messages au format OpenAI, par exemple {"role": "user", "content": "..."}. Les messages de l’assistant peuvent inclure tool_calls, et les résultats d’outils peuvent inclure tool_call_id ; lorsque aucun spans n’est fourni, le tableau de bord associe ces éléments en opérations d’outils.
metadata (dict, facultatif) — Métadonnées au niveau de la trace, par exemple session_id ou environment. Les clés status, duration_ms, latency_ms et cost_usd sont utilisées par le tableau de bord comme valeurs par défaut au niveau de la trace lorsque les spans ne les fournissent pas.
spans (list[dict[str, Any]], facultatif) — Spans d’exécution décrivant ce qui a produit la réponse. Chaque span est un dictionnaire indexé par id, name et kind ("span", "generation" ou "tool"), ainsi que par les champs facultatifs parent_id, start_time, end_time, duration_ms, status, error, input, output, model, usage, cost_usd et metadata.

Initialise un objet Trace.

Les traces capturent une demande conversationnelle ou de type agent : des messages au format OpenAI, des métadonnées facultatives et des spans d’exécution facultatives. Les spans sont des dictionnaires qui décrivent des générations de modèle, des appels d’outils ou d’autres opérations. Les objets média Trackio imbriqués dans les messages, les métadonnées ou les spans sont persistés et sérialisés avec la trace.

Histogramme

classe trackio.Histogram

( sequence: typing.Union[numpy.ndarray, typing.Sequence[float], typing.Sequence[int], NoneType] = Nonenp_histogram: tuple | None = Nonenum_bins: int = 64 )

Paramètres

sequence (np.ndarray ou Sequence[float] ou Sequence[int], facultatif) — Séquence de valeurs à partir de laquelle créer l’histogramme.
np_histogram (tuple, facultatif) — Histogramme NumPy précalculé sous forme de tuple (hist, bins).
num_bins (int, facultatif, par défaut 64) — Nombre de classes pour l’histogramme (maximum 512).

Type de données d'histogramme pour Trackio, compatible avec wandb.Histogram.

Exemple :

import trackio
import numpy as np

# Create histogram from sequence
data = np.random.randn(1000)
trackio.log({"distribution": trackio.Histogram(data)})

# Create histogram from numpy histogram
hist, bins = np.histogram(data, bins=30)
trackio.log({"distribution": trackio.Histogram(np_histogram=(hist, bins))})

# Specify custom number of bins
trackio.log({"distribution": trackio.Histogram(data, num_bins=50)})

Update on GitHub

←Exécution avec RapidFire AI