---
tags: [AI, lora, 量化, 微调]
阶段: 07-微调与对齐
难度: ★★★
created: 2026-10-18
related: "[[微调方法全景]], [[矩阵分解-SVD与特征分解]], [[指令微调SFT]]"
---

# LoRA与QLoRA

## 定义

**LoRA**（low-rank adaptation）在冻结的基座权重 $\mathbf{W}_{0}\in\mathbb{R}^{d\times k}$ 上叠加一个低秩更新 $\Delta\mathbf{W}=\mathbf{B}\mathbf{A}$，其中 $\mathbf{B}\in\mathbb{R}^{d\times r}$、$\mathbf{A}\in\mathbb{R}^{r\times k}$、$r\ll\min(d,k)$；训练只更新 $\mathbf{A},\mathbf{B}$，前向为 $\mathbf{y}=\mathbf{W}_{0}\mathbf{x}+\frac{\alpha}{r}\mathbf{B}\mathbf{A}\mathbf{x}$。**QLoRA** 是 LoRA 的量化变体：基座以 4-bit NormalFloat（NF4）存储并冻结，前向时按块反量化到 bf16 参与计算，梯度只回传到 bf16 的适配器；另加双重量化压缩量化常数、分页优化器吸收显存尖峰。

本篇符号约定如下。

| 符号 | 含义 |
|---|---|
| $d,k$ | 权重矩阵的输出维度、输入维度 |
| $r$ | 低秩分解的秩 |
| $\alpha$ | 缩放超参数 |
| $s=\alpha/r$ | 实际缩放因子 |
| $\mathbf{W}_{0}$ | 冻结的基座权重 |
| $\mathbf{A},\mathbf{B}$ | 低秩因子，$\mathbf{A}\in\mathbb{R}^{r\times k}$，$\mathbf{B}\in\mathbb{R}^{d\times r}$ |
| $\mathbf{x},\mathbf{y}$ | 该层的输入、输出 |
| $P$ | 可训练参数量 |
| $L$ | Transformer 层数 |
| $B,T$ | 批大小、序列长度 |
| $N$ | 基座参数量 |
| $b$ | 每参数字节数 |

术语定义。**秩**（rank）是矩阵线性无关的行（或列）的最大数目，也等于非零奇异值的个数。**内在维度**（intrinsic dimension）指能使微调达到接近全参数微调效果的最小参数子空间维数。**量化**（quantization）指把浮点张量映射到有限个离散值并以低位宽存储。**分块量化**（blockwise quantization）指把张量切成固定大小的块，每块共享一个缩放常数。**反量化**（dequantization）指由离散索引与缩放常数重建浮点近似值。**适配器**（adapter）此处指 $\mathbf{A},\mathbf{B}$ 这一对可训练矩阵。

## 为什么重要

全量微调的状态显存是每参数 16 字节，7B 模型为 107.8 GB。LoRA 把需要保存梯度与优化器状态的参数从 $N$ 降到 $P$：$r=8$ 时 $P=19{,}988{,}480$，状态显存 0.32 GB，加上 bf16 基座 13.48 GB 与激活约 1 GB，总需求约 15 GB，单张 24 GB 卡可以训练（[[微调方法全景]]）。QLoRA 再压缩基座存储：NF4 加双重量化后每参数约 4.13 bit，7B 的线性层从 13.0 GB 降到 3.34 GB，整卡需求约 5.8 GB，使 7B 训练可以在 12–16 GB 的消费级显卡上完成；按同一比例，65B 模型约需 40.5 GB，可在单张 48 GB 卡上微调。

LoRA 的第二个作用是部署。更新是加性的，可以无误差地写入基座权重：$\mathbf{W}'=\mathbf{W}_{0}+s\mathbf{B}\mathbf{A}$。合并后计算图与基座完全相同，推理延迟不增加，也没有额外的算子或显存；一个冻结基座可以挂载多组 $\{\mathbf{A},\mathbf{B}\}$，按请求切换，每份额外存储约 40 MB（$r=8$）而不是 13.5 GB。这是"单基座、多任务"服务形态的实现基础。

LoRA 的第三个作用是约束更新空间。全量微调在小数据上会改动全部层，遗忘风险高；LoRA 把每个矩阵的更新限制在秩 $r$ 的子空间内，参数量下降三到四个数量级，过拟合与遗忘都减轻。代价是容量受限：任务需要大幅改变表示时，低秩近似无法表示所需的更新，此时只能提高 $r$、增加目标模块，或回到全量微调。

在笔记库中的位置：本篇承接 [[微调方法全景]] 的方法分类，把 LoRA 展开到可实现、可验证的细节；秩与奇异值来自 [[矩阵分解-SVD与特征分解]]；训练数据组织与损失掩码见 [[指令微调SFT]]；合并后的推理与量化推理的工程细节见 [[模型推理优化]]。对应学习目标中的"能复现"：本篇给出的实现可在单卡上跑通，合并一致性可逐位验证。

## 原理与推导

### 1 低秩假设与内在维度

全量微调对形状为 $d\times k$ 的权重产生更新 $\Delta\mathbf{W}$，它有 $dk$ 个自由度。若任务只需调整少数方向上的映射，则 $\Delta\mathbf{W}$ 的有效秩远小于 $\min(d,k)$，可以用秩 $r$ 的矩阵近似而不显著损失效果。这一假设有三个可检验的来源。

第一，输入分布的低维性。线性层作用于隐藏状态 $\mathbf{x}$，而 $\mathbf{x}$ 的分布在训练中被归一化与残差结构约束，通常集中在低维子空间附近；映射中与这些方向正交的部分对输出没有贡献，其对应的参数梯度接近零。

第二，更新的谱衰减。对一个小模型做全量微调，取 $\Delta\mathbf{W}$ 的奇异值 $\sigma_{1}\ge\sigma_{2}\ge\cdots$，计算前 $r$ 项的平方能量占比 $\sum_{i\le r}\sigma_{i}^{2}/\sum_{i}\sigma_{i}^{2}$。若该比例在 $r=8$ 时已接近 1，说明秩 8 的近似已捕获主要更新。这是判断"某个任务能否用 LoRA"的直接实验，不需要训练 LoRA 本身。

第三，不同秩的解具有共同子空间。LoRA 论文用子空间相似度比较不同 $r$ 训练得到的更新，发现 $r=8$ 与 $r=64$ 的主子空间高度重叠，说明主要更新方向在低秩时已被捕获，增大 $r$ 主要增加次要方向。

内在维度的定义刻画同一现象：若存在维度为 $D$ 的子空间，使在该子空间内优化可达到与全空间优化相近的损失，则任务的内在维度为 $D$。LoRA 是这一概念在单个矩阵上的实现：每个被适配矩阵的更新被限制在秩不超过 $r$ 的子空间内，全部模块合计 $P=r(d+k)\times(\text{模块数})$ 个可训练参数。$P$ 与 $D$ 不是同一个量：$D$ 刻画任务所需的自由度，$P$ 是该实现提供的自由度，二者只在"远小于 $N$"这一点上一致。

### 2 $\Delta\mathbf{W}=\mathbf{B}\mathbf{A}$ 分解

设基座权重为 $\mathbf{W}_{0}\in\mathbb{R}^{d\times k}$，LoRA 把更新写成两个窄矩阵的乘积：

