> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 実験管理、システムのモニタリング、モデル管理のために W&B を Python ライブラリに統合する際のベストプラクティス。

このガイドでは、W\&B を Python ライブラリ、フレームワーク、SDK に統合するためのパターンを説明します。依存関係の管理、認証、任意でログすること、run の初期化、アーティファクト、ハイパーパラメーター調整、分散実行を扱います。

単一のトレーニングスクリプトやノートブックではなく、再利用可能なライブラリコードにわたるインテグレーションを実装する場合は、このガイドを使用してください。W\&B の概要については、[実験管理](/ja/products/wandb/track)を参照してください。

<h2 id="design-the-integration">
  インテグレーションを設計する
</h2>

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

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

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

<h2 id="decide-how-to-install-wb">
  W\&B のインストール方法を決める
</h2>

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

<h3 id="require-wb-as-a-dependency">
  W\&B を必須の依存関係にする
</h3>

W\&B がライブラリの中核を担う場合は、依存関係に `wandb` を追加します。

`requirements.txt` ファイルの場合:

```txt title="requirements.txt" type="text" theme={"system"}
torch
wandb
```

`pyproject.toml` ファイルの場合:

```toml title="pyproject.toml" type="toml" theme={"system"}
[project]
name = "my_awesome_lib"
version = "0.1.0"
dependencies = [
    "torch",
    "wandb",
]
```

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

<h3 id="make-wb-an-optional-dependency">
  W\&B をオプションの依存関係にする
</h3>

W\&B がオプションの機能である場合は、`wandb` なしでライブラリをインストールできるようにします。

`pyproject.toml` で W\&B をオプションの依存関係として宣言します。

```toml title="pyproject.toml" theme={"system"}
[project]
name = "my_awesome_lib"
version = "0.1.0"
dependencies = [
    "torch",
]

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

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

```bash theme={"system"}
pip install "my_awesome_lib[wandb]"
```

<h2 id="authenticate-users">
  ユーザーを認証する
</h2>

W\&B は APIキーを使用してユーザーとマシンを認証します。ライブラリから run をログするには、まず APIキーを発行し、`wandb` クライアントで使用できるようにする必要があります。

W\&B は CLI、環境変数、`wandb.login()` による認証をサポートしています。

<h3 id="create-an-api-key">
  APIキーを作成する
</h3>

<Note>
  より簡単な方法として、[User Settings](https://forge.coreweave.com/settings) に移動して APIキーを作成することもできます。作成した APIキーはすぐにコピーし、パスワードマネージャーなどの安全な場所に保存してください。
</Note>

<h3 id="authenticate-from-the-command-line">
  Command Line から認証する
</h3>

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

```bash theme={"system"}
wandb login
```

W\&B に APIキーの入力を求められます。

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

```bash theme={"system"}
export WANDB_API_KEY="<api_key>"
```

詳しくは、[環境変数](/ja/products/wandb/track/environment-variables)を参照してください。

<h3 id="authenticate-from-python">
  Python から認証する
</h3>

インタラクティブな Python 環境またはノートブックで、次のコードを実行します。

```python theme={"system"}
import wandb

wandb.login()
```

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

<h2 id="make-wb-logging-optional">
  W\&B ロギングを任意にする
</h2>

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

| モード | 動作 |
| - | - |
| `disabled` | W\&B ロギングを無効にします。W\&B は run データの保存もアップロードも行いません。W\&B のメソッドを呼び出しても何も起こりません。 |
| `offline` | run データをアップロードせずにローカルに保存します。run は後で [`wandb sync`](/ja/products/wandb/ref/cli/wandb-sync) を使用してアップロードできます。 |

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

<h3 id="use-disabled-mode">
  `disabled` モードを使用する
</h3>

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

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

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

```bash theme={"system"}
export WANDB_MODE=disabled
```

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

```bash theme={"system"}
wandb disabled
```

<h3 id="use-offline-mode">
  `offline` モードを使用する
</h3>

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

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

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

```bash theme={"system"}
export WANDB_MODE=offline
```

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

```python theme={"system"}
import os

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

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

```bash theme={"system"}
wandb offline
```

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

