ShadowPEFT

ShadowPEFT enrichit un modèle de base décodeur uniquement, figé, avec un réseau shadow léger et pré-entraînable qui s’exécute en parallèle avec l’architecture principale. Une petite architecture principale shadow produit un état shadow initial s^(0), qui suit ensuite la boucle de décodage du modèle de base : à chaque bloc ciblé, l’écart entre les états cachés de base et l’état shadow est réinjecté dans l’entrée du bloc (une correction de rang faible), et l’état shadow est mis à jour par une mise à jour résiduelle à porte calculée à partir de la sortie du bloc. Seuls les composants shadow sont entraînés ; le modèle de base reste figé.

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)

L'adaptation étant une trajectoire dépendante des entrées dans l'espace des couches (l'état ombre évolue avec les données) et non un delta statique dans l'espace des poids, ShadowPEFT ne peut pas être fusionné dans les poids de base. L'appel de merge, merge_adapter ou merge_and_unload lève une erreur explicite. Pour les modèles de langage Transformers, vous pouvez obtenir le réseau ombre léger de manière autonome via model.base_model.unload_shadow(), qui renvoie un DetachedShadowModel indépendant. Le déchargement autonome n'est pas pris en charge pour les modèles Diffusers, car la reconstruction d'un débruiteur complet dépend de l'architecture.

L’ajout de plusieurs adaptateurs, le passage de l’un à l’autre avec set_adapter, leur suppression ainsi que leur activation/désactivation fonctionnent de la même manière que pour les autres méthodes PEFT. Un seul adaptateur peut être actif à la fois, car l’état fantôme correspond à un unique parcours à travers le réseau.

Le backbone d'ombre peut être construit de deux manières, contrôlées par ShadowConfig.shadow_model :

• "mirror" (par défaut) : un backbone d’ombre plus petit est créé automatiquement. Les modèles de langage utilisent une copie réduite de l’architecture de base. Les architectures Diffusers avec un backend enregistré utilisent un modèle d’architecture similaire réduit, initialisé à partir de poids de base sélectionnés ; les architectures compatibles sans backend basculent sur un MLP résiduel par jeton. Lorsque la taille cachée d’ombre diffère de celle de base, une projection entraînée comble l’écart.
• un identifiant de modèle ou un chemin local : le backbone est chargé en tant que modèle pré-entraîné plus petit. Les modèles Transformers utilisent AutoModel ; les backends Diffusers enregistrés définissent leur propre chargement de checkpoint compatible.

La prise en charge des Diffusers tenant compte de l’architecture est sélectionnée automatiquement à partir de la classe du modèle. Flux2 dispose actuellement d’un backend enregistré ; les autres modèles Diffusers compatibles basés sur des transformateurs utilisent le repli générique MLP. L’appel autonome de unload_shadow() reste non pris en charge pour tous les modèles Diffusers, car la reconstruction d’un débruiteur complet est spécifique à l’architecture.

Par rapport aux méthodes de type LoRA, ShadowPEFT ajoute davantage de paramètres et de calculs (il exécute un réseau parallèle et encapsule des blocs décodeurs entiers), mais l'adaptateur est un réseau autonome qui peut être entraîné de manière centralisée, réutilisé entre différentes tâches et initialisé à partir d'un petit modèle pré-entraîné. Une perte auxiliaire optionnelle (auxiliary_loss_weight) applique la tête de tâche à l'état d'ombre initial s^(0) et l'ajoute à la perte de la tâche, encourageant le chemin d'ombre détachable à résoudre la tâche de manière autonome. Pour les LM causaux, la tête de sortie de base est réutilisée ; incluez "lm_head" dans modules_to_save pour l'entraîner et l'enregistrer via le mécanisme PEFT standard.

Cache KV

ShadowPEFT prend en charge le décodage incrémental avec un cache KV dual : l’un pour le modèle de base figé et l’autre pour l’ossature d’ombre. L’injection et la mise à jour sont locales au jeton, de sorte qu’un nouveau jeton n’a besoin que de son propre état d’ombre s ; la causalité conserve la validité des clés/valeurs de préfixe de base (calculées sous injection). L’objet apparié est un ShadowCache, renvoyé en tant que past_key_values lorsque use_cache=True. Vous pouvez passer use_cache=True à generate() comme d’habitude.

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 fonctionne toujours et reprocesse la séquence complète à chaque étape (utile pour le débogage).

Utilisation

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)

Pour initialiser l'ossature d'ombre à partir d'un modèle pré-entraîné plus petit, passez son identifiant ou son chemin en tant que shadow_model :

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

Évaluation du chemin d'ombre

Par défaut, la sortie du modèle (logits) est celle du modèle de base adapté par ombre : les corrections d’ombre sont injectées dans les états cachés du modèle de base à chaque couche, de sorte que logits reflète déjà ShadowPEFT (utilisez model.disable_adapter() pour obtenir le modèle de base brut à des fins de comparaison). La perte auxiliaire entraîne en outre le chemin d’ombre à résoudre la tâche de manière autonome.

Pour évaluer le réseau d'ombre autonome d'un modèle de langage Transformers (le modèle détachable et léger — l'analogue ShadowPEFT de merge_and_unload), utilisez unload_shadow(). Il renvoie head(projection(backbone(x))) en tant que modèle de tâche standard que vous pouvez évaluer comme n'importe quel autre : pour une tâche de LM causal, il s'agit d'un LM causal capable de génération (prend en charge generate() et le cache KV), et pour une tâche de classification de séquence, il agrège le dernier jeton et renvoie les logits de classe. L'appel de cette méthode pour un modèle Diffusers lève 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)

Par défaut (copy=False), le modèle retourné partage ses modules avec le modèle PEFT, et un squelette d’ombre qui partage les embeddings d’entrée figés de la base y accède via une référence qui n’est pas un sous-module. Cela convient pour l’évaluation, mais cela signifie que save_pretrained écrirait un point de contrôle sans le tableau d’embeddings. Passez copy=True si vous souhaitez enregistrer ou publier le modèle autonome :

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

API

ShadowConfig

ShadowModel

ShadowCache