PEFT documentation

ShadowPEFT

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.22.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ShadowPEFT

ShadowPEFT amplia um modelo base decodificador somente congelado com uma rede shadow leve e pré-treinável que executa em paralelo com o backbone. Um pequeno backbone shadow produz um estado shadow inicial s^(0), que então percorre o loop do decodificador do modelo base: em cada bloco alvo, a discrepância entre os estados ocultos do modelo base e o estado shadow é injetada de volta na entrada do bloco (uma correção de baixo rank) e o estado shadow é avançado por uma atualização residual com gate calculada a partir da saída do bloco. Apenas os componentes shadow são treinados; o modelo base permanece congelado.

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)

Como a adaptação é uma trajetória dependente da entrada no espaço de camadas (o estado sombra evolui com os dados) e não um delta estático no espaço de pesos, o ShadowPEFT não pode ser mesclado aos pesos base. Chamar merge, merge_adapter ou merge_and_unload levanta um erro explícito. Para modelos de linguagem do Transformers, você pode obter a rede sombra leve isoladamente com model.base_model.unload_shadow(), que retorna um DetachedShadowModel independente. O descarregamento independente não é suportado para modelos do Diffusers, pois a reconstrução de um denoiser completo é específica da arquitetura.

Adicionar vários adaptadores, alternar entre eles com set_adapter, excluí-los e ativá-los/desativá-los funciona da mesma forma que com outros métodos PEFT. Apenas um adaptador pode estar ativo por vez, pois o estado sombra é uma única trajetória pela rede.

O backbone de sombra pode ser construído de duas maneiras, controlado por ShadowConfig.shadow_model:

  • "mirror" (padrão): um backbone de sombra menor é criado automaticamente. Modelos de linguagem usam uma cópia reduzida da arquitetura base. Arquiteturas do Diffusers com um backend registrado usam um modelo de arquitetura semelhante, reduzido, inicializado a partir de pesos base selecionados; arquiteturas compatíveis sem um backend recorrem a um MLP residual por token. Quando o tamanho oculto da sombra difere do base, uma projeção treinada faz a ponte entre eles.
  • um id de modelo ou caminho local: o backbone é carregado como um modelo pré-treinado menor. Os modelos do Transformers usam AutoModel; os backends do Diffusers registrados definem seu próprio carregamento de checkpoint compatível.

O suporte a Diffusers com consciência da arquitetura é selecionado automaticamente a partir da classe do modelo. O Flux2 atualmente possui um backend registrado; outros modelos Diffusers compatíveis baseados em transformadores usam o fallback genérico de MLP. O unload_shadow() isolado continua sem suporte para todos os modelos Diffusers, pois a reconstrução de um denoiser completo é específica da arquitetura.

Em comparação com métodos no estilo LoRA, o ShadowPEFT adiciona mais parâmetros e computação (ele executa uma rede paralela e envolve blocos inteiros do decodificador), mas o adaptador é uma rede autossuficiente que pode ser treinada centralmente, reutilizada entre tarefas e inicializada a partir de um pequeno modelo pré-treinado. Uma perda auxiliar opcional (auxiliary_loss_weight) aplica a cabeça da tarefa ao estado inicial da sombra s^(0) e a soma à perda da tarefa, incentivando o caminho de sombra destacável a resolver a tarefa por conta própria. Para LM causal, a cabeça de saída base é reutilizada; inclua "lm_head" em modules_to_save para treiná-la e salvá-la por meio do mecanismo padrão de PEFT.

Cache de KV

ShadowPEFT suporta decodificação incremental com um cache KV dual: um para o modelo base congelado e outro para o backbone de sombra. Injetar/atualizar são locais por token, portanto um novo token só precisa do seu próprio estado de sombra s; a causalidade mantém as chaves/valores do prefixo base (calculados sob injeção) válidos. O objeto emparelhado é um ShadowCache, retornado como past_key_values quando use_cache=True. Você pode passar use_cache=True para generate() como de costume.

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 ainda funciona e reprocessa a sequência completa a cada etapa (útil para depuração).

Uso

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)

Para inicializar a espinha dorsal sombria a partir de um modelo pré-treinado menor, passe seu id ou caminho como shadow_model:

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

