LoRA 原理：低秩矩阵分解

全参数微调的问题

微调一个 7B 参数的模型，如果更新全部参数：

• 参数量：7,000,000,000 个 float16 参数
• 存储：约 14 GB（仅参数本身）
• 训练时还需存储梯度 + 优化器状态（Adam 需要 3× 参数量）
• 总显存需求：约 112 GB，需要多张 A100

LoRA（Low-Rank Adaptation，Hu et al. 2021）提供了一个优雅的解决方案：不改变原始权重，只训练两个小矩阵。

低秩分解的数学原理

假设我们要更新一个权重矩阵 W ∈ ℝ^(d×k)。全参数微调会直接修改这个矩阵的每个元素。LoRA 的做法是引入一个旁路（side path）：

为什么低秩假设成立？

理解这一点需要了解预训练 LLM 的权重矩阵结构。研究发现，LLM 权重矩阵的奇异值（Singular Values，通过 SVD 分解得到）呈现出明显的"长尾分布"：少数几个大奇异值包含了矩阵的大部分信息，绝大多数小奇异值贡献极少。

import torch
import numpy as np
from transformers import AutoModelForCausalLM

# 分析预训练模型权重矩阵的奇异值分布
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Meta-Llama-3-8B",
    torch_dtype=torch.float32
)

# 获取第一层 attention 的 q_proj 权重
W = model.model.layers[0].self_attn.q_proj.weight.data

# SVD 分解
U, S, Vh = torch.linalg.svd(W, full_matrices=False)

# 分析奇异值：前多少个值包含了 90% 的信息？
cumulative_energy = torch.cumsum(S**2, dim=0) / (S**2).sum()
rank_90 = (cumulative_energy < 0.9).sum().item()
rank_99 = (cumulative_energy < 0.99).sum().item()

print(f"矩阵形状: {W.shape}")             # (4096, 4096)
print(f"90% 能量 rank: {rank_90}")        # 通常远小于 4096
print(f"99% 能量 rank: {rank_99}")        # 依然远小于 4096

# 微调更新量 ΔW 通常比原始权重更低秩
# 这是 LoRA 方法有效性的核心依据

推理时的权重合并

训练完成后，LoRA 权重可以合并进原始权重，推理时没有额外开销。这是 LoRA 相比于 Adapter（早期的参数高效微调方法）的关键优势：

from peft import AutoPeftModelForCausalLM

# 训练时的计算：h = W₀x + (α/r) × BAx （两次矩阵乘法）
# 推理前合并：W_merged = W₀ + (α/r) × BA  （只在合并时做一次）
# 合并后推理：h = W_merged × x             （只有一次矩阵乘法）

# 合并代码（PEFT 库提供）
model = AutoPeftModelForCausalLM.from_pretrained(
    "./lora-checkpoint",
    torch_dtype=torch.bfloat16
)
merged = model.merge_and_unload()   # 合并 LoRA 矩阵进基座权重
merged.save_pretrained("./merged-model")  # 保存为标准格式

# 注意：合并后无法"卸载" LoRA，也无法同时使用多个 LoRA 适配器
# 如需保持灵活性（如多任务切换），推理时不合并，直接带 LoRA 推理

关键超参数详解

rank（r）— 最重要的超参

rank 决定了 LoRA 矩阵的"容量"，也是对微调效果影响最大的超参数：

alpha（α）— 缩放因子

alpha 控制 LoRA 更新对最终权重的影响程度，通过 α/r 缩放因子起作用。主要规律：

target_modules — 应用到哪些层

from peft import LoraConfig

# 方案一：只训练 attention 的 q/v 投影（最保守）
# 原始 LoRA 论文的做法，参数最少，显存最省
config_minimal = LoraConfig(
    r=8,
    lora_alpha=16,
    target_modules=["q_proj", "v_proj"],   # 只有 attention QV
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM"
)

