HiRA

High-Rank Adaptation (HiRA) 는 원본 가중치 행렬에 요소별(element-wise) 변조를 적용하여 LoRA 접근법을 확장한 PEFT 방법입니다. 저랭크 업데이트를 직접 추가하는 대신, HiRA는 다음을 계산합니다: $W' = W_0 + W_0 \odot (B A)$

여기서 $W_0$ 은 기본 가중치이고 $A, B$ 은 랭크가 $r \ll \min(\text{in_features}, \text{out_features})$인 저랭크 인자입니다. 이 구성은 HiRA가 곱셈적이고 입력에 의존하는 변조를 통해 기존 가중치를 적응시킬 수 있게 하여, 하위 작업에서 미세 조정 효율을 향상시킵니다.

HiRA 논문의 초록은 다음과 같습니다:

저희는 대규모 언어 모델(LLM)의 적응성을 향상시키는 매개변수 효율적 미세 조정(PEFT) 방법인 Hadamard High-Rank Adaptation(HiRA)을 제안합니다. Low-rank Adaptation(LoRA)은 자원 요구량을 줄이기 위해 널리 사용되지만, 그 low-rank 업데이트는 새로운 작업에 대한 표현력을 제한할 수 있습니다. HiRA는 Hadamard product를 사용하여 high-rank 업데이트 매개변수를 유지함으로써 모델 용량을 개선하여 이 문제를 해결합니다. 실험적으로, HiRA는 여러 작업에서 LoRA 및 그 변형보다 우수한 성능을 보였으며, 광범위한 ablation study를 통해 그 효과성이 검증되었습니다.

예시

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

벤치마크 개요

인용:

HiRA가 유용하셨다면, HiRA를 다음과 같이 인용해 주세요:

@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

class peft.HiraConfig

< source >

( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falser: int = 32target_modules: Optional[Union[list[str], str]] = Noneexclude_modules: Optional[Union[list[str], str]] = Nonehira_dropout: float = 0.0fan_in_fan_out: bool = Falsemodules_to_save: Optional[list[str]] = Noneinit_weights: bool | Literal['gaussian'] | None = Truelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = Nonerank_pattern: Optional[dict] = <factory> )

매개변수

r (int) — HiRA의 저랭크(low-rank) 구성 요소의 랭크(rank)입니다. HiRA는 Hadamard fusion을 통해 고랭크(high-rank) 적응을 달성하지만, 이 값은 저랭크 분해(행렬 A와 B)의 차원을 정의합니다.
target_modules (Optional[Union[List[str], str]]) — 어댑터를 적용할 모듈의 이름입니다. 이 값이 지정되면 지정된 이름을 가진 모듈만 교체됩니다. 문자열을 전달하면 정규식 매칭이 수행됩니다. 문자열 목록을 전달하면 정확한 매칭이 수행되거나, 모듈 이름이 전달된 문자열 중 하나로 끝나는지 확인됩니다. 이 값이 ‘all-linear’로 지정되면 모든 linear/Conv1D 모듈이 선택됩니다(모델이 PreTrainedModel인 경우 출력 레이어는 제외). 이 값이 지정되지 않으면 모델 아키텍처에 따라 모듈이 선택됩니다. 아키텍처가 알려지지 않은 경우 오류가 발생하며, 이 경우 대상 모듈을 수동으로 지정해야 합니다.
exclude_modules (Optional[Union[List[str], str]]) — 어댑터를 적용하지 않을 모듈의 이름입니다. 문자열을 전달하면 정규식 매칭이 수행됩니다. 문자열 목록을 전달하면 정확한 매칭이 수행되거나, 모듈 이름이 전달된 문자열 중 하나로 끝나는지 확인됩니다.
hira_dropout (float) — HiRA 레이어의 dropout 확률입니다.
fan_in_fan_out (bool) — 교체할 레이어가 가중치를 (fan_in, fan_out) 형태로 저장하는 경우 True로 설정합니다. 예를 들어, gpt-2는 가중치를 (fan_in, fan_out) 형태로 저장하는 Conv1D를 사용하므로 이 값을 True로 설정해야 합니다.
modules_to_save (List[str]) — 어댑터 레이어를 제외한 최종 체크포인트에 학습 가능 상태로 설정되고 저장될 모듈 목록.
init_weights (bool | Literal["gaussian"]) — HiRA 레이어의 가중치를 초기화하는 방법입니다. True(기본값)를 전달하면 HiRA B 가중치가 0으로 설정되는 기본 초기화가 수행됩니다. 이는 추가 학습 없이 HiRA 어댑터가 no-op이 됨을 의미합니다. 초기화를 False로 설정하면 HiRA A와 B가 무작위로 초기화되어 학습 전 HiRA가 no-op이 되지 않으며, 이 설정은 디버깅 목적으로 사용됩니다. 'gaussian'을 전달하면 linear 및 레이어에 대해 HiRA 랭크로 스케일링된 가우시안 초기화가 수행됩니다.
layers_to_transform (Union[List[int], int]) — 변환할 레이어의 인덱스입니다. 정수 목록을 전달하면 이 목록에 지정된 레이어 인덱스에 어댑터를 적용합니다. 단일 정수를 전달하면 해당 인덱스의 레이어에 변환을 적용합니다.
layers_pattern (Optional[Union[List[str], str]]) — layers_to_transform가 None과 다르면만 사용되는 레이어 패턴 이름입니다. 이는 모델의 nn.ModuleList를 대상으로 해야 하며, 보통 'layers' 또는 'h'라고 불립니다.
rank_pattern (dict) — r로 지정된 기본 r과 다른 rank를 가지는 레이어 이름 또는 정규식 표현식에서 rank로의 매핑입니다. 예를 들어, {'^model.decoder.layers.0.encoder_attn.k_proj': 16}.

