LoRA 深挖：每个超参在干什么

LoRA 看似只有 r 和 alpha 两个超参，实际 LoraConfig 里有 25+ 个字段。 本章按"对效果影响"的顺序排列，告诉你每个开关在调什么、什么时候该动它。

5.1LoRA 公式回顾

$$h = W_0 x + \Delta W \cdot x,\quad \Delta W = \frac{\alpha}{r}\, B A,\quad B\in\mathbb R^{d\times r},\;A\in\mathbb R^{r\times d}$$

$W_0$ 冻结、$A, B$ 可训。关键事实：

• $A$ 高斯初始化、$B$ 初始为零 → 训练开始时 $\Delta W = 0$，等价于 base 模型；
• scaling $\alpha/r$ 单独控制 update 的强度，不动 $A, B$ 本身的方差；
• 可学参数量 = $2dr$（一个 Linear），相对全参 $d \times d$ 比例 $2r/d$。

5.2r（rank）

$r$ 直接决定容量。经验起点：

r 翻倍后参数量翻倍、显存翻倍，但边际效果递减。一般 r=16 是甜点。

5.3lora_alpha 和 scaling

scaling = $\alpha/r$。LoRA 论文设 $\alpha = r$，即 scaling = 1；社区惯例 $\alpha = 2r$，即 scaling = 2。理由：

• 固定 $\alpha$ 时，调 r 只改容量、不改 update 幅度；
• 固定 $\alpha = 2r$ 时，update 幅度跟 r 同步增大，效果通常更稳。

调试时建议先固定 alpha = 2r，调 r 找甜点，最后再微调 alpha。

rsLoRA：让 scaling 更稳

大 r（> 32）时 $\alpha/r$ 会很小，update 信号减弱。rsLoRA 改成 $\alpha / \sqrt{r}$：

$$\Delta W = \frac{\alpha}{\sqrt{r}}\, BA$$

启用：LoraConfig(use_rslora=True, ...)。当 r > 16 时建议开。

5.4target_modules

选哪些 layer 上 LoRA 是最影响效果的参数。常见配方：

实战建议：SFT 用 "all-linear" 起步；嫌慢再砍 MLP。

modules_to_save

这些模块不上 LoRA，但仍然可训且会被保存。典型场景：扩了词表后让 embedding/lm_head 全参微调。

LoraConfig(
    target_modules="all-linear",
    modules_to_save=["embed_tokens", "lm_head"],
)

5.5init_lora_weights

看 LoraConfig.init_lora_weights：

5.6lora_dropout

对 LoRA 的 input 做 dropout，防止过拟合。默认 0.0，SFT 数据少时设 0.05–0.1。位置：

$$h = W_0 x + (\alpha/r) B A\,\text{Dropout}(x)$$

注意 dropout 在 input 上而非 output——这样不会破坏 B 零初始化的对称性。

5.7bias 怎么处理

LoraConfig.bias 三档：

• "none"（默认）：bias 全冻结；
• "all"：所有 bias 都训；
• "lora_only"：只有 LoRA layer 自己的 bias 训。

通常 "none" 够用；调不上时可尝试 "all"。

5.8DoRA：把 magnitude 和 direction 分开

DoRA（Weight-Decomposed LoRA）把 $W = m \cdot \hat W$ 拆成方向 $\hat W$（单位列向量）和模长 $m$。LoRA 只更新方向：

$$W' = m \cdot \frac{W_0 + (\alpha/r) BA}{\lVert W_0 + (\alpha/r) BA \rVert_c}$$

启用：LoraConfig(use_dora=True, ...)。比 LoRA 多约 0.01% 参数（每列一个 m），但效果常比 LoRA 强 1-2%。代价：训练慢 30%。

实现：src/peft/tuners/lora/dora.py。

5.9训练时机：什么时候用什么变体

5.10对照其他低秩方法

LoRA 是基线，PEFT 还内置了一堆"分解方式不同"的变体（具体细节看后续章节）：

实战中 95% 用 LoRA / DoRA / rsLoRA 就够了，其他变体多是论文实验。

5.11init_lora_weights 10 种选项详解

LoraConfig 的 init_lora_weights 字段（tuners/lora/config.py:411–470）不只是 True/False。完整可选值：

"该选哪个？"实战经验：

• 普通 SFT：True（默认 Kaiming）就行；
• 追求快速收敛：pissa（需要给 base 模型权重做 SVD，启动慢但训练快）；
• 4bit QLoRA：loftq（必备，否则精度掉）；
• 有训练数据 calibration：corda（用 forward 激活算 init，比 pissa 更贴合任务）；
• 研究复现：eva / olora / orthogonal 看论文。

5.12rank_pattern / alpha_pattern：每层不同 rank

不是所有层都需要 r=16。LoraConfig 提供两个 dict 字段（config.py:441–446）实现层级异构 adapter：

cfg = LoraConfig(
    r=8,
    lora_alpha=16,
    target_modules="all-linear",
    rank_pattern={                       # ★ 正则匹配层名 → 自定义 r
        ".*q_proj": 32,                  # query 用大 rank
        ".*v_proj": 32,                  # value 用大 rank
        ".*\.mlp\..*": 4,                # MLP 用小 rank（参数量大，rank 小省内存）
    },
    alpha_pattern={                       # ★ 同样可以差异化 alpha
        ".*q_proj": 64,
    },
)

用途：

• attention 投影对小 LoRA 更敏感，MLP 反过来 → 给 attention 高 rank、MLP 低 rank；
• AdaLoRA 用同样字段的结果，只是它训练时动态调；
• 跟 target_modules 配合：先匹配 target，再用 pattern 覆盖具体 r/alpha。

5.13layers_to_transform + layers_pattern

"我只想动后 N 层" → LoraConfig.layers_to_transform：

cfg = LoraConfig(
    r=16,
    target_modules="all-linear",
    layers_to_transform=[28, 29, 30, 31],    # ★ 只在第 28-31 层加 LoRA
    layers_pattern=None,                       # 自动检测 layer 命名规律
)

"模型里怎么判断'第 i 层'？" → layers_pattern 是 layer 命名的正则（如 model\.layers\.(\d+)），不填则自动检测。这个字段配合 freeze_trainable_layers 风格的 freeze 微调用很方便（见 LLaMA-Factory ch06.13）。

5.14这章你需要带走的

• r 是容量旋钮，alpha 是 update 强度旋钮，默认 $\alpha = 2r$；
• target_modules 用 "all-linear" 起步，扩词表时配 modules_to_save；
• 大 r（≥ 32）开 use_rslora=True；
• 想刷 1-2% 效果开 use_dora=True（慢 30%）；
• QLoRA 长跑用 init_lora_weights="loftq"；
• 40+ LoRA 变体本质都是"换 $\Delta W$ 的分解方式"。