Utilisez le W&B Python SDK pour créer des Artifacts à partir de W&B Runs. Vous pouvez ajouter des fichiers, des répertoires, des URI et des fichiers issus de runs parallèles aux Artifacts. Après avoir ajouté un fichier à un Artifact, enregistrez l’Artifact sur le serveur W&B ou sur votre propre serveur privé. Chaque Artifact est associé à un run.
Pour savoir comment suivre des fichiers externes, tels que des fichiers stockés dans Amazon S3, voir la page Suivre les fichiers externes.
Construisez un W&B Artifact en trois étapes :
- Créer un objet Python d’artifact avec
wandb.Artifact()
- Ajouter un ou plusieurs fichiers à l’artifact
- Enregistrer votre artifact sur le serveur W&B
1. Créez un objet artifact Python avec wandb.Artifact()
wandb.Artifact() pour créer un objet artifact. Spécifiez les paramètres suivants :
- Nom : le nom de votre artifact. Il doit être unique, descriptif et facile à retenir.
- Type : le type de l’artifact. Il doit être simple, descriptif et correspondre à une seule étape de votre pipeline de machine learning. Parmi les types d’artifact courants, on trouve
'dataset' ou 'model'.
W&B utilise le “nom” et le “type” que vous fournissez pour créer un graphe orienté acyclique dans l’application W&B. Voir Explore and traverse artifact graphs pour plus d’informations. Les Artifacts ne peuvent pas avoir le même nom, quel que soit leur type. En d’autres termes, vous ne pouvez pas créer un artifact nommé cats de type dataset et un autre artifact portant le même nom de type model.
wandb.Artifact dans le guide de Référence du SDK Python.
Copiez-collez l’extrait de code suivant pour créer un objet artifact. Remplacez les espaces réservés <name> et <type> par vos propres valeurs :
import wandb
# Créer un objet artifact
artifact = wandb.Artifact(name="<name>", type="<type>")
2. Ajoutez un ou plusieurs fichiers à l’artifact
Artifact.add_file() de l’objet artifact :
artifact.add_file(local_path="path/to/file.txt", name="<name>")
Artifact.add_dir() :
artifact.add_dir(local_path="path/to/directory", name="<name>")
3. Enregistrez votre artifact sur le serveur W&B
wandb.Run.log_artifact() de l’objet run pour enregistrer l’artifact.
with wandb.init(project="<project>", job_type="<job-type>") as run:
run.log_artifact(artifact)
Quand utiliser wandb.Run.log_artifact() ou Artifact.save()
- Utilisez
wandb.Run.log_artifact() pour créer un nouvel artifact et l’associer à un run spécifique.
- Utilisez
Artifact.save() pour mettre à jour un artifact existant sans créer de nouveau run.
import wandb
artifact = wandb.Artifact(name="<name>", type="<type>")
artifact.add_file(local_path="path/to/file.txt", name="<name>")
artifact.add_dir(local_path="path/to/directory", name="<name>")
with wandb.init(project="<project>", job_type="<job-type>") as run:
run.log_artifact(artifact)
W&B effectue les appels wandb.Run.log_artifact() de manière asynchrone afin d’optimiser les téléversements. Cela peut entraîner un comportement inattendu lors de l’enregistrement d’artifacts dans une boucle. Par exemple :with wandb.init() as run:
for i in range(10):
a = wandb.Artifact(name = "race",
type="dataset",
metadata={
"index": i,
},
)
# ... ajouter des fichiers à l'artifact a ...
run.log_artifact(a)
Ajouter des fichiers à un artifact
root-directory
| - hello.txt
| - images/
| -- | cat.png
| -- | dog.png
| - checkpoints/
| -- | model.h5
| - models/
| -- | model.h5
wandb.Artifact.add_file() pour ajouter un fichier local à un artifact. Indiquez le chemin local du fichier dans le paramètre local_path :
import wandb
# Initialiser un objet artifact
artifact = wandb.Artifact(name="<name>", type="<type>")
# Ajouter un fichier unique
artifact.add_file(local_path="path/file.format")
'hello.txt' dans votre répertoire de travail local.
artifact.add_file("hello.txt")
name pour renommer le fichier au sein de l’objet artifact lui-même. En reprenant l’exemple précédent :
artifact.add_file(
local_path="hello.txt",
name="new/path/hello_world.txt"
)
| Appel d’API | artifact obtenu |
|---|
artifact.new_file('hello.txt') | hello.txt |
artifact.add_file('model.h5') | model.h5 |
artifact.add_file('checkpoints/model.h5') | model.h5 |
artifact.add_file('model.h5', name='models/mymodel.h5') | models/mymodel.h5 |
Ajouter plusieurs fichiers
wandb.Artifact.add_dir() pour ajouter plusieurs fichiers d’un répertoire local à un artifact. Spécifiez le chemin local du répertoire à l’aide du paramètre local_path.
import wandb
# Initialiser un objet artifact
artifact = wandb.Artifact(name="<name>", type="<type>")
# Ajouter un répertoire local à l'artifact
artifact.add_dir(local_path="path/file.format", name="optional-prefix")
| Appel d’API | artifact obtenu |
|---|
artifact.add_dir('images') | cat.png
dog.png
|
artifact.add_dir('images', name='images') | images/cat.png
images/dog.png
|
Ajouter une référence URI
wandb.Artifact.add_reference(). Remplacez la chaîne 'uri' par votre propre URI. Vous pouvez également indiquer, pour le paramètre nom, le chemin souhaité dans l’artifact.
# Ajouter une référence URI
artifact.add_reference(uri="uri", name="optional-name")
http(s):// : chemin d’accès vers un fichier accessible via HTTP. L’artifact suit les sommes de contrôle sous forme d’ETags et les métadonnées de taille si le serveur HTTP prend en charge les en-têtes de réponse ETag et Content-Length.s3:// : chemin d’accès vers un objet ou un préfixe d’objet dans S3. L’artifact suit les sommes de contrôle et les informations de gestion des versions (si la gestion des versions des objets est activée pour le bucket) des objets référencés. Les préfixes d’objet sont étendus pour inclure les objets qu’ils contiennent, dans la limite de 10 000 objets.gs:// : chemin d’accès vers un objet ou un préfixe d’objet dans GCS. L’artifact suit les sommes de contrôle et les informations de gestion des versions (si la gestion des versions des objets est activée pour le bucket) des objets référencés. Les préfixes d’objet sont étendus pour inclure les objets qu’ils contiennent, dans la limite de 10 000 objets.
Le tableau suivant montre comment différents appels d’API génèrent différents contenus d’artifact :
| Appel d’API | Contenu de l’artifact obtenu |
|---|
artifact.add_reference('s3://my-bucket/model.h5') | model.h5 |
artifact.add_reference('s3://my-bucket/checkpoints/model.h5') | model.h5 |
artifact.add_reference('s3://my-bucket/model.h5', name='models/mymodel.h5') | models/mymodel.h5 |
artifact.add_reference('s3://my-bucket/images') | cat.png
dog.png
|
artifact.add_reference('s3://my-bucket/images', name='images') | images/cat.png
images/dog.png
|
Ajouter des fichiers à des artifacts à partir de runs parallèles
import wandb
import time
# Cet exemple utilise Ray pour exécuter des runs en parallèle
# à des fins de démonstration.
import ray
ray.init()
artifact_type = "dataset"
artifact_name = "parallel-artifact"
table_name = "distributed_table"
parts_path = "parts"
num_parallel = 5
# Chaque lot de writers parallèles doit avoir son propre
# nom de groupe unique.
group_name = "writer-group-{}".format(round(time.time()))
@ray.remote
def train(i):
"""
Notre job d'écriture. Chaque writer ajoutera une image à l'artifact.
"""
with wandb.init(group=group_name) as run:
artifact = wandb.Artifact(name=artifact_name, type=artifact_type)
# Ajouter des données à un tableau wandb.
table = wandb.Table(columns=["a", "b", "c"], data=[[i, i * 2, 2**i]])
# Ajouter le tableau dans un dossier de l'artifact
artifact.add(table, "{}/table_{}".format(parts_path, i))
# L'upsert de l'artifact crée ou ajoute des données à l'artifact
run.upsert_artifact(artifact)
# Lancez vos runs en parallèle
result_ids = [train.remote(i) for i in range(num_parallel)]
# Attendre tous les writers pour s'assurer que leurs fichiers ont
# été ajoutés avant de finaliser l'artifact.
ray.get(result_ids)
# Une fois tous les writers terminés, finaliser l'artifact
# pour le marquer comme prêt.
with wandb.init(group=group_name) as run:
artifact = wandb.Artifact(artifact_name, type=artifact_type)
# Créer une "PartitionTable" pointant vers le dossier de tableaux
# et l'ajouter à l'artifact.
artifact.add(wandb.data_types.PartitionedTable(parts_path), table_name)
# finish_artifact finalise l'artifact, interdisant les futurs "upserts"
# sur cette version.
run.finish_artifact(artifact)
<entity/project/run-id> par vos propres valeurs :
from wandb.apis.public.files import Files
from wandb.apis.public.api import Api
# Exemple d'objet run
run = Api().run("<entity/project/run-id>")
# Créer un objet Files pour itérer sur les fichiers du run
files = Files(api.client, run)
# Itérer sur les fichiers
for file in files:
print(f"Nom du fichier : {file.name}")
print(f"URL du fichier : {file.url}")
print(f"Chemin vers le fichier dans le bucket : {file.direct_url}")
