> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-hivemind-launch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

# 外部ファイルをトラッキングする

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

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

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

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

<div id="track-an-artifact-in-an-external-bucket">
  ## external cloud storage bucket内のartifactをトラッキングする
</div>

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

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

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

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

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

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

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

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

次のコードサンプルは、reference artifact `mnist:latest` を作成します。

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

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

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

<div id="download-an-artifact-from-an-external-bucket">
  ## external cloud storage bucket から artifact をダウンロードする
</div>

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

次のコードサンプルは、reference artifact をダウンロードする方法を示しています。artifact をダウンロードする API は、reference artifact と非 reference artifact のどちらでも同じです。

```python theme={null}
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 では、ワークフローの一環としてファイルを上書きする場合は、ストレージバケットで'オブジェクトのバージョン管理'を有効にすることを推奨しています。

  バージョン管理が有効になっていれば、artifact のログ後にファイルが上書きされていても、artifact のダウンロード時に 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>

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

次のコードサンプルでは、データセットを Amazon S3 バケットにアップロードし、reference artifact としてトラッキングした後、それをダウンロードします。

```python theme={null}
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 の名とタイプを指定します。

```python theme={null}
import wandb

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

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

  * [Google Cloud で参照によって Artifacts をトラッキングするためのガイド](https://wandb.ai/stacey/artifacts/reports/Tracking-Artifacts-by-Reference--Vmlldzo1NDMwOTE)
  * [Microsoft Azure で reference artifacts を扱う](https://wandb.ai/andrea0/azure-2023/reports/Efficiently-Harnessing-Microsoft-Azure-Blob-Storage-with-Weights-Biases--Vmlldzo0NDA2NDgw)
</Note>

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

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

| クラウドプロバイダ                   | 認証情報のドキュメント                                                                                                                                                 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CoreWeave AI Object Storage | [CoreWeave AI Object Storage documentation](https://docs.coreweave.com/docs/products/storage/object-storage/how-to/manage-access-keys/cloud-console-tokens) |
| 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 でこのようなリッチメディアを正しく表示できるようになります。

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

<div id="track-an-artifact-in-a-filesystem">
  ## ファイルシステム上のartifactをトラッキングする
</div>

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

ファイルシステム内のartifactをトラッキングするには、次の手順を実行します。

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

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

```python theme={null}
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` に次のような構造のファイルシステムがマウントされているとします。

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

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

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

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

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

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

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