# HiRA

High-Rank Adaptation ([HiRA](https://openreview.net/pdf?id=TwJrTz9cRS)) adalah metode PEFT yang memperluas pendekatan LoRA dengan menerapkan modulasi element-wise pada matriks bobot asli. Alih-alih menambahkan pembaruan low-rank secara langsung, HiRA menghitung:

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

di mana $W_0$ adalah bobot dasar, dan $A, B$ adalah faktor ber-rank rendah dengan rank $r \ll \min(	\text{in_features}, \text{out_features})$. Formulasi ini memungkinkan HiRA untuk menyesuaikan bobot yang ada dengan modulasi multiplikatif yang bergantung pada input, yang sering kali meningkatkan efisiensi fine-tuning pada tugas turunan.

Abstrak dari paper HiRA adalah:

> *Kami mengusulkan Hadamard High-Rank Adaptation (HiRA), sebuah metode fine-tuning yang efisien secara parameter (PEFT) yang meningkatkan kemampuan adaptasi Large Language Models (LLM). Meskipun Low-rank Adaptation (LoRA) banyak digunakan untuk mengurangi kebutuhan sumber daya, pembaruan ber-rank rendah dapat membatasi ekspresivitasnya untuk tugas-tugas baru. HiRA mengatasi hal ini dengan menggunakan produk Hadamard untuk mempertahankan parameter pembaruan ber-rank tinggi, sehingga meningkatkan kapasitas model. Secara empiris, HiRA melampaui LoRA dan variasinya pada beberapa tugas, dengan studi ablasif yang luas yang memvalidasi efektivitasnya.*

## Contoh

```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()
```

## Ikhtisar benchmark

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

## Sitasi:

Jika Anda merasa HiRA berguna, silakan kutip HiRA sebagai:
```
@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>)
```

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

**Parameter:**

r (`int`) : Rank dari komponen low-rank dalam HiRA. Meskipun HiRA mencapai adaptasi high-rank melalui fusi Hadamard, nilai ini mendefinisikan dimensi dari faktorisasi low-rank yang mendasarinya (matriks A dan B).

target_modules (`Optional[Union[List[str], str]]`) : Nama-nama modul yang akan diterapkan adapter-nya. Jika ini ditentukan, hanya modul dengan nama yang ditentukan yang akan diganti. Saat meneruskan string, pencocokan regex akan dilakukan. Saat meneruskan daftar string, pencocokan persis akan dilakukan atau diperiksa apakah nama modul diakhiri dengan salah satu string yang diteruskan. Jika ini ditentukan sebagai 'all-linear', maka semua modul linear/Conv1D akan dipilih (jika modelnya adalah PreTrainedModel, lapisan output dikecualikan). Jika ini tidak ditentukan, modul akan dipilih sesuai dengan arsitektur model. Jika arsitekturnya tidak diketahui, error akan dilempar -- dalam kasus ini, Anda harus menentukan modul target secara manual.

exclude_modules (`Optional[Union[List[str], str]]`) : Nama-nama modul yang tidak akan diterapkan adapter. Saat melewatkan string, pencocokan regex akan dilakukan. Saat melewatkan daftar string, pencocokan persis akan dilakukan atau diperiksa apakah nama modul diakhiri dengan salah satu string yang dilewatkan.

hira_dropout (`float`) : Probabilitas dropout untuk lapisan HiRA.

fan_in_fan_out (`bool`) : Setel ini ke True jika layer yang akan diganti menyimpan bobot seperti (fan_in, fan_out). Sebagai contoh, gpt-2 menggunakan `Conv1D` yang menyimpan bobot seperti (fan_in, fan_out), sehingga ini harus disetel ke `True`.

modules_to_save (`List[str]`) : Daftar modul selain lapisan adapter yang akan diatur sebagai dapat dilatih dan disimpan dalam checkpoint akhir.

init_weights (`bool` | `Literal["gaussian"]`) : Cara menginisialisasi bobot dari lapisan HiRA. Mengirimkan True (default) menghasilkan inisialisasi default, dengan bobot HiRA B diset ke 0. Ini berarti bahwa tanpa pelatihan lebih lanjut, adapter HiRA akan menjadi no-op. Menetapkan inisialisasi ke False menyebabkan inisialisasi acak untuk HiRA A dan B, yang berarti HiRA bukan no-op sebelum pelatihan; pengaturan ini ditujukan untuk keperluan debugging. Mengirimkan `'gaussian'` menghasilkan inisialisasi Gaussian yang diskalakan berdasarkan rank HiRA untuk lapisan linear dan layers.

layers_to_transform (`Union[List[int], int]`) : Indeks lapisan yang akan ditransformasi. Jika daftar int diberikan, adapter akan diterapkan pada indeks lapisan yang ditentukan dalam daftar ini. Jika satu integer diberikan, transformasi akan diterapkan pada lapisan di indeks tersebut.

layers_pattern (`Optional[Union[List[str], str]]`) : Nama pola layer, hanya digunakan jika `layers_to_transform` berbeda dari `None`. Ini harus menargetkan `nn.ModuleList` dari model, yang sering disebut `'layers'` atau `'h'`.

rank_pattern (`dict`) : Pemetaan dari nama layer atau ekspresi regexp ke rank yang berbeda dari r default yang ditentukan oleh `r`. Sebagai contoh, `{'^model.decoder.layers.0.encoder_attn.k_proj': 16}`.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari [HiraModel](/docs/peft/v0.22.0/id/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)
```

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

**Parameter:**

model (`torch.nn.Module`) : Model yang akan diadaptasi.

config ([HiraConfig](/docs/peft/v0.22.0/id/package_reference/hira#peft.HiraConfig)) : Konfigurasi model HiRA.

adapter_name (`str`) : Nama adapter, secara default `"default"`.

low_cpu_mem_usage (`bool`, `optional`, defaultnya `False`) : Membuat bobot adapter kosong pada perangkat meta. Berguna untuk mempercepat proses pemuatan.

**Mengembalikan:** `torch.nn.Module`

Model HiRA.

Membuat model HiRA Adapter dari model transformers yang telah dilatih sebelumnya.

Metode ini dijelaskan secara detail di https://openreview.net/pdf?id=TwJrTz9cRS.

Contoh:

```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)
```

**Atribut**:
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel)) -- Model yang akan diadaptasi.
- **peft_config** ([HiraConfig](/docs/peft/v0.22.0/id/package_reference/hira#peft.HiraConfig)): Konfigurasi model HiRA.

## Lapisan Inti

### 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)
```

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/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)
```

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

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

```python
get_delta_weight(adapter)
```

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

**Parameter:**

adapter (str) : Nama adapter yang bobot delta-nya harus dihitung.

Hitung bobot delta untuk adapter yang diberikan.

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

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

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

**Parameter:**

safe_merge (`bool`, *opsional*) : Jika True, operasi penggabungan akan dilakukan pada salinan dari bobot asli dan memeriksa NaN sebelum menggabungkan bobot. Ini berguna jika Anda ingin memeriksa apakah operasi penggabungan akan menghasilkan NaN. Bawaan adalah `False`.

adapter_names (`list[str]`, *opsional*) : Daftar nama adapter yang harus digabungkan. Jika None, semua adapter aktif akan digabungkan. Bawaan adalah `None`.

Gabungkan bobot adapter aktif ke dalam bobot dasar

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

```python
unmerge()
```

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

Metode ini memisahkan semua lapisan adapter yang telah digabungkan dari bobot dasar.

### 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)
```

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

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

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

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

HiRA forward untuk lapisan Embedding. Mendukung adapter campuran per batch atau adapter tunggal.

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

```python
get_delta_weight(adapter)
```

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

**Parameter:**

adapter (str) : Nama adapter yang bobot delta-nya harus dihitung.

Hitung bobot delta untuk adapter yang diberikan.

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

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

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

**Parameter:**

safe_merge (`bool`, *opsional*) : Jika True, operasi penggabungan akan dilakukan pada salinan dari bobot asli dan memeriksa NaN sebelum menggabungkan bobot. Ini berguna jika Anda ingin memeriksa apakah operasi penggabungan akan menghasilkan NaN. Bawaan adalah `False`.

adapter_names (`list[str]`, *opsional*) : Daftar nama adapter yang harus digabungkan. Jika None, semua adapter aktif akan digabungkan. Bawaan adalah `None`.

Gabungkan bobot adapter aktif ke dalam bobot dasar

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

```python
unmerge()
```

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

Metode ini memisahkan semua lapisan adapter yang telah digabungkan dari bobot dasar.

### Adaptasi Konvolusional

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

