Python ライブラリに W&B を追加する

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

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

ライブラリに W&B を追加する前に、次の点を決めてください。

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

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

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

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

W&B を必須の依存関係にする

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

requirements.txt

torch
wandb

pyproject.toml ファイルの場合:

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キーを使用してユーザーとマシンを認証します。ライブラリから run をログするには、まず APIキーを発行し、wandb クライアントで使用できるようにする必要があります。 W&B は CLI、環境変数、wandb.login() による認証をサポートしています。

APIキーを作成する

より簡単な方法として、User Settings に移動して APIキーを作成することもできます。作成した APIキーはすぐにコピーし、パスワードマネージャーなどの安全な場所に保存してください。

Command Line から認証する

ターミナルで次のコマンドを実行します。

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 のメソッドを呼び出しても何も起こりません。
`offline`	run データをアップロードせずにローカルに保存します。run は後で `wandb sync` を使用してアップロードできます。

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 はデフォルトの "uncategorized" project に run を保存します。トレーニングループを囲むコンテキストマネージャーとして 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,
    }
)

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

メトリクスをログする

トレーニング中に損失や精度などのメトリクスをログします。各キーがメトリクス名、各値がメトリクスの値となる辞書を作成します。この辞書を wandb.Run.log() に渡します。次のコードスニペットは、トレーニングと検証のメトリクスを 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/ などの接頭辞を使用して、関連するメトリクスをグループ化します。サポートされるデータタイプをログする方法、自動的に追跡されるデータ、ベストプラクティスについては、メトリクスとデータをログするを参照してください。モデルとデータセットをトラッキングするには、アーティファクトでモデルとデータセットをトラッキングするセクションを参照してください。

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

デフォルトでは、W&B はログされたメトリクスを、自動的に増加する step に対してプロットします。wandb.Run.log() を呼び出すたびに step が進みます。 wandb.Run.define_metric() を使用すると、エポックやグローバルステップなど、別の値に対してメトリクスをプロットできます。次の例では、x_axis_squared を validation_loss の X 軸として定義します。ループの各反復処理で、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)

詳しくは、カスタムのログ軸を定義するを参照してください。

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

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

ログするファイル。
アーティファクトをログするかどうかを任意にするかどうか。
チェックポイントをログする頻度。
アーティファクト名とエイリアスの付け方。
run の入力と出力を表すアーティファクト。

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

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

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 の入力として記録します。アーティファクトの特定のバージョンを参照するには、アーティファクト名と、必要に応じてエイリアスを指定します。アーティファクト名の形式は artifact_name:version または artifact_name:alias です。

Python

import wandb

# run を初期化します
with wandb.init(entity="your-entity", project="your-project") as run:
  # アーティファクトを取得し、依存関係として記録します
  artifact = run.use_artifact(artifact_or_name="artifact_name:alias_or_version")

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

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

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

import wandb

# run を初期化します
with wandb.init(entity="your-entity", project="project-name") as run:
  
  # アーティファクトを作成します
  artifact = wandb.Artifact(name = "artifact-name", type = "artifact-type")
  artifact.add_file(local_path = "path/to/file", name="optional-filename") # アーティファクトにファイルを追加します

  # アーティファクトを 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()

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

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

Registry を使用して、チーム間でアーティファクトのバージョンを共有、管理します。アーティファクトのバージョンをリンクする前に、次の事項を決めてください。

共有するアーティファクトのバージョン。
リンク先のコレクション。
パブリッシュ先のRegistry。

送信先の Registry は、あらかじめ作成されている必要があります。

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

import wandb
import random

# アーティファクトのパブリッシュ先となる
# コレクションとレジストリの名を指定します
COLLECTION_NAME = "collection-name"
REGISTRY_NAME = "registry-name"

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

    # アーティファクトを W&B にログします
    logged_artifact = run.log_artifact(
        artifact_or_path="./my_model.txt", 
        name="artifact-name",
        type="artifact-type" # アーティファクト タイプを指定します
    )

    # アーティファクトをレジストリにリンクします
    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 をグループ化します。

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

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

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

​W&B を必須の依存関係にする

​W&B をオプションの依存関係にする

​ユーザーを認証する

​APIキーを作成する

​Command Line から認証する

​Python から認証する

​W&B ロギングを任意にする

​disabled モードを使用する

​offline モードを使用する

​run の初期化

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

​設定値をログする

​メトリクスをログする

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

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

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

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

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

​アーティファクトのダウンロード

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

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

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

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

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

W&B を必須の依存関係にする

W&B をオプションの依存関係にする

ユーザーを認証する

APIキーを作成する

Command Line から認証する

Python から認証する

W&B ロギングを任意にする

`disabled` モードを使用する

`offline` モードを使用する

run の初期化

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

設定値をログする

メトリクスをログする

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

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

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

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

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

アーティファクトのダウンロード

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

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

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