如何用 Unsloth 微调 Gemma 4：完整实战指南

Unsloth 在 Gemma 4 发布当天就支持了全部四个变体：E2B、E4B、26B-A4B 和 31B。和标准 Hugging Face 训练流程相比，它通常能做到 2 倍训练速度，并把显存占用降低最多 70%，所以如果你打算在消费级硬件上做微调，它基本就是最务实的选择。

这篇指南会从模型选择开始，一直讲到数据集格式、LoRA 配置、多模态训练，以及如何把最终结果导出到 Ollama、llama.cpp 或 LM Studio。

应该微调哪个 Gemma 4 版本？

答案取决于你的硬件，以及你想得到什么结果。

Model	训练显存需求（LoRA, bf16）	最适合
E4B	~8–10 GB	笔记本、RTX 3060/4060、免费 Colab
E2B	~6–8 GB	多模态 + 音频任务、预算最紧
26B-A4B	~24+ GB（16-bit LoRA）	速度/质量平衡，RTX 3090/4090
31B	~20 GB（QLoRA 4-bit）	质量优先，NVIDIA A100 / 双 GPU

有几条判断很关键：

对大多数人来说，E4B 是最合理的起点。 它可以跑在免费的 Google Colab（T4 GPU）上，也能装进 12 GB 及以上显存的 RTX 显卡，并且同时支持文本和多模态（图像 + 音频）微调。Unsloth 也给它提供了免费的 Colab 笔记本。

不要在 26B-A4B 这个 MoE 模型上直接用 QLoRA。 因为 26B-A4B 是 Mixture-of-Experts 架构，Unsloth 明确建议对它使用 16-bit LoRA，而不是 4-bit QLoRA。MoE 路由和 4-bit 量化之间的组合表现不稳定。这个版本应使用 load_in_16bit=True，不要用 load_in_4bit=True。

如果你最在意最终质量，31B 是更适合的微调目标。 它是稠密模型，QLoRA 对它更友好，而且它目前在 Arena AI 文本榜单的开源模型里排在前列。

开始之前：安装并更新 Unsloth

如果你还没装 Unsloth，从这里开始。现在主要有两种用法：Unsloth Studio（免代码网页界面）和 Unsloth Core（Python 库，适合代码工作流）。

方案 A：Unsloth Studio（免代码，适合新手）

macOS、Linux 或 WSL：

curl -fsSL https://unsloth.ai/install.sh | sh

Windows PowerShell：

irm https://unsloth.ai/install.ps1 | iex

安装完成后，启动 Studio：

unsloth studio -H 0.0.0.0 -p 8888

然后在浏览器里打开 http://localhost:8888。首次启动时你需要设置一个密码，之后可以在向导里搜索 Gemma 4、选择模型大小和数据集。剩下的流程 Studio 会接管，你只需要在 UI 里观察训练进度并在完成后导出结果。

方案 B：Unsloth Core（代码方式）

如果你已经安装过 Unsloth，先更新：

pip install --upgrade --force-reinstall --no-cache-dir unsloth unsloth_zoo

如果是全新安装，并让它自动检测 PyTorch 后端：

pip install unsloth --torch-backend=auto

准备数据集

Gemma 4 使用标准的对话格式，角色是 user 和 model，不再是 Gemma 1/2/3 时代更旧的专用格式。你的训练数据应该类似这样：

{
  "messages": [
    {
      "role": "user",
      "content": "Classify the sentiment of this review: 'Shipping was late but the product is excellent.'"
    },
    {
      "role": "model",
      "content": "Mixed — negative sentiment toward shipping, positive toward the product."
    }
  ]
}

Gemma 4 数据格式有几条特别需要注意：

回答角色要用 "role": "model"，不要写成 "assistant"。这要和 tokenizer 的 chat template 保持一致。
Gemma 4 新增了原生 system prompt 支持。你可以在每段对话最前面加入 {"role": "system", "content": "..."}。
如果你想在训练里保留 thinking mode，可以把 <|think|> 放在 system prompt 的开头。如果你希望维持模型的推理能力，Unsloth 建议让推理型样本至少占到 75%。
对于多轮对话，只把最后一轮可见答案作为训练目标。不要把前面轮次里的思考内容再喂回后续对话。

