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メソッドと同様に動作します。シャドウ状態はネットワークを通過する単一の軌跡であるため、同時にアクティブなアダプターは1つだけです。

シャドウバックボーンは、ShadowConfig.shadow_modelによって制御される2つの方法で構築できます。

• "mirror"（デフォルト）：より小さいシャドウバックボーンが自動的に作成されます。言語モデルでは、ベースアーキテクチャの縮小コピーが使用されます。バックエンドが登録されているDiffusersアーキテクチャでは、選択されたベースの重みから初期化された、縮小された類似アーキテクチャのモデルが使用されます。バックエンドのない互換性のあるアーキテクチャでは、トークンごとの残差MLPにフォールバックします。シャドウの隠れ層サイズがベースと異なる場合、学習済みの射影がその差を埋めます。
• モデルIDまたはローカルパス: バックボーンは、より小さい事前学習済みモデルとして読み込まれます。TransformersモデルはAutoModelを使用し、登録済みのDiffusersバックエンドは、互換性のあるチェックポイントの読み込みを独自に定義します。

アーキテクチャ対応のDiffusersサポートは、モデルクラスから自動的に選択されます。Flux2には現在、登録されたバックエンドがあります。その他の互換性のあるtransformerベースのDiffusersモデルは、汎用のMLPフォールバックを使用します。完全なデノイザーの再構築はアーキテクチャ固有であるため、すべてのDiffusersモデルにおいて、単独のunload_shadow()はサポートされていません。

LoRA方式の手法と比較すると、ShadowPEFTはより多くのパラメータと計算量（並列ネットワークを実行し、デコーダーブロック全体をラップする）を必要としますが、アダプターは自己完結型のネットワークであり、中央で学習でき、タスク間で再利用でき、事前学習済み的小型モデルから初期化できます。任意の補助損失（auxiliary_loss_weight）は、タスクヘッドを初期シャドウ状態 s^(0) に適用し、タスク損失に追加することで、分離可能なシャドウパスが単独でタスクを解決することを促します。因果言語モデルの場合、ベースの出力ヘッドが再利用されます。標準的なPEFTメカニズムを通じてこれを学習・保存するには、modules_to_save に "lm_head" を含めてください。

KVキャッシュ

ShadowPEFT は、dual KV キャッシュによる増分デコードをサポートしています。これは、凍結されたベースモデル用とシャドウバックボーン用の2つのキャッシュです。注入/更新はトークンローカルであるため、新しいトークンには自身のシャドウ状態 s だけで十分です。因果性により、プレフィックスのベースキー/バリュー（注入下で計算されたもの）が有効に保たれます。ペアとなるオブジェクトは ShadowCache で、use_cache=True の場合、past_key_values として返されます。generate() に use_cache=True を渡すことも通常通り可能です。

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)

より小さい事前学習済みモデルからシャドウバックボーンを初期化するには、その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()を使用してください）。補助損失は、シャドウパスがタスクを単独で解決できるように訓練します。

Transformers の言語モデルにおけるスタンドアロンシャドウネットワーク（分離可能な軽量モデル — merge_and_unload の ShadowPEFT 相当）を評価するには、unload_shadow() を使用します。このメソッドは、head(projection(backbone(x))) を通常のタスクモデルとして返します。他のモデルと同様に評価できます。causal-LM タスクの場合、生成機能を持つ causal LM（generate() および KV キャッシングをサポート）となり、シーケンス分類タスクの場合、最後のトークンをプーリングしてクラス logits を返します。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