# التوازي السياقي في 🤗`accelerate`

ستغطي هذه الدليل أساسيات استخدام توازٍ السياق في 🤗`accelerate`، وللقراء الأكثر فضولاً، سنغطي أيضاً بعض التفاصيل التقنية في الأقسام اللاحقة.

انظر أيضًا إلى [دليل التوازي التسلسلي](./sequence_parallelism) ذي الصلة الوثيقة.

## لماذا التوازي السياقي؟

مع ظهور نماذج اللغة الكبيرة، ونماذج الاستدلال مؤخراً، شهدت طول التسلسل نمواً سريعاً. وقد أدى هذا، مقترناً بالتعقيد الذاكري التربيعي للانتباه، إلى الحاجة إلى طرق أكثر كفاءة لتدريب النماذج ذات التسلسلات الطويلة. فعند طول تسلسل يبلغ 128k، تكون المتطلبات الذاكرية لمصفوفة الانتباه `128k * 128k * 2 bytes * num_heads = ~32 GB * num_heads` لدقة `bf16`، بافتراض استخدام تطبيق الانتباه القياسي. ومنحاً، فإن استخدام `flash attention` أو `SDPA`، والتي لا تُجسّد أوزان الانتباه هذه، يُقلّص ذلك بشكل حاد، لكن النمو في المتطلبات الذاكرية لا يزال يُعدّ كبيراً.

يتيح لنا توازي السياق تقسيم مدخلات حساب الانتباه على طول بُعد التسلسل وحساب الانتباه بالتوازي على وحدات معالجة رسومية متعددة. وبفضل ذلك، يمكننا تدريب نماذج ذات تسلسلات طويلة، مع إمكانية التوسع لتصل إلى طول تسلسل يتجاوز مليون رمز.

## كيف تستخدم توازي السياق؟

```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]
> يمكنك أيضًا تعيين `cp_size` و`cp_comm_strategy` في أمر `accelerate config`، مما سيؤدي إلى حفظهما في ملف إعدادات `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]
> يجب إعادة إنشاء مدير السياق هذا مع كل خطوة تدريب، كما هو موضح في المثال أعلاه. من الضروري القيام بذلك.

يمكن أن يوسّع هذا حجم السياق إلى طول تسلسل يتجاوز 1 مليون رمز. أدناه، نُظهر سرعة استخدام الذاكرة لحالة التوازي السياقي لحجم سياق يصل إلى 256 ألف رمز. نلاحظ أنه عند مضاعفة حجم السياق وعدد وحدات معالجة الرسومات، يمكننا تحقيق استخدام متسق للذاكرة، مما قد يتيح توسيع طول السياق بشكل غير محدود.

  
  
  الشكل 1: استهلاك الذاكرة وسرعة توازي السياق لحجم سياق يصل إلى 256k.

