> 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/qat.md).

# Gemma 4 QAT

在本地运行 Google Gemma 4 QAT 模型，包括 E2B、E4B、12B、26B-A4B 和 31B。

Gemma 4 QAT（量化感知训练）是 Google DeepMind 的新 [Gemma 4](/docs/zh/mo-xing/gemma-4.md) 旨在 **在保持模型质量的同时降低内存需求**。这使得可以运行更大的模型，例如 **Gemma 4 26B-A4B**，只需在消费级 GPU 上本地运行，最低只需 **16GB RAM**.

Gemma 4 QAT 在训练时就考虑了量化，使 4 位格式具有约**72% 更低的内存占用** 替换为 **接近原始性能**。还提供了 E2B 和 E4B 的 2 个特殊移动量化版本，采用混合量化宽度。

转换为 `Q4_0` 从 QAT 直接转换后，26B-A4B 的 top-1 准确率只有 70.2%。 [我们应用了 Unsloth Dynamic 方法](#qat-analysis) 将其提升到 **85.6%（+15.6%），同时还** [**小了 200MB**](#usage-guide)!

Gemma 4 QAT 包括： **E2B**, **E4B**, **12B, 26B-A4B**，以及 **31B。** 它们是多模态、混合推理模型，支持 140+ 种语言，并可支持最高 **256K 上下文。**

{% columns %}
{% column %} <a href="/docs/zh/mo-xing/gemma-4/qat.md#run-gemma-4-qat-tutorials" class="button primary">运行 Gemma 4 QAT</a><a href="/docs/zh/mo-xing/gemma-4/qat.md#qat-analysis" class="button secondary">QAT 分析</a>

**Gemma-4-E2B** QAT 可在 3GB RAM 上运行， **E4B** 在 5GB &#x4E0A;**，12B** 在 7GB &#x4E0A;**，26-A4B** 在 15GB 上，以及 **31B** 在 18GB &#x4E0A;**.**

我们将 Gemma 4 QAT GGUF 命名为 `UD-Q4_K_XL` 因为我们发现 q4\_0 尽管更大，但会降低准确率。请参见我们的 [Gemma 4 QAT GGUF](https://huggingface.co/collections/unsloth/gemma-4-qat).

为了比较 `int4` 量化，请参见下面原始版本与 QAT 的大小差异。QAT 使用约 72% 更少的内存，同时保留了几乎全部原始准确率：
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FGLHNSIo3qe4ByThVZDzm%2Fgemma%204%20qat.png?alt=media&amp;token=ae72b8e1-def7-447c-bafc-67514354df7d" alt="" width="563"><figcaption><p>Gemma 4 Mobile QAT 工作方式的可视化。</p></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

| Gemma 4     | QAT（int4）GGUF | 原始 BF16 |  百分比变化 |
| ----------- | ------------: | ------: | -----: |
| **E2B**     |       2.62 GB | 9.31 GB | 71.86% |
| **E4B**     |       4.22 GB | 15.1 GB | 72.05% |
| **12B**     |       6.72 GB | 23.8 GB | 71.76% |
| **26B A4B** |       14.2 GB | 50.5 GB | 71.88% |
| **31B**     |       17.3 GB | 61.4 GB | 71.82% |

### 使用指南

面向 E2B 和 E4B 的 Gemma 4 QAT 变体专为手机和笔记本设计，而更大的 26B-A4B 和 31B QAT 模型现在可以在笔记本上运行，而不再只限于高性能家用 GPU。

有 **仅有一个 GGUF 文件** 适用于每个 Gemma 4 模型，因为我们发现高于上传的 `UD-Q4_K_XL` 版本的精度会降低准确率而不是提升它。请使用原始的非 QAT Q4\_0 量化版本 [这里](https://huggingface.co/collections/unsloth/gemma-4).

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FrTygbMBlZcUER9GUMzKg%2Fimage.png?alt=media&amp;token=85c3c44b-0f42-477a-9ce2-30b085e21b5c" alt="" width="563"><figcaption></figcaption></figure>

### 硬件要求

**表：Gemma 4 QAT 推理 GGUF 推荐硬件要求** （单位 = 总内存：RAM + VRAM，或统一内存）。

| Gemma 4 QAT     |    要求 |
| --------------- | ----: |
| **E2B** QAT     |  3 GB |
| **E4B** QAT     |  5 GB |
| **12B** QAT     |  7 GB |
| **26B A4B** QAT | 15 GB |
| **31B** QAT     | 18 GB |

{% hint style="info" %}
该表假设上下文约为 8K token。llama.cpp 对 26B A4B 的默认 256K 上下文会额外增加约 5 GB 的 KV 缓存。在内存受限的纯 CPU 机器上，请使用 `-c 8192` 或 `-c 16384`; `--fit` 目前会忽略 CPU 重打包权重。
{% endhint %}

### 推荐设置

QAT 检查点使用相同的推荐 Gemma 4 设置：

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

{% hint style="info" %}
Gemma 4 的最大上下文为 **128K** 用于 **E2B**, **E4B** 和 **256K** 用于 **12B**, **26B A4B**, **31B**.
{% endhint %}

## QAT 分析

我们发现，在 llama.cpp 中天真地将 QAT Q4\_0 检查点转换为 Q4\_0 实际上会降低准确率，而且并未真正与 Q4\_0 的 BF16 QAT 格式对齐。我们应用了 Unsloth dynamic 方法，强制让 llama.cpp 兼容的 Q4\_0 格式与真实的 BF16 QAT Q4\_0 格式更好地一致，从而既让量化文件更小（嵌入不需要 Q6\_K），也更准确！

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FcBHRs9twWiAnjgtm4EKf%2Fimage.png?alt=media&amp;token=023d7771-dba1-4a1e-a8c4-da6ac98921f7" alt=""><figcaption></figcaption></figure>

下面是 KLD、Top 1% 准确率和磁盘空间的表格。你可以看到我们的版本在 99.9% KLD 和平均 KLD 上都有显著提升。 **例如，E2B 的平均 KLD 为 0.00173，而朴素 Q4\_0 量化为 0.05109（相对好 29 倍），而我们的版本还小了 22%！**

主要问题是从 QAT BF16 转换到 llama.cpp 的 Q4\_0 格式并不是无损的。llama.cpp 使用 F16 scale，而 QAT BF16 使用 BF16 scale，而且在 llama.cpp 体系里这些 scale 的确定并不最优。

朴素转换与 BF16 QAT 的字节完全一致率只有 24.77%，而我们发现通过一些技巧可以把它提升到 99.96%！

<table><thead><tr><th width="100">模型</th><th>方法</th><th>磁盘（GB）</th><th>99.9% KLD</th><th>平均 KLD</th><th width="77.5999755859375">Top-1 %</th></tr></thead><tbody><tr><td>E2B</td><td>Unsloth</td><td><strong>2.62</strong></td><td>0.0557</td><td>0.00173</td><td><strong>98.16</strong></td></tr><tr><td>E2B</td><td>Q4_0</td><td>3.35</td><td>1.0513</td><td>0.05109</td><td>89.29</td></tr><tr><td>E4B</td><td>Unsloth</td><td><strong>4.22</strong></td><td>0.0536</td><td>0.00121</td><td><strong>98.54</strong></td></tr><tr><td>E4B</td><td>Q4_0</td><td>5.15</td><td>0.6722</td><td>0.03778</td><td>90.94</td></tr><tr><td>26B</td><td>Unsloth</td><td><strong>14.25</strong></td><td>2.7087</td><td>0.09788</td><td><strong>85.63</strong></td></tr><tr><td>26B</td><td>Q4_0</td><td>14.44</td><td>4.5420</td><td>0.36094</td><td>70.20</td></tr><tr><td>31B</td><td>Unsloth</td><td><strong>17.29</strong></td><td>1.3659</td><td>0.01403</td><td><strong>96.67</strong></td></tr><tr><td>31B</td><td>Q4_0</td><td>17.65</td><td>3.0030</td><td>0.09349</td><td>87.91</td></tr><tr><td>12B</td><td>Unsloth</td><td><strong>6.72</strong></td><td>9.2740</td><td>0.13288</td><td><strong>88.76</strong></td></tr><tr><td>12B</td><td>Q4_0</td><td>6.98</td><td>14.7323</td><td>0.50702</td><td>74.08</td></tr></tbody></table>

## 移动混合 QAT

Gemma-4 团队还发布了 Gemma-4-E2B-it 和 Gemma-4-E4B-it 的特殊移动混合 QAT 版本。我们也忠实地将它们转换为 llama.cpp 兼容格式，并恢复了几乎全部准确率。我们对 2 位层使用了 TQ2\_0，并采用了负 scale。

我们为 E2B 和 E4B 都制作了 UD-Q2\_K\_XL 量化版本。

|                  | E2B 移动版     | E4B 移动版 |
| ---------------- | ----------- | ------- |
| 大小               | 2.19 GB     | 3.22 GB |
| 2 位（TQ2\_0）张量    | 61（含深层 MLP） | 2（仅嵌入）  |
| 相对于 BF16 的平均 KLD | 0.00409     | 0.00102 |
| Top-1 %          | 97.82%      | 98.76%  |
| 基础 PPL           | \~103       | 42.4    |

请看 [gemma-4-E2B-it-qat-GGUF](https://huggingface.co/unsloth/gemma-4-E2B-it-qat-GGUF) 和 [gemma-4-E4B-it-qat-GGUF](https://huggingface.co/unsloth/gemma-4-E4B-it-qat-GGUF) 用于 `UD-Q2_K_XL`.

## 运行 Gemma 4 QAT 教程

由于 Gemma 4 GGUF 有多种大小，小模型的推荐起点是 8 位，而大模型则是 **动态 4 位**. [Gemma 4 GGUF](https://huggingface.co/collections/unsloth/gemma-4-qat):

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

<a href="/docs/zh/mo-xing/gemma-4/qat.md#unsloth-studio-guide" class="button primary">🦥 Unsloth Studio 指南</a><a href="/pages/f7d9352762b9a21f7ce27fda96cda62b115a7574#llama.cpp-guide" class="button primary">🦙 Llama.cpp 指南</a>

{% columns %}
{% column %}
**你可以在我们的** [**Unsloth Studio**](/docs/zh/xin/studio.md)✨ **笔记本中通过 UI 免费运行和训练 Gemma 4 QAT：**
{% endcolumn %}

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

### 🦥 Unsloth Studio 指南

Gemma 4 QAT 现在可以在 [Unsloth Studio](/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 %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FVrLgXwplAMcvkU4owjPk%2F26b%20gif.gif?alt=media&amp;token=8a569952-c152-435f-b815-c9f295619587" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% stepper %}
{% step %}

#### 安装 Unsloth

在你的终端中运行：

**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）在浏览器中打开。
{% endstep %}

{% step %}

#### 搜索并下载 Gemma 4 QAT

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

然后前往 [Unsloth Chat](/docs/zh/xin/studio/chat.md) 选项卡，在搜索栏中搜索 Gemma 4，并下载你想要的模型和量化版本。
{% endstep %}

{% step %}

#### 运行 Gemma 4 QAT

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

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

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FVrLgXwplAMcvkU4owjPk%2F26b%20gif.gif?alt=media&amp;token=8a569952-c152-435f-b815-c9f295619587" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

### 🦙 Llama.cpp 指南

在本指南中无需选择量化类型，因为只有一种： `UD-Q4_K_XL`。请参见： [Gemma 4 QAT 集合](https://huggingface.co/collections/unsloth/gemma-4-qat)。在这些教程中，我们将使用 [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` 保存到特定位置。

**26B-A4B：**

```bash
export LLAMA_CACHE="unsloth/gemma-4-26B-A4B-it-qat-GGUF"
./llama.cpp/llama-cli \\
    -hf unsloth/gemma-4-26B-A4B-it-qat-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-qat-GGUF"
./llama.cpp/llama-cli \\
    -hf unsloth/gemma-4-31B-it-qat-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-qat-GGUF"
./llama.cpp/llama-cli \\
    -hf unsloth/gemma-4-E4B-it-qat-GGUF:UD-Q4_K_XL \\
    --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-qat-GGUF:UD-Q4_K_XL \\
    --temp 1.0 \\
    --top-p 0.95 \\
    --top-k 64
```

{% endstep %}

{% step %}
通过以下方式下载模型（在安装 `pip install huggingface_hub hf_transfer` 之后）。你可以选择 `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-qat-GGUF \\
    --local-dir unsloth/gemma-4-26B-A4B-it-qat-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-qat-GGUF/gemma-4-26B-A4B-it-qat-UD-Q4_K_XL.gguf \\
    --mmproj unsloth/gemma-4-26B-A4B-it-qat-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-qat-GGUF/gemma-4-26B-A4B-it-qat-UD-Q4_K_XL.gguf \\
    --mmproj unsloth/gemma-4-26B-A4B-it-qat-GGUF/mmproj-BF16.gguf \\
    --temp 1.0 \\
    --top-p 0.95 \\
    --top-k 64 \\
    --alias "unsloth/gemma-4-26B-A4B-it-qat-GGUF" \\
    --port 8001 \\
    --chat-template-kwargs '{"enable_thinking":true}'
```

{% 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 %}
{% endstep %}
{% endstepper %}


---

# 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/qat.md?ask=<question>&goal=<user_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.