> 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

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 直接转换到 Q4\_0 时，26B-A4B 仅能获得 70.2% 的 top-1 准确率。 [我们应用了 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="/pages/f7d9352762b9a21f7ce27fda96cda62b115a7574#run-gemma-4-qat-tutorials" class="button primary">运行 Gemma 4 QAT</a><a href="/pages/f7d9352762b9a21f7ce27fda96cda62b115a7574#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="/files/b71679d39afcc685fad7aeedb31ca36ad2bcf97c" 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="/files/b31576c1814fc594951f802312d97b50185aa701" 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 |

### 推荐设置

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 分析

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

<figure><img src="/files/182a8bad178c82d1540d84a9b98b3eda842874e5" 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 缩放，而 QAT BF16 使用 BF16 缩放，并且在 llama.cpp 中这些缩放并没有被最优地确定。

朴素转换与 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，并采用了负缩放因子。

我们为 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="/pages/f7d9352762b9a21f7ce27fda96cda62b115a7574#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-zeng/studio.md)✨ **笔记本：**
{% 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-zeng/studio.md)，我们的全新本地 AI 开源 Web UI 中运行和训练。Unsloth Studio 让你可以在本地运行模型，支持 **MacOS、Windows**、Linux 以及：

{% columns %}
{% column %}

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

{% column %}

<div data-with-frame="true"><figure><img src="/files/650cd087ac9ab1b567e284813a7713806d466601" 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

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

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

{% step %}

#### 运行 Gemma 4 QAT

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

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

<div data-with-frame="true"><figure><img src="/files/650cd087ac9ab1b567e284813a7713806d466601" 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/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*" # 动态 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 dynamically by asking a question.

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

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

The question should be specific, self-contained, and written in natural language.
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.