Python ライブラリに W&B を追加する - Weights & Biases Documentation

このガイドでは、W&B を Python ライブラリ、フレームワーク、または SDK に統合する際のパターンについて説明します。依存関係の管理、認証、オプションでログする、run の初期化、アーティファクト、ハイパーパラメーター調整、分散実行を扱います。単一のトレーニングスクリプトやノートブックではなく、再利用可能なライブラリコードに統合する場合は、このガイドを使用してください。W&B の概要については、Experiment Tracking を参照してください。

インテグレーションを設計する

ライブラリに W&B を追加する前に、以下を決定します。

wandb を必須の依存関係にするか、オプションの依存関係にするか。
W&B データを保存またはアップロードせずに、ユーザーがライブラリを実行できるようにするか。
ライブラリでログする設定値、メトリクス、アーティファクト。
W&B Sweeps によるハイパーパラメーター調整をサポートするか。
モデルやデータセットなどのアーティファクトを、組織の W&B Registry を通じて共有するか。
分散トレーニングや複数のプロセスをライブラリでどのように処理するか。

これらの決定により、ライブラリでの W&B のインポート方法、run のライフサイクル管理方法、および W&B が利用できない場合の動作が決まります。

W&B のインストール方法を決める

W&B をライブラリとともに自動でインストールするか、オプション機能として提供するかを選択します。

W&B を依存関係として指定する

W&B がライブラリの中核となる場合は、依存関係に wandb を追加します。 requirements.txt ファイルの場合：

requirements.txt

torch
wandb

pyproject.toml file の場合：

pyproject.toml

[project]
name = "my_awesome_lib"
version = "0.1.0"
dependencies = [
    "torch",
    "wandb",
]

インテグレーションで使用する W&B の機能に応じて、互換性のあるバージョン範囲を指定することを検討してください。

W&B をオプションの依存関係として扱う

W&B がオプション機能の場合、wandb をインストールせずにライブラリをインストールできるようにします。 pyproject.toml で W&B をオプションの依存関係として宣言します。

pyproject.toml

[project]
name = "my_awesome_lib"
version = "0.1.0"
dependencies = [
    "torch",
]

[project.optional-dependencies]
wandb = [
    "wandb",
]

次のコマンドでインテグレーションをインストールします。

pip install "my_awesome_lib[wandb]"

ユーザー認証

W&B では、APIキーを使用してユーザーやマシンを認証します。ライブラリから Runs をログするには、事前に APIキーを発行し、wandb クライアントで使用できるようにしておく必要があります。 W&B は、CLI、環境変数、wandb.login() による認証をサポートしています。

APIキーを発行する

より手早く行うには、User Settings にアクセスしてAPIキーを作成してください。APIキーはすぐにコピーし、パスワードマネージャーなどの安全な場所に保存してください。

コマンドラインから認証する

ターミナルで次を実行します。

wandb login

W&B からAPIキーの入力を求められます。または、環境変数 WANDB_API_KEY を設定します。

export WANDB_API_KEY="<api_key>"

詳細は、環境変数をご覧ください。

Python から認証する

インタラクティブな Python 環境またはノートブックで、次を呼び出します。

import wandb

wandb.login()

再利用可能なライブラリコードから wandb.login() を自動的に呼び出さないでください。非対話型ワークフローが中断される可能性があります。

W&B をログすることを任意にする

W&B で run データを保存またはアップロードするかどうかを選択します。

モード	動作
`disabled`	W&B をログすることを無効にします。W&B は run データを保存もアップロードもしません。W&B メソッドを Call しても何も起こりません。
`offline`	run データをアップロードせずにローカルに保存します。後で `wandb sync` を使用して run をアップロードできます。

run データを保存しない場合は disabled を使用します。後でアップロードするためにデータをローカルに保存する場合は offline を使用します。

`disabled` モードを使用する

wandb.init() に mode="disabled" を渡します。

with wandb.init(mode="disabled") as run:
    # トレーニングのロジック。

または、環境で WANDB_MODE を設定します。

export WANDB_MODE=disabled

W&B CLI でもモードを設定できます。

wandb disabled

`offline` モードを使用する

wandb.init() に mode="offline" を指定します。

with wandb.init(mode="offline") as run:
    # トレーニングのロジック。

または、環境変数 WANDB_MODE を設定します。

export WANDB_MODE=offline

Python では、wandb.init() を呼び出す前に環境変数を設定します。

import os

