# 🤗`accelerate`のContext Parallel

このガイドでは、🤗`accelerate`でコンテキスト並列性を使用する基本的な内容について説明します。より詳細を知りたい読者のために、後半のセクションでは技術的な側面にも触れます。

関連性の非常に高い[シーケンス並列性ガイド](./sequence_parallelism)も参照してください。

## なぜコンテキスト並列性が必要なのか

大規模言語モデル、そして最近の推論モデルの登場により、シーケンス長は急速に伸びています。これにアテンションの二次的なメモリ複雑度が加わったことで、長いシーケンスを持つモデルを訓練するためのより効率的な手法の必要性が高まっています。シーケンス長が128kの場合、バニラなアテンション実装を前提とすると、アテンション行列のメモリ要件は`128k * 128k * 2 bytes * num_heads = ~32 GB * num_heads`となり、`bf16`精度での話です。もちろん、これらのアテンション重みを物化しない`flash attention`や`SDPA`を使用すれば、メモリ要件は大幅に減少しますが、それでもメモリ要件の増加は依然として無視できない規模です。

Context parallelismは、attention計算の入力をシーケンス次元に沿ってシャードし、複数のGPUでattentionを並列に計算することを可能にします。これにより、長いシーケンスを持つモデルの学習が可能になり、潜在的に100万を超えるシーケンス長までスケーリングできます。

## コンテキスト並列性の使用方法

```diff
from accelerate.utils import ParallelismConfig, TorchContextParallelConfig

+ cp_config = TorchContextParallelConfig(
+       cp_comm_strategy="alltoall", # no need to use cp_config at all, if you want to use the default "allgather"
+ )

+ parallelism_config = ParallelismConfig(
+     cp_size=8,
+     cp_handler=cp_config,  # or just cp_size=8, if you want to use the default "allgather"
+ )

accelerator = Accelerator(
    ...,
    parallelism_config=parallelism_config,
)
```

🤗`accelerate`の他の機能と同様に、`accelerate launch`に該当するフラグを渡すことで、コンテキスト並列性を有効にできます。この場合も、以下の通りです:

```bash
accelerate launch --parallelism-config-cp-size 8 --parallelism-config-cp-comm-strategy [allgather|alltoall] ...
```

> [!Tip]
> `accelerate config` コマンドで `cp_size` と `cp_comm_strategy` を設定することもできます。これらは `accelerate` の設定ファイルに保存されるため、スクリプトを起動するたびに毎回渡す必要がなくなります。

> [!Tip]
> コンテキスト並列は、データ並列、テンソル並列、FSDP2 などの他の並列戦略と互換性があります。並列サイズを希望する値に設定するだけで、それらを組み合わせることができます。例えば、`--parallelism-config-dp-size 8 --parallelism-config-tp-size 2 --parallelism-config-cp-size 8` のようにします。また、`ParallelismConfig` クラスを使用して、プログラム内でそれらを設定することもできます。

> [!Warning]
> コンテキスト並列性は`FSDP2`と密接に結合しており、[FSDP2 の紹介](fsdp1_vs_fsdp2)で詳細を学ぶことができます。つまり、コンテキスト並列性は、プログラムに`FullyShardedDataParallelPlugin`または`--use-fsdp`をバージョン 2 に設定して使用した場合にのみ機能します。`FSDP2`を使用しない場合、エラーが発生します。

