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 à l’intérieur ou à l’extérieur d’un run :

À l’intérieur d’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)

À l’extérieur 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")
    # Ajouter 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 via
    # `.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 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")
    # 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’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 à réindexer les fichiers qui n’ont pas changé. Cette opération crée une nouvelle version d’artifact appelée artifact incrémentiel.

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

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

Vous pouvez créer un artifact from scratch pour remplir la même fonction qu’un artifact incrémentiel. Cependant, lors de la création d’un artifact from scratch, vous devez disposer de l’intégralité du contenu de votre artifact sur votre disque local. Lors d’une modification incrémentielle, vous pouvez ajouter, supprimer ou modifier un seul fichier sans modifier les fichiers d’une version précédente de l’artifact.

Vous pouvez créer un artifact incrémentiel au sein d’un seul run ou à partir d’un ensemble de runs (mode distribué).

Suivez la procédure ci-dessous pour modifier un artifact de façon incrémentielle :

1. Obtenez la version de l’artifact sur laquelle vous souhaitez apporter une modification incrémentielle :

Dans un run

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

Hors d’un run

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

2. Créez un brouillon avec :

draft_artifact = saved_artifact.new_draft()

3. Apportez les modifications incrémentielles souhaitées pour la version suivante. Vous pouvez ajouter, supprimer ou modifier une entrée existante.

Sélectionnez l’un des onglets pour voir un exemple illustrant comment effectuer chacune de ces modifications :

Ajouter

Ajoutez un fichier à une version existante d’un artifact 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.

Supprimer

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

draft_artifact.remove("file_to_remove.txt")

Vous pouvez également supprimer plusieurs fichiers avec la méthode remove en indiquant le chemin d’un répertoire.

Modifier

Modifiez ou remplacez le contenu en supprimant l’ancien contenu du brouillon, puis en y ajoutant le nouveau contenu :

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

4. Enfin, consignez vos modifications ou enregistrez-les. Les onglets suivants montrent comment enregistrer vos modifications dans un run W&B ou en dehors. Sélectionnez l’onglet adapté à votre cas d’usage :

Dans un run

run.log_artifact(draft_artifact)

En dehors d’un run

draft_artifact.save()

En combinant le tout, les exemples de code ci-dessus donnent :

À l’intérieur d’un 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'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
    )  # journalise vos modifications pour créer une nouvelle version et la marquer comme sortie de votre run

En dehors d’un 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

# 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