diffusers/main/tr/quantization/nunchaku.md

Nunchaku Lite

Nunchaku Lite, Diffusers'ta önceden kantize edilmiş checkpoint'leri yüklemek için kullanılan bir kantizasyon arka ucudur. Uygun checkpoint'leri diffuse-compressor ile oluşturun. Bir transformer'ı kantize eder ve dışa aktarır, ardından onu bir Diffusers pipeline'ı olarak paketler.

Nunchaku Lite, orijinal Nunchaku çıkarım motoru, DeepCompressor kuantizasyon kütüphanesi ve SVDQuant makalesi üzerine inşa edilmiştir.

CUDA çekirdeklerini yükleyin

kernels paketi, otomatik olarak yüklenen optimize edilmiş CUDA çekirdeklerini sağlar. Önce bunu yükleyin.

pip install -U kernels

Nunchaku Lite, çekirdeklerini rootonchair/nunchaku-lite-kernels deposundan yükler; bu deponun yayıncısı Hub'da güvenilir bir çekirdek yayıncısı değildir. Bu bileşeni yüklemek, Hub'dan kod indirmesini ve çalıştırmasını gerektirdiğinden Diffusers, DIFFUSERS_TRUST_REMOTE_KERNELS=true değerini belirleyerek açıkça onay vermenizi ister. Ayrıntılar için Uzak çekirdekleri güvenme bölümüne bakın.

Kantize edilmiş bir pipeline yükleyin

Önkuantize edilmiş hattı, config.json dosyasından kuantizasyon yapılandırmasını okuyan from_pretrained() ile yükleyin.

import torch
from diffusers import DiffusionPipeline

model_id = "rootonchair/ERNIE-Image-Turbo-nunchaku-lite-nvfp4"

pipe = DiffusionPipeline.from_pretrained(
    model_id, dtype=torch.bfloat16,
).to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A modern red armchair in a quiet studio, soft window light, realistic product photography"
image = pipe(
    prompt=prompt,
    height=1024,
    width=1024,
    num_inference_steps=8,
    guidance_scale=1.0,
).images[0]
image.save("ernie-image-turbo-nunchaku-lite.png")

Dışa aktarılan state dict, hedef Diffusers model mimarisiyle tam olarak eşleşmelidir. Örneğin, birleştirilmiş QKV projeksiyonlarıyla kuantize edilmiş bir checkpoint, ayrı Q, K ve V projeksiyon modülleri bekleyen bir model yapılandırmasına yüklenemez.

Desteklenen kuantizasyon türleri

Nunchaku Lite aşağıdaki quantize edilmiş lineer katman formatlarını destekler.

Blackwell GPU'larında nvfp4 kullanın. Blackwell üzerinde int4 kontrol noktalarını çalıştırmak, nvfp4'e kıyasla daha yavaş olabilir.

CUDA çekirdekleri şu anda aşağıdaki NVIDIA GPU mimarilerini desteklemektedir:

• sm_75 (örneğin RTX 2080 için Turing)
• sm_80 (örneğin A100 için Ampere)
• sm_86 (örneğin Ampere, RTX 3090 ve RTX A6000)
• sm_89 (örneğin Ada, RTX 4090)
• sm_120 (örneğin RTX 5090 için Blackwell)

sm_90 H100 ve H200 gibi Hopper GPU'ları şu anda desteklenmemektedir.

nvfp4 checkpoint'ları Blackwell veya daha yeni bir NVIDIA GPU gerektirir. Blackwell GPU'larda CUDA >= 12.8 ile PyTorch >= 2.7 kullanın. int4 checkpoint'ları Turing veya daha yeni bir NVIDIA GPU gerektirir.

Yöntem	Hassasiyet	Grup boyutu	Notlar
svdq_w4a4	nvfp4	16	SVDQ düşük rütbeli düzeltme ile NVFP4 çalışma zamanı çekirdeklerini kullanır.
svdq_w4a4	int4	64	SVDQ düşük ranlı düzeltme ile INT4 W4A4 çekirdeklerini kullanır.
awq_w4a16	int4	64	INT4 ağırlık-özel AWQ tarzı çekirdekler kullanır.

