✨Gemma 4 - 如何在本地运行

在本地运行 Google 全新的 Gemma 4 模型，包括 E2B、E4B、26B A4B 和 31B。

Gemma 4 是 Google DeepMind 的新开放模型家族，包括 12B, E2B, E4B, 26B-A4B，以及 31B。 这些多模态、混合推理模型支持 140+ 种语言，最长可达 256K 上下文，并有稠密版和 MoE 版。Gemma 4 采用 Apache-2.0 许可，可在你的本地设备上运行。

Gemma-4-12B 是新的，支持统一的文本、图像和音频。它运行在 8GB 内存（4-bit）或 14GB（8-bit）上。 Gemma-4-E2B 和 E4B 也支持图像和音频。运行在 5GB 内存 （4-bit）或 15GB（完整 16-bit）上。

运行 Gemma 4微调 Gemma 4Gemma 4 QATGemma 4 MTP

新： Gemma 4 MTP 来了！MTP 可在不损失准确率的情况下实现 1.4-2.2 倍更快的推理。可直接在 Unsloth Studio.

Gemma-4-26B-A4B 运行在 18GB （4-bit）或 28GB（8-bit）上。 Gemma-4-31B 需要 20GB 内存 （4-bit）或 34GB（8-bit）上。

你现在可以运行所有 GGUF， MLX ，并在 Unsloth Studio 中微调 Gemma 4（见右侧）。

QAT 版本 的 Gemma 4 在保持模型质量的同时，将内存需求降低约 3 倍。

6 月 9 日： Gemma 4 MTP 已上线。

6 月 5 日： Gemma 4 QAT 已发布。

6 月 2 日： Gemma 4 12B Unified 已发布。

4 月 20 日： 我们进行了 Gemma 4 GGUF 基准测试 ，帮助你选择最佳量化版本。

使用指南

Gemma 4 在推理、编码、工具使用、长上下文和智能体工作流以及多模态任务方面表现出色。较小的 E2B 和 E4B 版本面向手机和笔记本，而较大的模型则面向中高端 CPU / VRAM 系统，例如配备 NVIDIA RTX GPU 的电脑。

Gemma 4 变体	详情	最适合
E2B	稠密 + PLE（128K 上下文） 支持：文本、图像、音频	适用于手机/边缘端推理、ASR、语音翻译
E4B	稠密 + PLE（128K 上下文） 支持：文本、图像、音频	适用于笔记本和快速本地多模态使用的小模型
12B Unified	稠密（256K 上下文） 支持：文本、图像、音频	适用于笔记本和本地多模态使用的中型模型
26B-A4B	MoE（256K 上下文） 支持：文本、图像	电脑使用的最佳速度/质量平衡
31B	稠密（256K 上下文） 支持：文本、图像	在较慢推理下性能最强

查看 Gemma 4： 性能基准 和 GGUF 基准.

我应该选 26B-A4B 还是 31B？

• 26B-A4B - 在速度和准确率之间取得平衡。其 MoE 设计使它比 31B 更快，激活参数为 4B。如果内存有限，并且你愿意用一点质量换取速度，就选它。

• 31B - 目前最强的 Gemma 4 模型。如果你有足够内存，并且能接受稍慢的速度，就选它以获得最高质量。

硬件要求

表：Gemma 4 推理 GGUF 推荐硬件要求 （单位 = 总内存：RAM + VRAM，或统一内存）。你可以在 MacOS、NVIDIA RTX GPU 等设备上使用 Gemma 4。

Gemma 4 变体	4-bit	8-bit	BF16 / FP16
E2B	4 GB	5–8 GB	10 GB
E4B	5.5–6 GB	9–12 GB	16 GB
12B Unified	7–8 GB	13–14 GB	25 GB
26B A4B	16–18 GB	28–30 GB	52 GB
31B	17–20 GB	34–38 GB	62 GB

一般来说，你的总可用内存应至少超过你下载的量化模型大小。如果不足，llama.cpp 仍可通过部分 RAM / 磁盘卸载运行，但生成速度会更慢。你还需要更多计算资源，具体取决于你使用的上下文窗口。

推荐设置

建议使用 Google 的默认 Gemma 4 参数：

• temperature = 1.0

• top_p = 0.95

• top_k = 64

Gemma 4 的最大上下文是 128K 用于 E2B / E4B 和 262,144 用于 12B / 26B A4B / 31B.

思考模式

与旧版 Gemma 聊天模板相比，Gemma 4 使用标准的 system, assistant，以及 user 角色，并增加了显式思考控制。

如何启用思考：

添加 token <|think|> 到 系统提示词的开头.

已启用思考

<|think|>
你是一个细心的编码助手。请清楚地解释你的答案。