Avaliando o caminho de sombra

Por padrão, a saída do modelo (logits) é o modelo base adaptado por sombra: as correções de sombra são injetadas nos estados ocultos do modelo base em cada camada, de modo que logits já reflete o ShadowPEFT (use model.disable_adapter() para obter o modelo base puro para comparação). A perda auxiliar treina adicionalmente o caminho de sombra para resolver a tarefa por conta própria.

Para avaliar a rede de sombra independente de um modelo de linguagem do Transformers (o modelo destacável e leve — o análogo do ShadowPEFT para merge_and_unload), use unload_shadow(). Ele retorna head(projection(backbone(x))) como um modelo de tarefa normal que você pode avaliar como qualquer outro: para uma tarefa de LM causal, é um LM causal com capacidade de geração (suporta generate() e cache de KV), e para uma tarefa de classificação de sequência, ele agrega o último token e retorna os logits de classe. Chamar este método para um modelo do Diffusers levanta 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)

Por padrão (copy=False), o modelo retornado compartilha seus módulos com o modelo PEFT, e um backbone de sombra que compartilha os embeddings de entrada congelados da base os alcança por meio de uma referência que não é um submódulo. Isso é adequado para avaliação, mas significa que save_pretrained gravaria um checkpoint sem a tabela de embeddings. Passe copy=True quando você quiser salvar ou enviar o modelo independente:

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

Visão geral do benchmark

API

ShadowConfig

classe peft.ShadowConfig

< >

( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falsetarget_modules: list[str] | str | None = Noneexclude_modules: list[str] | str | None = Noner: int = 8shadow_alpha: float = 0.1shadow_dropout: float = 0.2init_weights: bool = Trueshadow_model: str = 'mirror'shadow_num_hidden_layers: int | None = Noneshadow_hidden_size: int | None = Noneshadow_num_attention_heads: int | None = Noneshadow_intermediate_size: int | None = Noneshare_embeddings: bool = Trueupdate_hidden_size: int | None = Noneauxiliary_loss_weight: float = 0.05layers_to_transform: list[int] | int | None = Nonelayers_pattern: list[str] | str | None = Nonemodules_to_save: list[str] | None = None )