os.environ["WANDB_MODE"] = "offline"

W&B CLI を使用してモードを設定することもできます。

wandb offline

オフラインのrunを後でアップロードするには、次を使用します。

wandb sync <run_directory>

run を初期化する

認証後、run を初期化し、ライブラリからメトリクス、設定値、アーティファクトをログします。 wandb.init() を呼び出して、project とチーム entity を指定します。project を省略すると、W&B は run をデフォルトの "uncategorized" project に保存します。トレーニングループを囲むコンテキストマネージャーとして wandb.init() を使用します。ブロックを抜けると、プロセスの終了前に W&B が run を終了し、保留中のデータを処理します。たとえば、ライブラリに次のトレーニングループがあるとします。

Python

import random # データのシミュレーション用

def model(training_data: int) -> int:
    """Model simulation for demonstration purposes."""
    return training_data * 2 + random.randint(-1, 1)  

# 重みとノイズをシミュレート
weights = random.random() # ランダムな重みを初期化
noise = random.random() / 5  # ノイズを模した小さなランダム値

for epoch in range(epochs):
    xb = weights + noise  # シミュレートした入力トレーニングデータ
    yb = weights + noise * 2  # シミュレートした目標出力（入力ノイズの2倍）
    
    y_pred = model(xb)  # モデルの予測
    loss = (yb - y_pred) ** 2  # 平均二乗誤差の損失

    print(f"epoch={epoch}, loss={loss}")

W&B を統合するには、コンテキストマネージャーを使用して run を初期化し、設定値を wandb.init() に渡して、wandb.Run.log() でメトリクスをログします。

Python

import random # データのシミュレーション用
import wandb

def model(training_data: int) -> int:
    """Model simulation for demonstration purposes."""
    return training_data * 2 + random.randint(-1, 1)  

# 重みとノイズをシミュレート
weights = random.random() # ランダムな重みを初期化
noise = random.random() / 5  # ノイズを模した小さなランダム値

# ハイパーパラメーターと設定
config = {
    "epochs": 10,  # トレーニングするエポック数
    "learning_rate": 0.01,  # オプティマイザーの学習率
}

# コンテキストマネージャーを使用して W&B の run を初期化し、終了する
with wandb.init(entity="your-entity", project="your-project-name", config=config) as run:    
    # トレーニングループをシミュレート
    for epoch in range(config["epochs"]):
        xb = weights + noise  # シミュレートした入力トレーニングデータ
        yb = weights + noise * 2  # シミュレートしたターゲット出力（入力ノイズの2倍）
        
        y_pred = model(xb)  # モデルの予測
        loss = (yb - y_pred) ** 2  # 平均二乗誤差の損失

        print(f"epoch={epoch}, loss={loss}")
        # エポックと損失を W&B にログする
        run.log({
            "epoch": epoch,
            "loss": loss,
        })

wandb.init() を呼び出すタイミングW&B でモニタリングする処理の前に、wandb.init() を呼び出します。トレーニングループ全体をコンテキストマネージャーで囲むことで、run はデバッグに必要な標準出力、標準エラー出力、エラーメッセージを取得します。

次のセクションでは、ライブラリから設定値とメトリクスをログする方法を詳しく説明します。

設定とメトリクスをログする

設定値とメトリクスを W&B にログすることで、自分やチームのメンバーが実験を比較、フィルター、グループ化、再現できるようになります。

設定値をログする

設定辞書をwandb.init()に渡して、ハイパーパラメーターやその他のメタデータを記録します。わかりやすいキーとJSONシリアル化可能な値を使用します。

config = {
    "batch_size": 32,
    "learning_rate": 0.001,
    "optimizer": "adam",
    "model": {
        "type": "resnet",
        "depth": 50,
    },
    "dataset": {
        "name": "CIFAR-10",
        "num_classes": 10,
    },
}

辞書を wandb.init() に渡します。

with wandb.init(entity="your-entity", project="your-project-name", config=config) as run:
    # トレーニングの処理。

一部の値は、run の開始時にはまだ利用できないことがあります。後で wandb.Run.config.update() を使用して追加します。

run.config.update(
    {
        "model_parameters": 3500,
    }
)

詳細は、実験を設定するを参照してください。

メトリクスをログする

トレーニング中に、損失やaccuracyなどのメトリクスをログします。キーをメトリクスの名、値をメトリクス値とする辞書を作成します。この辞書をwandb.Run.log()に渡します。次のcode snippetは、トレーニングおよび検証のメトリクスをW&Bにログします。

