> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

<Note>
  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é.
</Note>

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

<h2 id="track-an-artifact-in-an-external-bucket">
  Suivre un artifact dans un bucket externe
</h2>

Utilisez le SDK Python 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 vers le chemin du bucket à l'aide de la méthode `wandb.Artifact.add_reference()` de l'objet artifact.
4. Journalisez les métadonnées de l'artifact avec `run.log_artifact()`.

```python theme={"system"}
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 :

```text theme={"system"}
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 :

1. Fournissez un nom pour l’artifact, par exemple `"mnist"`.
2. Définissez le paramètre `type` sur `"dataset"` lors de la construction de l’objet artifact (`wandb.Artifact(type="dataset")`).
3. 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()`.
4. Journalisez l’artifact avec `run.log_artifact()`.

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

```python theme={"system"}
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](/fr/products/wandb/artifacts/explore-and-traverse-an-artifact-graph) 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.

<Note>
  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).
</Note>

<Warning>
  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()`.
</Warning>

<h2 id="download-an-artifact-from-an-external-bucket">
  Télécharger un artifact depuis un bucket externe
</h2>

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 :

```python theme={"system"}
import wandb

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

<Note>
  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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/manage-versioning-examples.html), [Google Cloud](https://cloud.google.com/storage/docs/using-object-versioning#set), [Azure](https://learn.microsoft.com/azure/storage/blobs/versioning-enable).
</Note>

<h2 id="add-and-download-an-external-from-a-bucket">
  Ajouter et télécharger une référence externe depuis un bucket
</h2>

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 :

```python theme={"system"}
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 :

```python theme={"system"}
import wandb

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

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

  * [Guide du suivi des artifacts par référence avec Google Cloud](https://forge.coreweave.com/wandb/stacey/artifacts/reports/Tracking-Artifacts-by-Reference--Vmlldzo1NDMwOTE)
  * [Utiliser des artifacts de référence dans Microsoft Azure](https://forge.coreweave.com/wandb/andrea0/azure-2023/reports/Efficiently-Harnessing-Microsoft-Azure-Blob-Storage-with-Weights-Biases--Vmlldzo0NDA2NDgw)
</Note>

<h2 id="cloud-storage-credentials">
  Identifiants de stockage cloud
</h2>

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](/products/storage/object-storage/auth-access/manage-access-keys/create-keys) |
| Backblaze B2 Cloud Storage | [Documentation sur les clés d’application Backblaze B2](https://www.backblaze.com/docs/cloud-storage-application-keys) |
| AWS | [Documentation de Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials) |
| Google Cloud | [Documentation de Google Cloud](https://cloud.google.com/docs/authentication/provide-credentials-adc) |
| Azure | [Documentation d’Azure](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python) |

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.

<Warning>
  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.
</Warning>

<h2 id="track-an-artifact-in-a-filesystem">
  Suivre un artifact dans un système de fichiers
</h2>

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 :

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 système de fichiers à l'aide de la méthode `wandb.Artifact.add_reference()` de l'objet artifact.
4. 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.

```python theme={"system"}
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 :

```text theme={"system"}
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.

```python theme={"system"}
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/`.

<Warning>
  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()`.
</Warning>

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

```python theme={"system"}
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)
```

<h2 id="download-an-artifact-from-an-external-filesystem">
  Télécharger un artifact depuis un système de fichiers externe
</h2>

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 indiquer l'artifact à 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é

```python theme={"system"}
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/`.

<Info>
  `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.
</Info>