# GraLoRA

[**Granular Low-Rank Adaptation (GraLoRA)**](https://huggingface.co/papers/2505.20355) é um método PEFT projetado para aprimorar a **expressividade** da adaptação de baixo rank, ao mesmo tempo em que melhora a **robustez a outliers** nas ativações, com base em insights de problemas bem conhecidos na quantização.

![GraLoRA Overview](https://github.com/SqueezeBits/GraLoRA/raw/main/figure/gralora_overview.png)

Diferentemente do LoRA padrão, que aplica um único adaptador de baixo rank em todo o espaço de características, o GraLoRA introduz um esquema de adaptação estruturado e de granularidade fina. Ele divide o espaço de adaptação em uma grade de $𝑘^2$ pares de adaptadores menores e independentes, cada um responsável por um subconjunto localizado das dimensões de entrada e saída. Como resultado, cada adaptador opera em um subespaço que é $k$ vezes menor em ambas as dimensões em comparação com o adaptador LoRA original.

Essa decomposição granular permite atualizações espacialmente localizadas e conscientes do contexto, aumentando efetivamente a capacidade representacional sem parâmetros ou custo computacional adicionais. Ao isolar a influência de ativações extremas em subespaços menores, o GraLoRA mitiga a distorção do gradiente e preserva o equilíbrio entre canais durante a adaptação.

---

O resumo do artigo é:

*A Low-Rank Adaptation (LoRA) é um método popular para ajuste fino eficiente em parâmetros (PEFT) de modelos generativos, valorizado por sua simplicidade e eficácia. Apesar de aprimoramentos recentes, a LoRA ainda sofre de uma limitação fundamental: overfitting quando o gargalo é alargado. Ela apresenta o melhor desempenho em ranks 32–64, mas sua precisão estagna ou declina em ranks mais altos, ainda ficando aquém do desempenho do ajuste fino completo (FFT). Identificamos a causa raiz como o gargalo estrutural da LoRA, que introduz emaranhamento de gradientes nos canais de entrada não relacionados e distorce a propagação de gradientes. Para resolver isso, introduzimos uma estrutura nova, a Granular Low-Rank Adaptation (GraLoRA), que particiona as matrizes de pesos em sub-blocos, cada um com seu próprio adaptador de baixo rank. Com custo computacional ou de armazenamento desprezível, a GraLoRA supera as limitações da LoRA, aumenta efetivamente a capacidade representacional e aproxima-se mais do comportamento do FFT. Experimentos em benchmarks de geração de código, raciocínio de senso comum, raciocínio matemático, compreensão geral de linguagem e geração de imagens mostram que a GraLoRA supera consistentemente a LoRA e outras linhas de base, alcançando um ganho absoluto de até +8,5% em Pass@1 no HumanEval+. Essas melhorias se mantêm em diferentes tamanhos de modelo e configurações de rank, tornando a GraLoRA uma solução escalável e robusta para PEFT.*

## Visão geral do benchmark

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

# API

## GraloraConfig[[peft.GraloraConfig]]

#### peft.GraloraConfig[[peft.GraloraConfig]]

```python
peft.GraloraConfig(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, hybrid_r: int = 0, target_modules: list[str] | str | None = None, alpha: int = 64, gralora_dropout: float = 0.0, gralora_k: int = 2, fan_in_fan_out: bool = False, bias: str = 'none', modules_to_save: list[str] | None = None, init_weights: bool = True, layers_to_transform: list[int] | int | None = None, layers_pattern: str | None = None)
```

[Fonte](https://github.com/huggingface/peft/blob/main/src/peft/tuners/gralora/config.py#L23)

**Parâmetros:**

r (`int`) : A dimensão de atenção do GraLoRA determina o rank do adaptador GraLoRA. O número total de parâmetros do adaptador GraLoRA é o mesmo que o do LoRA com o mesmo rank r, enquanto a expressividade é multiplicada por gralora_k.

hybrid_r (`int`) : O rank do Hybrid GraLoRA determina o rank alocado ao método LoRA vanilla ao usar o método Hybrid GraLoRA. O Hybrid GraLoRA, uma combinação de GraLoRA e LoRA vanilla, fica disponível quando hybrid_r > 0. A contagem de parâmetros do adaptador GraLoRA é r + hybrid_r.

target_modules (`Union[List[str], str]`) : Lista de nomes de módulos ou expressão regular dos nomes de módulos a serem substituídos por GraLoRA. Por exemplo, ['q', 'v'] ou '.*decoder.*(SelfAttention|EncDecAttention).*(q|v)$'. Isso também pode ser um curinga 'all-linear', que corresponde a todos os lineares/Conv1D (se o modelo for um PreTrainedModel, a camada de saída é excluída). Se não for especificado, os módulos serão escolhidos 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.

alpha (`int`) : GraLoRA alpha. O GraLoRA alpha é o fator de escala para o adaptador GraLoRA. A escala se torna alpha / (r + hybrid_r).

gralora_dropout (`float`) : O dropout do GraLoRA é a probabilidade de dropout para o adaptador GraLoRA. Ele é usado para evitar overfitting e melhorar a generalização do adaptador GraLoRA.

gralora_k (`int`) : GraLoRA k determina o número de subblocos no adaptador GraLoRA. O rank r deve ser divisível por gralora_k para que o adaptador GraLoRA seja válido. A contagem total de parâmetros é preservada, independentemente de gralora_k. O rank total do adaptador GraLoRA é aumentado por gralora_k, enquanto o rank de cada subbloco é reduzido por gralora_k. gralora_k=2 é recomendado para rank 32 ou inferior, e gralora_k=4 é recomendado para rank 64 ou superior.

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 gralora. Pode ser 'none', 'all' ou 'gralora_only'. Se for 'all' ou 'gralora_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 (`Optional[list[str]]`) : Lista de módulos, além das camadas gralora, 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.

init_weights (`bool`) : Se as camadas GraLoRA devem ter seus pesos inicializados com a inicialização padrão. Não altere esta configuração, exceto se você souber exatamente o que está fazendo.

layers_to_transform (`Union[List[int], int]`) : Os índices das camadas a serem transformadas. Se esse argumento for especificado, o PEFT transformará apenas os índices das camadas especificados dentro dessa lista. Se um único inteiro for passado, o PEFT transformará apenas a camada nesse índice. Isso só funciona quando target_modules é uma lista de str.

layers_pattern (`Optional[Union[List[str], str]]`) : 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 só funciona quando target_modules é uma lista de str. Isso deve visar 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 [GraloraModel](/docs/peft/main/pt/package_reference/gralora#peft.GraloraModel).

## GraloraModel[[peft.GraloraModel]]

#### peft.GraloraModel[[peft.GraloraModel]]

```python
peft.GraloraModel(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/main/src/peft/tuners/gralora/model.py#L28)

**Parâmetros:**

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

config ([GraloraConfig](/docs/peft/main/pt/package_reference/gralora#peft.GraloraConfig)) : A configuração do modelo Gralora.

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

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

O modelo Gralora.

Cria um modelo de Random Matrix Adaptation baseado em vetores (Gralora) a partir de um modelo transformers pré-treinado.

Exemplo:

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

>>> base_model = AutoModelForCausalLM.from_pretrained("facebook/opt-125m")
>>> config = GraloraConfig(r=128)
>>> model = get_peft_model(base_model, config)
```

**Atributos**:
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) -- O modelo a ser adaptado.
- **peft_config** ([GraloraConfig](/docs/peft/main/pt/package_reference/gralora#peft.GraloraConfig)): A configuração do modelo Gralora.