Python

import wandb

with wandb.init(entity="your-entity", project="your-project-name") as run:
    metrics = {
        "train/loss": 0.4,
        "train/learning_rate": 0.4,
        "val/loss": 0.5, 
        "val/accuracy": 0.7
    }
    run.log(metrics)

train/ や val/ などの接頭辞を使用して、関連するメトリクスをグループ化します。サポートされているデータタイプ、自动的にトラッキングされるデータ、ベストプラクティスに沿ってログする方法については、メトリクスとデータをログするを参照してください。モデルとデータセットをトラッキングするには、artifact を使用してモデルとデータセットをトラッキングするセクションを参照してください。

カスタムログ軸を定義する

デフォルトでは、W&B はログしたメトリクスを自動的に増加するステップに対してプロットします。wandb.Run.log() を呼び出すたびに、ステップが進みます。 wandb.Run.define_metric() を使用すると、エポックやグローバルステップなどの別の値に対してメトリクスをプロットできます。次の例では、validation_loss の x 軸として x_axis_squared を定義します。ループの各反復で、x_axis_squared はインデックス i の二乗、validation_loss はランダムに生成された値です。

Python

import wandb
import random

with wandb.init() as run:
    run.define_metric(step_metric = "x_axis_squared", name = "validation_loss")

    for i in range(10):
        log_dict = {
            "x_axis_squared": i**2,
            "validation_loss": random.random(),
        }
        run.log(log_dict)

詳細は、カスタムログ軸を定義するをご覧ください。

アーティファクトでモデルとデータセットをトラッキングする

メトリクスに加えて、自分自身とチームのメンバーが Runs を再現して比較できるように、ライブラリが生成または使用するモデルとデータセットを永続的に保存できます。 W&B Artifacts を使用して、ライブラリが生成または使用するモデル、データセット、その他のファイルをバージョン管理します。アーティファクトのサポートを追加する前に、次の点を決定してください。

ログするファイル。
アーティファクトをログすることをオプションにするかどうか。
チェックポイントをログする頻度。
アーティファクトとエイリアスの命名方法。
run の入力と出力を表すアーティファクト。

モデルチェックポイントをログする

トレーニング済みの重みを復元、バージョン管理、共有できるように、モデルチェックポイントをアーティファクトとしてログします。各チェックポイントをソースrunに関連付けるため、アーティファクト名にrun IDを含めます。次の例では、10エポックごとにチェックポイントをログします。run IDを含む名前のアーティファクトを作成し、ローカルディレクトリからモデルの重みを追加して、カスタムaliasを指定してアーティファクトをログします。

Python

import wandb
with wandb.init(entity="your-entity", project="your-project-name") as run:

    # ここにトレーニングデータとモデル トレーニングのロジックを記述します

    if epoch % 10 == 0: # 10 エポックごとにモデル チェックポイントをログする

        metadata = {"eval/accuracy": 0.8, "train/steps": 800} 

        artifact = wandb.Artifact(
                        name=f"model-{run.id}", 
                        metadata=metadata, 
                        type="model"
                        )
        artifact.add_dir("./models/output_model") # モデルの重みが保存されているローカルディレクトリ

        run.log_artifact(artifact, aliases=f"epoch_{epoch}")

run の入力をトラッキングする

run がデータセットやモデルチェックポイントなどのアーティファクトを使用する場合は、wandb.Run.use_artifact() を使用します。W&B はアーティファクトをrun の入力として記録します。アーティファクトの名と、特定のバージョンのアーティファクトを参照するための任意のaliasを指定します。アーティファクトの名は、artifact_name:version または artifact_name:alias の形式です。

Python

import wandb

# run を初期化
with wandb.init(entity="your-entity", project="your-project") as run:
  # artifact を取得し、依存関係としてマーク
  artifact = run.use_artifact(artifact_or_name="artifact_name:alias_or_version")

run の出力をトラッキングする

wandb.Run.log_artifact() を使用して、アーティファクトを run の出力としてログします。

wandb.Artifact() を使用してアーティファクトを作成します。
1 つ以上の file をアーティファクトに追加します。
wandb.Run.log_artifact() を使用してアーティファクトをログします。

import wandb

