Hugging Face's logo

PEFT documentation

HiRA

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.21.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

HiRA

High-Rank Adaptation (HiRA) は、元の重み行列に対して要素ごとのモジュレーションを適用することで LoRA のアプローチを拡張した PEFT 手法です。低ランクの更新を直接加えるのではなく、HiRA は以下を計算します: W′=W0+W0⊙(BA) W' = W_0 + W_0 \odot (B A)

ここで W0W_0 はベースの重みであり、 A,BA, B はランク $r \ll \min(\text{in_features}, \text{out_features})$ の低ランク因子です。この定式化により、HiRA は乗法的で入力依存のモジュレーションを用いて既存の重みを適応させることができ、下流タスクでのファインチューニング効率を向上させることがよくあります。

HiRA論文の抄録は以下の通りです:

大規模言語モデル（LLM）の適応性を高めるパラメータ効率の良いファインチューニング（PEFT）手法として、Hadamard High-Rank Adaptation（HiRA）を提案します。LoRAはリソースの要求を低減するために広く利用されていますが、低ランクの更新は新しいタスクにおける表現力を制限する可能性があります。HiRAはHadamard積を用いて高ランクの更新パラメータを保持することでこの問題を解決し、モデルの容量を向上させます。実証的に、HiRAは複数のタスクにおいてLoRAとそのバリアントを上回る性能を示し、広範なアブレーションスタディによってその有効性が検証されています。

例

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

クラス peft.HiraConfig

< >

( 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における低ランク成分のランクです。HiRAはHadamard融合によって高ランク適応を実現しますが、この値は基礎となる低ランク分解（行列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層のドロップアウト確率です。
  • 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'を渡すと、線形層およびレイヤーに対して、HiRAのランクでスケーリングされたガウス初期化が行われます。
  • layers_to_transform (Union[List[int], int]) — 変換対象のレイヤーのインデックスです。int のリストが渡された場合、このリストに指定されたレイヤーのインデックスにアダプターが適用されます。単一の整数が渡された場合、そのインデックスのレイヤーに変換が適用されます。
  • layers_pattern (Optional[Union[List[str], str]]) — layers_to_transform が None と異なる場合にのみ使用されるレイヤーパターン名です。これはモデルの nn.ModuleList を対象とすべきで、通常は 'layers' または 'h' と呼ばれます。
  • rank_pattern (dict) — r で指定されるデフォルトの r と異なるランクを持つ、レイヤー名または正規表現からランクへのマッピングです。例えば、{'^model.decoder.layers.0.encoder_attn.k_proj': 16}。

これはHiraModelの設定を保存するための設定クラスです。

HiraModel

class peft.HiraModel

< >

( 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モデル。

事前学習済みのTransformersモデルからHiRA Adapterモデルを作成します。

この手法の詳細は、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)

属性:

コアレイヤー

HiraLayer

クラス peft.tuners.hira.HiraLayer

< >

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

Linear Adapter

クラス peft.tuners.hira.Linear

< >

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

get_delta_weight

< >

( adapter )

パラメータ

  • adapter (str) — デルタ重みの計算対象となるアダプタの名前。

指定されたアダプターについて、デルタ重みを計算します。

merge

< >

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

パラメータ

  • safe_merge (bool, 省略可) — True の場合、元の重みのコピー上でマージ操作を実行し、重みをマージする前に NaN のチェックを行います。マージ操作が NaN を生成するかどうかを確認したい場合に便利です。デフォルトは False です。
  • adapter_names (list[str], 任意) — マージするアダプター名のリストです。None の場合、すべてのアクティブなアダプターがマージされます。デフォルトは None です。

アクティブなアダプター重みをベース重みにマージします

unmerge

< >

( )

このメソッドは、ベースの重みからマージされたすべてのアダプタ層をアンマージします。

Embedding Adapter

クラス peft.tuners.hira.Embedding

< >

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

forward

< >

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

Embedding層のHiRAフォワード。バッチごとの混合アダプタまたは単一アダプタをサポートします。

get_delta_weight

< >

( adapter )

パラメータ

  • adapter (str) — デルタ重みの計算対象となるアダプタの名前。

指定されたアダプターについて、デルタ重みを計算します。

merge

< >

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

パラメータ

  • safe_merge (bool, 省略可) — True の場合、元の重みのコピー上でマージ操作を実行し、重みをマージする前に NaN のチェックを行います。マージ操作が NaN を生成するかどうかを確認したい場合に便利です。デフォルトは False です。
  • adapter_names (list[str], 任意) — マージするアダプター名のリストです。None の場合、すべてのアクティブなアダプターがマージされます。デフォルトは None です。

アクティブなアダプター重みをベース重みにマージします

unmerge

< >

( )

このメソッドは、ベースの重みからマージされたすべてのアダプタ層をアンマージします。

畳み込みアダプター

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

Update on GitHub

←GraLoRA HRA→