# LoKr

    

Настройка генерации изображений по тексту: от дообучения LyCORIS до оценки модели

Метод низкорангового произведения Кронекера ([LoKr](https://hf.co/papers/2309.14859)) представляет собой вариант LoRA, который аппроксимирует большую матрицу весов с помощью двух низкоранговых матриц и объединяет их с помощью [произведения Кронекера](https://en.wikipedia.org/wiki/Kronecker_product). LoKr также предоставляет опциональную третью низкоранговую матрицу для более точного контроля в процессе дообучения. Выражая матрицу обновления весов как разложение произведения Кронекера и формируя блочную матрицу, LoKr сохраняет ранг исходной матрицы весов. Размер меньших матриц определяется их *рангом* или `r`. Ещё одно преимущество произведения Кронекера состоит в том, что его можно векторизовать, складывая столбцы матрицы. Это ускоряет процесс, поскольку позволяет избежать полного восстановления ∆W.

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

*Генеративные модели «текст в изображение» привлекли огромное внимание благодаря своей способности создавать изображения высокого качества по текстовым запросам. Среди них Stable Diffusion выделяется как ведущая модель с открытым исходным кодом в этой быстро развивающейся области. Однако тонкости дообучения этих моделей создают множество проблем, от интеграции новых методологий до систематической оценки. Решая эти задачи, в данной статье представлена LyCORIS [Lora beYond Conventional methods, Other Rank adaptation Implementations for Stable diffusion](https://github.com/KohakuBlueleaf/LyCORIS) — библиотека с открытым исходным кодом, предлагающая широкий выбор методологий дообучения для Stable Diffusion. Кроме того, мы представляем тщательный фреймворк для систематической оценки различных техник дообучения. Этот фреймворк использует разнообразный набор метрик и рассматривает множество аспектов дообучения, включая настройку гиперпараметров и оценку с использованием разных типов запросов в различных категориях концептов. Благодаря этому комплексному подходу наша работа дает важные представления о тонких эффектах параметров дообучения, сокращая разрыв между передовыми исследованиями и практическим применением.*

## Использование

```py
from peft import LoKrConfig, get_peft_model

config = LoKrConfig(
    r=16,
    alpha=16,
    target_modules=["query", "value"],
    module_dropout=0.1,
    modules_to_save=["classifier"],
)
model = get_peft_model(model, config)
model.print_healthcheck()
```

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

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

# API

## LoKrConfig[[peft.LoKrConfig]]

#### peft.LoKrConfig[[peft.LoKrConfig]]

```python
peft.LoKrConfig(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, rank_pattern: Optional[dict] = <factory>, alpha_pattern: Optional[dict] = <factory>, r: int = 8, alpha: int = 8, rank_dropout: float = 0.0, module_dropout: float = 0.0, use_effective_conv2d: bool = False, decompose_both: bool = False, decompose_factor: int = -1, rank_dropout_scale: bool = False, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, init_weights: Union[bool, Literal['lycoris']] = True, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None, modules_to_save: Optional[list[str]] = None)
```

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

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

r (`int`) : ранг LoKr.

alpha (`int`) : Параметр alpha для масштабирования LoKr.

rank_dropout (`float`) : Вероятность dropout для размерности rank во время обучения.

module_dropout (`float`) : Вероятность dropout для отключения модулей LoKr во время обучения.

use_effective_conv2d (`bool`) : Использовать эффективное разложение параметров для Conv2d (и Conv1d) с ksize > 1 («Proposition 3» из статьи FedPara).

decompose_both (`bool`) : Выполнить разложение по рангу матрицы левого произведения Кронекера.

decompose_factor (`int`) : фактор разложения по тензорному произведению Кронекера.

rank_dropout_scale ('bool) : Указывает, следует ли масштабировать dropout ранга во время обучения, по умолчанию `False`.

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

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

init_weights (`bool`) : Выполнять ли инициализацию весов адаптера. По умолчанию установлено значение `True`. Используйте "lycoris", чтобы инициализировать веса в стиле репозитория LYCORIS. Передача значения `False` не рекомендуется.

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`. Например, `{'^model.decoder.layers.0.encoder_attn.k_proj': 16}`.

alpha_pattern (`dict`) : Соответствие от имён слоёв или регулярных выражений к альфам, отличным от альфы по умолчанию, указанной в `alpha`. Например, `{'^model.decoder.layers.0.encoder_attn.k_proj': 16}`.

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

Класс конфигурации [LoKrModel](/docs/peft/main/ru/package_reference/lokr#peft.LoKrModel).

## LoKrModel[[peft.LoKrModel]]

#### peft.LoKrModel[[peft.LoKrModel]]

```python
peft.LoKrModel(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/lokr/model.py#L27)

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

model (`torch.nn.Module`) : модель, к которой будут прикреплены слои адаптивного тюнера.

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

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

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

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

Модель LoKr.

Создаёт модель Low-Rank Kronecker Product на основе предобученной модели. Исходный метод частично описан в https://huggingface.co/papers/2108.06098 и в https://huggingface.co/papers/2309.14859 Текущая реализация в значительной степени заимствована из https://github.com/KohakuBlueleaf/LyCORIS/blob/eb460098187f752a5d66406d3affade6f0a07ece/lycoris/modules/lokr.py

Пример:
```py
>>> from diffusers import StableDiffusionPipeline
>>> from peft import LoKrModel, LoKrConfig

>>> config_te = LoKrConfig(
...     r=8,
...     lora_alpha=32,
...     target_modules=["k_proj", "q_proj", "v_proj", "out_proj", "fc1", "fc2"],
...     rank_dropout=0.0,
...     module_dropout=0.0,
...     init_weights=True,
... )
>>> config_unet = LoKrConfig(
...     r=8,
...     lora_alpha=32,
...     target_modules=[
...         "proj_in",
...         "proj_out",
...         "to_k",
...         "to_q",
...         "to_v",
...         "to_out.0",
...         "ff.net.0.proj",
...         "ff.net.2",
...     ],
...     rank_dropout=0.0,
...     module_dropout=0.0,
...     init_weights=True,
...     use_effective_conv2d=True,
... )

>>> model = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
>>> model.text_encoder = LoKrModel(model.text_encoder, config_te, "default")
>>> model.unet = LoKrModel(model.unet, config_unet, "default")
```

**Атрибуты**:
- **model** (`~torch.nn.Module`) -- Модель, подлежащая адаптации.
- **peft_config** ([LoKrConfig](/docs/peft/main/ru/package_reference/lokr#peft.LoKrConfig)): конфигурация модели LoKr.