Suivre des fichiers externes

Utilisez des artifacts de référence pour suivre et utiliser des fichiers enregistrés en dehors des serveurs W&B. Parmi les solutions de stockage externe courantes, citons : CoreWeave AI Object Storage, Backblaze B2 Cloud Storage, un bucket Amazon Simple Storage Service (Amazon S3), un bucket GCS, un blob Azure, un serveur de fichiers HTTP ou un partage NFS. Les artifacts de référence se comportent comme les artifacts non référencés, à une différence près : ils ne contiennent que des métadonnées sur les fichiers, comme leur taille et leur somme de contrôle MD5. Les fichiers eux-mêmes ne quittent jamais votre système. Vous pouvez interagir avec un artifact de référence de la même manière qu’avec un artifact non référencé. Dans la W&B App, vous pouvez parcourir le contenu de l’artifact de référence à l’aide du navigateur de fichiers, explorer le graphe de dépendances complet et consulter l’historique des versions de votre artifact. En revanche, l’interface ne peut pas afficher le rendu de médias enrichis tels que les images ou l’audio, car les données elles-mêmes ne sont pas stockées dans l’artifact.

Si vous journalisez un artifact qui ne suit pas de fichiers externes, W&B enregistre les fichiers de l’artifact sur les serveurs W&B. C’est le comportement par défaut lorsque vous journalisez des artifacts avec le SDK Python W&B.Si vous journalisez un artifact qui suit des fichiers externes, W&B journalise des métadonnées sur l’objet, comme son ETag et sa taille. Si la gestion des versions d’objets est activée sur le bucket, l’ID de version est également journalisé.

Les sections suivantes expliquent comment suivre des artifacts de référence externes.

Suivre un artifact dans un bucket externe

Utilisez le SDK Python W&B pour suivre des références vers des fichiers stockés en dehors de W&B.

Initialisez un run avec wandb.init().
Créez un objet artifact avec wandb.Artifact().
Indiquez la référence vers le chemin du bucket à l’aide de la méthode wandb.Artifact.add_reference() de l’objet artifact.
Journalisez les métadonnées de l’artifact avec run.log_artifact().

import wandb

# Initialiser un run W&B
with wandb.init(project="my-project") as run:

  # Créer un objet artifact
  artifact = wandb.Artifact(name="name", type="type")

  # Ajouter une référence au chemin du bucket
  artifact.add_reference(uri = "uri/to/your/bucket/path")

  # Journaliser les métadonnées de l’artifact
  run.log_artifact(artifact)

Par exemple, supposons que votre bucket présente l’arborescence de répertoires suivante :

s3://my-bucket

|datasets/
  |-- mnist/
|models/
  |-- cnn/

Le répertoire datasets/mnist/ contient une collection d’images. Pour suivre ce répertoire d’images datasets/mnist/ en tant qu’artifact de jeu de données, procédez comme suit :

