PEFT documentation

UniLoRA

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

UniLoRA

Uni-LoRA — это метод PEFT, который разделяет компактный банк обучаемых векторов между весами низко-ранговых адаптеров. Вместо того чтобы обучать каждый элемент матрицы LoRA независимо, UniLoRA детерминированно проецирует элементы в общие значения theta_d и обучает общие параметры, используемые в обновлении адаптера.

Быстрый старт

from peft import UniLoraConfig, get_peft_model
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-3B")

config = UniLoraConfig(
    r=32,
    theta_d_length=256,
    proj_seed=42,
    target_modules=["q_proj", "v_proj"],
    unilora_dropout=0.0,
    init_weights=True,
    task_type="CAUSAL_LM",
)

peft_model = get_peft_model(model, config)
peft_model.print_healthcheck()

Важные параметры

r управляет размерностью низко-рангового адаптера. Большие значения увеличивают ёмкость адаптера и потребление памяти.

theta_d_length управляет длиной общего банка векторов UniLoRA. Это основное обучаемое хранилище, которым совместно пользуются элементы проекционного адаптера.

proj_seed управляет детерминированной генерацией индексов для фиксированных проекций в theta_d. Повторное использование того же seed и конфигурации делает сгенерированные индексы адаптера воспроизводимыми.

target_modules определяет, какие модули получают адаптеры UniLoRA. Используйте суффиксы модулей, например ["q_proj", "v_proj"], строку регулярного выражения или "all-linear", если это поддерживается архитектурой модели.

unilora_dropout применяет dropout внутри слоёв адаптера UniLoRA во время обучения.

init_weights управляет инициализацией параметров UniLoRA. Установите значение False, чтобы сохранить случайную инициализацию theta_d, если вам необходимо управлять инициализацией вручную.

save_indices управляет тем, сохраняются ли в контрольных точках UniLoRA сгенерированные тензоры индексов и масштабов вместе с общими параметрами theta_d. Если оставить эту опцию отключённой, контрольные точки будут меньше по размеру, а индексы будут регенерироваться из proj_seed; если включить, сохранённые адаптеры станут независимыми от будущих изменений в генерации индексов.

Обзор бенчмарков

API

UniLoraConfig

класс peft.UniLoraConfig

< >

( 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 = 4proj_seed: int = 42theta_d_length: int = 256target_modules: list[str] | str | None = Noneunilora_dropout: float = 0.0fan_in_fan_out: bool = Falsebias: str = 'none'modules_to_save: list[str] | None = Noneinit_theta_d_bound: float = 0.02init_weights: bool = Truesave_indices: bool = Falselayers_to_transform: list[int] | int | None = Nonelayers_pattern: list[str] | str | None = None )

Параметры

  • r (int) — Ранг низко-ранговой адаптации. Этот параметр определяет выразительную способность обновления UniLora.
  • proj_seed (int) — Случайный сид, используемый для генерации фиксированного распределения индексов. Это обеспечивает воспроизводимость между запусками.
  • theta_d_length (int) — Длина общего вектора UniLora theta_d.
  • target_modules (Union[list[str], str], необязательный) — Имена или шаблоны модулей, к которым применяются адаптеры UniLora.
    • Если передана строка, она рассматривается как регулярное выражение.
    • Если передан список, модули сопоставляются по точному имени или суффиксу.
    • Специальное значение ‘all-linear’ применяет UniLora ко всем слоям Linear / Conv1D, за исключением выходного слоя. Если значение не указано, модули определяются на основе архитектуры модели. Если архитектура не поддерживается, возникает ошибка.
  • unilora_dropout (float) — Вероятность dropout, применяемая внутри слоёв UniLora.
  • fan_in_fan_out (bool) — Указывает, сохраняет ли заменяемый слой веса в формате (fan_in, fan_out). Это значение должно быть установлено в True для моделей, таких как GPT-2, которые используют слои Conv1D.
  • bias (str) — Указывает, какие смещения (bias) подлежат обучению:
    • ‘none’: параметры смещения не обновляются
    • ‘all’: обновляются все параметры смещения
    • ‘unilora_only’: обновляются только смещения внутри слоёв UniLora Примечание: включение обновления смещений изменяет выходные данные модели даже при отключённых адаптерах.
  • modules_to_save (list[str], необязательный) — Дополнительные модули (вне слоев UniLora), которые должны оставаться обучаемыми и сохраняться в итоговом чекпоинте. Обычно используется для специфичных для задачи головок, таких как классификаторы.
  • init_theta_d_bound (float) — Граница инициализации для векторного банка UniLora. Векторы выбираются равномерно из диапазона [-init_theta_d_bound, init_theta_d_bound]. Инициализация нулями избегается, чтобы предотвратить исчезновение градиентов. Для стабильного обучения рекомендуются небольшие значения (например, 0.02).
  • init_weights (bool) — Следует ли инициализировать theta_d с помощью стандартной инициализации UniLora. Если установлено в False, theta_d сохраняет случайную инициализацию.
  • save_indices (bool) — Сохранять ли сгенерированные индекс и буферы масштаба UniLora вместе с theta_d. Это увеличивает размер контрольной точки, но делает сохранённые адаптеры независимыми от будущих изменений в процедуре генерации индекса.
  • layers_to_transform (Union[list[int], int], необязательный) — Индексы слоёв трансформера, к которым применяется UniLora. Если указано, изменяются только эти слои. Этот параметр действителен только в том случае, если target_modules является списком.
  • layers_pattern (Union[list[str], str], необязательный) — Пользовательский шаблон имени слоя, используемый вместе с layers_to_transform, когда модель не следует стандартным конвенциям именования слоёв. Этот параметр действителен только в том случае, если target_modules является списком.

Класс конфигурации для адаптеров UniLora.

Этот класс определяет все гиперпараметры, необходимые для инициализации и применения слоёв UniLora в рамках PEFT. Конфигурация намеренно минимальна и включает только параметры, которые активно используются в текущей реализации UniLora.

Reference: Uni-LoRA: One Vector Is All You Need https://arxiv.org/abs/2506.00799

UniLoraModel

класс peft.UniLoraModel

< >

( modelconfigadapter_namelow_cpu_mem_usage: bool = Falsestate_dict: dict[str, torch.Tensor] | None = None )

Создаёт адаптер UniLora вокруг предобученной модели.

generate_index

< >

( lora_param_count: inttheta_d_length: intproj_seed: int )

Назначьте детерминированные индексы theta_d для сглаженного пространства параметров UniLora.

Обычный вызов np.random.choice(np.arange(theta_d_length), size=lora_param_count) выбирает каждую позицию независимо, из-за чего для небольших адаптеров некоторые элементы theta_d могут остаться неиспользованными. UniLora вместо этого использует сбалансированное детерминированное распределение: каждый индекс встречается либо floor(D / d), либо ceil(D / d) раз, где D — это количество параметров LoRA после приведения к одномерному виду, а d — это theta_d_length. Это обеспечивает стабильность нормализации для каждого индекса, при этом само распределение перемешивается с помощью proj_seed.

Update on GitHub