Track external files
Reference Artifacts を使用して、Amazon S3バケット、GCSバケット、Azure Blob、HTTPファイルサーバー、またはNFSシェアのようなW&Bシステム外に保存されたファイルをトラッキングします。W&B CLI を使用して、W&B Runの外でArtifactsをログします。
Runの外でArtifactsをログする
W&BはRunの外でArtifactsをログするときにRunを作成します。各ArtifactはRunに属し、そのRunはProjectに属します。また、Artifactのバージョンはコレクションに属し、タイプを持ちます。
wandb artifact put コマンドを使って、W&B runの外でArtifactをW&Bサーバーにアップロードします。Artifactを属させたいProjectの名前とArtifactの名前（project/artifact_name）を指定します。オプションでタイプ（TYPE）を指定します。以下のコードスニペットのPATHをアップロードしたいArtifactのファイルパスに置き換えてください。
$ wandb artifact put --name project/artifact_name --type TYPE PATH
指定したProjectが存在しない場合、W&Bは新しいProjectを作成します。Artifactのダウンロード方法については、Download and use artifacts を参照してください。
W&Bの外でArtifactsをトラッキングする
W&B Artifactsを使用してデータセットのバージョン管理やモデルリネージを行い、Reference Artifacts を使用してW&Bサーバーの外に保存されたファイルをトラッキングします。このモードでは、Artifactはファイルのメタデータ（URL、サイズ、チェックサムなど）のみを保存します。基となるデータはシステムから出ることはありません。ファイルやディレクトリーをW&Bサーバーに保存する方法については、Quick start を参照してください。
以下に、参照Artifactsを構築する方法とそれらをワークフローに組み込む最適な方法を説明します。
Amazon S3 / GCS / Azure Blob Storage 参照
W&B Artifactsを使用してクラウドストレージバケット内のデータセットやモデルのバージョン管理を行います。Artifactの参照を使えば、既存のストレージレイアウトを変更せずにバケットの上にトラッキングをシームレスにレイヤー化できます。
Artifactsは基となるクラウドストレージベンダー（AWS、GCP、Azureなど）を抽象化します。次のセクションで説明する情報は、Amazon S3、Google Cloud Storage、Azure Blob Storageに一様に適用されます。
W&B Artifactsは、MinIOを含むすべてのAmazon S3互換インターフェースをサポートします！以下のスクリプトは、AWS_S3_ENDPOINT_URL環境変数をMinIOサーバーに設定するだけで動作します。
次のような構造を持つバケットがあるとします：
s3://my-bucket
+-- datasets/
| +-- mnist/
+-- models/
+-- cnn/
mnist/の下にはイメージのコレクションであるデータセットがあります。これをArtifactでトラッキングしましょう：
import wandb
run = wandb.init()
artifact = wandb.Artifact("mnist", type="dataset")
artifact.add_reference("s3://my-bucket/datasets/mnist")
run.log_artifact(artifact)
デフォルトでは、オブジェクトのプレフィックスを追加する際にW&Bは10,000オブジェクトの制限を課しています。この制限はadd_referenceへの呼び出しでmax_objects=を指定して調整できます。
新しい参照Artifact mnist:latestは通常のArtifactと同様に見え、動作します。唯一の違いは、ArtifactがS3/GCS/Azureオブジェクトに関するETag、サイズ、およびバージョンID（バケットでオブジェクトバージョン管理が有効になっている場合）といったメタデータのみで構成されていることです。
W&Bは使用するクラウドプロバイダーに基づいて資格情報を探すデフォルトのメカニズムを使用します。クラウドプロバイダーの資格情報について詳細は、それぞれのドキュメントを参照してください：
| クラウドプロバイダー | 資格情報ドキュメント |
|---|---|
| AWS | Boto3 documentation |
| GCP | Google Cloud documentation |
| Azure | Azure documentation |
AWSの場合、バケットが配置されている地域が構成済みのユーザーのデフォルトの地域と異なる場合、AWS_REGION環境変数をバケットの地域に設定する必要があります。
このArtifactを通常のArtifactと同様に操作します。App UIでは、ファイルブラウザを使用して参照Artifactの内容を閲覧し、完全な依存関係グラフを調査し、Artifactのバージョン履歴をスキャンできます。
バケットのCORS設定に応じて、画像、音声、ビデオ、ポイントクラウドなどのリッチメディアがApp UIで適切にレンダリングされない場合があります。バケットのCORS設定で app.wandb.ai を許可リストに追加することで、App UIでリッチメディアを正しくレンダリングできます。
プライベートバケットの場合、パネルがApp UIでレンダリングに失敗することがあります。会社にVPNがある場合、バケットのアクセスポリシーを更新してVPN内のIPを許可リストに追加できます。
参照Artifactをダウンロードする
import wandb
run = wandb.init()
artifact = run.use_artifact("mnist:latest", type="dataset")
artifact_dir = artifact.download()
参照Artifactをダウンロードすると、Artifactがログされたときに記録されたメタデータを使用して、W&Bは基となるバケットからファイルを取得します。バケットにオブジェクトバージョン管理が有効になっている場合、W&BはArtifactがログされた時点のファイル状態に対応するオブジェクトバージョンを取得します。これにより、バケットの内容が変化しても、トレーニング時にモデルが使用したデータの正確なバージョンを指し示すことができます。
まとめ
以下のコード例は、Amazon S3、GCS、またはAzureでのデータセットをトラッキングし、トレーニングジョブにフィードするためのシンプルなワークフローを示しています：
import wandb
run = wandb.init()
artifact = wandb.Artifact("mnist", type="dataset")
artifact.add_reference("s3://my-bucket/datasets/mnist")
# Artifactをトラッキングし、このRunの入力として
# マークします。バケット内のファイルが変わった場合にのみ
# 新しいArtifactバージョンがログされます。
run.use_artifact(artifact)
artifact_dir = artifact.download()
# トレーニングをここで実行...
モデルをトラッキングするには、トレーニングスクリプトがモデルファイルをバケットにアップロードした後でモデルArtifactをログします：
import boto3
import wandb
run = wandb.init()
# トレーニング...
s3_client = boto3.client("s3")
s3_client.upload_file("my_model.h5", "my-bucket", "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)
GCPまたはAzureのArtifactsを参照してトラッキングする方法のエンドツーエンドの説明については、次のレポートを参照してください：
ファイルシステム参照
データセットへの迅速なアクセスのためのもう一つの一般的なパターンは、NFSマウントポイントをすべてのトレーニングジョブを実行するマシンに公開することです。これはクラウドストレージバケットよりもシンプルなソリューションとなる可能性があります。トレーニングスクリプトの観点からは、ファイルはローカルのファイルシステムに置かれているように見えるからです。この使いやすさは、マウントされたファイルシステムへの参照をトラッキングするためのArtifactsを使用する場合でも同様です。
次のような構造を持つマウントされたファイルシステムがあるとします：
mount
+-- datasets/
| +-- mnist/
+-- models/
+-- cnn/
mnist/の下にはイメージのコレクションであるデータセットがあります。これをArtifactでトラッキングしましょう：
import wandb
run = wandb.init()
artifact = wandb.Artifact("mnist", type="dataset")
artifact.add_reference("file:///mount/datasets/mnist/")
run.log_artifact(artifact)
デフォルトでは、W&Bはディレクトリーへの参照を追加する際に10,000ファイルの制限を課しています。この制限はadd_referenceへの呼び出しでmax_objects=を指定して調整できます。
URL中の三重スラッシュに注意してください。最初の部分はファイルシステム参照の使用を示す file:// プレフィックスです。次にデータセットへのパスである /mount/datasets/mnist/ が続きます。
結果として得られるArtifact mnist:latest は通常のArtifactと同様に見え、動作します。唯一の違いは、ArtifactがファイルのサイズやMD5チェックサムなどのメタデータのみで構成されていることです。ファイル自体はシステムから離れることはありません。
このArtifactを通常のArtifactと同様に操作できます。UIでは、ファイルブラウザを使用して参照Artifactの内容を閲覧し、完全な依存関係グラフを調査し、Artifactのバージョン履歴をスキャンできます。ただし、データがArtifact自体に含まれていないため、画像、音声などのリッチメディアはUIでレンダリングできません。
参照Artifactのダウンロードは簡単です：
import wandb
run = wandb.init()
artifact = run.use_artifact("entity/project/mnist:latest", type="dataset")
artifact_dir = artifact.download()
ファイルシステム参照の場合、download()操作は参照パスからファイルをコピーしてArtifactディレクトリーを構築します。上記の例では、/mount/datasets/mnistの内容がartifacts/mnist:v0/ディレクトリーにコピーされます。Artifactが上書きされたファイルへの参照を含む場合、download()はエラーをスローします。Artifactを再構築できなくなったためです。
すべてをまとめて、マウントされたファイルシステムの下でデータセットをトラッキングし、トレーニングジョブにフィードするためのシンプルなワークフローは次のとおりです：
import wandb
run = wandb.init()
artifact = wandb.Artifact("mnist", type="dataset")
artifact.add_reference("file:///mount/datasets/mnist/")
# Artifactをトラッキングし、このRunの入力として
# マークします。ディレクトリー下のファイルが変更された場合にのみ
# 新しいArtifactバージョンがログされます。
run.use_artifact(artifact)
artifact_dir = artifact.download()
# トレーニングをここで実行...
モデルをトラッキングするには、トレーニングスクリプトがモデルファイルをマウントポイントに書き込んだ後でモデルArtifactをログします：
import wandb
run = wandb.init()
# トレーニング...
# モデルをディスクに書き込み
model_artifact = wandb.Artifact("cnn", type="model")
model_artifact.add_reference("file:///mount/cnn/my_model.h5")
run.log_artifact(model_artifact)