# VB-LoRA：使用向量库实现极致的参数高效微调

## 概述

[VB-LoRA](https://huggingface.co/papers/2405.15179) 是一种参数高效微调技术，它通过在学习子向量级别的细粒度参数共享方案来扩展 LoRA，从而实现了显著更高的参数效率。这使得 VB-LoRA 在存储和传输成本至关重要的场景中尤为有用。其工作原理是将来自不同层和模块（如 K、Q、V 和 FFN）的低秩矩阵分解为子向量，然后通过向量库对这些子向量进行全局共享。

该论文的摘要如下：

*随着大语言模型应用的普及以及对按用户或按任务进行模型定制的需求日益增长，参数高效微调（PEFT）方法（如低秩适应（LoRA）及其变体）带来了巨大的存储和传输成本。为了进一步减少存储参数，我们提出了一种“分治共享”范式，通过向量库全局共享参数，打破了低秩分解在矩阵维度、模块和层之间的壁垒。作为该范式在 LoRA 上的具体实现，我们提出的 VB-LoRA 利用可微分的 top-k 混合模块，从共享向量库中组合出 LoRA 的所有低秩矩阵。VB-LoRA 在保持与最先进的 PEFT 方法相当甚至更优性能的同时，实现了极致的参数效率。大量实验证明了 VB-LoRA 在自然语言理解、自然语言生成和指令微调任务上的有效性。在对 Llama2-13B 模型进行微调时，VB-LoRA 仅使用了 LoRA 存储参数的 0.4%，却取得了更优的结果。*

## 使用技巧

- VB-LoRA 利用稀疏 top-k 模块来学习共享机制。在保存适配器参数时，您可以在 `VBLoRAConfig` 中设置 `save_only_topk_weights = True`，仅保存 top-k 权重及其索引；或者将其设置为 `False`，保存所有可训练的 logits。启用 `save_only_topk_weights = True` 可显著减少存储空间；例如，在 Llama2-7B 中，存储文件大小从 308MB 降低至 2.5MB。请注意，使用 `save_only_topk_weights = True` 保存的模型仅用于合并或推理，不能用于恢复训练。

- VB-LoRA 包含两组训练参数：向量库参数和 logit 参数。在实践中，我们发现 logit 参数需要更高的学习率，而向量库参数需要更低的学习率。使用 AdamW 优化器时，典型的学习率为：logit 参数 0.01，向量库参数 0.001。

## 基准测试概览

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

# API

## VBLoRAConfig[[peft.VBLoRAConfig]]

#### peft.VBLoRAConfig[[peft.VBLoRAConfig]]

```python
peft.VBLoRAConfig(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 = 4, num_vectors: int = 256, vector_length: int = 256, topk: int = 2, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, save_only_topk_weights: bool = False, vblora_dropout: float = 0.0, fan_in_fan_out: bool = False, bias: str = 'none', modules_to_save: Optional[list[str]] = None, init_vector_bank_bound: float = 0.02, init_logits_std: float = 0.1, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None)
```

[源代码](https://github.com/huggingface/peft/blob/main/src/peft/tuners/vblora/config.py#L25)

**参数：**

r (`int`) : 增量矩阵的秩。

num_vectors (`int`) : 向量库中的向量数量。当模型规模增大时，请使用更高的值。

vector_length (`int`) : 向量库中向量的长度。向量长度应能被模型的隐藏维度整除。

topk (`int`) : 用于 top-K 选择的 K 值。K 值越大，保存的模型尺寸越大。在实践中，设置 K=2 通常能提供最佳的性能和参数效率。更多细节请参阅论文中的讨论。

target_modules (`Union[List[str], str]`) : 要应用适配器的模块名称。如果指定了此参数，则只会替换具有指定名称的模块。传入字符串时，将执行正则表达式匹配。传入字符串列表时，将执行精确匹配，或检查模块名称是否以传入的字符串之一结尾。如果指定为 'all-linear'，则选择所有线性/Conv1D 模块，但不包括输出层。如果未指定，则根据模型架构选择模块。如果架构未知，则会引发错误——在这种情况下，应手动指定目标模块。

exclude_modules (`Optional[Union[List[str], str]]`) : 不应用适配器的模块名称。传入字符串时，将执行正则表达式匹配。传入字符串列表时，将执行精确匹配，或检查模块名称是否以传入的任一字符串结尾。

save_only_topk_weights (`bool`) : 是否仅保存 topk 权重。将 `save_only_topk_weights = True` 可显著减少存储空间。但以此模式保存的模型仅可用于合并或推理，不能用于恢复训练。

vblora_dropout (`float`) : VBLoRA 层的 dropout 概率。

fan_in_fan_out (`bool`) : 如果待替换的层以 (fan_in, fan_out) 的形式存储权重，请将此项设置为 True。例如，gpt-2 使用的 `Conv1D` 以 (fan_in, fan_out) 的形式存储权重，因此应将其设置为 `True`。

bias (`str`) : VBLoRA 的偏置类型。可以是 'none'、'all' 或 'vblora_only'。如果设置为 'all' 或 'vblora_only'，相应的偏置将在训练期间被更新。请注意，这意味着即使禁用了适配器，模型的输出也不会与未进行适配的基础模型相同。

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

init_vector_bank_bound (`float`) : 向量库在 -init_vector_bank_bound 和 init_vector_bank_bound 之间以均匀分布进行初始化。请避免将向量库初始化为全零，以防止梯度为零。通常，较小的值（例如 0.02）效果较好。使用较大的值进行初始化可能会导致训练不稳定。

init_logits_std (`float`) : logits 使用标准差为 init_logits_std 的正态分布进行初始化。默认值为 0.1。

layers_to_transform (`Union[List[int],int]`) : 要转换的层索引。如果传入一个整数列表，则会将适配器应用于该列表中指定的层索引。如果传入单个整数，则会对该索引处的层应用转换。

layers_pattern (`Optional[Union[List[str], str]]`) : 层模式名称，仅在 `layers_to_transform` 不同于 `None` 时使用。它应指向模型的 `nn.ModuleList`，通常命名为 `'layers'` 或 `'h'`。

这是用于存储 [VBLoRAModel](/docs/peft/main/zh/package_reference/vblora#peft.VBLoRAModel) 配置的类。

论文：https://huggingface.co/papers/2405.15179

## VBLoRAModel[[peft.VBLoRAModel]]

#### peft.VBLoRAModel[[peft.VBLoRAModel]]

```python
peft.VBLoRAModel(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/vblora/model.py#L29)

**参数：**

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

config ([VBLoRAConfig](/docs/peft/main/zh/package_reference/vblora#peft.VBLoRAConfig))：VBLoRA 模型的配置。

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

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

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

VBLoRA 模型。

从预训练的 transformers 模型创建 VBLoRA 模型。

该方法的详细描述见 https://huggingface.co/papers/2405.15179。

示例：

```py
>>> from transformers import AutoModelForCausalLM
>>> from peft import VBLoRAConfig, get_peft_model

>>> base_model = AutoModelForCausalLM.from_pretrained("facebook/opt-125m")
>>> config = VBLoRAConfig(
...     task_type="SEQ_CLS",
...     r=4,
...     target_modules=["fc1", "fc2", "k_proj", "out_proj", "q_proj", "v_proj"],
...     num_vectors=60,
...     vector_length=256,
...     save_only_topk_weights=True,
... )
>>> model = get_peft_model(base_model, config)
```

**属性**：
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) -- 要适配的模型。
- **peft_config** ([VBLoRAConfig](/docs/peft/main/zh/package_reference/vblora#peft.VBLoRAConfig)): VBLoRAConfig 模型的配置。

#### get_nb_savable_parameters[[peft.VBLoRAModel.get_nb_savable_parameters]]

```python
get_nb_savable_parameters(adapter = 'default')
```

[源代码](https://github.com/huggingface/peft/blob/main/src/peft/tuners/vblora/model.py#L158)

返回可保存的 VB-LoRA 参数数量以及其他可保存参数的数量。

#### print_savable_parameters[[peft.VBLoRAModel.print_savable_parameters]]

```python
print_savable_parameters()
```

[源代码](https://github.com/huggingface/peft/blob/main/src/peft/tuners/vblora/model.py#L194)

打印可保存的 VB-LoRA 参数数量和可保存的总参数数量。