이것은 HiraModel의 구성을 저장하기 위한 구성 클래스입니다.

HiraModel

class peft.HiraModel

< source >

( modelpeft_config: Union[PeftConfig, dict[str, PeftConfig]]adapter_name: strlow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None ) → torch.nn.Module

매개변수

model (torch.nn.Module) — 적응할 모델.
config (HiraConfig) — HiRA 모델의 구성입니다.
adapter_name (str) — 어댑터의 이름이며, 기본값은 "default"입니다.
low_cpu_mem_usage (bool, optional, 기본값 False) — 메타 디바이스에 빈 어댑터 가중치를 생성합니다. 로딩 프로세스를 가속하는 데 유용합니다.

반환값

torch.nn.Module

HiRA 모델.

HiRA Adapter 모델을 사전 학습된 transformers 모델에서 생성합니다.

해당 방법은 https://openreview.net/pdf?id=TwJrTz9cRS에서 자세히 설명되어 있습니다.

예:

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

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

속성:

model (PreTrainedModel) — 적응할 모델.
peft_config (HiraConfig): HiRA 모델의 구성입니다.

핵심 레이어

HiraLayer

class peft.tuners.hira.HiraLayer

< source >

( base_layer: nn.Moduleephemeral_gpu_offload: bool = False**kwargs )

Linear Adapter

class peft.tuners.hira.Linear

< source >

( base_layeradapter_name: strconfig: HiraConfigr: int = 0fan_in_fan_out: bool = Falseis_target_conv_1d_layer: bool = False**kwargs )

get_delta_weight

< source >

( adapter )

매개변수

adapter (str) — 델타 가중치를 계산할 어댑터의 이름입니다.

지정된 어댑터에 대한 델타 가중치를 계산합니다.

병합

< source >

( safe_merge: bool = Falseadapter_names: Optional[list[str]] = None )

매개변수

safe_merge (bool, 선택 사항) — True인 경우, 원본 가중치의 복사본에서 병합 작업을 수행하고 가중치를 병합하기 전에 NaN을 확인합니다. 병합 작업이 NaN을 생성하는지 확인하려는 경우 유용합니다. 기본값은 False입니다.
adapter_names (list[str], 선택 사항) — 병합할 어댑터 이름 목록입니다. None인 경우 모든 활성 어댑터가 병합됩니다. 기본값은 None입니다.

활성 어댑터 가중치를 기본 가중치에 병합합니다

unmerge

< source >

( )

이 메서드는 기본 가중치에서 병합된 모든 어댑터 레이어를 병합 해제합니다.

Embedding Adapter

class peft.tuners.hira.Embedding

< source >

( base_layer: nn.Moduleadapter_name: strconfig: HiraConfigr: int = 0fan_in_fan_out: bool = False**kwargs )

forward

< source >

( x: torch.Tensor*args: Any**kwargs: Any )

Embedding 레이어용 HiRA forward입니다. 배치별 혼합 어댑터 또는 단일 어댑터를 지원합니다.

get_delta_weight

< source >

( adapter )

매개변수

adapter (str) — 델타 가중치를 계산할 어댑터의 이름입니다.

지정된 어댑터에 대한 델타 가중치를 계산합니다.

병합

< source >

( safe_merge: bool = Falseadapter_names: Optional[list[str]] = None )

매개변수

safe_merge (bool, 선택 사항) — True인 경우, 원본 가중치의 복사본에서 병합 작업을 수행하고 가중치를 병합하기 전에 NaN을 확인합니다. 병합 작업이 NaN을 생성하는지 확인하려는 경우 유용합니다. 기본값은 False입니다.
adapter_names (list[str], 선택 사항) — 병합할 어댑터 이름 목록입니다. None인 경우 모든 활성 어댑터가 병합됩니다. 기본값은 None입니다.

활성 어댑터 가중치를 기본 가중치에 병합합니다

unmerge

< source >

( )

이 메서드는 기본 가중치에서 병합된 모든 어댑터 레이어를 병합 해제합니다.

합성곱 어댑터

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

Update on GitHub