LoRA：大型语言模型的低秩适应

本仓库包含 Python 包 loralib 的源代码，以及如何将其与 PyTorch 模型（例如 Hugging Face 中的模型）集成的若干示例。目前我们仅支持 PyTorch。

有关 LoRA 的详细说明，请参阅我们的论文。

LoRA：大型语言模型的低秩适应
Edward J. Hu*, Yelong Shen*, Phillip Wallis, Zeyuan Allen-Zhu, Yuanzhi Li, Shean Wang, Lu Wang, Weizhu Chen
论文：https://arxiv.org/abs/2106.09685
视频讲解：https://www.youtube.com/watch?v=DhRoTONcyZE

更新：2023年2月，LoRA 现已由 Hugging Face 的 最先进的参数高效微调（PEFT） 库支持。

LoRA 通过学习一对秩分解矩阵来减少可训练参数的数量，同时冻结原始权重。这大大降低了针对特定任务进行适配的大型语言模型所需的存储空间，并在部署过程中实现了高效的多任务切换，且不会引入推理延迟。此外，LoRA 在性能上优于其他多种适配方法，包括 Adapter、前缀调优和全量微调。

我们在 GLUE 基准测试中，使用 RoBERTa (Liu et al., 2019) base 和 large 模型，以及 DeBERTa (He et al., 2020) XXL 1.5B 模型，获得了与全量微调相当或更优的结果，而仅需训练和存储极小部分的参数。点击下方链接即可下载 RoBERTa 和 DeBERTa 的 LoRA 检查点。

		RoBERTa base 全量微调	RoBERTa base LoRA	DeBERTa XXL 全量微调	DeBERTa XXL LoRA
	可训练参数数量	1.25亿	80万	15亿	470万
	MNLI (m-Acc/mm-Acc)	87.6	87.5±0.3/86.9±0.3	91.7/91.9	91.9±0.1/91.9±0.2
	SST2 (Acc)	94.8	95.1±0.2	97.2	96.9±0.2
	MRPC (Acc)	90.2	89.7±0.7	92.0	92.6±0.6
	CoLA (Matthew's Corr)	63.6	63.4±1.2	72.0	72.4±1.1
	QNLI (Acc)	92.8	93.3±0.3	96.0	96.0±0.1
	QQP (Acc)	91.9	90.8±0.1	92.7	92.9±0.1
	RTE (Acc)	78.7	86.6±0.7	93.9	94.9±0.4
	STSB (Pearson/Spearman 相关性)	91.2	91.5±0.2/91.3±0.2	92.9/92.6	93.0±0.2/92.9±0.3
	平均值	86.40	87.24	91.06	91.32

注：使用 LoRA 检查点时，仍需从 Hugging Face 获取原始预训练检查点。

全量微调的数据来自 Liu et al. (2019) 和 He et al. (2020)。我们为实验结果提供了置信区间。请按照 examples/NLU/ 中的说明操作，以复现我们的结果。

在 GPT-2 上，LoRA 的表现优于全量微调以及其他高效调优方法，例如 Adapter (Houlsby et al., 2019) 和 前缀调优 (Li and Liang, 2021)。我们在 E2E NLG Challenge、DART 和 WebNLG 数据集上进行了评估：

	方法	可训练参数数量	E2E (BLEU)	DART (BLEU)	WebNLG (BLEU-U/S/A)
	GPT-2 M (全量微调)	3.5492亿	68.2	46.0	30.4/63.2/47.6
	GPT-2 M (Adapter)	37万	66.3	42.4	45.1/54.5/50.2
	GPT-2 M (前缀调优)	35万	69.7	45.7	44.1/63.1/54.4
	GPT-2 M (LoRA)	35万	70.4±0.1	47.1±0.2	46.7±0.4/62.1±0.2/55.3±0.2
	GPT-2 L (全量微调)	7.7403亿	68.5	46.5	41.7/64.6/54.2
	GPT-2 L (Adapter)	88万	69.1±0.1	45.7±0.1	49.8±0.0/61.1±0.0/56.0±0.0
	GPT-2 L (前缀调优)	77万	70.3	46.5	47.0/64.2/56.4
	GPT-2 L (LoRA)	77万	70.4±0.1	47.5±0.1	48.4±0.3/64.0±0.3/57.0±0.1

非 LoRA 对照组数据除 GPT-2 large 上的 Adapter 外，均来自 Li and Liang (2021)。我们为实验结果提供了置信区间。

下载 GPT-2 LoRA 检查点：

• GPT-2 Medium E2E (1.5 MB)
• GPT-2 Medium DART (1.5 MB)
• GPT-2 Medium WebNLG (1.5 MB)
• GPT-2 Large E2E (2.3 MB)
• GPT-2 Large DART (2.3 MB)
• GPT-2 Large WebNLG (2.3 MB)

请按照 examples/NLG/ 中的说明来复现我们的结果。

仓库概览

(本仓库的初始版本已归档在分支 "snapshot-9-15-2021" 中)

该仓库包含以下几个目录：

• loralib/ 包含 loralib 软件包的源代码，需要安装此包才能运行我们提供的示例；
• examples/NLG/ 包含使用我们的软件包在 GPT-2 中实现 LoRA 的示例，可用于复现论文中的结果；
• examples/NLU/ 包含使用我们的软件包在 RoBERTa 和 DeBERTa 中实现 LoRA 的示例，在 GLUE 基准测试上取得了具有竞争力的结果；
• 请参阅我们在 GPT-2、RoBERTa 和 DeBERTa v2 中如何使用 loralib

快速入门

1. 安装 loralib 非常简单：

pip install loralib
# 或者
# pip install git+https://github.com/microsoft/LoRA

2. 您可以选择用 loralib 中实现的对应层替换部分层以进行适配。目前我们仅支持 nn.Linear、nn.Embedding 和 nn.Conv2d。此外，我们还提供 MergedLinear，用于处理单个 nn.Linear 表示多个层的情况，例如某些注意力机制中 qkv 投影的实现（更多信息请参见附注）。

# ===== 之前 =====
# layer = nn.Linear(in_features, out_features)

# ===== 之后 ======
import loralib as lora
# 添加一对低秩适配矩阵，秩为 r=16
layer = lora.Linear(in_features, out_features, r=16)

3. 在训练循环开始前，仅将 LoRA 参数标记为可训练。

import loralib as lora
model = BigModel()
# 这会将所有名称中不包含 "lora_" 字样的参数的 requires_grad 设置为 False
lora.mark_only_lora_as_trainable(model)
# 训练循环
for batch in dataloader:
   ...

4. 保存检查点时，生成仅包含 LoRA 参数的 state_dict。

# ===== 之前 =====
# torch.save(model.state_dict(), checkpoint_path)
# ===== 之后 =====
torch.save(lora.lora_state_dict(model), checkpoint_path)

5. 使用 load_state_dict 加载检查点时，请务必设置 strict=False。

# 先加载预训练检查点
model.load_state_dict(torch.load('ckpt_pretrained.pt'), strict=False)
# 然后加载 LoRA 检查点
model.load_state_dict(torch.load('ckpt_lora.pt'), strict=False)

现在可以像往常一样继续训练了。

附注

1. 尽管我们在示例中专注于一个简单而有效的设置——即仅对 Transformer 中的 q 和 v 投影进行适配——但 LoRA 实际上可以应用于预训练权重的任何子集。我们鼓励您尝试不同的配置，例如用 lora.Embedding 替换 nn.Embedding 层，或对 MLP 层进行适配。对于不同的模型架构和任务，最佳配置很可能会有所不同。

2. 有些 Transformer 实现使用单个 nn.Linear 来完成查询、键和值的投影矩阵。如果希望限制对各个矩阵更新的秩，就需要将其拆分为三个独立的矩阵，或者使用 lora.MergedLinear。如果您选择拆分该层，请务必相应地修改检查点。

# ===== 之前 =====
# qkv_proj = nn.Linear(d_model, 3*d_model)
# ===== 之后 =====
# 拆分成三个独立的矩阵（记得相应地修改预训练检查点）
q_proj = lora.Linear(d_model, d_model, r=8)
k_proj = nn.Linear(d_model, d_model)
v_proj = lora.Linear(d_model, d_model, r=8)
# 或者使用 lora.MergedLinear（推荐）
qkv_proj = lora.MergedLinear(d_model, 3*d_model, r=8, enable_lora=[True, False, True])

3. 与 LoRA 同时训练偏置向量可能是提升任务性能的一种经济高效的方式（前提是仔细调整学习率）。虽然我们在论文中并未深入研究其效果，但在 lora 中我们已经使其易于尝试。您可以通过在调用 mark_only_lora_as_trainable 时将 bias= 参数设置为 "all" 或 "lora_only" 来标记部分偏置为可训练。保存检查点时，请确保将相应的 bias= 参数传递给 lora_state_dict。

# ===== 之前 =====
# lora.mark_only_lora_as_trainable(model) # 不训练任何偏置向量
# ===== 之后 =====
# 训练所有与应用 LoRA 的模块相关的偏置向量
lora.mark_only_lora_as_trainable(model, bias='lora_only')
# 或者，我们可以训练模型中的 *所有* 偏置向量，包括 LayerNorm 的偏置
lora.mark_only_lora_as_trainable(model, bias='all')
# 保存检查点时，使用相同的 bias=（'all' 或 'lora_only'）
torch.save(lora.lora_state_dict(model, bias='all'), checkpoint_path)

4. 调用 model.eval() 会触发 LoRA 参数与其对应的预训练参数合并，从而消除后续前向传播的额外延迟。再次调用 model.train() 则会取消合并。这一行为可以通过在 LoRA 层中传入 merge_weights=False 来禁用。

联系方式

如有任何问题，请联系我们或提交 issue。

关于 loralib 软件包的问题：

• Edward Hu (edward@edwardjhu.com)
• Phillip Wallis (phwallis@microsoft.com)
• Weizhu Chen (wzchen@microsoft.com)

关于 GPT-2 示例的问题：

• Phillip Wallis (phwallis@microsoft.com)
• Yelong Shen (yeshe@microsoft.com)

关于 RoBERTa/DeBERTa 示例的问题：

• Lu Wang (luw@microsoft.com)

致谢

我们按字母顺序感谢 Jianfeng Gao、Jade Huang、Jiayuan Huang、Lisa Xiang Li、Xiaodong Liu、Yabin Liu、Benjamin Van Durme、Luis Vargas、Haoran Wei、Peter Welinder 和 Greg Yang 提供的宝贵反馈。

引用

@inproceedings{
hu2022lora,
title={Lo{RA}: Low-Rank Adaptation of Large Language Models},
author={Edward J Hu and Yelong Shen and Phillip Wallis and Zeyuan Allen-Zhu and Yuanzhi Li and Shean Wang and Lu Wang and Weizhu Chen},
booktitle={International Conference on Learning Representations},
year={2022},
url={https://openreview.net/forum?id=nZeVKeeFYf9}
}

贡献说明

本项目欢迎各类贡献和建议。大多数贡献都需要您签署一份贡献者许可协议（CLA），以声明您有权且确实将您的贡献使用权授予我们。有关详细信息，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地为该 PR 添加标记（例如状态检查、评论等）。请按照机器人提供的指示操作即可。对于使用我们 CLA 的所有仓库，您只需完成一次此操作。

本项目已采纳 微软开源行为准则。如需更多信息，请参阅 行为准则常见问题解答；如有任何其他问题或意见，请发送邮件至 opencode@microsoft.com。

LoRA 快速上手指南

LoRA (Low-Rank Adaptation) 是一种用于大语言模型的高效微调技术。它通过冻结预训练权重并学习低秩分解矩阵，大幅减少可训练参数量，在降低存储需求的同时实现高效的任務切换，且不会增加推理延迟。

环境准备

• 操作系统: Linux, macOS, Windows
• 编程语言: Python 3.7+
• 核心依赖:
  • PyTorch (目前仅支持 PyTorch)
  • Hugging Face Transformers (推荐，用于加载预训练模型)
• 硬件要求: 支持 CUDA 的 GPU（推荐）或 CPU

安装步骤

你可以直接通过 pip 安装官方发布的 loralib 包：

pip install loralib

或者从 GitHub 源码安装最新版本：

pip install git+https://github.com/microsoft/LoRA

提示：国内用户若下载缓慢，可尝试使用清华或阿里镜像源加速： pip install loralib -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是将 LoRA 集成到现有 PyTorch 模型中的最小化流程。

1. 替换网络层

将需要适配的标准层（如 nn.Linear）替换为 loralib 提供的对应层，并指定秩（rank, r）。

import torch.nn as nn
import loralib as lora

# ===== 修改前 =====
# layer = nn.Linear(in_features, out_features)

# ===== 修改后 =====
# 添加一对秩 r=16 的低秩适应矩阵
layer = lora.Linear(in_features, out_features, r=16)

注：目前支持 nn.Linear, nn.Embedding, nn.Conv2d 以及针对注意力机制优化的 lora.MergedLinear。

2. 冻结参数并标记 LoRA 可训练

在训练循环开始前，冻结模型所有原始参数，仅将包含 "lora_" 的参数设为可训练。

import loralib as lora

model = BigModel() # 你的预训练模型

# 将所有不含 "lora_" 的参数的 requires_grad 设为 False
lora.mark_only_lora_as_trainable(model)

# 开始训练循环
for batch in dataloader:
    # ... 常规训练代码 ...
    pass

3. 保存检查点

保存时，仅导出 LoRA 相关的参数，以节省存储空间。

# ===== 修改前 =====
# torch.save(model.state_dict(), checkpoint_path)

# ===== 修改后 =====
# 仅保存 LoRA 参数的 state_dict
torch.save(lora.lora_state_dict(model), checkpoint_path)

4. 加载检查点

加载时需要分两步：先加载预训练底座权重，再加载 LoRA 权重。注意：加载 LoRA 权重时必须设置 strict=False。

# 1. 加载预训练底座权重
model.load_state_dict(torch.load('ckpt_pretrained.pt'), strict=False)

# 2. 加载 LoRA 微调权重
model.load_state_dict(torch.load('ckpt_lora.pt'), strict=False)

完成上述步骤后，即可像往常一样进行训练或推理。