跳到正文
Hugging Face Blog·· 2026-07-23精選AI 評分61

Diffusers 原生支援 Nunchaku Lite 4-bit 擴散模型推理

Bringing Nunchaku 4-bit Diffusion Inference to Diffusers

AI 導讀

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 image quality and performance comparison

目錄

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")
BF16 and Nunchaku Lite outputs for a red fox prompt

無須自訂 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 kernel fusion: the low-rank down projection is fused with input quantization, and the low-rank up projection is fused with the 4-bit matmul
Nunchaku 將低秩下投影與量化 kernel 融合,再把低秩上投影與 4-bit 運算 kernel 融合,消除 16-bit 分支的記憶體存取開銷。圖片取自 SVDQuant 論文。

介紹 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 啟動值,用於自適應正規化和調制投影,例如 FLUX adanorm_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 倍。

圖像品質

Quality comparison grid
相同 seed 和設定下的 BF16 與 4-bit 輸出。

量化自己的模型

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

如要立即開始,請查看以下儲存庫:

總結

Nunchaku 的 SVDQuant kernel 是在消費級硬件上高效執行擴散 Transformer 的最有效方法之一,現在已在 Diffusers 原生支援。預先量化的 checkpoint 可透過 from_pretrained() 載入,而 diffuse-compressor 工具組讓用戶無須等待引擎支援,便可量化新架構。W4A4 路徑同時量化權重和啟動值,在降低記憶體用量、改善去噪延遲的同時,令圖像品質接近原本的 BF16。

如果你量化並發布了新模型,我們很樂意知道詳情。歡迎分享到 Hub 並告訴我們!如對此功能有任何疑問,歡迎加入我們的 Discord。

如想了解更多,請參閲以下資源:

鳴謝

感謝 Diffusers 維護者在整合過程中審閲內容並提供指引,亦感謝 MIT HAN Lab/Nunchaku 團隊完成原始 SVDQuant 工作。感謝 Marc Sun 為本文提供意見,也感謝 Álvaro Somoza 試用 nunchaku-lite 並提供回饋。

rootonchair 亦感謝 SilverAI 支持這項工作,並提供進行大部分開發工作的環境。

來源:Hugging Face Blog · huggingface.co