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

> W&B を使用して、複数の GPU を用いた分散トレーニングの実験をログします。

# 分散トレーニングの実験をログする

分散トレーニングの実験では、複数のマシンまたはクライアントを並列に使用してモデルをトレーニングします。W\&B を使用すると、分散トレーニングの実験をトラッキングできます。ユースケースに応じて、次のいずれかの方法で分散トレーニングの実験をトラッキングしてください。

* **単一のプロセスをトラッキングする**: rank 0 のプロセス (「リーダー」または「コーディネーター」とも呼ばれます) を W\&B でトラッキングします。これは、[PyTorch Distributed Data Parallel](https://pytorch.org/docs/stable/generated/torch.nn.parallel.DistributedDataParallel.html#torch.nn.parallel.DistributedDataParallel) (DDP) クラスを使用した分散トレーニングの実験をログする際の一般的な方法です。
* **複数のプロセスをトラッキングする**: 複数のプロセスをトラッキングするには、次のいずれかの方法を使用できます。
  * プロセスごとに 1 つの run を使用して、各プロセスを個別にトラッキングします。必要に応じて、W\&B App UI でこれらの run をグループ化できます。
  * すべてのプロセスを単一の run にトラッキングします。

<Tip>
  **同時接続**

  同時接続はそれぞれ、コンピュート、メモリ、ネットワークのリソースを消費します。メトリクスをログしない空のクライアント接続であっても、システムメトリクスの更新を定期的に送信するため、チャートの読み込みが遅くなります。

  W\&B では、ワークロードに応じて同時クライアント接続の最大数を制限し、リソース使用量を継続的に監視することを推奨しています。W\&B は、**専用クラウド** で同時クライアント接続数 300 のハードリミットを設定してテストを実施しています。

  **Multi-tenant Cloud** の組織では、分散トレーニングのクライアント接続にも、通常のトレーニング run と同じ[レート制限](/ja/products/wandb/track/limits#rate-limits)が適用されます。[Teams および Enterprise プラン](https://coreweave.com/forge-pricing)のユーザーには、Free プランよりも高いレート制限が適用されます。
</Tip>

<h2 id="track-a-single-process">
  単一プロセスをトラッキングする
</h2>

このセクションでは、rank 0 のプロセスで取得できる値とメトリクスをトラッキングする方法について説明します。この方法は、単一のプロセスから取得できるメトリクスのみをトラッキングする場合に使用します。代表的なメトリクスには、GPU/CPU 使用率、共有検証セットでの動作、勾配とパラメーター、代表的なデータサンプルに対する損失値などがあります。

rank 0 のプロセス内で [`wandb.init()`](/ja/products/wandb/ref/python/functions/init) を使用して W\&B run を初期化し、その run に実験をログします ([`wandb.Run.log()`](/ja/products/wandb/ref/python/experiments/run#method-runlog)) 。

次の[サンプル Python スクリプト (`log-ddp.py`) ](https://github.com/wandb/examples/blob/master/examples/pytorch/pytorch-ddp/log-ddp.py)は、PyTorch DDP を使用して 1 台のマシン上の 2 つの GPU でメトリクスをトラッキングする方法の一例です。[PyTorch DDP](https://pytorch.org/tutorials/intermediate/ddp_tutorial.html) (`torch.nn` の `DistributedDataParallel`) は、分散トレーニングで広く使われているライブラリです。基本的な考え方はどのような分散トレーニング構成にも当てはまりますが、実装は異なる場合があります。

この Python スクリプトは次の処理を行います。

1. `torch.distributed.launch` で複数のプロセスを起動します。
2. `--local_rank` コマンドライン引数で rank を確認します。
3. rank が 0 の場合は、[`train()`](https://github.com/wandb/examples/blob/master/examples/pytorch/pytorch-ddp/log-ddp.py#L24) 関数内で `wandb` によるログを条件付きで設定します。

```python theme={"system"}
if __name__ == "__main__":
    # 引数を取得
    args = parse_args()

    if args.local_rank == 0:  # メインプロセスでのみ実行
        # wandb の run を初期化
        run = wandb.init(
            entity=args.entity,
            project=args.project,
        )
        # DDP でモデルをトレーニング
        train(args, run)
    else:
        train(args)
```

[単一のプロセスで追跡したメトリクスを表示するダッシュボードの例](https://forge.coreweave.com/wandb/ayush-thakur/DDP/runs/1s56u3hc/system)をご覧ください。

このダッシュボードには、2 つの GPU それぞれの温度や使用率などのシステムメトリクスが表示されます。

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/_media/distributed_training_method1.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=66cfba8954542e0e9b4c506218a2090c" alt="GPU メトリクスのダッシュボード" width="1822" height="733" data-path="products/wandb/_media/distributed_training_method1.png" />
</Frame>

ただし、エポックとバッチサイズに応じた損失の値は、1 つの GPU からのみログされています。

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/_media/loss_function_single_gpu.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=d2cf28685aee11bd28eeb635bb69f7ca" alt="損失関数のプロット" width="1207" height="391" data-path="products/wandb/_media/loss_function_single_gpu.png" />
</Frame>

<h2 id="track-multiple-processes">
  複数のプロセスをトラッキングする
</h2>

W\&B で複数のプロセスをトラッキングするには、次のいずれかの方法を使用します。

* プロセスごとに run を作成して、[各プロセスを個別にトラッキングする](/ja/products/wandb/track/log/distributed-training#track-each-process-separately)。
* [すべてのプロセスを単一の run でトラッキングする](/ja/products/wandb/track/log/distributed-training#track-all-processes-to-a-single-run)。

<h3 id="track-each-process-separately">
  各プロセスを個別にトラッキングする
</h3>

このセクションでは、プロセスごとに run を作成して、各プロセスを個別にトラッキングする方法について説明します。各 run では、メトリクスやアーティファクトなどをそれぞれの run にログします。トレーニングの最後に `wandb.Run.finish()` を呼び出して run の完了を示し、すべてのプロセスが正しく終了するようにします。

複数の実験にまたがる run をトラッキングするのは難しい場合があります。これに対処するには、W\&B の初期化時に `group` パラメーターに値を指定し (`wandb.init(group='group-name')`)、各 run がどの実験に属するかをトラッキングします。実験内のトレーニング用および評価用の W\&B run をトラッキングする方法の詳細については、[Group Runs](/ja/products/wandb/runs/grouping) を参照してください。

<Note>
  **個々のプロセスのメトリクスをトラッキングしたい場合は、この方法を使用してください**。典型的な例としては、各ノード上のデータと予測 (データ分布のデバッグ用) や、メインノード以外での個々のバッチのメトリクスが挙げられます。すべてのノードからシステムメトリクスを取得する場合や、メインノードで利用可能なサマリー統計を取得する場合には、この方法は必要ありません。
</Note>

次の Python コードスニペットは、W\&B の初期化時に group パラメーターを設定する方法を示しています。

```python theme={"system"}
if __name__ == "__main__":
    # 引数を取得
    args = parse_args()
    # run を初期化
    run = wandb.init(
        entity=args.entity,
        project=args.project,
        group="DDP",  # この実験のすべての run を 1 つのグループにまとめる
    )
    # DDP でモデルをトレーニング
    train(args, run)

    run.finish()  # run を完了としてマーク
```

W\&B App UI で、複数のプロセスから追跡したメトリクスの[ダッシュボードの例](https://wandb.ai/ayush-thakur/DDP?workspace=user-noahluna)を確認してみましょう。左サイドバーで 2 つの W\&B run がグループ化されている点に注目してください。グループをクリックすると、その実験専用のグループページが表示されます。このグループページでは、各プロセスのメトリクスが個別に表示されます。

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/_media/dashboard_grouped_runs.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=2b7be69d8a7e0b8e0b12d2f16a94627f" alt="グループ化された分散 run" width="3730" height="1618" data-path="products/wandb/_media/dashboard_grouped_runs.png" />
</Frame>

上の画像は、W\&B App UI のダッシュボードです。サイドバーには 2 つの実験が表示されています。1 つは 'null' というラベルの実験、もう 1 つは 'DPP' という名前の実験 (黄色の枠で囲まれたもの) です。グループを展開する (Group ドロップダウンを選択する) と、その実験に関連付けられた W\&B run が表示されます。

<h3 id="organize-distributed-runs">
  分散 run を整理する
</h3>

W\&B の初期化時に `job_type` パラメーターを設定すると (`wandb.init(job_type='type-name')`) 、ノードを役割ごとに分類できます。たとえば、全体を調整するメインノードと、結果を報告する複数のワーカーノードがあるとします。この場合、メインの調整ノードでは `job_type` を `main` に、報告を行うワーカーノードでは `worker` に設定します：

```python theme={"system"}
   # 全体を調整するメインノード
   with wandb.init(project="<project>", job_type="main", group="experiment_1") as run:
        # トレーニングコード

   # 結果を報告するワーカーノード
   with wandb.init(project="<project>", job_type="worker", group="experiment_1") as run:
        # トレーニングコード
```

ノードに `job_type` を設定したら、Workspace に [保存済みビュー](/ja/products/wandb/track/workspaces#create-a-new-saved-workspace-view) を作成して run を整理できます。右上の **action (<Icon icon="ellipsis" iconType="solid" />)** メニューをクリックし、**Save as new view** をクリックします。

たとえば、次のような保存済みビューを作成できます。

* **Default view**: ワーカーノードを除外してノイズを減らします
  * **Filter** をクリックし、**Job Type** を `worker` に設定します。

  * レポート用のノードのみが表示されます

  * **Debug view**: トラブルシューティング用にワーカーノードに絞り込みます
    * **Filter** をクリックし、**Job Type** を `==` `worker` に、**State** を `IN` `crashed` に設定します。
    * クラッシュしたワーカーノード、またはエラー状態のワーカーノードのみが表示されます

  * **All nodes view**: すべてのノードをまとめて表示します
    * フィルターなし
    * 全体をモニタリングする場合に便利です

保存済みビューを開くには、プロジェクトのサイドバーで **Workspaces** をクリックし、メニューをクリックします。リストの上部に Workspace が、下部に保存済みビューが表示されます。

<h3 id="track-all-processes-to-a-single-run">
  すべてのプロセスを単一の run にトラッキングする
</h3>

<Warning>
  `x_` で始まるパラメーター (`x_label` など) はパブリックプレビュー段階です。フィードバックは、[W\&B リポジトリの GitHub issue](https://github.com/wandb/wandb) からお寄せください。
</Warning>

<Note>
  **要件**

  複数のプロセスを単一の run にトラッキングするには、次の要件を満たす必要があります。

  * W\&B Python SDK バージョン `v0.19.9` 以降。

  * W\&B Server v0.68 以降。
</Note>

この方法では、1 つのプライマリノードと 1 つ以上のワーカーノードを使用します。分散ジョブを開始する前に一意の run ID を生成し、すべてのプロセスがその run ID を使用するように設定します。トレーニング中、各ワーカーノードはプライマリノードと同じ run ID にログします。W\&B はすべてのノードのメトリクスを集約し、W\&B App UI に表示します。

プライマリノードでは、[`wandb.init()`](/ja/products/wandb/ref/python/functions/init) で W\&B run を初期化します。その際、次の内容を指定した `wandb.Settings` オブジェクトを `settings` パラメーター (`wandb.init(settings=wandb.Settings()`) に渡します。

1. 共有モードを有効にするため、`mode` パラメーターを `"shared"` に設定します。
2. [`x_label`](https://github.com/wandb/wandb/blob/main/wandb/sdk/wandb_settings.py#L638) に一意のラベルを指定します。`x_label` に指定した値は、W\&B App UI のログやシステムメトリクスで、データの送信元ノードを識別するために使用します。指定しない場合は、ホスト名とランダムなハッシュを使用したラベルが W\&B によって自動的に作成されます。
3. このノードがプライマリノードであることを示すため、[`x_primary`](https://github.com/wandb/wandb/blob/main/wandb/sdk/wandb_settings.py#L660) パラメーターを `True` に設定します。
4. 必要に応じて、`x_stats_gpu_device_ids` に GPU インデックスのリスト (\[0,1,2]) を指定し、W\&B がメトリクスをトラッキングする GPU を指定します。リストを指定しない場合、W\&B はマシン上のすべての GPU のメトリクスをトラッキングします。

各プロセスを開始する前に、生成した run ID を `WANDB_RUN_ID` 環境変数に設定します。プロセスが `wandb.init()` を呼び出すと、W\&B は `WANDB_RUN_ID` を自動的に読み取ります。

<Note>
  `x_primary=True` によって、プライマリノードとワーカーノードが区別されます。設定ファイルやテレメトリなど、ノード間で共有されるファイルをアップロードするのはプライマリノードだけです。ワーカーノードはこれらのファイルをアップロードしません。
</Note>

各ワーカーノードでは、[`wandb.init()`](/ja/products/wandb/ref/python/functions/init) で W\&B run を初期化し、次のように指定します。

1. `settings` パラメーター (`wandb.init(settings=wandb.Settings()`) に、次の内容を指定した `wandb.Settings` オブジェクトを渡します。
   * 共有モードを有効にするため、`mode` パラメーターを `"shared"` に設定します。
   * `x_label` に一意のラベルを指定します。`x_label` に指定した値は、W\&B App UI のログやシステムメトリクスで、データの送信元ノードを識別するために使用します。指定しない場合は、ホスト名とランダムなハッシュを使用したラベルが W\&B によって自動的に作成されます。
   * このノードがワーカーノードであることを示すため、`x_primary` パラメーターを `False` に設定します。
2. ワーカープロセスを開始する前に、プライマリノードと同じ生成済みの run ID を `WANDB_RUN_ID` に設定します。
3. 必要に応じて、[`x_update_finish_state`](https://github.com/wandb/wandb/blob/main/wandb/sdk/wandb_settings.py#L772) を `False` に設定します。これにより、プライマリ以外のノードが [run の状態](/ja/products/wandb/runs/run-states#run-states) を途中で `finished` に更新してしまうことを防ぎ、run の状態をプライマリノードで一貫して管理できます。

<Tip>
  * すべてのノードで同じ entity と project を使用してください。これにより、正しい run ID を確実に見つけられます。
  * 分散ジョブを開始する前に run ID を生成してください。ランチャー、スケジューラー、またはオーケストレーションフレームワークを使用して、各プロセスに `WANDB_RUN_ID` を設定します。
  * W\&B の環境変数は各プロセスを開始する前に設定してください。実行時に `os.environ` を変更すると W\&B SDK が変更を検出できない場合があるため、避けてください。
</Tip>

run ID の生成方法と配布方法は、ノードのオーケストレーションに使用するフレームワークによって異なります。このガイドでは、汎用的なランチャーの例は扱いません。次のスニペットは、オーケストレーション層が `WANDB_RUN_ID` を設定した後に、各プロセス内で行う W\&B のセットアップを示しています。

次の例では、プライマリノードで run を初期化します。

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

entity = "your-entity"
project = "your-project"

# プライマリノードで run を初期化します
with wandb.init(
    entity=entity,
    project=project,
    settings=wandb.Settings(
        x_label="rank_0",
        mode="shared",
        x_primary=True,
        x_stats_gpu_device_ids=[0, 1],  # （オプション）GPU 0 と 1 のメトリクスのみをトラッキングします
    )
) as run:
    # ここにプライマリノードの処理を記述します
```

次の例は、ワーカーノードでの対応するセットアップを示しています。rank には、使用しているオーケストレーションフレームワークに応じて、ワーカーごとに一意の ID を設定してください。

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

entity = "your-entity"
project = "your-project"
rank = 1

# ワーカーノードで run を初期化します。
# W&B はワーカープロセスの環境から WANDB_RUN_ID を自動的に読み取ります。
with wandb.init(
    entity=entity,  # プライマリノードと同じ entity を使用します
    project=project,  # プライマリノードと同じ project を使用します
    settings=wandb.Settings(
        x_label=f"rank_{rank}",
        mode="shared",
        x_primary=False,
        x_update_finish_state=False,
    ),
) as run:
    # ここにワーカーノードのロジックを記述します
```

分散デプロイメントでは、ワーカーノードをそれぞれ別のマシンで実行できます。

<Note>
  GKE 上のマルチノード・マルチ GPU の Kubernetes クラスターでモデルをトレーニングするエンドツーエンドの例については、[Distributed Training with Shared Mode](https://forge.coreweave.com/wandb/dimaduev/simple-cnn-ddp/reports/Distributed-Training-with-Shared-Mode--VmlldzoxMTI0NTE1NA) report を参照してください。
</Note>

マルチノードプロセスのコンソールログは、run がログする project で確認できます。

1. run を含む project にアクセスします。
2. プロジェクトのサイドバーで **Runs** タブをクリックします。
3. 表示する run をクリックします。
4. プロジェクトのサイドバーで **Logs** タブをクリックします。

コンソールログページ上部にある UI の検索バーを使うと、`x_label` に指定したラベルでコンソールログをフィルターできます。たとえば次の画像は、`x_label` に `rank0`、`rank1`、`rank2`、`rank3`、`rank4`、`rank5`、`rank6` の値を指定した場合に、コンソールログのフィルターで選択できるオプションを示しています。\`

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/_media/multi_node_console_logs.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=5ac8491c9e4dcbbead2916de6e998750" alt="マルチノードのコンソールログ" width="3278" height="1794" data-path="products/wandb/_media/multi_node_console_logs.png" />
</Frame>

詳細については、[コンソールログ](/ja/products/wandb/app/console-logs)を参照してください。

W\&B はすべてのノードのシステムメトリクスを集約し、W\&B App UI に表示します。たとえば次の画像は、複数のノードのシステムメトリクスを表示したダッシュボードの例です。各ノードには、`x_label` パラメーターで指定した一意のラベル (`rank_0`、`rank_1`、`rank_2`) が付与されています。

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/_media/multi_node_system_metrics.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=cf3ab36b14b7ff48a66524cfbb14f04e" alt="マルチノードのシステムメトリクス" width="2450" height="1570" data-path="products/wandb/_media/multi_node_system_metrics.png" />
</Frame>

ラインプロットパネルのカスタマイズ方法については、[Line plots](/ja/products/wandb/app/features/panels/line-plot) を参照してください。

<h2 id="example-use-cases">
  ユースケースの例
</h2>

以下のコードスニペットでは、高度な分散処理のユースケースでよく見られるシナリオを紹介します。

<h3 id="spawn-process">
  プロセスの生成
</h3>

生成されたプロセスで run を開始する場合は、メイン関数で `wandb.setup()` メソッドを使用します。

```python theme={"system"}
import multiprocessing as mp

def do_work(n):
    with wandb.init(config=dict(n=n)) as run:
        run.log(dict(this=n * n))

def main():
    wandb.setup()
    pool = mp.Pool(processes=4)
    pool.map(do_work, range(4))


if __name__ == "__main__":
    main()
```

<h3 id="share-a-run">
  run を共有する
</h3>

プロセス間で run を共有するには、Run オブジェクトを引数として渡します。

```python theme={"system"}
def do_work(run):
    with wandb.init() as run:
        run.log(dict(this=1))

def main():
    run = wandb.init()
    p = mp.Process(target=do_work, kwargs=dict(run=run))
    p.start()
    p.join()
    run.finish()  # run を完了済みにします


if __name__ == "__main__":
    main()
```

W\&B はログする順序を保証できません。同期処理はスクリプトの作成者が行ってください。

<h2 id="troubleshooting">
  トラブルシューティング
</h2>

W\&B と分散トレーニングを併用する際に発生しやすい、よくある問題が 2 つあります。

1. **トレーニング開始時にハングする** - `wandb` のマルチプロセッシングが分散トレーニングのマルチプロセッシングと干渉すると、`wandb` プロセスがハングすることがあります。
2. **トレーニング終了時にハングする** - `wandb` プロセスが終了すべきタイミングを認識できないと、トレーニング ジョブがハングすることがあります。Python スクリプトの最後で `wandb.Run.finish()` API を呼び出し、run が終了したことを W\&B に通知してください。`wandb.Run.finish()` API を呼び出すと、データのアップロードが完了し、W\&B が終了します。
   分散ジョブの信頼性を高めるため、W\&B では `wandb service` コマンドの使用を推奨しています。上記のトレーニングに関する問題はいずれも、wandb service を利用できないバージョンの W\&B SDK でよく発生します。

<h3 id="enable-wb-service">
  W\&B Service を有効にする
</h3>

ご使用の W\&B SDK のバージョンによっては、W\&B Service がすでにデフォルトで有効になっている場合があります。

<h4 id="wb-sdk-0130-and-above">
  W\&B SDK 0.13.0 以降
</h4>

W\&B SDK `0.13.0` 以降のバージョンでは、W\&B Service はデフォルトで有効になっています。

<h4 id="wb-sdk-0125-and-above">
  W\&B SDK 0.12.5 以降
</h4>

W\&B SDK バージョン 0.12.5 以降で W\&B Service を有効にするには、Python スクリプトを変更します。メイン関数内で `wandb.require()` メソッドを使用し、文字列 `"service"` を渡します。

```python theme={"system"}
if __name__ == "__main__":
    main()


def main():
    wandb.require("service")
    # 以降にスクリプトの残りの処理を記述します
```

最適な操作性を得るために、最新バージョンへのアップグレードをお勧めします。

**W\&B SDK 0.12.4 以前**

W\&B SDK 0.12.4 以前のバージョンを使用している場合は、`WANDB_START_METHOD` 環境変数を `"thread"` に設定し、代わりにマルチスレッドを使用してください。