外部ファイルをトラッキングする - Weights & Biases Documentation

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

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

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

external cloud storage bucket内のartifactをトラッキングする

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

wandb.init()でrunを初期化します。
wandb.Artifact()でartifactオブジェクトを作成します。
artifactオブジェクトのwandb.Artifact.add_reference() methodを使用して、バケット pathへの参照を指定します。
run.log_artifact()でartifactのメタデータをログします。

import wandb

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

  # artifact オブジェクトを作成する
  artifact = wandb.Artifact(name="name", type="type")

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

  # artifact のメタデータをログする
  run.log_artifact(artifact)

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

s3://my-bucket

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

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

"mnist" など、artifact の名を指定します。
artifact オブジェクト (wandb.Artifact(type="dataset")) を作成するときに、type パラメーターを "dataset" に設定します。
wandb.Artifact.add_reference() を呼び出すときに、datasets/mnist/ ディレクトリへのパスを Amazon S3 URI (s3://my-bucket/datasets/mnist/) として指定します。
run.log_artifact() で 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 App では、ファイルブラウザを使用して reference artifact の内容を確認したり、依存関係グラフ全体を探索したり、artifact のバージョン履歴を確認したりできます。データ自体は artifact 内に含まれていないため、W&B App では画像やオーディオなどのリッチメディアは表示されません。

W&B Artifacts は、CoreWeave Storage や MinIO を含む、Amazon S3 互換のあらゆるインターフェースをサポートしています。以下で説明するスクリプトは、AWS_S3_ENDPOINT_URL 環境変数で CoreWeave Storage または MinIO サーバーを指定すれば、どちらのプロバイダでもそのまま動作します。

デフォルトでは、オブジェクトプレフィックスを追加する際、W&B は 10,000 オブジェクトの上限を適用します。この上限は、wandb.Artifact.add_reference() を呼び出すときに max_objects= を指定することで調整できます。

external cloud storage bucket から artifact をダウンロードする

W&B は、artifact のログ時に記録されたメタデータを使用して reference artifact をダウンロードする際、基盤となるバケットからファイルを取得します。バケットでオブジェクトのバージョン管理が有効になっている場合、W&B は artifact がログされた時点でのファイルの状態に対応するオブジェクトのバージョンを取得します。バケットの内容が変化しても、artifact はトレーニング run 中のバケットのスナップショットとして機能するため、特定のモデルがどのデータの正確なバージョンでトレーニングされたかをいつでも参照できます。次のコードサンプルは、reference artifact をダウンロードする方法を示しています。artifact をダウンロードする API は、reference artifact と非 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 では、ワークフローの一環としてファイルを上書きする場合は、ストレージバケットで’オブジェクトのバージョン管理’を有効にすることを推奨しています。バージョン管理が有効になっていれば、artifact のログ後にファイルが上書きされていても、artifact のダウンロード時に 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")

  # モデル artifact をログする
  model_artifact = wandb.Artifact("cnn", type="model")
  model_artifact.add_reference("s3://my-bucket/models/cnn/")
  run.log_artifact(model_artifact)

後で、モデル artifact をダウンロードできます。artifact の名とタイプを指定します。

import wandb

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

Google Cloud または Azure で、参照によって artifact をトラッキングする方法をエンドツーエンドで解説した以下のReportsをご覧ください。

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

W&B は、使用しているクラウドプロバイダに応じたデフォルトの方法で認証情報を探します。使用される認証情報について詳しくは、各クラウドプロバイダのドキュメントを参照してください。

クラウドプロバイダ	認証情報のドキュメント
CoreWeave AI Object Storage	CoreWeave AI Object Storage 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 でこのようなリッチメディアを正しく表示できるようになります。画像、オーディオ、ビデオ、ポイントクラウドなどのリッチメディアが App UI に表示されない場合は、バケットの CORS ポリシーで app.wandb.ai が許可リストに追加されていることを確認してください。

ファイルシステム上のartifactをトラッキングする

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

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

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

import wandb

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

  # artifactオブジェクトを作成する
  artifact = wandb.Artifact(name="<name>", type="<type>")

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

  # artifactをログする（メタデータのみ）
  run.log_artifact(artifact)

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

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

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

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:

  # ここでトレーニング...

  # モデルをディスクに書き込む

  # artifact オブジェクトを作成する
  model_artifact = wandb.Artifact("cnn", type="model")

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

  # artifact を W&B にログする
  run.log_artifact(model_artifact)

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

参照先のファイルシステムから、reference artifact ではない artifact と同じ API を使用してファイルをダウンロードします。

wandb.init() でrunを初期化します。
ダウンロードするartifactを指定するには、wandb.Run.use_artifact() methodを使用します。
artifactの wandb.Artifact.download() methodをcallして、参照先のファイルシステムからファイルをダウンロードします

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 を再構築できない場合にエラーをスローします。たとえば、artifact に上書きされたファイルへの参照が含まれていると、その artifact は再構築できなくなるため、Artifact.download() はエラーをスローします。

​external cloud storage bucket内のartifactをトラッキングする

​external cloud storage bucket から artifact をダウンロードする

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

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

​ファイルシステム上のartifactをトラッキングする

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

external cloud storage bucket内のartifactをトラッキングする

external cloud storage bucket から artifact をダウンロードする

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

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

ファイルシステム上のartifactをトラッキングする

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