> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-locadex-parallel-t9n-main-cs60c8p4o6ik99tylxgp3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

単一のトレーニングスクリプトやノートブックではなく、再利用可能なライブラリコードに統合する場合は、このガイドを使用してください。W\&B の概要については、[Experiment Tracking](/ja/models/track) を参照してください。

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

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

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

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

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

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

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

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

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

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

`pyproject.toml` file の場合：

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

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

<div id="make-wb-an-optional-dependency">
  ### W\&B をオプションの依存関係として扱う
</div>

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

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

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

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

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

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

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

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

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

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

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

<div id="authenticate-from-the-command-line">
  ### コマンドラインから認証する
</div>

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

```bash theme={null}
wandb login
```

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

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

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

詳細は、[環境変数](/ja/models/track/environment-variables)をご覧ください。

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

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

```python theme={null}
import wandb

wandb.login()
```

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

<div id="make-wb-logging-optional">
  ## W\&B をログすることを任意にする
</div>

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

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

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

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

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

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

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

```bash theme={null}
export WANDB_MODE=disabled
```

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

```bash theme={null}
wandb disabled
```

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

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

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

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

```bash theme={null}
export WANDB_MODE=offline
```

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

```python theme={null}
import os

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

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

```bash theme={null}
wandb offline
```

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

```bash theme={null}
wandb sync <run_directory>
```

<div id="initialize-a-run">
  ## run を初期化する
</div>

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

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

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

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

```python icon="python" title="Python" theme={null}
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={null}
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)では、ライブラリから設定値とメトリクスをログする方法を詳しく説明します。

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

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

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

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

わかりやすいキーとJSONシリアル化可能な値を使用します。

```python theme={null}
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={null}
with wandb.init(entity="your-entity", project="your-project-name", config=config) as run:
    # トレーニングの処理。
```

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

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

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

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

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

次のcode snippetは、トレーニングおよび検証のメトリクスをW\&Bにログします。

```python icon="python" title="Python" theme={null}
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/models/track/log)を参照してください。

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

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

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

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

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

```python title="Python" icon="python" theme={null}
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/models/track/log/customize-logging-axes)をご覧ください。

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

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

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

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

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

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

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

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

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

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

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

アーティファクトの名と、特定のバージョンのアーティファクトを参照するための任意のaliasを指定します。アーティファクトの名は、`artifact_name:version` または `artifact_name:alias` の形式です。

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

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

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

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

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

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

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

```python theme={null}
import wandb

api = wandb.Api()

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

local_path = artifact.download()
```

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

<div id="link-artifacts-to-the-wb-registry">
  ## アーティファクト を W\&B Registry にリンクする
</div>

[W\&B Registry](/ja/models/registry) を使用すると、チーム間で アーティファクト バージョンを共有・管理できます。

アーティファクト バージョンをリンクする前に、次の点を決定します。

* 共有する アーティファクト バージョン
* リンク先の[コレクション](/ja/models/registry/create_collection)
* 公開先の[Registry](/ja/models/registry)

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

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

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

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

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

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

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

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

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

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

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

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

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