$$
\Delta\mathbf{W}=\mathbf{B}\mathbf{A},\qquad
\mathbf{B}\in\mathbb{R}^{d\times r},\;
\mathbf{A}\in\mathbb{R}^{r\times k},\;
r\ll\min(d,k).
$$

由秩的次可乘性，

$$
\mathrm{rank}(\mathbf{B}\mathbf{A})\le\min\left(\mathrm{rank}(\mathbf{B}),\mathrm{rank}(\mathbf{A})\right)\le r .
$$

因此 $\Delta\mathbf{W}$ 的秩不超过 $r$。反过来，任何秩不超过 $r$ 的矩阵都能写成这种形式：对 $\mathbf{M}=\mathbf{U}_{r}\boldsymbol{\Sigma}_{r}\mathbf{V}_{r}^{\top}$ 取

$$
\mathbf{B}=\mathbf{U}_{r}\boldsymbol{\Sigma}_{r}^{1/2},\qquad
\mathbf{A}=\boldsymbol{\Sigma}_{r}^{1/2}\mathbf{V}_{r}^{\top},
$$

则 $\mathbf{B}\mathbf{A}=\mathbf{U}_{r}\boldsymbol{\Sigma}_{r}\mathbf{V}_{r}^{\top}=\mathbf{M}$。所以 LoRA 的可达集合恰好是"秩不超过 $r$ 的 $d\times k$ 矩阵"，限制只来自秩，不来自参数化形式。

参数化不唯一：对任意可逆 $\mathbf{Q}\in\mathbb{R}^{r\times r}$，

$$
(\mathbf{B}\mathbf{Q})(\mathbf{Q}^{-1}\mathbf{A})=\mathbf{B}\mathbf{A},
$$

即同一更新对应 $r^{2}$ 维的等价类。这使损失曲面在这些方向上平坦，但不改变可达集合；优化算法最终落在等价类中的哪一点不影响前向结果。

若真实更新 $\Delta\mathbf{W}^{\star}$ 的秩为 $R>r$，最优秩 $r$ 近似的误差由 Eckart–Young 定理给出：

$$
\min_{\mathrm{rank}(\mathbf{M})\le r}\left\|\Delta\mathbf{W}^{\star}-\mathbf{M}\right\|_{F}^{2}
=\sum_{i=r+1}^{R}\sigma_{i}^{2},
$$

最小值由截断 SVD 取得。误差只由被截掉的奇异值决定，与优化算法无关。这给出两条推论：其一，尾部奇异值能量大时，增大 $r$ 的收益明确；其二，梯度下降训练出的 $\mathbf{B}\mathbf{A}$ 不一定等于最优秩 $r$ 近似，上式只是该参数化族的能力上界，实际效果还要看优化是否收敛到该上界附近。

### 3 前向、反向与计算量

前向计算为

$$
\mathbf{y}=\mathbf{W}_{0}\mathbf{x}+s\,\mathbf{B}\mathbf{A}\mathbf{x},
\qquad s=\frac{\alpha}{r}\in\mathbb{R}.
$$

形状变化为 $\mathbf{x}\in\mathbb{R}^{k}\to\mathbf{A}\mathbf{x}\in\mathbb{R}^{r}\to\mathbf{B}\mathbf{A}\mathbf{x}\in\mathbb{R}^{d}$，基座路径与旁路的输出维度一致，可以直接相加。

设损失对输出的梯度为 $\mathbf{g}=\partial L/\partial\mathbf{y}\in\mathbb{R}^{d}$。由 $dL=\langle\mathbf{g},d\mathbf{y}\rangle$ 与 $d\mathbf{y}=s\mathbf{B}\mathbf{A}\,d\mathbf{x}$，分别对两个因子求导：

$$
\frac{\partial L}{\partial\mathbf{B}}=s\,\mathbf{g}\left(\mathbf{A}\mathbf{x}\right)^{\top}\in\mathbb{R}^{d\times r},
\qquad
\frac{\partial L}{\partial\mathbf{A}}=s\,\mathbf{B}^{\top}\mathbf{g}\,\mathbf{x}^{\top}\in\mathbb{R}^{r\times k}.
$$

对输入的梯度同时包含基座与旁路两项：

$$
\frac{\partial L}{\partial\mathbf{x}}
=\mathbf{W}_{0}^{\top}\mathbf{g}+s\,\mathbf{A}^{\top}\mathbf{B}^{\top}\mathbf{g}.
$$

第二项说明适配器改变了上游的梯度。若在多模块串联时把旁路输出 `detach`，这一项消失，前面的层收不到适配器的梯度，训练会退化；正确做法是让梯度沿计算图自然回传，只冻结 $\mathbf{W}_{0}$ 的参数而不是切断张量。

计算量方面，旁路每 token 的乘加为 $2r(d+k)$，基座为 $2dk$，比值为

$$
\frac{2r(d+k)}{2dk}=r\left(\frac{1}{d}+\frac{1}{k}\right),
$$

与参数量占比相同。7B 模型全部线性层取 $r=8$ 时为 $0.30\%$，合并前的前向开销可以忽略。训练时还需保存 $\mathbf{A}\mathbf{x}\in\mathbb{R}^{r}$，每个 token 每个模块 $r$ 个元素，属于可忽略项；反向需要保留 $\mathbf{x}$，这是激活显存不因 LoRA 下降的原因（见第 10 节）。

### 4 初始化

$\mathbf{A}$ 用随机初始化（原文取高斯，PEFT 取 `kaiming_uniform_(a=sqrt(5))`），$\mathbf{B}$ 初始化为零：

$$
\mathbf{A}\sim\mathcal{N}\left(0,\sigma^{2}\right),\qquad \mathbf{B}=\mathbf{0}
\;\Longrightarrow\;
\Delta\mathbf{W}(0)=\mathbf{0}.
$$

于是初始时刻 $\mathbf{y}=\mathbf{W}_{0}\mathbf{x}$ 逐元素成立，模型的损失与基座完全相同，不会出现初始扰动引起的损失尖峰，也不需要为适配器单独调整初始学习率。

首步的梯度结构值得注意。代入 $\mathbf{B}=\mathbf{0}$：

$$
\frac{\partial L}{\partial\mathbf{B}}=s\,\mathbf{g}\left(\mathbf{A}\mathbf{x}\right)^{\top}\neq\mathbf{0},
\qquad
\frac{\partial L}{\partial\mathbf{A}}=s\,\mathbf{B}^{\top}\mathbf{g}\,\mathbf{x}^{\top}=\mathbf{0}.
$$

因此第一步只有 $\mathbf{B}$ 被更新，$\mathbf{A}$ 从第二步起才收到非零梯度。这不是"对称性无法打破"的问题：$\mathbf{A}$ 的随机性使不同输出方向的 $\mathbf{B}$ 梯度各不相同，对称性已经打破；$\mathbf{A}$ 的首步梯度为零只是 $\mathbf{B}=\mathbf{0}$ 的代数结果。

两种错误初始化可以直接排除。若 $\mathbf{A},\mathbf{B}$ 都置零，两个梯度恒为零，训练完全不动，损失曲线为水平线。若两者都随机，初始 $\Delta\mathbf{W}\neq\mathbf{0}$，输出偏离基座，且 $\|\Delta\mathbf{W}\|$ 随 $r$ 与初始化方差增长，需要重新调整学习率与 $\alpha$，否则早期损失会跳升。

### 5 缩放因子 $\alpha/r$

