# 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](https://github.com/rootonchair/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](https://github.com/nunchaku-ai/nunchaku) çıkarım motoru, [DeepCompressor](https://github.com/nunchaku-ai/deepcompressor) kuantizasyon kütüphanesi ve [SVDQuant makalesi](https://arxiv.org/abs/2411.05007) ü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.

```bash
pip install -U kernels
```

Nunchaku Lite, çekirdeklerini [`rootonchair/nunchaku-lite-kernels`](https://huggingface.co/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](../optimization/attention_backends#trusting-remote-kernels) 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()](/docs/diffusers/main/tr/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) ile yükleyin.

```python
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")
```

> [!NOTE]
> 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.

> [!TIP]
> 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)

> [!NOTE]
> `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](/docs/diffusers/main/tr/api/quantization#diffusers.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.

```json
{
  "_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](https://github.com/nunchaku-ai/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`](../optimization/fp16#torchcompile) ile uyumludur. Daha hızlı çıkarım için kuantize edilmiş dönüştürücüyü, hattı yükledikten sonra derleyin.

```python
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](https://github.com/rootonchair/diffuse-compressor)
- [Nunchaku kurulum gereksinimleri](https://nunchaku.tech/docs/nunchaku/installation/installation.html)