Chapter 08

与 TRL / LLaMA-Factory / Axolotl 集成

📌 commit 1cf145c070ea Unsloth 是加速插件，不是替代品

Unsloth 的设计哲学是"加速插件"而非"独立训练框架"。本章教你怎么把 Unsloth 接到 TRL（SFTTrainer/DPOTrainer/GRPOTrainer）、LLaMA-Factory、Axolotl 这些上层框架里。共同的诀窍只有一句：把 model 用 FastLanguageModel 起就行。

8.1集成关系图

上层框架	Unsloth 怎么接	预期收益
TRL SFTTrainer	`model = FastLanguageModel.from_pretrained(...)` + `SFTTrainer(model=model, ...)`	2-5× 加速 + 省 30% 显存
TRL DPOTrainer	调 `PatchDPOTrainer()` + 用 FastLanguageModel	同上
TRL GRPOTrainer	调 `PatchFastRL("GRPO", FastLanguageModel)`	同上
LLaMA-Factory	YAML 加 `use_unsloth: true`	同上
Axolotl	YAML 加 `adapter: lora` + `plugins: [unsloth]`	同上
HuggingFace Trainer	直接用，无需额外配置	同上

8.2TRL SFTTrainer（最常用）

第 3 章已经演示过。完整模板：

from unsloth import FastLanguageModel
from trl import SFTTrainer
from transformers import TrainingArguments

# 1. Unsloth 加载模型
model, tokenizer = FastLanguageModel.from_pretrained(
    "unsloth/llama-3-8b-bnb-4bit",
    max_seq_length=2048, dtype=None, load_in_4bit=True,
)
model = FastLanguageModel.get_peft_model(
    model, r=16, target_modules=["q_proj","k_proj","v_proj","o_proj",
                                  "gate_proj","up_proj","down_proj"],
    lora_alpha=16, use_gradient_checkpointing="unsloth",
)

# 2. 普通 TRL SFTTrainer
trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    args=TrainingArguments(...),
)
trainer.train()

TRL 的所有功能（callbacks / packing / instruction template）原样可用。

8.3TRL DPOTrainer（偏好对齐）

DPO 需要"训练 actor + reference 模型"两份。Unsloth 通过 PatchDPOTrainer 让 DPOTrainer 也走 fast kernel：

from unsloth import FastLanguageModel, PatchDPOTrainer
from trl import DPOTrainer, DPOConfig

# ★ 必须在 import DPOTrainer 之前调
PatchDPOTrainer()

model, tokenizer = FastLanguageModel.from_pretrained(...)
model = FastLanguageModel.get_peft_model(model, ...)

dpo_trainer = DPOTrainer(
    model=model,
    ref_model=None,        # ★ Unsloth 自动创建 ref（用 LoRA disable 实现）
    tokenizer=tokenizer,
    train_dataset=pref_dataset,
    args=DPOConfig(
        beta=0.1,
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        learning_rate=5e-6,
        ...
    ),
)
dpo_trainer.train()

关键点：

不需要单独加载 ref model。Unsloth 通过 "LoRA disable / enable" 切换 actor 和 ref，显存只用一份模型；
这是 Unsloth DPO 比纯 TRL 还省一半显存的原因；
支持 IPO / KTO / ORPO / SimPO 等 DPO 系算法（DPOConfig 选 loss_type）。

8.4TRL GRPOTrainer（推理 RL）

v2026 新增。能在单卡训 R1 风格的 GRPO 模型：

from unsloth import FastLanguageModel, PatchFastRL
from trl import GRPOTrainer, GRPOConfig

# ★ 在 import GRPOTrainer 之前
PatchFastRL("GRPO", FastLanguageModel)

model, tokenizer = FastLanguageModel.from_pretrained(
    "unsloth/Qwen3-4B-bnb-4bit",
    max_seq_length=8192,
    fast_inference=True,         # ★ 用 vLLM 加速 rollout
    max_lora_rank=64,
)
model = FastLanguageModel.get_peft_model(model, r=32, ...)

def reward_func(completions, **kwargs):
    return [1.0 if check_correct(c) else 0.0 for c in completions]

grpo_config = GRPOConfig(
    use_vllm=True,                          # ★
    learning_rate=5e-6,
    num_generations=4,                       # 每 prompt 采 4 个
    max_prompt_length=512,
    max_completion_length=2048,
)

trainer = GRPOTrainer(
    model=model,
    processing_class=tokenizer,
    reward_funcs=[reward_func],
    args=grpo_config,
    train_dataset=dataset,
)
trainer.train()

Unsloth 在 v2026 把 vLLM 也集成进来，单 GPU 上一边训一边采样，实现真正的 single-GPU GRPO。

8.5LLaMA-Factory 集成

LLaMA-Factory v0.7+ 原生支持 Unsloth。YAML 加一行：

### model
model_name_or_path: unsloth/llama-3-8b-bnb-4bit
trust_remote_code: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 16
lora_target: all

### unsloth
use_unsloth: true                # ★ 关键开关

### dataset / output / train ... 后面都和普通 LLaMA-Factory 一样

LLaMA-Factory 检测到 use_unsloth: true 后，会用 FastLanguageModel 替代 HF AutoModel 加载，其他训练逻辑不变。详见 LLaMA-Factory ch10。