Parâmetros

  • target_modules (Optional[Union[list[str], str]]) — Os blocos do transformer a serem envolvidos pelo mecanismo de sombra (blocos completos do decoder, não camadas lineares). Pode ser uma lista de nomes de módulos ou uma expressão regular, por exemplo, r'.*\.layers\.\d+$' para direcionar a todos os blocos do decoder. O padrão é None, caso em que todos os blocos do decoder do modelo base são envolvidos. Observe que os blocos envolvidos devem ser contíguos, pois o estado de sombra percorre o loop do decoder do primeiro bloco envolvido ao último.
  • exclude_modules (Optional[Union[list[str], str]]) — Os nomes dos módulos que não devem ser envolvidos pelo mecanismo de sombra, fornecidos como uma lista ou uma expressão regular. O valor padrão é None.
  • r (int) — O rank do gargalo de injeção de baixo rank W_down / W_up. O valor padrão é 8.
  • shadow_alpha (float) — A intensidade da correção injetada adicionada à entrada do bloco (Eq. 4). O valor padrão é 0.1.
  • shadow_dropout (float) — A probabilidade de dropout aplicada ao sinal de discrepância antes do gargalo (Eq. 3). O valor padrão é 0.2.
  • init_weights (bool) — Se deve inicializar W_up com zeros para que a injeção seja uma operação nula no início do treinamento (espelhando a convenção B=0 do LoRA). Não altere isso a menos que saiba o que está fazendo. O valor padrão é True.
  • shadow_model (str) — Como construir o backbone de sombra. "mirror" (padrão) constrói um backbone novo com a mesma arquitetura do modelo base, mas com menos/camadas menores (veja as substituições shadow_* abaixo). Arquiteturas do Diffusers com um backend Shadow registrado usam um modelo de arquitetura reduzida semelhante; outros transformers de difusão compatíveis recorrem a um MLP genérico por token. Qualquer outra string é tratada como um id de modelo ou caminho local. Um checkpoint de sombra do Transformers “projetado” (model_type == "causal_lm_with_hidden_projection", por exemplo, shadow-llm/Qwen3-0.6B-H8B) carrega seu backbone pré-treinado junto com sua projeção treinada de shadow-hidden -> base-hidden. Checkpoints explícitos do Diffusers exigem um backend registrado; atualmente, o Flux2 é suportado.
  • shadow_num_hidden_layers (Optional[int]) — A profundidade do backbone de sombra construído automaticamente ("mirror"). Para o Flux2, isso cria o número solicitado de blocos de fluxo duplo e o dobro de blocos de fluxo simples; para o fallback genérico do Diffusers, é o número de blocos MLP residuais. O padrão é None (1 camada).
  • shadow_hidden_size (Optional[int]) — O tamanho oculto do backbone de sombra construído automaticamente; pode diferir do tamanho oculto base (uma projeção é inserida automaticamente). Os backends de arquitetura podem impor restrições adicionais; as reduções do Flux2 devem preservar sua dimensão de cabeça de atenção base. O padrão é None (mesmo que o modelo base).
  • shadow_num_attention_heads (Optional[int]) — O número de cabeças de atenção da espinha dorsal de sombra construída automaticamente. O padrão é None (igual ao modelo base). Esta opção é usada por backends conscientes da arquitetura, mas não pelo fallback genérico de MLP do Diffusers.
  • shadow_intermediate_size (Optional[int]) — A largura do feed-forward da shadow backbone construída automaticamente. O padrão é None (igual ao seu tamanho oculto para o fallback genérico de MLP do Diffusers).
  • share_embeddings (bool) — Se reutilizar as embeddings de entrada congeladas da base para alimentar a espinha dorsal sombra (via inputs_embeds) em vez da própria tabela de embeddings da espinha dorsal sombra. O padrão é True.
  • update_hidden_size (Optional[int]) — A largura oculta dos MLPs de atualização T (candidato) e G (portão). O padrão é None (usa r).
  • auxiliary_loss_weight (float) — O peso lambda da perda auxiliar de sombra (Eq. 8-9) que é adicionada à perda da tarefa quando labels são passadas. Os loops de treinamento de difusão podem usar o mesmo valor para a perda de desruido desconectada. Defina como 0 para desativá-la. O valor padrão é 0.05.
  • layers_to_transform (Optional[Union[list[int], int]]) — Os índices dos blocos a serem transformados. Se uma lista for passada, o mecanismo de sombra é aplicado aos blocos nesses índices. Se um único inteiro for passado, ele é aplicado apenas nesse índice. O padrão é None (todos os blocos correspondentes são transformados).
  • layers_pattern (Optional[Union[list[str], str]]) — O nome do padrão de camada, usado apenas se layers_to_transform for diferente de None. Este é o nome do nn.ModuleList que contém os blocos do decodificador (frequentemente "layers" ou "h"). O valor padrão é None.
  • modules_to_save (Optional[list[str]]) — Os módulos extras a serem definidos como treináveis e salvos no checkpoint final (por exemplo, "lm_head" ou um classificador). O padrão é None.

Classe de configuração para ShadowModel (ShadowPEFT).

ShadowPEFT complementa um modelo base decodificador somente congelado com uma pequena rede paralela shadow treinável. Um backbone shadow produz um estado shadow inicial s^(0) que então percorre o loop do decodificador do modelo base: em cada bloco alvo, a discrepância entre os estados ocultos do modelo base e o estado shadow é injetada de volta na entrada do bloco (Eq. 2-4), e o estado shadow é avançado por uma atualização residual com gate a partir da saída do bloco (Eq. 5-7). Apenas os componentes shadow são treinados; o modelo base permanece congelado. Como a adaptação é uma trajetória dependente da entrada no espaço de camadas, em vez de um delta estático de pesos, o ShadowPEFT não pode ser mesclado aos pesos do modelo base.

ShadowModel

classe peft.ShadowModel

< >

( modelpeft_config: Union[PeftConfig, dict[str, PeftConfig]]adapter_name: strlow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None )

