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

> 単一のrunまたは分散プロセスから新しいアーティファクトバージョンを作成します。

# アーティファクトバージョンを作成する

単一の[run](/ja/models/runs/)から、または分散された複数のrunが連携して、新しいアーティファクトバージョンを作成します。必要に応じて、以前のバージョン ([段階的アーティファクト](#create-a-new-artifact-version-from-an-existing-version)) から新しいアーティファクトバージョンを作成することもできます。

<Note>
  アーティファクト 内のファイルの一部に変更を適用する必要があり、元のアーティファクトのサイズが大幅に大きい場合は、段階的アーティファクトを作成することをお勧めします。
</Note>

<div id="create-new-artifact-versions-from-scratch">
  ## ゼロから新しいアーティファクトバージョンを作成する
</div>

新しいアーティファクトバージョンを作成する方法は 2 つあります。single run から作成する方法と、分散 run から作成する方法です。以下でそれぞれ説明します。

* **Single run**: 1 つの run が、新しいバージョンに必要なすべてのデータを提供します。これは最も一般的なケースで、run によって必要なデータを完全に再生成できる場合に最適です。たとえば、保存済みモデルを出力したり、分析用の表にモデルの予測を出力したりする場合です。
* **分散 run**: 複数の runs がまとまって、新しいバージョンに必要なすべてのデータを提供します。これは、複数の runs がしばしば並列にデータを生成する分散ジョブに最適です。たとえば、モデルを分散方式で評価し、予測を出力する場合です。

`wandb.Artifact` API に、project 内に存在しない名を渡すと、W\&B は新しいアーティファクトを作成し、`v0` alias を割り当てます。W\&B は、同じアーティファクトに再度ログするときに内容のチェックサムを計算します。アーティファクトが変更されている場合、W\&B は新しいバージョン `v1` を保存します。

`wandb.Artifact` API に、project 内の既存のアーティファクトと一致する名とアーティファクトタイプを渡すと、W\&B は既存のアーティファクトを取得します。取得されたアーティファクトのバージョンは 1 より大きくなります。

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/wKCrMJZKG3PxyJhv/images/artifacts/single_distributed_artifacts.png?fit=max&auto=format&n=wKCrMJZKG3PxyJhv&q=85&s=5149473f3f32aaf45d5e6e200677fc4c" alt="アーティファクトワークフローの比較" width="2010" height="986" data-path="images/artifacts/single_distributed_artifacts.png" />
</Frame>

### 単一の run

アーティファクト内のすべてのファイルを 1 つの run で生成する場合は、その run を使って アーティファクト の新しいバージョンをログします。これは、1 つの run が アーティファクト 内のすべてのファイルを生成するケースです。

ユースケースに応じて、以下のタブから 1 つ選択し、新しい アーティファクト バージョンを作成します。

<Tip title="Run.log_artifact() と Artifact.save()">
  アーティファクト を run の output として明示的にマークするには、`wandb.Run.log_artifact()` を使用します。

  `Artifact.save()` は簡便な method として使用できます。run がアクティブな場合、W\&B はその run に アーティファクト をログします。そうでない場合、W\&B は自動的に run を作成し、そこにログします。
</Tip>

<Tabs>
  <Tab title="run の output としてトラッキングする">
    アーティファクト を run に明示的に関連付けるには、`wandb.Run.log_artifact()` を使用します。

    1. `wandb.init()` で run を作成します。
    2. `wandb.Artifact` で新しい アーティファクト を作成するか、既存の アーティファクト を取得します。
    3. `wandb.Artifact.add_file()` で アーティファクト にファイルを追加します。
    4. `wandb.Run.log_artifact()` で アーティファクト を run にログします。

    ```python theme={null}
    with wandb.init() as run:
        artifact = wandb.Artifact("artifact_name", "artifact_type")

        # `.add`、`.add_file`、`.add_dir`、`.add_reference` を使用して
        # ファイルとアセットを artifact に追加します
        artifact.add_file("image1.png")
        run.log_artifact(artifact)
    ```
  </Tab>

  <Tab title="直接保存">
    現在のコンテキストから アーティファクト を永続化するための簡便な method として、`wandb.Artifact.save()` を使用します。

    1. `wandb.Artifact` で新しい アーティファクト を作成するか、既存の アーティファクト を取得します。
    2. `wandb.Artifact.add_file()` で アーティファクト にファイルを追加します。
    3. `wandb.Artifact.save()` で アーティファクト を保存します。

    ```python theme={null}
    artifact = wandb.Artifact("artifact_name", "artifact_type")
    # `.add`、`.add_file`、`.add_dir`、`.add_reference` を使用して
    # ファイルとアセットを artifact に追加します
    artifact.add_file("image1.png")
    artifact.save()
    ```
  </Tab>
</Tabs>

<div id="distributed-runs">
  ### 分散 run
</div>

コミットする前に、複数の run からなるコレクションで 1 つのバージョンを共同で作成できます。これは、前述の single run モード (1 つの run が新しいバージョンのすべてのデータを提供するモード) とは対照的です。

<Note>
  1. コレクション内の各 run は、同じバージョンで共同作業するために、同じ一意の ID (`distributed_id`) を認識している必要があります。デフォルトでは、存在する場合、W\&B は `wandb.init(group=GROUP)` で設定された run の `group` を `distributed_id` として使用します。
  2. バージョンを「コミット」してその状態を永続的にロックするための、最後の run が必要です。
  3. 共同の アーティファクト に追加するには `upsert_artifact` を使用し、コミットを完了するには `finish_artifact` を使用します。
</Note>

次の例を見てみましょう。異なる run (以下では **Run 1**、**Run 2**、**Run 3** と表記) が、`upsert_artifact` を使用して、それぞれ異なる画像ファイルを同じ アーティファクト に追加します。

<div id="run-1">
  #### Run 1
</div>

```python theme={null}
with wandb.init() as run:
    artifact = wandb.Artifact("artifact_name", "artifact_type")
    # `.add`、`.add_file`、`.add_dir`、`.add_reference` を使用して
    # ファイルとアセットをアーティファクトに追加する
    artifact.add_file("image1.png")
    run.upsert_artifact(artifact, distributed_id="my_dist_artifact")
```

<div id="run-2">
  #### Run 2
</div>

```python theme={null}
with wandb.init() as run:
    artifact = wandb.Artifact("artifact_name", "artifact_type")
    # `.add`、`.add_file`、`.add_dir`、`.add_reference` を使用して
    # ファイルとアセットをアーティファクトに追加する
    artifact.add_file("image2.png")
    run.upsert_artifact(artifact, distributed_id="my_dist_artifact")
```

<div id="run-3">
  #### Run 3
</div>

Run 1 と Run 2 の完了後に実行する必要があります。`wandb.Run.finish_artifact()` を呼び出す run では、アーティファクト にファイルを含めることもできますが、必須ではありません。

```python theme={null}
with wandb.init() as run:
    artifact = wandb.Artifact("artifact_name", "artifact_type")
    # ファイルとアセットをartifactに追加する
    # `.add`、`.add_file`、`.add_dir`、`.add_reference`
    artifact.add_file("image3.png")
    run.finish_artifact(artifact, distributed_id="my_dist_artifact")
```

<div id="create-a-new-artifact-version-from-an-existing-version">
  ## 既存のバージョンから新しいアーティファクト バージョンを作成する
</div>

既存のアーティファクト バージョンにファイルを追加、変更、または削除して、新しいアーティファクト バージョンを作成します。W\&B は変更されたファイルのみを再インデックス化します。生成されるバージョンは、*段階的*アーティファクトと呼ばれます。

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/wKCrMJZKG3PxyJhv/images/artifacts/incremental_artifacts.png?fit=max&auto=format&n=wKCrMJZKG3PxyJhv&q=85&s=08b3fc92938a1e7d03a02aae6108f7cd" alt="段階的アーティファクトのバージョン管理" width="2140" height="916" data-path="images/artifacts/incremental_artifacts.png" />
</Frame>

段階的アーティファクトを作成するには、以前にコミットされた任意のアーティファクト バージョンから *ドラフト* を作成します。次に、`Artifact.add_file()`、`Artifact.add_dir()`、`Artifact.remove()` などのメソッドを使用してドラフトを変更できます。利用可能なメソッドの完全な一覧については、[`Artifact` リファレンス ドキュメント](/ja/models/ref/python/experiments/artifact)を参照してください。

ドラフトの変更が完了したら、それをログするか保存して、新しいアーティファクト バージョンを作成します。

<Info>
  段階的アーティファクトを作成する代わりに、新しいアーティファクトを最初から作成することもできます。ただし、この方法では、すべてのアーティファクト ファイルがローカル ディスク上で利用可能である必要があります。段階的アーティファクトでは、前のアーティファクト バージョンの変更されていないファイルを再利用しながら、個々のファイルを追加、削除、または変更できます。
</Info>

単一の run を使用して、または新しいバージョンに反映される複数の Runs をまたいで、段階的アーティファクトを作成できます。以下のセクションでは、それぞれの場合に段階的アーティファクトを作成する方法を説明します。

<div id="single-run">
  ### Single run
</div>

<Tabs>
  <Tab title="run 入力としてトラッキング">
    現在の run が アーティファクト を使用する場合は、`wandb.Run.use_artifact()` を使用します。W\&B は、その アーティファクト を run の入力として記録します。

    1. `wandb.Run.use_artifact()` で アーティファクト バージョンを取得します。
    2. `Artifact.new_draft()` でドラフトを作成します。
    3. ドラフト内のエントリを追加、削除、または変更します。
    4. `wandb.Run.log_artifact()` でドラフトをログして、新しい アーティファクト バージョンを作成します。

    ```python lines theme={null}
    with wandb.init(job_type="modify dataset") as run:
        saved_artifact = run.use_artifact(
            "my_artifact:latest"
        )  # artifact を取得して run への入力として使用します
        draft_artifact = saved_artifact.new_draft()  # ドラフトバージョンを作成します

        # ドラフトバージョン内のファイルの一部を変更します
        draft_artifact.add_file("file_to_add.txt")
        draft_artifact.remove("dir_to_remove/")
        run.log_artifact(
            draft_artifact
        )  # 変更をログして新しいバージョンを作成し、run の出力としてマークします
    ```
  </Tab>

  <Tab title="直接取得">
    アーティファクト を run 入力として記録せずに取得するには、Public API を使用します。

    1. `wandb.Api.artifact()` で アーティファクト バージョンを取得します。
    2. `Artifact.new_draft()` でドラフトを作成します。
    3. ドラフト内のエントリを追加、削除、または変更します。
    4. `Artifact.save()` でドラフトバージョンを保存して、新しい アーティファクト バージョンを作成します。

    ```python theme={null}
    client = wandb.Api()
    saved_artifact = client.artifact("my_artifact:latest")  # artifact を読み込みます
    draft_artifact = saved_artifact.new_draft()  # ドラフトバージョンを作成します

    # ドラフトバージョン内のファイルの一部を変更します
    draft_artifact.remove("deleted_file.txt")
    draft_artifact.add_file("modified_file.txt")
    draft_artifact.save()  # ドラフトへの変更をコミットします
    ```
  </Tab>
</Tabs>

<div id="distributed-runs">
  ### 分散 run
</div>

複数の run から 1 つの アーティファクト version に file が追加される場合は、`Artifact.upsert_artifact()` と `Artifact.finish_artifact()` を使用します。

以下の例では、アーティファクト が [run への入力](/ja/models/artifacts/create-a-new-artifact-version#use-as-run-input) として使用されるケースで、分散 run から新しい アーティファクト version を作成する方法を示します。同じ方法は、Public API を使用して アーティファクト を [直接フェッチする](/ja/models/artifacts/create-a-new-artifact-version#fetch-directly) 場合にも適用できます。

```python theme={null}
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="Draft と Upsert">
  コミット済みの アーティファクト version を変更する場合は、`Artifact.new_draft()` を使用してください。

  複数の Runs で、確定前の 1 つの アーティファクト version を共同で更新する必要がある場合は、`Artifact.upsert_artifact()` と `Artifact.finish_artifact()` を使用してください。
</Tip>