数据量建议：

风格或语气微调：200–1,000 条高质量样本
领域适配（医疗、法律、技术）：10,000–50,000 条
指令跟随：5,000–20,000 条
分类或抽取任务：500–5,000 条

始终保留 10–20% 的数据做评估集。一个噪声样本或错误标注，往往会抵掉几十条干净样本的收益。

文本微调：完整代码示例

下面这个示例使用 LoRA 微调 Gemma 4 E4B 处理文本任务。把里面的数据集路径替换成你自己的数据源即可。

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

max_seq_length = 2048  # Start conservative. Scale up once the pipeline works.

# Load your dataset — it needs a "text" column, or use a chat-formatted dataset
dataset = load_dataset("json", data_files={"train": "your_dataset.jsonl"}, split="train")

# Load the model
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "google/gemma-4-e4b-it",
    max_seq_length = max_seq_length,
    load_in_4bit = False,    # For E4B and 31B dense: QLoRA (4-bit) also works
    load_in_16bit = True,    # bf16 LoRA — recommended starting point
    full_finetuning = False,
)

# Attach LoRA adapters
model = FastLanguageModel.get_peft_model(
    model,
    r = 16,                  # LoRA rank — higher = more capacity, more VRAM
    target_modules = [
        "q_proj", "k_proj", "v_proj", "o_proj",
        "gate_proj", "up_proj", "down_proj",
    ],
    lora_alpha = 16,
    lora_dropout = 0,
    bias = "none",
    use_gradient_checkpointing = "unsloth",  # Required for long context or tight VRAM
    random_state = 3407,
    max_seq_length = max_seq_length,
)

# Train
trainer = SFTTrainer(
    model = model,
    train_dataset = dataset,
    tokenizer = tokenizer,
    args = SFTConfig(
        max_seq_length = max_seq_length,
        per_device_train_batch_size = 1,
        gradient_accumulation_steps = 4,
        warmup_steps = 10,
        max_steps = 100,        # Replace with num_train_epochs for a real run
        logging_steps = 1,
        output_dir = "outputs_gemma4",
        optim = "adamw_8bit",
        seed = 3407,
        dataset_num_proc = 1,
    ),
)

trainer.train()

如果训练时爆显存怎么办？ 先试两件事：把 per_device_train_batch_size 降到 1，再把 max_seq_length 调小。use_gradient_checkpointing="unsloth" 不要关，它的作用就是在长上下文或紧张显存条件下把训练继续撑住。

微调 26B-A4B 这个 MoE 模型

MoE 版本的加载方式略有不同。这里要用 FastModel，并坚持用 16-bit LoRA：

import os
import torch
from unsloth import FastModel

model, tokenizer = FastModel.from_pretrained(
    model_name = "unsloth/Gemma-4-26B-A4B-it",
    max_seq_length = 2048,
    load_in_4bit = False,     # QLoRA not recommended for MoE
    load_in_16bit = True,     # bf16 LoRA
    full_finetuning = False,
)

加载完成后，LoRA adapter 的挂载方式和 E4B 示例一样。对于 MoE 微调，Unsloth 建议从 rank 16 和较短上下文开始，确认流程稳定后再逐步往上加。

多模态微调（E2B 和 E4B）

E2B 和 E4B 是 Gemma 4 里专门面向多模态任务的版本，它们原生支持图像和音频。如果你的微调任务涉及图像，可以用 FastVisionModel：

from unsloth import FastVisionModel
from unsloth.trainer import UnslothVisionDataCollator
from trl import SFTTrainer, SFTConfig

model, tokenizer = FastVisionModel.from_pretrained(
    model_name = "google/gemma-4-e4b-it",
    max_seq_length = 2048,
    load_in_4bit = False,
    use_gradient_checkpointing = "unsloth",
)