```bash theme={"system"}
wandb sync <run_directory>
```

<h2 id="initialize-a-run">
  run の初期化
</h2>

認証後、[run](/ja/products/wandb/runs) を初期化して、ライブラリからメトリクス、[設定](/ja/products/wandb/track/config)値、[アーティファクト](/ja/products/wandb/artifacts)をログします。

[`wandb.init()`](/ja/products/wandb/ref/python/functions/init) を呼び出し、project とチーム entity を指定します。project を省略すると、W\&B はデフォルトの `"uncategorized"` project に run を保存します。

トレーニングループを囲むコンテキストマネージャーとして `wandb.init()` を使用します。ブロックを抜けると、W\&B は run を終了し、プロセスが終了する前に保留中のデータを処理します。

たとえば、ライブラリに次のトレーニングループが含まれているとします。

```python icon="python" title="Python" theme={"system"}
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 icon="python" title="Python" highlight={2,13-16,19,30-33} theme={"system"}
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,
        })
```

<Tip>
  **`wandb.init()` を呼び出すタイミング**

  W\&B で監視したい処理の前に `wandb.init()` を呼び出します。トレーニングループ全体を囲むコンテキストマネージャーとして使用すると、run がデバッグに必要な標準出力、標準エラー出力、エラーメッセージを取得します。
</Tip>

