PEFT documentation

HiRA

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

HiRA

高秩适配(HiRA) )是一种 PEFT 方法,它通过对原始权重矩阵应用逐元素调制来扩展 LoRA 方法。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 论文的摘要如下:

我们提出了 Hadamard High-Rank Adaptation (HiRA),这是一种参数高效微调(PEFT)方法,旨在增强大语言模型(LLMs)的适应性。尽管低秩适应(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]]) — 要应用适配器(adapter)的模块名称。如果指定了此参数,则只有名称匹配的模块会被替换。传入字符串时,将执行正则表达式匹配。传入字符串列表时,将执行精确匹配,或检查模块名称是否以列表中的任一字符串结尾。如果指定为 ‘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 使用的 Conv1D 以 (fan_in, fan_out) 的形式存储权重,因此应将其设置为 True。
  • modules_to_save (List[str]) — 除适配器层外,需要设置为可训练并在最终检查点中保存的模块列表。
  • init_weights (bool | Literal["gaussian"]) — 如何初始化 HiRA 层的权重。传入 True(默认值)将采用默认初始化方式,其中 HiRA B 权重被设置为 0。这意味着在未进行进一步训练的情况下,HiRA 适配器将是一个空操作(no-op)。将初始化设置为 False 会导致 HiRA A 和 B 进行随机初始化,这意味着在训练之前 HiRA 不是空操作;此设置旨在用于调试目的。传入 'gaussian' 将导致对线性层和层进行按 HiRA 秩缩放的 Gaussian 初始化。
  • 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 不同的秩的映射。例如,{'^model.decoder.layers.0.encoder_attn.k_proj': 16}。

这是用于存储 HiraModel 配置的类。

HiraModel

类 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, defaults to False) — 在 meta 设备上创建空的适配器权重。有助于加快加载过程。

返回值

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 )

线性适配器

类 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) — 需要计算增量权重的适配器名称。

计算给定适配器的增量权重。

合并

< >

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

参数

  • safe_merge (bool, 可选) — 如果为 True,合并操作将在原始权重的副本上执行,并在合并权重之前检查是否存在 NaN。如果您想检查合并操作是否会产生 NaN,这将非常有用。默认为 False。
  • adapter_names (list[str], 可选) — 需要合并的适配器名称列表。如果为 None,则合并所有处于活动状态的适配器。默认值为 None。

将活动适配器的权重合并到基础权重中

unmerge

< >

( )

此方法会从基础权重中取消合并所有已合并的适配器层。

嵌入适配器

类 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) — 需要计算增量权重的适配器名称。

计算给定适配器的增量权重。

合并

< >

( 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