LoRA 原理与工程配置

LoRA（Low-Rank Adaptation，低秩适配）是当前 LLM 微调的事实标准：冻结预训练权重 (W_0)，只训练低秩增量 (\Delta W = BA)，在单卡上即可微调 7B–70B 模型。本篇聚焦工程配置；矩阵微积分与梯度推导见 Math-03/20 Attention 与 LoRA，优化配方见 Math-04/20 大模型训练与微调。

段末注释：PEFT（Parameter-Efficient Fine-Tuning，参数高效微调）泛指只更新少量附加参数的微调范式；LoRA 是 PEFT 中最常用的实现。

系列索引：微调技术路线导读

LoRA 低秩适配示意

一、原理：一行公式

对线性层 (y = W_0 x)，LoRA 注入：

$$
y = W_0 x + \frac{\alpha}{r} B A x
$$

符号	含义
(W_0 \in \mathbb{R}^{d \times k})	冻结的预训练权重
(A \in \mathbb{R}^{r \times k},\ B \in \mathbb{R}^{d \times r})	可训练低秩矩阵，(r \ll \min(d,k))
(r)	rank（秩），控制 adapter 容量
(\alpha)	缩放系数；有效步长 (\propto \alpha/r)

直觉：大矩阵的微调增量往往落在低维子空间；只学 (A,B) 即可近似任务所需的权重偏移，参数量从 billions 降到 millions。

二、在微调栈中的位置

AutoModelForCausalLM (冻结 W_0)
        │
        └─ peft.get_peft_model + LoraConfig
                │
                └─ 注入 target_modules 指定层
                        │
                        └─ SFTTrainer(peft_config=lora_config)

详见 SFTTrainer 详解 §七 LoRA 示例。

三、LoraConfig 关键参数

from peft import LoraConfig

lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
    target_modules="all-linear",  # 或 ["q_proj", "v_proj", ...]
)

参数	典型值	说明
`r`	8–64	越大容量越高、显存越大；分类窄任务 8–16 常够
`lora_alpha`	16–64	与 `r` 配合；有效缩放 (\alpha/r)，常用 2×
`lora_dropout`	0–0.1	训练时在 LoRA 分支上的 dropout
`target_modules`	见下节	挂载 LoRA 的层名
`bias`	`"none"`	一般不训 bias
`task_type`	`"CAUSAL_LM"`	Causal LM 微调

学习率：LoRA 常用 (10^{-4}) 量级，比全参 SFT（(2\times10^{-5})）高一个数量级——因为只更新少量参数，需更大步长才能有效收敛。见 Math-04/20 §2。

四、target_modules 选型

策略	配置	参数量	适用
最小	`["q_proj", "v_proj"]`	低	显存极紧、简单任务
注意力全量	`["q_proj","k_proj","v_proj","o_proj"]`	中	常见默认
注意力 + FFN	加上 `gate_proj`,`up_proj`,`down_proj`	高	复杂生成、领域适配
全覆盖	`"all-linear"`	最高	易跑通；AMD 实战采用

踩坑：不同模型层名不同（Llama 系 q_proj，GPT-2 系 c_attn）。Trainable params = 0 时打印 model.named_modules() 核对。

1
2
3

for name, _ in model.named_modules():
    if "proj" in name:
        print(name)

五、参数量估算

可训练参数近似：

$$
|\theta_{\mathrm{LoRA}}| \approx 2 \times r \times \sum_{\ell \in \mathcal{L}} (d_\ell + k_\ell)
$$

其中 (\mathcal{L}) 为挂载 LoRA 的层集合。7B 模型 r=16、all-linear 约 50M 可训练参数（见 AMD 实战 Step 11），仅为全参的 <1%。

六、与 SFTTrainer 集成

from trl import SFTTrainer, SFTConfig

trainer = SFTTrainer(
    model=base_model,           # 基座 ID 或 AutoModelForCausalLM
    train_dataset=train_ds,
    peft_config=lora_config,    # 自动注入 LoRA
    args=SFTConfig(
        learning_rate=1e-4,
        gradient_checkpointing=True,
        bf16=True,
    ),
)
trainer.train()
trainer.model.save_pretrained("./lora-out")  # 只存 adapter

续训已有 adapter：加载 PeftModel.from_pretrained(base, adapter_path)，不要再传 peft_config（见 SFTTrainer §十）。

七、rank 与 alpha 消融建议

任务复杂度	建议 rank	说明
格式约束分类（输出固定标签）	8–16	决策边界简单
单轮指令跟随	16–32	默认起点
多轮对话 / 长文本生成	32–64	需更大容量
领域 CPT+SFT	32–64	知识跨度大

固定 alpha/r = 2 做 rank 消融；若 underfit 升 rank，若 overfit 降 rank 或增 lora_dropout。

八、合并与部署

方式	命令/操作	场景
保留 adapter	`save_pretrained`	多任务切换、继续 DPO
合并进基座	`model.merge_and_unload()`	单任务部署、不支持 PEFT 的推理框架
Ollama ADAPTER	Modelfile `ADAPTER`	见 Ollama 对外服务

九、常见踩坑

现象	原因	对策
Trainable params = 0	`target_modules` 未匹配	打印层名修正
loss 不降	lr 过小或 rank 过小	试 `1e-4`、升 rank
过拟合 train、eval 差	rank 过大 / epoch 过多	降 rank、早停、增 dropout
推理无 LoRA 效果	未 load adapter	`PeftModel.from_pretrained`
ROCm QLoRA 失败	bitsandbytes 4bit 不稳定	BF16 基座 + LoRA（见 AMD 实战）

十、与其他 PEFT 方法（预告）

方法	相对 LoRA	本系列后续
QLoRA	4bit 量化基座 + LoRA	02-02
AdaLoRA	动态 rank 分配	02-03
DoRA	分解幅度与方向	02-03
IA³	只学缩放向量，参数更少	02-03

十一、小结

LoRA 用 (r)、(\alpha)、target_modules 三个旋钮在效果与显存间折中。实践默认：r=16, alpha=32, lr=1e-4，attention+FFN 或 all-linear，配合 SFTTrainer + gradient_checkpointing。验收不看 train loss alone，见评估指标系列。

下一步：03 SFTTrainer 详解 → 04 评估指标系列。