> 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 - 如何本地运行
在本地运行 Google 的新 Gemma 4 模型，包括 E2B、E4B、26B A4B 和 31B。
Gemma 4 是 Google DeepMind 的新一代开放模型家族，包括 **12B**, **E2B**, **E4B**, **26B-A4B**，以及 **31B。** 这些多模态、混合思考模型支持 140 多种语言，最高可达 **256K 上下文**，并且有 Dense 和 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 量化运行。
运行 Gemma 4 微调 Gemma 4 Gemma 4 QAT Gemma 4 MTP
{% 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 %}
{% 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** | Dense + PLE（128K 上下文）
| 适用于手机/边缘推理、ASR、语音翻译 |
| **E4B** | Dense + PLE（128K 上下文）
| 适合笔记本电脑和快速本地多模态使用的小型模型 |
| **12B Unified** | Dense（256K 上下文）
| 适合笔记本电脑和本地多模态使用的中型模型 |
| **26B-A4B** | MoE（256K 上下文）
| 速度/质量权衡最佳，适合电脑使用 |
| **31B** | Dense（256K 上下文）
| 在较慢推理下性能最强 |
**查看 Gemma 4：** [**性能基准**](#official-gemma-benchmarks) **和** [**GGUF 基准**](#unsloth-gguf-benchmarks)**.**
**我应该选 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 位 | 8 位 | 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|>`** 到 **system 提示的开头**.
{% columns %}
{% column %}
**已启用思考**
```
<|think|>
你是一个细致的编码助手。请清晰地解释你的答案。
```
{% endcolumn %}
{% column %}
**已禁用思考**
```
你是一个细致的编码助手。请清晰地解释你的答案。
```
{% endcolumn %}
{% endcolumns %}
**输出行为：**
{% columns %}
{% column %}
启用思考时，模型会在最终答案之前输出其内部推理通道。
```
<|channel>thought
[内部推理]
[最终答案]
```
{% endcolumn %}
{% column %}
当思考被禁用时，更大的模型仍可能输出一个 **空思考块** ，然后再给出最终答案。
```
<|channel>thought
[最终答案]
```
{% endcolumn %}
{% endcolumns %}
**例如使用“**法国的首都是哪里？”：
{% code overflow="wrap" %}
```
<|turn>system\n<|think|>\n<|turn>user\n法国的首都是哪里？\n<|turn>model\n
```
{% endcode %}
**然后它会输出：**
{% code overflow="wrap" %}
```
<|channel>thought\n用户在询问法国的首都。\n法国的首都是巴黎。法国的首都是巴黎。
```
{% endcode %}
**多轮聊天规则：**
对于多轮对话， **只在聊天历史中保留最终可见答案**。不要 **不会** 将之前的思考块重新喂给下一轮。
{% code overflow="wrap" %}
```
<|turn>user\n1+1 等于多少？\n<|turn>model\n2\n<|turn>user\n1+1 等于多少？\n<|turn>model\n2\n<|turn>user\n1+1 等于多少？\n<|turn>model\n2\n<|turn>user\n1+1 等于多少？\n<|turn>model\n2\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，较大模型的推荐起点是 [**Dynamic**](/docs/zh/ji-chu-zhi-shi/dynamic-3.0-ggufs.md) **4 位**. [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) |
| --------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
🦥 Unsloth Desktop 指南 🦙 Llama.cpp 指南 NVFP4 指南
{% columns %}
{% column %}
**你可以在我们的** [**Unsloth Studio**](/docs/zh/xin/studio.md)✨ **notebook：**
{% endcolumn %}
{% column %}
{% embed url="" %}
{% endcolumn %}
{% endcolumns %}
### 🦥 Unsloth 指南
Gemma 4 现在可以在 [Unsloth Desktop](/docs/zh/xin/studio.md)上运行和微调，我们新的本地 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) 参数调优（温度、top-p 等）
* 通过 llama.cpp 实现快速 CPU + GPU 推理
* [训练 LLM](/docs/zh/xin/studio.md#no-code-training) 速度快 2 倍，VRAM 占用减少 70%
{% endcolumn %}
{% column %}
{% 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).
下载 Unsloth
* :apple: [下载 macOS 版](https://unsloth.ai/download/mac)
* :windows: [下载 Windows 版](https://unsloth.ai/download/windows)
* :linux: [下载 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 模型。
{% endstep %}
{% step %}
#### 运行 Gemma 4
使用 Unsloth Studio 时，推理参数应自动设置，不过你仍然可以手动更改。你也可以编辑上下文长度、聊天模板和其他设置。你可以运行 GGUF 和 MLX 文件。
更多信息请查看我们的 [Unsloth Studio 推理指南](/docs/zh/xin/studio/chat.md).
{% 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-zhi-shi/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*" # 对于 Dynamic 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 动态量化
我们还为 MacOS 设备上传了动态 4bit 和 8bit 量化版，作为首次试用！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 指南**
我们上传了 [Dynamic NVFP4](/docs/zh/ji-chu-zhi-shi/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× |
26B A4B - KLD 基准（越低越好）
\* | 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% |
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://unsloth.ai/docs/zh/mo-xing/gemma-4.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
