# AdaLoRA

[AdaLoRA](https://hf.co/papers/2303.10512)（Adaptive LoRA）是一种用于优化分配给权重矩阵和层数的可训练参数数量的方法，与在所有模块间均匀分配参数的 LoRA 不同。该方法会为重要的权重矩阵和层分配更多的参数预算，而为不太重要的部分分配更少的参数。您可以控制矩阵的平均期望 *rank* 或 `r`，并通过 `target_modules` 指定将 AdaLoRA 应用于哪些模块。其他需要设置的重要参数包括 `lora_alpha`（缩放因子）和 `modules_to_save`（除 AdaLoRA 层之外需要训练并保存的模块）。所有这些参数——以及更多参数——都可以在 [AdaLoraConfig](/docs/peft/v0.22.0/zh/package_reference/adalora#peft.AdaLoraConfig) 中找到。

该论文的摘要如下：

*在下游任务上对大型预训练语言模型进行微调已成为自然语言处理中的一个重要范式。然而，常见的做法是微调预训练模型中的所有参数，当存在大量下游任务时，这种做法会变得难以承受。因此，许多微调方法被提出，以参数高效的方式学习预训练权重的增量更新，例如低秩增量。这些方法通常将增量更新的预算均匀地分配给所有预训练权重矩阵，而忽略了不同权重参数的重要性差异。因此，微调性能往往不是最优的。为了弥补这一差距，我们提出了 AdaLoRA，它根据权重矩阵的重要性分数自适应地在它们之间分配参数预算。具体而言，AdaLoRA 以奇异值分解的形式参数化增量更新。这种新颖的方法使我们能够有效地剪枝不重要更新的奇异值，这本质上是在减少其参数预算的同时，避免了密集且精确的 SVD 计算。我们在自然语言处理、问答和自然语言生成任务上，使用多个预训练模型进行了大量实验，以验证 AdaLoRA 的有效性。结果表明，与基线方法相比，AdaLoRA 表现出显著的性能提升，尤其是在低预算设置下。我们的代码已公开在 https://github.com/QingruZhang/AdaLoRA*

> [!WARNING]
> AdaLoRA 提供了一个 [update_and_allocate()](/docs/peft/v0.22.0/zh/package_reference/adalora#peft.AdaLoraModel.update_and_allocate) 方法，应在每个训练步骤中调用，以更新参数预算和掩码，否则将不会执行适配步骤。这需要编写自定义训练循环，或对 [Trainer](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.Trainer) 进行子类化以集成该方法。示例请参见此 [自定义训练循环](https://github.com/huggingface/peft/blob/912ad41e96e03652cabf47522cd876076f7a0c4f/examples/conditional_generation/peft_adalora_seq2seq.py#L120)。

AdaLoRA 通过为对任务适应性更好的重要权重矩阵分配更多参数——即更高的秩 `r`——并剪枝不太重要的矩阵，来管理由 LoRA 引入的参数预算。秩的控制采用了一种类似于奇异值分解（SVD）的方法。$\Delta W$ 由两个正交矩阵和一个包含奇异值的对角矩阵参数化。这种参数化方法避免了迭代应用计算开销较大的 SVD。基于此方法，$\Delta W$ 的秩会根据重要性分数进行调整。$\Delta W$ 被划分为三元组，每个三元组根据其模型性能贡献进行评分。重要性分数较低的三元组会被剪枝，而重要性分数较高的三元组则被保留用于微调。

使用 AdaLoRA 进行训练包含三个阶段：初始化阶段、预算分配阶段和最终阶段。在初始化阶段，不应用预算分配，因此秩保持不变。在预算分配阶段，应用上述流程，并根据预算重新分配秩，旨在为更重要的适配器分配更多的秩，为较不重要的层分配更少的秩。进入最终阶段时，预算分配结束，秩已被重新分配，但我们可以使用重新分配后的秩继续训练一段时间，以进一步提升性能。

> [!NOTE]
> **欢迎贡献**：本节需要进一步澄清。
>
> 目前尚不清楚重要性是如何衡量的。此外，相关解释也略显冗余，建议进行整合。有关如何贡献，请参阅[此处](../developer_guides/contributing#documentation-improvements)。

## 基准测试概览

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

## 用法

```py
from peft import AdaLoraConfig, get_peft_model

config = AdaLoraConfig(
    r=8,
    init_r=12,
    tinit=200,
    tfinal=1000,
    deltaT=10,
    target_modules=["query", "value"],
    modules_to_save=["classifier"],
)
model = get_peft_model(model, config)
model.print_healthcheck()

[... training code ...]

model.update_and_allocate(step_idx)
```

# API

## AdaLoraConfig[[peft.AdaLoraConfig]]

#### peft.AdaLoraConfig[[peft.AdaLoraConfig]]

```python
peft.AdaLoraConfig(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 = 8, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, lora_alpha: int = 8, lora_dropout: float = 0.0, fan_in_fan_out: bool = False, bias: Literal['none', 'all', 'lora_only'] = 'none', use_rslora: bool = False, modules_to_save: Optional[list[str]] = None, init_lora_weights: bool | Literal['gaussian', 'eva', 'olora', 'pissa', 'pissa_niter_[number of iters]', 'corda', 'astra', 'loftq', 'orthogonal', 'mica', 'nora'] = True, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None, rank_pattern: dict | None = None, alpha_pattern: Optional[dict] = <factory>, megatron_config: Optional[dict] = None, megatron_core: Optional[str] = 'megatron.core', trainable_token_indices: Optional[Union[list[int], dict[str, list[int]]]] = None, loftq_config: Union[LoftQConfig, dict] = <factory>, eva_config: Optional[EvaConfig] = None, corda_config: Optional[CordaConfig] = None, astra_config: Optional[AstraConfig] = None, lora_ga_config: Optional[LoraGAConfig] = None, use_dora: bool = False, velora_config: Optional[Union[VeloraConfig, dict]] = None, alora_invocation_tokens: Optional[list[int]] = None, use_qalora: bool = False, qalora_group_size: int = 16, monteclora_config: Optional[MontecloraConfig] = None, layer_replication: Optional[list[tuple[int, int]]] = None, runtime_config: LoraRuntimeConfig = <factory>, lora_bias: bool = False, target_parameters: Optional[list[str]] = None, use_bdlora: Optional[BdLoraConfig] = None, arrow_config: Optional[ArrowConfig] = None, kasa_config: Optional[KasaConfig] = None, ensure_weight_tying: bool = False, target_r: int = 8, init_r: int = 12, tinit: int = 0, tfinal: int = 0, deltaT: int = 1, beta1: float = 0.85, beta2: float = 0.85, orth_reg_weight: float = 0.5, total_step: int | None = None)
```

[源代码](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/adalora/config.py#L24)

**参数：**

target_r (`int`) : 增量矩阵的目标平均秩。

init_r (`int`) : 每个增量矩阵的初始秩。

tinit (`int`) : 初始微调的预热步数。

tfinal (`int`) : 最终微调的步数。

deltaT (`int`) : 两次预算分配之间的时间间隔。

beta1 (`float`) : 用于敏感性平滑的 EMA 超参数。

beta2 (`float`) : 用于不确定性量化的 EMA 超参数。

orth_reg_weight (`float`) : 正交正则化的系数。

total_step (`int`) : 在训练开始前应指定的总训练步数。

rank_pattern (`list`) : RankAllocator 为每个权重矩阵分配的秩。

这是用于存储 [AdaLoraModel](/docs/peft/v0.22.0/zh/package_reference/adalora#peft.AdaLoraModel) 配置的类。

AdaLoRA 由 `tinit`、`tfinal` 和 `total_step` 定义了三个阶段。

初始阶段可以理解为对适配器进行预训练的一个步骤，这样在降低其秩时，就已经编码了一些可被压缩的信息，而不是随机矩阵。该阶段通过提供 `tinit` 来定义。

在初始阶段结束（即经过 `tinit` 步）且最终阶段尚未开始时，AdaLoRA 会在每一步中减少每层允许的秩预算。秩的缩减正是在此阶段发生的。这一过程会持续到达到 `total_step - tfinal` 步为止。

最后一个阶段从达到 `total_step - tfinal` 步时开始，不再更改层的秩，而是对前一阶段产生的降秩层进行微调。

一个实际的例子：`tinit` 为 10，`tfinal` 为 20，`total_step` 为 100。我们花费 10 步进行预训练，期间不进行秩缩减，因为我们的预算是恒定的（初始化阶段）；然后，我们花费 80（100-20）步进入缩减阶段，在此期间我们的预算逐步减少；最后，我们花费 20 步进行最终微调阶段，期间不进行缩减。

## AdaLoraModel[[peft.AdaLoraModel]]

#### peft.AdaLoraModel[[peft.AdaLoraModel]]

```python
peft.AdaLoraModel(model, config, adapter_name, **kwargs)
```

[源代码](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/adalora/model.py#L36)

**参数：**

model ([transformers.PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel))：要适配的模型。

config ([AdaLoraConfig](/docs/peft/v0.22.0/zh/package_reference/adalora#peft.AdaLoraConfig))：AdaLora 模型的配置。

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

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

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

AdaLora 模型。

从预训练的 transformers 模型创建 AdaLoRA（自适应 LoRA）模型。论文：https://openreview.net/forum?id=lq62uWRJjiY

示例：
```py
>>> from transformers import AutoModelForSeq2SeqLM
>>> from peft import AdaLoraConfig, get_peft_model

>>> config = AdaLoraConfig(
...     peft_type="ADALORA",
...     task_type="SEQ_2_SEQ_LM",
...     init_r=12,
...     lora_alpha=32,
...     target_modules=["q", "v"],
...     lora_dropout=0.01,
...     total_step=1000,
... )
>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> adalora_model = get_peft_model(model, config)
```

**属性**：
- **model** ([transformers.PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel)) -- 要适配的模型。
- **peft_config** ([AdaLoraConfig](/docs/peft/v0.22.0/zh/package_reference/adalora#peft.AdaLoraConfig)): AdaLora 模型的配置。

#### add_weighted_adapter[[peft.AdaLoraModel.add_weighted_adapter]]

```python
add_weighted_adapter(*args, **kwargs)
```

[源代码](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/adalora/model.py#L370)

此方法不适用于 AdaLoRA，请改用 LoRA。

#### update_and_allocate[[peft.AdaLoraModel.update_and_allocate]]

```python
update_and_allocate(global_step)
```

[源代码](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/adalora/model.py#L328)

**参数：**

global_step (`int`) : 当前训练步数，用于计算 adalora 预算。

此方法用于更新 Adalora 的预算和掩码。

应在每个训练步骤中，在 `loss.backward()` 之后、`zero_grad()` 之前调用此方法。

`tinit`、`tfinal` 和 `deltaT` 在方法内部进行处理。

示例：

```python
>>> loss = model(**input).loss
>>> loss.backward()
>>> optimizer.step()
>>> model.base_model.update_and_allocate(i_step)
>>> optimizer.zero_grad()
```

