# PVeRA: вероятностная адаптация случайных матриц на основе векторов

[PVeRA](https://huggingface.co/papers/2512.07703) — это метод эффективной по параметрам дообучения, основанный на VeRA и относящийся к семейству адаптеров на базе LoRA. Он сохраняет крайне низкий бюджет параметров VeRA, но повышает качество работы за счёт обучения распределения латентных адаптаций. Это также позволяет моделям, адаптированным с помощью PVeRA, генерировать оценки доверительных интервалов Монте-Карло путём выборки из обученного распределения на этапе инференса.

При сохранении параметров адаптера можно отказаться от хранения матриц низкого ранга, установив `save_projection=False` в `PveraConfig`. В этом случае эти матрицы будут восстановлены на основе фиксированного случайного зерна из аргумента `projection_prng_key`. Это уменьшает размер контрольной точки, но мы не можем гарантировать воспроизводимость на всех устройствах и во всех будущих версиях PyTorch. Если вы хотите обеспечить воспроизводимость, установите `save_projection=True` (это значение по умолчанию).

Для обработки различных форм адаптируемых слоёв PVeRA инициализирует общие матрицы A и B максимальным требуемым размером для каждого измерения. Во время прямого прохода подматрицы A и B для данного слоя вырезаются из этих общих матриц и используются, как описано в статье. Например, адаптация двух линейных слоёв форм (100, 20) и (80, 50) создаст матрицы A и B форм (rank, 50) и (100, rank) соответственно. Затем, чтобы адаптировать слой формы (100, 20), будут извлечены подматрицы A и B форм (rank, 20) и (100, rank).

В настоящее время PVeRA имеет следующее ограничение:

- Поддерживаются только слои `nn.Linear`.
- Латентное представление не является легкодоступным для обучения с использованием расхождения Кульбака-Лейблера.

Аннотация из статьи:

> В последние годы появились крупные фундаментальные модели, которые продвигают границы производительности для широкого спектра задач. Обучение или даже дообучение таких моделей требует огромных наборов данных и вычислительных ресурсов, которые часто дефицитны и дороги. Методы адаптации предлагают вычислительно эффективное решение для преодоления этих ограничений, позволяя дообучать такие модели на малых объёмах данных и вычислительных мощностях. Это достигается путём добавления новых обучаемых модулей к замороженным базовым моделям, содержащим лишь малую долю обучаемых параметров, и настройки только этих модулей на новых задачах. Недавно было показано, что адаптер VeRA превосходит другие методы параметрически эффективной адаптации за счёт использования пары замороженных случайных матриц низкого ранга, общих для всех слоёв. В данной статье мы предлагаем PVeRA — вероятностную версию адаптера VeRA, которая изменяет матрицы низкого ранга VeRA вероятностным образом. Это изменение естественным образом позволяет учитывать внутреннюю неоднозначность входных данных и допускает различные конфигурации выборки при обучении и тестировании. Комплексная оценка была проведена на бенчмарке VTAB-1k с семью адаптерами, при этом PVeRA показал лучшие результаты по сравнению с VeRA и другими адаптерами.

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

<iframe src="https://peft-internal-testing-peft-method-comparison-embed.hf.space/?highlight[type]=PVERA" frameborder="0" width="850" height="1000"
>

# API

## PveraConfig[[peft.PveraConfig]]

#### peft.PveraConfig[[peft.PveraConfig]]

```python
peft.PveraConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, r: int = 256, target_modules: Optional[Union[list[str], str]] = None, projection_prng_key: int = 0, save_projection: bool = True, pvera_dropout: float = 0.0, d_initial: float = 0.1, fan_in_fan_out: bool = False, bias: str = 'none', modules_to_save: Optional[list[str]] = None, init_weights: bool = True, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None, sample_at_inference: bool = False, generator_seed: Optional[int] = None)
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/pvera/config.py#L25)

**Параметры:**

r (`int`, *optional*, по умолчанию `256`) : размерность параметра PVeRA («ранг»). Здесь следует выбирать значения выше рангов LoRA, поскольку PVeRA разделяет параметры между слоями и, следовательно, использует значительно меньше параметров, чем LoRA.

target_modules (`Union[List[str], str]`) : Имена модулей, к которым следует применить PVeRA. Поддерживаются только линейные слои. При передаче строки выполняется сопоставление по регулярному выражению. Если указано значение 'all-linear', выбираются все линейные/Conv1D модули. Если это поле не указано, модули выбираются в соответствии с архитектурой модели. Если архитектура неизвестна, будет выброшено исключение.

projection_prng_key (`int`) : ключ инициализации PRNG PVeRA. Используется для инициализации pvera_A и pvera_B для новых моделей или при загрузке контрольной точки, не содержащей эти проекции. По умолчанию `0`.

save_projection (`bool`) : Сохранять ли проекции pvera_A / pvera_B в state dict вместе с весами lambda_b / lambda_d для каждого слоя. Это увеличит размер контрольной точки, но гарантирует возможность перезагрузки контрольной точки на всех конфигурациях системы. По умолчанию `True`.

pvera_dropout (`float`) : Вероятность dropout для слоёв PVeRA.

d_initial (`float`, *optional*, по умолчанию `0.1`) : Начальное значение вектора `pvera_lambda_d`, используемое при инициализации параметров PVeRA. Рекомендуется использовать малые значения (<=0.1).

fan_in_fan_out (`bool`) : Установите это значение в True, если заменяемый слой хранит веса в формате (fan_in, fan_out). Например, gpt-2 использует `Conv1D`, который хранит веса в формате (fan_in, fan_out), поэтому это значение должно быть установлено в `True`.

bias (`str`) : Тип смещения для PVeRA. Может принимать значения 'none', 'all' или 'pvera_only'. Если указано 'all' или 'pvera_only', соответствующие смещения будут обновляться во время обучения. Обратите внимание, что это означает: даже при отключении адаптеров модель не будет выдавать тот же результат, что и базовая модель без адаптации.

modules_to_save (`List[str]`) : Список модулей, кроме слоёв PVeRA, которые должны быть установлены как обучаемые и сохранены в итоговый контрольный пункт.

init_weights (`bool`) : Инициализировать ли веса слоёв PVeRA с использованием их начальной инициализации по умолчанию. Не изменяйте этот параметр, если вы точно не знаете, что делаете.

layers_to_transform (`Union[List[int],int]`) : Индексы слоёв для преобразования. Если этот аргумент указан, преобразования PVeRA применяются к слоям с индексами, указанными в этом списке. Если передано одно целое число, преобразования PVeRA применяются к слою с этим индексом.

layers_pattern (`Optional[Union[List[str], str]]`) : Имя шаблона слоя, используется только в том случае, если `layers_to_transform` отличается от `None`. Это должно указывать на `nn.ModuleList` модели, который часто называется `'layers'` или `'h'`.

sample_at_inference (`bool`, по умолчанию `False`) : Использовать ли выборку из обученного распределения PVeRA при инференсе. Если False, используется обученное среднее значение.

generator_seed (`int`, по умолчанию None) : Случайное зерно для генератора, используемого для выборки из изученного распределения.

Это класс конфигурации для хранения конфигурации модели [PveraModel](/docs/peft/main/ru/package_reference/pvera#peft.PveraModel).

Статья: https://www.arxiv.org/abs/2512.07703.

## PveraModel[[peft.PveraModel]]

#### peft.PveraModel[[peft.PveraModel]]

```python
peft.PveraModel(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/pvera/model.py#L35)

**Параметры:**

model ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)): модель, подлежащая адаптации.

config ([PveraConfig](/docs/peft/main/ru/package_reference/pvera#peft.PveraConfig)) : конфигурация модели PVeRA.

adapter_name (`str`) : Имя адаптера, по умолчанию `"default"`.

low_cpu_mem_usage (`bool`, `optional`, по умолчанию `False`) : Создать пустые веса адаптера на мета-устройстве. Полезно для ускорения процесса загрузки.

**Возвращает:** `torch.nn.Module`

Модель PVeRA.

Создаёт модель Probabilistic Vector-based Random Matrix Adaptation (PVeRA) на основе предобученной модели transformers.

Пример:

```py
>>> from transformers import AutoModel
>>> from peft import PveraConfig, get_peft_model

>>> base_model = AutoModel.from_pretrained("facebook/dinov2-base")
>>> config = PveraConfig(r=128, sample_at_inference=False)
>>> model = get_peft_model(base_model, config)
```

**Атрибуты**:
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) -- Модель, подлежащая адаптации.
- **peft_config** ([PveraConfig](/docs/peft/main/ru/package_reference/pvera#peft.PveraConfig)): конфигурация модели PVeRA.

