W&B Python SDKを使用して、 W&B Runs から Artifacts を構築します。 ファイル、ディレクトリー、URI、および並列実行された run からのファイルを Artifacts に追加 することができます。ファイルを Artifacts に追加した後、その Artifacts を W&B サーバーまたは 独自のプライベートサーバー に保存します。各 Artifacts はひとつの run に関連付けられます。
Amazon S3 に保存されているファイルなどの外部ファイルを追跡する方法については、 外部ファイルの追跡 ページを参照してください。
Artifacts の構築方法
W&B Artifact は以下の3つのステップで構築します：
1. wandb.Artifact() で Artifacts の Python オブジェクトを作成する
wandb.Artifact() クラスを初期化して Artifacts オブジェクトを作成します。以下のパラメータを指定してください：
- Name: Artifacts の名前を指定します。名前は一意で、説明的、かつ覚えやすいものである必要があります。Artifacts 名は、W&B App UI で Artifacts を特定するため、およびその Artifacts を使用したい時の両方で使われます。
- Type: タイプを指定します。タイプはシンプルで説明的であり、機械学習パイプラインの単一のステップに対応している必要があります。一般的な Artifacts タイプには
'dataset' や 'model' が含まれます。
W&B は指定された “name” と “type” を使用して、有向非巡回グラフ（DAG）を作成します。W&B App 上で Artifacts のリネージを確認できます。詳細については、 Artifacts グラフの探索とトラバース を参照してください。 Artifacts は、type パラメータに異なるタイプを指定したとしても、同じ名前を持つことはできません。言い換えれば、dataset タイプの cats という名前の Artifacts と、model タイプの同名の Artifacts を作成することはできません。
wandb.Artifact クラス定義を参照してください。
以下のコードスニペットをコピー＆ペーストして、Artifacts オブジェクトを作成します。 <name> と <type> プレースホルダーを自身の値に置き換えてください。：
import wandb
# Artifacts オブジェクトを作成
artifact = wandb.Artifact(name="<name>", type="<type>")
2. Artifacts にファイルを追加する
ファイル、ディレクトリー、外部 URI 参照（Amazon S3 など）などを Artifacts オブジェクトに追加します。
単一のファイルを追加するには、Artifacts オブジェクトの Artifact.add_file() メソッドを使用します：
artifact.add_file(local_path="path/to/file.txt", name="<name>")
Artifact.add_dir() メソッドを使用します：
artifact.add_dir(local_path="path/to/directory", name="<name>")
3. Artifacts を W&B サーバーに保存する
最後に、Artifacts を W&B サーバーに保存します。 run オブジェクトの wandb.Run.log_artifact() メソッドを使用して Artifacts を保存します。
with wandb.init(project="<project>", job_type="<job-type>") as run:
run.log_artifact(artifact)
import wandb
artifact = wandb.Artifact(name="<name>", type="<type>")
artifact.add_file(local_path="path/to/file.txt", name="<name>")
artifact.add_dir(local_path="path/to/directory", name="<name>")
with wandb.init(project="<project>", job_type="<job-type>") as run:
run.log_artifact(artifact)
Artifact.save() と wandb.Run.log_artifact() の使い分け
Artifact.save() は、新しい run を作成せずに既存の Artifacts を更新する場合に使用します。wandb.Run.log_artifact() は、新しい Artifacts を作成し、それを特定の run に関連付ける場合に使用します。
log_artifact の呼び出しは、アップロードのパフォーマンス向上のため非同期で行われます。これにより、ループ内で Artifacts をログに記録する場合に予期しない振る舞いが発生することがあります。例えば：for i in range(10):
a = wandb.Artifact(
"race",
type="dataset",
metadata={
"index": i,
},
)
# ... artifact a にファイルを追加 ...
run.log_artifact(a)
Artifacts へのファイルの追加
以下のセクションでは、さまざまなファイルタイプを使用して、または並列 run から Artifacts を構築する方法を説明します。
以下の例では、複数のファイルとディレクトリー構造を持つプロジェクトディレクトリーがあることを想定しています。
project-directory
|-- images
| |-- cat.png
| +-- dog.png
|-- checkpoints
| +-- model.h5
+-- model.h5
単一ファイルの追加
以下のコードスニペットは、単一のローカルファイルを Artifacts に追加する方法を示しています：
# 単一のファイルを追加
artifact.add_file(local_path="path/file.format")
'file.txt' というファイルがあるとします。
artifact.add_file("path/file.txt") # `file.txt` として追加
name パラメータを使用して Artifacts 内の希望するパスを指定できます。
artifact.add_file(local_path="path/file.format", name="new/path/file.format")
| API 呼び出し | 結果の Artifacts |
|---|
artifact.add_file('model.h5') | model.h5 |
artifact.add_file('checkpoints/model.h5') | model.h5 |
artifact.add_file('model.h5', name='models/mymodel.h5') | models/mymodel.h5 |
複数ファイルの追加
以下のコードスニペットは、ローカルのディレクトリー全体を Artifacts に追加する方法を示しています：
# ディレクトリーを再帰的に追加
artifact.add_dir(local_path="path/file.format", name="optional-prefix")
| API 呼び出し | 結果の Artifacts |
|---|
artifact.add_dir('images') | cat.png
dog.png
|
artifact.add_dir('images', name='images') | images/cat.png
images/dog.png
|
artifact.new_file('hello.txt') | hello.txt |
URI 参照の追加
W&B ライブラリが処理可能なスキームを持つ URI の場合、Artifacts は再現性のためにチェックサムやその他の情報を追跡します。
add_reference メソッドを使用して、外部 URI 参照を Artifacts に追加します。 'uri' 文字列を自身の URI に置き換えてください。オプションで、 name パラメータに Artifacts 内の希望するパスを指定できます。
# URI 参照を追加
artifact.add_reference(uri="uri", name="optional-name")
http(s)://: HTTP 経由でアクセス可能なファイルへのパス。HTTP サーバーが ETag および Content-Length レスポンスヘッダーをサポートしている場合、Artifacts は etag 形式のチェックサムとサイズメタデータを追跡します。s3://: S3 内のオブジェクトまたはオブジェクトプレフィックスへのパス。Artifacts は、参照されたオブジェクトのチェックサムと（バケットでオブジェクトのバージョン管理が有効な場合は）バージョン情報を追跡します。オブジェクトプレフィックスは、そのプレフィックス下のオブジェクト（最大10,000オブジェクトまで）を含むように拡張されます。gs://: GCS 内のオブジェクトまたはオブジェクトプレフィックスへのパス。Artifacts は、参照されたオブジェクトのチェックサムと（バケットでオブジェクトのバージョン管理が有効な場合は）バージョン情報を追跡します。オブジェクトプレフィックスは、そのプレフィックス下のオブジェクト（最大10,000オブジェクトまで）を含むように拡張されます。
上記の API 呼び出しにより、以下の Artifacts が生成されます：
| API 呼び出し | 結果の Artifacts コンテンツ |
|---|
artifact.add_reference('s3://my-bucket/model.h5') | model.h5 |
artifact.add_reference('s3://my-bucket/checkpoints/model.h5') | model.h5 |
artifact.add_reference('s3://my-bucket/model.h5', name='models/mymodel.h5') | models/mymodel.h5 |
artifact.add_reference('s3://my-bucket/images') | cat.png
dog.png
|
artifact.add_reference('s3://my-bucket/images', name='images') | images/cat.png
images/dog.png
|
並列 run から Artifacts へファイルを追加する
大規模なデータセットや分散トレーニングでは、複数の並列 run が単一の Artifacts に寄与する必要がある場合があります。
import wandb
import time
# デモ目的で、run を並列に起動するために ray を使用します。
# 並列 run のオーケストレーションは任意の方法で行えます。
import ray
ray.init()
artifact_type = "dataset"
artifact_name = "parallel-artifact"
table_name = "distributed_table"
parts_path = "parts"
num_parallel = 5
# 並列ライターの各バッチには、それぞれ一意の
# グループ名が必要です。
group_name = "writer-group-{}".format(round(time.time()))
@ray.remote
def train(i):
"""
ライター・ジョブ。各ライターは Artifacts に1つの画像を追加します。
"""
with wandb.init(group=group_name) as run:
artifact = wandb.Artifact(name=artifact_name, type=artifact_type)
# W&B テーブルにデータを追加。この例ではサンプルデータを使用
table = wandb.Table(columns=["a", "b", "c"], data=[[i, i * 2, 2**i]])
# Artifacts 内のフォルダーにテーブルを追加
artifact.add(table, "{}/table_{}".format(parts_path, i))
# Artifacts の upsert は、Artifacts へのデータの作成または追加を行います
run.upsert_artifact(artifact)
# run を並列に起動
result_ids = [train.remote(i) for i in range(num_parallel)]
# 全てのライターが終了し、ファイルが追加されたことを
# 確認してから Artifacts を完成させます。
ray.get(result_ids)
# 全てのライターが終了したら、Artifacts を完成させて
# 準備完了の状態にします。
with wandb.init(group=group_name) as run:
artifact = wandb.Artifact(artifact_name, type=artifact_type)
# テーブルのフォルダーを指す "PartitionTable" を作成し
# Artifacts に追加します。
artifact.add(wandb.data_types.PartitionedTable(parts_path), table_name)
# Finish artifact は Artifacts を確定させ、このバージョンへの
# 今後の "upserts" を禁止します。
run.finish_artifact(artifact)
ログに記録された Artifacts やその他のメタデータのパスを確認する
以下のコードスニペットは、 W&B Public API を使用して、ファイル名や URL を含む run 内のファイルをリスト化する方法を示しています。 <entity/project/run-id> プレースホルダーを自身の値に置き換えてください：
from wandb.apis.public.files import Files
from wandb.apis.public.api import Api
# run オブジェクトの例
run = Api().run("<entity/project/run-id>")
# run 内のファイルを反復処理するための Files オブジェクトを作成
files = Files(api.client, run)
# ファイルを反復処理
for file in files:
print(f"File Name: {file.name}")
print(f"File URL: {file.url}")
print(f"Path to file in the bucket: {file.direct_url}")