$s=\alpha/r$ 同时出现在两个位置：前向中缩放旁路输出，反向中缩放两个因子的梯度。这带来两点性质。

其一，$s$ 与学习率在一阶意义下部分可互换。梯度含因子 $s$，参数更新量因此正比于 $s$；而输出中旁路项也正比于 $s$。二者都线性于 $s$，所以把 $s$ 减半并让学习率加倍，短期内参数更新的方向与量级接近；差别在于 $s$ 还决定旁路输出相对基座输出的比例，而学习率不影响这一比例。

其二，$s$ 抵消 $r$ 变化带来的尺度漂移。固定 $\alpha$ 而增大 $r$ 时，若没有 $1/r$，$\mathbf{B}\mathbf{A}$ 的初始尺度随 $r$ 增长（$\mathbf{A}$ 的元素数随 $r$ 增加），有效步长随之改变；除以 $r$ 后，不同 $r$ 下的更新幅度处于同一量级。论文的做法是固定 $\alpha$ 不随 $r$ 调整，正是为了让不同 $r$ 的实验在同一超参下可比。

常见设置有三种：$\alpha=r$，$s=1$；$\alpha=2r$，$s=2$；固定 $\alpha=16$，$r$ 在 4 到 64 之间扫描。第三种下 $s$ 随 $r$ 变化（$r=8$ 时 $s=2$，$r=64$ 时 $s=0.25$），报告结果时必须同时给出 $\alpha$ 与 $r$，否则无法复现。实际调参时先固定 $s\in\{1,2\}$，再只扫学习率，可以减少两个耦合超参同时变化造成的混淆。

### 6 参数量与占比

可训练参数量为

$$
P=rk+dr=r(d+k),
$$

与满秩的 $dk$ 之比为

$$
\frac{P}{dk}=\frac{r(d+k)}{dk}=r\left(\frac{1}{d}+\frac{1}{k}\right).
$$

对 $d=k=4096$、$r=8$，单个方阵的比值为 $8\times2/4096=1/256$，即 $0.39\%$。7B 模型对 $q,k,v,o,gate,up,down$ 全部线性层取 $r=8$，每层 $4\times65{,}536+3\times120{,}832=624{,}640$，32 层合计 $19{,}988{,}480$，占 $6{,}738{,}415{,}616$ 的 $0.2966\%$。若只适配 $q,v$，参数为 $4{,}194{,}304$（$0.0622\%$）。

作为量级对照，GPT-3 175B 的 $d=12288$、$L=96$，若只对 $W_{Q},W_{V}$ 取 $r=4$：

$$
96\times2\times4\times(12288+12288)=18{,}874{,}368,
$$

约占 175B 的 $1/9{,}272$，与论文摘要所称"可训练参数减少约一万倍"同一量级。注意力与低秩分解的维度关系见 [[矩阵分解-SVD与特征分解]]。

### 7 合并与推理零延迟

由于更新是加性的，可把它吸收进基座权重：

$$
\mathbf{W}'=\mathbf{W}_{0}+s\mathbf{B}\mathbf{A},
\qquad
\mathbf{W}'\mathbf{x}=\mathbf{W}_{0}\mathbf{x}+s\mathbf{B}\mathbf{A}\mathbf{x}=\mathbf{y}.
$$

合并的代价是每个适配模块计算一次 $\mathbf{B}\mathbf{A}$ 并加到 $\mathbf{W}_{0}$，即 $r\cdot dk$ 次乘加。7B 全部适配模块的 $\sum dk$ 等于线性层参数总量 $6.48\times10^{9}$，乘以 $r=8$ 得 $5.2\times10^{10}$ 次乘加，在有效算力 10 TFLOPs 的加速卡上约 10 ms，相对一次训练迭代可以忽略。合并后丢弃 $\mathbf{A},\mathbf{B}$，模型结构与参数量与基座完全一致，解码时没有额外算子、没有额外显存访问，因此推理延迟不增加。

数值上，合并前后不是逐位相同。合并把 $s\mathbf{B}\mathbf{A}$ 与 $\mathbf{W}_{0}$ 相加，若权重以 bf16 存储，加法引入的舍入误差量级为 $2^{-8}$ 的相对误差；未合并时旁路在 bf16 下单独计算再相加，两条路径的舍入顺序不同。fp32 下两者的差异通常在 $10^{-6}$ 量级，bf16 下在 $10^{-2}$ 量级，均远小于模型本身的数值噪声，但一致性检验的阈值必须按 dtype 设定。

合并的操作要点有三条。第一，合并必须在评估模式下进行，dropout 关闭；训练模式下合并会使后续前向的旁路项与非合并时不一致。第二，合并后适配器的梯度路径消失，不能继续训练；如需继续，先 `unmerge` 恢复。第三，合并到量化基座需要先反量化，得到的 bf16 权重不再有 4-bit 的存储优势，因此 QLoRA 的产物通常以"基座 + 适配器"的形式分发，而不是合并后的单文件。

多适配器场景下，切换成本是一次 `unmerge` 加一次 `merge`，约为合并代价的两倍，即数十毫秒；若逐请求切换且请求率高，这一开销会进入延迟，应按适配器分组批处理，避免每步都做权重往返。

### 8 目标模块选择

7B 模型的线性层形状与 $r=8$ 时的参数量如下。

| 模块 | 形状 | 每模块参数 | 说明 |
|---|---|---|---|
| `q_proj` | $4096\times4096$ | 65,536 | 查询投影，原论文默认适配 |
| `k_proj` | $4096\times4096$ | 65,536 | 键投影，影响匹配关系 |
| `v_proj` | $4096\times4096$ | 65,536 | 值投影，原论文默认适配 |
| `o_proj` | $4096\times4096$ | 65,536 | 输出投影，影响写回残差流 |
| `gate_proj` | $11008\times4096$ | 120,832 | 前馈门控 |
| `up_proj` | $11008\times4096$ | 120,832 | 前馈升维 |
| `down_proj` | $4096\times11008$ | 120,832 | 前馈降维 |

三档配置的总量与占比：

| 配置 | 每层参数 | 总量 | 占比 |
|---|---|---|---|
| 仅 $q,v$ | 131,072 | 4,194,304 | 0.0622% |
| 注意力四矩阵 | 262,144 | 8,388,608 | 0.1245% |
| 全部七个模块 | 624,640 | 19,988,480 | 0.2966% |

原论文的消融显示，只适配 $W_{Q}$ 或只适配 $W_{K}$ 的效果明显弱于同时适配 $W_{Q},W_{V}$；在 $q,v$ 基础上继续增加 $k,o$ 的收益不稳定。QLoRA 的消融给出更严格的要求：要与 16-bit 全量微调对齐，需要把适配器加到全部线性层，包括前馈的三个矩阵。两者的差别可以用容量解释：任务距离近时少数模块足够，任务距离远时需要更多可调方向。

工程上的选择顺序是：显存紧张或只做格式适配，用 $q,v$；追求与全量微调对齐，用全部线性层；介于两者之间，先加 $k,o$，再加前馈。`target_modules` 的名称必须与模型实现一致（Llama 系为 `q_proj`、`k_proj`、`v_proj`、`o_proj`、`gate_proj`、`up_proj`、`down_proj`），名称写错时 PEFT 会匹配不到模块，可训练参数为零或只覆盖部分层，训练仍能运行但不会产生预期效果。

### 9 秩与效果、过拟合