已禁用思考

你是一个细心的编码助手。请清楚地解释你的答案。

输出行为：

启用思考时，模型会在最终答案之前输出其内部推理通道。

<|channel>thought
[内部推理]
<channel|>
[最终答案]

禁用思考时，更大的模型在最终答案前仍可能输出一个 空思考块 。

<|channel>thought
<channel|>
[最终答案]

例如，使用“法国的首都是哪里？”：

<bos><|turn>system\n<|think|><turn|>\n<|turn>user\n法国的首都是哪里？<turn|>\n<|turn>model\n

然后它会输出：

<|channel>thought\n用户在询问法国的首都。\n法国的首都是巴黎。<channel|>法国的首都是巴黎。<turn|>

多轮对话规则：

对于多轮对话， 只保留聊天历史中的最终可见答案。不要 不要 把之前的思考块重新输入到下一轮。

<bos><|turn>user\n1+1 等于多少？<turn|>\n<|turn>model\n2<turn|>\n<|turn>user\n1+1 等于多少？<turn|>\n<|turn>model\n2<turn|>\n<|turn>user\n1+1 等于多少？<turn|>\n<|turn>model\n2<turn|>\n<|turn>user\n1+1 等于多少？<turn|>\n<|turn>model\n2<turn|>\n

如何禁用思考：

注意 llama-cli 可能不够稳定，因此请使用 llama-server 来禁用推理：

要 禁用思考 / 推理，使用 --chat-template-kwargs '{"enable_thinking":false}'

如果你使用的是 Windows Powershell，请使用： --chat-template-kwargs "{\"enable_thinking\":false}"

“true”和“false”可以互换使用。

运行 Gemma 4 教程

由于 Gemma 4 GGUF 有多种尺寸，小模型建议从 8-bit 开始，大模型建议从 动态 4-bit. Gemma 4 GGUF 或 MLX:

E2B	E4B	12b	26B-A4B	31B

🦥 Unsloth Studio 指南🦙 Llama.cpp 指南

你可以在我们的 Unsloth Studio✨ notebook：

Google Colabcolab.research.google.com

🦥 Unsloth Studio 指南

现在可以在 Unsloth Studio中运行和微调 Gemma 4，这是我们新的本地 AI 开源网页界面。Unsloth Studio 可让你在以下平台本地运行模型： MacOS、Windows、Linux 和：

• 搜索、下载， 运行 GGUF 和 safetensor 模型

• 自我修复 工具调用 + 网络搜索

• 代码执行 （Python、Bash）

• 自动推理 参数调优（temp、top-p 等）

• 通过 llama.cpp 进行快速 CPU + GPU 推理

• 训练 LLM 速度快 2 倍，VRAM 减少 70%

1

安装 Unsloth

在终端中运行：

MacOS、Linux、WSL：

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

Windows PowerShell：

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

2

启动 Unsloth

MacOS、Linux、WSL 和 Windows：

unsloth studio -H 0.0.0.0 -p 8888

然后打开 http://127.0.0.1:8888 在你的浏览器中。

3

搜索并下载 Gemma 4

首次启动时，你需要创建一个密码来保护你的账户，并重新登录。

然后进入 Studio Chat 标签页，在搜索栏中搜索 Gemma 4，并下载你想要的模型和量化版本。Unsloth 支持最新的 Gemma-4-12B Unified 模型。

4

运行 Gemma 4

在使用 Unsloth Studio 时，推理参数应会自动设置，不过你仍然可以手动修改。你还可以编辑上下文长度、聊天模板和其他设置。你可以运行 GGUF 和 MLX 文件。

如需更多信息，请查看我们的 Unsloth Studio 推理指南.

🦙 Llama.cpp 指南

在本指南中，我们将对 12B、26B-A4B 和 31B 使用 Dynamic 4-bit，对 E2B 和 E4B 使用 8-bit。参见： Gemma 4 GGUF 集合

对于这些教程，我们将使用 llama.cpp 进行快速本地推理，尤其是在你有 CPU 的情况下。

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=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp

2

如果你想直接使用 llama.cpp 来加载模型，可以根据每个模型按照下面的命令操作。 UD-Q4_K_XL 是量化类型。你也可以通过 Hugging Face 下载（第 3 步）。这与 ollama run 类似。使用 export LLAMA_CACHE="folder" 强制 llama.cpp 保存到特定位置。无需设置上下文长度，因为 llama.cpp 会自动使用所需的准确大小。

要 禁用思考 / 推理，使用： --chat-template-kwargs '{"enable_thinking":false}'

Windows Powershell： --chat-template-kwargs "{\"enable_thinking\":false}"

将“true”和“false”互换使用。

