# Утилиты полностью шардированного параллелизма данных

## enable_fsdp_ram_efficient_loading[[accelerate.utils.enable_fsdp_ram_efficient_loading]]

#### accelerate.utils.enable_fsdp_ram_efficient_loading[[accelerate.utils.enable_fsdp_ram_efficient_loading]]

```python
accelerate.utils.enable_fsdp_ram_efficient_loading()
```

[Источник](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L40)

Включает загрузку моделей Hugging Face с эффективным использованием оперативной памяти для FSDP в среде.

## disable_fsdp_ram_efficient_loading[[accelerate.utils.disable_fsdp_ram_efficient_loading]]

#### accelerate.utils.disable_fsdp_ram_efficient_loading[[accelerate.utils.disable_fsdp_ram_efficient_loading]]

```python
accelerate.utils.disable_fsdp_ram_efficient_loading()
```

[Источник](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L50)

Отключает загрузку моделей Hugging Face с эффективным использованием ОЗУ для FSDP в среде.

## merge_fsdp_weights[[accelerate.utils.merge_fsdp_weights]]

#### accelerate.utils.merge_fsdp_weights[[accelerate.utils.merge_fsdp_weights]]

```python
accelerate.utils.merge_fsdp_weights(checkpoint_dir: str, output_path: str, safe_serialization: bool = True, remove_checkpoint_dir: bool = False)
```

[Источник](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L486)

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

checkpoint_dir (`str`) : каталог, содержащий контрольные точки FSDP (может быть как моделью, так и оптимизатором).

output_path (`str`) : Путь для сохранения объединённой контрольной точки.

safe_serialization (`bool`, *необязательный*, по умолчанию `True`) : Сохранять ли объединённые веса в формате safetensors (рекомендуется).

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

Объедините веса из разбитых контрольных точек модели FSDP в одну общую контрольную точку. Следует использовать, если для модели применялся `SHARDED_STATE_DICT`. Веса будут сохранены в `{output_path}/model.safetensors`, если `safe_serialization`, иначе в `pytorch_model.bin`.

Примечание: это процесс, ограниченный производительностью CPU.

## FullyShardedDataParallelPlugin[[accelerate.FullyShardedDataParallelPlugin]]

#### accelerate.FullyShardedDataParallelPlugin[[accelerate.FullyShardedDataParallelPlugin]]

```python
accelerate.FullyShardedDataParallelPlugin(fsdp_version: int = None, sharding_strategy: str | ForwardRef('torch.distributed.fsdp.ShardingStrategy') = None, reshard_after_forward: str | ForwardRef('torch.distributed.fsdp.ShardingStrategy') | bool = None, backward_prefetch: str | ForwardRef('torch.distributed.fsdp.BackwardPrefetch') | None = None, mixed_precision_policy: dict | str | ForwardRef('torch.distributed.fsdp.MixedPrecision') | ForwardRef('torch.distributed.fsdp.MixedPrecisionPolicy') | None = None, auto_wrap_policy: typing.Callable | typing.Literal['transformer_based_wrap', 'size_based_wrap', 'no_wrap'] | None = None, cpu_offload: bool | ForwardRef('torch.distributed.fsdp.CPUOffload') | ForwardRef('torch.distributed.fsdp.CPUOffloadPolicy') = None, ignored_modules: collections.abc.Iterable[torch.nn.Module] | str | None = None, state_dict_type: str | ForwardRef('torch.distributed.fsdp.StateDictType') = None, state_dict_config: ForwardRef('torch.distributed.fsdp.FullStateDictConfig') | ForwardRef('torch.distributed.fsdp.ShardedStateDictConfig') | None = None, optim_state_dict_config: ForwardRef('torch.distributed.fsdp.FullOptimStateDictConfig') | ForwardRef('torch.distributed.fsdp.ShardedOptimStateDictConfig') | None = None, limit_all_gathers: bool = True, use_orig_params: bool | None = None, param_init_fn: typing.Callable[[torch.nn.Module], NoneType] | None = None, sync_module_states: bool | None = None, forward_prefetch: bool = None, activation_checkpointing: bool = None, activation_checkpointing_offload: bool = None, cpu_ram_efficient_loading: bool = None, transformer_cls_names_to_wrap: list[str] | None = None, min_num_params: int | None = None)
```

