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() を使って artifact の Python オブジェクトを作成する- artifact に 1 つ以上のファイルを追加する
- artifact を W&B Server に保存する
1. wandb.Artifact() を使って artifact Python オブジェクトを作成する
wandb.Artifact() クラスを初期化します。次のパラメーターを指定します。
- Name: artifact の名前です。名前は一意で、内容がわかりやすく、覚えやすいものにしてください。
- Type: artifact のタイプです。タイプはシンプルでわかりやすく、機械学習パイプライン内の単一の step に対応している必要があります。一般的な artifact タイプには
'dataset' や 'model' があります。
Artifacts には、タイプに関係なく同じ名前を付けることはできません。つまり、dataset タイプの cats という名前の artifact と、model タイプの同じ名前の artifact を別に作成することはできません。
wandb.Artifact クラス定義を参照してください。
次の code snippet をコピー＆ペーストして artifact オブジェクトを作成します。<name> と <type> のプレースホルダーを自分の値に置き換えてください。
import wandb
# artifactオブジェクトを作成する
artifact = wandb.Artifact(name="<name>", type="<type>")
2. artifact にさらにファイルを追加する
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>")
3. artifactをW&B Serverに保存する
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() を非同期で実行します。そのため、ループ内で 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オブジェクトを初期化する
artifact = wandb.Artifact(name="<name>", type="<type>")
# single fileを追加する
artifact.add_file(local_path="path/file.format")
'hello.txt' というファイルがあるとします。
artifact.add_file("hello.txt")
name パラメーターに別の名前を渡すと、artifact オブジェクト内でのファイル名を変更できます。前の例の続きは次のとおりです。
artifact.add_file(
local_path="hello.txt",
name="new/path/hello_world.txt"
)
| API 呼び出し | 生成される artifact |
|---|
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オブジェクトを初期化する
artifact = wandb.Artifact(name="<name>", type="<type>")
# ローカルディレクトリをartifactに追加する
artifact.add_dir(local_path="path/file.format", name="optional-prefix")
| API Call | 生成されるartifact |
|---|
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 を使用して、artifact に外部 URI reference を追加します。'uri' 文字列はご自身の URI に置き換えてください。必要に応じて、name パラメーターに artifact 内の任意のパスを指定できます。
# URI referenceを追加する
artifact.add_reference(uri="uri", name="optional-name")
http(s)://: HTTP 経由でアクセスできるファイルへのパスです。HTTP サーバーが ETag および Content-Length レスポンスヘッダーをサポートしている場合、artifact は ETag とサイズのメタデータの形式でチェックサムをトラッキングします。s3://: S3 内のオブジェクトまたはオブジェクトプレフィックスへのパスです。artifact は、参照先オブジェクトのチェックサムとバージョン管理情報 (バケットでオブジェクトのバージョン管理が有効になっている場合) をトラッキングします。オブジェクトプレフィックスは、そのプレフィックス配下のオブジェクトを含むように展開され、最大 10,000 オブジェクトまで含まれます。gs://: GCS 内のオブジェクトまたはオブジェクトプレフィックスへのパスです。artifact は、参照先オブジェクトのチェックサムとバージョン管理情報 (バケットでオブジェクトのバージョン管理が有効になっている場合) をトラッキングします。オブジェクトプレフィックスは、そのプレフィックス配下のオブジェクトを含むように展開され、最大 10,000 オブジェクトまで含まれます。
次の表は、API 呼び出しによって artifact の内容がどのように変わるかを示しています。
| API 呼び出し | 生成される artifact の内容 |
|---|
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 から artifact にファイルを追加する
import wandb
import time
# この例では、デモンストレーション目的で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):
"""
ライタージョブ。各ライターはartifactに1つの画像を追加します。
"""
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)
# finish_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}")
print(f"ファイルURL: {file.url}")
print(f"bucket内のファイルパス: {file.direct_url}")
