PEFT documentation
UniLoRA
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
< source >( 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) — Длина общего вектора UniLoratheta_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
< source >( modelconfigadapter_namelow_cpu_mem_usage: bool = Falsestate_dict: dict[str, torch.Tensor] | None = None )
Создаёт адаптер UniLora вокруг предобученной модели.
Назначьте детерминированные индексы 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.