# Картирование слияния (экспериментальная функция)

Fusion mapping предоставляет опциональный способ замены подмодулей модели при загрузке с сохранением исходного формата контрольной точки.

Опирается на:

- [Monkey patching](./monkey_patching) для замены классов модулей до создания экземпляра модели.
- [Динамическая загрузка весов](./weightconverter) для сопоставления весов между исходным и объединённым форматами выполнения.

> [!WARNING]
> Fusion mapping — это экспериментальная функция загрузки. Она изменяет структуру модулей во время выполнения и может повлиять на поведение модели. Используйте её только в том случае, если вы явно хотите получить слиянную (fused) структуру во время выполнения.

## Быстрый старт

Fusion включается через [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) с параметром `fusion_config`:

```python
from transformers import AutoModelForImageTextToText

model = AutoModelForImageTextToText.from_pretrained(
    "Qwen/Qwen2-VL-2B-Instruct",
    fusion_config={"patch_embeddings": True},
)
```

По умолчанию слияние не применяется. Если `fusion_config` сохранён в конфигурации модели, `from_pretrained()` автоматически использует его повторно.

## Как это работает

Регистрация слияния происходит до создания экземпляра модели:

1. [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) использует явный аргумент `fusion_config` или обращается к `config.fusion_config`.
2. Реестр слияний проверяет запрошенные имена слияний.
3. Каждый включённый fusion метаинициализирует целевой класс модели, при необходимости фильтрует кандидаты модулей по имени и использует `is_fusable(...)` для обнаружения совместимых классов модулей.
4. Классы для слияния регистрируются через [register_patch_mapping()](/docs/transformers/v5.23.0/ru/monkey_patching#transformers.monkey_patching.register_patch_mapping).
5. Правила `~WeightTransform` генерируются из конфигурации, чтобы при загрузке контрольной точки веса могли быть отображены в объединённую структуру рантайма.
6. По умолчанию [save_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.save_pretrained) использует обратный путь преобразования для восстановления исходной структуры контрольной точки. Передайте `save_original_format=False`, чтобы сохранить преобразованную структуру времени выполнения.

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

Примечание: В текущем механизме monkey-patching регистрация слияния выполняется на уровне класса: один совместимый класс модуля сопоставляется с одним классом слияния.

## Семейства текущих слияний

В настоящее время `fusion_config` поддерживает одно семейство слияний:

- `patch_embeddings` Включить с помощью:

  ```python
  fusion_config = {"patch_embeddings": True}
  ```

  Эффект: заменяет совместимые проекции встраивания патчей `nn.Conv3d` на эквивалентные сплющенные проекции `nn.Linear` во время выполнения.

## Расширение отображения слияния

Чтобы добавить новое семейство слияний:

1. Добавьте предикат `is_fusable`. Он определяет, совместим ли обнаруженный модуль с слиянием.
2. При необходимости добавьте `target_modules_patterns`. Это делает этап обнаружения более явным, предварительно фильтруя имена кандидатов модулей перед вызовом `is_fusable(...)`.
3. Добавьте фабрику `make_fused_class`. Она возвращает класс замены для совместимого класса модуля во время выполнения.
4. Добавьте фабрику `make_transforms`, если для слиянного макета требуется конвертация контрольных точек. Она возвращает правила `~WeightTransform`, которые отображают веса между исходным и слиянным макетами для заданной конфигурации.
5. Зарегистрируйте новый `ModuleFusionSpec` в [`fusion_mapping.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py).

После регистрации новая фузия становится доступной через `fusion_config`.

## Внутренний API[[transformers.fusion_mapping.ModuleFusionSpec]]

#### transformers.fusion_mapping.ModuleFusionSpec[[transformers.fusion_mapping.ModuleFusionSpec]]

```python
transformers.fusion_mapping.ModuleFusionSpec()
```

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

Базовый рецепт для семейства fusion.

Спецификация слияния определяет, какие модули подходят для слияния, как построить класс замены для времени выполнения и какие преобразования весов необходимы для сопоставления контрольных точек между исходной и слитой раскладками.

#### get_empty_log[[transformers.fusion_mapping.ModuleFusionSpec.get_empty_log]]

```python
get_empty_log(model_name: str)
```

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

Возвращает сообщение журнала, выводимое, если не найдено ни одного совместимого модуля.

#### is_fusable[[transformers.fusion_mapping.ModuleFusionSpec.is_fusable]]

```python
is_fusable(module: Module)
```

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

Возвращает, является ли `module` совместимым с данным семейством слияний.

#### make_fused_class[[transformers.fusion_mapping.ModuleFusionSpec.make_fused_class]]

```python
make_fused_class(original_cls: type[torch.nn.Module])
```

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

Создайте класс замены во время выполнения для совместимого класса модуля.

#### make_transforms[[transformers.fusion_mapping.ModuleFusionSpec.make_transforms]]

```python
make_transforms(config: PretrainedConfig)
```

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

Создайте преобразования весов, необходимые для загрузки и сохранения объединённой компоновки времени выполнения.

#### transformers.fusion_mapping.PatchEmbeddingsFusionSpec[[transformers.fusion_mapping.PatchEmbeddingsFusionSpec]]

```python
transformers.fusion_mapping.PatchEmbeddingsFusionSpec()
```

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

Слияние совместимых встраиваний патчей Conv3d в развёрнутые линейные проекции.

#### transformers.fusion_mapping._register_module_fusion[[transformers.fusion_mapping._register_module_fusion]]

```python
transformers.fusion_mapping._register_module_fusion(config: PretrainedConfig, fusion_name: str, spec: ModuleFusionSpec)
```

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

Зарегистрируйте одно семейство слияний для `cls`.

Эта функция обновляет два глобальных реестра, используемых при объединённой загрузке:
- реестр monkey-patching, благодаря которому совместимые классы модулей заменяются до инициализации
- маппинг конвертации чекпоинта, чтобы слиянные модули рантайма по-прежнему загружались из исходной структуры чекпоинта

Примечания:
- конфликтующие преобразования контрольных точек приводят к быстрому срабатыванию

#### transformers.fusion_mapping.register_fusion_patches[[transformers.fusion_mapping.register_fusion_patches]]

```python
transformers.fusion_mapping.register_fusion_patches(config, fusion_config: collections.abc.Mapping[str, bool | collections.abc.Mapping[str, typing.Any]] | None = None)
```

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

Зарегистрируйте запрошенные слияния времени выполнения для `cls`.

Эта функция:
- проверяет `fusion_config` по `_FUSION_REGISTRY`
- определяет включённые семейства слияний в порядке, указанном пользователем
- регистрирует monkey patches и преобразования контрольных точек перед созданием экземпляра модели

