> 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/ji-chu/unsloth-dynamic-2.0-ggufs.md).

# Unsloth Dynamic 2.0 GGUF

我们很高兴推出 [Unsloth](https://github.com/unslothai/unsloth) Dynamic v2.0 量化——这是对我们先前量化版本的一次重大升级。这种新方法优于主流量化方法，并为以下项目树立了新的基准： [Aider Polyglot](/docs/zh/ji-chu/unsloth-dynamic-2.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md)、5-shot MMLU 和 KL 散度。

这意味着你现在可以运行并微调 [量化 LLM](/docs/zh/mo-xing/tutorials.md) 同时尽可能保留精度！你可以在大多数推理引擎上运行 2.0 GGUF，例如 llama.cpp、 [Unsloth Studio](/docs/zh/xin/studio.md) 等。

{% columns %}
{% column %}
**2026 年 4 月 20 日更新：** 查看我们针对以下模型的新 GGUF 基准测试： [Qwen3.6](/docs/zh/mo-xing/qwen3.6.md#unsloth-gguf-benchmarks) 和 [Gemma 4](/docs/zh/mo-xing/gemma-4.md#unsloth-gguf-benchmarks).

[2026 年 2 月 27 日更新：](/docs/zh/mo-xing/qwen3.5/gguf-benchmarks.md) **Qwen3.5** 已发布，我们修复了一些工具调用聊天模板问题，并对每个 GGUF 在困惑度和 KL 散度上进行了基准测试。 [查看基准测试！](/docs/zh/mo-xing/qwen3.5/gguf-benchmarks.md)

使用 **关键优势** 的 [Unsloth 软件包](https://github.com/unslothai/unsloth) 和量化版本在于，我们积极参与修复主流模型中的错误。我们已直接与以下团队合作： [Qwen3](https://www.reddit.com/r/LocalLLaMA/comments/1kaodxu/qwen3_unsloth_dynamic_ggufs_128k_context_bug_fixes/), [Meta（Llama 4）](https://github.com/ggml-org/llama.cpp/pull/12889), [Mistral（Devstral）](https://app.gitbook.com/o/HpyELzcNe0topgVLGCZY/s/xhOjnexMCB3dmuQFQ2Zq/~/changes/618/basics/tutorials-how-to-fine-tune-and-run-llms/devstral-how-to-run-and-fine-tune), [Google（Gemma 1–3）](https://news.ycombinator.com/item?id=39671146) 和 [Microsoft（Phi-3/4）](https://simonwillison.net/2025/Jan/11/phi-4-bug-fixes)，贡献了可提升准确率的修复。
{% endcolumn %}

{% column %}

<figure><img src="/files/165ac9ca11098b16b371d7ca880c4b6b77335e1f" alt=""><figcaption><p>Gemma 4 26B A4B 基准测试（越低越好）</p></figcaption></figure>

<figure><img src="/files/2a6320fe208e8cb5edf737d5094f9f3a28f26540" alt=""><figcaption><p>Qwen3.6 基准测试（越低越好）</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% hint style="success" %}
Unsloth Dynamic GGUF 现在可以运行于 [Unsloth Studio](/docs/zh/xin/studio.md) ✨

<img src="/files/7b581d8402ea08202545e03519187dd478e0c463" alt="" data-size="original">
{% endhint %}

{% hint style="success" %}
[2025 年 9 月 10 日更新：](/docs/zh/ji-chu/unsloth-dynamic-2.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md) 你们想要更严格的基准测试，所以这里带来了 Aider Polyglot 的结果！我们的 Dynamic 3-bit DeepSeek V3.1 GGUF 得分为 **75.6%**，超过了许多全精度 SOTA LLM。 [阅读更多。](/docs/zh/ji-chu/unsloth-dynamic-2.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md)

<img src="/files/3d75b0063b3aff66275abe8924298c78ad250be6" alt="DeepSeek-V3.2 Thinking Aider Benchmarks" data-size="original"><img src="/files/c7d89f68b1da30c734e8e2f834090909d9b9c510" alt="Llama 4 5-shot MMLU Benchmarks" data-size="original">
{% endhint %}

你还可以查看 Benjamin Marie 针对 LiveCodeBench v6、MMLU Pro 等所进行的真实世界用例基准测试：

<div><figure><img src="/files/fb33d5f655dfe59134b3cc15a5571f8854926e28" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="/files/d10b056c649759de5b958a5a1e40f69826e1883c" alt="" width="450"><figcaption></figcaption></figure></div>

你可以看到，尽管 Unsloth 的 GGUF 体积小了约 8GB，但其表现仍优于非 Unsloth 的量化版本。

下方还有我们基准测试和评估的详细分析。

### 💡 Dynamic v2.0 有哪些新内容？

* **为 GGUF + safetensors 重新设计的层选择：** Unsloth Dynamic 2.0 现在能够以更智能、更广泛的方式对层进行选择性量化。我们不再只修改少数特定层，而是会动态调整每一个可能层的量化类型，而且不同层和不同模型的组合都会有所不同。
* 当前已选择的以及未来所有 GGUF 上传都将使用 Dynamic 2.0 和我们的新校准数据集。该数据集包含超过 >1.5M 个 **token** （取决于模型），由高质量、人工精心筛选并清洗的数据组成——可大幅提升对话聊天性能。
* 此前，我们的 Dynamic 量化（DeepSeek-R1 1.58-bit GGUF）仅对 MoE 架构有效。 <mark style="background-color:green;">**Dynamic 2.0 量化现在适用于所有模型（包括 MoE 和非 MoE）**</mark>.
* **模型特定量化：** 每个模型现在都使用量身定制的量化方案。例如，Gemma 3 中被量化的层与 Llama 4 中的层有显著差异。
* 为了最大化效率，尤其是在 Apple Silicon 和 ARM 设备上，我们现在还加入了 Q4\_NL、Q5.1、Q5.0、Q4.1 和 Q4.0 格式。

为了确保基准测试准确，我们构建了一个内部评估框架，以匹配 Llama 4 和 Gemma 3 官方报告的 5-shot MMLU 分数。这使我们能够在全精度与 Dynamic v2.0、 **QAT** 以及标准 **imatrix** GGUF 量化版本之间进行公平对比。

<div><figure><img src="/files/4f16853f8441efac8ebedba0cdac2a3f4a1ba3f0" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="/files/ab0958124534e5cdf4b3b987d110cc3b7f19a5d6" alt="" width="563"><figcaption></figcaption></figure></div>

未来所有 GGUF 上传都将使用 Unsloth Dynamic 2.0，而我们的 Dynamic 4-bit safetensor 量化版本未来也将从中受益。

## 📊 为什么是 KL 散度？

[准确率并不是你所需要的一切](https://arxiv.org/pdf/2407.09141) 展示了即便剪枝的层是被认为不必要的层，在“翻转”方面仍会带来巨大的差异。“翻转”被定义为答案从错误变为正确，或从正确变为错误。论文表明，当我们剪枝层或进行量化时，MMLU 可能不会下降，但那是因为一些错误答案可能“翻转”为正确答案。我们的目标是匹配原始模型，因此衡量“翻转”是一个很好的指标。

<div><figure><img src="/files/8bcad05aa989233fa890b29a4877ced0fa538f2b" alt=""><figcaption></figcaption></figure> <figure><img src="/files/97144e7d458db5dee88daffa3fd1d6060ae57bfc" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
**KL 散度** 应该是 **报告量化误差的黄金标准之一** 正如研究论文《Accuracy is Not All You Need》中所述。 **使用困惑度是不正确的** 因为输出 token 的数值可能会相互抵消，所以我们必须使用 KLD 或更严格的基准测试，例如 [Aider](/docs/zh/ji-chu/unsloth-dynamic-2.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md).
{% endhint %}

论文还表明，有趣的是，KL 散度与翻转高度相关，因此我们的目标是在尽可能少增加量化磁盘空间的同时，降低平均 KL 散度。

## ⚖️ 校准数据集过拟合

大多数框架使用维基百科文章测试集来报告困惑度和 KL 散度。然而，我们注意到，如果使用同样与维基百科相关的校准数据集，会导致量化版本过拟合，并获得更低的困惑度分数。我们使用 [Calibration\_v3](https://gist.github.com/bartowski1182/eb213dccb3571f863da82e99418f81e8) 和 [Calibration\_v5](https://gist.github.com/tristandruyen/9e207a95c7d75ddf37525d353e00659c/) 数据集进行公平测试，其中除其他数据外还包含一些 wikitext 数据。 <mark style="background-color:red;">**另外，指令模型具有独特的聊天模板，仅使用纯文本校准数据集对指令模型并不有效**</mark> （基础模型则可以）。事实上，大多数 imatrix GGUF 通常都带有这些校准问题。因此，它们在同样使用维基百科数据的 KL 散度基准测试中自然表现更好，因为模型本质上已针对该领域进行了优化。

为了确保评估公平且可控，我们在进行 KL 散度基准测试时不会使用我们自己的校准数据集（该数据集针对聊天性能进行了优化）。相反，我们使用相同的标准维基百科数据集进行了测试，从而能够将我们的 Dynamic 2.0 方法与基线 imatrix 方法直接比较性能。

## :1234: MMLU 复现历险记

* 复现 MMLU 5 shot 简直是一场噩梦。我们 <mark style="background-color:red;">**无法**</mark> 由于 <mark style="background-color:yellow;">**细微的实现问题**</mark>，我们无法复现许多模型的 MMLU 结果，包括 Llama 3.1（8B）Instruct、Gemma 3（12B）等。例如，Llama 3.1（8B）理论上应达到约 68.2%，而使用错误实现则可能只有 <mark style="background-color:red;">**35% 的准确率。**</mark>

<figure><img src="/files/9e1931d0d03cc2c84084abf10f65f629518d3e6b" alt="" width="375"><figcaption><p>MMLU 实现问题</p></figcaption></figure>

* 使用朴素的 MMLU 实现时，Llama 3.1（8B）Instruct 的 MMLU 5 shot 准确率为 67.8%。但我们发现 Llama **会将“A”和“\_A”（前面带空格的 A）分词为不同的 token id**。如果我们同时考虑带空格和不带空格的 token，结果就会达到 68.2% <mark style="background-color:green;">(+0.4%)</mark>
* 有趣的是，Llama 3 依据 Eleuther AI 的 [LLM Harness](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/tasks/llama3/instruct/mmlu/_continuation_template_yaml) 还会附加 <mark style="background-color:purple;">**“The best answer is”**</mark> 到问题后面，遵循了 Llama 3 原始的 MMLU 基准测试方式。
* 还有许多其他细微问题，因此为了在受控环境中对所有内容进行基准测试，我们通过直接研究 [github.com/hendrycks/test](https://github.com/hendrycks/test) 从零开始设计了自己的 MMLU 实现，并在多个模型上验证了结果并与报告数字进行了比较。

## :sparkles: Gemma 3 QAT 复现与基准测试

Gemma 团队发布了 Gemma 3 的两个 QAT（量化感知训练）版本：

1. Q4\_0 GGUF —— 通过公式将所有层量化为 Q4\_0 `w = q * block_scale` ，每个块有 32 个权重。更多细节请参见 [llama.cpp wiki ](https://github.com/ggml-org/llama.cpp/wiki/Tensor-Encoding-Schemes)。
2. int4 版本——推测是 [TorchAO int4 风格](https://github.com/pytorch/ao/blob/main/torchao/quantization/README.md)?

我们对所有 Q4\_0 GGUF 版本进行了基准测试，并在 12B 模型上进行了大量实验。我们看到 **12B Q4\_0 QAT 模型达到 67.07%** ，而全精度 bfloat16 12B 版本在 5 shot MMLU 上达到 67.15%。这非常令人印象深刻！27B 模型也已经非常接近了！

<table><thead><tr><th>指标</th><th>1B</th><th valign="middle">4B</th><th>12B</th><th>27B</th></tr></thead><tbody><tr><td>MMLU 5 shot</td><td>26.12%</td><td valign="middle">55.13%</td><td><mark style="background-color:blue;"><strong>67.07%（67.15% BF16）</strong></mark></td><td><strong>70.64%（71.5% BF16）</strong></td></tr><tr><td>磁盘空间</td><td>0.93GB</td><td valign="middle">2.94GB</td><td><strong>7.52GB</strong></td><td>16.05GB</td></tr><tr><td><mark style="background-color:green;"><strong>效率*</strong></mark></td><td>1.20</td><td valign="middle">10.26</td><td><strong>5.59</strong></td><td>2.84</td></tr></tbody></table>

我们设计了一个新的 **效率指标** 用于计算模型的实用性，同时也将其磁盘大小和 MMLU 5 shot 分数考虑在内：

$$
\text{Efficiency} = \frac{\text{MMLU 5 shot score} - 25}{\text{Disk Space GB}}
$$

{% hint style="warning" %}
我们必须 **减去 25** 因为 MMLU 有 4 个选项——A、B、C 或 D。假设我们做一个只会随机选答案的模型——它会得到 25% 准确率，而且磁盘空间只需几个字节。但显然这不是一个有用的模型。
{% endhint %}

关于相对于基础模型的 KL 散度，下面的表格展示了改进情况。提醒一下，KL 散度越接近 0 越好（也就是说 0 表示与全精度模型完全相同）

| 量化        | 基线 KLD   | GB    | 新的 KLD   | GB    |
| --------- | -------- | ----- | -------- | ----- |
| IQ1\_S    | 1.035688 | 5.83  | 0.972932 | 6.06  |
| IQ1\_M    | 0.832252 | 6.33  | 0.800049 | 6.51  |
| IQ2\_XXS  | 0.535764 | 7.16  | 0.521039 | 7.31  |
| IQ2\_M    | 0.26554  | 8.84  | 0.258192 | 8.96  |
| Q2\_K\_XL | 0.229671 | 9.78  | 0.220937 | 9.95  |
| Q3\_K\_XL | 0.087845 | 12.51 | 0.080617 | 12.76 |
| Q4\_K\_XL | 0.024916 | 15.41 | 0.023701 | 15.64 |

如果我们绘制磁盘空间增加比例与 KL 散度变化比例的关系图，就能更清楚地看出收益！我们的动态 2bit Q2\_K\_XL 显著降低了 KLD（约 7.5%）。

<figure><img src="/files/b745313d14ad367cc1b264b0d69b9529fda935a1" alt=""><figcaption></figcaption></figure>

Gemma 3（27B）的 MMLU 结果截断表。见下方。

1. **我们的动态 4bit 版本小了 2GB，同时相比 QAT 版本还额外提升了 +1% 准确率！**
2. 从效率角度看，2bit Q2\_K\_XL 等版本似乎表现非常好！

| 量化             | Unsloth   | Unsloth + QAT | 磁盘大小      | 效率       |
| -------------- | --------- | ------------- | --------- | -------- |
| IQ1\_M         | 48.10     | 47.23         | 6.51      | 3.42     |
| IQ2\_XXS       | 59.20     | 56.57         | 7.31      | 4.32     |
| IQ2\_M         | 66.47     | 64.47         | 8.96      | 4.40     |
| Q2\_K\_XL      | 68.70     | 67.77         | 9.95      | 4.30     |
| Q3\_K\_XL      | 70.87     | 69.50         | 12.76     | 3.49     |
| **Q4\_K\_XL**  | **71.47** | **71.07**     | **15.64** | **2.94** |
| **Google QAT** |           | **70.64**     | **17.2**  | **2.65** |

<details>

<summary><mark style="color:绿色;">点击这里</mark> 查看 Google 完整的 Gemma 3（27B）QAT 基准测试：</summary>

| 模型             | Unsloth   | Unsloth + QAT | 磁盘大小      | 效率       |
| -------------- | --------- | ------------- | --------- | -------- |
| IQ1\_S         | 41.87     | 43.37         | 6.06      | 3.03     |
| IQ1\_M         | 48.10     | 47.23         | 6.51      | 3.42     |
| IQ2\_XXS       | 59.20     | 56.57         | 7.31      | 4.32     |
| IQ2\_M         | 66.47     | 64.47         | 8.96      | 4.40     |
| Q2\_K          | 68.50     | 67.60         | 9.78      | 4.35     |
| Q2\_K\_XL      | 68.70     | 67.77         | 9.95      | 4.30     |
| IQ3\_XXS       | 68.27     | 67.07         | 10.07     | 4.18     |
| Q3\_K\_M       | 70.70     | 69.77         | 12.51     | 3.58     |
| Q3\_K\_XL      | 70.87     | 69.50         | 12.76     | 3.49     |
| Q4\_K\_M       | 71.23     | 71.00         | 15.41     | 2.98     |
| **Q4\_K\_XL**  | **71.47** | **71.07**     | **15.64** | **2.94** |
| Q5\_K\_M       | 71.77     | 71.23         | 17.95     | 2.58     |
| Q6\_K          | 71.87     | 71.60         | 20.64     | 2.26     |
| Q8\_0          | 71.60     | 71.53         | 26.74     | 1.74     |
| **Google QAT** |           | **70.64**     | **17.2**  | **2.65** |

</details>

## :llama: Llama 4 错误修复 + 运行

我们还帮助修复了一些 Llama 4 的问题：

* Llama 4 Scout 在其官方仓库中更改了 RoPE Scaling 配置。我们帮助解决了 llama.cpp 中的问题，以支持这一 [这里的更改](https://github.com/ggml-org/llama.cpp/pull/12889)

  <figure><img src="/files/01f18ab7bb927009325addd0c06a745f8f73496a" alt=""><figcaption></figcaption></figure>
* Llama 4 的 QK Norm 中，Scout 和 Maverick 的 epsilon 都应来自配置文件——这意味着应使用 1e-05 而不是 1e-06。我们帮助在以下项目中解决了这些问题： [llama.cpp](https://github.com/ggml-org/llama.cpp/pull/12889) 和 [transformers](https://github.com/huggingface/transformers/pull/37418)
* Llama 4 团队和 vLLM 还独立修复了一个 QK Norm 在所有头之间共享的问题（本不该如此） [这里](https://github.com/vllm-project/vllm/pull/16311)。MMLU Pro 准确率从 68.58% 提升到 71.53%。
* [Wolfram Ravenwolf](https://x.com/WolframRvnwlf/status/1909735579564331016) 展示了我们的 GGUF 通过 llama.cpp 能达到远高于第三方推理提供商的准确率——这很可能是上述问题叠加所致，也可能与量化问题有关。

  <figure><img src="/files/4c2c135b39d1c3b25c012c91ab151bedf090bd4c" alt=""><figcaption></figcaption></figure>

如我们的图表所示，我们的 4-bit Dynamic QAT 量化在 5-shot MMLU 上带来了更好的性能，同时体积也更小。

### 运行 Llama 4 Scout：

例如，要运行 Llama 4 Scout，首先克隆 llama.cpp：

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

然后下载我们为 Scout 提供的全新 Dynamic v2.0 量化版本：

```python
# !pip install huggingface_hub hf_transfer
import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id = "unsloth/Llama-4-Scout-17B-16E-Instruct-GGUF",
    local_dir = "unsloth/Llama-4-Scout-17B-16E-Instruct-GGUF",
    allow_patterns = ["*IQ2_XXS*"],
)
```

然后让我们开始推理！

{% code overflow="wrap" %}

```bash
./llama.cpp/llama-cli \\
    --model unsloth/Llama-4-Scout-17B-16E-Instruct-GGUF/Llama-4-Scout-17B-16E-Instruct-UD-IQ2_XXS.gguf \\
    --threads 32 \\
    --ctx-size 16384 \\
    --n-gpu-layers 99 \\
    -ot ".ffn_.*_exps.=CPU" \\
    --seed 3407 \\
    --prio 3 \\
    --temp 0.6 \\
    --min-p 0.01 \\
    --top-p 0.9 \\
    -no-cnv \\
    --prompt "<|header_start|>user<|header_end|>\n\n创建一个 Flappy Bird 游戏。<|eot|><|header_start|>assistant<|header_end|>\n\n"
```

{% endcode %}

{% hint style="success" %}
在这里阅读更多有关运行 Llama 4 的内容： <https://docs.unsloth.ai/basics/tutorial-how-to-run-and-fine-tune-llama-4>
{% endhint %}


---

# 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/ji-chu/unsloth-dynamic-2.0-ggufs.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.