Diffusers 原生支援 Nunchaku Lite 4-bit 擴散模型推理
Bringing Nunchaku 4-bit Diffusion Inference to Diffusers
Diffusers 現已原生支援 Nunchaku Lite 的 4-bit 擴散模型推理,預量化檢查點可用 `from_pretrained()` 載入,無須獨立推理引擎或本機編譯 CUDA。
文章説明 Nunchaku Lite 在 Diffusers 的原生載入方式,並以 RTX PRO 6000 基準量化呈現延遲與顯存變化。
大型擴散 Transformer 可以生成令人驚艷的圖像(甚至影片、音訊片段,現在還可生成文字),但以 BF16 精度載入現代文本生成圖像模型,往往需要 20–30 GB VRAM,令大多數消費級 GPU 都無法使用這些模型。量化是解決此問題的有效方法;Diffusers 已整合 bitsandbytes、GGUF、torchao 和 Quanto 等多種量化後端,我們曾在《探索 Diffusers 的量化後端》中介紹。
大部分後端都只量化權重。換言之,它們會以低精度儲存權重,並在運算時將權重反量化回高精度。這能大幅減少記憶體用量,但通常不會加快推論,甚至可能略為增加延遲。
SVDQuant 是熱門推論引擎 Nunchaku 背後採用的量化方法,與一般方法不同。它以 4-bit 權重和啟動值(W4A4)執行主要 Transformer 層,既節省記憶體,也加快去噪循環。下文會詳述其原理;不過在此之前,要使用這類 checkpoint 必須另裝推論程式庫。
目前的 Diffusers 只需呼叫 from_pretrained() 即可載入 Nunchaku checkpoint;透過 kernels 套件,無須在本機編譯 CUDA。此外,配套的 diffuse-compressor 工具組讓你可以自行量化新架構,並以一般 Diffusers 儲存庫的形式發布。
目錄
- Nunchaku Lite 入門
- 背景:SVDQuant 和 Nunchaku
- 介紹 Nunchaku Lite
- 在 Diffusers 中原生載入
- 進一步提升速度並減少記憶體用量
- 基準測試
- 量化自己的模型
- 可直接使用的 checkpoint
- 總結
- 鳴謝
Nunchaku Lite 入門
首先安裝必要套件。你需要較新的 Diffusers 版本及 Hugging Face kernels 套件:
pip install -U diffusers transformers accelerate kernels bitsandbytes
然後像載入其他 Diffusers 模型一樣,載入預先量化的 pipeline:
import torch
from diffusers import ErnieImagePipeline
pipe = ErnieImagePipeline.from_pretrained(
"lite-infer/ERNIE-Image-Turbo-nunchaku-lite-nvfp4_r32-bnb4-text-encoder",
torch_dtype=torch.bfloat16,
).to("cuda")
image = pipe(
prompt="A cinematic portrait of a red fox in a misty forest at sunrise, "
"detailed fur, volumetric light",
height=1024,
width=1024,
num_inference_steps=8,
guidance_scale=1.0,
generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("output.png")
無須自訂 pipeline 類別或獨立推論引擎,亦不必在本機編譯。首次使用時,NVFP4 kernels 會透過 Nunchaku Lite kernels 頁面從 Hub 下載。這個 checkpoint 結合 Nunchaku NVFP4 Transformer 和 bitsandbytes NF4 文本編碼器,在 RTX 5090 上生成一張 1024x1024 圖像約需 1.7 秒,峯值記憶體用量約 12 GB;相比之下,BF16 pipeline 約需 24 GB。Nunchaku Lite checkpoint 格式的詳情,請參閲官方 Diffusers 文件。
NVFP4 checkpoint 需要 NVIDIA Blackwell GPU(RTX 50 系列、RTX PRO 6000、B200)。較早世代的 GPU 請使用 INT4 版本。詳情請參閲下方硬件支援表格。
背景:SVDQuant 和 Nunchaku
SVDQuant 是 Nunchaku 及其參考 CUDA 推論引擎背後採用的量化方法。標準 4-bit 量化難以用於擴散 Transformer,因為權重和啟動值都含有大量離羣值。SVDQuant 將啟動值中的離羣值移入權重,以一個小型 16-bit 低秩分支表示每個權重矩陣中最難處理的部分,再把剩餘殘差量化至 4 bits。Nunchaku 透過為 4-bit 路徑和低秩分支提供融合 kernel,令運算更快。
介紹 Nunchaku Lite
原有的 Nunchaku 引擎,很多速度優勢來自針對模型的融合執行路徑,例如融合 QKV 投影和 GELU/MLP kernel。這些優化與各架構的模組排列和 checkpoint 格式緊密相關,因此要支援新的模型系列,通常需要專門整合作業。
Nunchaku Lite 是 Diffusers 新增的整合方式。使用它後,Diffusers 無須自訂 pipeline 或獨立推論引擎,即可載入 Nunchaku 格式的 checkpoint。在底層,Nunchaku Lite 會在載入 checkpoint 前,將標準 Diffusers 模型中相關的 nn.Linear 模組替換為 runtime 的 SVDQ/AWQ linear layer。CUDA kernel 透過 kernels 套件從 Hub 取得。系統會使用兩個 kernel 系列:
svdq_w4a4:搭配 SVDQuant 低秩修正的 4-bit 權重和啟動值。此 layer 用於 Transformer 的 attention 和 MLP 投影,幾乎所有運算都在這些層中執行;並提供 INT4 和 NVFP4 版本。awq_w4a16:4-bit 權重配合 16-bit 啟動值,用於自適應正規化和調制投影,例如 FLUXadanorm_single/adanorm_zero或 Qwen-Image 調制層。這些層受記憶體頻寬限制,且對精度敏感,因此 AWQ 適合在節省記憶體和空間的同時保留精度。
取捨在於缺少針對架構的融合 kernel 和模組,因此 Nunchaku Lite 無法達到原有 Nunchaku 引擎的加速幅度。不過,這個精簡實作仍可帶來約 30% 加速,同時維持相同程度的 VRAM 減幅。
在 Diffusers 中原生載入
如果你曾在 Diffusers 使用 bitsandbytes 或 torchao,便會覺得這個機制很熟悉。Nunchaku Lite 模型儲存庫就是一般的 Diffusers 儲存庫。唯一特別之處,是 Transformer 的量化設定由 quantization_config 區塊提供,並位於 config.json 內:
"quantization_config": {
"quant_method": "nunchaku_lite",
"compute_dtype": "bfloat16",
"svdq_w4a4": {
"precision": "nvfp4",
"group_size": 16,
"rank": 32,
"targets": [
"layers.0.self_attention.to_q",
"layers.0.self_attention.to_k",
"..."
]
},
"awq_w4a16": {
"precision": "int4",
"group_size": 64,
"targets": [
"adaLN_modulation.1",
"..."
]
}
}
此設定會告訴 Diffusers 哪些模組已量化、採用哪種方案,以及要建立哪種 Nunchaku Lite runtime layer(SVDQW4A4Linear 或 AWQW4A16Linear)。
由於量化模型保留與稠密模型完全相同的模組結構,下游的所有功能(scheduler、LoRA 載入 hook、offloading、torch.compile)都會將它視為一般 Diffusers 模型。
硬件支援
Nunchaku Lite 會按 GPU 世代和 checkpoint 精度使用不同的 kernel 版本:
| 方案 | 精度 | 支援的 GPU |
|---|---|---|
svdq_w4a4 |
nvfp4 |
Blackwell(RTX 50 系列、RTX PRO 6000、B200) |
svdq_w4a4 |
int4 |
Turing/Ampere/Ada(RTX 30 和 40 系列、A100、L40S) |
awq_w4a16 |
int4 |
Turing/Ampere/Ada(RTX 30 和 40 系列、A100、L40S) |
目前 4-bit kernel 不支援 Volta 和 Hopper GPU。量化器會在載入時驗證 GPU 的 CUDA 能力;若不支援,會發出清晰錯誤訊息,而非產生不正確的輸出。
提升速度並減少記憶體用量
Nunchaku Lite 可配合 Diffusers 的其他記憶體和速度優化功能使用。
torch.compile。編譯 Transformer 後,端到端加速幅度由 1.35x 提升至 1.8x:
pipe.transformer.compile(fullgraph=True)
# or compile_repeated_blocks() for faster compilation
pipe.transformer.compile_repeated_blocks(fullgraph=True)
量化文本編碼器。Transformer 並非唯一佔用大量記憶體的元件。T5 或 Qwen3 等文本編碼器本身也可佔用數 GB。使用 bitsandbytes NF4 進一步量化文本編碼器,在我們的基準測試中可令 VRAM 峯值降低約 22%。
Offloading。如需將 pipeline 放入較小型 GPU,Diffusers 的 offloading 輔助功能(例如 enable_model_cpu_offload() 和 enable_sequential_cpu_offload())可照常使用。
基準測試
以下所有數據均在 NVIDIA RTX PRO 6000(Blackwell)上,以 1024x1024 設定使用 rootonchair/ERNIE-Image-Turbo-nunchaku-lite-int4-bnb4-text-encoder 測得。
端到端延遲和記憶體
| 設定 | 完整 pipeline | 去噪循環 | VRAM 峯值 | 加速幅度 |
|---|---|---|---|---|
| BF16 基準 | 3.00 秒 | 2.86 秒 | 31.1 GB | 1.0x |
| Nunchaku Lite NVFP4 | 2.27 秒 | 2.13 秒 | 20.6 GB | 1.35x |
Nunchaku Lite NVFP4 + torch.compile |
1.68 秒 | 1.53 秒 | 20.6 GB | 1.8x |
| Nunchaku Lite NVFP4 + NF4 文本編碼器 | 2.29 秒 | 2.13 秒 | 16.0 GB | 1.35x |
如上所示,Nunchaku 最多可將 VRAM 峯值降低 50%,同時把延遲改善約 30%。剩餘開銷主要來自額外的 kernel 啟動;torch.compile 可減輕這個問題,將完整 pipeline 的時間縮短至 1.68 秒,比 BF16 基準快 1.8 倍。
圖像品質
量化自己的模型
Diffusers 中的 Nunchaku Lite 支援不受架構限制;diffuse-compressor 工具組則為 Diffusers 模型提供端到端 SVDQuant 流程:校準、量化、封裝並發布。
以下以量化 FLUX.2 Klein 4B 為例,逐步説明主要流程:檢查模型、校準並量化 Transformer、將結果封裝成 Diffusers pipeline,然後驗證並推送至 Hub。完整教學會詳細説明每個旗標。
1. 檢查要量化的內容
通用掃描器會遍歷模型並決定處理目標:重複 Transformer 區塊堆疊內相容的 linear layer 會成為 SVDQ W4A4 目標;識別到的調制 linear layer 會成為 AWQ W4A16 目標;其餘維持稠密格式。
python examples/text_to_image/quantize_hf.py black-forest-labs/FLUX.2-klein-4B \
--precision int4 --rank 32 --inspect-config
量化前務必先閲讀此報告。對 FLUX.2 Klein 4B 而言,預期結果是 100 個 SVDQ 目標、3 個 AWQ 目標,以及 6 個外圍稠密 linear layer,不會遺漏任何模式,也不會出現重複名稱。
2. 執行量化
以下命令會對 Transformer 執行 SVDQuant,並將量化後的 checkpoint 寫入 outputs/checkpoints/svdq-int4_r32-flux-2-klein-4b.safetensors:
python examples/text_to_image/quantize_hf.py black-forest-labs/FLUX.2-klein-4B \
--precision int4 \
--output outputs/checkpoints/svdq-int4_r32-flux-2-klein-4b.safetensors
將 --precision int4 換成 nvfp4,即可建立原生 Blackwell 權重。
3. 封裝 Diffusers pipeline
轉換器會將量化 Transformer 與基礎 pipeline 的其他元件合併,把精簡的 nunchaku_lite 設定寫入 transformer/config.json,並可選擇將文本編碼器轉成 NF4:
python examples/convert_nunchaku_lite_diffusers.py \
--checkpoint outputs/checkpoints/svdq-int4_r32-flux-2-klein-4b.safetensors \
--model-id black-forest-labs/FLUX.2-klein-4B \
--bnb4-text-encoder text_encoder \
--compute-dtype bfloat16 \
--output-dir outputs/diffusers/FLUX.2-klein-4B-nunchaku-lite-int4-bnb4-text-encoder
4. 載入、驗證並推送至 Hub
import torch
from diffusers import DiffusionPipeline
pipe = DiffusionPipeline.from_pretrained(
"outputs/diffusers/FLUX.2-klein-4B-nunchaku-lite-int4-bnb4-text-encoder",
device_map="cuda",
)
image = pipe(
"A glass robot in a greenhouse, cinematic lighting",
num_inference_steps=4, guidance_scale=1.0,
generator=torch.Generator("cuda").manual_seed(12345),
).images[0]
確認輸出效果理想後,執行 pipe.push_to_hub("your-name/your-model-nunchaku-lite-int4")。其他用戶便可使用上文所示的相同 from_pretrained() 用法載入模型。
以結構重寫方式量化模型
請注意,通用流程假設架構無須結構重寫即可量化。為進一步加速,原有 Nunchaku 引擎會將多組 Diffusers 層改寫為融合模組。通用流程無法自行推斷這些改動,例如把分開的 Q、K 和 V 投影合併到同一模組,或將融合投影拆分到多個模組。
FLUX.1-dev 的 QKV 投影是一個具體例子。Diffusers 將它定義為三個獨立模組:
self.to_q = torch.nn.Linear(query_dim, self.inner_dim, bias=bias)
self.to_k = torch.nn.Linear(query_dim, self.inner_dim, bias=bias)
self.to_v = torch.nn.Linear(query_dim, self.inner_dim, bias=bias)
Nunchaku FLUX 模組將這些層合併為單一量化的 to_qkv 模組:
to_qkv = fuse_linears([other.to_q, other.to_k, other.to_v])
self.to_qkv = SVDQW4A4Linear.from_linear(to_qkv, **kwargs)
這個分組模組是必需的,因為 Nunchaku 的融合運算子會一併處理 QKV 投影、Q/K 正規化和旋轉位置嵌入。相比之下,Diffusers 預設流程會分開執行:
query = attn.to_q(hidden_states)
key = attn.to_k(hidden_states)
value = attn.to_v(hidden_states)
query = query.unflatten(-1, (attn.heads, -1))
key = key.unflatten(-1, (attn.heads, -1))
value = value.unflatten(-1, (attn.heads, -1))
query = attn.norm_q(query)
key = attn.norm_k(key)
if image_rotary_emb is not None:
query = apply_rotary_emb(query, image_rotary_emb, sequence_dim=1)
key = apply_rotary_emb(key, image_rotary_emb, sequence_dim=1)
Nunchaku 流程會把分組投影、正規化模組和旋轉位置嵌入交給單一融合運算子:
qkv = fused_qkv_norm_rottary(
hidden_states, attn.to_qkv, attn.norm_q, attn.norm_k, image_rotary_emb
)
這就是通用流程無法推斷的結構重寫。Diffusers 有三個目標模組,參數前綴分別是 to_q、to_k 和 to_v;Nunchaku 則只有一個位於 to_qkv 下的分組模組。模型專用的目標設定或 adapter 必須指定,Q、K 和 V 參數應按此順序沿輸出維度串接,再載入 to_qkv。
這類結構重寫會在量化時由模型專用目標設定描述,載入 checkpoint 時則交由小型 runtime adapter 處理。FLUX.2 Klein 4B 量化指令碼提供了產生結構重寫 checkpoint 的目標設定範例;rootonchair/nunchaku-lite則提供載入分組 QKV 張量、拆分融合投影及其他融合運算所需的 runtime adapter。想了解完整流程,請參閲新增模型指南。
可直接使用的 checkpoint
如要立即開始,請查看以下儲存庫:
- rootonchair/ERNIE-Image-Turbo-nunchaku-lite-int4-bnb4-text-encoder:INT4 ERNIE-Image-Turbo,搭配 bitsandbytes NF4 文本編碼器
- rootonchair/ERNIE-Image-Turbo-nunchaku-lite-nvfp4-bnb4-text-encoder:NVFP4 ERNIE-Image-Turbo,搭配 bitsandbytes NF4 文本編碼器
- OzzyGT/Krea_2_Turbo_nunchaku_lite_nvfp4:NVFP4 Krea 2 Turbo checkpoint
- lite-infer:更多 Nunchaku Lite checkpoint 和合集
總結
Nunchaku 的 SVDQuant kernel 是在消費級硬件上高效執行擴散 Transformer 的最有效方法之一,現在已在 Diffusers 原生支援。預先量化的 checkpoint 可透過 from_pretrained() 載入,而 diffuse-compressor 工具組讓用戶無須等待引擎支援,便可量化新架構。W4A4 路徑同時量化權重和啟動值,在降低記憶體用量、改善去噪延遲的同時,令圖像品質接近原本的 BF16。
如果你量化並發布了新模型,我們很樂意知道詳情。歡迎分享到 Hub 並告訴我們!如對此功能有任何疑問,歡迎加入我們的 Discord。
如想了解更多,請參閲以下資源:
- Diffusers Nunchaku 文件
- 整合 PR(huggingface/diffusers#14100)
- SVDQuant 論文及 Nunchaku 引擎
- diffuse-compressor
- 過往文章:探索 Diffusers 的量化後端及使用 Quanto 和 Diffusers 打造高記憶體效率的擴散 Transformer
鳴謝
感謝 Diffusers 維護者在整合過程中審閲內容並提供指引,亦感謝 MIT HAN Lab/Nunchaku 團隊完成原始 SVDQuant 工作。感謝 Marc Sun 為本文提供意見,也感謝 Álvaro Somoza 試用 nunchaku-lite 並提供回饋。
rootonchair 亦感謝 SilverAI 支持這項工作,並提供進行大部分開發工作的環境。
來源:Hugging Face Blog · huggingface.co