Créer une nouvelle version d'artifact

Créer une nouvelle version d’artifact à partir d’un seul run ou d’un processus distribué.

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

Nous vous recommandons de créer un artifact incrémentiel lorsque vous devez appliquer des modifications à un sous-ensemble de fichiers d’un artifact et que l’artifact original est nettement plus volumineux.

​

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 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, 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. Cela convient particulièrement aux jobs distribués, où 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.

W&B créera un nouvel artifact et lui attribuera l’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 enregistrez de nouveau des données dans le même artifact. Si l’artifact a changé, W&B enregistre une nouvelle version v1.

W&B récupérera un artifact existant si vous transmettez à l’API wandb.Artifact un nom et un type d’artifact correspondant à un artifact existant dans votre projet. L’artifact récupéré aura une version supérieure à 1.

​

run unique

Consignez une nouvelle version d’un Artifact avec un run unique qui produit tous les fichiers de l’artifact. Ce cas se présente lorsqu’un run unique produit tous les fichiers de l’artifact.

En fonction de votre cas d’usage, sélectionnez l’un des onglets ci-dessous pour créer une nouvelle version d’artifact dans un run ou hors d’un run :

dans un run

Créez une version d’artifact dans un run W&B :

1. Créez un run avec wandb.init().
2. Créez un nouvel artifact ou récupérez-en un existant avec wandb.Artifact.
3. Ajoutez des fichiers à l’artifact avec .add_file.
4. Consignez l’artifact dans le run avec .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)

hors d'un run

Créez une version d’artifact en dehors d’un run W&B :

1. Créez un nouvel artifact ou récupérez-en un existant avec wanb.Artifact.
2. Ajoutez des fichiers à l’artifact avec .add_file.
3. Enregistrez l’artifact avec .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

Permet à une collection de runs de 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.

1. 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 existe, W&B utilise le group du run défini par wandb.init(group=GROUP) comme distributed_id.
2. Il doit y avoir un run final qui « valide » la version, en verrouillant définitivement son état.
3. Utilisez upsert_artifact pour ajouter du contenu à l’artifact collaboratif et finish_artifact pour finaliser la validation.

Considérez 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 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 que Run 1 et Run 2 sont terminés. Le run qui appelle wandb.Run.finish_artifact() peut inclure des fichiers dans l’artifact, mais ce n’est pas nécessaire.

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("image3.png")
    run.finish_artifact(artifact, distributed_id="my_dist_artifact")

​

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

Ajoutez, modifiez ou supprimez un sous-ensemble de fichiers d’une version d’artifact précédente sans avoir besoin de réindexer les fichiers qui n’ont pas changé. L’ajout, la modification ou la suppression d’un sous-ensemble de fichiers d’une version d’artifact précédente crée une nouvelle version d’artifact appelée artifact incrémental.

Voici quelques scénarios pour chaque type de modification incrémentale que vous pourriez rencontrer :

• ajout : vous ajoutez périodiquement un nouveau sous-ensemble de fichiers à un jeu de données après avoir collecté un nouveau lot.
• suppression : vous avez découvert plusieurs fichiers en double et souhaitez les supprimer de votre artifact.
• mise à jour : vous avez corrigé des annotations pour un sous-ensemble de fichiers et souhaitez remplacer les anciens fichiers par les corrects.

Vous pourriez créer un artifact de zéro pour remplir la même fonction qu’un artifact incrémental. Cependant, lorsque vous créez un artifact de zéro, vous devrez avoir tout le contenu de votre artifact sur votre disque local. Lors d’une modification incrémentale, vous pouvez ajouter, supprimer ou modifier un seul fichier sans changer les fichiers d’une version d’artifact précédente.

Vous pouvez créer un artifact incrémental dans un seul run ou avec un ensemble de runs (mode distribué).

Suivez la procédure ci-dessous pour modifier un artifact de manière incrémentale :

1. Obtenez la version d’artifact sur laquelle vous souhaitez effectuer une modification incrémentale :

Inside a run

saved_artifact = run.use_artifact("my_artifact:latest")

Outside of a run

client = wandb.Api()
saved_artifact = client.artifact("my_artifact:latest")

2. Créez un brouillon avec :

draft_artifact = saved_artifact.new_draft()

3. Effectuez les modifications incrémentales que vous souhaitez voir dans la prochaine version. Vous pouvez ajouter, supprimer ou modifier une entrée existante.

Sélectionnez l’un des onglets pour un exemple sur la façon d’effectuer chacune de ces modifications :

Add

Ajoutez un fichier à une version d’artifact existante avec la méthode add_file :

draft_artifact.add_file("file_to_add.txt")

Vous pouvez également ajouter plusieurs fichiers en ajoutant un répertoire avec la méthode add_dir.

Remove

Supprimez un fichier d’une version d’artifact existante avec la méthode remove :

draft_artifact.remove("file_to_remove.txt")

Vous pouvez également supprimer plusieurs fichiers avec la méthode remove en passant un chemin de répertoire.

Modify

Modifiez ou remplacez le contenu en supprimant l’ancien contenu du brouillon et en ajoutant le nouveau contenu :

draft_artifact.remove("modified_file.txt")
draft_artifact.add_file("modified_file.txt")

4. Enfin, journalisez ou sauvegardez vos modifications. Les onglets suivants vous montrent comment sauvegarder vos modifications à l’intérieur et à l’extérieur d’un run W&B. Sélectionnez l’onglet approprié à votre cas d’utilisation :

Inside a run

run.log_artifact(draft_artifact)

Outside of a run

draft_artifact.save()

En rassemblant le tout, les exemples de code ci-dessus ressemblent à :

Inside a run

with wandb.init(job_type="modify dataset") as run:
    saved_artifact = run.use_artifact(
        "my_artifact:latest"
    )  # récupère l'artifact et l'intègre à 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
    )  # journalise vos modifications pour créer une nouvelle version et la marquer comme sortie de votre run

Outside of a run

client = wandb.Api()
saved_artifact = client.artifact("my_artifact:latest")  # charge votre artifact
draft_artifact = saved_artifact.new_draft()  # crée 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 dans le brouillon