# Расширение экспортеров

`torch.export` строит граф модели, последующие этапы преобразуют этот граф, а на финальном этапе он понижается или выводится для целевого рантайма. Большинство моделей проходят этот процесс без изменений. Если в модели встречается паттерн PyTorch, который бэкенд не может обработать, экспортер применяет небольшой обходной путь на соответствующем этапе, а не редактирует саму модель.

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

## Патчи и исправления

Обходным решением может быть как заплатка (patch), так и исправление (fix). Разница между ними заключается в том, можно ли их откатить.

|              | Патч                                                                          | Исправление                                                                                   |
| ------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| Что он делает | Заменяет атрибут (операцию `torch`, внутреннюю операцию ExecuTorch или метод модели) на время экспорта | Переписывает трассированный граф или программу                                                  |
| Отменено     | Да, оригинал восстанавливается после этого                                        | Нет, он восстанавливает артефакт перед запуском следующего этапа                                |
| Зарегистрируйтесь с | `@register_patch(backend, *paths)`                                            | `@register_fx_node_fix(backend)` или `@register_fx_program_fix(backend)`               |

Оба находятся в реестре в [exporters/utils.py](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/utils.py), и экспортер устанавливает всё, что зарегистрировано для его бэкенда, на соответствующем этапе.

Обращайтесь к патчу, если проблема связана с ошибкой понижения (lowering) в одном конкретном бэкенде: отсутствием перевода в ONNX, особенностью валидации в ORT или разложением FX, которое генерирует неиспользуемую операцию. Обходное решение остаётся в экспортере, а код моделирования остаётся чистым.

Если блоки паттерна экспортируются через несколько бэкендов, например, циклы, зависящие от данных, кэши с состоянием вне `Cache` или вручную написанное внимание с разделённым циклом, исправьте модель. Однократное исправление в модели помогает всем экспортерам.

## Добавить патч

Допустим, метод модели выполняет действие, которое `torch.export` не может проследить. Метод `NllbMoeTop2Router._cast_classifier` в NLLB-MoE приводит веса классификатора к другому типу данных, что не поддаётся трассировке. Замените его на no-op на время экспорта.

Напишите фабрику, которая принимает исходный метод и возвращает его замену, а затем зарегистрируйте фабрику по точечному пути метода:

```python
from transformers.exporters.utils import register_patch

@register_patch("dynamo", "transformers.models.nllb_moe.modeling_nllb_moe.NllbMoeTop2Router._cast_classifier")
def _patch_classifier_cast(_original):
    # Replace the untraceable dtype cast with a no-op during export.
    return lambda self, *args, **kwargs: None
```

Экспортер заменяет метод перед трассировкой и восстанавливает его после, поэтому патч влияет только на экспорт. Несколько вариантов:

- Передавайте дополнительные пути, чтобы использовать один фабрика в нескольких местах вызова, например `@register_patch("dynamo", path_a, path_b)`.
- Патчите операцию `torch`, указывая на неё путь, например `@register_patch("onnx", "torch.where")`. Фабрика получает реальную операцию в качестве аргумента, поэтому замена может вызывать её.
- Если после трассировки требуется переписать граф, напишите фикс, а не патч. Механизм тот же: декорированная функция в соответствующем реестре.

## Этап ссылок

Исходный код каждого экспортера помечает свои этапы блоками комментариев вида `# ── Stage N: … ──`, поэтому структура файла соответствует этому справочнику. Обращайтесь к исходнику, чтобы узнать точные операции и классы, обрабатываемые на каждом этапе.

### DynamoExporter

Базовый экспортер выполняет один этап патча и четыре вспомогательных функции последовательно внутри `DynamoExporter.export_program` (см. [exporter_dynamo.py](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_dynamo.py)).

1. Патч сигнатуры forward: задаёт `model.forward` плоскую сигнатуру аргументов, чтобы `torch.export` не объединял входные данные в один кортеж `**kwargs`. Это внутренний механизм, а не точка расширения.
2. Патчи модели: во время трассировки заменяют нетрассируемые методы модели на эквиваленты, безопасные для экспорта. Расширяется с помощью `@register_patch("dynamo", ...)`.
3. Регистрация Pytree: зарегистрируйте каждый `Cache` и `ModelOutput`, чтобы `torch.export` мог их разворачивать и восстанавливать (обычно это происходит автоматически). Добавьте ветку в `_flatten_to_context` / `_unflatten_from_context` для типа, до которого не может добраться обход атрибутов.
4. Динамические формы: присвойте `Dim.AUTO` каждому тензору и кэшируйте лист, когда `dynamic=True`. Переопределите с помощью `DynamoConfig.dynamic_shapes`.
5. Очистка состояния: сброс атрибутов тензоров, которые модель устанавливает внутри `forward`, а `torch.export` оставляет в виде фиктивных тензоров. Для расширения добавьте имя атрибута в `_STATEFUL_CACHE_ATTRS`.

### OnnxExporter

`OnnxExporter` добавляет пять этапов вокруг `torch.onnx.export` (см. [exporter_onnx.py](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_onnx.py)). Используйте grep для поиска полного списка патчей в файле:

```bash
grep -nE "^def (_patch_|_fix_|_aten_)" src/transformers/exporters/exporter_onnx.py
```