$r$ 决定每个矩阵可用的更新方向数，参数量线性于 $r$：

| $r$ | 全部线性层参数 | 占比 | 仅 $q,v$ 参数 | 占比 |
|---|---|---|---|---|
| 1 | 2,498,560 | 0.0371% | 524,288 | 0.0078% |
| 2 | 4,997,120 | 0.0742% | 1,048,576 | 0.0156% |
| 4 | 9,994,240 | 0.1483% | 2,097,152 | 0.0311% |
| 8 | 19,988,480 | 0.2966% | 4,194,304 | 0.0622% |
| 16 | 39,976,960 | 0.5933% | 8,388,608 | 0.1245% |
| 32 | 79,953,920 | 1.1865% | 16,777,216 | 0.2490% |
| 64 | 159,907,840 | 2.3731% | 33,554,432 | 0.4980% |

效果随 $r$ 的增长不是线性的：在多数指令微调任务上，$r=4$ 到 $16$ 的差别小于数据质量带来的差别；当任务需要学习新的输出格式、新的语言或新的推理模式时，$r=32$ 到 $64$ 的收益才明显。饱和点的位置由数据量与任务距离共同决定：数据量小、任务近，早饱和；数据量大、任务远，饱和点右移。

过拟合的表现与全量微调相同：训练损失持续下降而验证损失回升，生成结果趋于模板化、重复训练集措辞。LoRA 的过拟合与 $r$ 的关系不是单调的：$r$ 增大提高容量，同时使一步更新的量级随 $\|\mathbf{A}\|_{F}^{2}\propto r$ 增长（在 $\mathbf{B}=\mathbf{0}$ 起步、学习率相同的条件下），两个效应对泛化的作用方向相反，因此不能只凭 $r$ 判断过拟合风险。处理手段按优先级为：增加或清洗数据、降低训练轮数、提高 `lora_dropout`、降低 $r$、降低学习率。

一个常见误解是"$r$ 小意味着总更新秩小"。正确的关系是：每个被适配的矩阵的更新秩不超过 $r$，但 7B 模型有 $32\times7=224$ 个被适配矩阵，集体更新可张成远超 $r$ 维的方向；$r$ 限制的是单个矩阵的表达能力，不是整个模型的表达能力。

### 10 训练显存分析

LoRA 训练的显存由四项构成：

$$
M_{\text{train}}
=\underbrace{b_{w}N}_{\text{冻结基座}}
+\underbrace{16P}_{\text{适配器状态}}
+\underbrace{M_{\text{act}}}_{\text{激活}}
+\underbrace{M_{\text{logits}}}_{\text{输出层}} .
$$

第一项不能省。冻结只意味着不计算梯度、不保存优化器状态，前向仍需要全部权重参与矩阵乘；bf16 基座为 $2N$，7B 为 13.48 GB。

第二项按每参数 16 字节计（bf16 参数 2、bf16 梯度 2、fp32 主权重 4、Adam 两个矩 8）。$r=8$ 时为 0.32 GB，$r=16$ 时为 0.64 GB，相对基座可忽略。

第三项与 PEFT 无关。反向传播需要 $\partial L/\partial\mathbf{A}=s\mathbf{B}^{\top}\mathbf{g}\mathbf{x}^{\top}$ 中的 $\mathbf{x}$，即每层输入；因此适配器越靠后，需要保留的激活越多。梯度检查点把这一项从"每层全部中间张量"降到"每层一个输入张量"，代价是约 30% 的额外前向时间。按 $B=1$、$T=2048$、bf16、$L=32$ 估算，不检查点约 7.2 GB（FlashAttention），检查点后约 0.54 GB，加首尾张量约 0.9 GB。

第四项是输出层 logits：$B\times T\times V$ 个元素，$V=32000$ 时 fp32 为 0.26 GB。使用分块交叉熵可以进一步降低。

7B 模型 $r=8$ 的汇总为 13.48 + 0.32 + 1.0 + 0.26 ≈ 15.1 GB；$r=16$ 为 15.4 GB。若把序列长度加倍到 4096，检查点下的激活约翻倍，总量增加约 1 GB；这与"参数少所以显存一定小"的判断不同，长上下文场景下激活会成为主项。

### 11 QLoRA 的三个组件

QLoRA 要解决三个独立的显存问题，每个组件对应一个。

```mermaid
flowchart LR
    A["bf16 基座<br/>2 字节/参数"] -->|"NF4 分块量化"| B["4-bit 基座<br/>0.5 字节/参数"]
    B -->|"双重量化"| C["量化常数再压缩<br/>0.516 字节/参数"]
    C --> D["前向按块反量化到 bf16"]
    D --> E["LoRA 旁路 bf16 计算"]
    E --> F["梯度只到适配器"]
    F --> G["分页优化器<br/>吸收显存尖峰"]
```

| 组件 | 解决的问题 | 机制 |
|---|---|---|
| NF4 | 权重存储过大 | 按 64 元素分块，块内归一化后查 16 值码本 |
| 双重量化 | 量化常数本身占空间 | 对 absmax 数组再做 8-bit 分块量化 |
| 分页优化器 | 长序列或大步长导致的瞬时尖峰 | 优化器状态可分页到 CPU，按需取回 |

三者互相独立，可单独启用；QLoRA 论文的组合是在 4-bit 基座上做 LoRA，同时启用双重量化与分页优化器。

### 12 NF4 的分位构造

分块量化的第一步是归一化。把权重按 64 个元素分块，对块 $j$ 取

$$
c_{j}=\max_{i\in\text{block}\,j}\left|w_{i}\right|,
\qquad
\hat{w}_{i}=\frac{w_{i}}{c_{j}}\in[-1,1].
$$

第二步是用 16 个码本值 $\{q_{0},\dots,q_{15}\}$ 表示 $\hat{w}_{i}$：

$$
n_{i}=\arg\min_{m}\left|\hat{w}_{i}-q_{m}\right|,
\qquad
\tilde{w}_{i}=c_{j}\,q_{n_{i}}.
$$

码本的选择决定误差。**NF4**（4-bit NormalFloat）取标准正态分布的 16 个等概率分位点：把 $[0,1]$ 上的概率区间等分为 16 份，取每份的中点做逆累积分布函数变换，

$$
q_{m}=\Phi^{-1}\left(\frac{m+0.5}{16}\right),\qquad m=0,\dots,15,
$$

再除以 $\max_{m}|q_{m}|$ 归一化到 $[-1,1]$。这样每个码本值覆盖相同的概率质量，量化后的 4-bit 索引近似等频出现，码本在权重密度高的零附近更密、在尾部更疏。实际库中的码本是预先计算并固定的 16 个常数，为使零精确映射到零，其中包含一个 0，整体为 7 个负值、1 个零、8 个正值，数值与纯分位公式略有差异。表 12.1 给出该码本。

| 索引 | 值 | 索引 | 值 |
|---|---|---|---|
| 0 | -1.0000 | 8 | 0.0796 |
| 1 | -0.6962 | 9 | 0.1609 |
| 2 | -0.5251 | 10 | 0.2461 |
| 3 | -0.3949 | 11 | 0.3379 |
| 4 | -0.2844 | 12 | 0.4407 |
| 5 | -0.1848 | 13 | 0.5626 |
| 6 | -0.0911 | 14 | 0.7230 |
| 7 | 0.0000 | 15 | 1.0000 |

