このガイドでは、Python ライブラリに Weights & Biases (W&B) を統合する方法を説明します。
W&B を、トレーニングフレームワーク、SDK、再利用可能なライブラリなどの複雑なコードベースに統合する場合は、以下の推奨事項に従ってください。
W&B を初めて使う場合は、先にコアガイド (たとえば 実験管理) を確認してください。 wandb) を追加します。
torch==1.8.0
...
wandb==0.13.*
wandb を条件付きで import するか、pyproject.toml でオプションの依存関係として宣言できます。
wandb が利用可能かどうかを確認し、インストールしていない状態でユーザーが W&B の機能を有効にした場合は、明確なエラーを出します。try:
import wandb
_WANDB_AVAILABLE = True
except ImportError:
_WANDB_AVAILABLE = False
pyproject.toml ファイルで wandb をオプションの依存関係として宣言します。[project]
name = "my_awesome_lib"
version = "0.1.0"
dependencies = [
"torch",
"sklearn"
]
[project.optional-dependencies]
dev = [
"wandb"
]
より手早く行うには、User Settings に直接アクセスしてAPIキーを作成してください。新しく作成したAPIキーはすぐにコピーし、パスワードマネージャーなどの安全な場所に保存してください。
- 右上にあるユーザープロフィールアイコンをクリックします。
- User Settings を選択し、API Keys セクションまでスクロールします。
wandb ライブラリをローカルにインストールしてログインするには、次の手順を実行します。
コマンドライン
Python
Python notebook
-
WANDB_API_KEY の環境変数に APIキー を設定します。
export WANDB_API_KEY=<your_api_key>
-
wandb ライブラリをインストールしてログインします。
pip install wandb
wandb login
-
ターミナルで Python SDK をインストールします。
-
Python スクリプトまたはノートブックから W&B にログインします。APIキー の入力を求められます。
import wandb
wandb.login()
次のコードスニペットを Jupyter notebook のセルにコピー＆ペーストして実行します。APIキー の入力を求められます。!pip install wandb
import wandb
wandb.login()
wandb.init() で run を初期化し、プロジェクト名とチーム entity (チーム名) を指定します。プロジェクトを指定しない場合、W&B は run を “uncategorized” というデフォルトのプロジェクトに保存します。:
with wandb.init(project="<project_name>", entity="<entity>") as run:
...
run.finish() を呼び出して run を終了し、すべてのデータを W&B にログする必要があります。
wandb.init() を呼び出すタイミングwandb.init() はできるだけ早く呼び出してください。W&B は stdout、stderr、エラーメッセージをキャプチャするため、デバッグが容易になります。関連するすべての情報が run にキャプチャされるよう、トレーニングループ全体を wandb.init() のコンテキストマネージャーで囲んでください。これにはエラーメッセージも含まれており、デバッグで重要になることがあります。
wandb をオプションにしたい場合は、次のいずれかの方法を使用できます。
- たとえば、次のように
wandb フラグを定義します。
python trainer = my_trainer(..., use_wandb=True)
bash python train.py ... --use-wandb
- または、
wandb.init() で wandb を disabled に設定します。
wandb.init(mode="disabled")
export WANDB_MODE=disabled
- または、
wandb をオフラインに設定します。なお、この場合も wandb 自体は実行されますが、インターネット経由で W&B と通信しなくなります。
Environment Variable
Bash
export WANDB_MODE=offline
os.environ['WANDB_MODE'] = 'offline'
- モデル名、バージョン、アーキテクチャーパラメーター、ハイパーパラメーター。
- データセット名、バージョン、トレーニングまたは検証のサンプル数。
- 学習率、バッチサイズ、オプティマイザーなどのトレーニングパラメーター。
次のコードスニペットは、設定をログする方法を示しています。
config = {"batch_size": 32, ...}
with wandb.init(..., config=config) as run:
...
wandb.Run.config.update を使って設定を更新します。たとえば、モデルをインスタンス化した後で、そのパラメーターを追加したいことがあります。
with wandb.init(...) as run:
model = MyModel(...)
run.config.update({"model_parameters": 3500})
wandb.Run.log() に渡して、W&B にログします。
NUM_EPOCHS = 10
for epoch in range(NUM_EPOCHS):
for input, ground_truth in data:
prediction = model(input)
loss = loss_fn(prediction, ground_truth)
metrics = { "loss": loss }
run.log(metrics)
train/ や検証用メトリクスの val/ などがありますが、ユースケースに応じて任意の接頭辞を使用できます。
これにより、プロジェクトのWorkspaceに、トレーニング用メトリクスと検証用メトリクス、または分けて表示したい他のタイプのメトリクスごとに、個別のセクションが作成されます:
with wandb.init(...) as run:
metrics = {
"train/loss": 0.4,
"train/learning_rate": 0.4,
"val/loss": 0.5,
"val/accuracy": 0.7
}
run.log(metrics)
wandb.Run.log() を参照してください。
同じトレーニング step に対して wandb.Run.log() を複数回呼び出すと、wandb SDK は wandb.Run.log() を呼び出すたびに内部の step カウンタをインクリメントします。このカウンタは、トレーニング ループ内のトレーニング step と一致しないことがあります。
これを避けるには、wandb.init() を呼び出した直後に、wandb.Run.define_metric() を使って x-axis の step を一度だけ明示的に定義します:
with wandb.init(...) as run:
run.define_metric("*", step_metric="global_step")
* は、すべてのメトリクスでグラフの x 軸に global_step が使用されることを意味します。global_step に対してログするメトリクスを特定のものだけにしたい場合は、代わりにそれらを指定できます。
run.define_metric("train/loss", step_metric="global_step")
wandb.Run.log() を呼び出すたびに、メトリクス、step メトリクス、および global_step をログしてください:
for step, (input, ground_truth) in enumerate(data):
...
run.log({"global_step": step, "train/loss": 0.1})
run.log({"global_step": step, "eval/loss": 0.2})
- メトリクスはどのくらいの頻度でログするべきですか。任意にするべきですか。
- 可視化に役立つのは、どのようなタイプのデータですか。
- 画像については、サンプル予測やセグメンテーションマスクなどをログすることで、時間の経過に伴う変化を確認できます。
- テキストについては、後で詳しく調べられるように、サンプル予測の表をログできます。
例については、オブジェクトとメディアをログするを参照してください。
分散環境をサポートするフレームワークでは、次のいずれかのワークフローを利用できます。
- メインプロセスからのみログする (推奨) 。
- すべてのプロセスからログし、共有の
group名でrunをグループ化する。
詳細は分散トレーニングのExperimentsをログするを参照してください。
Artifacts でモデルとデータセットをトラッキングする
- モデル チェックポイントまたはデータセットを Artifacts としてログするかどうか (オプションにする場合) 。
- Artifact の入力参照 (たとえば、
entity/project/artifact) 。
- モデル チェックポイントまたはデータセットをログする頻度。たとえば、各エポック、500 step ごとなどです。
モデル チェックポイントを W&B にログします。一般的には、W&B が生成する一意の run ID を Artifacts 名の一部として使用し、チェックポイントを Artifacts としてログします。
metadata = {"eval/accuracy": 0.8, "train/steps": 800}
artifact = wandb.Artifact(
name=f"model-{run.id}",
metadata=metadata,
type="model"
)
artifact.add_dir("output_model") # モデルの重みが保存されているローカルディレクトリ
aliases = ["best", "epoch_10"]
run.log_artifact(artifact, aliases=aliases)
dataset = wandb.Artifact(name="flowers", type="dataset")
dataset.add_file("flowers.npy")
run.use_artifact(dataset)
run.use_artifact() を使用してその Artifacts を現在の run に関連付けます。これにより、W&B はその run で使用されたデータセットのリネージをトラッキングできます。
以前にW&BにログしたArtifactsをダウンロードし、トレーニングまたは推論のコードで使用します。
runコンテキストがある場合は、wandb.Run.use_artifact() を使用してW&B内のArtifactsを参照し、その後 wandb.Artifact.download() を呼び出してローカルディレクトリにダウンロードします。
with wandb.init(...) as run:
artifact = run.use_artifact("user/project/artifact:latest")
local_path = artifact.download()
import wandb
artifact = wandb.Api().artifact("user/project/artifact:latest")
local_path = artifact.download()
