# Nunchaku Lite

Nunchaku Lite는 Diffusers에서 사전 양자화 체크포인트를 로드하기 위한 양자화 백엔드입니다. [diffuse-compressor](https://github.com/rootonchair/diffuse-compressor)를 사용하여 호환되는 체크포인트를 생성합니다. 이 도구는 transformer를 양자화하고 내보낸 후, 이를 Diffusers 파이프라인으로 패키징합니다.

Nunchaku Lite는 원래의 [Nunchaku](https://github.com/nunchaku-ai/nunchaku) 추론 엔진, [DeepCompressor](https://github.com/nunchaku-ai/deepcompressor) 양자화 라이브러리, [SVDQuant 논문](https://arxiv.org/abs/2411.05007)을 기반으로 구축되었습니다.

## CUDA 커널 설치

kernels 패키지는 최적화된 CUDA 커널을 제공하며, 자동으로 로드됩니다. 먼저 설치하세요.

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

Nunchaku Lite는 [`rootonchair/nunchaku-lite-kernels`](https://huggingface.co/rootonchair/nunchaku-lite-kernels) 저장소에서 커널을 로드합니다. 해당 저장소의 게시자는 Hub에서 신뢰할 수 있는 커널 게시자가 아닙니다. 이를 로드하면 Hub에서 코드를 다운로드하여 실행하므로, Diffusers는 `DIFFUSERS_TRUST_REMOTE_KERNELS=true`를 설정하여 명시적으로 동의하도록 요구합니다. 자세한 내용은 [원격 커널 신뢰](../optimization/attention_backends#trusting-remote-kernels)를 참조하세요.

## 양자화 파이프라인 로드

`config.json`에서 양자화 설정을 읽는 [from_pretrained()](/docs/diffusers/main/ko/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained)로 사전 양자화 파이프라인을 로드합니다.

```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]
> 내보낸 state dict는 대상 Diffusers 모델 아키텍처와 정확히 일치해야 합니다. 예를 들어, fused QKV projections으로 양자화된 체크포인트는 개별 Q, K, V projection 모듈을 기대하는 모델 구성에 로드되지 않습니다.

## 지원되는 양자화 유형

Nunchaku Lite는 다음 양자화 선형 레이어 형식을 지원합니다.

> [!TIP]
> Blackwell GPU에서 `nvfp4`를 사용하세요. Blackwell에서 `int4` 체크포인트를 실행하면 `nvfp4`보다 느릴 수 있습니다.

CUDA 커널은 현재 다음 NVIDIA GPU 아키텍처를 지원합니다:

- `sm_75` (예: RTX 2080을 위한 Turing)
- `sm_80` (예: A100을 위한 Ampere)
- `sm_86` (Ampere, 예: RTX 3090 및 RTX A6000)
- `sm_89` (예: RTX 4090의 Ada)
- `sm_120` (예: RTX 5090 Blackwell)

> [!NOTE]
> H100, H200와 같은 `sm_90` Hopper GPU는 현재 지원되지 않습니다.

`nvfp4` 체크포인트는 Blackwell 또는 그 이상의 NVIDIA GPU가 필요합니다. Blackwell GPU를 사용하는 경우 PyTorch >= 2.7과 CUDA >= 12.8을 사용하세요. `int4` 체크포인트는 Turing 또는 그 이상의 NVIDIA GPU가 필요합니다.

| 메서드 | 정밀도 | 그룹 크기 | The input is a single word "Notes".

참고 |
|---|---:|---:|---|
| `svdq_w4a4` | `nvfp4` | 16 | SVDQ 저순위 보정을 사용하는 NVFP4 런타임 커널을 사용합니다. |
| `svdq_w4a4` | `int4` | 64 | SVDQ 저순위 보정을 사용하는 INT4 W4A4 커널을 사용합니다. |
| `awq_w4a16` | `int4` | 64 | INT4 weight-only AWQ 스타일 커널을 사용합니다. |

## NunchakuLiteQuantizationConfig

`config.json` 파일에는 [NunchakuLiteQuantizationConfig](/docs/diffusers/main/ko/api/quantization#diffusers.NunchakuLiteQuantizationConfig)가 포함되어야 합니다. 이는 런타임 `compute_dtype`와 각 Nunchaku Lite 양자화 방식에 대한 대상 모듈을 정의합니다.

- `compute_dtype`: 양자화 모듈의 부동 소수점 버퍼에 사용되는 런타임 dtype으로, 일반적으로 `torch.bfloat16`입니다.
- `svdq_w4a4`: `precision`, `group_size`, `rank`, `targets`를 포함한 SVDQ W4A4 대상 구성입니다.
- `awq_w4a16`: `precision`, `group_size`, `targets`를 포함한 AWQ W4A16 대상 구성입니다.

`targets`의 각 항목은 선형 레이어를 가리켜야 합니다. Diffusers는 각 `svdq_w4a4` 타깃을 SVDQ W4A4 레이어로, 각 `awq_w4a16` 타깃을 AWQ W4A16 레이어로 교체합니다. 아래 예시는 줄인 타깃 목록과 함께 예상되는 형태를 보여줍니다.

`svdq_w4a4` 또는 `awq_w4a16` 아래에 양자화하려는 각 모듈을 나열하세요. 모듈은 하나의 방법만 사용할 수 있으므로, 동일한 대상 모듈을 두 곳 모두에 나열하지 마세요.

```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"]
    }
  }
}
```

## Fused 커널

원본 [Nunchaku](https://github.com/nunchaku-ai/nunchaku) 엔진은 모델별 융합 실행 경로에서 상당한 속도를 얻습니다. Q, K, V 투영을 RMSNorm과 RoPE와 결합하고, MLP에는 융합된 GELU 커널을 사용합니다. 반면 Nunchaku Lite는 표준 Diffusers 모델과 범용 양자화 선형 레이어를 사용하므로 이러한 융합을 포함하지 않습니다.

다음 측정값은 Flux Schnell을 RTX 5090에서 사용하여 원래 Nunchaku 엔진에서 이러한 융합의 단계별 지연 시간 영향을 측정한 결과입니다.

| 최적화 | OFF 상태의 지연 시간 | ON 상태에서의 지연 시간 | 속도 향상 |
| --- | --- | --- | --- |
| QKV+norm+RoPE 융합(통합) | 1.057 s | 0.834 s | **1.27×** |
| — Q/K/V를 하나의 matmul로 그룹화, 단독으로 | 1.059 s | 1.034 s | 1.025× |
| — 그룹핑 위에 RMSNorm+RoPE 에필로그 퓨전 | 1.034 s | 0.836 s | 1.236× |
| GELU-MLP 융합 | 0.766 s | 0.722 s | **1.06×** |

이러한 퓨전이 없으면 GPU는 projection, normalization, rotary-embedding, MLP 연산을 개별 커널로 실행하여 런치 오버헤드가 발생합니다. `torch.compile`은 이러한 오버헤드를 일부 줄일 수 있지만, 원래 엔진의 퓨전 커널을 반드시 재현하지는 않습니다. 해당 모델과 워크로드에 대해 컴파일된 파이프라인의 벤치마크를 실행해 보세요.

## torch.compile

Nunchaku Lite 커널과 양자화 선형 레이어는 [`torch.compile`](../optimization/fp16#torchcompile)과 호환됩니다. 파이프라인을 로드한 후 양자화된 트랜스포머를 컴파일하여 추론 속도를 높일 수 있습니다.

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

컴파일된 Nunchaku Lite NVFP4 파이프라인은 원래의 BF16 파이프라인보다 1.8배 빠릅니다(RTX PRO 6000에서 2.271초 → 1.675초).

## 리소스

- [diffuse-compressor](https://github.com/rootonchair/diffuse-compressor)
- [Nunchaku 설치 요구 사항](https://nunchaku.tech/docs/nunchaku/installation/installation.html)