✨Gemma 3n：如何运行与微调

在本地使用动态 GGUF 在 llama.cpp、Ollama、Open WebUI 上运行 Google 新的 Gemma 3n 并使用 Unsloth 进行微调！

Google 的 Gemma 3n 多模态模型能处理图像、音频、视频和文本输入。提供 2B 和 4B 大小，支持 140 种语言的文本和多模态任务。您现在可以在本地运行并微调 Gemma-3n-E4B 和 E2B 使用本地 Unsloth.

使用我们的 免费 Colab 笔记本

Gemma 3n 具有 32K 上下文长度、30 秒音频输入、OCR、自动语音识别（ASR）以及通过提示的语音翻译。

运行教程微调教程修复 + 技术分析

Unsloth Gemma 3n（Instruct）以上的最佳配置上传：

Dynamic 2.0 GGUF（仅文本）	Dynamic 4-bit Instruct（用于微调）	16-bit Instruct
2B 4B	2B 4B	2B 4B

在 我们的合集这里.

🖥️ 运行 Gemma 3n

目前 Gemma 3n 仅在 文本格式 用于推理。

我们已 修复问题 仅在 Ollama 中 GGUF 无法正常工作的问题。若使用 Ollama 请重新下载。

⚙️ 官方推荐设置

根据 Gemma 团队，官方推荐的推理设置为：

temperature = 1.0, top_k = 64, top_p = 0.95, min_p = 0.0

• Temperature 为 1.0

• Top_K 为 64

• Min_P 为 0.00（可选，但 0.01 表现良好，llama.cpp 的默认值是 0.1）

• Top_P 为 0.95

• 重复惩罚（Repetition Penalty）为 1.0。（在 llama.cpp 和 transformers 中 1.0 表示禁用）

• 聊天模板：

  <bos><start_of_turn>user\nHello!<end_of_turn>\n<start_of_turn>model\nHey there!<end_of_turn>\n<start_of_turn>user\nWhat is 1+1?<end_of_turn>\n<start_of_turn>model\n

• 具有 \n换行渲染（最后一行除外）的聊天模板

<bos><start_of_turn>user
Hello!<end_of_turn>
<start_of_turn>model
Hey there!<end_of_turn>
<start_of_turn>user
What is 1+1?<end_of_turn>
<start_of_turn>model\n

llama.cpp 和其他推理引擎会自动添加一个 <bos> - 切勿添加两个 <bos> 标记！在提示模型时应忽略 <bos>！

🦙 教程：如何在 Ollama 中运行 Gemma 3n

请重新下载 Gemma 3N 量化文件或通过 Ollama 删除旧文件，因为已有一些 bug 修复。您可以按以下操作删除旧文件并刷新：

ollama rm hf.co/unsloth/gemma-3n-E4B-it-GGUF:UD-Q4_K_XL

ollama run hf.co/unsloth/gemma-3n-E4B-it-GGUF:UD-Q4_K_XL

1. 安装 ollama 如果您还没有安装！

apt-get update
apt-get install pciutils -y
curl -fsSL https://ollama.com/install.sh | sh

1. 运行模型！注意如果失败，您可以在另一个终端调用 ollama serve！我们在 params 的 Hugging Face 上传中包含了我们所有的修复和建议参数（如 temperature 等）！

ollama run hf.co/unsloth/gemma-3n-E4B-it-GGUF:UD-Q4_K_XL

📖 教程：如何在 llama.cpp 中运行 Gemma 3n

我们首先要感谢 Xuan-Son Nguyen 来自 Hugging Face， Georgi Gerganov 来自 llama.cpp 团队，让 Gemma 3N 在 llama.cpp 中可用！

1. 获取最新的 llama.cpp 在 此处的 GitHub。您也可以按照下面的构建说明操作。更改 -DGGML_CUDA=ON 为 -DGGML_CUDA=OFF 如果您没有 GPU 或仅想使用 CPU 推理，请设置。

apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggerganov/llama.cpp
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=ON -DGGML_CUDA=ON -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-quantize llama-cli llama-gguf-split llama-mtmd-cli
cp llama.cpp/build/bin/llama-* llama.cpp

1. 如果您想直接使用 llama.cpp 来加载模型，可以如下操作：（:Q4_K_XL）是量化类型。您也可以通过 Hugging Face 下载（见第 3 点）。这与 ollama run

./llama.cpp/llama-cli -hf unsloth/gemma-3n-E4B-it-GGUF:UD-Q4_K_XL -ngl 99 --jinja

1. 或 通过以下方式下载模型（在安装 pip install huggingface_hub hf_transfer 之后）。您可以选择 Q4_K_M，或其他量化版本（如 BF16 全精度）。

# !pip install huggingface_hub hf_transfer
import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id = "unsloth/gemma-3n-E4B-it-GGUF",
    local_dir = "unsloth/gemma-3n-E4B-it-GGUF",
    allow_patterns = ["*UD-Q4_K_XL*", "mmproj-BF16.gguf"], # 针对 Q4_K_XL
)

1. 运行模型。