> [!Tip]
> تم إنشاء هذه الأمثلة باستخدام سكربت يمكنك العثور عليه [في مجلد الأمثلة](https://github.com/huggingface/accelerate/blob/main/examples/torch_native_parallelism/nd_parallel.py). لتشغيل المثال على 8 وحدات معالجة رسومية H100 (طول تسلسل 128k)، يمكنك استخدام الأمر التالي:
> ```bash
> accelerate launch --use-fsdp --fsdp-activation-checkpointing=TRUE examples/torch_native_parallelism/nd_parallel.py --cp-size=8 --sequence-length=128000
> ```

## واجهة Accelerate

يقبل مدير السياق (context manager) عدة حُجج تُستخدم لضبط توازٍ السياق (context parallelism).

- `buffers`: هذه قائمة من الموترات (tensors) التي سيتم تقسيمها عبر بُعد التسلسل. عادةً ما تكون هذه الموترات معرّفات الإدخال (input ids) والوسوم (labels) وقناع الانتباه (attention mask).
- `buffer_seq_dims`: هذه قائمة من الأعداد الصحيحة، تحدد بُعد التسلسل للـ buffers، بترتيب قائمة `buffers`. إذا مررت `buffers=[input_ids, shift_labels]` وكان كلاهما على شكل `[batch_size, sequence_length]`، فستمرر `buffer_seq_dims=[1, 1]`، لأن بُعد التسلسل هو البُعد الثاني من المصفوفات. هذا مطلوب للحساب الصحيح لمخرجات النموذج.
- `no_restore_buffers`: يعدّل تنفيذ توازي السياق المخازن المؤقتة في مكانها، محوّلًا إياها إلى `torch.distributed.tensor.Dtensor`. بعد خروج مدير السياق، سيُطلب إطلاق نواة اتصال لاستعادة المخازن المؤقتة إلى حالتها الأصلية (عادةً all-gather). يستغرق هذا بعض الوقت، لذا يُوصى بتمرير نفس المصفوفات كما في معامل `buffers` لتجنب الاتصالات غير الضرورية، ما لم تكن متأكدًا من حاجتك إلى استخدام المخازن المؤقتة بعد خروج مدير السياق.

> [!Warning]
> لا يتوافق توازٍ السياق مع `labels` التي تكون نسخة من `input_ids`، وهي التي يمكن لنماذج 🤗 transformers إزاحتها بنفسها لتفعيل نمذجة اللغة السببية. تخيّل هذا السيناريو: labels = [l1, l2, l3, l4, ... li] إذا طبقنا توازٍ السياق، فإن كل rank سيحصل على جزء من 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 خيارًا واحدًا فقط لتكوين توازٍ السياق (باستثناء `cp_size`)

- `cp_comm_strategy`: طريقة التدوير المستخدمة للتُحَفّظات. ننصح بشدة بإبقائها على `"allgather"`، فمن المرجح جداً أن تتفوق على `"alltoall"` في معظم الحالات.

حجم التوازي السياقي واضح من اسمه إلى حد كبير، فهو عدد الرتب التي تُقسَّم المدخلات عبرها. أما تدوير تقسيم التوازي السياقي فيحدد كيفية تدوير أجزاء المدخلات عبر الرتب. سنتناول الخيارين بالتفصيل في القسم التالي.

يمكنك الاطلاع على مثال شامل من البداية إلى النهاية في ملف [ND parallel example](https://github.com/huggingface/accelerate/blob/main/examples/torch_native_parallelism/nd_parallel.py)، حيث يمكنك تدريب نموذج بحجم 8B مع طول سياق يصل إلى 128k على عقدة واحدة من نوع 8xH100. وباستخدام التدريب متعدد العقد، يمكنك توسيع نطاق هذا النموذج ليصل إلى طول تسلسل يتجاوز 1M على وحدات معالجة رسومية متعددة. كما يمكنك دمجه بسلاسة مع استراتيجيات التوازي الأخرى لتلبية احتياجاتك.

## تفاصيل تقنية

> [!Tip]
> هذا القسم تقني إلى حد كبير، لذا إذا لم تكن بحاجة إلى فهم التفاصيل الداخلية لتوازي السياق، يمكنك تخطيه والبدء في البناء 🚀

سنستخدم كلمة `shard` على نطاق واسع في الأقسام التالية، لذا دعونا نعرّفها أولاً. إذا قلنا إن المصفوفة `sharded` عبر البُعد `Dth`، عبر `N` رتب، فإننا نعني أن هذه المصفوفة مقسمة إلى `N` أجزاء، حيث يكون شكل كل جزء من المصفوفة `[..., D//N, ...]`.

## كيف يعمل؟

يعمل توازي السياق على تقسيم مصفوفات `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` مقسمة عبر بُعد التسلسل، فإن المصفوفات الناتجة تكون أصغر حجماً ويمكنها أن تتسع على وحدة معالجة رسومية واحدة.

يمكننا صياغة ذلك بشكل رسمي في الشيفرة الزائفة التالية:
```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-to-all و all-gather؟ في حالة all-gather، تكون عملية الاتصال بسيطة للغاية. بعد (أو بالأحرى قبل، إذ يستغرق الأمر عادةً وقتاً أطول) حساب الانتباه المحلي `attn_i`، نطلق عملية all-gather لجمع جميع `Ks` و `Vs` من بقية الرتب. وبمجرد اكتمال هذا الاتصال، تمتلك كل رتبة جميع `Ks` و `Vs` من بقية الرتب، ويمكنها حساب الانتباه باستخدامها بشكل تسلسلي. في السيناريو المثالي، تنتهي عملية all-gather في اللحظة ذاتها التي يكتمل فيها حساب `attn_i`. ومع ذلك، لا يحدث هذا عملياً أبداً، لذا فإن التداخل الفعلي المثالي يتحقق عندما يتم تداخل `attn_i` بالكامل مع جزء من عملية الاتصال، ثم ننتظر انتهاء all-gather لبدء الحساب باستخدام `K_j` و `V_j`.

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

يمكنك رؤية هذه المشكلة مباشرةً في مخرجات أداة التحليل المعروضة في الصورة أدناه:

  
  
  الشكل 1: باللون الأحمر يمكنك رؤية وقت الخمول، بينما ننتظر انتهاء نواة all-to-all. في العمود الأزرق الأول المُبرز، يمكنك ملاحظة أنه يستغرق حوالي 250 ميكروثانية للانتهاء، وهو ما يتكرر N-1 مرة لكل استدعاء للدالة attention، حيث N هو حجم التوازي السياقي (context parallel size).

## لماذا FSDP2 فقط؟

ندعم توازى السياق مع `FSDP2` فقط، حيث ننشئ شبكة مشتركة من `context_parallel_size` و`dp_shard_size` لاستغلال كامل إمكاناتها. آلية العمل هي: نقسّم النموذج عبر الشبكة المشتركة ذات الحجم `cp_size*dp_shard_size`، مما يُعظّم توفير الذاكرة. هذا يُشبه "وجبة مجانية" إلى حد ما، لأن اتصال `FSDP` يتداخل بالكامل مع حساب الانتباه، كما هو موضح في الصور أدناه.

  
  
  الشكل 2: في المستطيلات الزرقاء (التدفق 23)، يمكنك ملاحظة أن الجلب المسبق لشريحة `FSDP` متراكب بالكامل مع حساب الانتباه (التدفق 7)، بينما في المستطيلات الحمراء (التدفق 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.
```

