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) é um método PEFT que estende a abordagem LoRA aplicando uma modulação elemento a elemento na matriz de pesos original. Em vez de adicionar uma atualização de baixo rank diretamente, o HiRA calcula: W′=W0+W0⊙(BA) W' = W_0 + W_0 \odot (B A)

onde W0W_0 é o peso base, e A,BA, B são fatores de baixo rank com rank $r \ll \min(\text{in_features}, \text{out_features})$. Essa formulação permite que o HiRA adapte pesos existentes com uma modulação multiplicativa e dependente da entrada, melhorando frequentemente a eficiência do fine-tuning em tarefas downstream.

O resumo do artigo HiRA é:

Propomos a Adaptação de Alto Rango de Hadamard (HiRA), um método de ajuste fino eficiente em parâmetros (PEFT) que aprimora a adaptabilidade dos Grandes Modelos de Linguagem (LLMs). Embora a Adaptação de Baixo Rango (LoRA) seja amplamente utilizada para reduzir a demanda de recursos, suas atualizações de baixo rango podem limitar sua expressividade para novas tarefas. O HiRA aborda isso ao usar um produto de Hadamard para reter parâmetros de atualização de alto rango, melhorando a capacidade do modelo. Empiricamente, o HiRA supera o LoRA e suas variantes em várias tarefas, com extensos estudos de ablação validando sua eficácia.

Exemplos

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

Visão geral do benchmark

Citação:

Se você achou que o HiRA é útil, por favor, cite o HiRA como:

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

Parâmetros

  • r (int) — Rank do componente de baixo rank em HiRA. Embora o HiRA alcance uma adaptação de alto rank por meio da fusão de Hadamard, esse valor define a dimensão da fatoração de baixo rank subjacente (matrizes A e B).
  • target_modules (Optional[Union[List[str], str]]) — Os nomes dos módulos aos quais o adaptador será aplicado. Se especificado, apenas os módulos com os nomes especificados serão substituídos. Ao passar uma string, uma correspondência de regex será realizada. Ao passar uma lista de strings, uma correspondência exata será realizada ou será verificado se o nome do módulo termina com qualquer uma das strings passadas. Se especificado como ‘all-linear’, todos os módulos lineares/Conv1D serão escolhidos (se o modelo for um PreTrainedModel, a camada de saída será excluída). Se não for especificado, os módulos serão escolhidos de acordo com a arquitetura do modelo. Se a arquitetura não for conhecida, um erro será lançado — nesse caso, você deve especificar os módulos de destino manualmente.
  • exclude_modules (Optional[Union[List[str], str]]) — Os nomes dos módulos para os quais o adaptador não deve ser aplicado. Ao passar uma string, será realizada uma correspondência por expressão regular. Ao passar uma lista de strings, será realizada uma correspondência exata ou será verificado se o nome do módulo termina com qualquer uma das strings passadas.
  • hira_dropout (float) — A probabilidade de dropout para as camadas HiRA.
  • fan_in_fan_out (bool) — Defina como True se a camada a ser substituída armazenar os pesos como (fan_in, fan_out). Por exemplo, o gpt-2 usa Conv1D, que armazena os pesos como (fan_in, fan_out), e portanto este parâmetro deve ser definido como True.
  • modules_to_save (List[str]) — Lista de módulos, além das camadas de adaptador, que devem ser configurados como treináveis e salvos no checkpoint final.
  • init_weights (bool | Literal["gaussian"]) — Como inicializar os pesos das camadas HiRA. Passar True (padrão) resulta na inicialização padrão, com o peso B do HiRA definido como 0. Isso significa que, sem treinamento adicional, o adaptador HiRA será um no-op. Definir a inicialização como False leva à inicialização aleatória de HiRA A e B, o que significa que o HiRA não é um no-op antes do treinamento; essa configuração é destinada a fins de depuração. Passar 'gaussian' resulta em inicialização gaussiana escalada pelo rank do HiRA para camadas lineares e camadas.
  • layers_to_transform (Union[List[int], int]) — Os índices das camadas a serem transformadas. Se uma lista de inteiros for passada, o adaptador será aplicado aos índices das camadas especificados nessa lista. Se um único inteiro for passado, as transformações serão aplicadas à camada nesse índice.
  • layers_pattern (Optional[Union[List[str], str]]) — O nome do padrão de camadas, usado apenas se layers_to_transform for diferente de None. Isso deve apontar para o nn.ModuleList do modelo, que frequentemente é chamado de 'layers' ou 'h'.
  • rank_pattern (dict) — O mapeamento de nomes de camadas ou expressões regulares para ranks que são diferentes do r padrão especificado por r. Por exemplo, {'^model.decoder.layers.0.encoder_attn.k_proj': 16}.

Esta é a classe de configuração para armazenar a configuração de um 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

Parâmetros

  • model (torch.nn.Module) — O modelo a ser adaptado.
  • config (HiraConfig) — A configuração do modelo HiRA.
  • adapter_name (str) — O nome do adaptador, padrão é "default".
  • low_cpu_mem_usage (bool, optional, defaults to False) — Cria pesos de adaptador vazios no dispositivo meta. Útil para acelerar o processo de carregamento.

Retorna

torch.nn.Module

O modelo HiRA.

Cria o modelo HiRA Adapter a partir de um modelo transformers pré-treinado.

O método é descrito em detalhes em https://openreview.net/pdf?id=TwJrTz9cRS.

Exemplo:

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

Atributos:

Camadas Principais

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 )

Parâmetros

  • adapter (str) — O nome do adaptador para o qual o peso delta deve ser calculado.

Calcule o peso delta para o adaptador fornecido.

merge

< >

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

Parâmetros

  • safe_merge (bool, opcional) — Se True, a operação de mesclagem será executada em uma cópia dos pesos originais e verificará a presença de NaNs antes de mesclar os pesos. Isso é útil se você deseja verificar se a operação de mesclagem produzirá NaNs. O valor padrão é False.
  • adapter_names (list[str], opcional) — A lista de nomes de adaptadores que devem ser mesclados. Se for None, todos os adaptadores ativos serão mesclados. O padrão é None.

Mergear os pesos do adaptador ativo nos pesos base

unmerge

< >

( )

Este método desmergeia todas as camadas de adaptador mescladas dos pesos base.

Adaptador de Embedding

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 para a camada de Embedding. Suporta adaptadores mistos por lote ou um único adaptador.

get_delta_weight

< >

( adapter )

Parâmetros

  • adapter (str) — O nome do adaptador para o qual o peso delta deve ser calculado.

Calcule o peso delta para o adaptador fornecido.

merge

< >

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

Parâmetros

  • safe_merge (bool, opcional) — Se True, a operação de mesclagem será executada em uma cópia dos pesos originais e verificará a presença de NaNs antes de mesclar os pesos. Isso é útil se você deseja verificar se a operação de mesclagem produzirá NaNs. O valor padrão é False.
  • adapter_names (list[str], opcional) — A lista de nomes de adaptadores que devem ser mesclados. Se for None, todos os adaptadores ativos serão mesclados. O padrão é None.

Mergear os pesos do adaptador ativo nos pesos base

unmerge

< >

( )

Este método desmergeia todas as camadas de adaptador mescladas dos pesos base.

Adaptadores Convolucionais

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

Update on GitHub

←GraLoRA HRA→