Suivre des fichiers externes

Suivez les fichiers enregistrés dans un bucket externe, un serveur de fichiers HTTP ou un partage NFS.

Utilisez des artifacts de référence pour suivre et utiliser des fichiers enregistrés en dehors des serveurs W&B. Les solutions courantes de stockage externe incluent : CoreWeave AI Object 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. La principale différence est que les artifacts de référence ne contiennent que des métadonnées sur les fichiers, telles que leur taille et leurs sommes 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 comme 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 parcourir l’historique versionné de votre artifact. Cependant, l’UI ne peut pas afficher de médias enrichis tels que des images ou de l’audio, car les données elles-mêmes ne sont pas contenues dans l’artifact.

Si vous enregistrez un artifact qui ne suit pas de fichiers externes, W&B enregistre les fichiers de l’artifact sur les serveurs W&B. Il s’agit du comportement par défaut lorsque vous enregistrez des artifacts avec le W&B Python SDK.

Si vous enregistrez un artifact qui suit des fichiers externes, W&B enregistre des métadonnées sur l’objet, telles que l’ETag et la taille de l’objet. Si la gestion des versions des objets est activée sur le bucket, l’ID de version est également enregistré.

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

​

Suivre un artifact dans un bucket externe

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

1. Initialisez un run avec wandb.init().
2. Créez un objet artifact avec wandb.Artifact().
3. Indiquez la référence au chemin du bucket avec la méthode wandb.Artifact.add_reference() de l’objet artifact.
4. Enregistrez 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")

  # Enregistrer les métadonnées de l'artifact
  run.log_artifact(artifact)

Par exemple, supposons que votre bucket ait la structure de répertoires suivante :

s3://my-bucket

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

Le répertoire datasets/mnist/ contient une collection d’images. Pour suivre le répertoire d’images datasets/mnist/ en tant qu’artifact de jeu de données, spécifiez :

1. Donnez un nom à l’artifact, par exemple "mnist".
2. Définissez le paramètre type sur "dataset" lorsque vous créez l’objet artifact (wandb.Artifact(type="dataset")).
3. Indiquez le chemin du répertoire datasets/mnist/ sous forme d’URI Amazon S3 (s3://my-bucket/datasets/mnist/) lorsque vous appelez wandb.Artifact.add_reference().
4. Enregistrez 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 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 versionné de votre artifact. La W&B App n’affiche pas les médias enrichis tels que les images, l’audio, etc., car les données elles-mêmes ne sont pas contenues dans l’artifact.

Les W&B Artifacts prennent en charge toute interface compatible avec Amazon S3, y compris CoreWeave Storage et MinIO. Les scripts décrits ci-dessous fonctionnent tels quels avec les deux fournisseurs lorsque vous définissez la variable d’environnement AWS_S3_ENDPOINT_URL de sorte qu’elle pointe vers votre serveur CoreWeave Storage ou MinIO.

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

​

Télécharger un artifact depuis un bucket externe

W&B récupère les fichiers du bucket sous-jacent lorsqu’il télécharge un artifact de référence à l’aide des métadonnées enregistrées au moment où l’artifact est enregistré. Si la gestion des versions des objets est activée sur votre bucket, W&B récupère la version de l’objet correspondant à l’état du fichier au moment où l’artifact a été enregistré. À mesure que le contenu de votre bucket évolue, vous pouvez toujours pointer vers la version exacte de vos données sur laquelle un modèle a été entraîné, car l’artifact sert d’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 des artifacts sont les mêmes pour les artifacts de référence et les autres artifacts :

import wandb

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

W&B recommande d’activer la ‘gestion des versions des objets’ sur vos buckets de stockage si vous écrasez des fichiers dans le cadre de votre flux de travail.

Si 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 le fichier a été écrasé après l’enregistrement de l’artifact.

Selon votre cas d’utilisation, lisez les instructions pour activer la gestion des versions des objets : AWS, Google Cloud, Azure.

​

Ajouter puis télécharger un élément externe depuis un bucket

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

import boto3
import wandb

with wandb.init() as run:
  # 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 du 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 du 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()

Voir les Reports suivants pour un guide pas à pas complet expliquant comment suivre des Artifacts par référence avec Google Cloud ou Azure :

• Guide pour suivre des Artifacts par référence avec Google Cloud
• Travailler avec des Artifacts de référence dans Microsoft Azure

​

Identifiants pour le stockage cloud

W&B utilise le mécanisme par défaut pour rechercher les identifiants correspondant au fournisseur cloud que vous utilisez. Consultez la documentation de votre fournisseur cloud pour en savoir plus sur les identifiants utilisés :

Fournisseur cloud	Documentation sur les identifiants
CoreWeave AI Object Storage	documentation CoreWeave AI Object Storage
AWS	documentation Boto3
Google Cloud	documentation Google Cloud
Azure	documentation 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 pour qu’elle corresponde à la région du bucket.

Les médias enrichis tels que les images, l’audio, la vidéo et les nuages de points peuvent ne pas s’afficher correctement dans l’UI de l’application selon la configuration CORS de votre bucket. L’ajout de app.wandb.ai à la liste d’autorisation dans les paramètres CORS de votre bucket permettra à W&B App d’afficher correctement ces médias enrichis.

Si des médias enrichis tels que des images, de l’audio, de la vidéo et des nuages de points ne s’affichent pas dans l’UI de l’application, assurez-vous que app.wandb.ai figure dans la liste d’autorisation de la politique CORS de votre bucket.

​

Suivre un artifact dans un système de fichiers

Une pratique courante pour accéder aux jeux de données consiste à exposer un point de montage NFS vers un système de fichiers distant sur toutes les machines exécutant des tâches d’entraînement. Cela peut constituer une alternative à un bucket de stockage cloud, car du point de vue du script d’entraînement, les fichiers apparaissent comme des fichiers locaux dans votre système de fichiers.

Pour suivre un artifact dans un système de fichiers :

1. Initialisez un run avec wandb.init().
2. Créez un objet artifact avec wandb.Artifact().
3. Indiquez la référence vers le chemin du système de fichiers à l’aide de la méthode wandb.Artifact.add_reference() de l’objet artifact.
4. Consignez les métadonnées de l’artifact dans le journal avec run.log_artifact().

Faites un copier-coller de 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 au 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 les trois barres obliques dans l’URL. Le premier composant est le préfixe file://, qui indique l’utilisation de références au système de fichiers. Le deuxième composant est la racine / du système de fichiers. Les composants restants correspondent au chemin vers le répertoire ou le fichier que vous souhaitez suivre.

Par exemple, supposons que vous ayez un système de fichiers monté sur /mount avec la structure suivante :

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

Vous souhaitez 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)

Cela 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 impose une limite de 10 000 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 modèle
  model_artifact.add_reference("file:///mount/cnn/my_model.h5")

  # Enregistrer 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 :

1. Initialisez un run avec wandb.init().
2. Utilisez la méthode wandb.Run.use_artifact() pour spécifier l’artifact que vous souhaitez télécharger.
3. 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() renvoie une erreur s’il ne peut pas reconstruire l’artifact. Par exemple, si un artifact contient une référence à un fichier qui a été remplacé, Artifact.download() renvoie une erreur, car l’artifact ne peut plus être reconstruit.