ShadowPEFT

ShadowPEFT는 동결된 base decoder-only 모델에 경량이고 사전 학습 가능한 shadow 네트워크를 추가하여 백본과 병렬로 실행되도록 합니다. 작은 shadow 백본이 초기 shadow 상태 s^(0)를 생성하며, 이 상태는 base 모델의 decoder 루프를 따라 이동합니다. 각 대상 블록에서 base hidden states와 shadow 상태 간의 차이를 블록 입력에 주입(저랭크 보정)하고, 블록 출력에서 계산된 게이트드 잔차 업데이트로 shadow 상태를 진행시킵니다. shadow 구성 요소만 학습되며, base 모델은 동결된 상태로 유지됩니다.

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 방법과 동일하게 작동합니다. 네트워크를 통한 단일 궤적(single trajectory)인 shadow state가 하나만 존재하기 때문에, 한 번에 하나의 어댑터만 활성화될 수 있습니다.

Shadow backbone은 ShadowConfig.shadow_model으로 제어되는 두 가지 방식으로 구축할 수 있습니다:

• "mirror" (기본값): 더 작은 shadow backbone이 자동으로 생성됩니다. 언어 모델은 기본 아키텍처의 축소된 복사본을 사용합니다. 등록된 백엔드가 있는 Diffusers 아키텍처는 선택된 기본 가중치로 초기화된 축소된 유사 아키텍처 모델을 사용하며, 백엔드가 없는 호환 아키텍처는 토큰 단위 residual MLP로 대체됩니다. shadow hidden size가 기본값과 다르면 학습된 projection이 이 차이를 연결합니다.
• 모델 ID 또는 로컬 경로: 백본은 더 작은 사전 학습된 모델로 로드됩니다. Transformers 모델은 AutoModel을 사용하며, 등록된 Diffusers 백엔드는 자체 호환 체크포인트 로딩을 정의합니다.

Architecture-aware Diffusers 지원은 모델 클래스에서 자동으로 선택됩니다. Flux2에는 현재 등록된 백엔드가 있으며, 기타 호환되는 transformer 기반 Diffusers 모델은 범용 MLP 폴백을 사용합니다. 완전한 denoiser를 재구성하는 것은 아키텍처에 따라 다르기 때문에, 모든 Diffusers 모델에서 독립적인 unload_shadow()는 여전히 지원되지 않습니다.

LoRA 방식의 방법론과 비교하면, ShadowPEFT는 더 많은 매개변수와 계산량이 필요합니다(병렬 네트워크를 실행하고 전체 디코더 블록을 래핑하기 때문). 그러나 어댑터는 중앙에서 학습할 수 있고, 작업 간에 재사용할 수 있으며, 사전 학습된 소형 모델에서 초기화할 수 있는 자체 완결형 네트워크입니다. 선택적인 보조 손실(auxiliary_loss_weight)은 작업 헤드를 초기 섀도 상태 s^(0)에 적용하여 작업 손실에 더함으로써, 분리 가능한 섀도 경로가 자체적으로 작업을 해결하도록 장려합니다. 인과적 LM의 경우, 기본 출력 헤드가 재사용됩니다. 표준 PEFT 메커니즘을 통해 이를 학습하고 저장하려면 modules_to_save에 "lm_head"를 포함하세요.

KV 캐시

ShadowPEFT는 dual KV 캐시를 통한 증분 디코딩을 지원합니다. 하나는 동결된 베이스 모델용이고, 다른 하나는 shadow backbone용입니다. Inject/update는 토큰 로컬(token-local)이므로, 새로운 토큰은 자신의 shadow 상태 s만 필요로 합니다. 인과성(causality) 덕분에 prefix의 base 키/값(injection 하에 계산된 것)이 유효하게 유지됩니다. 페어링된 객체는 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)

더 작은 사전 학습된 모델에서 shadow backbone을 초기화하려면, 해당 모델의 id 또는 경로를 shadow_model로 전달하세요:

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

섀도 경로 평가

기본적으로 모델 출력(logits)은 shadow-adapted base model입니다. shadow 보정이 모든 레이어의 base model hidden states에 주입되므로 logits에는 이미 ShadowPEFT가 반영되어 있습니다(비교를 위해 순수한 base model을 얻으려면 model.disable_adapter()를 사용하세요). 보조 손실(auxiliary loss)은 shadow path가 자체적으로 작업을 해결하도록 추가 학습을 수행합니다.

Transformers 언어 모델의 독립형 shadow network(분리 가능한 경량 모델 — merge_and_unload의 ShadowPEFT 대응물)를 평가하려면 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 모델과 모듈을 공유하며, 동결된 기본 입력 임베딩을 공유하는 shadow backbone은 서브모듈이 아닌 참조를 통해 해당 모듈에 도달합니다. 이는 평가에는 문제가 없으나, save_pretrained를 호출하면 임베딩 테이블이 없는 체크포인트가 작성됨을 의미합니다. 독립적인 모델을 저장하거나 push하려면 copy=True를 전달하세요:

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

벤치마크 개요

API

ShadowConfig

ShadowModel

ShadowCache