2. 编辑 --threads 32 用于设置 CPU 线程数， --ctx-size 32768 用于上下文长度（Gemma 3 支持 32K 上下文长度！）， --n-gpu-layers 99 用于设置要在 GPU 上卸载的层数。如果您的 GPU 出现显存不足，请尝试调整它。如果仅使用 CPU 推理，也请移除该参数。

3. 用于对话模式：

./llama.cpp/llama-cli \
    --model unsloth/gemma-3n-E4B-it-GGUF/gemma-3n-E4B-it-UD-Q4_K_XL.gguf \
    --ctx-size 32768 \
    --n-gpu-layers 99 \
    --seed 3407 \
    --prio 2 \
    --temp 1.0 \
    --repeat-penalty 1.0 \
    --min-p 0.00 \
    --top-k 64 \
    --top-p 0.95

1. 用于非对话模式以测试 Flappy Bird：

./llama.cpp/llama-cli \
    --model unsloth/gemma-3n-E4B-it-GGUF/gemma-3n-E4B-it-UD-Q4_K_XL.gguf \
    --ctx-size 32768 \
    --n-gpu-layers 99 \
    --seed 3407 \
    --prio 2 \
    --temp 1.0 \
    --repeat-penalty 1.0 \
    --min-p 0.00 \
    --top-k 64 \
    --top-p 0.95 \
    -no-cnv \
    --prompt "<start_of_turn>user\nCreate a Flappy Bird game in Python. You must include these things:\n1. You must use pygame.\n2. The background color should be randomly chosen and is a light shade. Start with a light blue color.\n3. Pressing SPACE multiple times will accelerate the bird.\n4. The bird's shape should be randomly chosen as a square, circle or triangle. The color should be randomly chosen as a dark color.\n5. Place on the bottom some land colored as dark brown or yellow chosen randomly.\n6. Make a score shown on the top right side. Increment if you pass pipes and don't hit them.\n7. Make randomly spaced pipes with enough space. Color them randomly as dark green or light brown or a dark gray shade.\n8. When you lose, show the best score. Make the text inside the screen. Pressing q or Esc will quit the game. Restarting is pressing SPACE again.\nThe final game should be inside a markdown section in Python. Check your code for errors and fix them before the final markdown section.<end_of_turn>\n<start_of_turn>model\n"

请记得移除 <bos>，因为 Gemma 3N 会自动添加一个 <bos>！

🦥 使用 Unsloth 微调 Gemma 3n

Gemma 3n，像 Gemma 3一样，在 如 Colab 中的 Tesla T4 等 Float16 GPU 上运行时存在问题。如果不为 Gemma 3n 的推理或微调打补丁，您会遇到 NaN 和无穷值。 更多信息如下.

• 使用我们的微调 Gemma 3n-E4B 免费 Colab 笔记本

• 音频： 使用我们的微调 Gemma 3n-E4B 仅音频 笔记本

• 视觉：使用我们的微调 Gemma 3n-E4B 仅视觉 笔记本

我们还发现，由于 Gemma 3n 独特的架构在视觉编码器中重用隐藏状态，这在 如下所述的梯度检查点（Gradient Checkpointing）方面带来了另一个有趣的特性

Unsloth 是唯一一个在 float16 机器上使 Gemma 3n 推理和训练可行的框架。 这意味着配有免费 Tesla T4 GPU 的 Colab 笔记本也能工作！总体而言，Unsloth 使 Gemma 3n 训练快 1.5 倍、显存减少 50% 并支持 4 倍更长的上下文长度。

我们的免费 Gemma 3n Colab 笔记本默认微调文本层。如果您想微调视觉或音频层，请注意这将需要更多显存——超过免费 Colab 或 Kaggle 提供的 15GB。您 可以 仍然微调包括音频和视觉在内的所有层，Unsloth 也允许您仅微调特定区域，例如仅微调视觉层。只需按需调整：

model = FastVisionModel.get_peft_model(
    model,
    finetune_vision_layers     = False, # 如果不微调视觉层则为 False
    finetune_language_layers   = True,  # 如果不微调语言层则为 False
    finetune_attention_modules = True,  # 如果不微调注意力层则为 False
    finetune_mlp_modules       = True,  # 如果不微调 MLP 层则为 False
)

🏆附加内容

我们也听到大家想要一个 支持视觉的 Gemma 3（4B） 笔记本 所以这里有：

• 使用我们的微调 Gemma 3（4B）并支持视觉功能，使用 免费 Colab 笔记本

如果您喜欢 Kaggle，Google 正在举办一个竞赛，使用 Gemma 3n 和 Unsloth 微调出的最佳模型将赢得 1 万美元奖金！ 在此查看更多信息.

🐛 Gemma 3n 的修复

✨GGUF 问题与修复

感谢来自以下讨论的贡献 Michael 来自 Ollama 团队，以及 Xuan 来自 Hugging Face，我们需要为 GGUF 专门修复两个问题：

1. 参数 add_shared_kv_layers 被意外地以 float32 编码，这本身没有问题，但在 Ollama 端解码时变得稍微复杂——简单改为 uint32 即可解决该问题。 已提交拉取请求（Pull request） 解决此问题。