Fournissez un nom pour l’artifact, par exemple "mnist".
Définissez le paramètre type sur "dataset" lors de la construction de l’objet artifact (wandb.Artifact(type="dataset")).
Fournissez le chemin du répertoire datasets/mnist/ sous la forme d’un URI Amazon S3 (s3://my-bucket/datasets/mnist/) lorsque vous appelez wandb.Artifact.add_reference().
Journalisez l’artifact avec run.log_artifact().

L’exemple de code suivant crée un artifact de référence mnist:latest :

import wandb

with wandb.init(project="my-project") as run:
  artifact = wandb.Artifact(name="mnist", type="dataset")
  artifact.add_reference(uri="s3://my-bucket/datasets/mnist")
  run.log_artifact(artifact)

Dans W&B App, vous pouvez parcourir le contenu de l’artifact de référence à l’aide du navigateur de fichiers, explorer le graphe de dépendances complet et consulter l’historique des versions de votre artifact. W&B App n’affiche pas le rendu des médias enrichis, comme les images ou l’audio, car les données elles-mêmes ne sont pas stockées dans l’artifact.

W&B Artifacts prend en charge toute interface compatible avec Amazon S3, notamment CoreWeave Storage, Backblaze B2 Cloud Storage et MinIO. Les scripts décrits ci-dessous fonctionnent tels quels avec ces fournisseurs, à condition de définir la variable d’environnement AWS_S3_ENDPOINT_URL pour qu’elle pointe vers votre serveur compatible S3 (par exemple, https://s3.us-west-001.backblazeb2.com pour Backblaze B2).

Par défaut, W&B limite à 10 000 le nombre d’objets lors de l’ajout d’un préfixe d’objet. Vous pouvez modifier cette limite en spécifiant max_objects= lorsque vous appelez wandb.Artifact.add_reference().

Télécharger un artifact depuis un bucket externe

Lorsque W&B télécharge un artifact de référence, il récupère les fichiers depuis le bucket sous-jacent à l’aide des métadonnées enregistrées au moment où l’artifact a été journalisé. Si la gestion des versions des objets est activée sur votre bucket, W&B récupère la version de l’objet qui correspond à l’état du fichier au moment où l’artifact a été journalisé. À mesure que le contenu de votre bucket évolue, vous pouvez donc toujours retrouver la version exacte des données sur lesquelles un modèle donné a été entraîné, car l’artifact constitue un instantané de votre bucket pendant le run d’entraînement. L’exemple de code suivant montre comment télécharger un artifact de référence. Les API de téléchargement sont les mêmes pour les artifacts de référence et les artifacts non référencés :

import wandb

with wandb.init(project="my-project") as run:
  artifact = run.use_artifact("mnist:latest", type="dataset")
  artifact_dir = artifact.download()

Si votre flux de travail implique d’écraser des fichiers, W&B vous recommande d’activer la « gestion des versions des objets » (Object Versioning) sur vos buckets de stockage.Lorsque la gestion des versions est activée, W&B peut toujours récupérer la bonne version du fichier lorsque vous téléchargez un artifact, même si ce fichier a été écrasé après la journalisation de l’artifact.Selon votre fournisseur, consultez les instructions pour activer la gestion des versions des objets : AWS, Google Cloud, Azure.

Ajouter et télécharger une référence externe depuis un bucket

L’exemple de code suivant téléverse un jeu de données dans un bucket Amazon S3, le suit à l’aide d’un artifact de référence, puis le télécharge :

import boto3
import wandb

with wandb.init() as run:
  # Code d’entraînement ici...

  s3_client = boto3.client("s3")
  s3_client.upload_file(file_name="my_model.h5", bucket="my-bucket", object_name="models/cnn/my_model.h5")

  # Journaliser l’artifact de modèle
  model_artifact = wandb.Artifact("cnn", type="model")
  model_artifact.add_reference("s3://my-bucket/models/cnn/")
  run.log_artifact(model_artifact)

Par la suite, vous pourrez télécharger l’artifact de modèle. Indiquez le nom de l’artifact et son type :

import wandb

with wandb.init() as run:
  artifact = run.use_artifact(artifact_or_name = "cnn", type="model")
  datadir = artifact.download()

Consultez les rapports suivants pour un guide pas à pas complet expliquant comment suivre des artifacts par référence avec Google Cloud ou Azure :

Identifiants de stockage cloud

W&B utilise le mécanisme par défaut de votre fournisseur de cloud pour rechercher les identifiants d’authentification. Pour en savoir plus sur les identifiants utilisés, consultez la documentation de votre fournisseur de cloud :

Fournisseur de cloud	Documentation sur les identifiants
CoreWeave AI Object Storage	Documentation de CoreWeave AI Object Storage
Backblaze B2 Cloud Storage	Documentation sur les clés d’application Backblaze B2
AWS	Documentation de Boto3
Google Cloud	Documentation de Google Cloud
Azure	Documentation d’Azure

Pour AWS, si le bucket ne se trouve pas dans la région par défaut de l’utilisateur configuré, vous devez définir la variable d’environnement AWS_REGION sur la région du bucket.

Selon la configuration CORS de votre bucket, les médias enrichis tels que les images, l’audio, la vidéo et les nuages de points peuvent ne pas s’afficher dans l’interface de l’application. Ajoutez app.wandb.ai à la liste des origines autorisées dans les paramètres CORS de votre bucket pour que la W&B App puisse afficher correctement ces médias enrichis.Si les médias enrichis tels que les images, l’audio, la vidéo et les nuages de points ne s’affichent pas dans l’interface de l’application, vérifiez que app.wandb.ai figure dans la liste des origines autorisées de la stratégie CORS de votre bucket.

Suivre un artifact dans un système de fichiers

Pour accéder aux jeux de données, une approche courante consiste à exposer un point de montage NFS vers un système de fichiers distant sur toutes les machines qui exécutent des tâches d’entraînement. Cette solution peut remplacer un bucket de stockage cloud, car, du point de vue du script d’entraînement, les fichiers semblent se trouver sur votre système de fichiers local. Pour suivre un artifact dans un système de fichiers :

Initialisez un run avec wandb.init().
Créez un objet artifact avec wandb.Artifact().
Indiquez la référence au chemin du système de fichiers à l’aide de la méthode wandb.Artifact.add_reference() de l’objet artifact.
Journalisez les métadonnées de l’artifact avec run.log_artifact().

Copiez-collez l’extrait de code suivant pour suivre des fichiers dans un système de fichiers monté. Remplacez les valeurs entre chevrons (< >) par vos propres valeurs.

import wandb

# Initialiser un run
with wandb.init(entity="<entity>", project="<project>") as run:

  # Créer un objet artifact
  artifact = wandb.Artifact(name="<name>", type="<type>")

  # Ajouter une référence vers le chemin du système de fichiers
  artifact.add_reference("file:///path/to/dataset/")

  # Journaliser l’artifact (métadonnées uniquement)
  run.log_artifact(artifact)

Notez la triple barre oblique dans l’URL. Le premier composant est le préfixe file://, qui indique que vous utilisez des références de système de fichiers. Le deuxième composant est la racine / du système de fichiers. Les composants suivants forment le chemin du répertoire ou du fichier que vous souhaitez suivre. Par exemple, supposons que vous disposiez d’un système de fichiers monté sur /mount avec la structure suivante :

mount
|datasets/
  |-- mnist/
|models/
  |-- cnn/

Supposons que vous souhaitiez suivre le répertoire datasets/mnist/ en tant qu’artifact de jeu de données. Pour ce faire, vous pouvez utiliser l’extrait de code suivant.

import wandb

with wandb.init() as run:
  artifact = wandb.Artifact("mnist", type="dataset")
  artifact.add_reference("file:///mount/datasets/mnist/")
  run.log_artifact(artifact)

Cette opération crée un artifact de référence mnist:latest qui pointe vers les fichiers stockés dans /mount/datasets/mnist/.

Par défaut, W&B limite à 10 000 le nombre de fichiers lors de l’ajout d’une référence à un répertoire. Vous pouvez ajuster cette limite en spécifiant max_objects= lorsque vous appelez wandb.Artifact.add_reference().

De même, pour suivre un modèle stocké dans models/cnn/my_model.h5, vous pouvez utiliser l’extrait de code suivant :

import wandb

with wandb.init() as run:

  # Entraînement ici…

  # Écrire le modèle sur le disque

  # Créer un objet artifact
  model_artifact = wandb.Artifact("cnn", type="model")

  # Ajouter une référence au chemin du fichier du modèle
  model_artifact.add_reference("file:///mount/cnn/my_model.h5")

  # Journaliser l’artifact dans W&B
  run.log_artifact(model_artifact)

Télécharger un artifact depuis un système de fichiers externe

Téléchargez des fichiers depuis un système de fichiers référencé à l’aide des mêmes API que pour les artifacts non référencés :

Initialisez un run avec wandb.init().
Utilisez la méthode wandb.Run.use_artifact() pour indiquer l’artifact à télécharger.
Appelez la méthode wandb.Artifact.download() de l’artifact pour télécharger les fichiers depuis le système de fichiers référencé

with wandb.init() as run:
  artifact = run.use_artifact("entity/project/mnist:latest", type="dataset")
  artifact_dir = artifact.download()

W&B copie le contenu de /mount/datasets/mnist dans le répertoire artifacts/mnist:v0/.

Artifact.download() lève une erreur s’il ne parvient pas à reconstruire l’artifact. Par exemple, si un artifact contient une référence à un fichier qui a été écrasé, Artifact.download() lève une erreur, car l’artifact ne peut plus être reconstruit.

​Suivre un artifact dans un bucket externe

​Télécharger un artifact depuis un bucket externe

​Ajouter et télécharger une référence externe depuis un bucket

​Identifiants de stockage cloud

​Suivre un artifact dans un système de fichiers

​Télécharger un artifact depuis un système de fichiers externe

Suivre un artifact dans un bucket externe

Télécharger un artifact depuis un bucket externe

Ajouter et télécharger une référence externe depuis un bucket

Identifiants de stockage cloud

Suivre un artifact dans un système de fichiers

Télécharger un artifact depuis un système de fichiers externe