外部ファイルのトラッキング

reference artifact を使用して、W&B サーバーの外部に保存されたファイルをトラッキングし、使用します。一般的な外部ストレージには、CoreWeave AI Object Storage、Backblaze B2 Cloud Storage、Amazon Simple Storage Service (Amazon S3) バケット、GCS バケット、Azure Blob、HTTP ファイルサーバー、NFS 共有などがあります。 reference artifact は、非リファレンスアーティファクトと同様に動作します。主な違いは、reference artifact に含まれるのが、ファイルのサイズや MD5 チェックサムなどのメタデータのみであることです。ファイル自体がシステムの外部に出ることはありません。 reference artifact は、非リファレンスアーティファクトと同様に操作できます。W&B アプリでは、ファイルブラウザーを使用して reference artifact の内容を閲覧したり、依存関係グラフ全体を確認したり、アーティファクトのバージョン履歴を調べたりできます。ただし、データ自体はアーティファクトに含まれていないため、UI では画像やオーディオなどのリッチメディアをレンダリングできません。

外部ファイルをトラッキングしないアーティファクトをログすると、W&B はアーティファクトのファイルを W&B サーバーに保存します。これは、W&B Python SDK でアーティファクトをログする際のデフォルトの動作です。外部ファイルをトラッキングするアーティファクトをログすると、W&B はオブジェクトの ETag やサイズなどのメタデータをログします。バケットでオブジェクトのバージョン管理が有効になっている場合は、バージョン ID もログされます。

以下のセクションでは、外部の reference artifact をトラッキングする方法を説明します。

外部バケット内のアーティファクトをトラッキングする

W&B Python SDK を使用して、W&B の外部に保存されているファイルへの参照をトラッキングします。

wandb.init() で run を初期化します。
wandb.Artifact() でアーティファクトオブジェクトを作成します。
アーティファクトオブジェクトの wandb.Artifact.add_reference() メソッドで、バケットパスへの参照を指定します。
run.log_artifact() でアーティファクトのメタデータをログします。

import wandb

# W&B run を初期化します
with wandb.init(project="my-project") as run:

  # アーティファクト オブジェクトを作成します
  artifact = wandb.Artifact(name="name", type="type")

  # バケットパスへの参照を追加します
  artifact.add_reference(uri = "uri/to/your/bucket/path")

  # アーティファクトのメタデータをログします
  run.log_artifact(artifact)

例として、バケットに次のディレクトリ構造があるとします。

s3://my-bucket

|datasets/
  |-- mnist/
|models/
  |-- cnn/

datasets/mnist/ ディレクトリには画像のコレクションが含まれています。画像を含む datasets/mnist/ ディレクトリをデータセットアーティファクトとしてトラッキングするには、次のように指定します。

