# LoKr

    

探索文本到图像生成的定制化：从 LyCORIS 微调至模型评估

低秩 Kronecker 积（[LoKr](https://hf.co/papers/2309.14859)）是一种 LoRA 变体方法，它使用两个低秩矩阵来近似大型权重矩阵，并通过 [Kronecker 积](https://en.wikipedia.org/wiki/Kronecker_product)将它们组合起来。LoKr 还提供了一个可选的第三个低秩矩阵，以便在微调过程中提供更好的控制。通过将权重更新矩阵表示为 Kronecker 积的分解并构建分块矩阵，LoKr 能够保留原始权重矩阵的秩。较小矩阵的大小由其 *rank* 或 `r` 决定。Kronecker 积的另一个优势是可以通过堆叠矩阵列来实现向量化。这可以加速处理过程，因为你避免了完全重构 ∆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/v0.22.0/src/peft/tuners/lokr/config.py#L24)

**参数：**

r (`int`) : LoKr 秩。

alpha (`int`) : LoKr 缩放的 alpha 参数。

rank_dropout (`float`) : 训练期间秩维度的 dropout 概率。

module_dropout (`float`) : 训练期间禁用 LoKr 模块的 dropout 概率。

use_effective_conv2d (`bool`) : 对 ksize > 1 的 Conv2d（以及 Conv1d）使用参数有效分解（FedPara 论文中的“命题 3”）。

decompose_both (`bool`) : 对左侧克罗内克积矩阵执行秩分解。

decompose_factor (`int`) : Kronecker 积分解因子。

rank_dropout_scale ('bool) : 是否在训练时缩放秩丢弃，默认为 `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` 指定的默认 rank 不同的 rank 的映射。例如，`{'^model.decoder.layers.0.encoder_attn.k_proj': 16}`。

alpha_pattern (`dict`) : 从层名称或正则表达式到与 `alpha` 指定的默认 alpha 不同的 alpha 值的映射。例如，`{'^model.decoder.layers.0.encoder_attn.k_proj': 16}`。

modules_to_save (`Optional[List[str]]`) : 除适配器层外，需要设置为可训练并保存在最终检查点中的模块列表。

[LoKrModel](/docs/peft/v0.22.0/zh/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/v0.22.0/src/peft/tuners/lokr/model.py#L27)

**参数：**

model (`torch.nn.Module`)：将挂载适配器调优层的模型。

config ([LoKrConfig](/docs/peft/v0.22.0/zh/package_reference/lokr#peft.LoKrConfig))：LoKr 模型的配置。

adapter_name (`str`) : 适配器的名称，默认为 `"default"`。

low_cpu_mem_usage (`bool`, `optional`, 默认为 `False`) : 在 meta 设备上创建空的适配器权重。有助于加快加载过程。

**返回：** `torch.nn.Module`

LoKr 模型。

从预训练模型创建低秩 Kronecker 积模型。原始方法部分描述于 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 LoKrConfig, get_peft_model

>>> config_te = LoKrConfig(
...     r=8,
...     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,
...     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 = get_peft_model(model.text_encoder, config_te)
>>> model.unet = get_peft_model(model.unet, config_unet)
```

**属性**：
- **model** (`~torch.nn.Module`) -- 要适配的模型。
- **peft_config** ([LoKrConfig](/docs/peft/v0.22.0/zh/package_reference/lokr#peft.LoKrConfig)): LoKr 模型的配置。