# 方案二：全量线性层（推荐，效果通常好 10-20%）
# 覆盖 attention 的 q/k/v/o 和 FFN 的 gate/up/down
config_full = LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=[
        "q_proj", "k_proj", "v_proj", "o_proj",  # Attention 层
        "gate_proj", "up_proj", "down_proj"      # FFN 层
    ],
    lora_dropout=0.0,   # 通常 FFN 已有 dropout，LoRA 不需要额外 dropout
    bias="none",
    task_type="CAUSAL_LM"
)

# 自动找到所有线性层（模型架构未知时的便捷方法）
config_auto = LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules="all-linear",  # PEFT 会自动找到所有 Linear 层
    task_type="CAUSAL_LM"
)

lora_dropout — 正则化

lora_dropout 在 A 矩阵的输出上应用 Dropout，起到正则化作用。经验值：

• 数据量 < 1000 条：dropout = 0.1（防止过拟合）
• 数据量 1000-10000 条：dropout = 0.05
• 数据量 > 10000 条：dropout = 0.0（数据量足够时 dropout 收益有限）

完整 LoRA 训练代码

from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments
from peft import LoraConfig, get_peft_model
from trl import SFTTrainer, SFTConfig
import torch

# 1. 加载基座模型（BF16 格式，比 FP16 更稳定）
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Meta-Llama-3-8B-Instruct",
    torch_dtype=torch.bfloat16,
    device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

# 2. 应用 LoRA 配置
lora_config = LoraConfig(
    r=16,
    lora_alpha=32,               # alpha = 2r，效果较激进
    target_modules=[              # 覆盖所有线性层
        "q_proj", "k_proj", "v_proj", "o_proj",
        "gate_proj", "up_proj", "down_proj"
    ],
    lora_dropout=0.05,           # 轻量正则化
    bias="none",                 # 不训练 bias（通常不需要）
    task_type="CAUSAL_LM"
)
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# 输出示例：trainable params: 41,943,040 || all params: 8,072,495,104 || trainable%: 0.52%

# 3. 训练配置（关键超参说明）
training_args = SFTConfig(
    output_dir="./lora-output",
    num_train_epochs=3,
    per_device_train_batch_size=4,
    gradient_accumulation_steps=4,    # 等效 batch_size = 16
    learning_rate=2e-4,              # LoRA 用较大学习率（比全参数高 10-100×）
    warmup_ratio=0.05,               # 5% steps 用于 warm-up
    lr_scheduler_type="cosine",      # Cosine 衰减，收敛更平滑
    logging_steps=10,
    evaluation_strategy="steps",
    eval_steps=100,
    save_steps=500,
    bf16=True,                       # 强制 BF16 训练
    gradient_checkpointing=True,     # 节省激活值显存（速度慢 20-30%）
    max_seq_length=2048,
    dataset_text_field="text",       # 数据集中存储文本的字段名
)

# 4. 启动训练
trainer = SFTTrainer(
    model=model,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    args=training_args,
)
trainer.train()

LoRA 的局限性与变体

诊断 LoRA 训练是否正常

# 监控 LoRA 训练健康度的关键指标

# 1. 打印可训练参数比例（应在 0.1% - 2%）
model.print_trainable_parameters()

# 2. 检查梯度流（排查梯度消失/爆炸）
for name, param in model.named_parameters():
    if param.requires_grad and param.grad is not None:
        grad_norm = param.grad.norm().item()
        if grad_norm > 10:                   # 梯度爆炸警告
            print(f"梯度爆炸: {name} = {grad_norm:.4f}")
        elif grad_norm < 1e-8:              # 梯度消失警告
            print(f"梯度消失: {name} = {grad_norm:.4f}")

# 3. 正常训练的 loss 曲线特征
# - 前 10% steps：loss 快速下降（warm-up 阶段）
# - 中间 80% steps：loss 稳定缓慢下降
# - 后 10% steps：loss 趋于平稳
# - eval loss 应始终接近 train loss（相差 > 0.5 可能是过拟合）