Transformers documentation

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

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

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

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

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

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

Fusion включается через from_pretrained() с параметром fusion_config:

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() использует явный аргумент fusion_config или обращается к config.fusion_config.
  2. Реестр слияний проверяет запрошенные имена слияний.
  3. Каждый включённый fusion метаинициализирует целевой класс модели, при необходимости фильтрует кандидаты модулей по имени и использует is_fusable(...) для обнаружения совместимых классов модулей.
  4. Классы для слияния регистрируются через register_patch_mapping().
  5. Правила ~WeightTransform генерируются из конфигурации, чтобы при загрузке контрольной точки веса могли быть отображены в объединённую структуру рантайма.
  6. По умолчанию save_pretrained() использует обратный путь преобразования для восстановления исходной структуры контрольной точки. Передайте save_original_format=False, чтобы сохранить преобразованную структуру времени выполнения.

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

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

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

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

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

    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.

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

Внутренний API

класс transformers.fusion_mapping.ModuleFusionSpec

< >

( )

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

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

get_empty_log

< >

( model_name: str )

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

is_fusable

< >

( module: Module )

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

make_fused_class

< >

( original_cls: type[torch.nn.Module] )

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

make_transforms

< >

( config: PretrainedConfig )

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

класс transformers.fusion_mapping.PatchEmbeddingsFusionSpec

< >

( )

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

transformers.fusion_mapping._register_module_fusion

< >

( config: PretrainedConfigfusion_name: strspec: ModuleFusionSpec )

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

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

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

Примечания:

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

transformers.fusion_mapping.register_fusion_patches

< >

( configfusion_config: collections.abc.Mapping[str, bool | collections.abc.Mapping[str, typing.Any]] | None = None )

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

Эта функция:

  • проверяет fusion_config по _FUSION_REGISTRY
  • определяет включённые семейства слияний в порядке, указанном пользователем
  • регистрирует monkey patches и преобразования контрольных точек перед созданием экземпляра модели
Update on GitHub