# توازي التسلسل في Ulysses

Ulysses sequence parallelism (SP) trains on very long sequences by splitting them across multiple GPUs. To compute attention correctly, an all-to-all collective swaps the sharding dimension from sequence to attention heads. Each GPU then has the full sequence and computes attention locally over a subset of heads. A second all-to-all returns to the sequence-sharded layout so the rest of the forward pass continues locally on each chunk.

```text
                        GPU 0                       GPU 1
                   ┌───────────────┐          ┌───────────────┐
  forward          │ tokens 0..N/2 │          │ tokens N/2..N │  ← each GPU holds half the sequence
  (seq-sharded)    │  all H heads  │          │  all H heads  │
                   └───────┬───────┘          └───────┬───────┘
                           └───────── all-to-all ──────┘
                   ┌───────────────┐          ┌───────────────┐
  attention        │ all N tokens  │          │ all N tokens  │  ← now each GPU has the full sequence
  (head-sharded)   │ heads 0..H/2  │          │ heads H/2..H  │  ← but only half the heads
                   └───────┬───────┘          └───────┬───────┘
                           └───────── all-to-all ──────┘
                   ┌───────────────┐          ┌───────────────┐
  forward          │ tokens 0..N/2 │          │ tokens N/2..N │  ← back to seq-sharded
  (seq-sharded)    │  all H heads  │          │  all H heads  │
                   └───────────────┘          └───────────────┘
```

