# Lily: Adaptação Interconectada de Baixo Rango entre Camadas

[Lily](https://huggingface.co/papers/2407.09946) é uma técnica de ajuste fino eficiente em parâmetros que introduz o compartilhamento de pesos entre camadas para as matrizes de adaptador. Em vez de aprender um par AB independente por camada, como no LoRA, o Lily usa **adaptadores A compartilhados localmente** (cada A é compartilhado entre um bloco de `stride_A` camadas consecutivas) e **especialistas B compartilhados globalmente** (um pequeno conjunto de `num_B` adaptadores B é compartilhado entre todas as camadas). Em cada passagem de frente, um roteador leve e dependente dos dados calcula uma combinação ponderada por softmax dos especialistas B para produzir o B efetivo para aquela camada e entrada.

Esse compartilhamento pode reduzir o número total de matrizes de adaptador de `2N` (LoRA padrão) para `N / stride_A + num_B`, liberando o orçamento de parâmetros para usar um **rank muito maior `r`** — tipicamente `2×`–`4×` do que você usaria no LoRA. Um rank maior e uma melhor interconectividade aumentam o rank efetivo da atualização de pesos `ΔW = A × combined_B`, resultando em um melhor desempenho de adaptação.

Como a combinação B é **dependente dos dados** (os pesos do roteador dependem das ativações de entrada em tempo de execução), `merge` e `unmerge` **não são suportados**. Se a mesclagem de pesos for necessária para sua implantação, considere outros métodos, como LoRA.

Atualmente, a Lily possui as seguintes restrições adicionais:
- Apenas camadas `nn.Linear` são suportadas.
- Camadas quantizadas não são suportadas.

Se essas restrições não funcionarem para o seu caso de uso, considere outros métodos.

O resumo do artigo é:

> A adaptação de baixo posto (LoRA) é um método amplamente utilizado de ajuste fino eficiente em parâmetros (PEFT) que aprende atualizações de pesos ΔW = AB para pesos pré-treinados W por meio de adaptadores de baixo posto A e B. Embora o LoRA garanta eficiência de hardware, suas atualizações de pesos de baixo posto limitam o desempenho da adaptação. Neste artigo, propomos a adaptação interconectada de baixo posto entre camadas (Lily), um novo método PEFT que introduz um framework interconectado com especialistas A compartilhados localmente e B compartilhados globalmente. Essa estrutura elimina pares AB redundantes por camada, permitindo ΔW de posto mais alto com o mesmo número ou menos parâmetros. Para aprimorar a expressividade, usamos roteadores dependentes de dados para determinar as interconexões A-B, impedindo que os especialistas B converjam para o mesmo comportamento e melhorando o poder representacional entre domínios. Experimentos em diferentes modalidades, arquiteturas e tamanhos de modelo demonstram o desempenho e a eficiência superiores da Lily.

## Visão geral do benchmark

<iframe src="https://peft-internal-testing-peft-method-comparison-embed.hf.space/?highlight[type]=LILY" frameborder="0" width="850" height="1000"
>

# API

## LilyConfig[[peft.LilyConfig]]

#### peft.LilyConfig[[peft.LilyConfig]]

```python
peft.LilyConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, r: int = 32, stride_A: int = 1, num_B: int = 2, scaling: float = 1.0, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, modules_to_save: Optional[list[str]] = None, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None, init_weights: bool = True)
```

[Fonte](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/lily/config.py#L24)

**Parâmetros:**

r (`int`) : O rank da Lily. Determina a dimensão oculta interna de cada adaptador e o rank da atualização de pesos `A @ B`. Na Lily, como o número de adaptadores é tipicamente menor do que no LoRA, cada adaptador precisa carregar mais capacidade, portanto, recomenda-se usar um `r` maior do que no LoRA — tipicamente `2x`, `3x` ou `4x` o rank do LoRA que você usaria normalmente. O número total de parâmetros treináveis escala com `r * (total_layers / stride_A + num_B)`, então aumentar `r` mantendo `stride_A` grande e `num_B` pequeno é o compromisso recomendado.

stride_A (`int`) : O número de camadas consecutivas que compartilham um adaptador A. Por exemplo, se `stride_A=4`, a cada 4 camadas adjacentes compartilham o mesmo adaptador A, resultando em `total_layers / stride_A` adaptadores A distintos no total. O adaptador A comprime a entrada em uma representação de baixo posto de tamanho `r`. `stride_A` deve ser no mínimo 1. Valores sugeridos: `2`, `3` ou `4` (ou seja, compartilhando a cada 2, 3 ou 4 camadas). Manter `stride_A` grande (menos adaptadores A distintos) e aumentar `r` em vez disso leva a um melhor desempenho do que o compromisso oposto (pequeno `stride_A`, pequeno `r`). Definir `stride_A=1` significa que cada camada tem seu próprio adaptador A. NOTA: o compartilhamento de A ocorre dentro de cada alvo (camadas com o mesmo sufixo de alvo). Por exemplo, se seus target_modules forem `['q_proj', 'v_proj']` e você definir `stride_A=2`, então a cada 2 camadas adjacentes de q_proj compartilharão um adaptador A, e a cada 2 camadas adjacentes de v_proj compartilharão outro adaptador A, mas as camadas de q_proj e v_proj não compartilharão adaptadores A entre si, pois têm sufixos diferentes.

num_B (`int`) : O número de adaptadores B compartilhados. Diferentemente dos adaptadores A (que são agrupados por camada), todos os adaptadores B são compartilhados globalmente entre todas as camadas. Para cada passagem para frente, um roteador calcula uma combinação ponderada de todos os `num_B` adaptadores B (usando pesos normalizados por softmax) para produzir um único adaptador B combinado, que então projeta a representação de baixo posto de volta para a dimensão original. Recomenda-se definir `num_B` para uma ordem de grandeza semelhante à de `total_layers / stride_A`. Valores sugeridos: `total_layers / 2`, `total_layers / 3` ou `total_layers / 4`. Assim como com `stride_A`, prefira um `num_B` menor com um `r` maior em vez de um `num_B` maior com um `r` menor. NOTA: para treinar o roteador, são necessários pelo menos 2 adaptadores B (ou seja, `num_B >= 2`), pois o roteador aprende a calcular uma combinação ponderada dos adaptadores B. NOTA: o compartilhamento de B ocorre dentro de cada alvo (camadas com o mesmo sufixo de alvo). Por exemplo, se seus target_modules forem `['q_proj', 'v_proj']` e você definir `num_B=4`, haverá 4 adaptadores B compartilhados entre todas as camadas q_proj e outros 4 adaptadores B compartilhados entre todas as camadas v_proj, mas as camadas q_proj e v_proj não compartilharão adaptadores B entre si, pois possuem sufixos diferentes.

target_modules (`Union[List[str], str]`, *opcional*) : Os nomes dos módulos aos quais aplicar o Lily. Pode ser uma lista de strings com nomes de módulos (por exemplo, `['q_proj', 'v_proj']`) ou um padrão de expressão regular (por exemplo, `'.*decoder.*(SelfAttention|EncDecAttention).*(q|v)$'`). Se não for especificado, o Lily será aplicado a todas as camadas lineares suportadas.

scaling (`float`) : Um multiplicador escalar aplicado à saída combinada do adaptador (`scaling * A @ combined_B`) antes de adicioná-la à passagem para frente do peso congelado. Diferentemente do LoRA, o Lily não utiliza uma formulação `alpha / r`; em vez disso, `scaling` é um multiplicador direto. Esse design torna simples varrer valores em uma escala logarítmica (por exemplo, `0.01`, `0.1`, `1.0`, `10.0`). O valor ótimo depende da tarefa e deve ser tratado como um hiperparâmetro. Recomendamos começar com `1.0`.

modules_to_save (`List[str]`, *opcional*) : Lista de módulos, além das camadas do Lily, que devem ser configurados como treináveis e salvos no checkpoint final. Por exemplo, em tarefas de Classificação de Sequência ou Classificação de Tokens, a camada final `classifier/score` é inicializada aleatoriamente e, portanto, precisa ser treinável e salva.

exclude_modules (`Union[List[str], str]`, *opcional*) : Os nomes dos módulos para os quais o adaptador não deve ser aplicado. Ao passar uma string, será realizada uma correspondência por regex. Ao passar uma lista de strings, será realizada uma correspondência exata ou será verificado se o nome do módulo termina com qualquer uma das strings passadas.

layers_to_transform (`Union[list[int], int]`, *opcional*) : Os índices das camadas a serem transformadas. Se este argumento for especificado, o PEFT transformará apenas os índices das camadas especificados dentro desta lista. Se um único inteiro for passado, o PEFT transformará apenas a camada neste índice.

layers_pattern (`Optional[Union[List[str], str]]`, *opcional*) : O nome do padrão da camada, usado apenas se `layers_to_transform` for diferente de None e se o padrão da camada não estiver no padrão de camadas comuns. Isso deve apontar para o `nn.ModuleList` do modelo, que frequentemente é chamado de `'layers'` ou `'h'`.

init_weights (`bool`) : Se as pesos do adaptador Lily devem ser inicializados usando o esquema de inicialização padrão: as matrizes A são inicializadas com Kaiming uniform, e as matrizes B são inicializadas com zero, garantindo que a saída do adaptador seja zero no início do treinamento e não perturbe o modelo pré-treinado. É fortemente recomendado manter isso como `True`, a menos que você tenha um motivo específico para alterá-lo.

Esta é a classe de configuração para armazenar a configuração de um [LilyModel](/docs/peft/v0.22.0/pt/package_reference/lily#peft.LilyModel).

## LilyModel[[peft.LilyModel]]

#### peft.LilyModel[[peft.LilyModel]]

```python
peft.LilyModel(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[Fonte](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/lily/model.py#L30)

**Parâmetros:**

model (`torch.nn.Module`) : O modelo a ser adaptado.

config ([LilyConfig](/docs/peft/v0.22.0/pt/package_reference/lily#peft.LilyConfig)) : A configuração do modelo Lily.

adapter_name (`str`) : O nome do adaptador, padrão é `"default"`.

**Retorna:** `torch.nn.Module`

O modelo PEFT da Lily.

Cria um modelo Low-Rank Interconnected Adaptation Across Layers (Lily) a partir de um modelo transformers pré-treinado.

O método é descrito em detalhes em https://arxiv.org/abs/2407.09946.

**Atributos**:
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel)) -- O modelo a ser adaptado.
- **peft_config** ([LilyConfig](/docs/peft/v0.22.0/pt/package_reference/lily#peft.LilyConfig)): A configuração do modelo Lily.

