> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-dbrian-docs-serverless-training-quickstart.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 実験管理、システムモニタリング、Model Management のために Python ライブラリへ Weights & Biases を組み込む際のベストプラクティス。

このガイドでは、Python ライブラリに Weights & Biases (W\&B) を統合する方法を説明します。

W\&B を、トレーニングフレームワーク、SDK、再利用可能なライブラリなどの複雑なコードベースに統合する場合は、以下の推奨事項に従ってください。

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

以下では、扱っているコードベースが単一の Python トレーニングスクリプトや Jupyter Notebook より複雑な場合に役立つヒントとベストプラクティスを紹介します。

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

開始する前に、W\&Bをライブラリの必須依存関係にするか、オプション機能として扱うかを決めてください。

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

W\&B がライブラリの中核機能に関わる場合は、依存関係に W\&B Python SDK (`wandb`) を追加します。

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

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

W\&B がオプション機能である場合は、インストールされていなくてもライブラリが動作するようにします。

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キーを使用してユーザーやマシンを認証します。

<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>

`wandb` ライブラリをローカルにインストールしてログインするには、次の手順を実行します。

<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キー の入力を求められます。

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

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

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

*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 にログする必要があります。

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

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

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

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

ユーザーがライブラリを使用する際に `wandb` をオプションにしたい場合は、次のいずれかの方法を使用できます。

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

<Tabs>
  <Tab title="Python">`python trainer = my_trainer(..., use_wandb=True) `</Tab>
  <Tab title="Bash">`bash 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` をオフラインに設定します。なお、この場合も `wandb` 自体は実行されますが、インターネット経由で W\&B と通信しなくなります。

<Tabs>
  <Tab title="Environment Variable">
    ```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 config を定義する
</div>

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

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

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

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-dbrian-docs-serverless-training-quickstart/t_irD8W7hYE5fbdi/images/integrations/integrations_add_any_lib_runs_page.png?fit=max&auto=format&n=t_irD8W7hYE5fbdi&q=85&s=3e3745d6667d5603e87a45098ec986bc" 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 config を更新する
</div>

初期化時に値を利用できない場合は、後から `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>

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

キーがメトリクスの名になる辞書を作成します。この辞書オブジェクトを [`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 App で関連するメトリクスをグループ化できます。一般的な接頭辞としては、トレーニング用メトリクスの `train/` や検証用メトリクスの `val/` などがありますが、ユースケースに応じて任意の接頭辞を使用できます。

これにより、プロジェクトの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-dbrian-docs-serverless-training-quickstart/t_irD8W7hYE5fbdi/images/integrations/integrations_add_any_lib_log.png?fit=max&auto=format&n=t_irD8W7hYE5fbdi&q=85&s=c83b0b9898b9541604222d5095bb9120" 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>

同じトレーニング 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" の値が wandb によって自動的に使用されます。この場合は、必要になったときに定義済みになっているよう、あらかじめメトリクスの初期値をログしておいてください。

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

スカラーに加えて、画像、表、テキスト、オーディオ、動画などもログできます。

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

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

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

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

分散環境をサポートするフレームワークでは、次のいずれかのワークフローを利用できます。

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

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

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

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

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

ライブラリに Artifacts を統合する際は、次の点を考慮してください。

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

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

モデル チェックポイントを W\&B にログします。一般的には、W\&B が生成する一意の run ID を Artifacts 名の一部として使用し、チェックポイントを Artifacts としてログします。

```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)
```

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

<div id="log-input-artifacts">
  ### 入力Artifactsをログする
</div>

入力として使用するデータセットや事前トレーニング済みモデルをログします:

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

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

<div id="download-artifacts">
  ### Artifacts をダウンロードする
</div>

以前にW\&BにログしたArtifactsをダウンロードし、トレーニングまたは推論のコードで使用します。

runコンテキストがある場合は、[`wandb.Run.use_artifact()`](/ja/models/ref/python/experiments/run) を使用してW\&B内のArtifactsを参照し、その後 [`wandb.Artifact.download()`](/ja/models/ref/python/experiments/artifact) を呼び出してローカルディレクトリにダウンロードします。

```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を初期化せずにArtifactsを参照およびダウンロードできます。これは、分散環境や推論を行う場合など、新しいrunを作成したくないシナリオで役立ちます。

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

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

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

お使いのライブラリがハイパーパラメーターのチューニングをサポートしている場合は、[W\&B Sweeps](/ja/models/sweeps/)を統合して、Experiments を管理・可視化できます。