Transformers documentation
Картирование слияния (экспериментальная функция)
Картирование слияния (экспериментальная функция)
Fusion mapping предоставляет опциональный способ замены подмодулей модели при загрузке с сохранением исходного формата контрольной точки.
Опирается на:
- Monkey patching для замены классов модулей до создания экземпляра модели.
- Динамическая загрузка весов для сопоставления весов между исходным и объединённым форматами выполнения.
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() автоматически использует его повторно.
Как это работает
Регистрация слияния происходит до создания экземпляра модели:
- from_pretrained() использует явный аргумент
fusion_configили обращается кconfig.fusion_config. - Реестр слияний проверяет запрошенные имена слияний.
- Каждый включённый fusion метаинициализирует целевой класс модели, при необходимости фильтрует кандидаты модулей по имени и использует
is_fusable(...)для обнаружения совместимых классов модулей. - Классы для слияния регистрируются через register_patch_mapping().
- Правила
~WeightTransformгенерируются из конфигурации, чтобы при загрузке контрольной точки веса могли быть отображены в объединённую структуру рантайма. - По умолчанию save_pretrained() использует обратный путь преобразования для восстановления исходной структуры контрольной точки. Передайте
save_original_format=False, чтобы сохранить преобразованную структуру времени выполнения.
Это позволяет fusion использовать другую структуру модулей рантайма, при этом по-прежнему загружая данные из исходного формата контрольной точки и по умолчанию сохраняя их обратно в этот же формат.
Примечание: В текущем механизме monkey-patching регистрация слияния выполняется на уровне класса: один совместимый класс модуля сопоставляется с одним классом слияния.
Семейства текущих слияний
В настоящее время fusion_config поддерживает одно семейство слияний:
patch_embeddingsВключить с помощью:fusion_config = {"patch_embeddings": True}Эффект: Заменяет совместимые проекции встраивания патчей
nn.Conv3dна эквивалентные сплющенные проекцииnn.Linearво время выполнения.
Расширение отображения слияния
Чтобы добавить новое семейство слияний:
- Добавьте предикат
is_fusable. Он определяет, совместим ли обнаруженный модуль с слиянием. - При необходимости добавьте
target_modules_patterns. Это делает этап обнаружения более явным, предварительно фильтруя имена кандидатов модулей перед вызовомis_fusable(...). - Добавьте фабрику
make_fused_class. Она возвращает класс замены во время выполнения для совместимого класса модуля. - Добавьте фабрику
make_transforms, если для слиянного макета требуется конвертация контрольных точек. Она возвращает правила~WeightTransform, которые отображают веса между исходным и слиянным макетами для заданной конфигурации. - Зарегистрируйте новый
ModuleFusionSpecвfusion_mapping.py.
После регистрации новая фузия становится доступной через fusion_config.
Внутренний API
Базовый рецепт для семейства fusion.
Спецификация слияния определяет, какие модули подходят для слияния, как построить класс замены для времени выполнения и какие преобразования весов необходимы для отображения контрольных точек между исходной и слитой раскладками.
Возвращает сообщение журнала, выводимое, если не найдено ни одного совместимого модуля.
Возвращает, является ли module совместимым с данным семейством слияний.
Создайте класс замены во время выполнения для совместимого класса модуля.
Создайте преобразования весов, необходимые для загрузки и сохранения объединённой компоновки времени выполнения.
Слияние совместимых встраиваний патчей Conv3d в развёрнутые линейные проекции.
transformers.fusion_mapping._register_module_fusion
< source >( config: PretrainedConfigfusion_name: strspec: ModuleFusionSpec )
Зарегистрируйте одно семейство слияний для cls.
Эта функция обновляет два глобальных реестра, используемых при объединённой загрузке:
- реестр monkey-patching, благодаря которому совместимые классы модулей заменяются до инициализации
- маппинг конвертации чекпоинта, чтобы слиянные модули рантайма по-прежнему загружались из исходной структуры чекпоинта
Примечания:
- конфликтующие преобразования контрольных точек приводят к быстрому срабатыванию
transformers.fusion_mapping.register_fusion_patches
< source >( configfusion_config: collections.abc.Mapping[str, bool | collections.abc.Mapping[str, typing.Any]] | None = None )
Зарегистрируйте запрошенные слияния времени выполнения для cls.
Эта функция:
- проверяет
fusion_configпо_FUSION_REGISTRY - определяет включённые семейства слияний в порядке, указанном пользователем
- регистрирует monkey patches и преобразования контрольных точек перед созданием экземпляра модели