DiffusionGemma 本地部署：用 vLLM 跑起 Google 文本扩散模型

上一篇整理了 DiffusionGemma 为什么值得关注：它不是传统逐 token 自回归生成，而是用文本扩散和 256-token canvas 做并行去噪，更适合低延迟、本地交互、行内编辑和代码补全。

这篇只看更具体的问题：怎么部署，怎么用命令行跑起来。

官方现在给出的主线是 vLLM。DiffusionGemma 已经可以通过 vLLM 的 OpenAI-compatible local server 方式启动，然后用类似 OpenAI Chat Completions 的接口请求。

前置判断

先确认自己是不是适合折腾 DiffusionGemma。

项目	建议
模型	`google/diffusiongemma-26B-A4B-it`
显卡	优先 NVIDIA 独立 GPU
显存	官方提到量化后可落在高端消费级独显的 18GB VRAM 范围内
推荐场景	本地低并发、低延迟、交互式生成
不推荐场景	高 QPS 云端服务、质量优先的长文生产
服务框架	`vLLM`
接口形态	OpenAI-compatible local server

DiffusionGemma 是 26B total MoE，推理时激活 3.8B 参数。它不是小模型，只是通过 MoE、量化和并行生成，把本地部署门槛压低到高端消费级 GPU 可以探索的范围。

如果你只想稳定写长文、做知识问答或上线生产接口，标准 Gemma 4 仍然更稳。DiffusionGemma 更适合试低延迟编辑器、代码中间补全、结构化文本即时修正这类交互工具。

方式一：直接用 vLLM 启动

官方开发者指南给出的核心命令如下：

1
2
3
4
5
6
7
8
9


vllm serve google/diffusiongemma-26B-A4B-it \
  --max-model-len 262144 \
  --max-num-seqs 4 \
  --gpu-memory-utilization 0.85 \
  --attention-backend TRITON_ATTN \
  --generation-config vllm \
  --hf-overrides '{"diffusion_sampler": "entropy_bound", "diffusion_entropy_bound": 0.1}' \
  --diffusion-config '{"canvas_length": 256}' \
  --enable-chunked-prefill

这条命令会从 Hugging Face 拉取 google/diffusiongemma-26B-A4B-it，并启动一个本地 OpenAI-compatible server。默认服务通常监听 http://localhost:8000。

如果你的 Hugging Face 环境需要登录，先执行：

1

huggingface-cli login

如果本机还没有 vLLM，通常可以先准备 Python 虚拟环境：

1
2
3
4


python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -U vllm

实际是否能直接 pip install -U vllm 跑通，要看 vLLM 当前版本是否已经包含 DiffusionGemma 支持。DiffusionGemma 是新架构，如果遇到模型结构不识别、参数不识别、attention backend 报错，优先查看 vLLM 官方 release、Google Developer Guide 和模型卡里的最新说明。

方式二：用 Docker 跑 vLLM

如果不想污染本机 Python 环境，可以用 vLLM Docker 镜像。vLLM recipes 里给过类似的 Docker 启动方式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


docker run -itd --name diffusiongemma \
  --ipc=host \
  --network host \
  --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:gemma \
    --model google/diffusiongemma-26B-A4B-it \
    --max-model-len 262144 \
    --max-num-seqs 4 \
    --gpu-memory-utilization 0.85 \
    --generation-config vllm \
    --enable-chunked-prefill \
    --host 0.0.0.0 \
    --port 8000

这个方式的好处是环境更干净，适合服务器、工作站或临时测试机。注意两点：

需要宿主机已经装好 NVIDIA driver 和 NVIDIA Container Toolkit。
如果镜像里的 vLLM 版本不含 DiffusionGemma 支持，仍然会启动失败，需要换更新镜像或对应分支。

如果你希望复用本机 Hugging Face 缓存，-v ~/.cache/huggingface:/root/.cache/huggingface 很有用，避免每次容器重拉模型。

用 curl 测试服务

服务启动后，可以先查模型列表：

1

curl http://localhost:8000/v1/models

如果返回里能看到 google/diffusiongemma-26B-A4B-it，说明服务基本起来了。

