# HiRA

Yüksek Sıralı Uyarlaması ([HiRA](https://openreview.net/pdf?id=TwJrTz9cRS)), orijinal ağırlık matrisine eleman bazlı bir modülasyon uygulayarak LoRA yaklaşımını genişleten bir PEFT yöntemidir. Düşük sıralı bir güncelleme doğrudan eklemek yerine HiRA şunu hesaplar:

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

burada $W_0$ taban ağırlığıdır ve $A, B$, $r \ll \min(	\text{in_features}, \text{out_features})$ rütbesine sahip düşük rütbeli faktörlerdir. Bu formülasyon, HiRA'nın mevcut ağırlıkları çoğalmalı ve girdiye bağlı bir modülasyonla uyarlamasına olanak tanır; bu da genellikle aşağı akış görevlerinde ince ayar verimliliğini artırır.

HiRA makalesinin özeti şudur:

> *Hadamard Yüksek-Rütbe Uyarlaması (HiRA) adını verdiğimiz, Büyük Dil Modellerinin (LLM) uyumluluğunu artıran parametre-verimli ince ayar (PEFT) yöntemini öneriyoruz. Düşük-rütbe Uyarlaması (LoRA), kaynak taleplerini azaltmak için yaygın olarak kullanılsa da, düşük-rütbe güncellemeleri yeni görevler için ifade gücünü sınırlayabilir. HiRA, yüksek-rütbe güncelleme parametrelerini korumak için Hadamard çarpımını kullanarak model kapasitesini artırır ve bu sorunu ele alır. Deneysel olarak HiRA, çeşitli görevlerde LoRA ve türevlerinden daha iyi performans göstermekte olup, kapsamlı ablatasyon çalışmaları etkinliğini doğrulamaktadır.*

## Örnekler

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

## Karma performans değerlendirmesi genel bakış

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

## Atıf:

HiRA'nın faydalı olduğunu düşünüyorsanız, lütfen HiRA'yı şu şekilde atıf yapın:
```
@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>)
```

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

**Parametreler:**

r (`int`) : HiRA'da düşük rütbeli bileşenin rütbesi. HiRA, Hadamard füzyonu yoluyla yüksek rütbeli bir uyarlama sağlasa da, bu değer altta yatan düşük rütbeli faktörizasyonun (A ve B matrisleri) boyutunu tanımlar.

target_modules (`Optional[Union[List[str], str]]`) : Adaptörün uygulanacağı modüllerin adları. Bu alan belirtilirse, yalnızca belirtilen adlara sahip modüller değiştirilir. Bir dize geçirildiğinde, bir regex eşleşmesi yapılır. Bir dize listesi geçirildiğinde, tam bir eşleşme yapılır veya modül adının, geçirilen dizelerden herhangi biriyle sonlanıp sonlanmadığı kontrol edilir. Bu alan 'all-linear' olarak belirtilirse, tüm linear/Conv1D modülleri seçilir (model bir PreTrainedModel ise, çıktı katmanı hariç). Bu alan belirtilmezse, modüller model mimarisine göre seçilir. Mimari bilinmiyorsa, bir hata oluşturulur -- bu durumda, hedef modülleri manuel olarak belirtmelisiniz.

exclude_modules (`Optional[Union[List[str], str]]`) : Uygulanmayacak modüllerin adları. Bir dize geçirildiğinde, bir regex eşleşmesi yapılır. Bir dize listesi geçirildiğinde, tam bir eşleşme yapılır veya modül adının, geçirilen dizelerden herhangi biriyle sona erip ermediği kontrol edilir.

hira_dropout (`float`) : HiRA katmanları için dropout olasılığı.

fan_in_fan_out (`bool`) : Değiştirilecek katman ağırlıkları (fan_in, fan_out) biçiminde saklıyorsa bunu True olarak ayarlayın. Örneğin, gpt-2 ağırlıkları (fan_in, fan_out) biçiminde saklayan `Conv1D` kullanır ve bu nedenle bu değer `True` olarak ayarlanmalıdır.

modules_to_save (`List[str]`) : Son kontrol noktasında eğilebilir olarak ayarlanacak ve kaydedilecek, adaptör katmanları dışındaki modüllerin listesi.

init_weights (`bool` | `Literal["gaussian"]`) : HiRA katmanlarının ağırlıklarının nasıl başlatılacağını belirtir. True (varsayılan) değeri geçirildiğinde varsayılan başlatma uygulanır ve HiRA B ağırlığı 0 olarak ayarlanır. Bu, ek eğitim yapılmadığı sürece HiRA adaptörünün bir no-op (etkisiz işlem) olacağı anlamına gelir. Başlatma değeri False olarak ayarlandığında HiRA A ve B rastgele başlatılır; bu da HiRA'nın eğitimden önce bir no-op olmadığı anlamına gelir ve bu ayar hata ayıklama amaçlıdır. `'gaussian'` değeri geçirildiğinde, lineer ve katmanlar için HiRA rank'ına göre ölçeklendirilmiş Gauss dağılımı başlatması uygulanır.

layers_to_transform (`Union[List[int], int]`) : Dönüştürülecek katman indeksleri. Bir int listesi geçirilirse, adaptör bu listede belirtilen katman indekslerine uygulanır. Tek bir tamsayı geçirilirse, dönüşümler bu indeksteki katmana uygulanır.

layers_pattern (`Optional[Union[List[str], str]]`) : Katman desen adı, yalnızca `layers_to_transform` `None`'den farklıysa kullanılır. Bu, genellikle `'layers'` veya `'h'` olarak adlandırılan modelin `nn.ModuleList`'ini hedeflemelidir.

rank_pattern (`dict`) : `r` tarafından belirtilen varsayılan r'den farklı rütlere sahip katman adlarından veya regexp ifadelerinden rütlere eşleme. Örneğin, `{'^model.decoder.layers.0.encoder_attn.k_proj': 16}`.

Bu, bir [HiraModel](/docs/peft/v0.22.0/tr/package_reference/hira#peft.HiraModel) yapılandırmasını depolamak için kullanılan yapılandırma sınıfıdır.

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

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

**Parametreler:**

model (`torch.nn.Module`) : Uyarlanacak model.

config ([HiraConfig](/docs/peft/v0.22.0/tr/package_reference/hira#peft.HiraConfig)) : HiRA modelinin yapılandırması.

adapter_name (`str`) : Adaptörün adı, varsayılan olarak `"default"`'tur.

low_cpu_mem_usage (`bool`, `optional`, varsayılan `False`) : Meta cihazında boş adaptör ağırlıkları oluşturur. Yükleme sürecini hızlandırmak için faydalıdır.

**Dönüş:** `torch.nn.Module`

HiRA modeli.

Önceden eğitilmiş bir transformers modelinden HiRA Adapter modeli oluşturur.

Yöntem, https://openreview.net/pdf?id=TwJrTz9cRS adresinde ayrıntılı olarak açıklanmıştır.

Örnek:

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

**Öznitelikler**:
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel)) -- Uyarlanacak model.
- **peft_config** ([HiraConfig](/docs/peft/v0.22.0/tr/package_reference/hira#peft.HiraConfig)): HiRA modelinin yapılandırması.

## Çekirdek Katmanlar

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

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

### Doğrusal Adaptör[[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)
```

[Kaynak](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)
```

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

**Parametreler:**

adapter (str) : Delta ağırlığın hesaplanacağı adaptörün adı.

Verilen adaptör için delta ağırlığı hesaplayın.

#### birleştir[[peft.tuners.hira.Linear.merge]]

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

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

**Parametreler:**

safe_merge (`bool`, *isteğe bağlı*) : True ise, birleştirme işlemi orijinal ağırlıkların bir kopyasında gerçekleştirilir ve ağırlıklar birleştirilmeden önce NaN değerleri kontrol edilir. Birleştirme işleminin NaN üreteceğini kontrol etmek istiyorsanız bu kullanışlıdır. Varsayılan değer `False`'dir.

adapter_names (`list[str]`, *isteğe bağlı*) : Birleştirilecek adaptör adlarının listesi. None ise, tüm etkin adaptörler birleştirilir. Varsayılan olarak `None`.

Aktif adaptör ağırlıklarını temel ağırlıklarla birleştirin

#### birleştirme işlemini geri al[[peft.tuners.hira.Linear.unmerge]]

```python
unmerge()
```

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

Bu yöntem, temel ağırlıklardan birleştirilmiş tüm adaptör katmanlarını ayırır.

### Gömme Adaptörü[[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)
```

[Kaynak](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)
```

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

HiRA ileri işlemi, Embedding katmanı için. Batch başına karışık adaptörleri veya tek bir adaptörü destekler.

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

```python
get_delta_weight(adapter)
```

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

**Parametreler:**

adapter (str) : Delta ağırlığın hesaplanacağı adaptörün adı.

Verilen adaptör için delta ağırlığı hesaplayın.

#### birleştir[[peft.tuners.hira.Embedding.merge]]

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

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

**Parametreler:**

safe_merge (`bool`, *isteğe bağlı*) : True ise, birleştirme işlemi orijinal ağırlıkların bir kopyasında gerçekleştirilir ve ağırlıklar birleştirilmeden önce NaN değerleri kontrol edilir. Birleştirme işleminin NaN üreteceğini kontrol etmek istiyorsanız bu kullanışlıdır. Varsayılan değer `False`'dir.

adapter_names (`list[str]`, *isteğe bağlı*) : Birleştirilecek adaptör adlarının listesi. None ise, tüm etkin adaptörler birleştirilir. Varsayılan olarak `None`.

Aktif adaptör ağırlıklarını temel ağırlıklarla birleştirin

#### birleştirme işlemini geri al[[peft.tuners.hira.Embedding.unmerge]]

```python
unmerge()
```

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

Bu yöntem, temel ağırlıklardan birleştirilmiş tüm adaptör katmanlarını ayırır.

### Dolanımsal Adaptörler

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

