# HiRA

L'adaptation de rang élevé ([HiRA](https://openreview.net/pdf?id=TwJrTz9cRS)) est une méthode PEFT qui étend l'approche LoRA en appliquant une modulation élément par élément sur la matrice de poids d'origine. Au lieu d'ajouter directement une mise à jour de faible rang, HiRA calcule :

$$ W' = W_0 + W_0 \odot (B A) $$

où $W_0$ est le poids de base, et $A, B$ sont des facteurs de faible rang avec un rang $r \ll \min(	\text{in_features}, \text{out_features})$. Cette formulation permet à HiRA d'adapter les poids existants par une modulation multiplicative dépendante de l'entrée, améliorant souvent l'efficacité de l'ajustement fin sur les tâches en aval.

L'abstract de l'article HiRA est le suivant :

> *Nous proposons l’adaptation de haut rang par produit de Hadamard (HiRA), une méthode d’ajustement fin efficace en paramètres (PEFT) qui améliore l’adaptabilité des grands modèles de langage (LLM). Bien que l’adaptation de bas rang (LoRA) soit largement utilisée pour réduire les exigences en ressources, ses mises à jour de bas rang peuvent limiter son expressivité pour de nouvelles tâches. HiRA remédie à cela en utilisant un produit de Hadamard pour conserver des paramètres de mise à jour de haut rang, améliorant ainsi la capacité du modèle. Empiriquement, HiRA surpasse LoRA et ses variantes sur plusieurs tâches, avec des études d’ablation approfondies validant son efficacité.*

## Exemples

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import get_peft_model
from peft.tuners.hira import HiraConfig

# Example 1: HiRA on opt-125m for causal language modeling
model_id = "facebook/opt-125m"
base_model = AutoModelForCausalLM.from_pretrained(model_id)
tokenizer = AutoTokenizer.from_pretrained(model_id)

# Define HiRA configuration: apply to the MLP dense layers in each transformer block
hira_config = HiraConfig(
    r=32,
    target_modules=["k_proj", "q_proj", "v_proj", "fc1", "fc2"],
    hira_dropout=0.0,
    init_weights=True,
)
peft_model = get_peft_model(base_model, hira_config)

