ShadowPEFT

ShadowPEFT дополняет замороженную базовую модель, работающую только в режиме декодирования, лёгкой, обучаемой теневой сетью, которая работает параллельно с основным каркасом. Небольшой теневой каркас формирует начальное теневое состояние s^(0), которое затем проходит по циклу декодера базовой модели: на каждом целевом блоке расхождение между скрытыми состояниями базовой модели и теневым состоянием добавляется обратно во вход блока (низкоранговая коррекция), а теневое состояние обновляется по гейтированному остаточному обновлению, вычисленному на основе выхода блока. Обучаются только теневые компоненты; базовая модель остаётся замороженной.

Input
  ├──► Shadow backbone (small, trainable) ──► s^(0)
  └──► Base model (frozen, large)
         block_0 ◄── inject(h, s) ─► h_0 ──► update ─► s_1
         block_1 ◄── inject(h, s) ─► h_1 ──► update ─► s_2
         ...                       (the (hidden, shadow) pair rides the loop together)

Поскольку адаптация представляет собой зависящую от входных данных траекторию в пространстве слоёв (теневое состояние эволюционирует вместе с данными), а не статическую дельту в пространстве весов, ShadowPEFT не может быть объединён с базовыми весами. Вызов merge, merge_adapter или merge_and_unload приводит к явной ошибке. Для языковых моделей Transformers можно получить лёгкую теневую сеть отдельно с помощью model.base_model.unload_shadow(), что возвращает автономный DetachedShadowModel. Автономная выгрузка не поддерживается для моделей Diffusers, поскольку восстановление полного денойзера зависит от архитектуры.

Добавление нескольких адаптеров, переключение между ними с помощью set_adapter, их удаление, а также включение и отключение работают так же, как и в других методах PEFT. Одновременно может быть активен только один адаптер, поскольку теневое состояние представляет собой единственную траекторию через сеть.

Теневой базовый блок можно построить двумя способами, которые контролируются параметром ShadowConfig.shadow_model:

• "mirror" (по умолчанию): автоматически создаётся более лёгкий теневой backbone. Языковые модели используют уменьшенную копию базовой архитектуры. Архитектуры Diffusers с зарегистрированным backend используют уменьшенную модель, аналогичную архитектуре, инициализированную из выбранных базовых весов; совместимые архитектуры без backend откатываются к поэлементному residual MLP. Если размер скрытого слоя теневой модели отличается от базового, обученная проекция компенсирует эту разницу.
• идентификатор модели или локальный путь: базовая модель загружается как более мелкая предобученная модель. Модели Transformers используют AutoModel; зарегистрированные бэкенды Diffusers определяют собственную совместимую загрузку контрольных точек.

Поддержка Diffusers с учётом архитектуры выбирается автоматически на основе класса модели. Для Flux2 в настоящее время зарегистрирован отдельный бэкенд; другие совместимые трансформерные модели Diffusers используют универсальный fallback на основе MLP. Самостоятельный вызов unload_shadow() по-прежнему не поддерживается для всех моделей Diffusers, поскольку восстановление полного денойзера зависит от конкретной архитектуры.

В отличие от методов в стиле LoRA, ShadowPEFT добавляет больше параметров и вычислений (он запускает параллельную сеть и оборачивает целые блоки декодера), но адаптер представляет собой автономную сеть, которую можно обучать централизованно, переиспользовать для разных задач и инициализировать из предварительно обученной небольшой модели. Необязательный вспомогательный потерь (auxiliary_loss_weight) применяет головку задачи к начальному теневому состоянию s^(0) и добавляет её к потере задачи, побуждая отключаемый теневой путь решать задачу самостоятельно. Для каузальных LM переиспользуется базовая головка вывода; включите "lm_head" в modules_to_save, чтобы обучить и сохранить её через стандартный механизм PEFT.

Кэш KV

ShadowPEFT поддерживает инкрементальное декодирование с dual KV-кэшем: один для замороженной базовой модели и один для теневой основы. Инжекция и обновление локальны по токенам, поэтому для нового токена требуется только его собственное теневое состояние s; причинность сохраняет валидность ключей и значений префикса базовой модели (вычисленных при инжекции). Сопоставленный объект — ShadowCache, который возвращается как past_key_values, если use_cache=True. Вы можете передать use_cache=True в generate() как обычно.

out = model.generate(input_ids, max_new_tokens=32)  # dual KV cache enabled by default
# or explicitly:
out = model.generate(input_ids, use_cache=True, max_new_tokens=32)

use_cache=False по-прежнему работает и пересчитывает всю последовательность на каждом шаге (полезно для отладки).

Использование

from transformers import AutoModelForCausalLM
from peft import ShadowConfig, get_peft_model

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B")
config = ShadowConfig(r=8, shadow_num_hidden_layers=1, task_type="CAUSAL_LM")
model = get_peft_model(model, config)
model.print_healthcheck()

out = model.generate(input_ids, max_new_tokens=32)

Чтобы инициализировать теневой backbone из более мелкой предобученной модели, передайте её id или путь как shadow_model:

config = ShadowConfig(shadow_model="Qwen/Qwen3-0.6B", task_type="CAUSAL_LM")
model = get_peft_model(base_model, config)

Оценка теневой траектории

По умолчанию выход модели (logits) — это базовая модель с теневой адаптацией: теневые корректировки внедряются в скрытые состояния базовой модели на каждом слое, поэтому logits уже отражают ShadowPEFT (чтобы получить чистую базовую модель для сравнения, используйте model.disable_adapter()). Дополнительный вспомогательный loss дополнительно обучает теневой путь решать задачу самостоятельно.

Для оценки автономной теневой сети языковой модели Transformers (отделяемая, легковесная модель — аналог ShadowPEFT для merge_and_unload) используйте unload_shadow(). Она возвращает head(projection(backbone(x))) как обычную модель для задачи, которую можно оценивать так же, как любую другую: для задачи causal-LM это генерирующая causal LM (поддерживает generate() и кэширование KV), а для задачи классификации последовательности она агрегирует последний токен и возвращает классовые логиты. Вызов этого метода для модели Diffusers вызывает NotImplementedError.

shadow = model.base_model.unload_shadow()  # a DetachedShadowModel (a PreTrainedModel)
shadow.eval()
# causal LM:
out = shadow.generate(input_ids, max_new_tokens=32)
# sequence classification:
logits = shadow(input_ids=input_ids, attention_mask=attention_mask).logits  # (batch, num_labels)

По умолчанию (copy=False) возвращаемая модель разделяет свои модули с моделью PEFT, а теневой базовый блок, разделяющий замороженные входные эмбеддинги, получает к ним доступ через ссылку, которая не является подмодулем. Это нормально для оценки, но это означает, что save_pretrained запишет контрольную точку без таблицы эмбеддингов. Передайте copy=True, если вы хотите сохранить или опубликовать автономную модель:

shadow = model.base_model.unload_shadow(copy=True)
shadow.save_pretrained("standalone-shadow")

API

ShadowConfig

ShadowModel

ShadowCache