8.6Axolotl 集成

Axolotl v0.4+ 通过 plugin 支持 Unsloth：

base_model: unsloth/llama-3-8b-bnb-4bit
adapter: lora

plugins:
  - axolotl.integrations.spectrum.SpectrumPlugin
  - axolotl.integrations.unsloth.UnslothPlugin    # ★

lora_r: 16
lora_alpha: 16
lora_target_modules:
  - q_proj
  - k_proj
  ...

unsloth_lora_qkv: true
unsloth_lora_o: true
unsloth_lora_mlp: true
unsloth_cross_entropy_loss: true
unsloth_rms_norm: true
unsloth_rope: true

每个 unsloth_* 字段对应 patch 的某一项是否开启，可以细粒度控制（debug 时有用）。

8.7HuggingFace Trainer 集成

不用 TRL，直接 HF Trainer 也行：

from unsloth import FastLanguageModel
from transformers import Trainer, TrainingArguments

model, tokenizer = FastLanguageModel.from_pretrained(...)
model = FastLanguageModel.get_peft_model(model, ...)

trainer = Trainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=tokenized_dataset,         # 自己 tokenize 好
    args=TrainingArguments(...),
)
trainer.train()

这条路要自己 tokenize 数据（TRL SFTTrainer 帮你做这事），其他完全等价。

8.8continue pre-training

除了 SFT，Unsloth 也支持 continue pre-training（CPT）。需要单独的 UnslothTrainer：

from unsloth import FastLanguageModel, is_bfloat16_supported
from unsloth import UnslothTrainer, UnslothTrainingArguments

model, tokenizer = FastLanguageModel.from_pretrained(...)
model = FastLanguageModel.get_peft_model(model, ...)

trainer = UnslothTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=long_text_dataset,
    dataset_text_field="text",
    max_seq_length=2048,
    args=UnslothTrainingArguments(
        per_device_train_batch_size=2,
        gradient_accumulation_steps=8,
        warmup_ratio=0.1,
        num_train_epochs=1,
        learning_rate=5e-5,
        embedding_learning_rate=1e-5,      # ★ embedding 单独学习率
        bf16=is_bfloat16_supported(),
        optim="adamw_8bit",
        ...
    ),
)
trainer.train()

关键差异：embedding_learning_rate 用更小的 LR（因为预训练阶段 embedding 不应该变太多）。

8.9vision / VLM 集成（FastVisionModel）

v2025+ 支持 Llama-3.2-Vision、Qwen2-VL、Pixtral、Gemma-3-Vision 等：

from unsloth import FastVisionModel
from trl import SFTTrainer

model, processor = FastVisionModel.from_pretrained(
    "unsloth/Llama-3.2-11B-Vision-Instruct",
    load_in_4bit=True,
    use_gradient_checkpointing="unsloth",
)
model = FastVisionModel.get_peft_model(
    model,
    finetune_vision_layers=True,         # ★ 是否训 visual encoder
    finetune_language_layers=True,
    finetune_attention_modules=True,
    finetune_mlp_modules=True,
    r=16, lora_alpha=16,
)

trainer = SFTTrainer(
    model=model,
    tokenizer=processor.tokenizer,
    data_collator=UnslothVisionDataCollator(model, processor),
    train_dataset=vision_dataset,        # 含 image + text
    args=...,
)
trainer.train()

8.10切换不同上层框架的小贴士

诉求	推荐
30 行最快上手	TRL SFTTrainer + Unsloth
WebUI 拖拉拽	LLaMA-Factory + use_unsloth
英文社区 yaml 文化	Axolotl + unsloth plugin
偏好对齐 DPO	TRL DPOTrainer + PatchDPOTrainer
R1 风格 GRPO	TRL GRPOTrainer + PatchFastRL（v2026）
VLM 微调	FastVisionModel + TRL SFTTrainer
continue pre-training	UnslothTrainer + embedding_learning_rate
极致自定义	HF Trainer 直接接 FastLanguageModel

8.11调试集成时的"自检步骤"

当你怀疑 Unsloth 没接上时（速度没变快 / 显存没省），检查：

启动 log 是否打印 Unsloth 2026.5.x: Fast Llama patching；
是否有 RMSNorm = TRITON、LoRA = TRITON 等字样；
用 nvidia-smi 看 GPU 利用率，应该 95%+；
对照基准（HF + PEFT）跑同样配置，时间应该快 2-5×；
如果没 patch 生效，UNSLOTH_DEBUG=1 看哪一步 fallback 了。

8.12这章带走的

Unsloth 是加速插件，不是独立训练框架；
"接 Unsloth" = "把 model 用 FastLanguageModel 起"；
TRL（SFT/DPO/GRPO）/ LLaMA-Factory / Axolotl 都原生支持；
DPO 时不用单独 ref model，Unsloth 用 LoRA enable/disable 切换；
v2026 加 GRPO + vLLM 集成，单 GPU 训 R1 成为可能；
不确定有没有 patch 生效时，看启动 log 里的 = TRITON 标记。

← 上一章

长上下文

多 GPU：Unsloth Pro / 社区方案