然后用 Chat Completions 测试：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/diffusiongemma-26B-A4B-it",
    "messages": [
      {
        "role": "user",
        "content": "用三句话解释 DiffusionGemma 和普通自回归 LLM 的区别。"
      }
    ],
    "max_tokens": 256,
    "temperature": 0.7
  }'

如果你习惯 OpenAI SDK，也可以把 base_url 指到本地服务：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY",
)

response = client.chat.completions.create(
    model="google/diffusiongemma-26B-A4B-it",
    messages=[
        {
            "role": "user",
            "content": "写一个 Python 函数，把 Markdown 表格转换成 CSV。",
        }
    ],
    max_tokens=512,
)

print(response.choices[0].message.content)

参数怎么理解

官方命令里有几个参数值得单独看。

`--max-model-len 262144`

设置最大上下文长度。DiffusionGemma / Gemma 4 系列支持很长的上下文，但这不代表每次都应该开到极限。上下文越长，显存和调度压力越大。

如果只是本地试跑，可以先保留官方值；如果显存吃紧，可以考虑降低它，再看实际任务是否受影响。

`--max-num-seqs 4`

限制同时处理的序列数量。DiffusionGemma 更适合低并发、本地交互；把并发开太大，不一定更快，反而可能增加显存压力。

本地单用户工具可以从 1 到 4 之间试。多人服务才需要更认真地压测。

`--gpu-memory-utilization 0.85`

告诉 vLLM 最多使用多少比例 GPU 显存。0.85 是一个比较常见的保守值。

如果启动 OOM，可以尝试降到：

1

--gpu-memory-utilization 0.75

如果显存很充足，也可以略微调高，但不要一开始就拉满，给系统和其他进程留一点余量。

`--attention-backend TRITON_ATTN`

指定 attention backend。官方命令使用 TRITON_ATTN，这和 DiffusionGemma 的特殊 attention / denoising 路径有关。

如果遇到 backend 不支持，多半是 vLLM、CUDA、Triton、显卡架构之间版本不匹配，先不要乱改模型参数，优先检查软件栈。

`--hf-overrides`

官方命令里这段很关键：

1

--hf-overrides '{"diffusion_sampler": "entropy_bound", "diffusion_entropy_bound": 0.1}'

它覆盖 Hugging Face config 里的 diffusion sampler 设置。entropy_bound 可以理解为一种控制去噪停止或采样行为的策略，用来配合 DiffusionGemma 的迭代生成。

这不是普通 LLM 常见参数，建议先照官方值跑通，再做实验。

`--diffusion-config`

官方命令里是：

1

--diffusion-config '{"canvas_length": 256}'

canvas_length 对应 DiffusionGemma 的 256-token canvas。模型不是一个 token 一个 token 线性生成，而是在一个块内并行去噪。这个值直接关系到它的块扩散生成方式。

不建议一开始随意改。先用官方值确认速度、质量和显存，再根据 vLLM 后续文档测试。

`--enable-chunked-prefill`

启用分块 prefill。DiffusionGemma 的长序列处理会在 prefill / denoising 之间配合工作，chunked prefill 可以帮助长上下文场景更稳地调度。

如果你只做短 prompt 测试，体感可能不明显；如果处理长上下文，它更有意义。

一个更保守的本地测试命令

如果你只是想先确认能不能启动，可以把并发和显存压力降一点：

1
2
3
4
5
6
7
8
9


vllm serve google/diffusiongemma-26B-A4B-it \
  --max-model-len 65536 \
  --max-num-seqs 1 \
  --gpu-memory-utilization 0.75 \
  --attention-backend TRITON_ATTN \
  --generation-config vllm \
  --hf-overrides '{"diffusion_sampler": "entropy_bound", "diffusion_entropy_bound": 0.1}' \
  --diffusion-config '{"canvas_length": 256}' \
  --enable-chunked-prefill

这个命令不一定是最优性能配置，但更适合第一次排障。先让模型起来，再逐步增加上下文长度和并发。

适合拿来做什么 demo

DiffusionGemma 不适合只拿普通聊天问题测试。它真正值得测的是“非线性生成”和“实时局部修正”。

可以先试这些 prompt：

1
2
3
4