12B：

export LLAMA_CACHE="unsloth/gemma-4-12B-it-GGUF"
./llama.cpp/llama-cli \\
    -hf unsloth/gemma-4-12b-it-GGUF:UD-Q4_K_XL \\
    --temp 1.0 \\
    --top-p 0.95 \\
    --top-k 64

26B-A4B：

export LLAMA_CACHE="unsloth/gemma-4-26B-A4B-it-GGUF"
./llama.cpp/llama-cli \\
    -hf unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_XL \\
    --temp 1.0 \\
    --top-p 0.95 \\
    --top-k 64

31B：

export LLAMA_CACHE="unsloth/gemma-4-31B-it-GGUF"
./llama.cpp/llama-cli \\
    -hf unsloth/gemma-4-31B-it-GGUF:UD-Q4_K_XL \\
    --temp 1.0 \\
    --top-p 0.95 \\
    --top-k 64

E4B：

export LLAMA_CACHE="unsloth/gemma-4-E4B-it-GGUF"
./llama.cpp/llama-cli \\
    -hf unsloth/gemma-4-E4B-it-GGUF:Q8_0 \\
    --temp 1.0 \\
    --top-p 0.95 \\
    --top-k 64

E2B：

export LLAMA_CACHE="unsloth/gemma-4-E2B-it-GGUF"
./llama.cpp/llama-cli \\
    -hf unsloth/gemma-4-E2B-it-GGUF:Q8_0 \\
    --temp 1.0 \\
    --top-p 0.95 \\
    --top-k 64

3

你也可以通过下面的代码手动下载模型（在安装 pip install huggingface_hub之后）。你可以选择 UD-Q4_K_XL 或其他量化版本，例如 Q8_0 。如果下载卡住了，请查看： Hugging Face Hub、XET 调试

hf download unsloth/gemma-4-26B-A4B-it-GGUF \\
    --local-dir unsloth/gemma-4-26B-A4B-it-GGUF \\
    --include "*mmproj-BF16*" \\
    --include "*UD-Q4_K_XL*" # 动态 2bit 请使用 "*UD-Q2_K_XL*"

4

然后以对话模式运行模型（带视觉 mmproj-F16):

./llama.cpp/llama-cli \\
    --model unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \\
    --mmproj unsloth/gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf \\
    --temp 1.0 \\
    --top-p 0.95 \\
    --top-k 64

5

Llama-server 部署

要在 llama-server 上部署 Gemma-4，请使用：

./llama.cpp/llama-server \\
    --model unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \\
    --mmproj unsloth/gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf \\
    --temp 1.0 \\
    --top-p 0.95 \\
    --top-k 64 \\
    --alias "unsloth/gemma-4-26B-A4B-it-GGUF" \\
    --port 8001 \\
    --chat-template-kwargs '{"enable_thinking":true}'

MLX 动态量化

我们也上传了动态 4bit 和 8bit 量化版本，作为 MacOS 设备的首次试验！MLX 量化支持 视觉。

现在所有 MLX 量化版本都可在 Unsloth Studio!

Gemma 4	4-bit MLX	8-bit MLX
31B	链接	链接
26B-A4B	链接	链接
E4B	链接	链接
E2B	链接	链接

试用它们，请使用：

curl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/refs/heads/main/scripts/install_gemma4_mlx.sh | sh
source ~/.unsloth/unsloth_gemma4_mlx/bin/activate
python -m mlx_vlm.chat --model unsloth/gemma-4-26b-a4b-it-UD-MLX-4bit

Ollama 指南

现在 Ollama 也很好地支持 Unsloth GGUF。使用 curl -fsSL https://ollama.com/install.sh | sh 在 Linux 上安装 Ollama，或者使用 irm https://ollama.com/install.ps1 | iex 适用于 Windows。 要使用单个量化文件（小于 50GB），请使用：

ollama run hf.co/unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_XL

对于多个分片，例如较大的 BF16 分片，请这样做：

pip install -U huggingface_hub

# 分两次下载 mmproj 和 BF16
hf download unsloth/gemma-4-26B-A4B-it-GGUF --include "BF16/*" \
    --local-dir gemma4
hf download unsloth/gemma-4-26B-A4B-it-GGUF --include "mmproj-BF16.gguf" \
    --local-dir gemma4

mv gemma4/mmproj-BF16.gguf gemma4/BF16/
echo "FROM ./gemma4/BF16" > Modelfile

ollama create unsloth-gemma4 -f Modelfile
ollama run unsloth-gemma4

如果你看到 错误：500 内部服务器错误：无法加载模型 通过以下方式更新 Ollama： curl -fsSL https://ollama.com/install.sh | sh 或者使用 PowerShell 版本。

