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

# DiffusionGemma - 如何在本地运行

DiffusionGemma **26B-A4B** 是 Google DeepMind 的全新开源 **多模态** 模型，构建于 [Gemma 4](/docs/zh/mo-xing/gemma-4.md) MoE 架构。支持 **256K 上下文**, **140 多种语言**，DiffusionGemma 旨在用于 **高速文本生成** 可处理文本、视频和图像输入。DiffusionGemma 可以在本地运行于 **18GB 内存**，以及 [微调](#fine-tune-diffusiongemma) 现已通过 [Unsloth](https://github.com/unslothai/unsloth).

DiffusionGemma 不采用标准的逐 token 解码，而是使用 **扩散生成** 并行生成输出，并逐步将其细化为最终答案——类似于图像扩散模型，但用于文本。可通过 [Unsloth Studio](/docs/zh/xin/studio.md) 或 llama.cpp。在 RTX 6000 上，DiffusionGemma 可达到 **2000+ tokens/秒**. **GGUF：** [diffusiongemma-26B-A4B-it-GGUF](https://huggingface.co/unsloth/diffusiongemma-26B-A4B-it-GGUF)

<a href="/docs/zh/mo-xing/diffusiongemma.md#run-diffusiongemma-tutorials" class="button primary">运行 DiffusionGemma</a><a href="/docs/zh/mo-xing/diffusiongemma.md#fine-tune-diffusiongemma" class="button secondary">微调 DiffusionGemma</a>

{% hint style="success" %}
**6 月 12 日：** 你现在可以通过运行 DiffusionGemma [Unsloth Studio](#unsloth-studio-guide) ✨ 推理速度提升 1.8 倍！
{% endhint %}

### 使用指南

DiffusionGemma 旨在为那些需要比标准模型更快生成速度的用户而设计。它适用于快速本地推理、长上下文文档分析、图像/视频理解、OCR 和文档解析、代码生成、工具调用、智能体工作流，以及低延迟的小批量推理。

与标准 Gemma 4 模型不同，DiffusionGemma 需要支持扩散的推理运行时。诸如 `temperature`, `top_p`，以及 `top_k` 仅靠它并不足以在没有所需扩散采样器的情况下复现推荐的行为。

<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%2Fszoidwwj70dLm5vBjpmL%2Fdiffusiongemma.gif?alt=media&amp;token=8ce359fd-f92c-4cf8-a491-06b04c505cb7" alt="" width="563"><figcaption></figcaption></figure></div>

### 硬件要求

通常最好至少有 18GB RAM，才能以 4 位精度运行该模型。 **GGUF：** [diffusiongemma-26B-A4B-it-GGUF](https://huggingface.co/unsloth/diffusiongemma-26B-A4B-it-GGUF)

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

| 4 位   | 5-bit | 6 位   | 8 位   | BF16 / FP16 |
| ----- | ----- | ----- | ----- | ----------- |
| 18 GB | 20 GB | 24 GB | 28 GB | 52 GB       |

{% hint style="info" %}
经验法则是，你可用的总内存应至少超过你下载的量化模型大小。如果不够，你仍然可以使用部分 RAM / 磁盘卸载运行，但生成速度会更慢。根据你使用的上下文窗口大小，你还需要更多算力。
{% endhint %}

## 运行 DiffusionGemma 教程

最好至少使用 4 位精度，因此我们将使用 4 位 `Q4_K_M` 量化版本，它需要 18GB RAM。 **GGUF：** [diffusiongemma-26B-A4B-it-GGUF](https://huggingface.co/unsloth/diffusiongemma-26B-A4B-it-GGUF)

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

### 🦥 Unsloth Studio 指南

{% hint style="success" %}
你现在可以通过运行 DiffusionGemma [Unsloth Studio](#unsloth-studio-guide) ✨。确保你使用 [`v0.1.463-beta`](https://github.com/unslothai/unsloth/tree/v0.1.462-beta) 或 `2026.6.6`.
{% endhint %}

DiffusionGemma 现在可以在……中运行和训练 [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%2Fszoidwwj70dLm5vBjpmL%2Fdiffusiongemma.gif?alt=media&amp;token=8ce359fd-f92c-4cf8-a491-06b04c505cb7" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% stepper %}
{% step %}

#### 安装 Unsloth

请确保你使用最新的 [`v0.1.463-beta`](https://github.com/unslothai/unsloth/tree/v0.1.462-beta) 或 `2026.6.6`。在你的终端中运行：

**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 %}

#### 搜索并下载 DiffusionGemma

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

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

{% step %}

#### 运行 DiffusionGemma

在使用 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%2Fszoidwwj70dLm5vBjpmL%2Fdiffusiongemma.gif?alt=media&amp;token=8ce359fd-f92c-4cf8-a491-06b04c505cb7" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

### 🦙 Llama.cpp 指南

在本教程中，我们将使用动态 4 位 `Q4_K_M` 量化版本，它需要 18GB RAM 和 [llama.cpp](llama.cpphttps://github.com/ggml-org/llama.cpp) 以进行快速本地推理，尤其是在你有 CPU 的情况下。

{% stepper %}
{% step %}
获取特定的 `llama.cpp` PR 上 [**GitHub 上获取**](https://github.com/ggml-org/llama.cpp/pull/24423)。你也可以按照下面的构建说明进行操作。将 `-DGGML_CUDA=ON` 改为 `-DGGML_CUDA=OFF` 如果你没有 GPU，或者只想使用 CPU 推理。 **对于 Apple Mac / Metal 设备**，设置 `-DGGML_CUDA=OFF` 然后按常规继续——Metal 支持默认开启。

```bash
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
gh pr checkout 24423
# 使用 CUDA 构建（若仅构建 CPU 版本则去掉 -DGGML_CUDA=ON）
cmake -B build -DGGML_CUDA=ON
cmake --build build -j --config Release --target llama-diffusion-cli
cd ..
```

{% endstep %}

{% step %}
通过以下方式下载模型（在安装 `pip install huggingface_hub`之后）。你可以选择 `Q4_K_M` 或者其他量化版本，如 `Q8_0` 。如果下载卡住，请查看： [Hugging Face Hub、XET 调试](/docs/zh/ji-chu-zhi-shi/troubleshooting-and-faqs/hugging-face-hub-xet-debugging.md)

```bash
pip install -U "huggingface_hub[cli]"
hf download unsloth/diffusiongemma-26B-A4B-it-GGUF \
    --local-dir unsloth/diffusiongemma-26B-A4B-it-GGUF \
    --include "*Q8_0*" # 使用 "*Q4_K_M*" 可下载更小的 16 GB 版本
```

{% endstep %}
{% endstepper %}

### 与 DiffusionGemma 聊天

然后运行下面的命令：

{% code overflow="wrap" %}

```bash
./build/bin/llama-diffusion-cli \
  -m unsloth/diffusiongemma-26B-A4B-it-GGUF/diffusiongemma-26B-A4B-it-Q8_0.gguf \
  -ngl 99 -cnv -n 2048
```

{% endcode %}

你会看到：

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fqax7SXjUrxZpWORhexyj%2Fimage.png?alt=media&amp;token=066fb8a1-8865-417a-9ca0-2c5443ebe520" alt=""><figcaption></figcaption></figure>

如果你输入诸如“创建一个 Flappy Bird 游戏”这样的问题，你会看到步骤：

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FWBxW71WgZwEmj8vqEuhT%2Fimage.png?alt=media&amp;token=19ae3bfc-2a8d-463b-b2cb-7b9456ee9226" alt=""><figcaption></figcaption></figure>

然后之后你会看到输出：

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fngo7EXmeZnJKhmWAcrNy%2Fimage.png?alt=media&amp;token=f6024241-227c-41f9-9a23-cac8418f89e7" alt="" width="375"><figcaption></figcaption></figure>

你也可以继续对话！

将 `-n 2048` 作为你想要预测的 token 数量，因此数值越大，答案越长。

### 扩散过程的实时可视化

要实时查看扩散过程，请使用下面的方式——特别启用 `--diffusion-visual`:

```bash
./build/bin/llama-diffusion-cli \
  -m unsloth/diffusiongemma-26B-A4B-it-GGUF/diffusiongemma-26B-A4B-it-Q8_0.gguf \
  -ngl 99 -cnv -n 2048 --diffusion-visual
```

你将再次看到：

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FwvBjHSctfgHXYDAu1TFp%2Fimage.png?alt=media&amp;token=860a27d0-6d1c-404b-972a-4cdbdcce166a" alt=""><figcaption></figcaption></figure>

然后我们得到：

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FTrPopPhlJZGW28cyjaJB%2Fdiffusiongem.gif?alt=media&amp;token=b8d9434b-d929-4f13-81ad-ecfe21262169" alt="" width="563"><figcaption></figcaption></figure>

llama.cpp 的所有参数，使用分支：

* `-n, --n-predict N` - 目标 token；推导 `--diffusion-blocks` 并增长 `-ub` / `-b` / `-c`.
* `-ngl 99` - 将所有层卸载到 GPU（`-ngl 0` 用于仅 CPU）。
* `-cnv` - 多轮对话模式。
* `--diffusion-visual` - 画布实时去噪视图。
* 熵界采样器默认开启（`--diffusion-eb auto`）。可通过以下参数调整： `--diffusion-eb-max-steps` （默认 48）， `--diffusion-eb-t-max` / `--diffusion-eb-t-min` (0.8 -> 0.4), `--diffusion-eb-entropy-bound` （0.1），以及 `--diffusion-eb-confidence` (0.005).
* `--diffusion-kv-cache {auto,on,off}` - 提示前缀 KV 缓存（auto = 单 GPU 时开启）。

## 微调 DiffusionGemma

现在你可以直接使用……训练和微调 DiffusionGemma [**Unsloth**](#unsloth-studio-guide)。在我们的示例中，我们通过在数独数据上微调模型来展示领域特定训练的影响。基础模型起初在数独任务上的表现很差，但在针对性数据集上训练后，它学会了真正解决数独，并能正确解答每个示例。

你可以使用我们的 Colab 笔记本（A100）通过以下方式微调 DiffusionGemma：

{% embed url="<https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/DiffusionGemma_(26B-A4B)-Sudoku.ipynb>" %}

<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%2FexAR7eC5YN44boNs2tFD%2Fsudoku_before_after(1).gif?alt=media&amp;token=2bc254a8-dbf9-4638-a5cb-8a7877d3c9fa" alt="" width="563"><figcaption></figcaption></figure></div>

## 推荐设置

[Unsloth Studio](#unsloth-studio-guide) 会自动为你的模型设置最佳推理参数。如有必要，可使用以下设置：

| 类别    | 设置项      | 值                           |
| ----- | -------- | --------------------------- |
| 采样    | 方法       | `diffusion_sampling`        |
| 采样    | 采样器      | `entropy_bounded_denoising` |
| 采样    | 最大去噪步数   | `48`                        |
| 温度    | 温度调度     | `linear_decay`              |
| 温度    | 温度起始值    | `0.8`                       |
| 温度    | 温度结束值    | `0.4`                       |
| 熵     | 熵界       | `0.1`                       |
| 自适应停止 | 已启用自适应停止 | `true`                      |
| 自适应停止 | 熵阈值      | `0.005`                     |
| 画布    | 画布长度     | `256`                       |

**自适应停止触发条件**

自适应停止应仅在以下情况下触发： **两者** 满足条件：

| 条件                    | 所需值       |
| --------------------- | --------- |
| 画布平均熵                 | `< 0.005` |
| 最高概率 token 连续 2 步保持稳定 | `true`    |

在每个去噪步骤中，采样器应选择互信息界仍保持以下值的最低熵 token： `entropy_bound = 0.1`。未被选中的 token 应在下一个去噪步骤之前完全重新加噪。

### 思考模式

DiffusionGemma 支持 Gemma 4 风格的思考模式。要启用思考，请在系统提示词开头添加思考 token：

```
<|think|>
```

启用思考后，模型可能会先输出内部推理通道，然后给出最终答案：

```
<|channel>thought
[内部推理]
<channel|>
[最终答案]
```

要禁用思考，请移除 `<|think|>` token 从系统提示词中删除。即使禁用思考，模型仍可能输出一个空的思考通道：

```
<|channel>thought
<channel|>
[最终答案]
```

对于多轮对话，不要 **不会** 将之前的隐藏思考包含在对话历史中。只应在下一轮用户输入前保留最终的助手回复。

## DiffusionGemma 最佳实践

### 多模态提示

DiffusionGemma 支持交错的多模态输入，包括文本和图像。视频可以作为图像帧序列进行处理。

为了在多模态提示中获得最佳效果，请将图像或帧内容放在文本指令之前。示例：

```
[图像]
描述这张图表并总结关键趋势。
```

对于文档解析、OCR、图表理解、UI 理解或小段文本提取，请使用更高的视觉 token 预算。

支持的视觉 token 预算：

| 视觉 token 预算 | 最适合             |
| ----------- | --------------- |
| 70          | 快速分类、简单描述       |
| 140         | 轻量级视觉问答         |
| 280         | 通用图像理解          |
| 560         | OCR、图表、UI 截图    |
| 1120        | 密集文档、小字号文本、细致提取 |

对于视频样式输入，DiffusionGemma 最多可处理 **60 秒** 当采样为 **每秒 1 帧**.

### 采样说明

DiffusionGemma 不是普通的仅下一 token 模型。它会生成一块 token，称为 **画布**，方法是反复细化带噪的 token 预测。生成过程大致如下：

1. 编码器处理提示并构建上下文缓存。
2. 解码器接收一个 256 token 的生成画布。
3. 扩散采样器迭代地对画布去噪。
4. 置信度高的 token 会被选中并保留。
5. 不确定的 token 会重新加噪并再次细化。
6. 画布完成后，会将其追加到上下文中。
7. 模型继续处理下一个画布。

这种块自回归方法使 DiffusionGemma 能比标准自回归模型在更少的前向传递中生成更多 token。

## 基准测试

DiffusionGemma 针对速度和多模态推理进行了优化，不过标准 Gemma 4 在传统推理基准上更强。

| 基准                  | DiffusionGemma 26B-A4B | Gemma 4 26B-A4B |
| ------------------- | ---------------------: | --------------: |
| MMLU Pro            |                  77.6% |           82.6% |
| AIME 2026 无工具       |                  69.1% |           88.3% |
| LiveCodeBench v6    |                  69.1% |           77.1% |
| Codeforces ELO      |                   1429 |            1718 |
| GPQA Diamond        |                  73.2% |           82.3% |
| Tau2 平均值            |                  56.2% |           68.2% |
| HLE 无工具             |                  11.0% |            8.7% |
| HLE 带搜索             |                  11.9% |           17.2% |
| BigBench Extra Hard |                  47.6% |           64.8% |
| MMMLU               |                  81.5% |           86.3% |

| 长上下文基准               | DiffusionGemma 26B-A4B | Gemma 4 26B-A4B |
| -------------------- | ---------------------: | --------------: |
| MRCR v2 8 针 128K 平均值 |                  32.0% |           44.1% |

**视觉基准：**

| 视觉基准                  | DiffusionGemma 26B-A4B | Gemma 4 26B-A4B |
| --------------------- | ---------------------: | --------------: |
| MMMU Pro              |                  54.3% |           73.8% |
| OmniDocBench 1.5，越低越好 |                  0.319 |           0.149 |
| MATH-Vision           |                  70.5% |           82.4% |
| MedXPertQA MM         |                  49.0% |           58.1% |


---

# 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/diffusiongemma.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.