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

外部 バケット 、HTTP ファイル サーバー 、または NFS シェアに保存されたファイルを追跡します。

W&B サーバーの外に保存されているファイルを追跡・利用するには、リファレンス Artifacts を使用します。一般的な外部ストレージソリューションには、CoreWeave AI Object Storage、Amazon Simple Storage Service (Amazon S3) バケット、GCS バケット、Azure blob、HTTP ファイルサーバー、NFS シェアなどがあります。

リファレンス Artifacts は、通常（非リファレンス）の Artifacts と同様に動作します。主な違いは、リファレンス Artifacts にはファイルサイズや MD5 チェックサムなどのファイルに関する メタデータ のみが含まれる点です。ファイル自体がお客様のシステムから外に出ることはありません。

リファレンス Artifacts は、通常の Artifacts と同じように操作できます。W&B App では、ファイルブラウザを使用してリファレンス Artifact の内容を閲覧したり、完全な依存関係グラフを探索したり、Artifact のバージョン履歴をスキャンしたりできます。ただし、データ自体が Artifact 内に含まれていないため、UI 上で画像や音声などのリッチメディアをレンダリングすることはできません。

外部ファイルを追跡しない Artifact を ログ に記録する場合、W&B は Artifact のファイルを W&B サーバーに保存します。これは、W&B Python SDK で Artifacts を ログ に記録する際のデフォルトの 振る舞い です。

外部ファイルを追跡する Artifact を ログ に記録する場合、W&B はオブジェクトの ETag やサイズなどの メタデータ を ログ に記録します。バケットでオブジェクトの バージョン管理 が有効になっている場合は、バージョン ID も ログ に記録されます。

以下のセクションでは、外部リファレンス Artifacts を追跡する方法について説明します。

​

外部バケット内の Artifact を追跡する

W&B Python SDK を使用して、W&B の外部に保存されているファイルへの参照を追跡します。

1. wandb.init() で run を初期化します。
2. wandb.Artifact() で Artifact オブジェクトを作成します。
3. Artifact オブジェクトの wandb.Artifact.add_reference() メソッドを使用して、バケットパスへの参照を指定します。
4. 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")

  # バケットパスへの参照を追加
  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/ ディレクトリー を Datasets Artifact として追跡するには、以下のように指定します。

1. Artifact に "mnist" などの名前を付けます。
2. Artifact オブジェクトを構築する際、type パラメータ を "dataset" に設定します (wandb.Artifact(type="dataset"))。
3. wandb.Artifact.add_reference() を呼び出す際に、datasets/mnist/ ディレクトリー へのパスを Amazon S3 URI (s3://my-bucket/datasets/mnist/) として提供します。
4. run.log_artifact() で Artifact を ログ に記録します。

以下の コードスニペット は、リファレンス 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 内では、ファイルブラウザを使用してリファレンス 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= を指定します。

​

外部バケットから Artifact をダウンロードする

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

以下の コードスニペット は、リファレンス Artifact をダウンロードする方法を示しています。Artifact をダウンロードするための API は、リファレンス Artifact と非リファレンス Artifact の両方で共通です。

import wandb

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

ワークフローの一部としてファイルを上書きする場合は、ストレージバケットで「オブジェクトの バージョン管理 (Object Versioning)」を有効にすることをお勧めします。

バージョン管理 が有効であれば、Artifact が ログ に記録された後にファイルが上書きされたとしても、Artifact をダウンロードする際に W&B は常に正しい バージョン のファイルを取得できます。

ユースケース に応じて、オブジェクトの バージョン管理 を有効にするための手順を確認してください: AWS, Google Cloud, Azure

​

外部バケットからの追加とダウンロード

以下の コードスニペット は、データセット を Amazon S3 バケットにアップロードし、それをリファレンス 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 でリファレンスによって Artifacts を追跡する方法のエンドツーエンドのチュートリアルについては、以下の レポート を参照してください。

• Guide to Tracking Artifacts by Reference with Google Cloud
• Working with Reference Artifacts in Microsoft Azure

​

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

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 を追跡する

データセット への アクセス における一般的なパターンは、トレーニング ジョブを実行するすべてのマシンに対して、リモートファイルシステムへの NFS マウントポイントを公開することです。トレーニングスクリプト の観点からはファイルがローカルの ファイルシステム にあるように見えるため、これはクラウドストレージバケットの代替ソリューションとなります。

ファイルシステム 内の Artifact を追跡するには：

1. wandb.init() で run を初期化します。
2. wandb.Artifact() で Artifact オブジェクトを作成します。
3. Artifact オブジェクトの wandb.Artifact.add_reference() メソッドを使用して、ファイルシステムパスへの参照を指定します。
4. 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 内のトリプルスラッシュに注意してください。最初のコンポーネントは ファイルシステム 参照の使用を示す file:// プレフィックスです。2 番目のコンポーネントは ファイルシステム のルート / です。残りのコンポーネントは、追跡したい ディレクトリー またはファイルへのパスです。

例として、/mount にマウントされた ファイルシステム が以下の構造を持っているとします。

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

datasets/mnist/ ディレクトリー を Datasets 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/ の下に保存されているファイルを指すリファレンス 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")

  # W&BにArtifactをログとして記録
  run.log_artifact(model_artifact)

​

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

リファレンスされた ファイルシステム からファイルをダウンロードするには、非リファレンス Artifact と同じ API を使用します。

1. wandb.init() で run を初期化します。
2. wandb.Run.use_artifact() メソッドを使用して、ダウンロードしたい Artifact を指定します。
3. 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 を再構成できない場合にエラーをスローします。例えば、上書きされたファイルへの参照が Artifact に含まれている場合、Artifact を再構成できなくなるため、Artifact.download() はエラーをスローします。