Registre

Un registre est un catalogue partagé de vos meilleures versions d’artefacts. Un projet répertorie les artefacts produits par vos expériences ; un registre répertorie les artefacts sélectionnés à travers les projets.

Un registre contient des collections. Chaque collection représente un actif — un modèle que vous réentraînez au fil du temps, un jeu d'évaluation de référence — et conserve les versions que vous avez choisi de publier. Vous liez une version d'artefact à une collection. Un lien est un pointeur vers la version source : rien n'est copié. Vous promouvez ensuite une version liée à travers les étapes du cycle de vie en déplaçant des alias tels que staging et production.

Par exemple, un registre nommé models peut contenir une collection par modèle déployable, et un registre nommé datasets une collection par benchmark. La manière dont vous répartissez les actifs entre les registres et les collections vous appartient.

Une collection possède sa propre ligne de version (v0, v1, …) qui est indépendante des numéros de version des artefacts sources, et ses versions peuvent pointer vers des artefacts sources différents dans différents projets. Les alias désignent exactement une version par collection.

Un registre est soit local — stocké à côté de vos autres données Trackio sous la forme d’un projet nommé registry-models (le préfixe registry- est réservé) — soit adossé à un seau Hugging Face, ce qui le rend accessible depuis d’autres machines et depuis des exécutions qui journalisent vers un Space. Voir Registres distants.

Créer un registre

Créez un registre avec Api.create_registry() :

import trackio

registry = trackio.Api().create_registry("models", description="Our deployable models")

Le paramètre facultatif description est stocké dans le registre et lisible via registry.description.

Les registres ne sont jamais créés implicitement. Lier à un registre qui n'existe pas provoque une erreur.

Utilisez Api.registry() pour récupérer un registre existant. Elle lève également une exception si le registre n'existe pas.

Créer une collection

Une collection est un ensemble de versions d'artefacts liés au sein d'un registre, avec un historique de versions unique. Les versions peuvent provenir d'artefacts sources différents : si un modèle basé sur resnet et un modèle basé sur unet sont des candidats pour le même produit déployable, liez-les dans une seule collection et ils deviennent des versions successives de celui-ci. S'il s'agit de produits distincts, attribuez à chacun sa propre collection.

Vous ne créez généralement pas de collections manuellement : le lien vers une collection qui n’existe pas la crée automatiquement. Créez-en une explicitement lorsque vous souhaitez définir une description à l’avance :

registry.create_collection("my-model", "model", description="The model we deploy")

Types de collections

Chaque collection accepte un seul type d’artefact, fixé lors de la création de la collection. Le type provient de l’artefact lui-même — le champ type que vous passez à trackio.Artifact ou trackio.log_artifact — de sorte qu’une collection créée par un premier lien adopte le type de cet artefact.

Par exemple, si vous liez un artefact "dataset" à une collection qui n’accepte que des artefacts "model", Trackio lève une erreur.

Le registre lui-même accepte tous les types : une collection de modèles et une collection de jeux de données peuvent coexister dans le même registre.

Lier une version d’artefact à une collection

Publier une version d'artefact avec Run.link_artifact() :

import trackio

trackio.Api().create_registry("models")

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"])

Le chemin cible est "registry-<registry>/<collection>". Le premier segment est le nom complet du registre, préfixe inclus.

link_artifact prend l'objet artefact lui-même, de sorte que la version que vous détenez est exactement celle qui est publiée :

Vous pouvez également créer un lien depuis l’artefact lui-même avec Artifact.link(), pratique lorsque l’exécution n’est pas dans le contexte :

artifact.link("registry-models/my-model", aliases=["staging"])

Artifact.link exige que l’artefact ait déjà été journalisé ou récupéré — il ne journalise pas un brouillon à votre place — et le lien ne consigne aucune exécution de publication.

L'artefact lié

link_artifact renvoie l’artefact à son emplacement dans le registre. Son name est la collection, son project est le registre, et ses version et aliases sont ceux de la collection. Son contenu — manifest, manifest_digest, size, metadata — est celui de la version source, et les propriétés source_project, source_name, source_version et source_qualified_name renvoient vers celle-ci :

linked = run.link_artifact(artifact, "registry-models/my-model")
linked.qualified_name         # "registry-models/my-model:v0"
linked.source_qualified_name  # "my-experiments/resnet:v0"

Lier un artefact lié lie directement sa version source (avec un avertissement), de sorte que les liens ne s’enchaînent jamais.

Les consommateurs résolvent un emplacement de registre directement avec use_artifact, sans savoir quel projet ou quel artefact l’a produit :

model = run.use_artifact("registry-models/my-model:production")
model.download()  # fetches the source version's files

La spécification après la collection accepte une version de collection ("v1"), un alias ("production") ou rien pour la version liée la plus récente. Le téléchargement d'un artefact lié récupère les octets de la version source vers laquelle il pointe.