1. Патчи для Torch: замена операций `torch`, которые экспортёр ONNX не может преобразовать напрямую. Расширяется с помощью `@register_patch("onnx", ...)`.
2. Патчи ONNX: повторное выполнение исправлений узлов после `run_decompositions`, чтобы вновь введённые узлы проверки форм были исправлены до понижения. Используется тот же реестр `@register_patch("onnx", ...)`.
3. Исправления узлов FX: переписывание узлов графа, которые экспортёр ONNX не может опустить, таких как операции alias, in-place views и мёртвые assert. Расширяется с помощью `@register_fx_node_fix("onnx")`.
4. Переводы ONNX: предоставьте собственную реализацию понижения (lowering) для операции aten, если стандартная отсутствует или содержит ошибку (например, `aten.index_put` или `aten._grouped_mm`). Добавьте функцию `_aten_*` в `_ONNX_TRANSLATION_TABLE`.
5. Исправления ONNX IR: переписать готовую программу ONNX, чтобы обойти ошибки ONNX Runtime (например, принудительно задать `TopK(sorted=True)`). Добавьте функцию `_fix_ir_*` в `_IR_FIXES`.

### ExecutorchExporter

`ExecutorchExporter` добавляет пять этапов вокруг `to_edge_transform_and_lower` и `to_executorch`, начиная с подготовки бэкенда (см. [exporter_executorch.py](https://github.com/huggingface/transformers/blob/main/src/transformers/exporters/exporter_executorch.py)).

1. Подготовка бэкенда: переместите модель на целевое устройство и dtype, а также выберите её партиционер (`prepare_for_xnnpack`, `prepare_for_cuda`). Добавьте бэкенд, зарегистрировав `prepare_for_<name>` в `_BACKEND_PREPARE`.
2. Патчи для Torch: заменяют операции `torch`, которые бэкенды ExecuTorch не поддерживают, например `split_copy`, `chunk` и `topk(k>dim)`. Расширяются с помощью `@register_patch("executorch", ...)`.
3. Патчи для ExecuTorch: замена внутренних компонентов ExecuTorch, которые вызывают сбой на валидных графах с динамической формой. Используется тот же реестр `@register_patch("executorch", ...)`.
4. Исправления программы FX: восстановление экспортированной программы, когда для исправления требуется контекст всей программы, например, расширение ограничений диапазона или заполнение отсутствующих метаданных плейсхолдеров. Расширяется с помощью `@register_fx_program_fix("executorch")`.
5. Исправления узлов FX: переписывание отдельных узлов, например, сопоставление символьных операций Python с `executorch_prim.*` или переписывание `pow` в цепочку `mul`. Расширение с помощью `@register_fx_node_fix("executorch")`.

## Добавление бэкенда

Бэкенд представляет собой подкласс `HfExporter` и конфигурацию. `export_program` отслеживает один граф и возвращает программу бэкенда с метаданными, записанными во время отслеживания, `save_program` записывает одну программу на диск, а `load_program` считывает её обратно. `~HfExporter.export` и `~HfExporter.export_for_generation` строят `ExportedModel` на их основе. Наследование от `DynamoExporter` позволяет переиспользовать его трассировку и метаданные, поэтому бэкенду остаётся только преобразовать `ExportedProgram`:

```python
from dataclasses import dataclass

from transformers.exporters import DynamoConfig, DynamoExporter, register_backend

@dataclass
class MyConfig(DynamoConfig):
    export_format: str = "my_format"

class MyExporter(DynamoExporter):
    export_format = "my_format"
    config_class = MyConfig
    program_suffix = ".bin"

    def export_program(self, model, sample_inputs, config):
        exported_program, metadata = super().export_program(model, sample_inputs, config)
        return convert(exported_program), metadata

    @classmethod
    def save_program(cls, program, path):
        program.save(path)

    @classmethod
    def load_program(cls, path):
        return load(path)

register_backend(MyExporter)
```

Чтобы вызвать его экспорты, зарегистрируйте в нём `ModelRunner`: `register_backend(MyExporter, MyRunner)`.

Затем автоклассы передают `"my_format"` им, а `ExportedModel.from_pretrained` загружает сохранённые экспорты:

```python
from transformers.exporters import AutoExportConfig, AutoHfExporter, ExportedModel

config = AutoExportConfig.from_dict({"export_format": "my_format", "dynamic": True})
exported = AutoHfExporter.from_config(config).export(model, inputs, config)
exported.save_pretrained("my-model-my_format")  # model.bin, export.json, config.json
exported.push_to_hub("my-org/my-model-my_format")

loaded = ExportedModel.from_pretrained("my-org/my-model-my_format")
```

## Известные обходные решения в исходном коде

Некоторые классы моделей сталкиваются с подтверждёнными ошибками в оптимизаторе графов `onnxscript` (сбой при свёртке констант для `SplitToSequence`, потеря инициализаторов FPN). [ONNX_DISABLE_OPTIMIZE](https://github.com/huggingface/transformers/blob/main/tests/exporters/test_export.py) отключает оптимизацию `onnxscript` для этих моделей. В каждой записи рядом с названием модели указан соответствующий upstream-баг. Ожидается, что список будет сокращаться по мере исправления ошибок upstream, поэтому новая запись должна ссылаться на конкретный upstream-баг, а не отключать оптимизацию произвольно.

[EXPORT_SKIPS](https://github.com/huggingface/transformers/blob/main/tests/exporters/test_export.py) исключает ряд классов моделей из процесса экспорта, если модель принципиально не может быть экспортирована в текущем виде (управляющие потоки, зависящие от данных, которые нельзя векторизовать, или модули, обрабатываемые как аргументы forward). Каждая запись содержит причину, указывающую на необходимое изменение на стороне модели. Ожидается, что этот список будет сокращаться, а не расти.