"mnist" などのアーティファクト名を指定します。
アーティファクトオブジェクトを作成する際に、type パラメーターを "dataset" に設定します (wandb.Artifact(type="dataset")) 。
wandb.Artifact.add_reference() を呼び出す際に、datasets/mnist/ ディレクトリへのパスを Amazon S3 URI (s3://my-bucket/datasets/mnist/) として指定します。
run.log_artifact() でアーティファクトをログします。

次のコード例では、reference artifact mnist:latest を作成します。

import wandb

with wandb.init(project="my-project") as run:
  artifact = wandb.Artifact(name="mnist", type="dataset")
  artifact.add_reference(uri="s3://my-bucket/datasets/mnist")
  run.log_artifact(artifact)

W&B アプリでは、ファイルブラウザーを使用して reference artifact の内容を確認し、依存関係グラフ全体を探索し、アーティファクトのバージョン履歴を閲覧できます。データ自体はアーティファクト内に含まれていないため、W&B アプリは画像やオーディオなどのリッチメディアをレンダリングしません。

W&B Artifacts は、CoreWeave Storage、Backblaze B2 Cloud Storage、MinIO など、あらゆる Amazon S3互換インターフェースをサポートしています。AWS_S3_ENDPOINT_URL 環境変数に S3互換サーバーの URL (たとえば Backblaze B2 の場合は https://s3.us-west-001.backblazeb2.com) を設定すると、以下のスクリプトをこれらのプロバイダーでそのまま使用できます。

デフォルトでは、W&B はオブジェクトの接頭辞を追加する際に、オブジェクト数を 10,000 個に制限します。wandb.Artifact.add_reference() を呼び出す際に max_objects= を指定すると、この制限を調整できます。

外部バケットからアーティファクトをダウンロードする

W&B は reference artifact をダウンロードする際、アーティファクトをログしたときに記録されたメタデータを使用して、参照先のバケットからファイルを取得します。バケットでオブジェクトのバージョン管理が有効になっている場合、W&B はアーティファクトをログした時点のファイルの状態に対応するオブジェクトのバージョンを取得します。アーティファクトはトレーニング run 中のバケットのスナップショットとして機能するため、バケットの内容が変化しても、特定のモデルのトレーニングに使用されたデータの正確なバージョンをいつでも参照できます。次のコード例は、reference artifact をダウンロードする方法を示しています。アーティファクトをダウンロードする API は、reference artifact と非リファレンスアーティファクトで共通です。

import wandb

with wandb.init(project="my-project") as run:
  artifact = run.use_artifact("mnist:latest", type="dataset")
  artifact_dir = artifact.download()

ワークフローの一環としてファイルを上書きする場合は、ストレージバケットで ‘オブジェクトのバージョン管理’ を有効にすることを W&B は推奨します。バージョン管理が有効になっていれば、アーティファクトをログした後にファイルが上書きされても、アーティファクトをダウンロードする際に W&B は常にファイルの正しいバージョンを取得できます。使用するサービスに応じて、オブジェクトのバージョン管理を有効にする手順を参照してください: AWS、Google Cloud、Azure。

バケットから外部リソースを追加してダウンロードする

次のコード例では、データセットを Amazon S3 バケットにアップロードし、reference artifact でトラッキングしてからダウンロードします。

import boto3
import wandb

with wandb.init() as run:
  # ここでトレーニングします...

  s3_client = boto3.client("s3")
  s3_client.upload_file(file_name="my_model.h5", bucket="my-bucket", object_name="models/cnn/my_model.h5")

  # モデル アーティファクトをログする
  model_artifact = wandb.Artifact("cnn", type="model")
  model_artifact.add_reference("s3://my-bucket/models/cnn/")
  run.log_artifact(model_artifact)

後でモデルアーティファクトをダウンロードできます。アーティファクト名とタイプを指定してください：

import wandb

with wandb.init() as run:
  artifact = run.use_artifact(artifact_or_name = "cnn", type="model")
  datadir = artifact.download()

Google Cloud または Azure のアーティファクトを参照でトラッキングする方法の一連の手順については、以下の report を参照してください。

クラウドストレージの認証情報

W&B は、使用するクラウドプロバイダーに基づいて認証情報を探すためのデフォルトのメカニズムを使用します。使用される認証情報について詳しくは、クラウドプロバイダーのドキュメントをお読みください：

クラウドプロバイダー	認証情報のドキュメント
CoreWeave AI Object Storage	CoreWeave AI Object Storage documentation
Backblaze B2 Cloud Storage	Backblaze B2 Application Keys documentation
AWS	Boto3 documentation
Google Cloud	Google Cloud documentation
Azure	Azure documentation

AWS の場合、バケットが設定されたユーザーのデフォルトリージョンにない場合は、AWS_REGION 環境変数をバケットのリージョンに合わせて設定する必要があります。

リッチメディア (画像、オーディオ、ビデオ、ポイントクラウドなど) は、バケットの CORS 設定によっては App UI でレンダリングに失敗する場合があります。バケットの CORS 設定で app.wandb.ai を許可リストに追加すると、W&B アプリでそのようなリッチメディアを正しくレンダリングできるようになります。リッチメディア (画像、オーディオ、ビデオ、ポイントクラウドなど) が App UI でレンダリングされない場合は、バケットの CORS ポリシーで app.wandb.ai が許可リストに登録されていることを確認してください。

ファイルシステム内のアーティファクトをトラッキングする

データセットにアクセスする一般的な方法は、トレーニングジョブを実行するすべてのマシンで、リモートファイルシステムへの NFS マウントポイントを公開することです。トレーニングスクリプトからはファイルがローカルのファイルシステムにあるように見えるため、クラウドのストレージバケットに代わる方法として使用できます。ファイルシステム内のアーティファクトをトラッキングするには、次の手順に従います。

wandb.init() で run を初期化します。
wandb.Artifact() でアーティファクトオブジェクトを作成します。
アーティファクトオブジェクトの wandb.Artifact.add_reference() メソッドで、ファイルシステムのパスへの参照を指定します。
run.log_artifact() でアーティファクトのメタデータをログします。

次のコードスニペットをコピー＆ペーストして、マウントされたファイルシステム内のファイルをトラッキングします。山括弧 (< >) で囲まれた値を、ご自身の値に置き換えてください。

import wandb

# run を初期化します
with wandb.init(entity="<entity>", project="<project>") as run:

  # アーティファクト オブジェクトを作成します
  artifact = wandb.Artifact(name="<name>", type="<type>")

  # ファイルシステムのパスへの参照を追加します
  artifact.add_reference("file:///path/to/dataset/")

  # アーティファクトをログします（メタデータのみ）
  run.log_artifact(artifact)

URL 内の 3 つのスラッシュに注意してください。最初の構成要素は、ファイルシステム参照の使用を示す file:// 接頭辞です。2 番目の構成要素は、ファイルシステムのルート / です。残りの構成要素は、トラッキングするディレクトリまたはファイルへのパスです。例として、次の構造を持つファイルシステムが /mount にマウントされているとします。

mount
|datasets/
  |-- mnist/
|models/
  |-- cnn/

datasets/mnist/ ディレクトリをデータセットアーティファクトとしてトラッキングするには、次のコードスニペットを使用できます。

import wandb

with wandb.init() as run:
  artifact = wandb.Artifact("mnist", type="dataset")
  artifact.add_reference("file:///mount/datasets/mnist/")
  run.log_artifact(artifact)

これにより、/mount/datasets/mnist/ に保存されているファイルを指す reference artifact mnist:latest が作成されます。

デフォルトでは、W&B はディレクトリへの参照を追加する際に、ファイル数の上限を 10,000 に設定しています。wandb.Artifact.add_reference() を呼び出す際に max_objects= を指定することで、この上限を調整できます。

同様に、models/cnn/my_model.h5 に保存されているモデルをトラッキングするには、次のコードスニペットを使用できます。

import wandb

with wandb.init() as run:

  # ここでトレーニングします...

  # モデルをディスクに書き込みます

  # アーティファクト オブジェクトを作成します
  model_artifact = wandb.Artifact("cnn", type="model")

  # モデルのファイルパスへの参照を追加します
  model_artifact.add_reference("file:///mount/cnn/my_model.h5")

  # アーティファクトを W&B にログします
  run.log_artifact(model_artifact)

外部ファイルシステムからアーティファクトをダウンロードする

参照先のファイルシステムからファイルをダウンロードするには、非リファレンスアーティファクトと同じ API を使用します。

wandb.init() で run を初期化します。
wandb.Run.use_artifact() メソッドを使用して、ダウンロードするアーティファクトを指定します。
アーティファクトの wandb.Artifact.download() メソッドを呼び出して、参照先のファイルシステムからファイルをダウンロードします。

with wandb.init() as run:
  artifact = run.use_artifact("entity/project/mnist:latest", type="dataset")
  artifact_dir = artifact.download()

W&B は /mount/datasets/mnist の内容を artifacts/mnist:v0/ ディレクトリにコピーします。

アーティファクトを再構築できない場合、Artifact.download() はエラーをスローします。たとえば、アーティファクトに上書きされたファイルへの参照が含まれている場合、そのアーティファクトは再構築できなくなるため、Artifact.download() はエラーをスローします。

​外部バケット内のアーティファクトをトラッキングする

​外部バケットからアーティファクトをダウンロードする

​バケットから外部リソースを追加してダウンロードする

​クラウドストレージの認証情報

​ファイルシステム内のアーティファクトをトラッキングする

​外部ファイルシステムからアーティファクトをダウンロードする

外部バケット内のアーティファクトをトラッキングする

外部バケットからアーティファクトをダウンロードする

バケットから外部リソースを追加してダウンロードする

クラウドストレージの認証情報

ファイルシステム内のアーティファクトをトラッキングする

外部ファイルシステムからアーティファクトをダウンロードする