Créer une version d’artifact

Créez une nouvelle version d’artifact avec un seul run ou de manière collaborative avec des runs distribués. Vous pouvez aussi créer une nouvelle version d’artifact à partir d’une version précédente : on parle alors d’artifact incrémentiel.

Nous vous recommandons de créer un artifact incrémentiel lorsque vous devez modifier un sous-ensemble de fichiers d’un artifact dont la taille totale est nettement plus importante.

Créer de nouvelles versions d’artifact à partir de zéro

Il existe deux façons de créer une nouvelle version d’artifact : à partir d’un run unique ou à partir de runs distribués. Elles se définissent comme suit :

Run unique : un seul run fournit toutes les données d’une nouvelle version. Il s’agit du cas le plus courant, particulièrement adapté lorsque le run recrée entièrement les données nécessaires. Par exemple : générer des modèles enregistrés ou des prédictions de modèle dans un tableau à des fins d’analyse.
Runs distribués : un ensemble de runs fournit collectivement toutes les données d’une nouvelle version. Ce cas convient particulièrement aux jobs distribués dans lesquels plusieurs runs génèrent des données, souvent en parallèle. Par exemple : évaluer un modèle de manière distribuée et générer les prédictions.

Si vous transmettez à l’API wandb.Artifact un nom qui n’existe pas dans votre projet, W&B crée un nouvel artifact et lui attribue l’alias v0. Lorsque vous journalisez à nouveau dans le même artifact, W&B calcule une somme de contrôle de son contenu. Si l’artifact a été modifié, W&B enregistre une nouvelle version v1. Si vous transmettez à l’API wandb.Artifact un nom et un type d’artifact correspondant à un artifact existant dans votre projet, W&B récupère cet artifact. L’artifact récupéré aura une version supérieure à 1.

Comparaison des flux de travail d'artifact

Run unique

Journalisez une nouvelle version d’un artifact avec un seul run qui produit tous les fichiers de l’artifact. C’est le cas lorsqu’un seul run génère l’ensemble des fichiers de l’artifact. Selon votre cas d’usage, sélectionnez l’un des onglets ci-dessous pour créer une nouvelle version d’artifact :

Utilisez wandb.Run.log_artifact() pour marquer explicitement un artifact comme sortie d’un run.Utilisez Artifact.save() comme méthode de commodité. Si un run est actif, W&B journalise l’artifact dans ce run. Sinon, W&B crée automatiquement un run et y journalise l’artifact.

Suivre comme sortie de run
Enregistrer directement

Utilisez wandb.Run.log_artifact() pour associer explicitement l’artifact à un run :

Créez un run avec wandb.init().
Créez un nouvel artifact ou récupérez un artifact existant avec wandb.Artifact.
Ajoutez des fichiers à l’artifact avec wandb.Artifact.add_file().
Journalisez l’artifact dans le run avec wandb.Run.log_artifact().

with wandb.init() as run:
    artifact = wandb.Artifact("artifact_name", "artifact_type")

    # Ajoutez des fichiers et des ressources à l’artifact avec
    # `.add`, `.add_file`, `.add_dir` et `.add_reference`
    artifact.add_file("image1.png")
    run.log_artifact(artifact)

Utilisez wandb.Artifact.save() comme méthode de commodité pour persister l’artifact à partir du contexte actuel :

Créez un nouvel artifact ou récupérez un artifact existant avec wandb.Artifact.
Ajoutez des fichiers à l’artifact avec wandb.Artifact.add_file().
Enregistrez l’artifact avec wandb.Artifact.save().

artifact = wandb.Artifact("artifact_name", "artifact_type")
# Ajoutez des fichiers et des ressources à l’artifact avec
# `.add`, `.add_file`, `.add_dir` et `.add_reference`
artifact.add_file("image1.png")
artifact.save()

Runs distribués

Permettez à un ensemble de runs de collaborer sur une version avant de la valider. Contrairement au mode run unique décrit ci-dessus, où un seul run fournit toutes les données d’une nouvelle version.

Chaque run de l’ensemble doit connaître le même ID unique (appelé distributed_id) pour collaborer sur la même version. Par défaut, s’il est défini, W&B utilise comme distributed_id le group du run, tel que défini par wandb.init(group=GROUP).
Un run final doit « valider » la version, ce qui verrouille définitivement son état.
Utilisez upsert_artifact pour ajouter du contenu à l’artifact collaboratif et finish_artifact pour finaliser la validation.

Prenons l’exemple suivant. Différents runs (désignés ci-dessous par Run 1, Run 2 et Run 3) ajoutent chacun un fichier image différent au même artifact avec upsert_artifact.

Run 1

with wandb.init() as run:
    artifact = wandb.Artifact("artifact_name", "artifact_type")
    # Ajoutez des fichiers et des ressources à l’artifact avec
    # `.add`, `.add_file`, `.add_dir` et `.add_reference`
    artifact.add_file("image1.png")
    run.upsert_artifact(artifact, distributed_id="my_dist_artifact")

Run 2

with wandb.init() as run:
    artifact = wandb.Artifact("artifact_name", "artifact_type")
    # Ajoutez des fichiers et des ressources à l’artifact avec
    # `.add`, `.add_file`, `.add_dir` et `.add_reference`
    artifact.add_file("image2.png")
    run.upsert_artifact(artifact, distributed_id="my_dist_artifact")

Run 3

Doit être exécuté une fois les runs 1 et 2 terminés. Le run qui appelle wandb.Run.finish_artifact() peut ajouter des fichiers à l’artifact, mais ce n’est pas obligatoire.

