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

単一のrunから、または分散された複数のrunが連携して、新しいアーティファクトバージョンを作成します。必要に応じて、以前のバージョン (段階的アーティファクト) から新しいアーティファクトバージョンを作成することもできます。

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

ゼロから新しいアーティファクトバージョンを作成する

新しいアーティファクトバージョンを作成する方法は 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 より大きくなります。

単一の run

アーティファクト内のすべてのファイルを 1 つの run で生成する場合は、その run を使ってアーティファクトの新しいバージョンをログします。これは、1 つの run がアーティファクト内のすべてのファイルを生成するケースです。ユースケースに応じて、以下のタブから 1 つ選択し、新しいアーティファクトバージョンを作成します。

アーティファクトを run の output として明示的にマークするには、wandb.Run.log_artifact() を使用します。Artifact.save() は簡便な method として使用できます。run がアクティブな場合、W&B はその run にアーティファクトをログします。そうでない場合、W&B は自動的に run を作成し、そこにログします。

run の output としてトラッキングする
直接保存

アーティファクトを run に明示的に関連付けるには、wandb.Run.log_artifact() を使用します。

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

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)

現在のコンテキストからアーティファクトを永続化するための簡便な method として、wandb.Artifact.save() を使用します。

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

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

分散 run

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

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

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

Run 1

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")

Run 2

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")

Run 3

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

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")

既存のバージョンから新しいアーティファクトバージョンを作成する

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

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

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

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

Single run

run 入力としてトラッキング
直接取得

現在の run がアーティファクトを使用する場合は、wandb.Run.use_artifact() を使用します。W&B は、そのアーティファクトを run の入力として記録します。

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

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 の出力としてマークします

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

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

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()  # ドラフトへの変更をコミットします

分散 run

複数の run から 1 つのアーティファクト version に file が追加される場合は、Artifact.upsert_artifact() と Artifact.finish_artifact() を使用します。以下の例では、アーティファクトが run への入力として使用されるケースで、分散 run から新しいアーティファクト version を作成する方法を示します。同じ方法は、Public API を使用してアーティファクトを直接フェッチする場合にも適用できます。

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()

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

​ゼロから新しいアーティファクトバージョンを作成する

​単一の run

​分散 run

​Run 1

​Run 2

​Run 3

​既存のバージョンから新しいアーティファクト バージョンを作成する

​Single run

​分散 run

ゼロから新しいアーティファクトバージョンを作成する

単一の run

分散 run

Run 1

Run 2

Run 3

既存のバージョンから新しいアーティファクトバージョンを作成する

Single run

分散 run