Adapter layers (адаптерные слои)

Adapter layers (адаптерные слои) — это небольшие обучаемые модули, которые вставляют внутрь слоёв предобученной модели, обычно Transformer, чтобы адаптировать её под новую задачу без обновления всех исходных весов. В узком смысле термин чаще означает классические bottleneck adapters; в более широком — любые методы parameter-efficient fine-tuning (PEFT), но это зависит от библиотеки и контекста.

На практике это способ дообучать одну и ту же базовую модель под разные задачи, сохраняя отдельные небольшие адаптеры вместо полной копии весов. По состоянию на 2026-08-15 два основных официальных экосистемных контекста для этого термина — AdapterHub/adapters и Hugging Face PEFT.

Английский термин: adapter layers. Также встречается: adapters, adapter modules, bottleneck adapters, PEFT methods. Важная оговорка: в документации AdapterHub слово adapter используется широко и может означать любой метод эффективного дообучения, если не указано иное; поэтому всегда проверяйте, говорится ли именно о классических bottleneck-адаптерах.

Простыми словами

Грубо говоря, adapter layers можно представить как сменные насадки для одной и той же модели. У вас есть большая предобученная система, и вместо того чтобы каждый раз перенастраивать весь механизм, вы добавляете маленький специализированный блок, который подстраивает поведение под конкретную задачу.

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

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

В классическом варианте bottleneck adapters в каждый слой Transformer добавляют небольшой feed-forward модуль. В документации AdapterHub он описывается как последовательность: понижение размерности (down-projection) → нелинейность → повышение размерности (up-projection) → сложение с исходным представлением через residual connection.

Скрытое состояние слоя h
        |
        v
[основной Transformer-слой]
        |
        +-------------------------------+
        |                               |
        |  adapter module               |
        |  down-projection              |
        |        -> non-linearity       |
        |        -> up-projection       |
        +---------------+---------------+
                        |
                        v
             residual addition с h
                        |
                        v
                выход слоя

Ключевая идея в том, что основные веса предобученной модели остаются фиксированными, а обучаются только параметры адаптера. В AdapterHub официальный workflow для этого выглядит так: вы добавляете адаптер, вызываете train_adapter(), и библиотека замораживает все веса модели, кроме весов адаптера. Для использования адаптера в прямом проходе применяется set_active_adapters().

В более широком современном смысле слово «адаптеры» часто включает и другие PEFT-методы. В текущей интеграции Hugging Face Transformers через PeftAdapterMixin поддерживаются непromptовые методы вроде LoRA, IA3 и AdaLoRA, а prompt-based подходы, включая prompt tuning и prefix tuning, требуют прямого использования библиотеки PEFT.

Что важно понять: не каждый «adapter» в сегодняшних библиотеках — это буквально новый bottleneck-слой. Иногда это просто зонтичное название для экономного дообучения.

Где применяется

• Несколько задач на одной базе. Вы можете держать одну предобученную модель и подключать к ней разные адаптеры под разные сценарии, не создавая полную обученную копию модели для каждого случая.
• Модульное переключение поведения. В AdapterHub адаптер нужно явно активировать через set_active_adapters(); в PEFT после загрузки адаптер тоже не считается автоматически активным и включается через PeftModel.set_adapter().
• Лёгкие checkpoint-файлы. В PEFT при save_pretrained() сохраняются файлы адаптера — adapter_model.safetensors или adapter_model.bin, adapter_config.json и README.md. Базовая модель внутрь такого checkpoint не входит, поэтому для загрузки она всё равно нужна отдельно.
• Сравнение разных семейств PEFT. Если вам нужно проверить, лучше ли для вашей задачи классический bottleneck-адаптер или один из современных PEFT-подходов, обе официальные экосистемы дают для этого понятную отправную точку: AdapterHub — для классических adapter workflows, PEFT — для более широкого набора методов.

Это тесно связано с переносом обучения: вы не обучаете модель с нуля, а экономно адаптируете уже готовую основу. Оценивать результат всё равно нужно метриками конкретной задачи; рядом с этой темой часто обсуждают и перплексию, но одной метрики обычно недостаточно для выводов о практической полезности адаптера.

Практический пример

Ниже — схематичный workflow по официальной логике AdapterHub для классического адаптера. Это не полный скрипт под конкретную модель, а минимальная последовательность шагов, которую прямо подтверждает документация.

model = ...  # ваша предобученная Transformer-модель

model.add_adapter("legal_domain")
model.train_adapter("legal_domain")
# После этого обучаемыми остаются только веса адаптера,
# а остальные веса модели замораживаются.

model.set_active_adapters("legal_domain")
# Теперь прямой проход использует выбранный адаптер.

# Дальше вы запускаете обычный цикл обучения на своей задаче.

