Pytorch-Fsdp スキル

公式ドキュメントから生成された、pytorch-fsdp 開発に関する包括的なサポート。

このスキルを使用する際

このスキルは以下の場合にトリガーされるべきです：

• pytorch-fsdp を使用している場合
• pytorch-fsdp の機能または API について質問する場合
• pytorch-fsdp ソリューションを実装する場合
• pytorch-fsdp コードをデバッグする場合
• pytorch-fsdp のベストプラクティスを学習する場合

クイックリファレンス

一般的なパターン

パターン 1: ジェネリック Join コンテキストマネージャー# 作成日: 2025年6月6日 | 最終更新日: 2025年6月6日 ジェネリック join コンテキストマネージャーは、不均等な入力での分散学習を容易にします。このページでは関連クラスの API について説明します: Join、Joinable、および JoinHook。チュートリアルについては、「Join コンテキストマネージャーを使用した不均等な入力での分散学習」を参照してください。 class torch.distributed.algorithms.Join(joinables, enable=True, throw_on_early_termination=False, **kwargs)[source]# このクラスはジェネリック join コンテキストマネージャーを定義しており、プロセスが join した後にカスタムフックを呼び出すことができます。これらのフックは、join していないプロセスの集約通信をシャドウして、ハングやエラーを防ぎ、アルゴリズムの正確性を確保する必要があります。フック定義の詳細については、JoinHook を参照してください。 警告 コンテキストマネージャーでは、各参加 Joinable が正確性を確保するために、独自のイテレーション単位の集約通信の前に notify_join_context() メソッドを呼び出す必要があります。 警告 コンテキストマネージャーでは、JoinHook オブジェクト内のすべての process_group 属性が同じである必要があります。複数の JoinHook オブジェクトがある場合、最初のオブジェクトのデバイスが使用されます。プロセスグループおよびデバイス情報は、join していないプロセスの確認と、throw_on_early_termination が有効な場合の例外をスロー通知に使用されます。これらはすべて all-reduce を使用しています。 パラメータ joinables (List[Joinable]) – 参加している Joinable のリスト。そのフックは与えられた順序で反復処理されます。 enable (bool) – 不均等な入力検出を有効にするフラグ。False に設定するとコンテキストマネージャーの機能が無効になり、ユーザーが入力が不均等でないことを知っている場合にのみ設定すべきです。(デフォルト: True)。 throw_on_early_termination (bool) – 不均等な入力の検出時に例外をスロー するかどうかを制御するフラグ。(デフォルト: False)。 例: >>> import os >>> import torch >>> import torch.distributed as dist >>> import torch.multiprocessing as mp >>> import torch.nn.parallel.DistributedDataParallel as DDP >>> import torch.distributed.optim.ZeroRedundancyOptimizer as ZeRO >>> from torch.distributed.algorithms.join import Join >>> >>> # 各スポーンされたワーカーで >>> def worker(rank): >>> dist.init_process_group("nccl", rank=rank, world_size=2) >>> model = DDP(torch.nn.Linear(1, 1).to(rank), device_ids=[rank]) >>> optim = ZeRO(model.parameters(), torch.optim.Adam, lr=0.01) >>> # ランク 1 がランク 0 より 1 つ多い入力を取得 >>> inputs = [torch.tensor([1.]).to(rank) for _ in range(10 + rank)] >>> with Join([model, optim]): >>> for input in inputs: >>> loss = model(input).sum() >>> loss.backward() >>> optim.step() >>> # すべてのランクがハングやエラーなく到達 static notify_join_context(joinable)[source]# join コンテキストマネージャーに、呼び出しプロセスがまだ join していないことを通知します。その後、throw_on_early_termination=True の場合、不均等な入力が検出されたかどうかを確認し(つまり、1 つのプロセスがすでに join 済み)、該当する場合は例外をスロー します。このメソッドは、イテレーション単位の集約通信の前に Joinable オブジェクトから呼び出す必要があります。たとえば、これは DistributedDataParallel のフォワードパスの開始時に呼び出す必要があります。コンテキストマネージャーに渡された最初の Joinable オブジェクトのみが、このメソッドで集約通信を実行し、その他の場合、このメソッドは空操作です。 パラメータ joinable (Joinable) – このメソッドを呼び出す Joinable オブジェクト。 戻り値 プロセスが join していないことをコンテキストマネージャーに通知するための all-reduce の非同期作業ハンドル。joinable が、コンテキストマネージャーに渡された最初のものである場合。それ以外の場合は None。 class torch.distributed.algorithms.Joinable[source]# 参加可能なクラスのための抽象ベースクラスを定義します。参加可能なクラス(Joinable から継承)は、join_hook() を実装し、JoinHook インスタンスを返すことに加えて、デバイスおよびプロセスグループ情報を返す join_device() および join_process_group() を実装する必要があります。 abstract property join_device: device# join コンテキストマネージャーに必要な集約通信を実行するデバイスを返します。 abstract join_hook(**kwargs)[source]# 与えられた Joinable に対する JoinHook インスタンスを返します。 パラメータ kwargs (dict) – join フックの動作を実行時に変更するためのキーワード引数を含む辞書。同じ join コンテキストマネージャーを共有するすべての Joinable インスタンスに同じ値が転送されます。 戻り値の型 JoinHook abstract property join_process_group: Any# join コンテキストマネージャー自体に必要な集約通信用のプロセスグループを返します。 class torch.distributed.algorithms.JoinHook[source]# join フックを定義します。join コンテキストマネージャーで 2 つのエントリーポイントを提供します。エントリーポイント: join していないプロセスが存在する間に繰り返し呼び出されるメインフックと、すべてのプロセスが join した後に一度呼び出されるポストフック。ジェネリック join コンテキストマネージャーの join フックを実装するには、JoinHook から継承するクラスを定義し、main_hook() および post_hook() を適切にオーバーライドしてください。 main_hook()[source]# join していないプロセスが存在する間にこのフックを呼び出して、学習イテレーション中の集約通信をシャドウします。学習イテレーション、つまり、フォワードパス、バックワードパス、およびオプティマイザーステップ。 post_hook(is_last_joiner)[source]# すべてのプロセスが join した後にフックを呼び出します。追加の bool 引数 is_last_joiner が渡されます。これは、そのランクが join した最後のランクの 1 つであるかどうかを示します。 パラメータ is_last_joiner (bool) – ランクが join した最後のランクの 1 つである場合は True。それ以外の場合は False。

