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

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

> 実験管理、システム監視、Model Management のために W&B を Python ライブラリに組み込む際のベストプラクティスです。

このガイドでは、ユーザーがあなたのコードを使用する際に、実験をトラッキングし、システムメトリクスを監視し、モデルを管理できるように、Python ライブラリに W\&B を統合する方法を説明します。対象読者は、独自のフレームワーク、SDK、または再利用可能なトレーニングコードを通じて W\&B の機能を利用できるようにしたい、ライブラリの作成者やメンテナーです。

単一の Python トレーニングスクリプトや Jupyter ノートブックよりも複雑なコードベース (トレーニングフレームワーク、SDK、または再利用可能なライブラリなど) に W\&B を統合する場合は、以下の推奨事項に従ってください。

<Tip>
  W\&B を初めて使用する場合は、先にコアガイド (たとえば [Experiment Tracking](/ja/models/track/)) を確認してください。
</Tip>

以下のセクションでは、主要なインテグレーション上の判断ポイントを順に説明します。具体的には、W\&B のインストール方法、認証方法、run の開始方法と設定方法、メトリクスやアーティファクトをログする方法、そして分散トレーニングやハイパーパラメーター sweep をどのようにサポートするかを扱います。

<div id="decide-how-users-install-wb">
  ## ユーザーによるW\&Bのインストール方法を決める
</div>

開始する前に、W\&Bをライブラリの必須依存関係にするか、オプション機能として扱うかを決めてください。この選択は、W\&B Python SDK (`wandb`) をどのようにimportするか、インストール方法をどのようにドキュメント化するか、また `wandb` が存在しない環境をどのように処理するかに影響します。

<div id="require-wb-as-a-dependency">
  ### W\&B を依存関係として必須にする
</div>

W\&B がライブラリの中核機能に関わる場合は、ライブラリと一緒に自動的にインストールされるよう、依存関係に `wandb` を追加します。

```txt theme={null}
torch==1.8.0 
...
wandb==0.13.*
```

<div id="make-wb-optional-on-installation">
  ### インストール時に W\&B をオプションにする
</div>

W\&B がオプション機能である場合は、実験管理を必要としない Users も引き続きコードを使用できるように、インストールされていなくてもライブラリが動作するようにします。

Python で `wandb` を条件付きで import するか、`pyproject.toml` でオプションの依存関係として宣言できます。

<Tabs>
  <Tab title="Python">
    `wandb` が利用可能かどうかを確認し、インストールしていない状態でユーザーが W\&B の機能を有効にした場合は、明確なエラーを出します。

    ```python theme={null}
    try:
        import wandb
        _WANDB_AVAILABLE = True
    except ImportError:
        _WANDB_AVAILABLE = False
    ```
  </Tab>

  <Tab title="pyproject.toml">
    `pyproject.toml` ファイルで `wandb` をオプションの依存関係として宣言します。

    ```toml theme={null}
    [project]
    name = "my_awesome_lib"
    version = "0.1.0"
    dependencies = [
        "torch",
        "sklearn"
    ]

    [project.optional-dependencies]
    dev = [
        "wandb"
    ]
    ```
  </Tab>
</Tabs>

<div id="authenticate-users">
  ## ユーザー認証
</div>

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

<div id="create-an-api-key">
  ### APIキーを発行する
</div>

APIキーは、クライアントやマシンをW\&Bに認証するために使用します。続いて行うログイン手順で使用できるように、ユーザープロフィールからAPIキーを発行します。