with wandb.init() as run:
    artifact = wandb.Artifact("artifact_name", "artifact_type")
    # Ajouter des fichiers et des ressources à l’artifact
    # `.add`, `.add_file`, `.add_dir`, and `.add_reference`
    artifact.add_file("image3.png")
    run.finish_artifact(artifact, distributed_id="my_dist_artifact")

Créer une nouvelle version d’artifact à partir d’une version existante

Créez une nouvelle version d’artifact en ajoutant, en modifiant ou en supprimant des fichiers dans une version d’artifact existante. W&B ne réindexe que les fichiers modifiés. La version obtenue est appelée artifact incrémentiel.

Gestion des versions d’artifacts incrémentiels

Pour créer un artifact incrémentiel, créez un brouillon à partir de n’importe quelle version d’artifact déjà validée. Vous pouvez ensuite modifier ce brouillon à l’aide de méthodes telles que Artifact.add_file(), Artifact.add_dir() et Artifact.remove(). Pour obtenir la liste complète des méthodes, consultez la documentation de référence de Artifact. Une fois vos modifications terminées, journalisez ou enregistrez le brouillon pour créer une nouvelle version d’artifact.

Au lieu de créer un artifact incrémentiel, vous pouvez créer un nouvel artifact de zéro. Cette approche exige toutefois que tous les fichiers de l’artifact soient disponibles sur votre disque local. Avec un artifact incrémentiel, vous pouvez ajouter, supprimer ou modifier des fichiers individuellement tout en réutilisant les fichiers inchangés de la version précédente de l’artifact.

Vous pouvez créer un artifact incrémentiel au sein d’un seul run ou à partir de plusieurs runs qui contribuent à la nouvelle version. Les sections suivantes décrivent la marche à suivre dans chacun de ces cas.

Run unique

Suivre comme entrée du run
Récupérer directement

Utilisez wandb.Run.use_artifact() lorsque le run actuel consomme l’artifact. W&B enregistre alors l’artifact comme entrée du run.

Récupérez la version de l’artifact avec wandb.Run.use_artifact().
Créez un brouillon avec Artifact.new_draft().
Ajoutez, supprimez ou modifiez des entrées dans le brouillon.
Journalisez le brouillon avec wandb.Run.log_artifact() pour créer une nouvelle version de l’artifact.

with wandb.init(job_type="modify dataset") as run:
    saved_artifact = run.use_artifact(
        "my_artifact:latest"
    )  # récupérer l’artifact et le déclarer comme entrée de votre run
    draft_artifact = saved_artifact.new_draft()  # créer une version brouillon

    # modifier un sous-ensemble de fichiers dans la version brouillon
    draft_artifact.add_file("file_to_add.txt")
    draft_artifact.remove("dir_to_remove/")
    run.log_artifact(
        draft_artifact
    )  # journaliser vos modifications pour créer une nouvelle version et la marquer comme sortie de votre run

Utilisez l’API publique pour récupérer un artifact sans l’enregistrer comme entrée d’un run.

Récupérez la version de l’artifact avec wandb.Api.artifact().
Créez un brouillon avec Artifact.new_draft().
Ajoutez, supprimez ou modifiez des entrées dans le brouillon.
Enregistrez la version brouillon avec Artifact.save() pour créer une nouvelle version de l’artifact.

client = wandb.Api()
saved_artifact = client.artifact("my_artifact:latest")  # charger votre artifact
draft_artifact = saved_artifact.new_draft()  # créer une version brouillon

# modifier un sous-ensemble de fichiers dans la version brouillon
draft_artifact.remove("deleted_file.txt")
draft_artifact.add_file("modified_file.txt")
draft_artifact.save()  # valider les modifications apportées au brouillon

Runs distribués

Utilisez Artifact.upsert_artifact() et Artifact.finish_artifact() lorsque plusieurs runs ajoutent des fichiers à une même version d’artifact. L’exemple suivant montre comment créer une nouvelle version d’artifact à partir de runs distribués, lorsque l’artifact sert d’entrée aux runs. La même approche s’applique lorsque l’artifact est récupéré directement avec l’API publique.

import wandb

project = "<project>"
artifact_name = "<distributed-artifact-name>"
distributed_id = "dataset-build-001"

worker_files = [
    ("data/shards/worker-0.txt", "shards/worker-0.txt"),
    ("data/shards/worker-1.txt", "shards/worker-1.txt"),
]

for local_path, artifact_path in worker_files:
    with wandb.init(project=project, group=distributed_id) as run:
        artifact = wandb.Artifact(artifact_name, type="dataset")
        artifact.add_file(local_path, name=artifact_path)
        run.upsert_artifact(artifact, distributed_id=distributed_id)

with wandb.init(project=project, group=distributed_id) as run:
    artifact = wandb.Artifact(artifact_name, type="dataset")
    logged = run.finish_artifact(
        artifact,
        aliases=["latest"],
        distributed_id=distributed_id,
    )
    logged.wait()

Utilisez Artifact.new_draft() lorsque vous modifiez une version d’artifact déjà validée.Utilisez Artifact.upsert_artifact() et Artifact.finish_artifact() lorsque plusieurs runs doivent contribuer à une même version d’artifact avant sa finalisation.

​Créer de nouvelles versions d’artifact à partir de zéro

​Run unique

​Runs distribués

​Run 1

​Run 2

​Run 3

​Créer une nouvelle version d’artifact à partir d’une version existante

​Run unique

​Runs distribués

Créer de nouvelles versions d’artifact à partir de zéro

Run unique

Runs distribués

Run 1

Run 2

Run 3

Créer une nouvelle version d’artifact à partir d’une version existante

Run unique

Runs distribués