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

高秩适配（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

←GraLoRA HRA→