2. 参数 per_layer_token_embd 层的精度应为 Q8_0。低于此的精度在 Ollama 引擎中无法正确工作并会报错——为了减少社区问题，我们在所有量化文件中将其设置为 Q8_0——但不幸的是这会占用更多空间。

   1. 作为一次 更新, Matt 提到我们也可以对嵌入使用 Q4_0、Q4_1、Q5_0、Q5_1 —— 我们确认这些在 Ollama 中也能工作！这意味着更小的 2、3 和 4bit 量化文件体积更小，不需要 Q8_0！

♾️无穷与 NaN 梯度及激活

Gemma 3n 与 Gemma 3 一样在 FP16 GPU（例如 Colab 中的 Tesla T4）上存在问题。

我们之前对 Gemma 3 的修复 在此讨论。对于 Gemma 3，我们发现激活值会超过 float16 的最大范围 65504.

Gemma 3N 没有此激活问题，但我们仍然遭遇了无穷值！

为了解这些无穷值，我们绘制了 Gemma 3N 的权重绝对最大值，并看到如下情况：

我们发现绿色叉号是 Conv2D 卷积权重。我们可以看到 Conv2D 层的幅度平均要大得多。

下面是一张具有大幅度的 Conv2D 权重表。我们的假设是，在 Conv2D 运算期间，大权重相乘并累加， 不幸的是恰好超过了 float16 的最大范围 65504。 Bfloat16 没问题，因为它的最大范围为 10^38。

名称	最大值
msfa.ffn.pw_proj.conv.weight	98.000000
blocks.2.21.attn.key.down_conv.weight	37.000000
blocks.2.32.pw_exp.conv.weight	34.750000
blocks.2.30.pw_exp.conv.weight	33.750000
blocks.2.34.pw_exp.conv.weight	33.750000

🎇解决无穷值的方案

最简单的解决方案是将所有 Conv2D 权重 上采样为（upcast） float32（如果不可用 bfloat16）。但那会增加显存使用。为了解决此问题，我们改为使用 autocast 在运行时将权重和输入上采样为 float32，因此我们在矩阵乘法过程中以 float32 进行累加，而无需显式上采样权重。

Unsloth 是唯一一个使 Gemma 3n 能在 float16 GPU 上进行推理和训练的框架，因此配有免费 Tesla T4 的 Colab 笔记本也能工作！

🏁梯度检查点问题

我们发现 Gemma 3N 的视觉编码器也很独特，因为它会重用隐藏状态。这不幸地限制了 Unsloth 的梯度检查点的使用，它本可以显著减少显存使用，因为无法应用于视觉编码器。

不过，我们仍设法利用了 Unsloth 的自动编译器 来优化 Gemma 3N！

🌵微调期间的大损失

我们还发现微调开始时损失值非常大——在 6 到 7 的范围内，但它们会很快下降。我们推测这可能有两种可能性：

1. 可能存在某些实现问题，但这不太可能，因为推理似乎正常工作。

2. 多模态模型总是似乎表现出这种行为 ——我们发现 Llama 3.2 Vision 的损失开始于 3 或 4，PixtraI 在 8 左右，Qwen 2.5 VL 也在 4 左右。由于 Gemma 3N 还包含音频，可能会放大起始损失。但这只是一个假设。我们还发现将 Qwen 2.5 VL 72B Instruct 量化后困惑度非常高（约 30 左右），但模型有趣的是仍能正常工作。

使用我们的 免费 Colab 笔记本

🛠️ 技术分析

Gemma 3n：MatFormer

那么 Gemma 3n 有什么特殊之处？它基于 Matryoshka Transformer 或 MatFormer 架构，意味着每个 transformer 层/块嵌入/套嵌逐渐更小的 FFN。可以把它想象成逐渐变小的杯子互相套在一起。训练时的设计使得在推理时您可以选择所需的规模并尽可能获得更大模型的性能。

还有逐层嵌入（Per Layer Embedding）可以缓存以减少推理时的内存使用。因此 2B 模型（E2B）是 4B（也称 5.44B）模型内部的一个子网络，这是通过逐层嵌入缓存并跳过音频和视觉组件仅专注于文本实现的。

MatFormer 架构通常以指数间隔的子模型进行训练，即每层的大小为 S, S/2, S/4, S/8 等。因此在训练时，输入会随机通过上述某个子块，使每个子块都有相等的学习机会。现在优点是，在推理时，如果您想要模型为原始大小的 1/4，您可以选择 S/4 大小的子块在每层中。

您还可以选择 混合搭配（Mix and Match） 在这里您可以选择例如， S/4 一层的子块大小为 S/2 另一层的子块大小为， S/8 另一层的子块大小为。实际上，您可以根据输入本身改变所选子模型，如果您愿意的话。基本上这像是在每一层选择您自己的结构。因此仅训练一个特定大小的模型，就等于创建了指数级数量的更小模型。没有任何学习被浪费。挺巧妙的吧。

图片来自 Gemma 3n 模型概览

使用我们的微调并尝试多模态 Gemma 3n 推理 免费 Colab 笔记本