Créer un artifact - CoreWeave Docs

Utilisez le SDK Python W&B pour créer des artifacts à partir de runs W&B. Vous pouvez ajouter aux artifacts des fichiers, des répertoires, des URI et des fichiers issus de runs parallèles. Une fois un fichier ajouté à 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, comme des fichiers stockés dans Amazon S3, consultez la page Suivre des fichiers externes.

Construire un artifact

Construisez un artifact W&B en trois étapes :

Créer un objet Python artifact 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 facile à retenir.
Type : le type d’artifact. Il doit être simple, descriptif et correspondre à une seule étape de votre pipeline de machine learning. Parmi les types d’artifacts courants figurent 'dataset' et 'model'.

W&B utilise le « nom » et le « type » que vous fournissez pour créer un graphe orienté acyclique dans la W&B App. Pour plus d’informations, consultez Explorer et parcourir les graphes d’artifacts.

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")

Deux artifacts ne peuvent pas porter le même nom, même s’ils sont de 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.

Lorsque vous initialisez un objet artifact, vous pouvez également fournir une description, des métadonnées, un algorithme de digest et d’autres paramètres facultatifs. 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. À partir du SDK Python W&B 0.29.0, définissez digest_algorithm="XXH128" pour bénéficier d’un hachage plus rapide sur les nouveaux artifacts. Les collections d’artifacts existantes qui utilisent MD5 continuent d’utiliser MD5. Les versions du SDK antérieures à 0.29.0 ne peuvent pas vérifier avec Artifact.verify() les artifacts contenant des entrées XXH128.

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.

Ajouter 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")

Pour plus d’informations sur l’ajout de différents types de fichiers à un artifact, consultez la section suivante, Ajouter des fichiers à un artifact.

Enregistrer votre artifact sur le serveur W&B

Enregistrez votre artifact sur le serveur W&B. Pour ce faire, utilisez la méthode wandb.Run.log_artifact() de l’objet run.

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ésumer, l’extrait de code suivant montre comment créer un artifact de jeu de données, y ajouter un fichier et l’enregistrer 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 journalisez 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 exécute les appels à wandb.Run.log_artifact() de manière asynchrone afin d’optimiser les téléversements. Cela peut entraîner un comportement inattendu lorsque vous journalisez des 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)

La version d’artifact v0 n’aura pas forcément l’index 0 dans ses métadonnées, car les artifacts peuvent être journalisés dans un ordre arbitraire.

Ajouter des fichiers à un artifact

Les sections suivantes montrent comment ajouter différents types d’objets à un artifact. Pour suivre les exemples, partez du principe que vous disposez d’un répertoire présentant la structure suivante :

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 seul 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 nommé 'hello.txt' dans votre répertoire de travail local.

artifact.add_file("hello.txt")

L’artifact contient désormais les éléments suivants :

hello.txt

Vous pouvez également transmettre un autre nom au paramètre name pour renommer le fichier dans l’objet artifact lui-même. Pour reprendre l’exemple précédent :

artifact.add_file(
    local_path="hello.txt", 
    name="new/path/hello_world.txt"
    )

L’artifact est stocké comme suit :

new/path/hello_world.txt

Le tableau suivant montre le contenu de l’artifact obtenu selon l’appel d’API utilisé :

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 à un artifact plusieurs fichiers d’un répertoire local. Indiquez le chemin local du répertoire dans le 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 le contenu de l’artifact varie selon l’appel d’API utilisé :

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

Les artifacts enregistrent les sommes de contrôle et d’autres informations à des fins de 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, dans le paramètre name, le chemin souhaité au sein de l’artifact.

# Ajouter une référence URI
artifact.add_reference(uri="uri", name="optional-name")

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

http(s):// : chemin vers un fichier accessible via HTTP. L’artifact suit les sommes de contrôle sous forme d’ETags ainsi que 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 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 sur le bucket) des objets référencés. Les préfixes d’objet sont développés de façon à inclure les objets situés sous le préfixe, dans la limite de 10 000 objets.
gs:// : chemin 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 sur le bucket) des objets référencés. Les préfixes d’objet sont développés de façon à inclure les objets situés sous le préfixe, dans la limite de 10 000 objets.

Le tableau suivant montre le contenu de l’artifact obtenu selon l’appel d’API utilisé :

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 aux artifacts depuis des runs parallèles

Dans le cas de jeux de données volumineux ou d’un entraînement distribué, plusieurs runs parallèles peuvent devoir contribuer à un même artifact.

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 rédacteurs parallèles doit avoir
# un 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 à un dossier de l’artifact
        artifact.add(table, "{}/table_{}".format(parts_path, i))

        # L’upsert de l’artifact crée l’artifact ou y ajoute des données
        run.upsert_artifact(artifact)


# Lancer les runs en parallèle
result_ids = [train.remote(i) for i in range(num_parallel)]

# Attendre la fin de tous les rédacteurs pour s’assurer que leurs fichiers
# ont bien été ajoutés avant de finaliser l’artifact.
ray.get(result_ids)

# Une fois tous les rédacteurs 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 des tableaux
    # et l’ajouter à l’artifact.
    artifact.add(wandb.data_types.PartitionedTable(parts_path), table_name)

    # finish_artifact finalise l’artifact et interdit tout « upsert » ultérieur
    # sur cette version.
    run.finish_artifact(artifact)

Trouver le chemin des artifacts journalisé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, avec leurs noms et leurs 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 parcourir les fichiers du run
files = Files(api.client, run)

# Parcourir 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}")

Consultez la classe File pour plus d’informations sur les attributs et les méthodes disponibles.

​Construire un artifact

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

​Ajouter un ou plusieurs fichiers à l’artifact

​Enregistrer 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 aux artifacts depuis des runs parallèles

​Trouver le chemin des artifacts journalisés et d’autres métadonnées

Construire un artifact

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

Ajouter un ou plusieurs fichiers à l’artifact

Enregistrer 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 aux artifacts depuis des runs parallèles

Trouver le chemin des artifacts journalisés et d’autres métadonnées