peft_model.print_healthcheck()
```

## Aperçu des benchmarks

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

## Citation :

Si vous avez trouvé HiRA utile, veuillez citer HiRA comme suit :
```
@inproceedings{
huang2025hira,
title={Hi{RA}: Parameter-Efficient Hadamard High-Rank Adaptation for Large Language Models},
author={Qiushi Huang and Tom Ko and Zhan Zhuang and Lilian Tang and Yu Zhang},
booktitle={The Thirteenth International Conference on Learning Representations},
year={2025},
url={https://openreview.net/forum?id=TwJrTz9cRS}
}
```

# API

## HiraConfig[[peft.HiraConfig]]

#### peft.HiraConfig[[peft.HiraConfig]]

```python
peft.HiraConfig(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, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, hira_dropout: float = 0.0, fan_in_fan_out: bool = False, modules_to_save: Optional[list[str]] = None, init_weights: bool | Literal['gaussian'] | None = True, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None, rank_pattern: Optional[dict] = <factory>)
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/config.py#L25)

**Paramètres :**

r (`int`) : Rang de la composante de faible rang dans HiRA. Bien que HiRA atteigne une adaptation de haut rang par fusion de Hadamard, cette valeur définit la dimension de la factorisation de faible rang sous-jacente (matrices A et B).

target_modules (`Optional[Union[List[str], str]]`) : Les noms des modules auxquels appliquer l'adaptateur. Si ce paramètre est spécifié, seuls les modules portant les noms indiqués seront remplacés. En passant une chaîne de caractères, une correspondance par expression régulière est effectuée. En passant une liste de chaînes de caractères, une correspondance exacte est effectuée ou il est vérifié si le nom du module se termine par l'une des chaînes passées. Si ce paramètre est spécifié comme 'all-linear', tous les modules linéaires/Conv1D sont sélectionnés (si le modèle est un PreTrainedModel, la couche de sortie est exclue). Si ce paramètre n'est pas spécifié, les modules sont sélectionnés en fonction de l'architecture du modèle. Si l'architecture n'est pas connue, une erreur est levée -- dans ce cas, vous devez spécifier manuellement les modules cibles.

exclude_modules (`Optional[Union[List[str], str]]`) : Les noms des modules auxquels l'adaptateur ne doit pas être appliqué. Lors du passage d'une chaîne de caractères, une correspondance par expression régulière est effectuée. Lors du passage d'une liste de chaînes de caractères, soit une correspondance exacte est effectuée, soit il est vérifié si le nom du module se termine par l'une des chaînes passées.

hira_dropout (`float`) : Probabilité de dropout pour les couches HiRA.

fan_in_fan_out (`bool`) : Définissez cette valeur sur True si la couche à remplacer stocke les poids sous la forme (fan_in, fan_out). Par exemple, gpt-2 utilise `Conv1D`, qui stocke les poids sous la forme (fan_in, fan_out), et il convient donc de définir cette valeur sur `True`.

modules_to_save (`List[str]`) : Liste des modules, à l'exception des couches d'adaptateur, à définir comme entraînables et à enregistrer dans le point de contrôle final.

init_weights (`bool` | `Literal["gaussian"]`) : Méthode d’initialisation des poids des couches HiRA. Passer True (par défaut) entraîne l’initialisation par défaut, avec le poids B de HiRA défini à 0. Cela signifie qu’en l’absence d’entraînement supplémentaire, l’adaptateur HiRA sera un no-op. Définir l’initialisation à False conduit à une initialisation aléatoire de HiRA A et B, ce qui signifie que HiRA n’est pas un no-op avant l’entraînement ; ce paramétrage est destiné aux fins de débogage. Passer `'gaussian'` entraîne une initialisation gaussienne mise à l’échelle par le rang de HiRA pour les couches linéaires et les couches.

layers_to_transform (`Union[List[int], int]`) : Les indices de couches à transformer. Si une liste d'entiers est transmise, l'adaptateur sera appliqué aux indices de couches spécifiés dans cette liste. Si un seul entier est transmis, les transformations seront appliquées à la couche située à cet index.

layers_pattern (`Optional[Union[List[str], str]]`) : Le nom du motif de couche, utilisé uniquement si `layers_to_transform` est différent de `None`. Il doit cibler le `nn.ModuleList` du modèle, souvent appelé `'layers'` ou `'h'`.

rank_pattern (`dict`) : La correspondance entre les noms de couches ou les expressions régulières et les rangs qui diffèrent du rang par défaut r spécifié par `r`. Par exemple, `{'^model.decoder.layers.0.encoder_attn.k_proj': 16}`.

Ceci est la classe de configuration destinée à stocker la configuration d'un [HiraModel](/docs/peft/main/fr/package_reference/hira#peft.HiraModel).

## HiraModel[[peft.HiraModel]]

#### peft.HiraModel[[peft.HiraModel]]

```python
peft.HiraModel(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)
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/model.py#L49)

**Paramètres :**

model (`torch.nn.Module`) : Le modèle à adapter.

config ([HiraConfig](/docs/peft/main/fr/package_reference/hira#peft.HiraConfig)) : La configuration du modèle HiRA.

adapter_name (`str`) : Le nom de l'adaptateur, par défaut `"default"`.

low_cpu_mem_usage (`bool`, `optional`, par défaut `False`) : Crée des poids d'adaptateur vides sur l'appareil méta. Utile pour accélérer le processus de chargement.

**Retourne :** `torch.nn.Module`

Le modèle HiRA.

Crée un modèle HiRA Adapter à partir d'un modèle transformers pré-entraîné.

La méthode est décrite en détail dans https://openreview.net/pdf?id=TwJrTz9cRS.

Exemple :

```py
>>> from transformers import AutoModelForSeq2SeqLM
>>> from peft import HiraConfig, get_peft_model

>>> config = HiraConfig(
...     task_type="SEQ_2_SEQ_LM",
...     r=32,
...     target_modules=["q", "v"],
...     hira_dropout=0.01,
... )

>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> hira_model = get_peft_model(model, config)
```

```py
>>> import torch
>>> import transformers
>>> from peft import HiraConfig, get_peft_model, prepare_model_for_kbit_training

>>> rank = ...
>>> target_modules = ["q_proj", "k_proj", "v_proj", "out_proj", "fc_in", "fc_out", "wte"]
>>> config = HiraConfig(r=32, target_modules=target_modules, hira_dropout=0.1, task_type="CAUSAL_LM")
>>> quantization_config = transformers.BitsAndBytesConfig(load_in_8bit=True)

>>> tokenizer = transformers.AutoTokenizer.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     bos_token="[BOS]",
...     eos_token="[EOS]",
...     unk_token="[UNK]",
...     pad_token="[PAD]",
...     mask_token="[MASK]",
... )
>>> model = transformers.GPTJForCausalLM.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     pad_token_id=tokenizer.eos_token_id,
...     use_cache=False,
...     device_map={"": rank},
...     torch_dtype=torch.float16,
...     quantization_config=quantization_config,
... )
>>> model = prepare_model_for_kbit_training(model)
>>> hira_model = get_peft_model(model, config)
```

**Attributs** :
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) -- Le modèle à adapter.
- **peft_config** ([HiraConfig](/docs/peft/main/fr/package_reference/hira#peft.HiraConfig)) : La configuration du modèle HiRA.

## Couches principales

### HiraLayer[[peft.tuners.hira.HiraLayer]]

#### peft.tuners.hira.HiraLayer[[peft.tuners.hira.HiraLayer]]

```python
peft.tuners.hira.HiraLayer(base_layer: nn.Module, ephemeral_gpu_offload: bool = False, **kwargs)
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/layer.py#L31)

