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) es un método PEFT que extiende el enfoque de LoRA aplicando una modulación elemento a elemento sobre la matriz de pesos original. En lugar de añadir una actualización de bajo rango directamente, HiRA calcula: W′=W0+W0⊙(BA) W' = W_0 + W_0 \odot (B A)

donde W0W_0 es el peso base, y A,BA, B son factores de bajo rango con rango $r \ll \min(\text{in_features}, \text{out_features})$. Esta formulación permite a HiRA adaptar los pesos existentes con una modulación multiplicativa y dependiente de la entrada, lo que a menudo mejora la eficiencia del fine-tuning en tareas posteriores.

El resumen del artículo HiRA es:

Proponemos Hadamard High-Rank Adaptation (HiRA), un método de ajuste fino eficiente en parámetros (PEFT) que mejora la adaptabilidad de los Modelos de Lenguaje Grandes (LLMs). Si bien Low-rank Adaptation (LoRA) se utiliza ampliamente para reducir la demanda de recursos, sus actualizaciones de bajo rango pueden limitar su expresividad para nuevas tareas. HiRA aborda esto utilizando un producto de Hadamard para retener parámetros de actualización de alto rango, mejorando la capacidad del modelo. Empíricamente, HiRA supera a LoRA y sus variantes en varias tareas, con estudios de ablatión extensos que validan su efectividad.

Ejemplos

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

Resumen de las pruebas de rendimiento

Cita:

Si encontraste que HiRA es útil, por favor cita 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

clase 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) — Rango del componente de bajo rango en HiRA. Aunque HiRA logra una adaptación de alto rango mediante la fusión de Hadamard, este valor define la dimensión de la factorización de bajo rango subyacente (matrices A y B).
  • target_modules (Optional[Union[List[str], str]]) — Los nombres de los módulos a los que se aplicará el adaptador. Si se especifica, solo se reemplazarán los módulos con los nombres indicados. Al pasar una cadena de caracteres, se realizará una coincidencia mediante expresión regular. Al pasar una lista de cadenas de caracteres, se realizará una coincidencia exacta o se verificará si el nombre del módulo termina con alguna de las cadenas pasadas. Si se especifica como ‘all-linear’, se seleccionarán todos los módulos lineales/Conv1D (si el modelo es un PreTrainedModel, excluyendo la capa de salida). Si no se especifica, los módulos se elegirán según la arquitectura del modelo. Si la arquitectura no es conocida, se generará un error; en este caso, debe especificar los módulos objetivo manualmente.
  • exclude_modules (Optional[Union[List[str], str]]) — Los nombres de los módulos a los que no se aplicará el adaptador. Al pasar una cadena de caracteres, se realizará una coincidencia mediante expresión regular. Al pasar una lista de cadenas de caracteres, se realizará una coincidencia exacta o se comprobará si el nombre del módulo termina con alguna de las cadenas de caracteres pasadas.
  • hira_dropout (float) — La probabilidad de dropout para las capas HiRA.
  • fan_in_fan_out (bool) — Establezca este valor en True si la capa que se va a reemplazar almacena los pesos como (fan_in, fan_out). Por ejemplo, gpt-2 utiliza Conv1D, que almacena los pesos como (fan_in, fan_out), por lo que este valor debe establecerse en True.
  • modules_to_save (List[str]) — Lista de módulos, aparte de las capas de adaptador, que se configurarán como entrenables y se guardarán en el punto de control final.
  • init_weights (bool | Literal["gaussian"]) — Cómo inicializar los pesos de las capas HiRA. Pasar True (valor predeterminado) resulta en la inicialización predeterminada, con el peso B de HiRA establecido en 0. Esto significa que, sin entrenamiento adicional, el adaptador HiRA será una operación sin efecto (no-op). Establecer la inicialización en False lleva a una inicialización aleatoria de HiRA A y B, lo que significa que HiRA no es una operación sin efecto antes del entrenamiento; esta configuración está destinada a fines de depuración. Pasar 'gaussian' resulta en una inicialización gaussiana escalada por el rango de HiRA para las capas lineales.
  • layers_to_transform (Union[List[int], int]) — Los índices de las capas a transformar. Si se pasa una lista de enteros, se aplicará el adaptador a los índices de capa especificados en esta lista. Si se pasa un solo entero, se aplicarán las transformaciones a la capa en este índice.
  • layers_pattern (Optional[Union[List[str], str]]) — El nombre del patrón de capas, utilizado solo si layers_to_transform es diferente de None. Esto debe apuntar al nn.ModuleList del modelo, que a menudo se llama 'layers' o 'h'.
  • rank_pattern (dict) — El mapeo de nombres de capas o expresiones regulares a los rangos que difieren del r predeterminado especificado por r. Por ejemplo, {'^model.decoder.layers.0.encoder_attn.k_proj': 16}.

Esta es la clase de configuración para almacenar la configuración de un HiraModel.

HiraModel

clase 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) — El modelo que se va a adaptar.
  • config (HiraConfig) — La configuración del modelo HiRA.
  • adapter_name (str) — El nombre del adaptador, por defecto es "default".
  • low_cpu_mem_usage (bool, optional, defaults to False) — Crea pesos de adaptador vacíos en el dispositivo meta. Útil para acelerar el proceso de carga.

Devuelve

torch.nn.Module

El modelo HiRA.

Crea un modelo HiRA Adapter a partir de un modelo de transformers preentrenado.

El método se describe en detalle en https://openreview.net/pdf?id=TwJrTz9cRS.

Ejemplo:

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

Capas principales

HiraLayer

clase peft.tuners.hira.HiraLayer

< >

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

Linear Adapter

clase 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) — El nombre del adaptador para el que se debe calcular el peso delta.

Calcule el peso delta para el adaptador dado.

merge

< >

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

Parámetros

  • safe_merge (bool, opcional) — Si es True, la operación de fusión se realizará en una copia de los pesos originales y se verificarán los NaN antes de fusionar los pesos. Esto es útil si deseas comprobar si la operación de fusión producirá NaN. El valor predeterminado es False.
  • adapter_names (list[str], opcional) — La lista de nombres de adaptadores que deben fusionarse. Si es None, se fusionarán todos los adaptadores activos. El valor predeterminado es None.

Fusiona los pesos del adaptador activo en los pesos base

unmerge

< >

( )

Este método desune todas las capas de adaptador fusionadas de los pesos base.

Adaptador de incrustación

clase 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 la capa de Embedding. Admite adaptadores mixtos por lote o un solo adaptador.

get_delta_weight

< >

( adapter )

Parámetros

  • adapter (str) — El nombre del adaptador para el que se debe calcular el peso delta.

Calcule el peso delta para el adaptador dado.

merge

< >

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

Parámetros

  • safe_merge (bool, opcional) — Si es True, la operación de fusión se realizará en una copia de los pesos originales y se verificarán los NaN antes de fusionar los pesos. Esto es útil si deseas comprobar si la operación de fusión producirá NaN. El valor predeterminado es False.
  • adapter_names (list[str], opcional) — La lista de nombres de adaptadores que deben fusionarse. Si es None, se fusionarán todos los adaptadores activos. El valor predeterminado es None.

Fusiona los pesos del adaptador activo en los pesos base

unmerge

< >

( )

Este método desune todas las capas de adaptador fusionadas de los pesos base.

Adaptadores convolucionales

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

Update on GitHub

←GraLoRA HRA→