# VB-LoRA: Ajuste fino extremamente eficiente em parâmetros com bancos de vetores

## Visão geral

[VB-LoRA](https://huggingface.co/papers/2405.15179) é uma técnica de ajuste fino eficiente em parâmetros que estende o LoRA ao aprender um esquema de compartilhamento de parâmetros de granularidade fina no nível de subvetores, alcançando uma eficiência de parâmetros significativamente maior. Isso torna o VB-LoRA especialmente útil em cenários em que os custos de armazenamento e transmissão são críticos. Ele funciona decompondo matrizes de baixo rank — de diferentes camadas e módulos, como K, Q, V e FFN — em subvetores, que são então compartilhados globalmente por meio de um banco de vetores.

O resumo do artigo é:

*Com o aumento da adoção de modelos de linguagem de grande escala e a crescente necessidade de personalização de modelos por usuário ou por tarefa, os métodos de ajuste fino eficiente em parâmetros (PEFT), como a adaptação de baixo rank (LoRA) e suas variantes, incorrem em custos substanciais de armazenamento e transmissão. Para reduzir ainda mais os parâmetros armazenados, introduzimos um paradigma de "dividir e compartilhar" que quebra as barreiras da decomposição de baixo rank entre dimensões de matriz, módulos e camadas, compartilhando parâmetros globalmente por meio de um banco de vetores. Como uma instância desse paradigma para LoRA, nosso VB-LoRA proposto compõe todas as matrizes de baixo rank da LoRA a partir de um banco de vetores compartilhado com um módulo de mistura top-k diferenciável. O VB-LoRA atinge uma eficiência extrema de parâmetros, mantendo desempenho comparável ou superior em relação aos métodos PEFT mais avançados. Experimentos extensos demonstram a eficácia do VB-LoRA em tarefas de compreensão de linguagem natural, geração de linguagem natural e ajuste fino por instruções. Ao ajustar o modelo Llama2-13B, o VB-LoRA utiliza apenas 0,4% dos parâmetros armazenados da LoRA, e ainda assim alcança resultados superiores.*

## Dicas de uso

- O VB-LoRA utiliza um módulo sparse top-k para aprender o mecanismo de compartilhamento. Ao salvar os parâmetros do adaptador, você pode salvar apenas os pesos top-k e seus índices definindo `save_only_topk_weights = True` em `VBLoRAConfig`, ou salvar todos os logits treináveis definindo-o como `False`. Habilitar `save_only_topk_weights = True` reduz significativamente o espaço de armazenamento; por exemplo, no Llama2-7B, o tamanho do arquivo de armazenamento diminui de 308MB para 2,5MB. Observe que os modelos salvos com `save_only_topk_weights = True` são destinados apenas para mesclagem ou inferência e não podem ser usados para retomar o treinamento.

- VB-LoRA possui dois conjuntos de parâmetros de treinamento: parâmetros do banco de vetores e parâmetros de logit. Na prática, observamos que os parâmetros de logit exigem uma taxa de aprendizado mais alta, enquanto os parâmetros do banco de vetores exigem uma taxa de aprendizado mais baixa. Ao usar o otimizador AdamW, as taxas de aprendizado típicas são 0.01 para logits e 0.001 para os parâmetros do banco de vetores.

## Visão geral do benchmark

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

# API

## VBLoRAConfig[[peft.VBLoRAConfig]]

#### peft.VBLoRAConfig[[peft.VBLoRAConfig]]

```python
peft.VBLoRAConfig(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 = 4, num_vectors: int = 256, vector_length: int = 256, topk: int = 2, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, save_only_topk_weights: bool = False, vblora_dropout: float = 0.0, fan_in_fan_out: bool = False, bias: str = 'none', modules_to_save: Optional[list[str]] = None, init_vector_bank_bound: float = 0.02, init_logits_std: float = 0.1, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None)
```

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

**Parâmetros:**

r (`int`) : O rank das matrizes incrementais.

num_vectors (`int`) : Número de vetores no banco de vetores. Use valores maiores quando o tamanho do modelo aumentar.

vector_length (`int`) : O comprimento dos vetores no banco de vetores. O comprimento dos vetores deve ser divisível pela dimensão oculta do modelo.

topk (`int`) : O valor de K para a seleção top-K. Um valor de K maior aumenta o tamanho do modelo salvo. Na prática, definir K=2 geralmente fornece o melhor desempenho e eficiência de parâmetros. Para mais detalhes, consulte a discussão no artigo.

target_modules (`Union[List[str], str]`) : Os nomes dos módulos aos quais o adaptador será aplicado. Se especificado, apenas os módulos com os nomes especificados serão substituídos. Ao passar uma string, uma correspondência de expressão regular será realizada. 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. Se especificado como 'all-linear', todos os módulos lineares/Conv1D serão selecionados, excluindo a camada de saída. Se não especificado, os módulos serão selecionados de acordo com a arquitetura do modelo. Se a arquitetura não for conhecida, um erro será lançado -- nesse caso, você deve especificar os módulos de destino manualmente.

exclude_modules (`Optional[Union[List[str], str]]`) : Os nomes dos módulos aos 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.

save_only_topk_weights (`bool`) : Se deve salvar apenas os pesos topk. Definir `save_only_topk_weights = True` reduz significativamente o espaço de armazenamento. No entanto, modelos salvos neste modo podem ser usados apenas para mesclagem ou inferência, não para retomar o treinamento.

vblora_dropout (`float`) : A probabilidade de dropout para as camadas VBLoRA.

fan_in_fan_out (`bool`) : Defina como True se a camada a ser substituída armazena pesos como (fan_in, fan_out). Por exemplo, o gpt-2 usa `Conv1D`, que armazena pesos como (fan_in, fan_out), e portanto isso deve ser definido como `True`.

bias (`str`) : Tipo de viés para VBLoRA. Pode ser 'none', 'all' ou 'vblora_only'. Se for 'all' ou 'vblora_only', os vieses correspondentes serão atualizados durante o treinamento. Tenha em mente que isso significa que, mesmo ao desativar os adaptadores, o modelo não produzirá a mesma saída que o modelo base teria sem adaptação.

modules_to_save (`List[str]`) : Lista de módulos, exceto as camadas VBLoRA, que devem ser configurados como treináveis e salvos no checkpoint final.

init_vector_bank_bound (`float`) : O banco de vetores é inicializado com uma distribuição uniforme entre -init_vector_bank_bound e init_vector_bank_bound. Evite inicializar o banco de vetores com todos os zeros para prevenir gradientes nulos. Um valor pequeno, como 0.02, é tipicamente eficaz. Inicializar com um valor grande pode causar instabilidade no treinamento.

init_logits_std (`float`) : Os logits são inicializados com uma distribuição normal com desvio padrão de init_logits_std. O padrão é 0.1.

layers_to_transform (`Union[List[int],int]`) : Os índices das camadas a serem transformadas. Se uma lista de inteiros for passada, o adaptador será aplicado aos índices das camadas especificados nessa lista. Se um único inteiro for passado, as transformações serão aplicadas à camada nesse índice.

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

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

Artigo: https://huggingface.co/papers/2405.15179

## VBLoRAModel[[peft.VBLoRAModel]]

#### peft.VBLoRAModel[[peft.VBLoRAModel]]

```python
peft.VBLoRAModel(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/vblora/model.py#L29)

**Parâmetros:**

model ([PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel)) : O modelo a ser adaptado.

config ([VBLoRAConfig](/docs/peft/v0.22.0/pt/package_reference/vblora#peft.VBLoRAConfig)) : A configuração do modelo VBLoRA.

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

low_cpu_mem_usage (`bool`, `optional`, padrão `False`) : Cria pesos de adaptador vazios no dispositivo meta. Útil para acelerar o processo de carregamento.

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

O modelo VBLoRA.

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

O método é descrito em detalhes em https://huggingface.co/papers/2405.15179.

Exemplo:

```py
>>> from transformers import AutoModelForCausalLM
>>> from peft import VBLoRAConfig, get_peft_model

>>> base_model = AutoModelForCausalLM.from_pretrained("facebook/opt-125m")
>>> config = VBLoRAConfig(
...     task_type="SEQ_CLS",
...     r=4,
...     target_modules=["fc1", "fc2", "k_proj", "out_proj", "q_proj", "v_proj"],
...     num_vectors=60,
...     vector_length=256,
...     save_only_topk_weights=True,
... )
>>> model = get_peft_model(base_model, config)
```

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

#### get_nb_savable_parameters[[peft.VBLoRAModel.get_nb_savable_parameters]]

```python
get_nb_savable_parameters(adapter = 'default')
```

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

Retorna o número de parâmetros VB-LoRA salváveis e outros parâmetros salváveis.

#### print_savable_parameters[[peft.VBLoRAModel.print_savable_parameters]]

```python
print_savable_parameters()
```

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

Imprime o número de parâmetros VB-LoRA salváveis e o total de parâmetros salváveis.