[Источник](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/dataclasses.py#L1465)

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

fsdp_version (`int`, по умолчанию `1`) : Версия FSDP для использования. По умолчанию 1. Если установлено значение 2, загрузчик ожидает, что конфигурация будет преобразована в формат FSDP2.

sharding_strategy (`Union[str, torch.distributed.fsdp.ShardingStrategy]`, по умолчанию `'FULL_SHARD'`) : Стратегия шардирования. Должна быть либо `str`, либо экземпляром `torch.distributed.fsdp.fully_sharded_data_parallel.ShardingStrategy`. Устарела, рекомендуется использовать `reshard_after_forward`.

reshard_after_forward (`Union[str, torch.distributed.fsdp.ShardingStrategy, bool]`, по умолчанию `'FULL_SHARD'` для `fsdp_version=1` и `True` для `fsdp_version=2`) : Стратегия шардирования. Должна быть bool, если `fsdp_version` установлено в 2, иначе `str` или экземпляр `torch.distributed.fsdp.fully_sharded_data_parallel.ShardingStrategy`.

backward_prefetch (`Union[str, torch.distributed.fsdp.BackwardPrefetch]`, по умолчанию `'NO_PREFETCH'`) : Стратегия предварительной загрузки в обратном направлении. Должно быть либо `str`, либо экземпляром `torch.distributed.fsdp.fully_sharded_data_parallel.BackwardPrefetch`.

mixed_precision_policy (`Optional[Union[dict, str, torch.distributed.fsdp.MixedPrecision, torch.distributed.fsdp.MixedPrecisionPolicy]]`, по умолчанию `None`) : Конфигурация для включения обучения с смешанной точностью с использованием FullyShardedDataParallel. Если передается `dict`, он должен содержать следующие ключи: `param_dtype`, `reduce_dtype` и `buffer_dtype`. Если `fsdp_version` установлен в 2, может быть передан экземпляр `torch.distributed.fsdp.MixedPrecisionPolicy`. Если передается `str`, он должен быть одним из следующих значений: fp8, fp16, bf16, fp32, и используется для установки `param_dtype`, `reduce_dtype` и `buffer_dtype`.

auto_wrap_policy (`Optional(Union[Callable, Literal["transformer_based_wrap", "size_based_wrap", "no_wrap"]]), defaults to `NO_WRAP`) : A callable or string specifying a policy to recursively wrap layers with FSDP. If a string, it must be one of `transformer_based_wrap`, `size_based_wrap`, or `no_wrap`. See `torch.distributed.fsdp.wrap.size_based_wrap_policy` for a direction on what it should look like.

cpu_offload (`Union[bool, torch.distributed.fsdp.CPUOffload, torch.distributed.fsdp.CPUOffloadPolicy]`, по умолчанию `False`) : следует ли выгружать параметры на CPU. Значением может быть `bool` или экземпляр `torch.distributed.fsdp.fully_sharded_data_parallel.CPUOffload` или `torch.distributed.fsdp.fully_sharded_data_parallel.CPUOffloadPolicy`, если `fsdp_version` установлен в 2.

ignored_modules (`Optional[Union[Iterable[torch.nn.Module], str]]`, по умолчанию `None`) : Список модулей, которые следует игнорировать при обёртке с помощью FSDP. При передаче строки модули сопоставляются по имени с использованием regex fullmatch. Если `fsdp_version` установлен в значение 2, модули преобразуются в параметры и используются.

state_dict_type (`Union[str, torch.distributed.fsdp.StateDictType]`, по умолчанию `'FULL_STATE_DICT'`) : Тип state dict для использования. Если передана строка, она должна быть одной из `full_state_dict`, `local_state_dict` или `sharded_state_dict`.

state_dict_config (`Optional[Union[torch.distributed.fsdp.FullStateDictConfig, torch.distributed.fsdp.ShardedStateDictConfig]`, по умолчанию `None`) : Конфигурация state dict для использования. Если не передана, определяется на основе `state_dict_type`.

optim_state_dict_config (`Optional[Union[torch.distributed.fsdp.FullOptimStateDictConfig, torch.distributed.fsdp.ShardedOptimStateDictConfig]`, по умолчанию `None`) : Конфигурация state dict для оптимизатора. Если не передана, определяется на основе `state_dict_type`.

limit_all_gathers (`bool`, по умолчанию `True`) : Указывает, следует ли FSDP явно синхронизировать CPU-поток, чтобы предотвратить слишком большое количество незавершённых all-gather операций. Этот параметр влияет только на стратегии с шардированием, которые планируют all-gather операции. Включение этой опции может помочь снизить количество повторных попыток выделения памяти CUDA.

use_orig_params (`bool`, по умолчанию `False`) : Использовать ли исходные параметры для оптимизатора.

param_init_fn (`Optional[Callable[[torch.nn.Module], None]`, по умолчанию `None`) : `Callable[torch.nn.Module] -> None`, определяющий, как модули, находящиеся на meta-устройстве, должны быть инициализированы на фактическом устройстве. Применимо только тогда, когда `sync_module_states` равно `True`. По умолчанию это `lambda`, вызывающая `to_empty` для модуля.

sync_module_states (`bool`, по умолчанию `False`) : Следует ли каждому индивидуально обернутому модулю FSDP транслировать параметры модуля с ранга 0, чтобы гарантировать их идентичность на всех рангах после инициализации. По умолчанию `False`, если только `cpu_ram_efficient_loading` не равно `True`, в этом случае параметр принудительно включается.

forward_prefetch (`bool`, по умолчанию `False`) : Указывает, следует ли FSDP явно выполнять предварительную загрузку (prefetch) следующего all-gather во время выполнения прямого прохода. Используйте только со статическими графами.

activation_checkpointing (`bool`, по умолчанию `False`) : Техника для снижения потребления памяти путём очистки активаций определённых слоёв и их повторного вычисления во время обратного прохода. По сути, это позволяет сэкономить память за счёт дополнительного времени вычислений.

cpu_ram_efficient_loading (`bool`, по умолчанию `None`) : Если True, только первый процесс загружает контрольную точку предобученной модели, а все остальные процессы имеют пустые веса. Применимо только для Transformers. При использовании этого параметра `sync_module_states` должен быть `True`.

transformer_cls_names_to_wrap (`Optional[List[str]]`, по умолчанию `None`) : список имён классов слоёв трансформера для обёртки. Применимо только тогда, когда `auto_wrap_policy` равно `transformer_based_wrap`.

min_num_params (`Optional[int]`, по умолчанию `None`) : минимальное количество параметров, которое должен иметь модуль, чтобы быть обернутым. Применимо только тогда, когда `auto_wrap_policy` равно `size_based_wrap`.

Это плагин используется для включения полностью шардированного параллелизма данных.

#### set_auto_wrap_policy[[accelerate.FullyShardedDataParallelPlugin.set_auto_wrap_policy]]

```python
set_auto_wrap_policy(model)
```

[Источник](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/dataclasses.py#L1941)

Создаёт `auto_wrap_policy` на основе переданной политики и возможности использования `transformer_cls_to_wrap` для `model`.

#### set_mixed_precision[[accelerate.FullyShardedDataParallelPlugin.set_mixed_precision]]

```python
set_mixed_precision(mixed_precision, buffer_autocast = False, override = False)
```

[Источник](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/dataclasses.py#L1981)

Устанавливает политику смешанной точности для FSDP

#### set_state_dict_type[[accelerate.FullyShardedDataParallelPlugin.set_state_dict_type]]

```python
set_state_dict_type(state_dict_type = None)
```

[Источник](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/dataclasses.py#L1896)

Установите конфигурацию state dict на основе `StateDictType`.

#### validate_mixed_precision_policy[[accelerate.FullyShardedDataParallelPlugin.validate_mixed_precision_policy]]

```python
validate_mixed_precision_policy()
```

[Источник](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/dataclasses.py#L2029)

Проверяет политику смешанной точности, абстрагированную так, чтобы не импортировать зависимости, если они не нужны.

## fsdp2_load_full_state_dict[[accelerate.utils.fsdp2_load_full_state_dict]]

#### accelerate.utils.fsdp2_load_full_state_dict[[accelerate.utils.fsdp2_load_full_state_dict]]

```python
accelerate.utils.fsdp2_load_full_state_dict(accelerator, model: Module, full_sd: dict, cpu_offload: bool = False)
```

[Источник](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L584)

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

accelerator (`Accelerator`) : экземпляр акселератора

model (`torch.nn.Module`) : модель, в которую будет загружен state dict; ожидается, что она находится на meta device, иначе может произойти скачок потребления VRAM

full_sd (`dict`) : Полный state dict для загрузки, может находиться только на rank 0

cpu_offload (`bool`, по умолчанию `False`) : Если True, перемещает шардированные параметры на CPU после распределения. Обязательно, если включено выделение памяти FSDP на CPU. Буферы и игнорируемые параметры остаются на устройстве акселератора.

Загружает полный state dict (возможно, только на rank 0) в шардированную модель. Это выполняется путём рассылки параметров с rank 0 на все остальные ранги. Данная функция изменяет модель на месте.

## fsdp2_switch_optimizer_parameters[[accelerate.utils.fsdp2_switch_optimizer_parameters]]

#### accelerate.utils.fsdp2_switch_optimizer_parameters[[accelerate.utils.fsdp2_switch_optimizer_parameters]]

```python
accelerate.utils.fsdp2_switch_optimizer_parameters(optimizer: Optimizer, mapping: dict)
```

[Источник](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L658)

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

optimizer (`torch.optim.Optimizer`) : экземпляр оптимизатора, содержащий исходные параметры модели

mapping (`dict`) : Соответствие между указателем на данные исходного параметра (или идентификатором для мета-параметров) и шардированным параметром.

**Исключения:** ``KeyError``

- ``KeyError`` --  Если параметр в оптимизаторе не удалось переключить на его шардированную версию. Этого не должно происходить, и это указывает на ошибку. Если бы мы сохранили исходные параметры вместо того, чтобы вызывать исключение, обучение не было бы численно корректным, а веса не обновлялись бы.

Переключает параметры оптимизатора на новые (в обычном случае — на шардированные параметры). Эта функция изменяет оптимизатор на месте.

## fsdp2_prepare_model[[accelerate.utils.fsdp2_prepare_model]]

#### accelerate.utils.fsdp2_prepare_model[[accelerate.utils.fsdp2_prepare_model]]

```python
accelerate.utils.fsdp2_prepare_model(accelerator, model: Module)
```

[Источник](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L740)

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

accelerator (`Accelerator`) : экземпляр акселератора

model (`torch.nn.Module`) : модель для подготовки

**Возвращает:** `torch.nn.Module`

Подготовленная модель

Подготавливает модель для FSDP2 на месте. Также возвращает модель, чтобы избежать неправильного использования исходной модели.

## fsdp2_prepare_auto_wrap_policy

