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。

一套最小驗證流程

可以按這個順序走：

登入 Hugging Face。

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。跑通之後，再回到官方配置，逐步測試速度、顯存和輸出品質。

參考資料：