补全下面这个 Python 函数中间缺失的逻辑，只输出完整函数：

def markdown_table_to_csv(markdown: str) -> str:
    ...

1
2
3


修复下面 JSON，让它成为合法 JSON，并保留原始字段含义：

{"name":"demo","items":[{"id":1,"tags":["a","b",],},]}

1
2
3
4


把下面这段 Markdown 表格补齐为 5 行，并保证每行列数一致：

| 参数 | 作用 | 建议 |
| --- | --- | --- |

1
2
3


你是编辑器里的行内补全模型。只改写下面句子中括号里的部分，保持前后文连贯：

DiffusionGemma 适合 [这里写一个关于低延迟交互的短语]，但不适合质量优先的长文生产。

这些任务比“讲个故事”更能体现它的双向注意力、块内自修正和结构化输出能力。

常见问题

启动时报模型不支持

优先检查 vLLM 版本。DiffusionGemma 是新模型，旧版 vLLM 可能还没有对应实现。

可先查看：

1

vllm --version

然后对照官方开发者指南、vLLM release note 或 DiffusionGemma 模型卡。

Hugging Face 下载失败

先确认网络和登录状态：

1

huggingface-cli whoami

必要时重新登录：

1

huggingface-cli login

如果在服务器上跑，建议预先拉取模型，或者把 Hugging Face cache 挂到容器里。

OOM

先按这个顺序降压力：

1

--max-num-seqs 1

1

--gpu-memory-utilization 0.75

1

--max-model-len 65536

如果仍然 OOM，就需要确认是否用了量化权重、当前 vLLM 是否正确加载量化格式，以及显卡是否满足模型要求。

速度没有想象中快

先确认你的场景是不是 DiffusionGemma 的优势区间。它的加速主要面向本地、低并发、专用 GPU、低到中等 batch。

如果是在高并发云端服务，自回归模型可以通过 batch 把硬件吃满，DiffusionGemma 的优势会变小。Apple Silicon 这类统一内存架构也未必能看到同等加速。

输出质量不如 Gemma 4

这是预期内的。官方明确说，DiffusionGemma 因为优先速度和并行布局生成，整体输出质量低于标准 Gemma 4。质量优先的生产应用，仍应选标准 Gemma 4。

一套最小验证流程

可以按这个顺序走：

1

huggingface-cli login

启动 vLLM 服务。

1
2
3
4
5
6
7
8
9


vllm serve google/diffusiongemma-26B-A4B-it \
  --max-model-len 65536 \
  --max-num-seqs 1 \
  --gpu-memory-utilization 0.75 \
  --attention-backend TRITON_ATTN \
  --generation-config vllm \
  --hf-overrides '{"diffusion_sampler": "entropy_bound", "diffusion_entropy_bound": 0.1}' \
  --diffusion-config '{"canvas_length": 256}' \
  --enable-chunked-prefill

检查模型列表。

1

curl http://localhost:8000/v1/models

发起一次请求。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/diffusiongemma-26B-A4B-it",
    "messages": [
      {
        "role": "user",
        "content": "补全一个 Python 函数：输入 Markdown 表格字符串，输出 CSV 字符串。"
      }
    ],
    "max_tokens": 512,
    "temperature": 0.4
  }'

再测试结构化修复或代码 infilling。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/diffusiongemma-26B-A4B-it",
    "messages": [
      {
        "role": "user",
        "content": "修复这段 JSON，只输出合法 JSON：{\"name\":\"demo\",\"items\":[{\"id\":1,\"tags\":[\"a\",\"b\",],},]}"
      }
    ],
    "max_tokens": 256,
    "temperature": 0.2
  }'

如果这五步能跑通，再去调高上下文长度、并发和显存利用率。

小结

DiffusionGemma 的部署重点不是“找一个聊天模型替代品”，而是验证一条新的本地交互路线：用 vLLM 启动 OpenAI-compatible 服务，再围绕行内编辑、代码填空、结构化文本修复、低延迟输出做实验。

第一次部署建议先用保守参数跑通：--max-num-seqs 1、--max-model-len 65536、--gpu-memory-utilization 0.75。跑通之后，再回到官方配置，逐步测试速度、显存和输出质量。

参考资料：