W&B Python SDK を使用して、W&B Runs から artifact を作成できます。ファイル、ディレクトリ、URI、並列 run のファイルを artifact に追加できます。artifact にファイルを追加したら、その artifact を W&B Server または独自のプライベートサーバーに保存します。各 artifact は run に関連付けられています。
Amazon S3 に保存されたファイルなどの外部ファイルをトラッキングする方法については、外部ファイルをトラッキングするページを参照してください。
W&B Artifact は、次の 3 つの step で作成します。
wandb.Artifact() を使って アーティファクト の Python オブジェクトを作成する- アーティファクト に 1 つ以上のファイルを追加する
- アーティファクト を W&B Server に保存する
wandb.Artifact() を使って アーティファクト Python オブジェクトを作成する
wandb.Artifact() クラスを初期化します。次のパラメーターを指定します。
- Name: アーティファクト の名前です。名前は一意で、内容がわかりやすく、覚えやすいものにしてください。
- Type: アーティファクト のタイプです。タイプはシンプルでわかりやすく、機械学習パイプライン内の単一の step に対応している必要があります。一般的な アーティファクト タイプには
'dataset' や 'model' があります。
Artifacts には、タイプに関係なく同じ名前を付けることはできません。つまり、dataset タイプの cats という名前の アーティファクト と、model タイプの同じ名前の アーティファクト を別に作成することはできません。
wandb.Artifact クラス定義を参照してください。
次の コードスニペット をコピー＆ペーストして アーティファクト オブジェクトを作成します。<name> と <type> のプレースホルダーを自分の値に置き換えてください。
import wandb
# アーティファクト オブジェクトを作成する
artifact = wandb.Artifact(name="<name>", type="<type>")
アーティファクト に 1 つ以上のファイルを追加する
Artifact.add_file() method を使用します。
artifact.add_file(local_path="path/to/file.txt", name="<name>")
Artifact.add_dir() methodを使用します。
artifact.add_dir(local_path="path/to/directory", name="<name>")
wandb.Run.log_artifact() method を使用します。
with wandb.init(project="<project>", job_type="<job-type>") as run:
run.log_artifact(artifact)
wandb.Run.log_artifact() と Artifact.save() の使い分け
- 新しいアーティファクトを作成し、特定の run に関連付ける場合は
wandb.Run.log_artifact() を使用します。
- 新しい run を作成せずに既存のアーティファクトを更新する場合は
Artifact.save() を使用します。
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)
W&B では、アップロード性能を高めるために wandb.Run.log_artifact() を非同期で実行します。そのため、ループ内で アーティファクト をログすると、想定外の動作が発生することがあります。例:with wandb.init() as run:
for i in range(10):
a = wandb.Artifact(name = "race",
type="dataset",
metadata={
"index": i,
},
)
# ... artifact a にファイルを追加 ...
run.log_artifact(a)
root-directory
| - hello.txt
| - images/
| -- | cat.png
| -- | dog.png
| - checkpoints/
| -- | model.h5
| - models/
| -- | model.h5
wandb.Artifact.add_file() を使用します。ファイルのローカルパスを local_path パラメーターに指定します。
import wandb
# アーティファクト オブジェクトを初期化する
artifact = wandb.Artifact(name="<name>", type="<type>")
# 単一ファイルを追加する
artifact.add_file(local_path="path/file.format")
'hello.txt' というファイルがあるとします。
artifact.add_file("hello.txt")
name パラメーターに別の名前を渡すと、アーティファクト オブジェクト内でのファイル名を変更できます。前の例の続きは次のとおりです。
artifact.add_file(
local_path="hello.txt",
name="new/path/hello_world.txt"
)
| API 呼び出し | 生成される アーティファクト |
|---|
artifact.new_file('hello.txt') | hello.txt |
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 |
wandb.Artifact.add_dir() methodを使用します。local_path パラメーターには、対象ディレクトリのローカルパスを指定します。
import wandb
# アーティファクト オブジェクトを初期化する
artifact = wandb.Artifact(name="<name>", type="<type>")
# ローカルディレクトリをアーティファクトに追加する
artifact.add_dir(local_path="path/file.format", name="optional-prefix")
| API 呼び出し | 生成されるアーティファクト |
|---|
artifact.add_dir('images') | cat.png
dog.png
|
artifact.add_dir('images', name='images') | images/cat.png
images/dog.png
|
wandb.Artifact.add_reference() method を使用して、アーティファクト に外部 URI reference を追加します。'uri' 文字列はご自身の URI に置き換えてください。必要に応じて、name パラメーターに アーティファクト 内の任意のパスを指定できます。
# URI referenceを追加する
artifact.add_reference(uri="uri", name="optional-name")
http(s)://: HTTP 経由でアクセスできるファイルへのパスです。HTTP サーバーが ETag および Content-Length レスポンスヘッダーをサポートしている場合、アーティファクト は ETag とサイズのメタデータの形式でチェックサムをトラッキングします。s3://: S3 内のオブジェクトまたはオブジェクトプレフィックスへのパスです。アーティファクト は、参照先オブジェクトのチェックサムとバージョン管理情報 (バケットでオブジェクトのバージョン管理が有効になっている場合) をトラッキングします。オブジェクトプレフィックスは、そのプレフィックス配下のオブジェクトを含むように展開され、最大 10,000 オブジェクトまで含まれます。gs://: GCS 内のオブジェクトまたはオブジェクトプレフィックスへのパスです。アーティファクト は、参照先オブジェクトのチェックサムとバージョン管理情報 (バケットでオブジェクトのバージョン管理が有効になっている場合) をトラッキングします。オブジェクトプレフィックスは、そのプレフィックス配下のオブジェクトを含むように展開され、最大 10,000 オブジェクトまで含まれます。
次の表は、API 呼び出しによって アーティファクト の内容がどのように変わるかを示しています。
| API 呼び出し | 生成される アーティファクト の内容 |
|---|
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 からアーティファクトにファイルを追加する
import wandb
import time
# この例では、デモンストレーション目的で
# Ray を使用して並列実行します。
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):
"""
Our writer job. Each writer will add one image to the artifact.
"""
with wandb.init(group=group_name) as run:
artifact = wandb.Artifact(name=artifact_name, type=artifact_type)
# wandb の表にデータを追加します。
table = wandb.Table(columns=["a", "b", "c"], data=[[i, i * 2, 2**i]])
# artifact 内のフォルダーに表を追加します。
artifact.add(table, "{}/table_{}".format(parts_path, i))
# artifact をアップサートすると、artifact にデータが作成または追記されます。
run.upsert_artifact(artifact)
# run を並列で起動します。
result_ids = [train.remote(i) for i in range(num_parallel)]
# artifact を完了する前に、すべてのライターのファイルが
# 追加済みであることを確認するために待機します。
ray.get(result_ids)
# すべてのライターが完了したら、artifact を完了して
# 使用可能な状態としてマークします。
with wandb.init(group=group_name) as run:
artifact = wandb.Artifact(artifact_name, type=artifact_type)
# 表のフォルダーを指す "PartitionTable" を作成し、
# artifact に追加します。
artifact.add(wandb.data_types.PartitionedTable(parts_path), table_name)
# artifact を完了すると artifact が確定され、このバージョンへの
# 以降の "upsert" が禁止されます。
run.finish_artifact(artifact)
<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}")
