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) — это метод 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), повышающий адаптивность больших языковых моделей (LLM). Хотя Low-rank Adaptation (LoRA) широко применяется для снижения требований к ресурсам, её обновления низкого ранга могут ограничивать выразительность модели при решении новых задач. HiRA решает эту проблему, используя произведение Хадамарда для сохранения параметров обновлений высокого ранга, что увеличивает ёмкость модели. Экспериментально показано, что 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 обеспечивает адаптацию высокого ранга посредством гадамаровского слияния, это значение определяет размерность базовой низко-ранговой факторизации (матрицы A и B).
  • target_modules (Optional[Union[List[str], str]]) — Имена модулей, к которым следует применить адаптер. Если это значение указано, будут заменены только модули с указанными именами. При передаче строки выполняется сопоставление по регулярному выражению. При передаче списка строк выполняется точное совпадение или проверяется, заканчивается ли имя модуля каким-либо из переданных строк. Если это значение указано как ‘all-linear’, выбираются все линейные/Conv1D модули (если модель является PreTrainedModel, выходной слой исключается). Если это значение не указано, модули выбираются в соответствии с архитектурой модели. Если архитектура неизвестна, будет выброшена ошибка — в этом случае следует указать целевые модули вручную.
  • exclude_modules (Optional[Union[List[str], str]]) — Имена модулей, к которым не следует применять адаптер. При передаче строки выполняется сопоставление по регулярному выражению. При передаче списка строк выполняется точное совпадение или проверяется, заканчивается ли имя модуля каким-либо из переданных строк.
  • hira_dropout (float) — Вероятность dropout для слоёв HiRA.
  • fan_in_fan_out (bool) — Установите это значение в True, если заменяемый слой хранит веса в формате (fan_in, fan_out). Например, 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 не является no-op до обучения; этот вариант предназначен для отладки. Передача 'gaussian' приводит к гауссовой инициализации, масштабированной рангом HiRA для линейных слоев.
  • 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, по умолчанию False) — Создаёт пустые веса адаптера на meta-устройстве. Полезно для ускорения процесса загрузки.

Возвращает

torch.nn.Module

Модель HiRA.

Создаёт модель HiRA Adapter на основе предобученной модели transformers.

Метод подробно описан в 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)

Атрибуты:

  • model (PreTrainedModel) — Модель, подлежащая адаптации.
  • peft_config (HiraConfig): конфигурация модели HiRA.

Основные слои

HiraLayer

класс peft.tuners.hira.HiraLayer

< >

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

Linear Adapter

класс 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) — Имя адаптера, для которого следует вычислить дельту весов.

Вычислите дельта-веса для указанного адаптера.

merge

< >

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

HiRA forward для слоя Embedding. Поддерживает смешанные адаптеры в одном батче или одиночный адаптер.

get_delta_weight

< >

( adapter )

Параметры

  • adapter (str) — Имя адаптера, для которого следует вычислить дельту весов.

Вычислите дельта-веса для указанного адаптера.

merge

< >

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