> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/mo-xing/gemma-4.md).

# Gemma 4 - 如何本地运行

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

**Gemma-4-12B** 是全新的，具备统一的文本、图像和音频支持。它可运行在 **8GB** RAM（4-bit）或 14GB（8-bit）上。 **Gemma-4-E2B** 和 **E4B** 也支持图像和音频。可运行在 **5GB RAM** （4-bit）或 15GB（完整 16-bit）上，通过 GGUF、MLX 或 NVFP4 量化版本。

<a href="/pages/10f714f4a513e0d0a86b6f9d5945f9014729b035#run-gemma-4-tutorials" class="button primary">运行 Gemma 4</a><a href="/pages/33fa9e3bb3ccf6a5c0011aa600e98abbe3a829e3" class="button secondary">微调 Gemma 4</a><a href="/pages/f7d9352762b9a21f7ce27fda96cda62b115a7574" class="button primary">Gemma 4 QAT</a><a href="/pages/920fe33c7186b6051fad8a9511be000eb5406bc7#gemma-4-mtp" class="button secondary">Gemma 4 MTP</a>

{% hint style="success" %}
**新：** [**Gemma 4 MTP 现已推出**](/docs/zh/mo-xing/mtp.md)**！MTP 可在不损失准确率的情况下实现 1.4-2.2 倍更快的推理速度。可直接在** [**Unsloth Studio**](/docs/zh/mo-xing/mtp.md#unsloth-studio-mtp-guide)**.**
{% endhint %}

{% columns %}
{% column %}
**Gemma-4-26B-A4B** 可运行在 **18GB** （4-bit）或 28GB（8-bit）上。 **Gemma-4-31B** 需要 **20GB RAM** （4-bit）或 34GB（8-bit）。

现在你可以运行所有 GGUF、 [MLX](#mlx-dynamic-quants) 以及在 [Unsloth Studio](#unsloth-studio-guide) 中微调 Gemma 4（见右侧）。

[**QAT** 变体](/docs/zh/mo-xing/gemma-4/qat.md) 的 Gemma 4 在保持模型质量的同时，可将内存需求降低约 3 倍。
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="/files/2dfd7fbf0b551d243091cd1054c69104594c25d5" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% hint style="success" %}
**6月9日：** [Gemma 4 MTP](/docs/zh/mo-xing/mtp.md) 已到来。

**6月5日：** [Gemma 4 QAT](/docs/zh/mo-xing/gemma-4/qat.md) 已发布。

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

**4月20日：** 我们进行了 [Gemma 4 GGUF 基准测试](#unsloth-gguf-benchmarks) 以帮助你选择最佳量化版本。
{% endhint %}

### 使用指南

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

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

**查看 Gemma 4：** [**性能基准**](#official-gemma-benchmarks) **和** [**GGUF 基准**](#unsloth-gguf-benchmarks)**.**

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

* **26B-A4B** - 在速度和准确率之间取得平衡。其 MoE 设计使其比 31B 更快，且只有 4B 活跃参数。如果 RAM 有限，并且你愿意用一点质量换取速度，就选它。
* **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 |

{% hint style="info" %}
通常情况下，你的可用总内存应至少大于你下载的量化模型大小。如果不够，llama.cpp 仍可通过部分 RAM/磁盘卸载运行，但生成速度会更慢。根据你使用的上下文窗口大小，你还需要更多算力。
{% endhint %}

### 推荐设置

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

* `temperature = 1.0`
* `top_p = 0.95`
* `top_k = 64`

{% hint style="info" %}
Gemma 4 的最大上下文长度是 **128K** 用于 **E2B** / **E4B** 和 `262,144` 用于 **12B** / **26B A4B** / **31B**.
{% endhint %}

#### 思考模式

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

**如何启用思考：**

添加标记 **`<|think|>`** 到 **系统提示词的开头**.

{% columns %}
{% column %}
**已启用思考**

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

{% endcolumn %}

{% column %}
**已禁用思考**

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

{% endcolumn %}
{% endcolumns %}

**输出行为：**

{% columns %}
{% column %}
启用思考后，模型会在最终答案之前输出其内部推理通道。

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

{% endcolumn %}

{% column %}
当思考被禁用时，更大的模型在最终答案之前仍可能输出一个 **空的思考块** 。

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

{% endcolumn %}
{% endcolumns %}

**例如，使用“**&#x6CD5;国的首都是哪里？”：

{% code overflow="wrap" %}

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

{% endcode %}

**然后会输出：**

{% code overflow="wrap" %}

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

{% endcode %}

**多轮对话规则：**

对于多轮对话， **只保留聊天记录中最终可见的答案**。不 **要** 将之前的思考块重新喂回下一轮。

{% code overflow="wrap" %}

```
<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
```

{% endcode %}

**如何禁用思考：**

注意 `llama-cli` 可能无法稳定工作，因此请使用 `llama-server` 来禁用推理：

{% hint style="warning" %}
要 [禁用思考/推理](#how-to-enable-or-disable-reasoning-and-thinking)，请使用 `--chat-template-kwargs '{"enable_thinking":false}'`

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

可将 'true' 和 'false' 互换使用。
{% endhint %}

## 运行 Gemma 4 教程

由于 Gemma 4 GGUF 有多种尺寸，小模型推荐从 8-bit 开始，而较大的模型则是 [**动态**](/docs/zh/ji-chu/dynamic-3.0-ggufs.md) **4-bit**. [Gemma 4 GGUF](https://huggingface.co/collections/unsloth/gemma-4) 或 [MLX](#mlx-dynamic-quants) 或 [NVFP4](#nvfp4-guide):

| [E2B](https://huggingface.co/unsloth/gemma-4-E2B-it-GGUF) | [E4B](https://huggingface.co/unsloth/gemma-4-E4B-it-GGUF) | [12b](https://huggingface.co/unsloth/gemma-4-12b-it-GGUF) | [26B-A4B](https://huggingface.co/unsloth/gemma-4-26B-A4B-it-GGUF) | [31B](https://huggingface.co/unsloth/gemma-4-31B-it-GGUF) |
| --------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |

<a href="/pages/10f714f4a513e0d0a86b6f9d5945f9014729b035#unsloth-studio-guide" class="button primary">🦥 Unsloth 桌面指南</a><a href="/pages/10f714f4a513e0d0a86b6f9d5945f9014729b035#llama.cpp-guide" class="button primary">🦙 Llama.cpp 指南</a><a href="/pages/10f714f4a513e0d0a86b6f9d5945f9014729b035#nvfp4-guide" class="button primary">NVFP4 指南</a>

{% columns %}
{% column %}
**你可以在我们的** [**Unsloth Studio**](/docs/zh/xin/studio.md)✨ **笔记本：**
{% endcolumn %}

{% column %}
{% embed url="<https://colab.research.google.com/github/unslothai/unsloth/blob/main/studio/Unsloth_Studio_Colab.ipynb>" %}
{% endcolumn %}
{% endcolumns %}

### 🦥 Unsloth 指南

现在你可以在 [Unsloth Desktop](/docs/zh/xin/studio.md)中运行和微调 Gemma 4，这是一款用于本地 AI 的新开源桌面 UI。Unsloth Studio 让你可以在本地运行模型，支持 **MacOS、Windows**、Linux 和：

{% columns %}
{% column %}

* 搜索、下载、 [运行 GGUF](/docs/zh/xin/studio.md#run-models-locally) 以及 safetensor 模型
* [**自我修复** 工具调用](/docs/zh/xin/studio.md#execute-code--heal-tool-calling) + **网页搜索**
* [**代码执行**](/docs/zh/xin/studio.md#run-models-locally) （Python、Bash）
* [自动推理](https://unsloth.ai/docs/desktop#feature-deep-dive) 参数调优（temp、top-p 等）
* 通过 llama.cpp 实现快速 CPU + GPU 推理
* [训练 LLM](/docs/zh/xin/studio.md#no-code-training) 速度快 2 倍，显存占用减少 70%
  {% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="/files/b0dfb852351654c29812a5aa23885913432eaa10" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% stepper %}
{% step %}

#### 安装 Unsloth

最简单的入门方式是下载 [Unsloth Desktop 应用](/docs/zh/desktop.md)。适用于 [macOS](/docs/zh/kuai-su-kai-shi/install/mac.md), [Windows](/docs/zh/kuai-su-kai-shi/install/windows-installation.md)，以及 [Linux](/docs/zh/kuai-su-kai-shi/install/linux.md).

<a href="https://unsloth.ai/download" class="button primary" data-icon="down-to-bracket">下载 Unsloth</a>

* <i class="fa-apple">:apple:</i> [下载 macOS 版本](https://unsloth.ai/download/mac)
* <i class="fa-windows">:windows:</i> [下载 Windows 版本](https://unsloth.ai/download/windows)
* <i class="fa-linux">:linux:</i> [下载 Linux 版本](https://unsloth.ai/download/linux)

或者，如果你更喜欢手动安装：

**MacOS、Linux、WSL：**

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

**Windows PowerShell：**

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

{% endstep %}

{% step %}

#### 启动 Unsloth

**MacOS、Linux、WSL 和 Windows：**

```bash
unsloth studio -H 0.0.0.0 -p 8888
```

然后打开 `http://127.0.0.1:8888` 或在浏览器中打开你的特定 URL。

**通过 HTTPS 和 Cloudflare 安全启动 Unsloth**

**新！** Unsloth 现在提供了一种通过免费的 Cloudflare 隧道以 HTTPS 安全启动 Unsloth 的方式。使用下面的命令（适用于 Windows、Mac 和 Linux）：

```bash
unsloth studio --secure
```

{% endstep %}

{% step %}

#### 搜索并下载 Gemma 4

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

然后前往 [Unsloth Chat](/docs/zh/xin/studio/chat.md) 标签页，在搜索栏中搜索 Gemma 4，并下载你想要的模型和量化版本。Unsloth 支持最新的 Gemma-4-12B Unified 模型。

<div data-with-frame="true"><figure><img src="/files/ae392b7077a8f5857a60be994eb52447f286483f" alt="" width="375"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### 运行 Gemma 4

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

更多信息请查看我们的 [Unsloth Studio 推理指南](/docs/zh/xin/studio/chat.md).

<div data-with-frame="true"><figure><img src="/files/650cd087ac9ab1b567e284813a7713806d466601" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

### 🦙 Llama.cpp 指南

在本指南中，我们将对 12B、26B-A4B 和 31B 使用 Dynamic 4-bit，对 E2B 和 E4B 使用 8-bit。见： [Gemma 4 GGUF 集合](https://huggingface.co/collections/unsloth/gemma-4)

对于这些教程，我们将使用 [llama.cpp](llama.cpphttps://github.com/ggml-org/llama.cpp) 进行快速本地推理，尤其是在你有 CPU 的情况下。

{% stepper %}
{% step %}
获取最新 `llama.cpp` **在** [**GitHub 这里**](https://github.com/ggml-org/llama.cpp)。你也可以按照下面的构建说明进行。将 `-DGGML_CUDA=ON` 改为 `-DGGML_CUDA=OFF` 如果你没有 GPU，或者只是想进行 CPU 推理。 **对于 Apple Mac / Metal 设备**，设置 `-DGGML_CUDA=OFF` 然后照常继续——Metal 支持默认已开启。

```bash
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
```

{% endstep %}

{% step %}
如果你想 `llama.cpp` 直接加载模型，可以按照下面的命令进行，具体取决于各个模型。 `UD-Q4_K_XL` 是量化类型。你也可以通过 Hugging Face 下载（第 3 步）。这类似于 `ollama run` 。使用 `export LLAMA_CACHE="folder"` 以强制 `llama.cpp` 保存到特定位置。无需设置上下文长度，因为 llama.cpp 会自动使用所需的精确大小。

{% hint style="warning" %}
要 [禁用思考/推理](#how-to-enable-or-disable-reasoning-and-thinking)，请使用： `--chat-template-kwargs '{"enable_thinking":false}'`

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

可将 '`true`' 和 '`false`互换使用。
{% endhint %}

**12B：**

```bash
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：**

```bash
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：**

```bash
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：**

```bash
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：**

```bash
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
```

{% endstep %}

{% step %}
你也可以通过下面的代码手动下载模型（在安装 `pip install huggingface_hub`之后）。你可以选择 `UD-Q4_K_XL` 或其他量化版本，例如 `Q8_0` 。如果下载卡住，请查看： [Hugging Face Hub，XET 调试](/docs/zh/ji-chu/troubleshooting-and-faqs/hugging-face-hub-xet-debugging.md)

```bash
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*" # 动态 2 位使用 "*UD-Q2_K_XL*"
```

{% endstep %}

{% step %}
然后以对话模式运行模型（带视觉 `mmproj-F16`):

{% code overflow="wrap" %}

```bash
./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
```

{% endcode %}
{% endstep %}

{% step %}

#### Llama-server 部署

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

```bash
./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}'
```

{% endstep %}
{% endstepper %}

### MLX 动态量化

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

{% hint style="success" %}
所有 MLX 量化现在都可在[ Unsloth Studio](#unsloth-studio-guide)!
{% endhint %}

| Gemma 4 | 4-bit MLX                                                           | 8-bit MLX                                                        |
| ------- | ------------------------------------------------------------------- | ---------------------------------------------------------------- |
| 31B     | [链接](https://huggingface.co/unsloth/gemma-4-31b-it-UD-MLX-4bit)     | [链接](https://huggingface.co/unsloth/gemma-4-31b-it-MLX-8bit)     |
| 26B-A4B | [链接](https://huggingface.co/unsloth/gemma-4-26b-a4b-it-UD-MLX-4bit) | [链接](https://huggingface.co/unsloth/gemma-4-26b-a4b-it-MLX-8bit) |
| E4B     | [链接](https://huggingface.co/unsloth/gemma-4-E4B-it-UD-MLX-4bit)     | [链接](https://huggingface.co/unsloth/gemma-4-E4B-it-MLX-8bit)     |
| E2B     | [链接](https://huggingface.co/unsloth/gemma-4-E2B-it-UD-MLX-4bit)     | [链接](https://huggingface.co/unsloth/gemma-4-E2B-it-MLX-8bit)     |

要试用它们，请使用：

{% code overflow="wrap" %}

```bash
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
```

{% endcode %}

### **NVFP4 指南**

我们上传了 [动态 NVFP4](/docs/zh/ji-chu/nvfp4.md) 用于在 NVIDIA Blackwell GPU 上更快进行 4-bit 推理的 Gemma 4 量化版本。以下是你可使用的模型（包括 Gemma 4）的硬件要求。另请查看你将获得的总体速度提升：

| Gemma 4 变体                                                         | 所需 VRAM | 比 BF16 更快 |
| ------------------------------------------------------------------ | ------: | --------: |
| [E2B](https://huggingface.co/unsloth/gemma-4-E2B-it-NVFP4)         |    7 GB |   快 1.12× |
| [E4B](https://huggingface.co/unsloth/gemma-4-E4B-it-NVFP4)         |    9 GB |   快 1.22× |
| [12B Unified](https://huggingface.co/unsloth/gemma-4-12b-it-NVFP4) |   11 GB |   快 1.26× |
| [26B A4B](https://huggingface.co/unsloth/gemma-4-26B-A4B-it-NVFP4) |   26 GB |   快 1.41× |
| [31B](https://huggingface.co/unsloth/gemma-4-31B-it-NVFP4)         |   32 GB |   快 1.45× |

<figure><img src="/files/240a6c62e1bfd3cb3bc2d9a2cb46fdf1ead5dd27" alt="" width="563"><figcaption></figcaption></figure>

#### **vLLM 教程：**

要运行 NVFP4 量化版本，请参见下方在 [vLLM](/docs/zh/ji-chu/inference-and-deployment/vllm-guide.md) 和 [SGLang](/docs/zh/ji-chu/inference-and-deployment/sglang-guide.md) 中运行 Gemma-4-26B-A4B 的命令（你可以将模型名称改为 `gemma-4-31B-it-NVFP4` 等）。另外，请不要选择任何 MoE 后端——让 vLLM 自行选择——例如 Marlin 会慢 2.5 倍！参见 [#marlin-vs-flashinfer-vs-cutlass-vs-cute-dsl](#marlin-vs-flashinfer-vs-cutlass-vs-cute-dsl "mention")如果你有 DGX Spark，请参见 [#dgx-spark-serving](#dgx-spark-serving "mention") 你必须使用 `--moe-backend flashinfer_b12x` 否则推理速度会慢很多。

要在单独的 venv 中安装 vLLM：

{% code overflow="wrap" expandable="true" %}

```bash
uv venv unsloth-nvfp4-env --python 3.13
source unsloth-nvfp4-env/bin/activate
uv pip install "vllm>=0.25.0" "flashinfer-python>=0.6.13" "nvidia-cutlass-dsl>=4.5.2" \\
    --torch-backend=auto
```

{% endcode %}

然后提供 26B MoE 变体：

```shell
vllm serve unsloth/gemma-4-26B-A4B-it-NVFP4
```

将 `unsloth/gemma-4-26B-A4B-it-NVFP4` 改为任意 [可用的 NVFP4](/docs/zh/ji-chu/nvfp4.md#overview) 量化名称！

要启用 MTP / speculative decoding（解码更快，但吞吐量会稍低），请使用：

```bash
vllm serve unsloth/gemma-4-26B-A4B-it-NVFP4
    --speculative-config '{"method": "mtp", "num_speculative_tokens": 2}'
```

如果你遇到 Torchcodec 问题，请务必先执行下面的操作，然后重新启动 vllm。

{% code overflow="wrap" expandable="true" %}

```bash
sudo apt-get update
sudo apt-get install -y ffmpeg
```

{% endcode %}

#### **带 NVFP4 量化的 DGX Spark**

为确保 DGX Spark 使用正确的内核（否则你会得到 **慢 2 倍的推理**），请先检查：

{% code overflow="wrap" expandable="true" %}

```bash
python -c "
import torch; from vllm.utils.flashinfer import has_flashinfer_b12x_gemm as g, has_flashinfer_b12x_moe as m
cap = torch.cuda.get_device_capability(); print('cap', cap, '| b12x gemm', g(), '| b12x moe', m()); assert cap[0] == 12 and g() and m(), 'b12x unavailable: serving would degrade to marlin W4A16'"
```

{% endcode %}

这不应当报错——如果报错了，请更新 vllm 或通过以下方式重新安装：

{% code overflow="wrap" expandable="true" %}

```bash
uv venv unsloth-nvfp4-env --python 3.13
source unsloth-nvfp4-env/bin/activate
uv pip install "vllm>=0.25.0" "flashinfer-python>=0.6.13" "nvidia-cutlass-dsl>=4.5.2" \\
    --torch-backend=auto
```

{% endcode %}

然后在 vLLM 中为 DGX Spark 提供服务：

{% code overflow="wrap" expandable="true" %}

```shellscript
export CUTE_DSL_ARCH=sm_121a
vllm serve unsloth/gemma-4-26B-A4B-it-NVFP4 --moe-backend flashinfer_b12x
```

{% endcode %}

如果你遇到 Torchcodec 问题，请务必先执行下面的操作，然后重新启动 vllm。

{% code overflow="wrap" expandable="true" %}

```bash
sudo apt-get update
sudo apt-get install -y ffmpeg
```

{% endcode %}

#### **SGLang 教程：**

```bash
python -m sglang.launch_server --model-path unsloth/gemma-4-31B-it-NVFP4 --speculative-algorithm NEXTN \\
     --speculative-num-steps 3 --speculative-eagle-topk 1 --speculative-num-draft-tokens 4
```

### Ollama 指南

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

{% code overflow="wrap" %}

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

{% endcode %}

对于较大的 BF16 分片等多个分片，请执行：

{% code overflow="wrap" %}

```bash
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
```

{% endcode %}

<div data-with-frame="true"><figure><img src="/files/1365c2c26a9d1c3ac868a82fdcbce2a48bfd4a53" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="info" %}
如果你看到 `Error: 500 Internal Server Error: unable to load model` 请通过以下方式更新 Ollama `curl -fsSL https://ollama.com/install.sh | sh` 或者使用 Powershell 那个。
{% endhint %}

## 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 输出分布的匹配程度，表明保留的准确性。

<div data-with-frame="true"><figure><img src="/files/165ac9ca11098b16b371d7ca880c4b6b77335e1f" alt=""><figcaption><p>26B A4B - KLD 基准测试（越低越好）</p></figcaption></figure></div>

### 官方 Gemma 基准测试

**文本/代码基准测试**

| 基准                  | Gemma 4 31B | Gemma 4 26B A4B | Gemma 4 12B Unified | Gemma 4 E4B | Gemma 4 E2B | Gemma 3 27B（不思考） |
| ------------------- | ----------- | --------------- | ------------------- | ----------- | ----------- | ---------------- |
| 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 Extra Hard | 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<sup>\*</sup>  | 35.54 | 33.47 | -     |
| ------------------------- | ----- | ----- | ------------------ | ----- | ----- | ----- |
| FLEURS（越低越好）              | -     | -     | 0.069<sup>\*</sup> | 0.08  | 0.09  | -     |
| **长上下文**                  |       |       |                    |       |       |       |
| MRCR v2 8 needle 128k（平均） | 66.4% | 44.1% | 43.4%              | 25.4% | 19.1% | 13.5% |

<div data-with-frame="true"><figure><img src="/files/c08e39442f65ecbed28e4b7974151644bf4f22ce" alt=""><figcaption></figcaption></figure></div>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://unsloth.ai/docs/zh/mo-xing/gemma-4.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.