# run を初期化する
with wandb.init(entity="your-entity", project="project-name") as run:
  
  # artifact を作成する
  artifact = wandb.Artifact(name = "artifact-name", type = "artifact-type")
  artifact.add_file(local_path = "path/to/file", name="optional-filename") # artifact に file を追加する

  # artifact を run の出力としてログする
  run.log_artifact(artifact_or_path = artifact)

アーティファクトの作成、管理、使用方法について詳しくは、Artifactsを参照してください。

アーティファクトをダウンロードする

W&B Public API を使用すると、run を作成したり、run の入力関係を記録したりせずにアーティファクトをダウンロードできます。

import wandb

api = wandb.Api()

artifact = api.artifact(
    "<entity>/<project>/<artifact_name>:<alias_or_version>"
)

local_path = artifact.download()

詳細については、アーティファクトのダウンロードと使用を参照してください。

アーティファクトを W&B Registry にリンクする

W&B Registry を使用すると、チーム間でアーティファクトバージョンを共有・管理できます。アーティファクトバージョンをリンクする前に、次の点を決定します。

共有するアーティファクトバージョン
リンク先のコレクション
公開先のRegistry

リンク先の Registry は、あらかじめ存在している必要があります。

次の例では、アーティファクトをログし、Registry 内のコレクションにリンクします。

import wandb
import random

# artifact の公開先となるコレクションと Registry の名前を指定します
COLLECTION_NAME = "collection-name"
REGISTRY_NAME = "registry-name"

# artifact をトラッキングするために W&B Run を初期化します
with wandb.init(project="project-name") as run:
    # ログできるように、模擬的なモデル file を作成します
    with open("my_model.txt", "w") as f:
        f.write("Model: " + str(random.random()))

    # artifact を W&B にログします
    logged_artifact = run.log_artifact(
        artifact_or_path="./my_model.txt", 
        name="artifact-name",
        type="artifact-type" # artifact type を指定します
    )

    # artifact を Registry にリンクします
    run.link_artifact(
        artifact=logged_artifact, 
        target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}"
    )

詳細は、アーティファクトバージョンをコレクションにリンクするを参照してください。

ハイパーパラメーターを調整する

ライブラリがハイパーパラメーター調整をサポートしている場合は、W&B Sweeps を統合して、グリッド探索、ランダム探索、またはベイズ探索を実行します。

W&B は、sweep 設定を基盤となるトレーニングロジックとは分離しておくことを推奨します。トレーニング関数では、sweep 固有のロジックに直接依存するのではなく、wandb.Run.config からパラメーターを読み取るようにしてください。

詳細は、Sweeps を参照してください。

分散トレーニングをサポートする

ライブラリが複数のプロセスまたはマシンをサポートする場合は、どのプロセスでrunを作成し、データをログするかを指定します。一般的なアプローチは次のとおりです。

メインプロセスからのみログする。この方法では、メトリクスとアーティファクトの重複を回避できます。
プロセスごとに1つのrunを作成し、共有のgroup値を使用してrunをグループ化する。

詳細は、分散トレーニングのExperimentsをログするを参照してください。

​インテグレーションを設計する

​W&B のインストール方法を決める

​W&B を依存関係として指定する

​W&B をオプションの依存関係として扱う

​ユーザー認証

​APIキーを発行する

​コマンドラインから認証する

​Python から認証する

​W&B をログすることを任意にする

​disabled モードを使用する

​offline モードを使用する

​run を初期化する

​設定とメトリクスをログする

​設定値をログする

​メトリクスをログする

​カスタムログ軸を定義する

​アーティファクト でモデルとデータセットをトラッキングする

​モデル チェックポイントをログする

​run の入力をトラッキングする

​run の出力をトラッキングする

​アーティファクト をダウンロードする

​アーティファクト を W&B Registry にリンクする

​ハイパーパラメーターを調整する

​分散トレーニングをサポートする

インテグレーションを設計する

W&B のインストール方法を決める

W&B を依存関係として指定する

W&B をオプションの依存関係として扱う

ユーザー認証

APIキーを発行する

コマンドラインから認証する

Python から認証する

W&B をログすることを任意にする

`disabled` モードを使用する

`offline` モードを使用する

run を初期化する

設定とメトリクスをログする

設定値をログする

メトリクスをログする

カスタムログ軸を定義する

アーティファクトでモデルとデータセットをトラッキングする

モデルチェックポイントをログする

run の入力をトラッキングする

run の出力をトラッキングする

アーティファクトをダウンロードする

アーティファクトを W&B Registry にリンクする

ハイパーパラメーターを調整する

分散トレーニングをサポートする