### Linear Adapter[[peft.tuners.hira.Linear]]

#### peft.tuners.hira.Linear[[peft.tuners.hira.Linear]]

```python
peft.tuners.hira.Linear(base_layer, adapter_name: str, config: HiraConfig, r: int = 0, fan_in_fan_out: bool = False, is_target_conv_1d_layer: bool = False, **kwargs)
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/layer.py#L172)

#### get_delta_weight[[peft.tuners.hira.Linear.get_delta_weight]]

```python
get_delta_weight(adapter)
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/layer.py#L217)

**Paramètres :**

adapter (str) : Le nom de l'adaptateur pour lequel le poids delta doit être calculé.

Calculer le poids delta pour l'adaptateur donné.

#### fusion[[peft.tuners.hira.Linear.merge]]

```python
merge(safe_merge: bool = False, adapter_names: Optional[list[str]] = None)
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/layer.py#L192)

**Paramètres :**

safe_merge (`bool`, *facultatif*) : Si True, l'opération de fusion sera effectuée sur une copie des poids d'origine et vérifiera la présence de NaN avant de fusionner les poids. Cela est utile si vous souhaitez vérifier si l'opération de fusion produira des NaN. La valeur par défaut est `False`.

adapter_names (`list[str]`, *facultatif*) : La liste des noms d'adaptateurs à fusionner. Si None, tous les adaptateurs actifs seront fusionnés. La valeur par défaut est `None`.

Fusionner les poids de l'adaptateur actif dans les poids de base

#### unmerge[[peft.tuners.hira.Linear.unmerge]]

```python
unmerge()
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/layer.py#L211)

Cette méthode désintègre toutes les couches d'adaptateur fusionnées à partir des poids de base.

### Embedding Adapter[[peft.tuners.hira.Embedding]]

#### peft.tuners.hira.Embedding[[peft.tuners.hira.Embedding]]

```python
peft.tuners.hira.Embedding(base_layer: nn.Module, adapter_name: str, config: HiraConfig, r: int = 0, fan_in_fan_out: bool = False, **kwargs)
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/layer.py#L284)

#### forward[[peft.tuners.hira.Embedding.forward]]

```python
forward(x: torch.Tensor, *args: Any, **kwargs: Any)
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/layer.py#L398)

HiRA forward pour la couche d'Embedding. Prend en charge des adaptateurs mixtes par lot ou un adaptateur unique.

#### get_delta_weight[[peft.tuners.hira.Embedding.get_delta_weight]]

```python
get_delta_weight(adapter)
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/layer.py#L353)

**Paramètres :**

adapter (str) : Le nom de l'adaptateur pour lequel le poids delta doit être calculé.

Calculer le poids delta pour l'adaptateur donné.

#### fusion[[peft.tuners.hira.Embedding.merge]]

```python
merge(safe_merge: bool = False, adapter_names: Optional[list[str]] = None)
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/layer.py#L328)

**Paramètres :**

safe_merge (`bool`, *facultatif*) : Si True, l'opération de fusion sera effectuée sur une copie des poids d'origine et vérifiera la présence de NaN avant de fusionner les poids. Cela est utile si vous souhaitez vérifier si l'opération de fusion produira des NaN. La valeur par défaut est `False`.

adapter_names (`list[str]`, *facultatif*) : La liste des noms d'adaptateurs à fusionner. Si None, tous les adaptateurs actifs seront fusionnés. La valeur par défaut est `None`.

Fusionner les poids de l'adaptateur actif dans les poids de base

#### unmerge[[peft.tuners.hira.Embedding.unmerge]]

```python
unmerge()
```

[Source](https://github.com/huggingface/peft/blob/main/src/peft/tuners/hira/layer.py#L347)

Cette méthode désintègre toutes les couches d'adaptateur fusionnées à partir des poids de base.

### Adaptateurs convolutifs

[[autodoc]] tuners.hira.layer.Conv1d [[autodoc]] tuners.hira.layer.Conv2d [[autodoc]] tuners.hira.layer.ConvNd

