lora-qlora-recipes

LoRA 与 QLoRA 配方

本技能假设路由决策已经完成——finetuning-method-selection 应该已经指向了这里，因为数据形态是演示（SFT），而非偏好对或可验证的奖励信号。以下是配置适配器本身当前的最佳实践配方：以哪些模块为目标、如何设定 rank 和 alpha 的规模、使用什么学习率，以及 QLoRA 何时能带来真正的余量、何时只是徒增风险。数据集准备与质量检查是另一个独立关注点——参见 dataset-curation。

输入： 一个路由决策（通过 LoRA/QLoRA 进行 SFT）加上一个目标规模类别。 输出格式： 一份经过验证的适配器配置——即下面的 kwarg 取值，而非自由形式的建议——供 llm-finetuning-training-engineer 在生成可运行脚本时直接使用。

参考配方

参考配方是 "LoRA Without Regret"（Thinking Machines/Schulman，2025-09），现已成为 LoRA/QLoRA SFT 的既定惯例。

目标模块

以 all-linear 模块为目标，而不仅仅是注意力：

target_modules = [
    "q_proj", "k_proj", "v_proj", "o_proj",   # attention
    "gate_proj", "up_proj", "down_proj",      # MLP — matters most
]

MLP 层（gate_proj、up_proj、down_proj）最为重要——仅针对注意力是更早、更弱的惯例。为了节省内存而舍弃模块是下方的失败模式，而不是有效的优化。

Alpha 与学习率

• lora_alpha = 2 * r 是既定惯例（NeurIPS 2025 "intruder dimensions" 结果）。不要独立于 rank 手动调优 alpha——每次都从 rank 推导它。
• LoRA 学习率 ≈ 等效全量微调学习率的 10 倍。 具体到 QLoRA，2e-4 是标准的起点。完整超参数表和完整示例：references/hyperparameters.md。

按任务选择 Rank

Rank 由任务决定，而非单一的全局默认值：

任务	Rank
RL（GRPO/RLVR 适配器）	1–32
通用默认	16–32
大规模 SFT	最高约 256

更高的 rank 并不会自动更好——它在提升记忆容量的同时，也会以同样快的速度提升泛化容量。从与任务匹配的那一行开始，只有在较低 rank 在留出评估上可测量地欠拟合时，才向上移动一行，而不是作为默认的保险措施。

有效批次大小

保持有效批次大小低于 32。本配方是在该规模下验证的——将有效批次推得更高是未经测试的外推，而不是免费的吞吐量收益。

Unsloth 默认值

Unsloth 是本插件假定为默认快速路径的参考实现——但有一个例外：对于使用 assistant_only_loss=True 的 messages 形态对话式 SFT，Unsloth 2026.7.x 的编译版 trainer 根本没有 messages 形态的路径，此时纯 TRL 逃生通道（references/unsloth-trl-mapping.md）是该组合的默认选择，而不是罕见回归的兜底方案。其开箱即用的默认值，以及每个默认值如此设定的原因：

• lora_dropout=0 ——优化后的 kernel 路径假定 dropout 为零；设定非零值会丧失融合 kernel 的加速。
• bias="none" ——偏置项会增加适配器参数，而在此 rank 范围内质量提升可忽略不计。
• use_gradient_checkpointing="unsloth" ——Unsloth 的 checkpointing 变体，而非原版 HF checkpointing；相比不启用 checkpointing，大约节省 30% 显存。
• optim="adamw_8bit" ——8-bit AdamW 减少了优化器状态内存，而在 LoRA/QLoRA 适配器规模下对质量影响可忽略不计。
• 固定 random_state ——固定 LoRA 初始化以保证跨运行的可复现性；把它当作任何其他随机种子对待，而不是可调参数。

这些会一起出现在 get_peft_model 调用上：

model = FastLanguageModel.get_peft_model(
    model,
    r=32,
    target_modules=target_modules,
    lora_alpha=64,               # 2 * r
    lora_dropout=0,
    bias="none",
    use_gradient_checkpointing="unsloth",
    random_state=3407,
)

确切的 kwarg 名称及其在纯 TRL/PEFT 中的等价写法，外加包含 SFTConfig 的完整示例配置：references/unsloth-trl-mapping.md 和 references/hyperparameters.md。

LoRA vs QLoRA vs Full FT

情况	默认选择
在演示样本上适配行为	LoRA
基座模型在目标 rank 下无法以 bf16 装下	QLoRA
注入密集的新领域知识	Full FT（参见 finetuning-method-selection）
不确定选哪个	LoRA — 仅在显存迫使时才升级到 QLoRA

• QLoRA = NF4 量化的冻结基座权重 + BF16 适配器。正是这一点让 65B 级别的 模型能在 48GB 上训练 — 量化后的基座 才是显存收益的来源，而不是适配器本身。
• 完整微调不是默认选项。 把它留给 密集知识注入的场景，即目标是在权重层面 改变模型所知，而不是适配某种行为。对于 本技能范围内的其他一切情况，LoRA 或 QLoRA 才是起始假设。
• 在 DGX Spark 上，QLoRA 可能会在等效的 bf16 LoRA 运行尚能进行时就先 OOM，尽管 QLoRA 的稳态占用更小 — bitsandbytes 的 反量化缓冲区是加载期间瞬时飙高的 CUDA 侧分配。QLoRA 的 OOM 并不能证明 模型装不下；dgx-spark-ops 插件的 spark-memory-thermal-ops 技能涵盖了 完整的 OOM 补救阶梯（bf16 LoRA 是 下一步要尝试的，而不是进一步缩小 QLoRA）。

失败模式

• 在非 BF16 GPU 上出现 fp16 发散。 在 不具备可靠 BF16 支持的硬件上用 fp16 训练，是 loss 尖峰和静默发散的已知来源。 只要硬件支持，就强制 bf16=True；不要把 fp16 当作等效方案作为退路。在选择 dtype 之前先检查硬件支持：

  python -c "import torch; print(torch.cuda.is_bf16_supported())"
  

• 在小数据集上 rank 过高会过拟合。 为「大规模 SFT」挑选的 rank（最高约 256） 用在背后没有规模支撑的数据集上，会导致 记忆而非泛化。让 rank 与上文「按任务 选择 Rank」表匹配，而不是跟可用的 最大数字匹配。

• 为省显存而移除 target modules，会以 质量损失换来微不足道的节省。 gate_proj/up_proj/down_proj 上的适配器 参数只占模型总规模的很小一部分 — 砍掉 它们几乎不改变显存占用，却会明显损害 质量。如果显存紧张，先转向 QLoRA 或 降低 rank/batch/pack 长度，再考虑裁剪 target modules。

这三种失败模式有一个共同点：它们 看起来像训练循环的 bug（loss 尖峰、 平台期、记忆化），但实际上是配置选择 与上文参考配方相矛盾。在调试训练循环 本身之前，先对照本技能检查配置。

参考资料

• references/hyperparameters.md — 按任务类型 的完整 rank/alpha/LR 表、rsLoRA 说明、 batch/packing 交互，以及一份完整的 Unsloth 配置示例块。
• references/unsloth-trl-mapping.md — 每个 Unsloth kwarg 到其 TRL/PEFT 等价项的 映射、当前 TRL API 说明，以及何时回退到 纯 TRL 的逃生通道规则。

相关技能：finetuning-method-selection 会路由到这里；dataset-curation 涵盖本技能 不涉及的数据侧；llm-finetuning-training-engineer 是本技能所产出配置的下游消费者。