零附近的间隔为 $0.0796$ 到 $0.0911$，尾部的间隔为 $0.277$ 到 $0.304$，前者约为后者的三分之一。均匀网格在 $[-1,1]$ 上的固定间隔为 $2/15=0.1333$，无法同时兼顾两个区域。

需要区分两种"最优"。等概率分位使码本熵最大、每个码字被等频使用；而最小化均方误差的最优码本由 Lloyd–Max 条件给出，其点密度正比于 $p(w)^{1/3}$，对正态分布而言比正态本身更平缓。NF4 采用的是前者，因此它并非严格的最小均方误差码本；但在权重近似正态、每块由 absmax 归一化的条件下，它把量化级数集中到权重实际出现的区域，比均匀网格的误差更低。用例 3 的模拟（每块 64 个 $\mathcal{N}(0,0.02^{2})$ 样本、最近邻量化）测得，NF4 码本的平均平方误差约为均匀 4-bit 网格的 $0.84$ 倍。

存储上，每 64 个权重存 64 个 4-bit 索引（打包为 32 字节）加 1 个 fp32 的 $c_{j}$。计算时按块把索引查表、乘回 $c_{j}$，转成 bf16 后进入矩阵乘；这一步由融合算子完成，不物化完整的 bf16 权重矩阵。

### 13 双重量化

分块量化的常数开销可以精确计算。每 64 个参数共享一个 fp32 的 absmax，摊到每个参数是 $32/64=0.5$ bit，使实际位宽从 4 bit 升到 4.5 bit，相对开销 $12.5\%$。

双重量化对 absmax 数组本身再做一次分块量化：把每 256 个 absmax 分为一组，组内用 8-bit 表示，另存一个 fp32 的组缩放常数。每个参数分摊的常数位宽变为

$$
\frac{8}{64}+\frac{32}{64\times256}
=0.125+0.00195=0.12695\ \text{bit},
$$

总位宽为 $4.12695$ bit，即每参数 $0.5159$ 字节；相比单重量化的 4.5 bit，每个参数节省 $0.373$ bit，相对降低 $8.3\%$。对 65B 模型，节省量为

$$
65\times10^{9}\times\frac{0.373}{8}\approx3.03\ \text{GB}.
$$

这一操作可行的原因是 absmax 沿权重张量变化平缓：同一层内相邻块的尺度相近，用 8-bit 表示带来约 $2^{-8}$ 的相对误差，经过 $c_{j}$ 传到权重上是同量级的相对扰动，远小于 NF4 码本本身的量化误差，因此对最终精度的影响可以忽略。若块内权重的尺度差异很大（例如未做归一化的嵌入矩阵），这一假设不成立，应避免对该张量使用分块量化。

### 14 分页优化器

训练中的显存占用不是常量。序列长度可变、批内样本长度不齐、梯度检查点的重算阶段与参数更新阶段交替，都会造成瞬时峰值；峰值超过容量时训练直接失败，即使平均占用远低于容量。

分页优化器利用统一内存（unified memory）把优化器状态标记为可分页：显存不足时，最近未使用的状态页被换出到主机内存，需要时再换回。它作用于优化器状态（Adam 的一阶矩、二阶矩，以及 8-bit 版本中的量化常数），不作用于模型权重与激活。效果是把"超出容量即失败"变成"超出容量时该步变慢"，代价是 PCIe 传输延迟；若工作集持续大于显存，每一步都会换页，吞吐显著下降。

配置方式是在训练参数中指定 `optim="paged_adamw_32bit"`（或 8-bit 版本）。它与梯度检查点配合使用：检查点降低平均占用，分页优化器吸收剩余尖峰。需要注意两点：分页优化器不降低稳态占用，不能用它替代显存预算；它依赖 CUDA 的统一内存支持，在部分加速卡或驱动上不可用。

### 15 BF16 计算与量化存储的混合

QLoRA 把"存储精度"与"计算精度"分开：权重以 NF4 存储，矩阵乘在 bf16 下进行，适配器参数与梯度也是 bf16（优化器状态可用 fp32）。前向的数据路径为

$$
\mathbf{y}=\mathrm{matmul}_{\text{bf16}}\left(\mathbf{x},\ \mathrm{dequant}_{\text{bf16}}\left(\mathbf{W}_{\text{NF4}}\right)\right)+s\,\mathbf{B}\mathbf{A}\mathbf{x}.
$$

反向只对 $\mathbf{A},\mathbf{B}$ 求梯度，基座不产生梯度，因此也不需要 fp32 主权重与 Adam 状态。归一化层的参数在部分实现中被转为 fp32 计算，原因是归一化层的输入尺度在低精度下波动较大，用 fp32 计算统计量可避免方差估计失真。

选择 bf16 而非 fp16 的原因是动态范围。bf16 有 8 位指数、7 位尾数，fp16 有 5 位指数、10 位尾数；前者表示范围与 fp32 相同，梯度中出现小幅值或大幅值时不会上溢或下溢，后者在 $10^{-5}$ 以下与 $65504$ 以上失效。QLoRA 论文的消融显示 bf16 计算的稳定性优于 fp16，因此推荐配置为"NF4 存储 + bf16 计算"。

混合精度带来一个实现约束：同一次矩阵乘的两个操作数 dtype 必须一致。若基座以 NF4 加载、计算 dtype 设为 bf16，而适配器被创建为 fp32，前向会报 dtype 不匹配；若输入张量是 fp16 而计算 dtype 是 bf16，同样报错。解决方式是在加载模型时统一 `bnb_4bit_compute_dtype`，并在创建适配器后确认其 dtype 与基座的计算 dtype 一致。

### 16 QLoRA 显存估算算例

配置：7B 模型，$r=16$，全部线性层，NF4 加双重量化，bf16 计算，$B=1$、$T=2048$，梯度检查点开启。

| 项 | 计算 | 大小 |
|---|---|---|
| NF4 线性层 | $6{,}476{,}255{,}232\times4.12695/8$ | 3.34 GB |
| 嵌入与输出层（bf16） | $2\times32000\times4096\times2$ | 0.52 GB |
| 适配器状态 | $39{,}976{,}960\times16$ | 0.64 GB |
| 激活（检查点） | $L\cdot BTd\cdot 2$ 加首尾 | 约 1.0 GB |
| logits（fp32） | $1\times2048\times32000\times4$ | 0.26 GB |
| 合计 | | 约 5.8 GB |

加上 CUDA 上下文、通信缓冲与显存碎片（通常 10%–30%），实测峰值在 6–8 GB，可运行在 12 GB 以上的显卡。同配置下若使用 bf16 基座（普通 LoRA），权重项从 3.86 GB 变为 13.48 GB，总量约 15.4 GB。

按同一方法估算 65B 模型（$d=8192$、$L=80$、$r=16$、全部线性层）：

| 项 | 计算 | 大小 |
|---|---|---|
| NF4 线性层 | $64.5\times10^{9}\times4.12695/8$ | 33.3 GB |
| 嵌入与输出层（bf16） | $2\times32000\times8192\times2$ | 1.05 GB |
| 适配器状态 | $199{,}884{,}800\times16$ | 3.20 GB |
| 激活（检查点） | $80\times2048\times8192\times2$ 加 logits | 2.94 GB |
| 合计 | | 约 40.5 GB |