Если вы работаете через Hugging Face PEFT, текущая документация рекомендует создать конфигурацию PEFT, получить обучаемую модель через get_peft_model() и проверить объём обучаемых параметров через print_trainable_parameters(). Для интеграции прямо в Transformers используется PeftAdapterMixin; там также показан workflow с конфигурацией вроде LoraConfig и add_adapter().

Практический вердикт: если вам нужны именно классические bottleneck-адаптеры, композиция адаптеров и AdapterHub-style workflows, начинайте с AdapterHub/adapters. Если вам нужен широкий современный набор PEFT-методов, включая LoRA, IA3, AdaLoRA и DoRA, чаще удобнее смотреть в сторону Hugging Face PEFT.

Чем отличается от близких терминов

Ограничения и заблуждения

• Заблуждение: «adapter layers» — всегда один и тот же механизм. Нет. В литературе и библиотеках термин используется неодинаково: иногда строго про bottleneck adapters, иногда про PEFT в целом.
• Заблуждение: достаточно сохранить один адаптер, и базовая модель больше не нужна. Нет. Официальная документация PEFT прямо указывает, что adapter state dict не включает базовую модель; она нужна отдельно при загрузке.
• Заблуждение: после загрузки адаптер уже активен. В PEFT загруженный адаптер не активируется автоматически; для этого нужен PeftModel.set_adapter(). В AdapterHub используется set_active_adapters().
• Ограничение интеграций. Текущий PeftAdapterMixin в Transformers покрывает только непpromptовые PEFT-методы. Если вам нужен prompt tuning или prefix tuning, придётся работать с библиотекой PEFT напрямую.
• Ограничение окружения. Для adapter-hub/adapters официальный репозиторий указывает Python 3.9+ и PyTorch 2.0+. В текущем setup.py ветки huggingface/peft указано требование Python 3.10+.

Редакционное ограничение: официальные документы хорошо описывают механику и API, но не дают универсального ответа, какой вид адаптера «лучше» для любой задачи. Если вам нужен выбор между bottleneck adapters, LoRA и другими PEFT-методами, придётся опираться на ваши данные, модель и собственную валидацию.

Связанные термины и инструменты

• Transfer learning (перенос обучения) — более общий принцип, в который вписываются адаптеры.
• Perplexity (перплексия) — одна из метрик, которую часто обсуждают рядом с языковыми моделями и дообучением.
• AI Safety (безопасность ИИ) — область, где модульная адаптация поведения модели может быть практически полезна, но сама по себе не гарантирует безопасность.
• RLAIF — другой класс пост-обучения, который решает иные задачи, чем adapter layers.
• Инструменты: AdapterHub/adapters и Hugging Face PEFT — две основные официальные библиотеки, определяющие современный практический контекст термина.

Источники

• Releases · adapter-hub/adapters · GitHub
• PEFT · Hugging Face
• Releases · huggingface/peft · GitHub

• Overview and Configuration — AdapterHub documentation
• Adapter Methods — AdapterHub documentation
• Adapter Training — AdapterHub documentation
• AdapterHub: A Framework for Adapting Transformers – ACL Anthology
• Adapters: A Unified Library for Parameter-Efficient and Modular Transfer Learning – ACL Anthology
• Parameter-efficient fine-tuning · Hugging Face
• Quicktour · Hugging Face
• Models · Hugging Face
• PEFT checkpoint format · Hugging Face
• GitHub – adapter-hub/adapters
• peft/setup.py at main · huggingface/peft · GitHub

Вопросы и ответы

Adapter layers и LoRA — это одно и то же?

Нет. В узком смысле adapter layers — это классические bottleneck-модули внутри слоёв Transformer. LoRA в текущих официальных документах рассматривается как отдельный PEFT-метод, хотя в широком разговорном смысле оба подхода могут попасть под слово «адаптеры».

Нужно ли хранить базовую модель отдельно от адаптера?

Да. По документации PEFT, checkpoint адаптера не содержит базовую модель, поэтому для загрузки и использования PEFT-модели исходная база остаётся необходимой.

Почему после загрузки адаптер не влияет на вывод?

Частая причина — адаптер не активирован. В AdapterHub используйте set_active_adapters(), а в PEFT — PeftModel.set_adapter().

Что выбрать: AdapterHub/adapters или Hugging Face PEFT?

Если вам нужен классический bottleneck-подход и экосистема AdapterHub, логично начинать с adapters. Если важен широкий выбор современных PEFT-методов, включая LoRA, IA3, AdaLoRA и prompt-based подходы, обычно практичнее смотреть на PEFT.

Поддерживаются ли prompt tuning и prefix tuning через Transformers PeftAdapterMixin?

Нет. Текущая документация Transformers указывает, что PeftAdapterMixin покрывает непpromptовые методы, а prompt tuning и prefix tuning требуют работы с библиотекой PEFT напрямую.