Join

パターン 2: 分散通信パッケージ - torch.distributed# 作成日: 2017年7月12日 | 最終更新日: 2025年9月4日 注釈 分散学習に関連するすべての機能の簡潔な紹介については、PyTorch 分散概要を参照してください。 バックエンド# torch.distributed は 4 つの組み込みバックエンドをサポートしており、各バックエンドは異なる機能を持ちます。以下の表は、各バックエンドで CPU または GPU で使用可能な関数を示しています。NCCL の場合、GPU は CUDA GPU を指し、XCCL の場合は XPU GPU を指します。MPI は、PyTorch のビルドに使用された実装がサポートしている場合にのみ CUDA をサポートします。 バックエンド gloo mpi nccl xccl デバイス CPU GPU CPU GPU CPU GPU CPU GPU send ✓ ✘ ✓ ? ✘ ✓ ✘ ✓ recv ✓ ✘ ✓ ? ✘ ✓ ✘ ✓ broadcast ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ all_reduce ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ reduce ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ all_gather ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ gather ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ scatter ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ reduce_scatter ✓ ✓ ✘ ✘ ✘ ✓ ✘ ✓ all_to_all ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ barrier ✓ ✘ ✓ ? ✘ ✓ ✘ ✓ PyTorch に付属するバックエンド# PyTorch 分散パッケージは Linux (安定版)、MacOS (安定版)、および Windows (プロトタイプ) をサポートしています。デフォルトでは Linux の場合、Gloo および NCCL バックエンドがビルドされ PyTorch 分散に含まれます(CUDA でビルドする場合は NCCL のみ)。MPI はオプションのバックエンドであり、ソースから PyTorch をビルドする場合にのみ含めることができます。(例えば、MPI がインストールされているホストで PyTorch をビルドします。) 注釈 PyTorch v1.8 以降、Windows は NCCL を除くすべての集約通信バックエンドをサポートします。init_process_group() の init_method 引数がファイルを指している場合、以下のスキーマに準拠する必要があります: ローカルファイルシステム、init_method="file:///d:/tmp/some_file" 共有ファイルシステム、init_method="file://////{machine_name}/{share_folder_name}/some_file" Linux プラットフォームと同じように、環境変数 MASTER_ADDR および MASTER_PORT を設定することで TcpStore を有効にできます。 どのバックエンドを使用するか？# 過去には、「どのバックエンドを使用すべきか？」とよく聞かれました。経験則# CUDA GPU による分散学習には NCCL バックエンドを使用してください。 XPU GPU による分散学習には XCCL バックエンドを使用してください。 CPU による分散学習には Gloo バックエンドを使用してください。 InfiniBand インターコネクトを備えた GPU ホスト# NCCL を使用してください。現在、InfiniBand と GPUDirect をサポートしている唯一のバックエンドです。 Ethernet インターコネクトを備えた GPU ホスト# NCCL を使用してください。特にマルチプロセス単一ノードまたはマルチノード分散学習の場合、現在最良の分散 GPU 学習パフォーマンスを提供しています。NCCL で問題が発生した場合は、フォールバックオプションとして Gloo を使用してください。(Gloo は現在 GPU では NCCL より遅く実行されることに注意してください。) InfiniBand インターコネクトを備えた CPU ホスト# InfiniBand が IB 上の IP を有効にしている場合は Gloo を使用し、そうでない場合は MPI を使用してください。今後のリリースで Gloo に InfiniBand サポートを追加することを計画しています。 Ethernet インターコネクトを備えた CPU ホスト# MPI を使用する具体的な理由がない限り、Gloo を使用してください。 共通環境変数# 使用するネットワークインターフェイスの選択# デフォルトでは、NCCL および Gloo バックエンドの両方が、使用する適切なネットワークインターフェイスを自動的に検出しようとします。自動検出されたインターフェイスが正しくない場合は、以下の環境変数を使用してオーバーライドできます(それぞれのバックエンドに適用可能)。 NCCL_SOCKET_IFNAME、例えば export NCCL_SOCKET_IFNAME=eth0 GLOO_SOCKET_IFNAME、例えば export GLOO_SOCKET_IFNAME=eth0 Gloo バックエンドを使用している場合、複数のインターフェイスをコンマで区切って指定できます。このように指定します: export GLOO_SOCKET_IFNAME=eth0,eth1,eth2,eth3。バックエンドは、これらのインターフェイス全体にラウンドロビン方式で操作をディスパッチします。すべてのプロセスがこの変数に同じ数のインターフェイスを指定することが不可欠です。 その他の NCCL 環境変数# デバッグ - NCCL 障害の場合、NCCL_DEBUG=INFO を設定して明示的な警告メッセージおよび基本的な NCCL 初期化情報を印刷できます。NCCL_DEBUG_SUBSYS を使用して、NCCL の特定の側面についてさらに詳しい情報を取得することもできます。たとえば、NCCL_DEBUG_SUBSYS=COLL は集約呼び出しのログを印刷します。これは、ハングをデバッグする際に役立つ場合があります。特に、集約型またはメッセージサイズの不一致が原因の場合です。トポロジー検出が失敗した場合、NCCL_DEBUG_SUBSYS=GRAPH を設定して詳細な検出結果を検査し、NCCL チームからさらなるサポートが必要な場合は参考資料として保存すると役立ちます。 パフォーマンスチューニング - NCCL はトポロジー検出に基づいて自動チューニングを実行し、ユーザーのチューニング作業を節約します。一部のソケットベースシステムでは、NCCL_SOCKET_NTHREADS および NCCL_NSOCKS_PERTHREAD をチューニングしてソケットネットワーク帯域幅を増加させることをお試しいただけます。これら 2 つの環境変数は、AWS や GCP などの一部のクラウドプロバイダーで NCCL によってプリチューニングされています。NCCL 環境変数の完全なリストについては、NVIDIA NCCL の公式ドキュメントを参照してください。 torch.distributed.ProcessGroupNCCL.NCCLConfig および torch.distributed.ProcessGroupNCCL.Options を使用して NCCL コミュニケーターをさらにチューニングできます。インタープリター内で help を使用してそれらについて詳しく学んでください(例えば help(torch.distributed.ProcessGroupNCCL.NCCLConfig))。 基本# torch.distributed パッケージは、1 つ以上のマシンで実行される複数の計算ノード全体で、マルチプロセス並列化に対する PyTorch サポートおよび通信プリミティブを提供します。クラス torch.nn.parallel.DistributedDataParallel() はこの機能に基づいており、任意の PyTorch モデル周辺のラッパーとして同期分散学習を提供します。これは、Multiprocessing パッケージ - torch.multiprocessing および torch.nn.DataParallel() によって提供される並列化の種類とは異なります。複数のネットワーク接続マシンをサポートしており、ユーザーはプロセスごとにメインの学習スクリプトの個別のコピーを明示的に起動する必要があります。単一マシン同期の場合、torch.distributed または torch.nn.parallel.DistributedDataParallel() ラッパーは、torch.nn.DataParallel() を含む他のデータ並列化アプローチに対して、依然として利点があります。 各プロセスは独自のオプティマイザーを維持し、各イテレーションで完全な最適化ステップを実行します。これは冗長に見えるかもしれませんが、勾配はすでに集約されてプロセス全体で平均化されているため同じですが、これはパラメータブロードキャストステップが不要であることを意味し、ノード間でのテンソル転送に費やされる時間を削減します。 各プロセスは独立した Python インタープリターを含み、複数の実行スレッド、モデルレプリカ、または GPU を単一の Python プロセスから駆動することから生じる追加のインタープリターオーバーヘッドと「GIL スラッシング」を排除します。これは、Python ランタイムを大量に使用するモデル(再帰層を持つモデルや多数の小さなコンポーネントを持つモデルなど)では特に重要です。 初期化# パッケージは、他のメソッドを呼び出す前に、torch.distributed.init_process_group() または torch.distributed.device_mesh.init_device_mesh() 関数を使用して初期化する必要があります。どちらもすべてのプロセスが join するまでブロックします。 警告 初期化はスレッドセーフではありません。プロセスグループ作成は単一のスレッドから実行する必要があります。ランク全体で一貫性のない 'UUID' 割り当てを防ぎ、ハングにつながる可能性のある初期化中のレースを防ぐためです。 torch.distributed.is_available()[source]# 分散パッケージが利用可能な場合、True を返します。そうでない場合、torch.distributed は他の API を公開しません。現在、torch.distributed は Linux、MacOS、および Windows で利用可能です。ソースから PyTorch をビルドする場合は、USE_DISTRIBUTED=1 を設定して有効にしてください。現在、デフォルト値は Linux および Windows の場合 USE_DISTRIBUTED=1、MacOS の場合 USE_DISTRIBUTED=0 です。 戻り値の型 bool torch.distributed.init_process_group(backend=None, init_method=None, timeout=None, world_size=-1, rank=-1, store=None, group_name='', pg_options=None, device_id=None)[source]# デフォルト分散プロセスグループを初期化します。これは分散パッケージも初期化します。プロセスグループを初期化するには 2 つの主な方法があります: store、rank、および world_size を明示的に指定します。 init_method(URL 文字列)を指定します。これはピアを検出する場所/方法を示しています。必要に応じて rank と world_size を指定するか、すべての必須パラメータを URL にエンコードして省略します。どちらも指定されていない場合、init_method は「env://」と見なされます。 パラメータ backend (str または Backend、オプション) – 使用するバックエンド。ビルド時の設定に応じて、有効な値には mpi、gloo、nccl、ucc、xccl、またはサードパーティプラグインによって登録されたバックエンドが含まれます。PyTorch 2.6 以降、backend が提供されない場合、c10d は device_id kwarg で示されるデバイスタイプに対して登録されたバックエンドを使用します(提供されている場合)。既知のデフォルト登録は現在: cuda の場合 nccl、cpu の場合 gloo、xpu の場合 xccl。backend と device_id の両方が提供されない場合、c10d は実行時マシンのアクセラレータを検出し、そのアクセラレータ(または cpu)に対して登録されたバックエンドを使用します。このフィールドは小文字の文字列として指定できます(例えば、「gloo」)。これは Backend 属性経由でもアクセスできます(例えば、Backend.GLOO)。nccl バックエンドで複数のプロセスマシンごとを使用する場合、各プロセスは使用するすべての GPU への排他的アクセスを持つ必要があります。プロセス間での GPU 共有はデッドロックまたは NCCL の無効な使用につながる可能性があります。 ucc バックエンドは実験的です。デバイスのデフォルトバックエンドは get_default_backend_for_device() で照会できます。 init_method (str、オプション) – プロセスグループを初期化する方法を指定する URL。init_method または store が指定されていない場合、デフォルトは「env://」です。store と相互に排他的です。 world_size (int、オプション) – ジョブに参加するプロセスの数。store が指定されている場合は必須です。 rank (int、オプション) – 現在のプロセスのランク(0 から world_size-1 の間の数である必要があります)。store が指定されている場合は必須です。 store (Store、オプション) – すべてのワーカーからアクセス可能なキー/値ストア。接続/アドレス情報を交換するために使用されます。init_method と相互に排他的です。 timeout (timedelta、オプション) – プロセスグループに対して実行される操作のタイムアウト。NCCL の場合のデフォルト値は 10 分、その他のバックエンドの場合は 30 分です。これは、集約がこの期間後に非同期に中止され、プロセスがクラッシュする期間です。これは、CUDA の実行が非同期であり、失敗した非同期 NCCL 操作が破損したデータで後続の CUDA 操作を実行する可能性があるため、ユーザーコードの実行を継続することはもはや安全ではないため行われます。TORCH_NCCL_BLOCKING_WAIT が設定されている場合、プロセスはこのタイムアウトをブロックして待機します。 group_name (str、オプション、非推奨) – グループ名。この引数は無視されます。 pg_options (ProcessGroupOptions、オプション) – プロセスグループオプション。特定のプロセスグループの構築中に渡す必要のある追加オプションを指定します。現在のところ、nccl バックエンドの ProcessGroupNCCL.Options のみがサポートされており、is_high_priority_stream を指定して、nccl バックエンドがコンピュートカーネルを待機している場合に高優先度の CUDA ストリームを選択できるようにします。NCCL を設定するその他の使用可能なオプションについては、https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/api/types.html#ncclconfig-t を参照してください。 device_id (torch.device | int、オプション) – このプロセスが動作する単一の特定のデバイス。バックエンド固有の最適化を可能にします。現在、これは NCCL でのみ 2 つの効果があります: コミュニケーター は即座に形成されます(通常の遅延呼び出しではなく ncclCommInit* を呼び出します)。サブグループは不要なグループ作成オーバーヘッドを回避するために可能な場合 ncclCommSplit を使用します。NCCL 初期化エラーを早期に知りたい場合は、このフィールドも使用できます。int が提供される場合、API は、コンパイル時に使用されるアクセラレータタイプを想定します。 注釈 backend == Backend.MPI を有効にするには、MPI をサポートするシステムでソースから PyTorch をビルドする必要があります。 注釈 複数のバックエンドのサポートは実験的です。現在、バックエンドが指定されていない場合、gloo および nccl バックエンドの両方が作成されます。gloo バックエンドは CPU テンソルでの集約に使用され、nccl バックエンドは CUDA テンソルでの集約に使用されます。カスタムバックエンドは、「<device_type>:<backend_name>,<device_type>:<backend_name>」の形式の文字列を渡すことで指定できます。例えば、「cpu:gloo,cuda:custom_backend」。 torch.distributed.device_mesh.init_device_mesh(device_type, mesh_shape, *, mesh_dim_names=None, backend_override=None)[source]# device_type、mesh_shape、および mesh_dim_names パラメータに基づいて DeviceMesh を初期化します。これは n 次元配列レイアウトで DeviceMesh を作成します。n は mesh_shape の長さです。mesh_dim_names が提供されている場合、各次元は mesh_dim_names[i] としてラベル付けされます。 注釈 init_device_mesh は SPMD プログラミングモデルに従います。つまり、同じ PyTorch Python プログラムはクラスター内のすべてのプロセス/ランクで実行されます。mesh_shape(デバイスレイアウトを記述する nD 配列の次元)がすべてのランク全体で同一であることを確認してください。mesh_shape が一貫していない場合、ハングが発生する可能性があります。 注釈 プロセスグループが見つからない場合、init_device_mesh はシーンの背後で分散通信に必要な分散プロセスグループを初期化します。 パラメータ device_type (str) – メッシュのデバイスタイプ。現在サポートしています: 「cpu」、「cuda/cuda-like」、「xpu」。「cuda:0」などの GPU インデックスを含むデバイスタイプを渡すことは許可されていません。 mesh_shape (Tuple[int]) – マルチ次元配列の次元を定義する複合型。デバイスレイアウトを記述します。 mesh_dim_names (Tuple[str]、オプション) – マルチ次元配列の各次元に割り当てるメッシュ次元名のタプル。デバイスレイアウトを記述します。その長さは mesh_shape の長さと一致する必要があります。mesh_dim_names の各文字列は一意である必要があります。 backend_override (Dict[int | str, tuple[str, Options] | str | Options]、オプション) – 各メッシュ次元に対して作成される ProcessGroup の一部またはすべてのオーバーライド。各キーは次元のインデックスまたは名前(mesh_dim_names が提供されている場合)のいずれかです。各値は、バックエンドの名前とそのオプションを含むタプル、または、これら 2 つのコンポーネントのいずれか一方(この場合、その他のコンポーネントはデフォルト値に設定されます)です。 戻り値 デバイスレイアウトを表す DeviceMesh オブジェクト。 戻り値の型 DeviceMesh 例: >>> from torch.distributed.device_mesh import init_device_mesh >>> >>> mesh_1d = init_device_mesh("cuda", mesh_shape=(8,)) >>> mesh_2d = init_device_mesh("cuda", mesh_shape=(2, 8), mesh_dim_names=("dp", "tp")) torch.distributed.is_initialized()[source]# デフォルトプロセスグループが初期化されているかどうかを確認します。 戻り値の型 bool torch.distributed.is_mpi_available()[source]# MPI バックエンドが利用可能であるかどうかを確認します。 戻り値の型 bool torch.distributed.is_nccl_available()[source]# NCCL バックエンドが利用可能であるかどうかを確認します。 戻り値の型 bool torch.distributed.is_gloo_available()[source]# Gloo バックエンドが利用可能であるかどうかを確認します。 戻り値の型 bool torch.distributed.distributed_c10d.is_xccl_available()[source]# XCCL バックエンドが利用可能であるかどうかを確認します。 戻り値の型 bool torch.distributed.is_torchelastic_launched()[source]# このプロセスが torch.distributed.elastic(別名 torchelastic)で起動されたかどうかを確認します。TORCHELASTIC_RUN_ID 環境変数の存在が、現在のプロセスが torchelastic で起動されたかどうかを判断するためのプロキシとして使用されます。TORCHELASTIC_RUN_ID はランデヴー ID にマップされ、常にピア検出目的のジョブ ID を示す非ヌル値であるため、これは合理的なプロキシです。 戻り値の型 bool torch.distributed.get_default_backend_for_device(device)[source]# 与えられたデバイスのデフォルトバックエンドを返します。 パラメータ device (Union[str, torch.device]) – デフォルトバックエンドを取得するデバイス。 戻り値 与えられたデバイスのデフォルトバックエンドを小文字の文字列として。 戻り値の型 str 現在、3 つの初期化方法がサポートされています: TCP 初期化# TCP を使用した初期化には 2 つの方法があり、どちらもすべてのプロセスから到達可能なネットワークアドレスと目的の world_size が必要です。最初の方法には、ランク 0 プロセスに属するアドレスの指定が必要です。この初期化方法では、すべてのプロセスがランクを手動で指定する必要があります。最新の分散パッケージではマルチキャストアドレスがサポートされなくなったことに注意してください。group_name も非推奨です。 import torch.distributed as dist # 1 つのマシンのアドレスを使用 dist.init_process_group(backend, init_method='tcp://10.1.1.20:23456', rank=args.rank, world_size=4) 共有ファイルシステム初期化# 別の初期化方法では、グループ内のすべてのマシンから見える共有ファイルシステムと目的の world_size を使用します。URL は file:// で始まり、共有ファイルシステム上の(既存のディレクトリ内の)存在しないファイルへのパスを含む必要があります。ファイルシステム初期化は、ファイルが存在しない場合は自動的に作成されますが、ファイルは削除されません。したがって、同じファイルパス/名で次の init_process_group() 呼び出しの前にファイルがクリーンアップされていることを確認するのはユーザーの責任です。最新の分散パッケージでは自動ランク割り当てがサポートされなくなっており、group_name も非推奨です。 警告 このメソッドは、fcntl を使用したファイルシステムロック をサポートするファイルシステムを想定しています - ほとんどのローカルシステムと NFS がサポートしています。 警告 このメソッドは常にファイルを作成し、プログラムの終了時にファイルをクリーンアップして削除するためにベストを尽くします。つまり、ファイル init メソッドでの各初期化には、初期化を成功させるために、新しい空ファイルが必要です。前の初期化で使用されたのと同じファイル(クリーンアップされていない場合があります)を再度使用する場合、これは予期しない動作であり、デッドロックと障害につながることがあります。したがって、このメソッドはファイルのクリーンアップを最善を尽くそうとしますが、自動削除が失敗した場合、次回初期化を防ぐために、学習の終わりにファイルが削除されていることを確認するのはユーザーの責任です。これは特に、同じファイル名で init_process_group() を複数回呼び出す予定がある場合に重要です。つまり、ファイルが削除/クリーンアップされていない場合、その同じファイルで再び init_process_group() を呼び出すと、障害が予想されます。経験則として、init_process_group() を呼び出すたびに、ファイルが存在しないか空であることを確認してください。 import torch.distributed as dist # ランクは常に指定する必要があります dist.init_process_group(backend, init_method='file:///mnt/nfs/sharedfile', world_size=4, rank=args.rank) 環境変数初期化# このメソッドは環境変数から設定を読み取り、情報を取得する方法を完全にカスタマイズできます。設定する変数は以下の通りです: MASTER_PORT - 必須。ランク 0 マシンの空きポートである必要があります。 MASTER_ADDR - 必須(ランク 0 を除く)。ランク 0 ノードのアドレス。 WORLD_SIZE - 必須。ここで設定することも、init 関数の呼び出しで設定することもできます。 RANK - 必須。ここで設定することも、init 関数の呼び出しで設定することもできます。 ランク 0 のマシンはすべての接続をセットアップするために使用されます。これはデフォルト方法です。init_method は指定不要(または env:// にできます)。 初期化時間の改善# TORCH_GLOO_LAZY_INIT - すべての mesh を使用する代わりに要求に応じて接続を確立します。これは、all2all 操作以外の初期化時間を大幅に改善できます。 初期化後# torch.distributed.init_process_group() の実行後、以下の関数を使用できます。プロセスグループが既に初期化されているかどうかを確認するには、torch.distributed.is_initialized() を使用してください。 class torch.distributed.Backend(name)[source]# バックエンドの enum に似たクラス。利用可能なバックエンド: GLOO、NCCL、UCC、MPI、XCCL、およびその他の登録済みバックエンド。このクラスの値は小文字の文字列です(例えば、「gloo」)。属性としてアクセスできます(例えば、Backend.NCCL)。このクラスは直接呼び出されて文字列を解析できます(例えば、Backend(backend_str) は backend_str が有効かどうかを確認し、そうであれば解析された小文字の文字列を返します)。大文字の文字列も受け入れます(例えば、Backend("GLOO") は「gloo」を返します)。 注釈 Backend.UNDEFINED エントリが存在していますが、一部のフィールドの初期値としてのみ使用されます。ユーザーはこれを直接使用したり、その存在を仮定したりしてはいけません。 classmethod register_backend(name, func, extended_api=False, devices=None)[source]# 与えられた名前とインスタンス化関数で新しいバックエンドを登録します。このクラスメソッドは、サードパーティ ProcessGroup 拡張が新しいバックエンドを登録するために使用されます。 パラメータ name (str) – ProcessGroup 拡張のバックエンド名。init_process_group() のバックエンド名と一致する必要があります。 func (function) – バックエンドをインスタンス化する関数ハンドラー。関数はバックエンド拡張で実装され、store、rank、world_size、および timeout を含む 4 つの引数を取ります。 extended_api (bool、オプション) – バックエンドが拡張引数構造をサポートしているかどうか。デフォルト: False。True に設定すると、バックエンドは c10d::DistributedBackendOptions のインスタンスと、バックエンド実装で定義されたプロセスグループオプションオブジェクトを取得します。 device (str または list of str、オプション) – このバックエンドがサポートするデバイスタイプ(例えば、「cpu」、「cuda」など)。None の場合、「cpu」と「cuda」の両方を想定しています。 注釈 サードパーティバックエンドのこのサポートは実験的であり、変更される可能性があります。 torch.distributed.get_backend(group=None)[source]# 与えられたプロセスグループのバックエンドを返します。 パラメータ group (ProcessGroup、オプション) – 作業するプロセスグループ。デフォルトは一般的なメインプロセスグループです。別の特定のグループが指定されている場合、呼び出しプロセスは group の一部である必要があります。 戻り値 与えられたプロセスグループのバックエンドを小文字の文字列として。 戻り値の型 Backend torch.distributed.get_rank(group=None)[source]# 提供されたグループ内の現在のプロセスのランク、またはそれ以外の場合のデフォルトを返します。ランクは、分散プロセスグループ内の各プロセスに割り当てられた一意の識別子です。それらは常に 0 から world_size への連続した整数です。 パラメータ group (ProcessGroup、オプション) – 作業するプロセスグループ。None の場合、デフォルトプロセスグループが使用されます。 戻り値 プロセスグループのランク。グループに含まれていない場合は -1。 戻り値の型 int torch.distributed.get_world_size(group=None)[source]# 現在のプロセスグループ内のプロセス数を返します。 パラメータ group (ProcessGroup、オプション) – 作業するプロセスグループ。None の場合、デフォルトプロセスグループが使用されます。 戻り値 プロセスグループの world size。グループに含まれていない場合は -1。 戻り値の型 int シャットダウン# destroy_process_group() を呼び出してリソースをクリーンアップすることが重要です。従うべき最も簡単なパターンは、通信がもはや不要な学習スクリプトのポイント(通常 main() の終わり)で、group 引数のデフォルト値 None で destroy_process_group() を呼び出してすべてのプロセスグループとバックエンドを破棄することです。呼び出しはトレーナープロセスごとに 1 回実行するべきで、外側のプロセスランチャーレベルではありません。 pg 内のすべてのランクが タイムアウト期間内に destroy_process_group() を呼び出さない場合、特に N-D 並列化のための複数のプロセスグループがあるアプリケーション内では、終了時のハングが可能です。これは、ProcessGroupNCCL のデストラクタが ncclCommAbort を呼び出し、集約的に呼び出される必要があり、Python の GC によって呼び出される ProcessGroupNCCL のデストラクタの順序が決定的でないためです。destroy_process_group() を呼び出すことで、ランク全体で ncclCommAbort が一貫した順序で呼び出され、ProcessGroupNCCL のデストラクタ中に ncclCommAbort を呼び出すことを回避します。 再初期化# destroy_process_group は個々のプロセスグループを破棄するためにも使用できます。1 つのユースケースは、フォールトトレラント学習の場合です。プロセスグループを破棄してから、実行時中に新しいものを初期化できます。この場合、torch.distributed プリミティブ以外の何らかの手段を使用してトレーナープロセスを同期化することが重要です。destroy を呼び出した後と、その後の初期化の前。この動作は、この同期を達成する困難さのため、現在サポートされていない/テストされていません。既知の問題と見なされています。このユースケースがあなたをブロックしている場合は、github issue または RFC を提出してください。 グループ# デフォルトでは、集約はデフォルトグループ(world とも呼ばれる)で動作し、すべてのプロセスが分散関数呼び出しに入ることが必要です。ただし、一部のワークロードは、より細粒度の通信から恩恵を受ける可能性があります。これが分散グループが登場する場所です。 new_group() 関数を使用して、すべてのプロセスの任意のサブセットで新しいグループを作成できます。これは、すべての集約(分散関数を特定の既知のプログラミングパターンで情報を交換する)に group 引数として与えることができる不透明なグループハンドルを返します。 torch.distributed.new_group(ranks=None, timeout=None, backend=None, pg_options=None, use_local_synchronization=False, group_desc=None, device_id=None)[source]# 新しい分散グループを作成します。この関数では、メイングループ内のすべてのプロセス(つまり、分散ジョブの一部であるすべてのプロセス)がこの関数に入る必要があります。グループのメンバーではないプロセスであっても。さらに、グループはすべてのプロセスで同じ順序で作成される必要があります。 警告 安全な同時使用: NCCL バックエンドで複数のプロセスグループを使用する場合、ユーザーはランク全体で集約の実行順序をグローバルに一貫性があることを確保する必要があります。プロセス内の複数のスレッドが集約を発行する場合、実行順序の一貫性を確保するには明示的な同期が必要です。torch.distributed 通信 API の非同期バリアントを使用する場合、作業オブジェクトが返され、通信カーネルは別の CUDA ストリームでエンキューされ、通信と計算のオーバーラップを可能にします。1 つのプロセスグループで 1 つ以上の非同期 ops が発行されたら、他のプロセスグループを使用する前に他の cuda ストリームと work.wait() を呼び出して同期する必要があります。詳細については、複数の NCCL コミュニケーターの同時使用 https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/usage/communicators.html#using-multiple-nccl-communicators-concurrently を参照してください。 パラメータ ranks (list[int]) – グループメンバーのランク一覧。None の場合、すべてのランクに設定されます。デフォルトは None です。 timeout (timedelta、オプション) – init_process_group の詳細とデフォルト値を参照してください。 backend (str または Backend、オプション) – 使用するバックエンド。ビルド時の設定に応じて、有効な値は gloo および nccl です。デフォルトではグローバルグループと同じバックエンドを使用します。このフィールドは小文字の文字列として指定する必要があります(例えば、「gloo」)。Backend 属性経由でもアクセスできます(例えば、Backend.GLOO)。None が渡された場合、デフォルトプロセスグループに対応するバックエンドが使用されます。デフォルトは None です。 pg_options (ProcessGroupOptions、オプション) – プロセスグループオプション。特定のプロセスグループの構築中に渡す必要のある追加オプションを指定します。例えば、nccl バックエンドの場合、is_high_priority_stream を指定して、プロセスグループがコンピュートカーネルを待機している場合に高優先度の cuda ストリームを選択できるようにします。NCCL を設定するその他の使用可能なオプションについては、https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/api/types.html#ncclconfig-t を参照してください。use_local_synchronization (bool、オプション): プロセスグループ作成の終了時に、グループローカルバリアを実行します。これは、非メンバーランクが API に呼び出す必要もなく、バリアに参加する必要もないという点で異なります。 group_desc (str、オプション) – プロセスグループを記述する文字列。 device_id (torch.device、オプション) – このプロセスを「バインド」する単一の特定のデバイス。new_group 呼び出しは、このフィールドが与えられている場合、デバイスの通信バックエンドを直ちに初期化しようとします。 戻り値 集約呼び出しまたは GroupMember.NON_GROUP_MEMBER に与えることができる分散グループのハンドル。ランクが ranks の一部でない場合。 N.B. use_local_synchronization は MPI で機能しません。 N.B. use_local_synchronization=True はより大きなクラスターや小さなプロセスグループで大幅に高速化できますが、非メンバーランクがグループバリア()に参加しないため、クラスタの動作が変わるため、注意が必要です。 N.B. use_local_synchronization=True は、各ランクが複数の重複するプロセスグループを作成する場合、デッドロックにつながる可能性があります。これを回避するには、すべてのランクが同じグローバル作成順序に従うことを確認してください。 torch.distributed.get_group_rank(group, global_rank)[source]# グローバルランクをグループランクに変換します。global_rank は group に含まれている必要があります。そうでない場合、これは RuntimeError を引き起こします。 パラメータ group (ProcessGroup) – 相対ランクを検出する ProcessGroup。 global_rank (int) – クエリするグローバルランク。 戻り値 group に相対的な global_rank のグループランク。 戻り値の型 int N.B. このメソッドをデフォルトプロセスグループで呼び出すと、恒等式が返されます。 torch.distributed.get_global_rank(group, group_rank)[source]# グループランクをグローバルランクに変換します。group_rank は group に含まれている必要があります。そうでない場合、これは RuntimeError を引き起こします。 パラメータ group (ProcessGroup) – グローバルランクを検出する ProcessGroup。 group_rank (int) – クエリするグループランク。 戻り値 group に相対的な group_rank のグローバルランク。 戻り値の型 int N.B. このメソッドをデフォルトプロセスグループで呼び出すと、恒等式が返されます。 torch.distributed.get_process_group_ranks(group)[source]# group に関連するすべてのランクを取得します。 パラメータ group (Optional[ProcessGroup]) – すべてのランクを取得する ProcessGroup。None の場合、デフォルトプロセスグループが使用されます。 戻り値 グループランク順に並べたグローバルランクのリスト。 戻り値の型 list[int] DeviceMesh# DeviceMesh はプロセスグループ(または NCCL コミュニケーター)を管理する高レベルの抽象化です。これにより、ユーザーはノード間およびノード内プロセスグループを簡単に作成でき、異なるサブプロセスグループのランクをどのように設定するかについて心配する必要がなく、分散プロセスグループを簡単に管理できます。 init_device_mesh() 関数は新しい DeviceMesh を作成するために使用でき、メッシュシェイプはデバイストポロジーを記述しています。 class torch.distributed.device_mesh.DeviceMesh(device_type, mesh, *, mesh_dim_names=None, backend_override=None, _init_backend=True)[source]# DeviceMesh はデバイスのメッシュを表します。デバイスのレイアウトは n 次元配列として表現でき、n 次元配列の各値はデフォルトプロセスグループランクのグローバル ID です。DeviceMesh はクラスター全体で N 次元デバイス接続をセットアップし、N 次元並列化のための ProcessGroup を管理するために使用できます。通信は DeviceMesh の各次元で個別に発生する可能性があります。DeviceMesh はユーザーが既に選択しているデバイスを尊重します(つまり、ユーザーが DeviceMesh 初期化の前に torch.cuda.set_device を呼び出す場合)。ユーザーが事前にデバイスを設定していない場合は、現在のプロセスのデバイスを選択/設定します。手動デバイス選択は DeviceMesh 初期化の前に実施される必要があることに注意してください。DeviceMesh は、DTensor API と一緒に使用する場合、コンテキストマネージャーとしても使用できます。 注釈 DeviceMesh は SPMD プログラミングモデルに従います。つまり、同じ PyTorch Python プログラムはクラスター内のすべてのプロセス/ランクで実行されます。したがって、ユーザーはメッシュ配列(デバイスレイアウトを記述する)がすべてのランク全体で同一であることを確認する必要があります。メッシュが一貫していない場合、サイレントハングが発生します。 パラメータ device_type (str) – メッシュのデバイスタイプ。現在サポートしています: 「cpu」、「cuda/cuda-like」。 mesh (ndarray) – マルチ次元配列またはデバイスレイアウトを記述する整数テンソル。ID はデフォルトプロセスグループのグローバル ID です。 戻り値 デバイスレイアウトを表す DeviceMesh オブジェクト。 戻り値の型 DeviceMesh 次のプログラムはクラスター内の各プロセス/ランクで SPMD 方式で実行されます。この例では、8 つの GPU を持つ 2 つのホストがあります。メッシュの最初の次元での削減により、(0, 4)、.. および(3, 7)列全体で削減されます。メッシュの 2 番目の次元での削減により、行(0, 1, 2, 3)および(4, 5, 6, 7)全体で削減されます。 例: >>> from torch.distributed.device_mesh import DeviceMesh >>> >>> # デバイスメッシュを(2, 4)として初期化し、 >>> # クロスホスト(dim 0)およびホスト内(dim 1)のトポロジーを表現します。 >>> mesh = DeviceMesh(device_type="cuda", mesh=[[0, 1, 2, 3],[4, 5, 6, 7]]) static from_group(group, device_type, mesh=None, *, mesh_dim_names=None)[source]# 既存の ProcessGroup または既存の ProcessGroup のリストから device_type で DeviceMesh を構築します。構築された device mesh の次元数は、渡されたグループの数に等しくなります。たとえば、単一のプロセスグループが渡された場合、結果の DeviceMesh は 1D メッシュです。2 つのプロセスグループのリストが渡された場合、結果の DeviceMesh は 2D メッシュです。複数のグループが渡される場合、mesh および mesh_dim_names 引数が必須です。渡されたプロセスグループの順序により、メッシュのトポロジーが決まります。たとえば、最初のプロセスグループは DeviceMesh の 0 番目の次元になります。渡されたメッシュテンソルは、渡されたプロセスグループの数と同じ数の次元を持つ必要があり、メッシュテンソル内の次元の順序は、プロセスグループに渡された順序と一致する必要があります。 パラメータ group (ProcessGroup または list[ProcessGroup]) – 既存の ProcessGroup または既存の ProcessGroup のリスト。 device_type (str) – メッシュのデバイスタイプ。現在サポートしています: 「cpu」、「cuda/cuda-like」。「cuda:0」などの GPU インデックスを含むデバイスタイプを