40.5 GB 可放进单张 48 GB 卡，余量约 7.5 GB，与 QLoRA 论文报告的"65B 在单张 48 GB GPU 上微调"一致；而 7B 的对应总量是 5.8 GB，可放进 12 GB 卡。这一算例说明 QLoRA 的收益集中在基座存储项：适配器状态随模型增大而增大（65B 为 3.2 GB），激活也与层数和宽度成正比，两者不会被 4-bit 压缩。

### 17 质量、代价与适用边界

QLoRA 论文报告的结果是：在其实验配置下，4-bit NF4 基座加 LoRA 的微调质量接近 16-bit 全量微调，65B 模型可在单张 48 GB 卡上完成训练。这一结论的适用范围需要限定：任务为指令微调、基座规模足够大、适配器覆盖全部线性层；若只适配 $q,v$ 或数据量很小，4-bit 基座带来的误差可能与适配器容量不足叠加，差距会被放大。

代价有四项。其一，反量化开销：每次前向都要把权重块从 4-bit 转成 bf16，相同计算量下步时增加，吞吐低于 bf16 LoRA。其二，合并困难：合并需要先把基座反量化回 bf16，得到的是 16-bit 权重，失去 4-bit 的存储优势；因此 QLoRA 的产物通常以"基座 + 适配器"分发，推理时仍需 4-bit 加载。其三，4-bit 存储对某些任务有损：需要精确权重更新的场景（继续预训练、大幅改变输出分布的微调）不适合把基座压到 4-bit。其四，分页优化器在内存压力大时引入不可预测的步时抖动。

选择判据：显存不足以容纳 bf16 基座时用 QLoRA；显存足够但需要高频合并部署时用 bf16 LoRA；数据量极大、追求吞吐时用 bf16 LoRA；需要改变基座分布时用全量微调或继续预训练（[[继续预训练与领域适配]]）。三者的显存差异已经由前面的公式给出，不需要实测即可估算。

## 关键直觉

> [!tip] LoRA 把权重更新重参数化为两个窄矩阵的乘积，QLoRA 把基座存储的位宽压低
> LoRA 的可达集合是"秩不超过 $r$ 的矩阵"，参数化 $\Delta\mathbf{W}=\mathbf{B}\mathbf{A}$ 恰好覆盖该集合（第 2 节），因此限制来自秩而不是形式。训练时只有 $\mathbf{A},\mathbf{B}$ 进入优化器，基座权重的梯度与 Adam 状态全部消失，这是 $16P$ 取代 $16N$ 的原因；但基座仍要驻留显存参与前向，激活也仍要保存，因此显存不是按参数量比例下降。
> 初始化 $\mathbf{B}=\mathbf{0}$ 使 $\Delta\mathbf{W}(0)=\mathbf{0}$，训练起点与基座逐位一致；由此产生的首步梯度结构是"$\mathbf{B}$ 有梯度、$\mathbf{A}$ 无梯度"，属于代数结果而非缺陷。
> 合并 $\mathbf{W}'=\mathbf{W}_{0}+s\mathbf{B}\mathbf{A}$ 是恒等变换，所以推理延迟不增加；这是可合并性的全部内容，与"LoRA 参数少所以快"无关。
> QLoRA 与 LoRA 正交：前者压缩基座的存储位宽，后者压缩需训练的参数集合。两者叠加时，计算仍在 bf16 进行，量化误差只进入权重存储，不进入梯度累积。

## 例子与代码

### 例 1：参数量与占比的手算核对

以下代码只使用标准库，Python 3.10 及以上可运行。

```python
D, FFN, L, N = 4096, 11008, 32, 6_738_415_616

def per_module(r):
    return {"q_proj": r * (D + D), "k_proj": r * (D + D), "v_proj": r * (D + D),
            "o_proj": r * (D + D), "gate_proj": r * (D + FFN),
            "up_proj": r * (D + FFN), "down_proj": r * (FFN + D)}

pm = per_module(8)
for name, p in pm.items():
    print(f"{name:<12}{p:>10,}")
print(f"{'per layer':<12}{sum(pm.values()):>10,}")
print(f"{'total':<12}{sum(pm.values()) * L:>10,}{100 * sum(pm.values()) * L / N:>9.4f}%")
print()
print(f"{'rank':<6}{'all-linear':>12}{'share':>9}{'q,v only':>13}{'share':>9}")
for r in (1, 2, 4, 8, 16, 32, 64):
    total = sum(per_module(r).values()) * L
    qv = 2 * r * (D + D) * L
    print(f"{'r=' + str(r):<6}{total:>12,}{100 * total / N:>8.4f}%{qv:>13,}{100 * qv / N:>8.4f}%")
print()
print("q_proj at r=8 share of its d*k:", 8 * (D + D) / (D * D))
gpt3 = 96 * 2 * 4 * (12288 + 12288)
print("GPT-3 175B q,v r=4:", gpt3, "one over", round(175e9 / gpt3))
```

```text
q_proj          65,536
k_proj          65,536
v_proj          65,536
o_proj          65,536
gate_proj      120,832
up_proj        120,832
down_proj      120,832
per layer      624,640
total       19,988,480   0.2966%

rank    all-linear    share     q,v only    share
r=1      2,498,560  0.0371%      524,288  0.0078%
r=2      4,997,120  0.0742%    1,048,576  0.0156%
r=4      9,994,240  0.1483%    2,097,152  0.0311%
r=8     19,988,480  0.2966%    4,194,304  0.0622%
r=16    39,976,960  0.5933%    8,388,608  0.1245%
r=32    79,953,920  1.1865%   16,777,216  0.2490%
r=64   159,907,840  2.3731%   33,554,432  0.4980%

q_proj at r=8 share of its d*k: 0.00390625
GPT-3 175B q,v r=4: 18874368 one over 9272
```

输出与公式一致。`per_module(8)` 的七行说明参数量只取决于 $r(d+k)$：四个方阵各 65,536，三个 $11008\times4096$ 矩阵各 120,832，后者是前者的 1.84 倍，因为 $d_{ff}=11008$ 约为 $d$ 的 2.7 倍，而 $(d+d_{ff})/(2d)=1.84$。七模块合计 624,640，乘 32 层得 19,988,480，除以 6,738,415,616 为 0.2966%。

`q_proj` 一行给出单模块比值 $1/256$，说明"低秩"在参数层面的直观含义：$r=8$ 时用 65,536 个参数表示一个 16,777,216 维的更新空间，只保留了 256 分之一。最后一行用 GPT-3 的配置做量级对照，18,874,368 是 175B 的约 $1/9{,}272$。

### 例 2：从零实现 LoRA 层与合并一致性检验

以下代码在 PyTorch 2.0 及以上运行。为便于核对，维度取小值，参数量可手算。