> [!NOTE]
> يتناول هذا الدليل مكوّن موازاة التسلسل Ulysses ضمن [ALST](https://www.deepspeed.ai/tutorials/ulysses-alst-sequence-parallelism/) (تدريب التسلسلات الطويلة القطبية). كما يتضمن نظام ALST الكامل مكوّني TiledMLP وإفراغ نقاط التفتيش للتفعيل، وهما غير متوفرين في Transformers. راجع [دليل DeepSpeed ALST](https://www.deepspeed.ai/tutorials/ulysses-alst-sequence-parallelism/) للاطلاع على النظام الكامل.

## إعداد

يتطلب توازي التسلسل (Sequence parallelism) إصدار Accelerate 1.12.0 على الأقل، ووحدة معالجة رسومية (GPU) واحدة على الأقل. قم بإعداد توازي التسلسل في `ParallelismConfig` الخاص بـ Accelerate، ثم مرّره إلى [parallelism_config](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments.parallelism_config) أو إلى [ملف إعدادات Accelerate](./accelerate#accelerate-config-file).

```py
from accelerate.utils import ParallelismConfig, DeepSpeedSequenceParallelConfig

parallelism_config = ParallelismConfig(
    sp_backend="deepspeed",
    sp_size=4,
    dp_replicate_size=1,
    sp_handler=DeepSpeedSequenceParallelConfig(
        sp_seq_length_is_variable=True,
        sp_attn_implementation="flash_attention_2",
    ),
)

training_args = TrainingArguments(
    ...,
    deepspeed="path/to/deepspeed_config.json",
    parallelism_config=parallelism_config,
)
```

شغّل [accelerate launch](https://huggingface.co/docs/accelerate/en/package_reference/cli#accelerate-launch) مع سكربت مبني على [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer).

```shell
accelerate launch --num_processes 4 train.py \
--output_dir output_dir \
--per_device_train_batch_size 1 \
--gradient_accumulation_steps 1
```

شغّل الأمر [accelerate config](https://huggingface.co/docs/accelerate/en/package_reference/cli#accelerate-config) وأجب عن الأسئلة المتعلقة بمكوناتك المادية وإعداد التدريب لإنشاء ملف `default_config.yaml` في ذاكرتك المؤقتة.

```yaml
distributed_type: DEEPSPEED
deepspeed_config:
  deepspeed_config_file: path/to/ds_config.json
machine_rank: 0
num_machines: 1
num_processes: 4
parallelism_config:
  parallelism_config_sp_size: 4
  parallelism_config_dp_replicate_size: 1
  parallelism_config_sp_backend: deepspeed
  parallelism_config_sp_seq_length_is_variable: true
  parallelism_config_sp_attn_implementation: flash_attention_2
```

شغّل [accelerate launch](https://huggingface.co/docs/accelerate/en/package_reference/cli#accelerate-launch) مع سكربت مبني على [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer).

```shell
accelerate launch --config_file alst_config.yaml train.py \
--output_dir output_dir \
--per_device_train_batch_size 1 \
--gradient_accumulation_steps 1
```

الحقول التالية مهمة لإعداد توازي التسلسل.

> [!TIP]
> يتولى [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) تلقائيًا إدارة تقسيم DataLoader، وتوليد `position_ids`، وإزاحة التسميات، وتجميع الخسارة عبر رتب SP. إذا كنت تكتب حلقة تدريب مخصصة، فراجع دليل [Sequence Parallelism](https://huggingface.co/docs/accelerate/concept_guides/sequence_parallelism) الخاص بـ Accelerate بدلاً من ذلك.

- يجب تعيين `sp_backend` إلى `"deepspeed"` لاستخدام موازاة تسلسل Ulysses.

- `sp_size` هو عدد وحدات معالجة الرسوميات التي تعالج تسلسلاً واحداً بالتوازي. يستقبل كل رتبة SP تدفّق بيانات فريداً من DataLoader، على عكس توازي الموترات حيث تستقبل جميع الرتب بيانات متطابقة. الحجم الفعّال هو `dp_world_size = world_size / sp_size`، لذا مع 4 وحدات معالجة رسوميات و`sp_size=4`، يكون `dp_world_size=1` لحسابات حجم الدفعة. يجب أيضاً ملء التسلسلات إلى مضاعف لـ`sp_size`. اضبط `pad_to_multiple_of` في مجمّع البيانات الخاص بك وفقاً لذلك.

    > [!WARNING]
    > يجب أن يكون عدد رؤوس الانتباه قابلاً للقسمة على `sp_size`. يدعم النموذج الذي يحتوي على 32 رأساً قيم `sp_size` التالية: 1، 2، 4، 8، 16، أو 32.

    ```py
    from transformers import DataCollatorForLanguageModeling

    data_collator = DataCollatorForLanguageModeling(
        tokenizer=tokenizer,
        mlm=False,
        pad_to_multiple_of=sp_size,
    )
    ```

- يتحكم `sp_seq_length_is_variable` في معالجة طول التسلسل المتغير. اضبطه على `True` (موصى به) عند وجود أطوال متغيرة بين الدفعات. اضبطه على `False` عندما تكون جميع التسلسلات ممتلئة حتى طول ثابت محدد بواسطة `sp_seq_length`.

- يحدد `sp_attn_implementation` واجهة التنفيذ الخاصة بالانتباه. القيم المدعومة هي `"sdpa"` أو `"flash_attention_2"` أو `"flash_attention_3"`. يُوصى باستخدام FlashAttention، خاصة عند حزم عينات متعددة في دفعة واحدة. قد يؤدي استخدام SDPA إلى الانتباه بشكل غير صحيح عبر حدود العينات عند حزمها. ولا يُدعم الانتباه الفوري (Eager attention) لأن قناع الانتباه ذي الأبعاد الأربعة `attention_mask` يُستبعد لأسباب تتعلق بالذاكرة والتوسع.

## الجمع مع توازي البيانات

تستخدم موازاة التسلسل وموازاة البيانات نفس وحدات معالجة الرسوميات، ولا تتطلب موازاة التسلسل أي أجهزة إضافية. لتشغيل كلا النوعين، اضبط `dp_replicate_size` أو `dp_shard_size` بحيث يساوي `dp_replicate_size × dp_shard_size × sp_size` إجمالي عدد وحدات معالجة الرسوميات لديك.

على سبيل المثال، مع 8 وحدات معالجة رسومية و`sp_size=4`، اضبط `dp_replicate_size=2` (2 × 1 × 4 = 8).

```py
parallelism_config = ParallelismConfig(
    sp_backend="deepspeed",
    sp_size=4,
    dp_replicate_size=2,
    sp_handler=DeepSpeedSequenceParallelConfig(
        sp_seq_length_is_variable=True,
        sp_attn_implementation="flash_attention_2",
    ),
)
```

## الخطوات التالية

- التوازي السياقي مع FSDP2 (`cp_size`) منفصل عن Ulysses (`sp_size`). راجع [التقييم مع التوازي السياقي](./fsdp#evaluate-with-context-parallelism).
- يتناول دليل التسلسل المتوازي [Sequence Parallelism](https://huggingface.co/docs/accelerate/concept_guides/sequence_parallelism) في Accelerate تنفيذ Ulysses بتفصيل أكبر، ويوضح كيفية كتابة حلقة تدريب مخصصة.
- يتناول [دليل DeepSpeed ALST](https://www.deepspeed.ai/tutorials/ulysses-alst-sequence-parallelism/) نظام ALST بالكامل، بما في ذلك TiledMLP وإفراغ نقاط التفتيش التفعيل.
- يوضح دليل [طرق التوازي](./perf_train_gpu_many) كيفية دمج توازي التسلسل مع استراتيجيات أخرى مثل ZeRO.
- يشرح منشور المدونة [Ulysses Sequence Parallelism: Training with Million-Token Contexts](https://huggingface.co/blog/ulysses-sp) كيفية عمل Ulysses وكيفية دمجه في Accelerate وTrainer وSFTTrainer.