> 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-zhi-shi/dynamic-3.0-ggufs.md).

# Unsloth Dynamic 3.0 GGUF

**Unsloth Dynamic V3.1** （2026 年 11 月）是我们面向 Qwen3.8-27B、DeepSeek-V4.1-Flash-1017 和 Qwen3.8-Flash-Next 的最新量化算法，可带来 **准确率提升 10–15%** 并且 **Token 用量减少 50%** 与同等大小的其他量化版本相比。我们正在开发更出色的 Dynamic 量化版本，未来将应用于 Qwen4 及所有后续模型。

Unsloth [Qwen3.8-27B](https://unsloth.ai/docs/zh/mo-xing/qwen3.8.md) Dynamic V3.1 将所有量化版本的帕累托前沿进一步推高，超越了我们之前的 UD3 量化版本、Exllama-3 和 GSQ-RCO。

[Qwen3.8-Flash-Next](https://unsloth.ai/docs/zh/mo-xing/qwen3.8-next.md) 1-bit 量化版本在 DeepSWE v1.1 上达到 54.0%，在 Terminal Bench 2.1 上达到 68.3%。

[DeepSeek-V4.1-Flash-1017](https://unsloth.ai/docs/zh/mo-xing/deepseek-v4.1-flash.md) Dynamic V3.1 IQ1\_S 在 DeepSWE v1.1 上达到 65.8%，在 Terminal Bench 2.1 上达到 69.5%，在 Automation Bench v1.0.6 上达到 51.5%。

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FRHyZ5X7qYZAdCQsgKT7R%2Ffour(1).png?alt=media&amp;token=3c563d60-5767-437a-a704-98fffecb04f8" alt=""><figcaption><p>Qwen3.8-27B 基准测试</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FXC2NHQCS4KKsMoY4IjpT%2Fimage.png?alt=media&amp;token=67fb9d55-8fbb-4f35-a13f-83465cee8475" alt=""><figcaption><p>DeepSeek-V4.1-Flash-1017 基准测试</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FqdXHweLFGzUhUcqj7jZX%2Ffinal%20key%204.png?alt=media&amp;token=8e3249b1-e26c-4a04-82ba-7cfdef952fe6" alt=""><figcaption><p>Qwen3.8-Flash-Next 基准测试</p></figcaption></figure></div>

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FWTSMbLLxexSW1HiwU411%2Fqwen%20speed%20token%20con.png?alt=media&amp;token=fea0700d-24e7-4046-a915-4c087e0230aa" alt=""><figcaption><p>Qwen3.8-Flash-Next GGUF Token 消耗与速度基准测试</p></figcaption></figure>

### Dynamic v3.0

以下是早期 Dynamic v3.0 版本的发布说明和基准测试。

我们现已发布 [**Qwen3.8-27B**](https://unsloth.ai/docs/zh/mo-xing/qwen3.8.md) Dynamic v3.0 量化版本，其 **在相同大小下，Top-1 准确率提升超过 10%** 相比于 **所有其他提供方**。这是我们首次公开的 **早期预览** 版 Dynamic v3.0 的更新版本。新版 3.0 GGUF 可用于大多数推理引擎，包括 **llama.cpp** 和 [**Unsloth Desktop**](https://unsloth.ai/docs/zh/desktop.md).

{% columns %}
{% column width="41.66666666666667%" %}
Dynamic v3.0 在保持相同大小的同时，整体上能更好地保留模型质量，并在 **Divergence-300** @32 和 **KL Divergence**.

也非常感谢大家的支持！仅 5 天内，Unsloth Qwen3.8 的下载量就超过了 510 万次！
{% endcolumn %}

{% column width="58.33333333333333%" %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fl9piThTmmUsePst5w3F2%2Fimage.png?alt=media&amp;token=821e88e2-ad4e-40bf-adf2-e13837228e82" alt=""><figcaption><p>请参阅下文，了解更多图表、基准测试和分析</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

我们的新方法结合了许多新功能和改进。现在，我们使用来自多种来源、质量更高的 imatrix 校准数据集。该数据集针对 **智能体编程和聊天**以及多语言表现进行了优化。我们还改进了 **层选择** 并引入了更多量化技术，以尽可能保留模型质量。

我们 **不会使用 imatrix 校准数据集进行训练**，并且绝不会使用 **QAT** 或 **QAD**。所有操作均通过 **训练后量化**。我们使用的 imatrix 文件已开放给社区进行测试、评估和使用。我们鼓励研究人员和开发者使用我们的 Unsloth quants/imatrix 创建 Qwen3.8 的变体和微调版本。你也可以阅读我们的 [过拟合分析](#not-overfitting) 了解详情。

* 我们还从以下规格的小型量化版本中移除了 MTP 模块： `UD-Q2_K_XL` （8.37GB 及以下），以节省约 500MB 的磁盘空间——如有需要，你可以使用 `Q4_0` 独立 MTP 模块。
* 我们还制作了一些更小的 UD-1bit 量化版本，其中 `UD-IQ1_S` 大小为 6.2GB（不含 MTP），保留了约 72% 的 top-1 准确率，同时体积缩小了 89%。
* `UD-Q2_K_XL` 的 top-1 准确率比次优方案高约 8%，大小为 9.83GB，并成功生成了一个可用的 HTML 程序，仅有 1 个小型 JS 错误——此前该程序会崩溃。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FHkiEb4BgU9IZ4t0pbMKs%2FUD-Q2_K_XL-Qwen.gif?alt=media&amp;token=6b4cd6d5-0b70-4741-a72e-1f5e1974dbb0" alt="" width="360"><figcaption><p>由 2-bit Qwen3.8-27B GGUF 生成</p></figcaption></figure>

### 🔀 Divergence-300 @32

我们通常会报告 top-1 准确率，例如在谈到 Kimi-K3 时会说“动态 1-bit 的 **\~78.9%** top-1 准确率达到 **体积缩小 62%**。”不过，top-1 是对单次预测取 argmax，因此并不能有效衡量实际推理表现。

我们从 Terminal-Bench 2.1、DeepSWE、Harbor、MathArena 2025-26 以及非拉丁文字/长文档提示中，创建了一个包含 300 个留出样例的数据集（未包含在校准数据集中），并针对 BF16、所有量化版本及各提供方进行了 32 个 token 的贪心 argmax 解码。更多过拟合详情请参阅 [过拟合分析](#not-overfitting) 。

这使我们能够评估是否存在过拟合，以及量化输出在多个 token 上是否与 BF16 的生成轨迹相似。与 top-1 准确率相比，这是更好的指标，因为我们将 KLD top-1 的衡量扩展到了 32 个 token。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FySCIjoinQuhNqfGz3C4Q%2Fimage.png?alt=media&amp;token=dcc5a2be-3445-4a67-b1e2-0ca5e89fbcf6" alt=""><figcaption></figcaption></figure>

### :question:1-bit 不应用于智能体场景

如 [#divergence-300-32](#divergence-300-32 "mention")所示，对于 32 个 token 的预测，准确率从 UD-Q2\_K\_XL 到 UD-IQ2\_S 急剧下降：从约 25% 降至不足 8–10%。这种骤降意味着工具调用和非思考模式会失效。使用 1-bit 量化时可能遇到的问题及缓解方法如下：

1. **过度循环**\
   使用低于 UD-Q2\_K\_XL 的量化版本时，你会发现大量循环；所有情况下都应使用 `presence_penalty = 1.5` （或更高）。
2. **空响应**\
   使用 1-bit 量化版本时，务必至少启用低推理强度的思考模式——非推理模式甚至会导致模型不输出内容。
3. **智能体场景和工具调用**\
   不要将该模型用于工具调用——量化程度较高时，模型 **仅能保留通用知识** ，并且可能无法调用工具、反复调用工具，或完全不调用工具。
4. **通用知识表现良好**\
   Top-1 恢复率达到 77%，并不能取代 Divergence-300 @32 的 8%；后者更能反映实际推理工作负载。你可以用该模型回答非常简短的通用知识事实类问题，但最好使用 UD-Q2\_K\_XL。

### 🔀 KL 散度基准测试

我们也对所有提供方进行了 KLD 基准测试，并报告 Top-1 和 KLD 均值。在所有级别，尤其是较小的量化尺寸下，Unsloth UD-3 量化版本在相同磁盘占用下的 top-1 准确率最高可提升 10%！

为确保比较公平，所有图表在计算磁盘占用时，都会从横轴对应的量化版本中移除 MTP 头。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F4ipZ74oiCRRLbB2FJa4J%2Fimage.png?alt=media&amp;token=09f263b9-4cd9-45dc-bd31-8c7ecff2ca41" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FA6YPmwKLaJ7IZ4U4bQE3%2Fimage.png?alt=media&amp;token=e003bf7b-5c78-4eb4-bbae-5358410ef3fa" alt=""><figcaption></figcaption></figure>

### :dove:未过拟合

与我们较早的 UD-2 在未见过的 Wikitext 和 Code 数据上进行比较时，我们的 KLD 表现有了显著提升；较大的量化版本则提升不大，因此我们仍将旧版 UD-2 用于较大的量化版本，并计划继续试验和改进！

我们还通过使用完全不同的数据集进行校准，并尽可能消除所有数据泄漏，来控制过拟合。我们在这些未见过的数据集上测试 KLD，而且不进行 QAD/QAT，只采用纯 PTQ，因此与其他 QAD/QAT 方法相比，过拟合问题较轻。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FP6ro1GH2PqtO63Zdvale%2Fimage.png?alt=media&amp;token=109ca035-6fe1-4154-a33e-20d609f2bf57" alt=""><figcaption></figcaption></figure>

同样， [#divergence-300-32](#divergence-300-32 "mention") 使用来自 DeepSWE、Terminal Bench 等数据集的 300 条提示作为未见数据集，可作为另一组用于评估过拟合的数据，并表明我们的新 UD-3 方法不会过拟合。

***

## Dynamic v2.0（旧版）

我们推出了 [Unsloth](https://github.com/unslothai/unsloth) Dynamic v2.0 量化技术，这是对我们此前量化版本的一次重大升级。这种新方法优于领先的量化方法，并为以下方面树立了新的基准 [Aider Polyglot](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/dynamic-3.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md)、5-shot MMLU 和 KL 散度。

这意味着您现在可以运行并微调 [量化 LLM](https://unsloth.ai/docs/zh/mo-xing/tutorials.md) ，同时尽可能保持准确率！您可以在 llama.cpp、 [Unsloth Studio](https://unsloth.ai/docs/zh/xin/studio.md) 等大多数推理引擎上运行 2.0 GGUF。

{% columns %}
{% column %}
**2026 年 4 月 20 日更新：** 查看我们最新的 GGUF 基准测试，涵盖 [Qwen3.6](https://unsloth.ai/docs/zh/mo-xing/qwen3.6.md#unsloth-gguf-benchmarks) 和 [Gemma 4](https://unsloth.ai/docs/zh/mo-xing/gemma-4.md#unsloth-gguf-benchmarks).

[2026 年 2 月 27 日更新：](https://unsloth.ai/docs/zh/mo-xing/qwen3.5/gguf-benchmarks.md) **Qwen3.5** 已发布，我们修复了一些工具调用聊天模板的问题，并对每个 GGUF 的困惑度和 KL 散度进行了基准测试。 [查看基准测试结果！](https://unsloth.ai/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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F8y2cQ4VFqGEJLBS8PKZV%2Fgemma%20426b%20bench.lossless.webp?alt=media" alt=""><figcaption><p>Gemma 4 26B A4B 基准测试（越低越好）</p></figcaption></figure>

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fe4U8EnJcC1rAVIrQS9gt%2Fqwen36_mean_q6k_corrected_arrow_pareto_fixed.lossless.webp?alt=media" alt=""><figcaption><p>Qwen3.6 基准测试（越低越好）</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

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

<img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FsERzR65n4jc1UtuSHozZ%2Fwedefrwfwe.gif?alt=media&amp;token=e303ed9e-0d90-456d-8d57-874a06803903" alt="" data-size="original">
{% endhint %}

{% hint style="success" %}
[2025 年 9 月 10 日更新：](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/dynamic-3.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md) 您希望看到更严格的基准测试，下面是 Aider Polyglot 的测试结果！我们的 Dynamic 3-bit DeepSeek V3.1 GGUF 得分为 **75.6%**，超过了许多全精度 SOTA LLM。 [了解更多。](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/dynamic-3.0-ggufs/unsloth-dynamic-ggufs-on-aider-polyglot.md)

<img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-a114143bdd47add988182aabf9313ab40be38d7d%2Faider%20thinking.png?alt=media" alt="DeepSeek-V3.2 Thinking Aider Benchmarks" data-size="original"><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-b085c16c7f8351308229f1341846cbf1a2617d0a%2Faider%20non.png?alt=media" alt="Llama 4 5-shot MMLU Benchmarks" data-size="original">
{% endhint %}

您还可以查看 Benjamin Marie 针对 LiveCodeBench v6、MMLU Pro 等开展的实际应用场景基准测试：

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FhfO2gsbz2lWrZXg3ojyE%2FHCGBTzgboAASv_A.png?alt=media&amp;token=7d6334ca-4f3c-4946-aacd-d55527375fce" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Ftbfnqq8ppzwFbeqPhnw0%2FHAfMRrrXQAALkQb.png?alt=media&amp;token=9730d4e1-3d4a-4ae6-92bf-32aa6724ab86" alt="" width="450"><figcaption></figcaption></figure></div>

可以看到，尽管 Unsloth 的 GGUF 比非 Unsloth 量化模型小约 8GB，表现却更好。

下文将详细分析我们的基准测试和评估结果。

### 💡 Dynamic v2.0 有哪些新变化？

* **重新设计 GGUF 和 safetensors 的层选择机制：** Unsloth Dynamic 2.0 现在能够以更智能、更全面的方式选择性地量化各层。我们不再只修改部分层，而是动态调整每一个可量化层的量化类型，且各层和各模型采用的组合都可能不同。
* 目前选定的 GGUF 以及未来上传的所有 GGUF 都将采用 Dynamic 2.0 和我们的新校准数据集。该数据集包含超过 >1.5M 个 **token** （具体取决于模型），由高质量、经过人工筛选和清洗的数据组成，可显著提升对话性能。
* 此前，我们的 Dynamic 量化（DeepSeek-R1 1.58-bit GGUF）仅对 MoE 架构有效。 <mark style="color:默认值;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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-fd0a92a2bea8efa37b71946ea934a22f00589f40%2Fkldivergence%20graph.png?alt=media" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-76662317725a3b76fb1e5e33b586c86e712bee6f%2F5shotmmlu.png?alt=media" alt="" width="563"><figcaption></figcaption></figure></div>

今后所有 GGUF 上传都将采用 Unsloth Dynamic 2.0，我们的 Dynamic 4 位安全张量量化版本未来也将从中受益。

## 📊 为什么选择 KL 散度？

[准确率并非你所需的一切](https://arxiv.org/pdf/2407.09141) 展示了剪枝层的影响，即使选择剪掉不必要的层，也会导致“翻转”数量出现巨大差异。“翻转”指答案从错误变为正确，或从正确变为错误。论文指出，随着剪枝或量化，MMLU 分数可能不会下降，但这是因为一些错误答案可能“翻转”为正确答案。我们的目标是匹配原始模型，因此衡量“翻转”是一个很好的指标。

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-5a97c101b0df31fb49df20ce4241930897098cf8%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-e4a60354ad8613b6f2361f63fa82c552e00fdda9%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
**KL 散度** 应当是 **报告量化误差时的黄金标准之一** 正如研究论文《准确率并非你所需的一切》所述。 **使用困惑度并不正确** 因为输出 token 的数值可能相互抵消，因此我们必须使用 KLD，或使用更具挑战性的基准测试，例如 [Aider](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/dynamic-3.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="color:默认值;background-color:red;">**此外，指令微调模型各有独特的聊天模板，而仅使用文本的校准数据集并不适用于指令微调模型**</mark> （但适用于基础模型）。事实上，大多数 imatrix GGUF 通常都存在这些校准问题。因此，它们在同样使用维基百科数据的 KL 散度基准测试中自然表现更好，因为模型本质上针对该领域进行了优化。

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

## :1234: 复现 MMLU 的冒险之旅

* 复现 5-shot MMLU 简直是一场噩梦。我们 <mark style="color:默认值;background-color:red;">**无法**</mark> 复现包括 Llama 3.1 (8B) Instruct、Gemma 3 (12B) 在内的许多模型的 MMLU 结果，原因是存在 <mark style="color:默认值;background-color:yellow;">**细微的实现问题**</mark>。例如，Llama 3.1 (8B) 的得分理应约为 68.2%，但使用错误的实现方式可能只得到 <mark style="color:默认值;background-color:red;">**35% 的准确率。**</mark>

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-cc2b4b2bc512b3c9bc065250930259b9b9a9fce0%2FMMLU%20differences.png?alt=media" alt="" width="375"><figcaption><p>MMLU 实现问题</p></figcaption></figure>

* 使用简单的 MMLU 实现时，Llama 3.1 (8B) Instruct 的 5-shot MMLU 准确率为 67.8%。但我们发现，Llama **会将 "A" 和 "\_A"（前面带空格的 A）分词为不同的 token ID**。如果同时考虑带空格和不带空格的 token，得分为 68.2%。 <mark style="color:默认值;background-color:green;">(+0.4%)</mark>
* 有趣的是，根据 Eleuther AI 的 [LLM Harness](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/tasks/llama3/instruct/mmlu/_continuation_template_yaml) ，Llama 3 也会在问题后附加 <mark style="color:默认值;background-color:purple;">**"The best answer is"**</mark> ，以遵循 Llama 3 原始 MMLU 基准测试的做法。
* 还有许多其他细微问题。为了在受控环境中对所有模型进行基准测试，我们从头设计了自己的 MMLU 实现，并直接研究了 [github.com/hendrycks/test](https://github.com/hendrycks/test) ，随后在多个模型上验证结果，并与已公布的数据进行比较。

## :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="color:默认值;background-color:blue;"><strong>67.07%（BF16 为 67.15%）</strong></mark></td><td><strong>70.64%（BF16 为 71.5%）</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="color:默认值;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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-5b352d0449e723556e6e871396c2ee78ae8ec3dc%2Fchart(2).svg?alt=media" 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 缩放配置。我们协助修复了 llama.cpp 中的问题，以支持这一变更 [此处的变更](https://github.com/ggml-org/llama.cpp/pull/12889)

  <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-7ff8229dfa96425f50c2c87f9ca988ef9cc99eff%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>
* Scout 和 Maverick 的 Llama 4 QK Norm 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) 展示了通过 llama.cpp 使用我们的 GGUF 模型时，准确率远高于第三方推理服务提供商的结果——这很可能是上述问题综合导致的，也可能与量化问题有关。

  <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-76c49d8c8e3e42f7407f431a2cede369f87878e4%2FGoC79hYXwAAPTMs.jpg?alt=media" alt=""><figcaption></figcaption></figure>

如图所示，我们的 4 位动态 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 的新版动态量化 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\nCreate a Flappy Bird game.<|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 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/ji-chu-zhi-shi/dynamic-3.0-ggufs.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.