[次のセクション](#log-configuration-and-metrics)では、ライブラリから設定値とメトリクスをログする方法を詳しく説明します。

<h2 id="log-configuration-and-metrics">
  設定とメトリクスをログする
</h2>

設定値とメトリクスを W\&B にログすることで、自分やチームのメンバーが実験を[比較](/ja/products/wandb/runs/compare-runs)、[フィルター](/ja/products/wandb/runs/filter-runs#example-filter-run-configuration-values-with-contains)、[グループ化](/ja/products/wandb/runs/grouping)、[再現](/ja/products/wandb/track/reproduce_experiments)できます。

<h3 id="log-configuration-values">
  設定値をログする
</h3>

ハイパーパラメーターやその他のメタデータを記録するには、[設定](/ja/products/wandb/track/config)の辞書を `wandb.init()` に渡します。

わかりやすいキーと JSON にシリアライズ可能な値を使用します：

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

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

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

一部の値は、run の開始時点ではまだ確定していない場合があります。そのような値は、後から `wandb.Run.config.update()` で追加できます:

```python theme={"system"}
run.config.update(
    {
        "model_parameters": 3500,
    }
)
```

詳しくは、[実験を設定する](/ja/products/wandb/track/config)を参照してください。

<h3 id="log-metrics">
  メトリクスをログする
</h3>

トレーニング中に損失や精度などのメトリクスをログします。各キーがメトリクス名、各値がメトリクスの値となる辞書を作成します。この辞書を [`wandb.Run.log()`](/ja/products/wandb/ref/python/experiments/run#method-run-log) に渡します。

次のコードスニペットは、トレーニングと検証のメトリクスを W\&B にログします：

```python icon="python" title="Python" theme={"system"}
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/` などの接頭辞を使用して、関連するメトリクスをグループ化します。

サポートされるデータタイプをログする方法、自動的に追跡されるデータ、ベストプラクティスについては、[メトリクスとデータをログする](/ja/products/wandb/track/log)を参照してください。

モデルとデータセットをトラッキングするには、[アーティファクトでモデルとデータセットをトラッキングする](#track-models-and-datasets-with-artifacts)セクションを参照してください。

<h3 id="define-a-custom-log-axis">
  カスタムのログ軸を定義する
</h3>

デフォルトでは、W\&B はログされたメトリクスを、自動的に増加する step に対してプロットします。`wandb.Run.log()` を呼び出すたびに step が進みます。

`wandb.Run.define_metric()` を使用すると、エポックやグローバルステップなど、別の値に対してメトリクスをプロットできます。

次の例では、`x_axis_squared` を `validation_loss` の X 軸として定義します。ループの各反復処理で、`x_axis_squared` はインデックス `i` の二乗となり、`validation_loss` はランダムに生成された値となります。

```python title="Python" icon="python" theme={"system"}
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)
```

詳しくは、[カスタムのログ軸を定義する](/ja/products/wandb/track/log/customize-logging-axes)を参照してください。

<h2 id="track-models-and-datasets-with-artifacts">
  アーティファクトでモデルとデータセットをトラッキングする
</h2>

メトリクスに加えて、ライブラリが生成または使用するモデルとデータセットを永続化することで、自分やチームのメンバーが run を再現して比較できます。

[W\&B Artifacts](/ja/products/wandb/artifacts) を使用して、ライブラリが生成または使用するモデル、データセット、その他のファイルをバージョン管理します。

アーティファクトのサポートを追加する前に、次の点を決めてください。

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

<h3 id="log-model-checkpoints">
  モデル チェックポイントをログする
</h3>

モデル チェックポイントをアーティファクトとしてログすることで、トレーニング済みの重みを復元、バージョン管理、共有できます。アーティファクト名に run ID を含めて、各チェックポイントをソースの run に関連付けます。

次の例では、10 エポックごとにチェックポイントをログします。名に run ID を含むアーティファクトを作成し、ローカル ディレクトリからモデルの重みを追加して、[カスタム エイリアス](/ja/products/wandb/artifacts/create-a-custom-alias)を付けてアーティファクトをログします。

```python title="Python" icon="python" theme={"system"}
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}")
```

<h3 id="track-run-inputs">
  run の入力をトラッキングする
</h3>

run がデータセットやモデル チェックポイントなどのアーティファクトを使用する場合は、[`wandb.Run.use_artifact()`](/ja/products/wandb/ref/python/experiments/run#method-run-use_artifact) を使用します。W\&B は、そのアーティファクトを run の入力として記録します。

アーティファクトの特定のバージョンを参照するには、アーティファクト名と、必要に応じてエイリアスを指定します。アーティファクト名の形式は `artifact_name:version` または `artifact_name:alias` です。

```python title="Python" icon="python" theme={"system"}
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")
```

<h3 id="track-run-outputs">
  run の出力をトラッキングする
</h3>

[`wandb.Run.log_artifact()`](/ja/products/wandb/ref/python/experiments/run#method-run-log_artifact) を使用すると、アーティファクトを run の出力としてログできます。

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

```python theme={"system"}
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](/ja/products/wandb/artifacts) を参照してください。

<h3 id="download-artifacts">
  アーティファクトのダウンロード
</h3>

[W\&B Public API](/ja/products/wandb/ref/python/public-api) を使用すると、run を作成したり、run の入力関係を記録したりせずに、アーティファクトをダウンロードできます。

```python theme={"system"}
import wandb

api = wandb.Api()

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

local_path = artifact.download()
```

詳細については、[アーティファクトのダウンロードと使用](/ja/products/registry/download_use_artifact)を参照してください。

<h2 id="link-artifacts-to-the-registry">
  アーティファクトを Registry にリンクする
</h2>

[Registry](/ja/products/registry) を使用して、チーム間でアーティファクトのバージョンを共有、管理します。

アーティファクトのバージョンをリンクする前に、次の事項を決めてください。

* 共有するアーティファクトのバージョン。
* リンク先の[コレクション](/ja/products/registry/create_collection)。
* パブリッシュ先の[Registry](/ja/products/registry)。

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

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

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

詳しくは、[アーティファクトのバージョンをコレクションにリンクする](/ja/products/registry/link_version)を参照してください。

<h2 id="tune-hyperparameters">
  ハイパーパラメーターを調整する
</h2>

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

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

詳細については、[Sweeps](/ja/products/wandb/sweeps) を参照してください。

<h2 id="support-distributed-training">
  分散トレーニングをサポートする
</h2>

ライブラリが複数のプロセスまたはマシンをサポートする場合は、どのプロセスが run を作成してデータをログするかを定義します。

一般的なアプローチは次のとおりです。

* メインプロセスからのみログします。この方法により、メトリクスやアーティファクトの重複を避けられます。
* 各プロセスごとに1つの run を作成し、共有の `group` 値で run をグループ化します。

詳細については、[分散トレーニング実験をログする](/ja/products/wandb/track/log/distributed-training) を参照してください。