# Экспертная параллельность

[Экспертная параллельность](https://huggingface.co/spaces/nanotron/ultrascale-playbook?section=expert_parallelism) — это стратегия параллелизма для [моделей mixture-of-experts (MoE)](https://huggingface.co/blog/moe). Слой прямой передачи каждого эксперта размещается на отдельном аппаратном ускорителе. Роутер направляет токены к соответствующим экспертам и собирает результаты. Этот подход позволяет масштабировать модели до значительно большего числа параметров без увеличения вычислительных затрат, поскольку каждый токен активирует лишь несколько экспертов.

## DistributedConfig

Включите экспертную параллельность с помощью класса [DistributedConfig](/docs/transformers/v5.23.0/ru/expert_parallelism#transformers.DistributedConfig) и аргумента `ep_size`. Модели MoE разделяют своих экспертов с помощью `"ep_dispatch_experts"`. Их реализации определяют, как токены поступают к экспертам. [Token dispatch](#token-dispatch) позволяет `ep_size` отличаться от `tp_size`. Некоторые реализации EP требуют `ep_size=tp_size`, например `"all_reduce"` и `"deepgemm_megamoe"`, поэтому каждый ранг в группе экспертов хранит одни и те же токены.

У Llama 4 нет плана EP: её эксперты обрабатывают каждый токен, уже масштабированный по его оценке от роутера, поэтому ничего распределять не нужно. Вместо этого используйте тензорное параллелизм (`tp_size`) для их шардирования.
```py
import os

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from transformers.distributed.configuration_utils import DistributedConfig

distributed_config = DistributedConfig(
    tp_size=int(os.environ["WORLD_SIZE"]),
    ep_size=int(os.environ["WORLD_SIZE"]),
)

model = AutoModelForCausalLM.from_pretrained(
    "openai/gpt-oss-120b",
    distributed_config=distributed_config,
)
```

Каждая MoE-модель определяет два плана в своём конфиге: `base_model_tp_plan` для плотных модулей и `base_model_ep_plan` для экспертов. Они доступны в загруженной модели как `model.tp_plan` и `model.ep_plan`. При `tp_size > 1` и `ep_size > 1` применяются оба: план [тензорного параллелизма](./perf_infer_gpu_multi) разбивает внимание и плотные MLP, а план экспертного параллелизма — экспертов. Правила EP имеют приоритет над правилами TP для одних и тех же модулей, поэтому веса экспертов разбиваются один раз, согласно плану EP. В плане EP стиль `GroupedGemmParallel` разбивает веса экспертов вдоль измерения экспертов, так что каждый ранг загружает только своих локальных экспертов, а правило `"ep_dispatch_experts"` для модуля экспертов определяет, как токены к ним поступают.

`tp_plan` применяется только при `tp_size > 1`, а `ep_plan` — только при `ep_size > 1`. Если TP включён, а EP отключён, применяется полный план TP, включая правила для экспертов.

`"ep_dispatch_experts"` распределяет целых экспертов по рангам (`ep_size` — кратное `tp_size` число, делящее `fsdp_size * tp_size`), и обращается к ним через реализацию, указанную в `ep_implementation`, см. [Выбор реализации](#choosing-an-implementation).

### Выбор реализации

`"ep_dispatch_experts"` разбивает экспертов один раз и выбирает, как токены к ним поступают, из реализаций, зарегистрированных в `EPImplementationInterface`, которые выбираются с помощью `ep_implementation` в [DistributedConfig](/docs/transformers/v5.23.0/ru/expert_parallelism#transformers.DistributedConfig):

| `ep_implementation` | преимущества | недостатки |
| :--- | :--- | :--- |
| `"all_to_all"`, см. [распределение токенов](#token-dispatch) | Работает с любой раскладкой, включая `ep_size > tp_size`. Перемещаются только маршрутизированные токены. | Два коллективных all-to-all и один синхронизационный вызов на хосте на каждый слой, поэтому он не захватывается в граф CUDA. |
| `"all_reduce"` | Токены не перемещаются и синхронизация с хостом не требуется, поэтому декодирование захватывается в граф CUDA. | Требуется `ep_size=tp_size`. Каждый ранг выполняет свои эксперты для всей партии, поэтому его стоимость растёт вместе с размером партии. |
| `"deepgemm_megamoe"` | DeepGEMM Mega MoE объединяет dispatch, experts и combine в одном ядре. Каждый слой группы EP разделяет свои буферы симметричной памяти. | Требуется `ep_size=tp_size`, а также FP8-активации с FP4-экспертами на SM100+. Только для инференса. |
| `"auto"`, значение по умолчанию | Выполняет `"all_reduce"` при инференсе, если ранги группы экспертов разделяют одну батч, и `"all_to_all"` в противном случае. | Не всегда является самым быстрым вариантом: рабочая нагрузка может выиграть от кастомной реализации, см. [Добавление реализации](#adding-an-implementation). |

> [!NOTE]
> `ep_implementation` выбирает только среди размеров параллелизма, заданных в [DistributedConfig](/docs/transformers/v5.23.0/ru/expert_parallelism#transformers.DistributedConfig). Если ранги группы экспертов обрабатывают разные батчи, например `tp_size=1` при `fsdp_size=ep_size`, то единственной применимой реализацией является `"all_to_all"`.

### Добавление реализации

Реализация наследует `EPImplementation` и регистрируется под именем `ep_implementation` selects. Она создаётся один раз на модуль экспертов, поэтому может хранить состояние, например, буферы коммуникации. Вызов с батчем, который хранит данный ранк, и глобальными идентификаторами экспертов возвращает взвешенный вывод экспертов для каждого из его токенов. Она запускает экспертов данного ранка с помощью `experts_forward` на строках, локальных идентификаторах экспертов и весах, которые она им передала.

```py
from transformers.distributed.expert_parallel import EPImplementation, EPImplementationInterface

class MyEP(EPImplementation):
    def __call__(self, hidden_states, top_k_index, top_k_weights):
        tokens, expert_ids, weights = ...  # bring this rank's experts the rows routed to them
        expert_output = self.experts_forward(tokens, expert_ids, weights)
        return ...  # the weighted expert output for each token of the batch this rank holds

EPImplementationInterface.register("my_ep", MyEP)
distributed_config = DistributedConfig(tp_size=1, fsdp_size=8, ep_size=8, ep_implementation="my_ep")
```

> [!NOTE]
> Градиенты должны доходить до каждого ранга, на котором хранится токен, включая веса маршрутизации, поэтому коллективные операции, которые autograd не дифференцирует, необходимо оборачивать в `torch.autograd.Function`.

> [!TIP]
> Использование `enable_expert_parallel=True` без `ep_size` устарело и вызывает `FutureWarning`. Это разделяет только экспертов, как в случае `ep_size=tp_size, tp_plan={}`.

Запустите скрипт инференса с помощью [torchrun](https://pytorch.org/docs/stable/elastic/run.html). Количество процессов должно быть равно `tp_size * fsdp_size * pp_size`, а `ep_size` должно делить количество экспертов нацело.

```zsh
torchrun --nproc-per-node 8 your_script.py
```

### Переопределение планов

Передайте `tp_plan={...}` или `ep_plan={...}` в [DistributedConfig](/docs/transformers/v5.23.0/ru/expert_parallelism#transformers.DistributedConfig), чтобы переопределить отдельные правила предопределённых планов. Нерасписанные правила сохраняются, а объединённые планы записываются в модель. Каждый ключ должен соответствовать модулю, параметру или существующей записи плана; в противном случае при загрузке возникает `ValueError` до начала шардирования. Используйте полный путь, как он виден из загруженной модели, то есть `model.layers.*` для causal LM и `layers.*` для её базовой модели.

```py
distributed_config = DistributedConfig(
    tp_size=4,
    ep_size=4,
    tp_plan={"model.layers.*.self_attn.q_proj": "colwise_rep"},
    ep_plan={"model.layers.*.mlp.experts.down_proj": "grouped_gemm"},
)
```

Указание плана не определяет размеры параллелизма: явно задайте `tp_size` и `ep_size`.

При `ep_size=tp_size` реализация по умолчанию `"auto"` выполняет `"all_reduce"` на этапе инференса и распределяет токены при обучении. Чтобы маскировать и выполнять all-reduce также при обучении, установите `ep_implementation="all_reduce"`:

```py
distributed_config = DistributedConfig(tp_size=4, ep_size=4, ep_implementation="all_reduce")
```

## Диспетчеризация токенов

Token dispatch is the `"all_to_all"` implementation: each rank trains on its own part of the batch. At every MoE layer, a rank routes its tokens, sends each (token, expert) pair to the rank that owns the expert with an all-to-all, runs its local experts on what it receives, gets the results back with a second all-to-all and combines them with the routing weights. Only the routed activations and expert outputs travel, and no rank computes experts for tokens it does not own.

```py
from transformers import AutoModelForCausalLM
from transformers.distributed import DistributedConfig

distributed_config = DistributedConfig(
    tp_size=1,
    fsdp_size=8,
    ep_size=4,
)
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-30B-A3B", distributed_config=distributed_config)
```

При `tp_size=1` `ep_size` должно делить `fsdp_size` и количество экспертов, а внимание не ограничивается `num_key_value_heads`. Для остальной части модели:

- Параметры вне экспертов распределяются с помощью [FSDP2](./fsdp) по `fsdp`, что уменьшает их градиенты.
- Эксперты разбиты на шарды по `ep` и, когда `efsdp_size = fsdp_size * tp_size // ep_size` больше единицы, дополнительно разбиты на шарды FSDP по `efsdp`. Они всегда обёрнуты в FSDP, поэтому `fsdp_mixed_precision` и `fsdp_cpu_offload` применяются и к ним, а [save_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.save_pretrained) собирает их так же, как и любой другой параметр.
- Группа экспертного параллелизма содержит `ep_size / tp_size` батчей, поэтому градиент эксперта представляет собой сумму по этому числу батчей. Редукция `efsdp` делит на `fsdp_size`, а не на размер своей группы, что даёт тот же средний по батчу результат, который FSDP2 использует для плотных модулей.
- Каждый локальный эксперт также обрабатывает одну строку нулевых отступов на каждый слой. Ранг, эксперты которого не получили токены, всё равно участвует в обратном all-to-all и в редукции градиентов экспертов.

### Как комбинируются размеры

- `tp_size * fsdp_size` — это количество процессов. `ep_size` не добавляет новых: он лишь перегруппировывает те же ранги, но только для весов экспертов.
- `ep_size` разбивает список экспертов на `ep_size` блоков. Каждый ранг вычисляет `num_experts / ep_size` экспертов, а `ep_size` последовательных рангов хранят один полный набор. Этот набор рангов является группой, в которой выполняется all-to-all.
- `efsdp_size = fsdp_size * tp_size / ep_size` — это количество полных копий набора экспертов. Ранги, находящиеся на одной и той же позиции в разных копиях, разделяют этих экспертов по памяти и усредняют их градиенты, как это делает FSDP для плотных модулей.
- Партия, которую удерживает ранг, зависит только от `fsdp`. Последовательные ранги образуют группу TP и получают одну и ту же партию; группы `fsdp_size` получают разные партии.

Восемь процессов, `tp_size=2, fsdp_size=4`, восемь экспертов:

```text
rank         0      1       2      3       4      5       6      7
batch       [====B0====]   [====B1====]   [====B2====]   [====B3====]     one batch per TP pair
tp           0      1       0      1       0      1       0      1

ep_size=2   E0-3   E4-7    E0-3   E4-7    E0-3   E4-7    E0-3   E4-7     group = a TP pair,   efsdp_size=4
ep_size=4   E0E1   E2E3    E4E5   E6E7    E0E1   E2E3    E4E5   E6E7     group = two pairs,   efsdp_size=2
ep_size=8   E0     E1      E2     E3      E4     E5      E6     E7       group = all ranks,   efsdp_size=1
```

Из рисунка следуют два числа:

- Внутри группы EP каждый токен существует `tp_size` раз, по одному разу на каждый ранг пары, которая хранит его батч. Это не зависит от `ep_size`.
- Группа EP содержит `ep_size / tp_size` различных батчей. Это количество, по которому суммируются градиенты эксперта.

### С параллелизмом тензоров

Установите `tp_size > 1`, чтобы разбить плотные модули по плану TP, в то время как эксперты используют dispatch. На восьми процессах:

```py
distributed_config = DistributedConfig(
    tp_size=2,
    fsdp_size=4,
    ep_size=4,
)
```

Каждая пара TP-рангов получает один и тот же батч, поскольку тензорный параллелизм дублирует активации внутри пары. Если бы оба ранга передали все свои токены, ранг, владеющий экспертом, получил бы каждый токен дважды, вычислил его дважды, и градиент его весов удвоился бы. Эксперты целиком размещены на одном ранге, поэтому дубликат нельзя разделить по весам, а владелец обычно является другим рангом, поэтому проблему нельзя решить через владение, как это делает маскирование. Поэтому пара разделяет строки: каждый TP-ранг передает непересекающуюся часть `1 / tp_size` токенов, результаты возвращаются на тот ранг, который их отправил, а all-reduce по паре нулевых дополненных половин восстанавливает дублированный вывод, который ожидает следующий слой. Разделение выполняется по `tp_size`, а не по `ep_size`, поскольку только ранги, у которых есть батч, могут его отправить. Группы экспертов охватывают четыре ранга, и каждый эксперт разбит FSDP на `efsdp_size = 2` ранга, в то время как FSDP-группа ствольной части охватывает четыре ранга. Обычные ограничения TP для модели, такие как делимость числа головок внимания, по-прежнему применяются к плотным модулям. Срезы токенов могут быть неравными или пустыми, в том числе при декодировании одного токена.

Пока не поддерживается одновременное использование Token dispatch и pipeline parallelism; используйте `pp_size=1` (ещё не проверено). Каждая из этих конфигураций использует восемь GPU:

| Конфигурация | Результат |
| :--- | :--- |
| `DistributedConfig(tp_size=4, fsdp_size=2, ep_size=4)` | Каждая TP-группа из четырёх рангов разделяет одну батч. Во время обучения токены распределяются так, что каждый ранг получает четверть батча; при инференсе используется `"all_reduce"`; при установке `ep_implementation="all_reduce"` он применяется на всех этапах. |
| `DistributedConfig(tp_size=1, fsdp_size=8, ep_size=4)` | Диспетчеризация с независимой партией на каждом ранке, без нарезки, и экспертами, распределёнными через FSDP по парам ранков. |
| `DistributedConfig(tp_size=2, fsdp_size=4, ep_size=4)` | Диспетчеризация с парой TP на каждый батч, где каждая пара разбивает свой батч на две части; два батча на группу экспертов. |
| `DistributedConfig(tp_size=8, ep_size=8)` | Каждый ранг разделяет одну партию. Во время обучения токены распределяются так, что каждый ранг получает одну восьмую партии; при выводе используется `"all_reduce"`; установка `ep_implementation="all_reduce"` применяет его на всех этапах. |

> [!WARNING]
> Класс [Trainer](/docs/transformers/v5.23.0/ru/main_classes/trainer#transformers.Trainer) пока не учитывает диспетчеризацию токенов: подсчёт батчей и токенов предполагает компоновку all-reduce, в которой ранги группы TP разделяют один батч, а существует `fsdp_size` шардов с параллелизмом данных. Поддержка диспетчеризации в Trainer будет добавлена в последующих обновлениях.

## Комбинирование с FSDP2

Параллелизм тензоров и экспертов распределяет веса по собственным сеткам, `tp` и `ep`, но состояние оптимизатора и модули без правил по-прежнему дублируются на каждом ранге группы, что ограничивает размер модели, которую можно обучать. Добавьте [FSDP2](./fsdp) по другому измерению сетки с помощью `fsdp_size`. С использованием маскирования и all-reduce, установите `ep_size=tp_size` и передайте `ep_implementation="all_reduce"`.

```py
from transformers import AutoModelForCausalLM
from transformers.distributed import DistributedConfig

distributed_config = DistributedConfig(
    tp_size=4,
    ep_size=4,  # expert parallel size, must match tp_size with masking and all-reduce
    fsdp_size=2,  # data parallel shards
    ep_implementation="all_reduce",  # "auto" would dispatch tokens in training, which the Trainer does not support yet
)
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-30B-A3B", distributed_config=distributed_config)
```

Загрузите модель как обычно, затем обучите с помощью [Trainer](/docs/transformers/v5.23.0/ru/main_classes/trainer#transformers.Trainer). Он вычисляет норму градиента по обеим сеткам и назначает каждой сетке собственную группу параметров оптимизатора. [save_model()](/docs/transformers/v5.23.0/ru/main_classes/trainer#transformers.Trainer.save_model) собирает разбитые веса в обычный чекпоинт. Для этого требуется `accelerate>=1.12`, чтобы `Trainer` мог отразить `tp_size` и `fsdp_size` в `~Accelerate.ParallelismConfig`.

Таблица ниже сравнивает обучение только с EP с обучением 2D EP+FSDP2 на 8xH100 GPU. Нагрузкой является полное дообучение Qwen3-30B-A3B в bf16 при длине последовательности 2048. Увеличение количества шардов FSDP снижает пиковое потребление памяти, а токены/с немного падают, так как FSDP2 выполняет all-gather и reduce-scatter экспертов через `fsdp`.

| конфигурация | токенов/с/ГП | пиковая память/ГП |
|---|---|---|
| `tp_size=8` | 3485 | 38,6 ГБ |
| `tp_size=4, fsdp_size=2` | 2900 | 34,2 ГБ |
| `tp_size=2, fsdp_size=4` | 2830 | 32,3 ГБ |

> [!WARNING]
> Возобновление обучения из контрольной точки пока не поддерживается для моделей, разбитых на части при загрузке, поэтому [Trainer](/docs/transformers/v5.23.0/ru/main_classes/trainer#transformers.Trainer) принимает для них только `save_only_model=True` или `save_strategy="no"`.

## Справочник API[[transformers.DistributedConfig]]

#### transformers.DistributedConfig[[transformers.DistributedConfig]]

```python
transformers.DistributedConfig(tp_size: int | None = None, tp_plan: typing.Union[dict[str, str], typing.Literal['auto'], NoneType] = None, enable_sequence_parallel: bool = False, enable_expert_parallel: bool = False, fsdp_size: int | None = None, dp_replicate_size: int | None = None, fsdp_plan: dict[str, str] | None = None, fsdp_cpu_offload: bool = False, fsdp_mixed_precision: bool = False, pp_size: int | None = None, ep_size: int | None = None, ep_plan: dict[str, str] | None = None, ep_implementation: str = 'auto')
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/distributed/configuration_utils.py#L26)

**Параметры:**

tp_size (`int`, *optional*) : Количество устройств для tensor parallelism. Если `None` и задан `tp_plan`, по умолчанию равно `WORLD_SIZE // (other_parallel_size)`. Если `None` и `tp_plan` не задан, по умолчанию равно 1.

tp_plan (`dict[str, str]` или `"auto"`, *необязательно*) : План шардирования тензорного параллелизма. Передайте `"auto"` или оставьте `None`, если задан `tp_size`, чтобы использовать предопределённый `base_model_tp_plan` модели. Передайте словарь, чтобы переопределить отдельные правила этого плана; неуказанные правила сохраняются. Пустой словарь не применяет ни одного правила тензорного параллелизма.

enable_sequence_parallel (`bool`, *необязательный*, по умолчанию `False`) : Зарезервировано для последовательного параллелизма. Пока не реализовано.

enable_expert_parallel (`bool`, *необязательный*, по умолчанию `False`) : Устаревший параметр, удалён в v5.21. При отсутствии `ep_size` эквивалентен `ep_size=tp_size, tp_plan={}`: план экспертного параллелизма на `tp_size` рангах. Явно заданное значение `ep_size` имеет приоритет. Этот флаг не изменяет `tp_size` или `fsdp_size`.

fsdp_size (`int`, *optional*) : Количество устройств для FSDP (параллелизм данных). Если `None` и `tp_size` задано, по умолчанию равно 1.

dp_replicate_size (`int`, *optional*) : Количество реплик FSDP (HSDP). Параметры распределяются по `fsdp_size` устройствам и реплицируются `dp_replicate_size` раз: градиенты сворачиваются и распределяются (reduce-scatter) внутри реплики, затем агрегируются (all-reduce) между репликами. По умолчанию равно 1. Мы рекомендуем использовать этот параметр для обучения на нескольких узлах: обычный FSDP собирает параметры (all-gather) и сворачивает градиенты (reduce-scatter) на всех устройствах на каждом шаге, поэтому этот трафик проходит по более медленным межузловым каналам. Установите `dp_replicate_size` равным количеству узлов, а `fsdp_size * tp_size` — количеству устройств на узле: тогда трафик распределения останется на быстрых внутриузловых каналах, а агрегация градиентов будет проходить только между узлами. Цена за это — большее потребление памяти на устройство, так как параметры распределяются внутри узла.

fsdp_plan (`dict[str, str]`, *необязательный*) : план шардирования FSDP2. Оставьте `None`, чтобы использовать предопределённый для модели `base_model_fsdp_plan` и классовый `_fsdp_plan`. Передайте словарь, чтобы переопределить отдельные правила; неуказанные правила сохраняются. Применяется только при `dp_replicate_size * fsdp_size > 1`.

fsdp_cpu_offload (`bool`, *необязательный*, по умолчанию `False`) : Включает ли выгрузку на CPU для FSDP2.

fsdp_mixed_precision (`bool`, *необязательный*, по умолчанию `False`) : Включает ли смешанную точность для FSDP2.

pp_size (`int`, *optional*) : Количество устройств для параллелизма по конвейеру. Если `None` и задан другой режим параллелизма, по умолчанию равно 1.

ep_size (`int`, *optional*) : Количество устройств, владеющих различными фрагментами экспертов. По умолчанию равно 1. Укажите явно для включения EP. Должно быть кратным `tp_size` и делить `fsdp_size * tp_size`. Для `ep_size > tp_size` требуется правило `"ep_dispatch_experts"` с `ep_implementation`, обменивающим токены, например `"all_to_all"`.

ep_plan (`dict[str, str]`, *необязательный*) : План шардирования для параллелизма экспертов. Оставьте `None`, чтобы использовать предопределённый план `base_model_ep_plan` модели. Передайте словарь, чтобы переопределить отдельные правила этого плана; неуказанные правила сохраняются. Применяется только при `ep_size > 1`, и его правила имеют приоритет над правилами `tp_plan` для тех же модулей. Правило `"ep_dispatch_experts"` позволяет `ep_implementation` выбирать способ доставки токенов к экспертам.

ep_implementation (`str`, *необязательный*, по умолчанию `"auto"`) : Описывает, как правило `"ep_dispatch_experts"` доставляет токены экспертам. Указывает имя `EPImplementation`, зарегистрированного в `EPImplementationInterface`:  - `"all_to_all"` обменивает маршрутизированные токены с помощью коллективных операций all-to-all. - `"all_reduce"` запускает экспертов каждого ранга на батче, общим для группы EP, и суммирует выходные данные. Требует, чтобы `ep_size == tp_size`. - `"deepgemm_megamoe"` передает этот батч в DeepGEMM Mega MoE, ядро которого самостоятельно обменивает токены. Загрузка с параметром `experts_implementation="deepgemm_megamoe"` выбирает этот вариант. - `"auto"` использует `"all_reduce"` при инференсе, если группа EP разделяет один батч, и `"all_to_all"` в остальных случаях.

Конфигурация для нативного распределённого вывода и обучения с использованием параллелизма по тензорам, конвейерной параллели или FSDP2.

