Créer un artifact

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.

Construire un artifact

Construisez un W&B Artifact en trois étapes :

Créez un objet artifact Python avec `wandb.Artifact()`

Initialisez la classe 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 mémorable.
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.

Copiez-collez l’extrait de code suivant pour créer un objet artifact. Remplacez les espaces réservés "artifact-name" et "artifact-type" par vos propres valeurs :

import wandb

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

Les Artifacts ne peuvent pas porter le même nom, même s’ils ont des types différents. Par exemple, vous ne pouvez pas créer un artifact nommé cats de type dataset et un autre artifact nommé cats de type model.

Vous pouvez aussi fournir une description, des métadonnées, un algorithme de digest et d’autres paramètres lorsque vous initialisez un objet artifact. Par exemple, l’extrait de code suivant crée un objet artifact avec un nom, un type, une description, des métadonnées et un algorithme de digest :

import wandb
# Créer un objet artifact
artifact = wandb.Artifact(
    name="my-dataset",
    type="dataset",
    description="This is my dataset artifact",
    metadata={"source": "generated", "version": 1},
    digest_algorithm="XXH128"
)

MD5 reste l’algorithme de digest par défaut. Avec le SDK Python W&B 0.29.0 ou une version ultérieure, définissez digest_algorithm="XXH128" pour activer un hachage plus rapide pour les nouveaux artifacts. Les artifact collections existantes qui utilisent MD5 continuent d’utiliser MD5. Les versions du SDK antérieures à 0.29.0 ne peuvent pas vérifier les artifacts contenant des entrées XXH128 avec Artifact.verify().

Pour plus d’informations sur les attributs et paramètres disponibles, consultez la définition de la classe wandb.Artifact dans le guide de Référence du SDK Python.

Ajoutez un ou plusieurs fichiers à l’artifact

Ajoutez des fichiers, des répertoires, des références URI externes (comme Amazon S3), etc. à votre objet artifact. Pour ajouter un seul fichier, utilisez la méthode Artifact.add_file() de l’objet artifact :

artifact.add_file(local_path="path/to/file.txt", name="artifact-name")

Pour ajouter un répertoire, utilisez la méthode Artifact.add_dir() :

artifact.add_dir(local_path="path/to/directory", name="artifact-name")

Voir la section suivante, Ajouter des fichiers à un artifact, pour en savoir plus sur l’ajout de différents types de fichiers à un artifact.

Enregistrez votre artifact sur le serveur W&B

Enregistrez votre artifact sur le serveur W&B. Utilisez la méthode 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.

Pour récapituler, l’extrait de code suivant montre comment créer un artifact de jeu de données, y ajouter un fichier et enregistrer l’artifact dans W&B :

import wandb

artifact = wandb.Artifact(name="artifact-name", type="artifact-type")
artifact.add_file(local_path="path/to/file.txt", name="filename")
artifact.add_dir(local_path="path/to/directory", name="filename")

with wandb.init(project="<project>", job_type="<job-type>") as run:
    run.log_artifact(artifact)

Chaque fois que vous enregistrez un artifact avec le même nom et le même type, W&B crée une nouvelle version de cet artifact. Pour plus d’informations, voir Créer une nouvelle version d’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,
            },
        )
        # ... add files to artifact a ...
        run.log_artifact(a)

Il est possible que la version d’artifact v0 n’ait pas un index de 0 dans ses métadonnées, car les artifacts peuvent être enregistrés dans un ordre arbitraire.

Ajouter des fichiers à un artifact

Les sections suivantes montrent comment ajouter différents types d’objets à un artifact. Supposons que vous disposiez d’un répertoire présentant la structure suivante à mesure que vous parcourez les exemples :

root-directory
| - hello.txt
| - images/
| -- | cat.png
| -- | dog.png
| - checkpoints/
| -- | model.h5
| - models/
| -- | model.h5

Ajouter un seul fichier

Utilisez 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="artifact-name", type="artifact-type")

# Ajouter un seul fichier
artifact.add_file(local_path="path/file.format")

Par exemple, supposons que vous ayez un fichier appelé 'hello.txt' dans votre répertoire de travail local.

artifact.add_file("hello.txt")

L’artifact contient désormais le contenu suivant :

hello.txt

Vous pouvez également passer un autre nom au paramètre 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"
    )

L’artifact est stocké sous la forme suivante :

new/path/hello_world.txt

Le tableau suivant montre comment différents appels d’API génèrent des contenus d’artifact différents :

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

Utilisez la méthode 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="artifact-name", type="artifact-type")

# Ajouter un répertoire local à l'artifact
artifact.add_dir(local_path="path/file.format", name="optional-prefix")

Le tableau suivant montre comment différents appels d’API génèrent des contenus d’artifact différents :

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

Artifacts suivent les sommes de contrôle et d’autres informations pour assurer la reproductibilité si l’URI utilise un schéma pris en charge par la bibliothèque W&B. Ajoutez une référence URI externe à un artifact avec la méthode 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")

Les Artifacts prennent actuellement en charge les schémas d’URI suivants :

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 artefacts depuis des exécutions parallèles

Pour les jeux de données volumineux ou l’entraînement distribué, plusieurs exécutions parallèles peuvent devoir alimenter un même artefact.

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):
    """
    Our writer job. Each writer will add one image to the 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)


# Lancer les 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)

Trouver le chemin d’accès des Artifacts enregistrés et d’autres métadonnées

L’extrait de code suivant montre comment utiliser l’API publique W&B pour lister les fichiers d’un run, y compris leur nom et leur URL. Remplacez l’espace réservé <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"File Name: {file.name}")
    print(f"File URL: {file.url}")
    print(f"Path to file in the bucket: {file.direct_url}")

Voir la classe File pour en savoir plus sur les attributs et méthodes disponibles.

Guides

Intégrations

Référence

Construire un artifact

Créez un objet artifact Python avec `wandb.Artifact()`

Ajoutez un ou plusieurs fichiers à l’artifact

Enregistrez votre artifact sur le serveur W&B

Ajouter des fichiers à un artifact

Ajouter un seul fichier

Ajouter plusieurs fichiers

Ajouter une référence URI

Ajouter des fichiers à des artefacts depuis des exécutions parallèles

Trouver le chemin d’accès des Artifacts enregistrés et d’autres métadonnées

​Construire un artifact

​Créez un objet artifact Python avec wandb.Artifact()

​Ajoutez un ou plusieurs fichiers à l’artifact

​Enregistrez votre artifact sur le serveur W&B

​Ajouter des fichiers à un artifact

​Ajouter un seul fichier

​Ajouter plusieurs fichiers

​Ajouter une référence URI

​Ajouter des fichiers à des artefacts depuis des exécutions parallèles

​Trouver le chemin d’accès des Artifacts enregistrés et d’autres métadonnées

Construire un artifact

Créez un objet artifact Python avec `wandb.Artifact()`

Ajoutez un ou plusieurs fichiers à l’artifact

Enregistrez votre artifact sur le serveur W&B

Ajouter des fichiers à un artifact

Ajouter un seul fichier

Ajouter plusieurs fichiers

Ajouter une référence URI

Ajouter des fichiers à des artefacts depuis des exécutions parallèles

Trouver le chemin d’accès des Artifacts enregistrés et d’autres métadonnées