Unsloth 详解：LoRA/QLoRA 训练加速

Unsloth 不是又一整套 YAML 工厂，而是专注 LoRA/QLoRA 训练加速 的库：通过 Triton 手写内核减少前向/反向开销，在 NVIDIA GPU 上常显著缩短 step 时间。加速层定位见 03-00 横向对比；与 Liger 对比见 07-03。

段末注释：Triton 是 OpenAI 开源的 GPU 编程语言，用于编写高性能深度学习内核；Unsloth 核心算子以 Triton 实现。

系列索引：微调技术路线导读 | 旧版笔记：5023 Unsloth

一、定位

适合	不适合
单卡 QLoRA 快速迭代	必须 AMD ROCm 稳定训练（见 AMD 实战 BF16）
Llama/Gemma/Mistral/Qwen 等主流架构	自定义架构 / 改 loss
与 TRL `SFTTrainer` 组合	替代完整对齐平台（DPO/GRPO 仍靠 TRL）

二、安装

1 2	pip install unsloth # 官方常推荐指定 torch/cuda 组合，见 https://github.com/unslothai/unsloth

支持消费级 NVIDIA GPU（T4、RTX 20/30/40、A100 等）；ROCm 支持有限。

三、独立训练流程

from unsloth import FastLanguageModel
from trl import SFTTrainer, SFTConfig
from datasets import load_dataset

max_seq_length = 2048
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Meta-Llama-3.1-8B-bnb-4bit",
    max_seq_length=max_seq_length,
    load_in_4bit=True,
)

model = FastLanguageModel.get_peft_model(
    model,
    r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                    "gate_proj", "up_proj", "down_proj"],
    use_gradient_checkpointing="unsloth",  # 优化版 checkpointing
)

dataset = load_dataset("json", data_files="train.jsonl", split="train")

trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    args=SFTConfig(
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        learning_rate=2e-4,
        max_length=max_seq_length,
        completion_only_loss=True,
        output_dir="outputs",
        num_train_epochs=1,
    ),
)
trainer.train()

model.save_pretrained("lora_out")
tokenizer.save_pretrained("lora_out")

LoRA 参数见 02-01；QLoRA 见 02-02。

四、与 Hugging Face 权重互操作

可从 unsloth/ 前缀的 预量化模型 加载，省下载与转换。
也可对标准 HF 模型使用 FastLanguageModel.from_pretrained(..., load_in_4bit=True)。
保存的 adapter 一般可用 peft 加载；merge 见 02-04。

五、与 SFTTrainer / Liger 选型

	Unsloth	Liger (`use_liger_kernel=True`)
改动量	换模型加载类	SFTConfig 一行
加速来源	全流程内核	部分 loss/层融合
QLoRA	强项	依版本
绑定度	较高	低，仍在 TRL 内

建议：已有 TRL 脚本 → 先试 Liger；要极致 QLoRA 速度 → Unsloth。

六、数据格式

与 TRL 相同：JSONL messages 或 text；须与 01-01 template 一致。Unsloth 不解决数据清洗（01-02）。

七、验收

加速不改变训练目标；仍须 08-01 基线评估与 04 任务指标。对比实验时锁定 seed、数据子集。

八、常见踩坑

现象	对策
仅支持部分模型	查官方支持列表；换 `unsloth/` 镜像权重
`tokenizer` 与 TRL 版本	按 Unsloth 文档 pin 版本
ROCm 失败	改用 SFTTrainer + BF16 LoRA
与 Factory 同时装依赖冲突	独立 venv

九、小结

Unsloth = 在 TRL 之上换高速引擎，主攻单卡 LoRA/QLoRA。工厂选型用 LLaMA-Factory / ms-swift；编程与对齐用 SFTTrainer。

横向对比：03-00