Les emplacements de registre peuvent actuellement être résolus uniquement par des exécutions locales, et uniquement lorsque l’artefact source est disponible localement. Les sources stockées sur un Space, dans un bucket ou sur un serveur auto-hébergé peuvent être publiées dans un registre adossé à un bucket, mais la résolution de ces liens dans un processus ultérieur n’est pas encore prise en charge. L’artefact lié renvoyé directement par link_artifact conserve sa source Space ou auto-hébergée et peut effectuer le téléchargement depuis celle-ci.

Versions des collections

Chaque nouveau lien reçoit le numéro de version suivant dans la collection, en commençant par v0. Les versions de collection sont indépendantes des numéros de version des artefacts sources, car les versions liées proviennent généralement d’artefacts et de projets différents.

Lier une version source déjà présente dans la collection ne crée pas une nouvelle version. Vous récupérez la version existante, et les aliases que vous avez transmis sont toujours déplacés. Les numéros de version ne sont jamais réutilisés, de sorte qu’une my-model:v3 publiée ne peut jamais changer de sens silencieusement.

Promouvoir une version avec des alias

Un alias référence une version par collection. L’attribution d’un alias déjà détenu par une autre version le déplace — ce déplacement est la promotion. Les consommateurs qui résolvent my-model:production suivent l’alias, de sorte que rien en aval ne change lorsqu’il se déplace.

La plupart des promotions ont lieu au moment de la publication : vous liez une nouvelle version et placez l’alias dans le même appel.

run.link_artifact(artifact, "registry-models/my-model", aliases=["staging"])

Pour promouvoir une version déjà présente dans la collection, re-liez-la avec l’alias. La re-lien ne crée rien de nouveau : vous récupérez la version existante de la collection, et les alias que vous transmettez sont appliqués à celle-ci. Trouvez la source de la version dans les liens de la collection, récupérez-la, puis liez-la à nouveau :

registry.collection("my-model").links
# [..., {"collection_version": 1, "source_project": "my-experiments",
#        "source_artifact": "resnet", "source_version": 3, ...}]

candidate = run.use_artifact("resnet:v3")
run.link_artifact(candidate, "registry-models/my-model", aliases=["production"])

Vous pouvez également le récupérer directement depuis le registre :

candidate = run.use_artifact("registry-models/my-model:v1")
run.link_artifact(candidate, "registry-models/my-model", aliases=["production"])

Revenir à une version antérieure d'un alias fonctionne de la même manière.

Trackio gère l'alias latest pour vous : il pointe toujours vers la dernière version liée.

Détacher une version

Supprimez un lien avec Artifact.unlink(), appelé sur l’artefact lié :

linked = run.link_artifact(artifact, "registry-models/my-model")
linked.unlink()

L’artefact source et ses fichiers restent intacts — seule l’appartenance à la collection est supprimée. Les alias associés au lien sont retirés avec elle, et le numéro de version de la collection n’est jamais réutilisé, de sorte que my-model:v0 ne peut plus désigner autre chose par la suite. Si la version supprimée portait l’alias latest, celui-ci est transféré vers la version restante la plus élevée, afin que latest continue de pointer vers la version la plus récente de la collection.

Registres distants

Un registre local n’existe que sur la machine qui l’a créé. Pour partager un catalogue entre plusieurs machines — ou pour publier depuis une exécution qui journalise vers un Space ou un serveur auto-hébergé — appuyez le registre sur un seau Hugging Face en passant bucket_id :

registry = trackio.Api().create_registry(
    "models", description="Our deployable models", bucket_id="my-org/models-registry"
)

Le bucket est créé (privé) s’il n’existe pas. Définissez TRACKIO_REGISTRY_BUCKET_ID pour qu’il devienne la valeur par défaut de chaque appel au registre dans un processus, afin que les scripts n’aient pas à le transmettre.

La récupération, l’inspection et la publication prennent tous le même argument :

registry = trackio.Api().registry("models", bucket_id="my-org/models-registry")

run = trackio.init(project="my-experiments", space_id="my-org/my-dashboard")
artifact = trackio.log_artifact("model.pt", name="resnet", type="model")

run.link_artifact(
    artifact,
    "registry-models/my-model",
    aliases=["staging"],
    bucket_id="my-org/models-registry",
)

Toute personne ayant accès au bucket y écrit directement avec ses propres identifiants Hugging Face — il n’y a aucun serveur dans le chemin, de sorte qu’un registre n’est lié à aucun Space en particulier et survit à tous. Artifact.link et Artifact.unlink acceptent bucket_id de la même manière, et un artefact lié se souvient du bucket dont il provient, de sorte que linked.unlink() retourne au bon registre.

Le propre bucket du registre est délibérément différent du bucket de l’exécution : un registre est un catalogue inter-projets, vous le nommez donc explicitement plutôt que d’hériter de l’endroit où les métriques se trouvent.

Ce qui se trouve dans le bucket

Chaque mutation est stockée sous forme d'un objet immuable, et l'état est un repli de ce journal :

trackio/registries/<registry>/registry.json            name, description, created_at
trackio/registries/<registry>/events/<event_uid>.json  one object per mutation

