> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

# Créer une version d’artifact

Créez une nouvelle version d’artifact avec un seul [run](/fr/products/wandb/runs) 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](#create-a-new-artifact-version-from-an-existing-version).

<Note>
  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.
</Note>

<h2 id="create-new-artifact-versions-from-scratch">
  Créer de nouvelles versions d'artifact à partir de zéro
</h2>

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.

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/_media/single_distributed_artifacts.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=282def1033e091eccfb804f02d7764e1" alt="Comparaison des flux de travail d'artifact" width="2010" height="986" data-path="products/wandb/_media/single_distributed_artifacts.png" />
</Frame>

<h3 id="single-run">
  Run unique
</h3>

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 :

<Tip title="Run.log_artifact() ou Artifact.save()">
  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.
</Tip>

<Tabs>
  <Tab title="Suivre comme sortie de run">
    Utilisez `wandb.Run.log_artifact()` pour associer explicitement l’artifact à un run :

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

    ```python theme={"system"}
    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)
    ```
  </Tab>

  <Tab title="Enregistrer directement">
    Utilisez `wandb.Artifact.save()` comme méthode de commodité pour persister l’artifact à partir du contexte actuel :

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

    ```python theme={"system"}
    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()
    ```
  </Tab>
</Tabs>

<h3 id="distributed-runs">
  Runs distribués
</h3>

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.

<Note>
  1. 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)`.
  2. Un run final doit « valider » la version, ce qui verrouille définitivement son état.
  3. Utilisez `upsert_artifact` pour ajouter du contenu à l’artifact collaboratif et `finish_artifact` pour finaliser la validation.
</Note>

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`.

<h4 id="run-1">
  Run 1
</h4>

```python theme={"system"}
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")
```

<h4 id="run-2">
  Run 2
</h4>

```python theme={"system"}
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")
```

<h4 id="run-3">
  Run 3
</h4>

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.

```python theme={"system"}
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")
```

<h2 id="create-a-new-artifact-version-from-an-existing-version">
  Créer une nouvelle version d’artifact à partir d’une version existante
</h2>

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*.

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/_media/incremental_artifacts.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=ce6e5d53cde482d8deafb484ff24ad7b" alt="Gestion des versions d’artifacts incrémentiels" width="2140" height="916" data-path="products/wandb/_media/incremental_artifacts.png" />
</Frame>

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`](/fr/products/wandb/ref/python/experiments/artifact).

Une fois vos modifications terminées, journalisez ou enregistrez le brouillon pour créer une nouvelle version d’artifact.

<Info>
  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.
</Info>

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.

<h3 id="single-run-2">
  Run unique
</h3>

<Tabs>
  <Tab title="Suivre comme entrée du run">
    Utilisez `wandb.Run.use_artifact()` lorsque le run actuel consomme l’artifact. W\&B enregistre alors l’artifact comme entrée du run.

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

    ```python lines theme={"system"}
    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
    ```
  </Tab>

  <Tab title="Récupérer directement">
    Utilisez l’API publique pour récupérer un artifact sans l’enregistrer comme entrée d’un run.

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

    ```python theme={"system"}
    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
    ```
  </Tab>
</Tabs>

<h3 id="distributed-runs-2">
  Runs distribués
</h3>

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](/fr/products/wandb/artifacts/create-a-new-artifact-version#use-as-run-input). La même approche s’applique lorsque l’artifact est [récupéré directement](/fr/products/wandb/artifacts/create-a-new-artifact-version#fetch-directly) avec l’API publique.

```python theme={"system"}
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()
```

<Tip title="Brouillon ou upsert">
  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.
</Tip>


## Related topics

- [Référencer une version d'artifact à l'aide d'alias](/fr/products/registry/aliases.md)