Cria um modelo ShadowPEFT a partir de um modelo transformers pré-treinado.

ShadowPEFT complementa um modelo base decodificador somente congelado com uma pequena rede paralela shadow treinável. Um backbone shadow produz um estado shadow inicial que percorre o loop do decodificador base; em cada bloco alvo, a discrepância entre os estados ocultos do base e o estado shadow é injetada no bloco, e o estado shadow é avançado por uma atualização residual com gate. Apenas os componentes shadow são treinados. Consulte ShadowConfig para a configuração.

O método não pode ser mesclado nos pesos base (a adaptação é uma trajetória dependente da entrada, não um delta de pesos estático); use ShadowModel.unload_shadow() para obter a rede de sombra independente.

shadow_auxiliary_loss

< >

( labels: Tensorattention_mask: torch.Tensor | None = None )

A perda de tarefa própria do caminho de sombra, CE(shadow_head(s^(0)), labels) (sem peso; forward aplica o peso).

A perda é calculada no estado sombra inicial s^(0) (a saída do backbone sombra, projetada) — exatamente o que o modelo standalone unload_shadow() calcula como head(projection(backbone(x))). É isso que torna a rede sombra destacada utilizável de forma independente; treiná-la em s^(L) (o estado final, que depende das saídas por camada do modelo base e não existe de forma standalone) deixaria o modelo destacado sem treinamento.

unload_shadow

< >

( adapter_name: str | None = Nonecopy: bool = False )

Parâmetros

  • adapter_name (str, opcional) — O adaptador cuja rede de sombra será descarregada. O padrão é o adaptador ativo.
  • copy (bool, opcional, padrão False) — Se True, faz uma cópia profunda do modelo retornado para que ele seja independente deste (usa mais memória). Se False (padrão), compartilha os módulos — semelhante a merge_and_unload, que reutiliza os módulos em vez de cloná- los. Modificar um modelo afeta o outro.

Retorne o backbone de sombra (+ head) como um modelo independente, sem o modelo base.

O análogo do ShadowPEFT para merge_and_unload: enquanto esse devolveria o modelo base com a adaptação incorporada, este devolve apenas a rede sombra leve para inferência de alta eficiência / em edge. Ele executa head(projection(backbone(x))) — as atualizações por bloco requerem as saídas da base e, portanto, não existem de forma independente. Para modelos de linguagem, o resultado se comporta como um LM causal normal (suporta generate() e cache de KV). Modelos do Diffusers não são suportados, pois a reconstrução de um denoiser completo e independente é específica para cada arquitetura de difusão.

Atribua o resultado a uma variável e use-o; com copy=False, os módulos permanecem compartilhados com este modelo.

Pass copy=True quando você pretende save_pretrained o modelo standalone. Um shadow backbone que compartilha os embeddings de entrada congelados da base (a configuração padrão "mirror") acessa-os por meio de uma referência que não é um submodule do modelo retornado, portanto um checkpoint com copy=False fica sem a tabela de embeddings; copy=True reanexa uma cópia privada e salva um checkpoint completo.

ShadowCache

classe peft.tuners.shadow.ShadowCache

< >

( base: Any = Noneshadow: Any = None )

Caches de KV em pares para decodificação incremental com ShadowPEFT.

A geração autoregressiva requer um cache do modelo base (chaves/valores calculados sob injeção de sombra) e um cache de modelo de sombra separado (para avançar o token s^(0) token a token). Esta é uma subclasse de Cache do Transformers: as operações que afetam o layout do lote ou da sequência (reset, reorder, crop, repeat e select) são aplicadas a ambos os caches, enquanto os metadados de atenção e as atualizações são delegados ao cache base. Atributos de cache desconhecidos também são delegados ao cache base para compatibilidade com implementações de cache específicas de arquitetura.

O wrapper não é compilável intencionalmente, pois os dois caches podem ter layouts de camadas e tamanhos ocultos diferentes. A conversão de tuplas legadas não é suportada, pois uma única tupla legada não pode representar ambos os caminhos. A metade sombra é desempacotada antes do forward da base e reempacotada na saída — veja os hooks de ShadowModel.

Update on GitHub