> [!Warning]
> コンテキスト並列性は[SDPA](https://docs.pytorch.org/docs/stable/generated/torch.nn.functional.scaled_dot_product_attention.html)でのみ動作し、マスクなしまたは因果マスクのみの場合に限り利用できます。これを適切に検出することはできないため、`SDPA`をマスクなしまたは因果マスクなしで使用するよう、ご自身で確認してください。その他のアテンション実装を使用すると、エラーが発生します。

上記の方法でコンテキスト並列性を有効にした後、トレーニングループに適用できます。[`torch.distributed.tensor.experimental.context_parallel`](https://docs.pytorch.org/docs/stable/distributed.tensor.html#torch.distributed.tensor.experimental.context_parallel) の薄いラッパーを提供しており、トレーニングループで使用できます。これにより、コンテキスト並列性を使用する上での一部の複雑さを抽象化します（詳細は後述します）。トレーニングループで行う変更を最小限に抑えるため、コンテキスト並列性が有効でない場合は `noop` として動作し、有効な場合はコンテキスト並列性を適用するコンテキストマネージャーを提供しています。これにより、並列性設定に基づいてコードを変更することなく、トレーニングループで使用できます。以下のように使用できます:

```python
for batch in dataloader:
    with accelerator.maybe_context_parallel(
        buffers=[batch["input_ids"], batch["attention_mask"]],
        buffer_seq_dims=[1, 1],
        no_restore_buffers={batch["input_ids"], batch["labels"]},
    ):
        outputs = model(**batch)
        ...
```

> [!Warning]
> 上記の例に示すように、このコンテキストマネージャーは各トレーニングステップごとに再作成する必要があります。これは非常に重要です。

これにより、コンテキストサイズを1M以上のシーケンス長に拡張できる可能性があります。以下では、最大256kのコンテキストサイズにおけるコンテキスト並列性の速度とメモリ使用量を示します。コンテキストサイズとGPUの数を2倍にすると、メモリ使用量が一定に保たれることがわかります。これにより、コンテキスト長の無制限なスケーリングが実現できる可能性があります。

  
  
  図1: 最大256kのコンテキストサイズにおけるコンテキスト並列性のメモリ使用量と速度。

> [!Tip]
> これらの例は、[examplesフォルダ](https://github.com/huggingface/accelerate/blob/main/examples/torch_native_parallelism/nd_parallel.py)にあるスクリプトで作成されています。8つのH100 GPU（シーケンス長128k）で例を実行するには、以下のコマンドを使用できます。
> ```bash
> accelerate launch --use-fsdp --fsdp-activation-checkpointing=TRUE examples/torch_native_parallelism/nd_parallel.py --cp-size=8 --sequence-length=128000
> ```

## Accelerateのインターフェース

コンテキストマネージャーは、コンテキスト並列性を設定するために使用されるいくつかの引数を受け取ります。

- `buffers`: シーケンス次元にシャードされるテンソルのリストです。これらのテンソルは通常、入力 ID、ラベル、アテンションマスクです。
- `buffer_seq_dims`: `buffers` リストの順序に従って、各バッファのシーケンス次元を指定する整数のリストです。`buffers=[input_ids, shift_labels]` を渡す場合、両方の形状が `[batch_size, sequence_length]` であるため、テンソルのシーケンス次元が2番目の次元であることから、`buffer_seq_dims=[1, 1]` を渡します。これは、モデルの出力を正しく計算するために必要です。
- `no_restore_buffers`: コンテキスト並列性の実装は、バッファをインプレースで変更し、`torch.distributed.tensor.Dtensor`に変換します。コンテキストマネージャーを抜けた後、バッファを元の状態（通常はオールギャザー）に復元するには、通信カーネルの起動が必要です。これには時間がかかるため、コンテキストマネージャーを抜けた後にバッファを使用する必要があると確信している場合を除き、`buffers`引数と同じテンソルを渡すことをお勧めします。これにより、不要な通信を回避できます。

> [!Warning]
> コンテキスト並列性は、`labels`が`input_ids`のコピーである場合に非互換です。🤗 transformers のモデルは、因果言語モデリングを有効にするために、このシフトを自分で行うことができます。このケースを想像してください。labels = [l1, l2, l3, l4, ... li] の場合、コンテキスト並列性を適用すると、各ランクは labels の一部を持つことになります。例えば、labels_rank_0 = [l1, l2]、labels_rank_1 = [l3, l4]、... のようになります。transformers のモデリングコードが labels をシフトすると、labels_rank_0 = [l2, PAD]、labels_rank_1 = [l3, PAD]、... のようになります。ここで`PAD`はパディングトークンです。これにより、labels がもはや入力とアラインされていないため、誤った損失計算が行われることになります。そのため、モデルに渡す前に、labels を手動でシフトする必要があります。

## 設定可能なオプション
Accelerateは、コンテキスト並列性を設定するためのオプションを1つしか提供していません（`cp_size`を除く）。

- `cp_comm_strategy`: シャードに使用する回転メソッドです。ほとんどのケースで`"alltoall"`よりも高性能が期待できるため、`"allgather"`のままにすることを強く推奨します。

Context parallel size はその名が示す通り、入力がシャード化されるランクの数を指します。Context parallel shard rotation は、入力のシャードがランク間でどのようにローテーションされるかを定義します。2つのオプションの詳細については、次のセクションで説明します。

[ND parallel example](https://github.com/huggingface/accelerate/blob/main/examples/torch_native_parallelism/nd_parallel.py)ファイルにエンドツーエンドの例を確認できます。この例では、単一の8xH100ノード上で、最大128kのコンテキスト長を持つ8Bモデルをトレーニングできます。マルチノードトレーニングを使用することで、この設定を複数のGPU上で1M以上のシーケンス長にスケールアップできます。また、ニーズに合わせて他の並列化戦略とシームレスに組み合わせることも可能です。

## 技術的な詳細

> [!Tip]
> このセクションは比較的技術的な内容です。コンテキスト並列処理の内部構造を学ぶ必要がない場合は、読み飛ばして構築を開始できます 🚀

次のセクションでは`shard`という用語を頻繁に使用するため、まず定義しておきます。テンソルを`Dth`次元に沿って`N`個のランクにわたって`sharded`と呼ぶ場合、これはそのテンソルが`N`個の部分に分割されていることを意味し、各部分の形状は`[..., D//N, ...]`となります。

## では、どのように動作するのでしょうか？

Context parallelism は、シーケンス次元に沿って `Q, K and V` 行列をシャーディングすることで機能します。各ランクには `Q` の割り当てられたシャードがあり、これを `Q_i` と呼びます。この行列は、計算全体を通じてこのランクにのみ保持されます。同様に、各ランクには `K` と `V` の独自のシャードがあり、これらを `K_i` と `V_i` と呼びます。次に、各ランクは、独自の `Q_i`、`K_i`、`V_i` のシャードを用いてアテンションを計算し、これを `attn_i` と呼びます。この計算中、他のすべてのランクから `Ks` と `Vs` を集めるための通信カーネルが起動されます。使用される通信プリミティブは、`context_parallel_shard_rotation` オプションによって決まります。これにより、各ランクは、まず `Q_i`、`K_i`、`V_i` を用いて、次に他のすべてのランクからの `K_j` と `V_j` を用いて、ローカルアテンションを計算できます。各ランクがシーケンス次元に沿ってシャーディングされた `Q, K and V` 行列を保持するため、結果の行列は小さくなり、単一の GPU に収まります。

これを以下の疑似コードで形式化できます。
```python
comm_kernel = {"allgather": allgather, "alltoall": alltoall}[context_parallel_shard_rotation]
Qi, Ki, Vi = shard(Q, K, V, seq_dim)
attn[i] = attn(Qi, Ki, Vi)
for j in range(context_parallel_size):
    Kj, Vj = comm_kernel()
    attn[j] = attn(Qi, Kj, Vj) # [batch, num_heads, seq_len // context_parallel_size, head_dim]

final_attn = combine(attn)
```

## all-to-all と all-gather

### all-gather
では、all-to-allとall-gatherの違いは何でしょうか。all-gatherでは、通信は非常にシンプルです。ローカルアテンション`attn_i`を計算した（実際には、通常は計算に時間がかかるため、計算を開始する前に）後、他のすべてのランクから他の`Ks`と`Vs`を集めるためにall-gatherを発行します。この通信が完了すると、各ランクは他のすべてのランクからの`Ks`と`Vs`をすべて保有し、それらを使ってアテンションを逐次的に計算できます。理想的なシナリオでは、`attn_i`の計算が完了したまさにその瞬間にall-gatherが完了します。しかし、実際にはそのようなことは起こらず、理想的なリアルオーバーラップは、`attn_i`全体が通信の一部とオーバーラップし、その後`K_j`と`V_j`での計算を開始するためにall-gatherの完了を待つことで達成されます。

### all-to-all
All-to-all, or sometimes called `ring-rotation` utilizes a ring-like communication pattern. After concluding `attn_i` computation, an all-to-all is launched to send `K_i` and `V_i` to the neighbouring ranks. We then repeat this `context_parallel_size-1` times, so that each rank sees all the shards of `K` and `V` from all other ranks once. In ideal scenario, we prefetch shards `K_i+1` and `V_i+1` from the neighbouring rank and this communication is exactly overlapped with computation of our current `attn_i`. Again, realistically, this perfect overlap doesn't ever happen. Given the nature of this approach, if we don't achieve perfect overlap, the penalty is way larger than with all-gather.

## 適切な回転手法の選び方
In theory, all-to-all should be the better choice. Though in practice, it rarely is. Therefore, we default to all-gather, as it's more likely to achieve better performance. Extensive [benchmarks](https://discuss.pytorch.org/t/distributed-w-torchtitan-breaking-barriers-training-long-context-llms-with-1m-sequence-length-in-pytorch-using-context-parallel/215082) from the `torchtitan` team also show that all-to-all rarely outperforms all-gather. Though, we still provide both options, as you might find one to be better for your use case.

次の画像のプロファイラー出力から、この問題が直接確認できます:

  
  
  Figure 1: 赤色で示されているのは、all-to-allカーネルの完了を待っているアイドル時間です。最初の青色のバーにハイライトされている部分を見ると、完了までに約250usかかることがわかります。これは、コンテキスト並列サイズNに対して、各アテンション呼び出しでN-1回繰り返されます。

## なぜFSDP2のみなのか

コンテキスト並列性は`FSDP2`でのみサポートしています。これは、`context_parallel_size`と`dp_shard_size`のジョイントメッシュを作成し、その全機能を最大限に活用するためです。動作原理は以下の通りです。サイズ`cp_size*dp_shard_size`のジョイントメッシュ全体にモデルをシャーディングすることで、メモリ削減を最大化します。これはある種の「フリーランチ」であり、`FSDP`の通信がアテンションの計算と完全にオーバーラップするためです。以下の画像に示す通りです。

  
  
  Figure 2: 青い長方形（Stream 23）では、`FSDP` シャードのプリフェッチがアテンションの計算（Stream 7）と完全にオーバーラップしていることがわかります。一方、赤い長方形（Stream 24）では、all-gather カーネルがアイドル時間のバブルを生み、その間、計算ストリーム（7）がアイドル状態になっていることがわかります。

In the figure above, you can also note the difference between all-to-all and all-gather. While in all-to-all (Figure 1), we launch a communication kernel N-1 times for each attention call, in all-gather (Figure 2), we launch a communication kernel only once. This results in a bigger bubble, but it only happens once per attention call, while in all-to-all, it happens N-1 times.

## ジョイントメッシュにおけるデータのディスパッチ

`cp` サブグループ全体に同じバッチのデータをディスパッチするようにすることで、結果が正しくなることを保証しています（つまり、`cp` サブグループ内の各ランクが同じバッチのデータを受け取ります）。ただし、`dp_shard` グループの各ランクには異なるバッチをディスパッチします。次のようにイメージしてください。
```
# 8 GPUS, --dp_shard_size 4, --cp_size 2
# mesh = [[0, 1], [2, 3], [4, 5], [6, 7]]
# model is sharded across the whole mesh (each GPU holds 1/8 of the model)
# GPUs 0,1 = batch 0
# GPUs 2,3 = batch 1
... and so on.
```