model = FastVisionModel.get_peft_model(
    model,
    finetune_vision_layers     = False,  # Start with text-only to save VRAM
    finetune_language_layers   = True,
    finetune_attention_modules = True,
    finetune_mlp_modules       = True,
    r = 16,
    lora_alpha = 16,
    lora_dropout = 0,
    bias = "none",
    target_modules = "all-linear",
)

trainer = SFTTrainer(
    model = model,
    tokenizer = tokenizer,
    data_collator = UnslothVisionDataCollator(model, tokenizer),
    train_dataset = dataset,
    args = SFTConfig(
        per_device_train_batch_size = 1,
        gradient_accumulation_steps = 4,
        learning_rate = 2e-4,
        output_dir = "outputs_gemma4_vision",
    ),
)

trainer.train()

一个容易踩坑的点： 在 Gemma 4 的多模态 prompt 里，图像必须放在文本指令前面。格式大概如下：

{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "image", "image": "path/to/image.jpg"},
        {"type": "text",  "text": "Describe what is happening in this image."}
      ]
    },
    {
      "role": "model",
      "content": "..."
    }
  ]
}

如果是音频微调（仅 E2B / E4B）：尽量保持音频片段短、小而专，并优先参考 Unsloth 的 Vision RL / Audio 示例笔记本来搭建流程。

如何保存并导出微调结果

训练完成后，可以根据你的部署目标走不同的导出路线。

保存成 LoRA adapter（最快、最小）

model.save_pretrained("gemma4_e4b_adapter")
tokenizer.save_pretrained("gemma4_e4b_adapter")

这样只会保存 adapter 权重，通常只有几百 MB，而不是整套基模型。推理时你仍然需要原始 base model。

合并并导出为 GGUF（给 llama.cpp / Ollama / LM Studio）

model.save_pretrained_gguf(
    "gemma4_e4b_finetuned",
    tokenizer,
    quantization_method = "q4_k_m"   # or "q8_0", "f16"
)

生成的 .gguf 文件可以直接被 llama.cpp 加载，也可以通过自定义 Modelfile 导入 Ollama，或直接放进 LM Studio。

从 Unsloth Studio 导出

如果你使用的是 Studio 界面，训练结束后进入 Export 标签页，选择 GGUF、safetensors，或两者都导出。Studio 会自动处理合并。

这里最值得注意的一点： 如果导出的模型放到别的 runtime（Ollama、llama.cpp）里表现异常，最常见的原因不是权重坏了，而是 chat template 或 EOS token 不一致。训练时用什么模板，推理时最好就保持一致。

免费 Colab 笔记本

Unsloth 为所有 Gemma 4 尺寸都提供了免费的 Google Colab 笔记本。E2B 和 E4B 可以跑在免费 T4 GPU 上；26B-A4B 和 31B 则需要 A100（Colab Pro）。

Model	Task	Link
E2B	Text	Open in Colab
E2B	Vision	Open in Colab
E2B	Audio	Open in Colab
26B-A4B	Vision (A100)	Open in Colab
31B	Vision (A100)	Open in Colab

常见问题

训练时内存不够。 先减小 max_seq_length，再把 per_device_train_batch_size 改成 1。确认 use_gradient_checkpointing="unsloth" 已经打开，它不是普通开关，而是影响长上下文和显存占用的关键项。

在 26B-A4B 上用 QLoRA。 MoE 架构和 4-bit 量化组合不稳定。对这个版本坚持使用 16-bit LoRA，也就是 load_in_16bit=True。

导出后 chat template 不匹配。 如果你的模型在 Ollama 或 llama.cpp 中回复异常，先检查推理 runtime 是否用了和训练阶段相同的 Gemma 4 chat template。这是导出后效果变差最常见的原因。

微调后推理能力明显变差。 如果你希望保住 Gemma 4 原生的推理能力，就要在训练集中混入足够多的 reasoning-style 样本。Unsloth 的建议是至少保留 75% 这类样本。

如果你想看官方训练参考，可以直接看 Unsloth documentation。