Gemma 4 最佳实践

提示示例

简单推理提示

系统：
<|think|>
你是一个严谨的推理助手。

用户：
一列火车于上午 8:15 出发，上午 11:47 到达。行程用了多长时间？

OCR / 文档提示

对于 OCR，请使用 较高的视觉 token 预算 例如 560 或 1120.

[先放图像]
提取这张收据中的所有文本。将商品条目、总额、商家和日期以 JSON 形式返回。

多模态比较提示

[图像 1]
[图像 2]
比较这两张截图，并告诉我哪一张更可能让新用户感到困惑。

音频 ASR 提示

将以下 {LANGUAGE} 语音片段转写为 {LANGUAGE} 文本。

按以下具体说明格式化答案：
* 仅输出转写内容，不要换行。
* 转写数字时请使用数字形式，例如写 1.7 而不是 one point seven，写 3 而不是 three。

音频翻译提示

先将以下 {SOURCE_LANGUAGE} 语音片段转写出来，然后翻译为 {TARGET_LANGUAGE}。格式化答案时，先输出 {SOURCE_LANGUAGE} 的转写内容，然后换行，再输出字符串 '{TARGET_LANGUAGE}: '，最后输出 {TARGET_LANGUAGE} 的翻译。

多模态设置

为了在多模态提示中获得最佳效果，请将多模态内容放在前面：

• 将 图像和/或音频放在文本之前.

• 对于视频，请先传入一系列帧，然后再传入指令。

音频和视频限制

• 音频 仅适用于 12B, E2B 和 E4B 。

• 音频支持的最长时长为 30 秒.

• 视频支持的最长时长为 60 秒 假设 每秒 1 帧 处理。

音频提示模板

ASR 提示

将以下 {LANGUAGE} 语音片段转写为 {LANGUAGE} 文本。

按以下具体说明格式化答案：
* 仅输出转写内容，不要换行。
* 转写数字时请使用数字形式，例如写 1.7 而不是 one point seven，写 3 而不是 three。

语音翻译提示

将以下 {SOURCE_LANGUAGE} 语音片段转写，然后翻译为 {TARGET_LANGUAGE}。
格式化答案时，先输出 {SOURCE_LANGUAGE} 的转写内容，然后换行，再输出字符串 '{TARGET_LANGUAGE}: '，最后输出 {TARGET_LANGUAGE} 的翻译。

📊 基准测试

Unsloth GGUF 基准测试

我们对各提供方的 Gemma 4 GGUF 进行了平均 KL 散度基准测试，帮助你选择最佳量化版本（越低越好）。

• KL 散度使所有 Unsloth GGUF 都位于 SOTA 帕累托前沿

• KLD 显示量化模型与原始 BF16 输出分布的匹配程度，体现保留的准确性。

26B A4B - KLD 基准测试（越低越好）

Gemma 官方基准测试

文本/代码基准测试

基准	Gemma 4 31B	Gemma 4 26B A4B	Gemma 4 12B Unified	Gemma 4 E4B	Gemma 4 E2B	Gemma 3 27B (no think)
MMLU Pro	85.2%	82.6%	77.2%	69.4%	60.0%	67.6%
AIME 2026（无工具）	89.2%	88.3%	77.5%	42.5%	37.5%	20.8%
LiveCodeBench v6	80.0%	77.1%	72.0%	52.0%	44.0%	29.1%
Codeforces ELO	2150	1718	1659	940	633	110
GPQA Diamond	84.3%	82.3%	78.8%	58.6%	43.4%	42.4%
Tau2	76.9%	68.2%	69.0%	42.2%	24.5%	16.2%
HLE（无工具）	19.5%	8.7%	5.2%	-	-	-
HLE（带搜索）	26.5%	17.2%	-	-	-	-
BigBench 超难	74.4%	64.8%	53.0%	33.1%	21.9%	19.3%
MMMLU	88.4%	86.3%	83.4%	76.6%	67.4%	70.7%

视觉基准测试

MMMU Pro	76.9%	73.8%	69.1%	52.6%	44.2%	49.7%
OmniDocBench 1.5（越低越好）	0.131	0.149	0.164	0.181	0.290	0.365
MATH-Vision	85.6%	82.4%	79.7%	59.5%	52.4%	46.0%
MedXPertQA MM	61.3%	58.1%	48.7%	28.7%	23.5%	-

音频基准测试

CoVoST	-	-	38.5*	35.54	33.47	-
FLEURS（越低越好）	-	-	0.069*	0.08	0.09	-
长上下文
MRCR v2 8 needle 128k（平均）	66.4%	44.1%	43.4%	25.4%	19.1%	13.5%