> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

> 外部バケット、HTTP ファイルサーバー、または NFS 共有に保存されたファイルをトラッキングします。

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

*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 では画像やオーディオなどのリッチメディアをレンダリングできません。

<Note>
  外部ファイルをトラッキングしないアーティファクトをログすると、W\&B はアーティファクトのファイルを W\&B サーバーに保存します。これは、W\&B Python SDK でアーティファクトをログする際のデフォルトの動作です。

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

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

<h2 id="track-an-artifact-in-an-external-bucket">
  外部バケット内のアーティファクトをトラッキングする
</h2>

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

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

```python theme={"system"}
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)
```

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

```text theme={"system"}
s3://my-bucket

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

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

1. `"mnist"` などのアーティファクト名を指定します。
2. アーティファクト オブジェクトを作成する際に、`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()` でアーティファクトをログします。

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

```python theme={"system"}
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 の内容を確認し、[依存関係グラフ全体を探索](/ja/products/wandb/artifacts/explore-and-traverse-an-artifact-graph)し、アーティファクトのバージョン履歴を閲覧できます。データ自体はアーティファクト内に含まれていないため、W\&B アプリ は画像やオーディオなどのリッチメディアをレンダリングしません。

<Note>
  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`) を設定すると、以下のスクリプトをこれらのプロバイダーでそのまま使用できます。
</Note>

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

<h2 id="download-an-artifact-from-an-external-bucket">
  外部バケットからアーティファクトをダウンロードする
</h2>

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

次のコード例は、reference artifact をダウンロードする方法を示しています。アーティファクトをダウンロードする API は、reference artifact と非リファレンスアーティファクトで共通です。

```python theme={"system"}
import wandb

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

<Note>
  ワークフローの一環としてファイルを上書きする場合は、ストレージバケットで 'オブジェクトのバージョン管理' を有効にすることを W\&B は推奨します。

  バージョン管理が有効になっていれば、アーティファクトをログした後にファイルが上書きされても、アーティファクトをダウンロードする際に W\&B は常にファイルの正しいバージョンを取得できます。

  使用するサービスに応じて、オブジェクトのバージョン管理を有効にする手順を参照してください: [AWS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/manage-versioning-examples.html)、[Google Cloud](https://cloud.google.com/storage/docs/using-object-versioning#set)、[Azure](https://learn.microsoft.com/azure/storage/blobs/versioning-enable)。
</Note>

<h2 id="add-and-download-an-external-from-a-bucket">
  バケットから外部リソースを追加してダウンロードする
</h2>

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

```python theme={"system"}
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)
```

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

```python theme={"system"}
import wandb

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

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

  * [Google Cloud で参照によってアーティファクトをトラッキングするためのガイド](https://forge.coreweave.com/wandb/stacey/artifacts/reports/Tracking-Artifacts-by-Reference--Vmlldzo1NDMwOTE)
  * [Microsoft Azure での reference artifact の使用](https://forge.coreweave.com/wandb/andrea0/azure-2023/reports/Efficiently-Harnessing-Microsoft-Azure-Blob-Storage-with-Weights-Biases--Vmlldzo0NDA2NDgw)
</Note>

<h2 id="cloud-storage-credentials">
  クラウドストレージの認証情報
</h2>

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

| クラウドプロバイダー | 認証情報のドキュメント |
| - | - |
| CoreWeave AI Object Storage | [CoreWeave AI Object Storage documentation](/products/storage/object-storage/auth-access/manage-access-keys/create-keys) |
| Backblaze B2 Cloud Storage | [Backblaze B2 Application Keys documentation](https://www.backblaze.com/docs/cloud-storage-application-keys) |
| AWS | [Boto3 documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials) |
| Google Cloud | [Google Cloud documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc) |
| Azure | [Azure documentation](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python) |

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

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

  リッチメディア (画像、オーディオ、ビデオ、ポイントクラウドなど) が App UI でレンダリングされない場合は、バケットの CORS ポリシーで `app.wandb.ai` が許可リストに登録されていることを確認してください。
</Warning>

<h2 id="track-an-artifact-in-a-filesystem">
  ファイルシステム内のアーティファクトをトラッキングする
</h2>

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

ファイルシステム内のアーティファクトをトラッキングするには、次の手順に従います。

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

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

```python theme={"system"}
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` にマウントされているとします。

```text theme={"system"}
mount
|datasets/
  |-- mnist/
|models/
  |-- cnn/
```

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

```python theme={"system"}
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` が作成されます。

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

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

```python theme={"system"}
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)
```

<h2 id="download-an-artifact-from-an-external-filesystem">
  外部ファイルシステムからアーティファクトをダウンロードする
</h2>

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

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

```python theme={"system"}
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/` ディレクトリにコピーします。

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