```python
import math
import torch
import torch.nn as nn

class LoRALinear(nn.Module):
    def __init__(self, in_features, out_features, r=8, alpha=16, dropout=0.0):
        super().__init__()
        self.base = nn.Linear(in_features, out_features, bias=False)  # 冻结的 W0
        self.r, self.scaling = r, alpha / r
        self.lora_A = nn.Parameter(torch.empty(r, in_features))       # A: r x k
        self.lora_B = nn.Parameter(torch.zeros(out_features, r))      # B: d x r，零初始化
        nn.init.kaiming_uniform_(self.lora_A, a=math.sqrt(5))
        self.dropout = nn.Dropout(dropout)                            # 作用在旁路输入上
        self.merged = False

    def forward(self, x):
        out = self.base(x)                                            # W0 x
        if not self.merged:
            out = out + self.scaling * (self.dropout(x) @ self.lora_A.T @ self.lora_B.T)
        return out

    @torch.no_grad()
    def merge(self):
        if self.merged:
            raise RuntimeError("already merged")                      # 重复合并会加倍更新
        self.base.weight += self.scaling * (self.lora_B @ self.lora_A)  # W' = W0 + sBA
        self.merged = True

    @torch.no_grad()
    def unmerge(self):
        if not self.merged:
            raise RuntimeError("not merged")
        self.base.weight -= self.scaling * (self.lora_B @ self.lora_A)
        self.merged = False

torch.manual_seed(0)
layer = LoRALinear(8, 8, r=2, alpha=4)
x = torch.randn(4, 8)

print(torch.allclose(layer(x), layer.base(x), atol=1e-6))   # 初始 Delta W = 0
layer.eval()                                                # 关闭 dropout 后再比较
with torch.no_grad():
    layer.lora_B.normal_(0.0, 0.02)                         # 模拟训练后的 B
ref = layer(x)
layer.merge()
print(torch.allclose(layer(x), ref, atol=1e-6))             # 合并前后一致
layer.unmerge()
print(torch.allclose(layer(x), ref, atol=1e-6))             # 反合并恢复
layer.merge()
try:
    layer.merge()
except RuntimeError as e:
    print(type(e).__name__)
print(sum(p.numel() for p in layer.parameters()))           # 64 + 16 + 16 = 96
```

```text
True
True
True
RuntimeError
96
```

第一行验证初始化：$\mathbf{B}=\mathbf{0}$ 时 $\Delta\mathbf{W}=\mathbf{0}$，适配器层的输出与 `base` 的输出逐元素相等。记录 `ref` 之前先切到评估模式，关闭 dropout。第二行把 `base.weight` 改为 $\mathbf{W}_{0}+s\mathbf{B}\mathbf{A}$，前向跳过旁路，输出应与 `ref` 在 $10^{-6}$ 内一致；差异来自两种计算顺序的舍入。第三行验证反合并把权重恢复原值，一致性仍然成立。第四行是重复合并的保护：不检查 `merged` 标志的实现会再执行一次加法，得到 $\mathbf{W}_{0}+2s\mathbf{B}\mathbf{A}$，输出偏移且在损失曲线上不可见。第五行 96 = 64（$\mathbf{W}_{0}$）加 16（$\mathbf{A}$）加 16（$\mathbf{B}$），与 $r(d+k)+dk=2\times16+64$ 一致。

去掉 `self.merged` 标志与 `unmerge` 后，这段代码仍能训练，但无法验证合并的正确性；去掉 `raise` 后，重复调用 `merge` 会把更新累加两次，这是实际训练脚本中最常见的静默错误。

### 例 3：NF4 码本的构造与量化误差

以下代码用标准库构造等概率分位码本，并在正态权重块上比较它与均匀 4-bit 网格的误差。

```python
from statistics import NormalDist
import random

ND = NormalDist()
FIXED = [-1.0, -0.6961928009986877, -0.5250730514526367, -0.39491748809814453,
         -0.28444138169288635, -0.18477343022823334, -0.09105003625154495, 0.0,
         0.07958029955625534, 0.16093020141124725, 0.24611230194568634,
         0.33791524171829224, 0.44070982933044434, 0.5626170039176941,
         0.7229568362236023, 1.0]

def codebook():
    q = [ND.inv_cdf((i + 0.5) / 16) for i in range(16)]
    scale = max(abs(x) for x in q)
    return [x / scale for x in q]

cb = codebook()
print("quantiles:", [round(x, 3) for x in cb])
print("gap near 0:", round(cb[8] - cb[7], 3), "gap at edge:", round(cb[1] - cb[0], 3))
print("uniform  :", [round(-1.0 + 2.0 * i / 15, 3) for i in range(16)])

def quantize(w, grid):
    c = max(abs(x) for x in w)                 # 块内 absmax
    return [c * min(grid, key=lambda g: abs(g - x / c)) for x in w]

UNIFORM = [-1.0 + 2.0 * i / 15 for i in range(16)]
random.seed(0)
mse_fixed = mse_uniform = 0.0
count = 0
for _ in range(20_000):
    block = [random.gauss(0.0, 0.02) for _ in range(64)]
    for w, a, b in zip(block, quantize(block, FIXED), quantize(block, UNIFORM)):
        mse_fixed += (w - a) ** 2
        mse_uniform += (w - b) ** 2
        count += 1
print(f"NF4  MSE: {mse_fixed / count:.3e}")
print(f"INT4 MSE: {mse_uniform / count:.3e}")
print(f"ratio   : {mse_fixed / mse_uniform:.3f}")
print(f"bits/param 4.5 -> {4 + 8 / 64 + 32 / (64 * 256):.4f}")
```

```text
quantiles: [-1.0, -0.708, -0.542, -0.417, -0.311, -0.216, -0.127, -0.042, 0.042, 0.127, 0.216, 0.311, 0.417, 0.542, 0.708, 1.0]
gap near 0: 0.084 gap at edge: 0.292
uniform  : [-1.0, -0.867, -0.733, -0.6, -0.467, -0.333, -0.2, -0.067, 0.067, 0.2, 0.333, 0.467, 0.6, 0.733, 0.867, 1.0]
NF4  MSE: 3.378e-06
INT4 MSE: 4.022e-06
ratio   : 0.840
bits/param 4.5 -> 4.1270
```

第一行输出是纯分位构造的结果：零附近的间隔 0.084，边缘处 0.292，二者相差 3.5 倍。它与表 12.1 的固定码本不完全相同（后者含精确的 0，且整体略有偏移），但间隔分布一致，说明固定码本同样来自等概率划分。第二行给出均匀网格的固定间隔 0.1333，既不比 NF4 在零附近细，也不比它在尾部粗。

`quantize` 按块取 absmax 做归一化，与 NF4 的存储格式一致；比较两种码本时共用同一次归一化，因此误差差异只来自码本形状。模拟结果 0.840 说明在正态权重上 NF4 的平均平方误差比均匀网格低 16%。最后一行输出双重量化后的实际位宽 4.1270 bit，即每参数 0.5159 字节。

### 例 4：PEFT 与 QLoRA 的配置

以下代码在 transformers 4.40 及以上、peft 0.10 及以上、bitsandbytes 0.43 及以上运行，展示 4-bit 加载、适配器挂载与可训练参数统计。

```python
import torch
from transformers import AutoModelForCausalLM, BitsAndBytesConfig
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

bnb = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",           # 16 值分位码本
    bnb_4bit_use_double_quant=True,      # absmax 数组再量化
    bnb_4bit_compute_dtype=torch.bfloat16,
)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    quantization_config=bnb,
    device_map="auto",
)
model = prepare_model_for_kbit_training(model)   # 冻结基座、norm 转 fp32、关 use_cache

cfg = LoraConfig(
    r=16,
    lora_alpha=32,                       # s = alpha / r = 2
    lora_dropout=0.05,
    bias="none",                         # 不训练任何偏置
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                    "gate_proj", "up_proj", "down_proj"],
    task_type="CAUSAL_LM",
)
model = get_peft_model(model, cfg)
model.print_trainable_parameters()
```

```text
trainable params: 39,976,960 || all params: 6,738,415,616 || trainable%: 0.5933
```