La lecture d’un registre distant agrège ces événements dans une base de données de projection locale sous registry-cache/, qui est un cache : supprimez-le et la lecture suivante le reconstruit à partir du bucket.

Concurrence

Le stockage d'objets ne dispose pas de compare-and-swap, les rédacteurs ne peuvent donc pas prendre de verrou — ils ne peuvent que créer des objets que personne d'autre n'est en train d'écrire. Deux conséquences, toutes deux par conception :

• Les numéros de version sont attribués par le pliage, et non par l’auteur. Les liens concurrents sont ordonnés par leur identifiant d’événement (horodatage, puis auteur, puis séquence), de sorte que chacun reçoit un numéro distinct, jamais réutilisé. Une version signalée par un auteur peut changer une fois que les événements d’un auteur concurrent sont pliés.
• Les déplacements d’alias suivent la règle « dernier écrit, dernier gagnant » dans le même ordre, latest inclus. Si deux personnes promeuvent production au même instant, l’ordre des événements tranche.

Les liens restent de simples pointeurs : rien n’est copié dans le seau du registre, de sorte que le stockage du projet source doit rester accessible. La résolution de liens dont la source est distante n’est pas encore prise en charge. La copie (l’épinglage) des octets d’une version dans le registre est une étape prévue par la suite.

Inspecter un registre

Le Registry gère les listes de collections et leurs versions liées. Les lectures renvoient des instantanés de Collection :

registry = trackio.Api().registry("models")

registry.collections()
# [Collection(name="my-model", type="model", num_links=2, latest_version=1, ...)]

registry.collection("my-model").links
# [{"collection_version": 1, "source_project": "my-experiments",
#   "source_artifact": "resnet", "source_version": 4,
#   "aliases": ["latest", "production"], ...}]

Chaque lien enregistre l’origine de la version (source_project, source_artifact, source_version), les coordonnées de stockage de la source lorsqu’elle n’est pas locale (source_space_id, source_bucket_id ou source_server_base_url), ainsi que les alias actuellement associés. Un lien est un simple pointeur vers cette version source.

Interface en ligne de commande

Les commandes du trackio registry couvrent le même flux de publication et d'inspection sans nécessiter de script Python :

trackio registry create models --description "Models we deploy"
trackio registry create-collection models/churn-model --type model

trackio registry link models/churn-model my-experiments/resnet:v3 --alias staging
trackio registry promote models/churn-model production v0

trackio registry list models
trackio registry show models/churn-model
trackio registry events models

trackio registry unlink models/churn-model v0

link résout sa source à partir des données Trackio locales. Il accepte une version ou un alias explicite et utilise latest par défaut lorsque le suffixe est omis. Le registre peut toujours être basé sur un bucket ; passez --bucket-id my-org/models-registry à n’importe quelle commande. Utilisez --json pour une sortie structurée adaptée aux scripts.

La CLI accepte à la fois models/churn-model et la syntaxe complète de cible registry-models/churn-model de l’API Python. Consultez Commandes CLI pour la référence complète des commandes.

Parcourir les registres dans le tableau de bord

Lancez le tableau de bord du registre autonome en lecture seule pour parcourir les descriptions du registre, les collections, les versions liées, les alias, les emplacements sources et les événements d’audit :

trackio show registry

Ou lancez-le depuis Python avec trackio.show(dashboard="registry"). Le tableau de bord du registre est distinct du tableau de bord du projet car les registres cataloguent les artefacts à travers les projets.

La source Local affiche les registres stockés sur la machine du tableau de bord. Sélectionnez HF Bucket pour choisir un bucket Hugging Face accessible ou saisissez un identifiant de bucket tel que my-org/models-registry. Sur un Space, l’accès aux buckets privés utilise les identifiants Hugging Face du spectateur connecté. Un tableau de bord auto-hébergé n’utilise son jeton Hugging Face enregistré que pour les spectateurs ayant ouvert son URL d’accès en écriture. Les tableaux de bord publics en lecture seule n’exposent jamais les buckets via un jeton appartenant au serveur. La navigation dans les registres n’est pas incluse dans les instantanés statiques des tableaux de bord.

Historique des audits

Chaque mutation ajoute un événement au journal d’audit du registre : création du registre et de la collection (create), link, promote, modifications de description (update) et unlink. Le journal répond à des questions du type « quelle version était en production le mois dernier, et quel run l’a publiée ? » :

registry.events()
# [{"id": 1, "ts": "...", "kind": "create", "payload": {...}},
#  {"id": 2, "ts": "...", "kind": "link",
#   "payload": {"collection": "my-model", "collection_version": 0,
#               "source_project": "my-experiments", "run_name": "exp-1", ...}},
#  {"id": 3, "ts": "...", "kind": "promote",
#   "payload": {"alias": "staging", "collection_version": 0,
#               "previous_version": None, ...}}]

Les événements de liaison et de promotion enregistrent l’exécution de publication. Les événements de promotion enregistrent également la version d’origine de l’alias.