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) 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′=W0+W0⊙(BA) W' = W_0 + W_0 \odot (B A)

où W0W_0 est le poids de base, et A,BA, B sont des facteurs de faible rang de rang $r \ll \min(\text{in_features}, \text{out_features})$. Cette formulation permet à HiRA d'adapter les poids existants avec 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

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

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

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

Paramètres

  • r (int) — Rang de la composante de bas 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 bas 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 cas de chaîne de caractères, une correspondance par expression régulière est effectuée. En cas de liste de chaînes de caractères, une correspondance exacte est réalisée ou il est vérifié si le nom du module se termine par l’une des chaînes fournies. Si la valeur est « 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 choisis en fonction de l’architecture du modèle. Si l’architecture est inconnue, 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é. Si une chaîne de caractères est transmise, une correspondance par expression régulière est effectuée. Si une liste de chaînes de caractères est transmise, une correspondance exacte est effectuée ou il est vérifié si le nom du module se termine par l’une des chaînes transmises.
  • 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, en dehors 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. La valeur 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ètre 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.
  • 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 r par défaut 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.

HiraModel

classe 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

Paramètres

  • model (torch.nn.Module) — Le modèle à adapter.
  • config (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'adaptateurs 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 :

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

Attributs :

Couches principales

HiraLayer

classe peft.tuners.hira.HiraLayer

< >

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

Linear Adapter

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

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é.

merge

< >

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

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. Valeur par défaut : None.

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

unmerge

< >

( )

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

Embedding Adapter

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

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

get_delta_weight

< >

( adapter )

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é.

merge

< >

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

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. Valeur par défaut : None.

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

unmerge

< >

( )

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

Update on GitHub

←GraLoRA HRA→