<Note>
  より手早く行うには、[User Settings](https://wandb.ai/settings) にアクセスしてAPIキーを作成してください。APIキーはすぐにコピーし、パスワードマネージャーなどの安全な場所に保存してください。
</Note>

1. 右上にあるユーザープロフィールアイコンをクリックします。
2. **User Settings** を選択し、**API Keys** セクションまでスクロールします。

<div id="install-and-log-in-to-wb">
  ### W\&B をインストールしてログインする
</div>

APIキー を取得したら、`wandb` ライブラリをローカルにインストールしてログインし、以降の Runs が W\&B に対して認証できるようにします。ご利用の環境に合ったタブを選択してください。

<Tabs>
  <Tab title="コマンドライン">
    1. `WANDB_API_KEY` の[環境変数](/ja/models/track/environment-variables/)に APIキー を設定します。`<>` で囲まれた値はご自身の値に置き換えてください。

       ```bash theme={null}
       export WANDB_API_KEY=<your_api_key>
       ```

    2. `wandb` ライブラリをインストールしてログインします。

       ```bash theme={null}
       pip install wandb

       wandb login
       ```
  </Tab>

  <Tab title="Python">
    1. ターミナルで Python SDK をインストールします。
       ```bash theme={null}
       pip install wandb
       ```

    2. Python スクリプトまたはノートブックから W\&B にログインします。APIキー の入力を求められます。
       ```python theme={null}
       import wandb
       wandb.login()
       ```
  </Tab>

  <Tab title="Python notebook">
    次のコードスニペットを Jupyter notebook のセルにコピー＆ペーストして実行します。APIキー の入力を求められます。

    ```python theme={null}
    !pip install wandb

    import wandb
    wandb.login()
    ```
  </Tab>
</Tabs>

<div id="start-a-run">
  ## run を開始する
</div>

認証を設定したら、次のステップは W\&B run を開始することです。これにより、ライブラリがメトリクス、設定、アーティファクトをログする場所を確保できます。

*run* は、トレーニング実験などの単一の計算単位を表します。ほとんどのライブラリでは、トレーニング ジョブごとに 1 つの run が作成されます。run の詳細については、[W\&B Runs](/ja/models/runs/) を参照してください。

[`wandb.init()`](/ja/models/ref/python/functions/init) で run を初期化し、プロジェクト名とチーム entity (チーム名) を指定します。プロジェクトを指定しない場合、W\&B は run を "uncategorized" というデフォルトのプロジェクトに保存します。`<>` で囲まれた値は、ご自身の値に置き換えてください。

```python theme={null}
with wandb.init(project="<project_name>", entity="<entity>") as run:
    ...
```

W\&B では、エラーが発生した場合でも run が確実に適切に終了されるよう、コンテキストマネージャーを使用することを推奨しています。コンテキストマネージャーを使用しない場合は、`run.finish()` を呼び出して run を終了し、すべてのデータを W\&B にログする必要があります。run を終了すると、プロセスが終了する前に、すべてのメトリクス、設定、アーティファクトがアップロードされることが保証されます。

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

  `wandb.init()` はできるだけ早く呼び出してください。W\&B は stdout、stderr、エラーメッセージをキャプチャするため、デバッグが容易になります。

  関連するすべての情報が run にキャプチャされるよう、トレーニングループ全体を `wandb.init()` のコンテキストマネージャーで囲んでください。これにはエラーメッセージも含まれており、デバッグで重要になることがあります。
</Tip>

<div id="set-wandb-as-an-optional-dependency">
  ### `wandb` をオプションの依存関係にする
</div>

実行時に `wandb` をオプションにして、ユーザーが W\&B runs を生成せずにライブラリを実行できるようにしたい場合は、次のいずれかの方法を使用できます。

* `wandb` フラグを定義します。
* `wandb.init()` で `wandb` を `disabled` に設定します。
* `wandb` をオフラインに設定します。なお、この場合も `wandb` 自体は実行されますが、インターネット経由で W\&B と通信しません。

たとえば、次のように `wandb` フラグを定義します。

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    trainer = my_trainer(..., use_wandb=True)
    ```
  </Tab>

  <Tab title="Bash">
    ```bash theme={null}
    python train.py ... --use-wandb
    ```
  </Tab>
</Tabs>

`wandb.init()` で `wandb` を `disabled` に設定します。

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    wandb.init(mode="disabled")
    ```
  </Tab>

  <Tab title="Bash">
    ```bash theme={null}
    export WANDB_MODE=disabled
    ```

    または

    ```bash theme={null}
    wandb disabled
    ```
  </Tab>
</Tabs>

`wandb` をオフラインに設定します。

<Tabs>
  <Tab title="環境変数">
    ```bash theme={null}
    export WANDB_MODE=offline
    ```

    または

    ```python theme={null}
    os.environ['WANDB_MODE'] = 'offline'
    ```
  </Tab>

  <Tab title="Bash">
    ```bash theme={null}
    wandb offline
    ```
  </Tab>
</Tabs>

<div id="define-a-run-config">
  ## run 設定 を定義する
</div>

run を初期化した後、その run に関連付けられたハイパーパラメーターやその他のメタデータを記録する設定辞書を追加できます。設定をログすると、後から run を比較、フィルター、再現しやすくなります。

run の初期化時に設定辞書を指定すると、ハイパーパラメーターやその他のメタデータを W\&B にログできます。

W\&B では、設定パラメーターに基づいて run を比較したり、Runs table でフィルターしたりできます。また、これらのパラメーターを使って、W\&B で run をグループ化することもできます。

たとえば、次の画像では、バッチサイズ (`batch_size`) が設定パラメーターとして定義されており、Runs table に表示されています (最初の列を参照) 。これにより、ユーザーはバッチサイズに基づいて run をフィルターし、比較できます。

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/mVjDwbx0mC8gYx-b/images/integrations/integrations_add_any_lib_runs_page.png?fit=max&auto=format&n=mVjDwbx0mC8gYx-b&q=85&s=a059dd2d4101adf87649438ea957b35c" alt="W&B Runs table" width="1820" height="768" data-path="images/integrations/integrations_add_any_lib_runs_page.png" />
</Frame>

一般的な設定パラメーターの値には、次のようなものがあります。

* モデル名、バージョン、アーキテクチャーパラメーター、ハイパーパラメーター。
* データセット名、バージョン、トレーニングまたは検証のサンプル数。
* 学習率、バッチサイズ、オプティマイザーなどのトレーニングパラメーター。

次のコードスニペットは、設定をログする方法を示しています。

```python theme={null}
config = {"batch_size": 32, ...}
with wandb.init(..., config=config) as run:
    ...
```

<div id="update-the-run-config">
  ### run 設定 を更新する
</div>

モデルのパラメーター数など、一部の設定値は `wandb.init()` を呼び出す時点ではまだわからないことがあります。初期化時に値を利用できない場合は、後から `wandb.Run.config.update` を使って設定を更新します。たとえば、モデルをインスタンス化した後で、そのパラメーターを追加したいことがあります。

```python theme={null}
with wandb.init(...) as run:
    model = MyModel(...)
    run.config.update({"model_parameters": 3500})
```

詳細は、[Experiments の設定](/ja/models/track/config/)を参照してください。

<div id="log-metrics-and-data">
  ## メトリクスとデータをログする
</div>

run を開始して設定したら、メトリクスやその他のデータをログできるようになります。これにより、W\&B はそれらを run に紐付けて記録します。

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

損失や accuracy などのスカラーメトリクスをログするには、キーがメトリクスの名になる辞書を作成します。この辞書オブジェクトを [`wandb.Run.log()`](/ja/models/ref/python/experiments/run#method-run-log) に渡して、W\&B にログします。

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

メトリクス名に接頭辞を付けると、W\&B で関連するメトリクスをグループ化できます。一般的な接頭辞としては、トレーニング用メトリクスの `train/` や検証用メトリクスの `val/` などがありますが、ユースケースに応じて任意の接頭辞を使用できます。

これにより、project のWorkspaceに、トレーニング用メトリクスと検証用メトリクス、または分けて表示したい他のタイプのメトリクスごとに、個別のセクションが作成されます:

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

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/mVjDwbx0mC8gYx-b/images/integrations/integrations_add_any_lib_log.png?fit=max&auto=format&n=mVjDwbx0mC8gYx-b&q=85&s=da8be42cd29aef0849aa301423982676" alt="W&B Workspace" width="1236" height="738" data-path="images/integrations/integrations_add_any_lib_log.png" />
</Frame>

詳しくは [`wandb.Run.log()`](/ja/models/ref/python/experiments/run#method-run-log) を参照してください。

<div id="control-the-x-axis">
  ### x-axis を制御する
</div>

デフォルトでは、W\&B Python SDK は独自の step カウンタを管理しており、これはトレーニング ループにおける step の意味と一致しない場合があります。同じトレーニング step に対して `wandb.Run.log()` を複数回呼び出すと、wandb SDK は `wandb.Run.log()` を呼び出すたびに内部の step カウンタをインクリメントします。このカウンタは、トレーニング ループ内のトレーニング step と一致しないことがあります。

これを避けるには、`wandb.init()` を呼び出した直後に、`wandb.Run.define_metric()` を使って x-axis の step を一度だけ明示的に定義します:

```python theme={null}
with wandb.init(...) as run:
    run.define_metric("*", step_metric="global_step")
```

グロブパターン `*` は、すべてのメトリクスでグラフの x 軸に `global_step` が使用されることを意味します。`global_step` に対してログするメトリクスを特定のものだけにしたい場合は、代わりにそれらを指定できます。

```python theme={null}
run.define_metric("train/loss", step_metric="global_step")
```

次に、`wandb.Run.log()` を呼び出すたびに、メトリクス、`step` メトリクス、および `global_step` をログしてください:

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

独立したstep変数にアクセスできない場合、たとえば検証ループ中に `global_step` を使用できないときは、以前にログした `global_step` の値が W\&B によって自動的に使用されます。この場合は、必要になったときに定義済みになっているよう、あらかじめメトリクスの初期値をログしておいてください。

<div id="log-media-and-structured-data">
  ### メディアと構造化データをログする
</div>

スカラーに加えて、画像、表、テキスト、オーディオ、動画などもログできます。メトリクスとあわせてメディアをログすることで、ユーザーは時間の経過に伴うモデルの定性的な動作を確認できます。

データをログする際の留意点には、次のようなものがあります。

* メトリクスはどのくらいの頻度でログするべきですか。任意にするべきですか。
* 可視化に役立つのは、どのようなタイプのデータですか。
  * 画像については、サンプル予測やセグメンテーションマスクをログすることで、時間の経過に伴う変化を確認できます。
  * テキストについては、後で詳しく調べられるように、サンプル予測の表をログできます。

詳細は、[オブジェクトとメディアをログする](/ja/models/track/log)を参照してください。

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

ライブラリが複数のプロセスまたはマシンにまたがってトレーニングを実行できる場合は、その環境でW\&Bをどのように動作させるかを決めて、ログの整合性を保ち、重複しないようにしてください。分散環境をサポートするフレームワークでは、次のいずれかのワークフローを利用できます。

* メインプロセスからのみログする (推奨) 。
* すべてのプロセスからログし、共有の`group`名でrunをグループ化する。

詳細は[分散トレーニングのExperimentsをログする](/ja/models/track/log/distributed-training/)を参照してください。

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

メトリクスに加えて、ユーザーが Runs を再現して比較できるように、ライブラリが生成または使用するモデルとデータセットを永続化できます。

[W\&B Artifacts](/ja/models/artifacts/) を使用して、モデルとデータセットをトラッキングし、バージョン管理できます。アーティファクト は機械学習アセットのストレージとバージョン管理を提供し、データとモデルの関連性を示すリネージを自動的にトラッキングします。

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/mVjDwbx0mC8gYx-b/images/integrations/integrations_add_any_lib_dag.png?fit=max&auto=format&n=mVjDwbx0mC8gYx-b&q=85&s=e3d7cd8e279f640b8f1a442dc83e1a8c" alt="W&B に保存された Datasets とモデル チェックポイント" width="1622" height="324" data-path="images/integrations/integrations_add_any_lib_dag.png" />
</Frame>

ライブラリに アーティファクト を統合する際は、次の点を考慮してください。

* モデル チェックポイントまたはデータセットを アーティファクト としてログするかどうか (オプションにする場合) 。
* Artifact の入力参照 (たとえば、`entity/project/artifact`) 。
* モデル チェックポイントまたはデータセットをログする頻度。たとえば、各エポックまたは 500 step ごとです。

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

モデル チェックポイントをアーティファクトとしてログすると、ユーザーはトレーニング済みの重みを復元、バージョン管理、共有できます。一般的には、W\&B が生成する一意の run ID を アーティファクト 名の一部として使用し、チェックポイントを アーティファクト としてログします。

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

前のスニペットでは、モデル チェックポイントをアーティファクトとしてログし、評価精度やトレーニング step などのメタデータを追加します。このアーティファクトの名には一意のrun IDが含まれ、すばやく参照できるように[カスタムエイリアス](/ja/models/artifacts/create-a-custom-alias/)が設定されます。

<div id="log-input-artifacts">
  ### 入力アーティファクトをログする
</div>

データとモデルのリネージを取得するには、run が入力として使用するデータセットまたは事前トレーニング済みモデルをログします:

```python theme={null}
dataset = wandb.Artifact(name="flowers", type="dataset")
dataset.add_file("flowers.npy")
run.use_artifact(dataset)
```

前のスニペットでは、"flowers" という名前のデータセット用の アーティファクト を作成し、その アーティファクト にファイルを追加しています。`wandb.Run.use_artifact()` の呼び出しによって、その アーティファクト を現在の run に関連付けます。これにより、W\&B はその run で使用されたデータセットのリネージをトラッキングできます。

<div id="download-artifacts">
  ### アーティファクト をダウンロードする
</div>

アーティファクトをログした後、以前にW\&Bにログしたアーティファクトをダウンロードし、トレーニングまたは推論のコードで使用できます。適切な方法は、すでにアクティブなrunがあるかどうかによって異なります。

runコンテキストがある場合は、[`wandb.Run.use_artifact()`](/ja/models/ref/python/experiments/run) を使用してW\&B内のアーティファクトを参照し、その後 [`wandb.Artifact.download()`](/ja/models/ref/python/experiments/artifact) を呼び出してローカルディレクトリにダウンロードします。`wandb.Run.use_artifact()` を使用すると、artifact は現在のrunへの入力としても記録され、リネージが保持されます。

```python theme={null}
with wandb.init(...) as run:
    artifact = run.use_artifact("user/project/artifact:latest")
    local_path = artifact.download()
```

[W\&B Public API](/ja/models/ref/python/public-api/) を使用すると、runを初期化せずにアーティファクトを参照およびダウンロードできます。これは、分散環境や推論を行う場合など、新しいrunを作成したくないシナリオで役立ちます。

```python theme={null}
import wandb
artifact = wandb.Api().artifact("user/project/artifact:latest")
local_path = artifact.download()
```

詳細は、[アーティファクト をダウンロードして使用する](/ja/models/artifacts/download-and-use-an-artifact/)を参照してください。

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

お使いのライブラリがハイパーパラメーターのチューニングをサポートしている場合は、[W\&B Sweeps](/ja/models/sweeps/)を統合して、Experiments を管理・可視化できます。Sweeps は、定義された探索空間内で複数の run を連携して実行し、その結果を W\&B 上に表示することで、ユーザーが設定を並べて比較できるようにします。