NunchakuLiteQuantizationConfig

config.json dosyası bir NunchakuLiteQuantizationConfig içermelidir. Bu yapı, çalışma zamanı compute_dtype değerini ve her Nunchaku Lite kuantizasyon yöntemi için hedef modülleri tanımlar.

• compute_dtype: kuantize modüllerdeki kayan noktalı tamponlar için çalışma zamanı veri türü, genellikle torch.bfloat16.
• svdq_w4a4: precision, group_size, rank ve targets içeren SVDQ W4A4 hedef yapılandırması.
• awq_w4a16: precision, group_size ve targets içeren AWQ W4A16 hedef yapılandırması.

targets içindeki her giriş bir lineer katmana işaret etmelidir. Diffusers, her svdq_w4a4 hedefini bir SVDQ W4A4 katmanı ile, her awq_w4a16 hedefini ise bir AWQ W4A16 katmanı ile değiştirir. Aşağıdaki örnek, kısaltılmış hedef listeleriyle beklenen şekli göstermektedir.

Kantize etmek istediğiniz her modülü svdq_w4a4 veya awq_w4a16 altında listeleyin. Bir modül yalnızca bir yöntem kullanabilir, bu nedenle aynı hedefi her ikisinin altında da listelemeyin.

{
  "_class_name": "ErnieImageTransformer2DModel",
  "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"]
    },
    "awq_w4a16": {
      "precision": "int4",
      "group_size": 64,
      "targets": ["final_linear"]
    }
  }
}

Birleştirilmiş çekirdekler

Orijinal Nunchaku motoru, hızının büyük kısmını modele özgü birleşik (fused) yürütme yollarından alır. Q, K ve V projeksiyonlarını RMSNorm ve RoPE ile birleştirir ve MLP için birleşik bir GELU çekirdeği kullanır. Nunchaku Lite ise standart Diffusers modelini genel amaçlı nicelenmiş doğrusal katmanlarla kullanır, bu nedenle bu birleştirmeleri içermez.

Aşağıdaki ölçümler, bu füzyonların orijinal Nunchaku motorundaki adım başına gecikme etkisini, RTX 5090 üzerinde Flux Schnell ile ölçülmüş olarak göstermektedir.

Optimizasyon	Kapalıyken gecikme	Açıkken gecikme	Hızlanma
QKV+norm+RoPE füzyonu (birleşik)	1.057 s	0.834 s	1.27×
— Q/K/V'yi tek bir matmul'da birleştirme, yalnızca	1.059 s	1.034 s	1.025×
— Gruplama üzerine RMSNorm+RoPE epilog füzyonu	1.034 s	0.836 s	1.236×
GELU-MLP birleştirme	0.766 s	0.722 s	1.06×

Bu füzyonlar olmadan GPU, projeksiyon, normalizasyon, döner gömme ve MLP işlemlerini ayrı çekirdekler olarak başlatır; bu da başlatma maliyeti ekler. torch.compile bu maliyetin bir kısmını azaltabilir, ancak orijinal motorun füzyonlu çekirdeklerini zorunlu olarak yeniden üretmeyebilir. Derlenmiş hattı modeliniz ve iş yükünüz için ölçün.

torch.compile

Nunchaku Lite çekirdekleri ve kuantize doğrusal katmanlar torch.compile ile uyumludur. Daha hızlı çıkarım için kuantize edilmiş dönüştürücüyü, hattı yükledikten sonra derleyin.

pipe.transformer = torch.compile(pipe.transformer, mode="default", fullgraph=True)

Derlenmiş Nunchaku Lite NVFP4 hattı, orijinal BF16 hattından 1.8 kat daha hızlı çalışır (RTX PRO 6000 üzerinde 2.271s → 1.675s).

Kaynaklar

• diffuse-compressor
• Nunchaku kurulum gereksinimleri