Créer une version d'artefact

Créez une nouvelle version d’artefact à partir d’un seul run ou de manière collaborative avec des runs distribués. Vous pouvez également créer une nouvelle version d’artefact à partir d’une version précédente, appelée artefact incrémentiel.

Nous vous recommandons de créer un artefact incrémentiel lorsque vous devez appliquer des modifications à un sous-ensemble de fichiers d’un artefact, en particulier si l’artefact d’origine est nettement plus volumineux.

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

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

Run unique : un seul run fournit toutes les données d’une nouvelle version. C’est le cas le plus courant, et il convient le mieux 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 pour analyse.
Runs distribués : un ensemble de runs fournit collectivement toutes les données d’une nouvelle version. Ce mode convient le mieux aux jobs distribués comportant plusieurs runs qui génèrent des données, souvent en parallèle. Par exemple : évaluer un modèle de manière distribuée et produire les prédictions.

W&B créera un nouvel artefact et lui attribuera un alias v0 si vous transmettez à l’API wandb.Artifact un nom qui n’existe pas dans votre projet. W&B calcule une somme de contrôle du contenu lorsque vous journalisez de nouveau dans le même artefact. Si l’artefact a été modifié, W&B enregistre une nouvelle version v1. W&B récupérera un artefact existant si vous transmettez à l’API wandb.Artifact un nom et un type d’artefact qui correspondent à un artefact existant dans votre projet. L’artefact récupéré aura une version supérieure à 1.

Comparaison des flux de travail des artefacts

Run unique

Enregistrez une nouvelle version d’un artefact avec une seule exécution qui produit tous les fichiers de l’artefact. Ce cas se présente lorsqu’une seule exécution produit tous les fichiers de l’artefact. Selon votre cas d’usage, sélectionnez l’un des onglets ci-dessous pour créer une nouvelle version d’artefact :

Utilisez wandb.Run.log_artifact() pour marquer explicitement un artefact comme sortie d’une exécution.Utilisez Artifact.save() comme méthode pratique. Si une exécution est active, W&B enregistre l’artefact dans cette exécution. Sinon, W&B crée automatiquement une exécution et y enregistre l’artefact.

Associer comme sortie d’exécution
Enregistrer directement

Utilisez wandb.Run.log_artifact() pour associer explicitement l’artefact à une exécution :

Créez une exécution avec wandb.init().
Créez un nouvel artefact ou récupérez-en un existant avec wandb.Artifact.
Ajoutez des fichiers à l’artefact avec wandb.Artifact.add_file().
Enregistrez l’artefact dans l’exécution avec wandb.Run.log_artifact().

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

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

Utilisez wandb.Artifact.save() comme méthode pratique pour enregistrer l’artefact depuis le contexte actuel :

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

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

Runs distribués

Autorisez une collection de runs à collaborer sur une version avant de la valider. Cela contraste avec le mode à run unique décrit ci-dessus, dans lequel un seul run fournit toutes les données d’une nouvelle version.

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

Prenez l’exemple suivant. Différents runs (indiqués ci-dessous comme Run 1, Run 2 et Run 3) ajoutent chacun un fichier image différent au même artefact 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 s’exécuter une fois que Run 1 et Run 2 sont terminés. Le Run qui appelle wandb.Run.finish_artifact() peut inclure des fichiers dans l’artefact, 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`, et `.add_reference`
    artifact.add_file("image3.png")
    run.finish_artifact(artifact, distributed_id="my_dist_artifact")

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

Créez une nouvelle version d’artefact en ajoutant, en modifiant ou en supprimant des fichiers d’une version d’artefact existante. W&B réindexe uniquement les fichiers qui ont changé. La version obtenue est appelée un artefact incrémentiel.

Gestion des versions d’artefacts incrémentiels

Pour créer un artefact incrémentiel, créez un brouillon à partir de n’importe quelle version d’artefact précédemment 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, voir la documentation de référence de Artifact. Une fois le brouillon modifié, consignez-le ou enregistrez-le pour créer une nouvelle version d’artefact.

Vous pouvez créer un nouvel artefact à partir de zéro au lieu de créer un artefact incrémentiel. Toutefois, cette approche exige que tous les fichiers de l’artefact soient disponibles sur votre disque local. Avec un artefact incrémentiel, vous pouvez ajouter, supprimer ou modifier des fichiers individuels tout en réutilisant les fichiers inchangés de la version précédente de l’artefact.

Vous pouvez créer un artefact incrémentiel dans le cadre d’une seule exécution ou de plusieurs exécutions contribuant à la nouvelle version. Les sections suivantes décrivent comment créer un artefact incrémentiel dans chaque cas.

Run unique

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

Utilisez wandb.Run.use_artifact() lorsque le run en cours consomme l’artefact. W&B enregistre l’artefact comme entrée du run.

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

with wandb.init(job_type="modify dataset") as run:
    saved_artifact = run.use_artifact(
        "my_artifact:latest"
    )  # récupère l'artefact et l'utilise comme entrée dans votre run
    draft_artifact = saved_artifact.new_draft()  # crée une version brouillon

    # modifie 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
    )  # enregistre 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 artefact sans l’enregistrer comme entrée du run.

Récupérez la version de l’artefact 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 d’artefact.

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

# modifie 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()  # valide les modifications du brouillon

Runs distribués

Utilisez Artifact.upsert_artifact() et Artifact.finish_artifact() lorsque plusieurs runs ajoutent des fichiers à une même version d’artefact. L’exemple suivant montre comment créer une nouvelle version d’artefact à partir de runs distribués lorsque l’artefact est utilisé comme entrée pour les runs. La même approche s’applique lorsque l’artefact 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’artefact déjà validée.Utilisez Artifact.upsert_artifact() et Artifact.finish_artifact() lorsque plusieurs runs doivent collaborer sur une même version d’artefact avant sa finalisation.

Guides

Intégrations

Référence

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

Run unique

Runs distribués

Run 1

Run 2

Run 3

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

Run unique

Runs distribués

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

​Run unique

​Runs distribués

​Run 1

​Run 2

​Run 3

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

​Run unique

​Runs distribués

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

Run unique

Runs distribués

Run 1

Run 2

Run 3

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

Run unique

Runs distribués