# Lily: низко-ранговая адаптация с межслойными связями

[Lily](https://huggingface.co/papers/2407.09946) — это метод эффективной дообучения, вводящий обмен весами между слоями для матриц адаптеров. Вместо обучения независимой пары AB для каждого слоя, как в LoRA, Lily использует **локально общие адаптеры A** (каждый A общий для блока из `stride_A` последовательных слоёв) и **глобально общие эксперты B** (небольшой пул из `num_B` адаптеров B общий для всех слоёв). На каждом прямом проходе лёгкий роутер, зависящий от данных, вычисляет комбинацию экспертов B с весами softmax, чтобы получить эффективный B для данного слоя и входа.

Такой подход позволяет сократить общее количество матриц адаптеров с `2N` (стандартный LoRA) до `N / stride_A + num_B`, высвобождая бюджет параметров для использования **значительно большего ранга `r`** — как правило, в `2×`–`4×` раз больше, чем в LoRA. Более высокий ранг и лучшая связанность увеличивают эффективный ранг обновления весов `ΔW = A × combined_B`, что приводит к улучшению качества адаптации.

Поскольку комбинация B является **зависимой от данных** (веса маршрутизатора зависят от активаций на входе во время выполнения), `merge` и `unmerge` **не поддерживаются**. Если для вашего развертывания требуется объединение весов, рассмотрите другие методы, такие как LoRA.

В настоящее время у Lily есть следующие дополнительные ограничения:
- Поддерживаются только слои `nn.Linear`.
- Квантованные слои не поддерживаются.

Если эти ограничения не подходят для вашего сценария использования, рассмотрите другие методы.

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

> Метод адаптации низкого ранга (LoRA) — это широко используемый параметрически эффективный метод дообучения (PEFT), который обучает обновления весов ΔW = AB для предобученных весов W с помощью адаптеров низкого ранга A и B. Хотя LoRA обеспечивает эффективность использования аппаратных средств, обновления весов низкого ранга ограничивают качество адаптации. В данной статье мы предлагаем метод адаптации низкого ранга с межслойными связями (Lily) — новый метод PEFT, который вводит взаимосвязанную архитектуру с локально общими экспертами A и глобально общими экспертами B. Эта структура устраняет избыточные пары AB для каждого слоя, позволяя получать ΔW более высокого ранга при том же или меньшем количестве параметров. Для повышения выразительности мы используем маршрутизаторы, зависящие от данных, для определения связей между A и B, что предотвращает сходимость экспертов B к одинаковому поведению и улучшает способность представления в различных областях. Эксперименты на разных модальностях, архитектурах и размерах моделей демонстрируют превосходство Lily по производительности и эффективности.

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

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

# API

## LilyConfig[[peft.LilyConfig]]

#### peft.LilyConfig[[peft.LilyConfig]]

```python
peft.LilyConfig(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 = 32, stride_A: int = 1, num_B: int = 2, scaling: float = 1.0, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, modules_to_save: Optional[list[str]] = None, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None, init_weights: bool = True)
```

[Источник](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/lily/config.py#L24)

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

r (`int`) : ранг Lily. Определяет внутреннее скрытое измерение каждого адаптера и ранг обновления весов `A @ B`. В Lily количество адаптеров обычно меньше, чем в LoRA, поэтому каждому адаптеру требуется большая ёмкость, и рекомендуется использовать значение `r` больше, чем в LoRA, — как правило, `2x`, `3x` или `4x` от ранга LoRA, который вы обычно применяете. Общее количество обучаемых параметров масштабируется по формуле `r * (total_layers / stride_A + num_B)`, поэтому рекомендуемый компромисс — увеличивать `r`, сохраняя `stride_A` большим, а `num_B` — малым.

stride_A (`int`) : Количество последовательных слоев, разделяющих один адаптер A. Например, если `stride_A=4`, то каждые 4 соседних слоя используют один и тот же адаптер A, в результате чего всего получается `total_layers / stride_A` различных адаптеров A. Адаптер A сжимает входные данные до представления низкого ранга размера `r`. Значение `stride_A` должно быть не меньше 1. Рекомендуемые значения: `2`, `3` или `4` (то есть разделение каждые 2, 3 или 4 слоя). Сохранение большого значения `stride_A` (меньше различных адаптеров A) и одновременное увеличение `r` приводит к лучшей производительности, чем обратный компромисс (малое `stride_A`, малое `r`). Установка `stride_A=1` означает, что каждый слой имеет собственный адаптер A. Примечание: разделение адаптеров A происходит внутри каждой целевой группы (слои с одинаковым суффиксом целевого модуля). Например, если ваши target_modules равны `['q_proj', 'v_proj']` и вы установили `stride_A=2`, то каждые 2 соседних слоя q_proj будут разделять один адаптер A, а каждые 2 соседних слоя v_proj — другой адаптер A, но слои q_proj и v_proj не будут разделять адаптеры A друг с другом, так как у них разные суффиксы.

num_B (`int`) : Количество разделяемых B-адаптеров. В отличие от A-адаптеров (которые группируются по слоям), все B-адаптеры разделяются глобально между всеми слоями. При каждом прямом проходе роутер вычисляет взвешенную комбинацию всех `num_B` B-адаптеров (используя веса, нормированные функцией softmax), чтобы получить единый объединённый B-адаптер, который затем проецирует представление низкого ранга обратно в исходное измерение. Рекомендуется устанавливать `num_B` в том же порядке, что и `total_layers / stride_A`. Рекомендуемые значения: `total_layers / 2`, `total_layers / 3` или `total_layers / 4`. Аналогично `stride_A`, предпочтительнее использовать меньшее `num_B` с большим `r`, чем большое `num_B` с малым `r`. Примечание: для обучения роутера необходимо как минимум 2 B-адаптера (т. е. `num_B >= 2`), поскольку роутер обучается вычислять взвешенную комбинацию B-адаптеров. Примечание: разделение B-адаптеров происходит внутри каждой целевой группы (слои с одинаковым суффиксом целевого модуля). Например, если ваши target_modules равны `['q_proj', 'v_proj']` и вы установили `num_B=4`, то будет 4 B-адаптера, разделяемых между всеми слоями q_proj, и ещё 4 B-адаптера, разделяемых между всеми слоями v_proj, однако слои q_proj и v_proj не будут разделять B-адаптеры друг с другом, так как у них разные суффиксы.

target_modules (`Union[List[str], str]`, *необязательный*) : Имена модулей, к которым следует применить Lily. Может быть списком строк с именами модулей (например, `['q_proj', 'v_proj']`) или регулярным выражением (например, `'.*decoder.*(SelfAttention|EncDecAttention).*(q|v)$'`). Если не указано, Lily будет применена ко всем поддерживаемым линейным слоям.

scaling (`float`) : Скалярный множитель, применяемый к объединённому выводу адаптера (`scaling * A @ combined_B`) перед добавлением к прямому пропуску замороженных весов. В отличие от LoRA, Lily не использует формулировку `alpha / r`; вместо этого `scaling` является прямым множителем. Такой подход упрощает перебор значений по логарифмической шкале (например, `0.01`, `0.1`, `1.0`, `10.0`). Оптимальное значение зависит от задачи и должно рассматриваться как гиперпараметр. Рекомендуем начинать со значения `1.0`.

modules_to_save (`List[str]`, *необязательный*) : Список модулей, кроме слоёв Lily, которые должны быть установлены как обучаемые и сохранены в итоговый контрольный пункт. Например, в задачах классификации последовательностей или классификации токенов последний слой `classifier/score` инициализируется случайно и, следовательно, должен быть обучаемым и сохранённым.

exclude_modules (`Union[List[str], str]`, *необязательный*) : Имена модулей, к которым не следует применять адаптер. При передаче строки выполняется сопоставление по регулярному выражению. При передаче списка строк выполняется точное совпадение или проверяется, заканчивается ли имя модуля каким-либо из переданных строк.

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

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

init_weights (`bool`) : Инициализировать веса адаптера Lily с использованием схемы по умолчанию: матрицы A инициализируются методом Kaiming uniform, а матрицы B — нулями, что гарантирует нулевой выход адаптера в начале обучения и отсутствие влияния на предобученную модель. Настоятельно рекомендуется оставить это значение равным `True`, если у вас нет конкретной причины для его изменения.

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

## LilyModel[[peft.LilyModel]]

#### peft.LilyModel[[peft.LilyModel]]

```python
peft.LilyModel(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/v0.22.0/src/peft/tuners/lily/model.py#L30)

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

model (`torch.nn.Module`) : модель, подлежащая адаптации.

config ([LilyConfig](/docs/peft/v0.22.0/ru/package_reference/lily#peft.LilyConfig)) : конфигурация модели Lily.

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

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

Модель Lily PEFT.

Создаёт модель Low-Rank Interconnected Adaptation Across Layers (Lily) на основе предобученной модели transformers.

Метод подробно описан в https://arxiv.org/abs/2407.09946.

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