输出中的可训练参数与例 1 的 $r=16$ 行一致，说明 `target_modules` 覆盖了七个线性层。`prepare_model_for_kbit_training` 做三件事：把基座参数设为不可训练、把归一化层转为 fp32、关闭 `use_cache` 以避免与梯度检查点冲突；若后续开启梯度检查点，它还会调用 `enable_input_require_grads`，否则冻结的嵌入层没有梯度，检查点会报"张量不需要梯度"。

`bias="none"` 表示不训练任何偏置；改为 `"all"` 会把归一化参数一并纳入，可训练参数从 39,976,960 增加到 40,243,200（增加 32 层各 2 个与末端 1 个归一化参数，共 $65\times4096$ 个），`trainable%` 随之改变，报告结果时必须注明。`lora_alpha=32` 与 `r=16` 给出 $s=2$；若把 $r$ 改为 8 而 `lora_alpha` 不变，$s$ 变为 4，有效更新幅度改变，需要重新扫描学习率。

## 易错点

> [!warning] 以下六条均可在代码或数值上直接检验。
> 1. 合并后继续训练或重复合并。`merge` 把 $s\mathbf{B}\mathbf{A}$ 写入 $\mathbf{W}_{0}$，适配器的梯度路径随之消失；再次 `merge` 会得到 $\mathbf{W}_{0}+2s\mathbf{B}\mathbf{A}$，输出偏移但训练日志无异常。检验方法是在合并前后各跑一次同一批输入，评估模式下最大绝对差应小于 $10^{-5}$（fp32）或 $10^{-2}$（bf16）。
> 2. dropout 位置错误或在训练模式下合并。PEFT 把 dropout 施加在旁路输入 $\mathbf{x}$ 上，而不是 $\mathbf{A}\mathbf{x}$ 上；两种放置的期望相同、方差不同，训练出的适配器统计性质不同。合并必须在 `eval()` 下进行，否则 `ref` 本身带随机性，一致性检验会随机失败。
> 3. `bias` 设置与参数量报告不一致。`bias="none"` 冻结全部偏置，`"all"` 训练全部偏置与归一化参数，`"lora_only"` 只训练被适配层的偏置。Llama 无线性层偏置，但归一化参数存在，`"all"` 会改变可训练参数量与合并语义，报告"0.59%"时必须注明 `bias` 取值。
> 4. 学习率过大且与 $\alpha/r$ 叠加。LoRA 常用学习率比全量微调高一到两个数量级（$10^{-4}$ 到 $3\times10^{-4}$ 对 $10^{-5}$ 到 $2\times10^{-5}$），而 $s$ 又线性放大旁路输出与梯度。两者同时取大值时，早期 $\Delta\mathbf{W}$ 过大，损失出现尖峰甚至发散；应先固定 $s\in\{1,2\}$，再单独扫描学习率。
> 5. 量化后 dtype 不一致。基座以 NF4 加载、计算 dtype 设为 bf16 时，若适配器被创建为 fp32 或输入张量为 fp16，矩阵乘会抛出 dtype 不匹配错误（典型信息为 `expected scalar type BFloat16 but found Float`）；合并时若把 `Params4bit` 权重当作普通张量做原地加法，会绕过量化结构或直接报错，正确做法是先反量化为 bf16 再合并。统一 `bnb_4bit_compute_dtype` 并在创建适配器后检查 dtype 可以避免。
> 6. 缩放应用两次或漏乘。合并时写成 `weight += lora_B @ lora_A` 而漏掉 $s$，合并后的输出与合并前相差 $(1-s)\mathbf{B}\mathbf{A}\mathbf{x}$；若合并代码又乘了一次 $s$，权重变为 $\mathbf{W}_{0}+s^{2}\mathbf{B}\mathbf{A}$，相差 $(s^{2}-s)\mathbf{B}\mathbf{A}\mathbf{x}$。两种错误都只在合并后显现，必须用一致性检验捕获。

## 关联笔记

- 前置 [[微调方法全景]]：该篇给出 PEFT 的分类、各类方法的参数量与显存对照，本篇展开其中使用最广的一种，并在第 8 节回答"适配哪些模块"。
- 前置 [[矩阵分解-SVD与特征分解]]：秩、奇异值与截断近似的定义来自该篇，第 2 节的 Eckart–Young 误差公式是其直接推论。
- 后续 [[指令微调SFT]]：本篇解决"如何以低显存训练"，该篇解决"用什么数据、如何组织损失与掩码"，两者组合才构成完整的微调流程。
- 对照 [[模型推理优化]]：该篇讨论量化推理、批处理与 KV 缓存优化，与本篇的 NF4 存储、合并部署共享同一组显存与延迟指标。
- 对照 [[继续预训练与领域适配]]：该篇处理分布偏移，指出低秩容量在需要新知识时的不足，与第 17 节的适用边界互补。

## 达标检测

- [ ] 写出 LoRA 的前向式与三个梯度公式（对 $\mathbf{A}$、$\mathbf{B}$、$\mathbf{x}$），标注形状，并解释 $\mathbf{B}=\mathbf{0}$ 时 $\mathbf{A}$ 的首步梯度为何为零。
- [ ] 用 Eckart–Young 定理说明秩 $r$ 近似的误差来源，并设计一个实验检验某任务的低秩假设是否成立。
- [ ] 计算 7B 模型在 $r=8$ 与 $r=16$、全线性层与仅 $q,v$ 两种配置下的参数量与占比，并解释四种结果的倍数关系。
- [ ] 证明合并的等价性，说明合并后推理延迟不增加的原因，并解释 bf16 下合并前后输出为何不逐位相同。
- [ ] 写出 NF4 的块量化与反量化公式，说明等概率分位构造与均匀网格的差别，并推导双重量化每参数节省 0.373 bit 的过程。
- [ ] 按 7B、$r=16$、$T=2048$、$B=1$、NF4 双重量化的配置逐项列出显存预算，指出哪一项随序列长度线性增长。
- [ ] 运行例 2，报告五项输出，并说明把 `merge` 中的 `self.scaling` 去掉后，哪一项检验会失败、失败的量级是多少。

## 参考来源

- Hu et al., "LoRA: Low-Rank Adaptation of Large Language Models", arXiv:2106.09685, 2021 —— 对应第 2 至 7 节的低秩分解、初始化、$\alpha/r$ 缩放、参数量公式与合并方式。
- Dettmers et al., "QLoRA: Efficient Finetuning of Quantized LLMs", arXiv:2305.14314, 2023 —— 对应第 11 至 16 节的 NF4 码本、双重量化位宽计算、分页优化器与显存算例。
- Hugging Face PEFT 官方文档（LoRA 概念指南与 `LoraConfig` 参数说明）—— 对应第 4 节的 `lora_A` 初始化方式、第 8 节的 `target_modules` 名称约定与例 4 的配置。
- Hugging Face Transformers 官方文档（`BitsAndBytesConfig` 与 4-bit 加载）—— 对应第 15 节的 `bnb_4bit_compute_dtype`、`bnb_4bit_use_double_quant` 语义与 dtype 约束。
- Goodfellow et al., *Deep Learning*, 2016, 第 2 章 —— 对应第 1 至 2 节的秩、奇异值分解与低秩近似的线性代数基础。
- 张奇等《大规模语言模型：从理论到实践》 —— 对应第 10 节的显存分解方法与第 17 节的工程取舍。
