Gemma 3n：如何运行与微调

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

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

使用我们的对 Gemma 3n 进行微调 免费 Colab 笔记本

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

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

Unsloth Gemma 3n（Instruct）上传及其最佳配置：

动态 2.0 GGUF（仅文本）	动态 4 位 Instruct（用于微调）	16 位 指令版
2B 4B	2B 4B	2B 4B

在此处查看我们所有的 Gemma 3n 上传，包括基础模型和更多格式， 我们的收藏在这里.

🖥️ 运行 Gemma 3n

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

我们已 修复问题 解决了 GGUF 在 Ollama 中无法正常工作的情况。如果使用 Ollama，请重新下载。

⚙️ 官方推荐设置

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

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

• 温度为 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 删除旧文件，因为有一些错误修复。你可以按以下操作删除旧文件并刷新：

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我们在 Hugging Face 上传中包含了所有修复和建议参数（如 temperature 等），位于 params 中！

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 上进行推理。 对于 Apple Mac / Metal 设备，设置 -DGGML_CUDA=OFF 然后照常继续 - Metal 支持默认启用。

apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/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、4 位量化文件体积更小，不需要 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

🎇解决无穷值的方案

最简单的解决方案是将 上转（upcast） 所有 Conv2D 权重上转为 float32（如果不可用 bfloat16）。但那会增加显存使用。为了解决这一点，我们改为使用 自动类型转换（autocast） 在运行时将权重和输入临时上转到 float32，因此我们在矩阵乘法本身中以 float32 执行累加，而无需永久上转权重。

Unsloth 是唯一能在 float16 GPU 上实现 Gemma 3n 推理与训练的框架，因此带有免费 Tesla T4 的 Colab 笔记本可行！

🏁梯度检查点问题

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

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

🌵微调期间的大损失

我们还发现微调开始时损失值非常大——在 6 到 7 的范围，但随着时间迅速下降。我们推测这可能由两种可能性导致：

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

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

使用我们的对 Gemma 3n 进行微调 免费 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 等的子模型。因此在训练时，输入会随机通过上述某个子块，使每个子块有相等的学习机会。其优势在于，在推理时，如果你希望模型为原始大小的四分之一，你可以选择 S/4 尺寸的每层子块。

你也可以选择 混合搭配（Mix and Match） 在其中你可以选择例如， S/4 某一层的 子块尺寸， S/2 另一层的 子块尺寸，以及 S/8 另一层的 子块尺寸。事实上，如果你愿意，还可以根据输入本身改变所选择的子模型。基本上就像在每一层选择你自己的结构。因此仅训练一个特定尺寸的模型，就创建了指数级许多更小尺寸的模型。没有学习被浪费。很巧妙，不是吗。

图片来自 Gemma 3n 模型概览

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