# Nunchaku Lite

Nunchaku Lite es un backend de cuantización para cargar puntos de control precuantizados en Diffusers. Crea puntos de control compatibles con [diffuse-compressor](https://github.com/rootonchair/diffuse-compressor). Cuantiza y exporta un transformer y luego lo empaqueta como un pipeline de Diffusers.

Nunchaku Lite se basa en el motor de inferencia original [Nunchaku](https://github.com/nunchaku-ai/nunchaku), la biblioteca de cuantización [DeepCompressor](https://github.com/nunchaku-ai/deepcompressor) y el artículo [SVDQuant](https://arxiv.org/abs/2411.05007).

## Instalar los núcleos de CUDA

El paquete kernels proporciona los kernels de CUDA optimizados, que se cargan automáticamente. Instálalo primero.

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

Nunchaku Lite carga sus kernels desde el repositorio [`rootonchair/nunchaku-lite-kernels`](https://huggingface.co/rootonchair/nunchaku-lite-kernels), cuyo editor no es un editor de kernels de confianza en el Hub. Al cargarlo, se descarga y ejecuta código desde el Hub, por lo que Diffusers requiere que aceptes explícitamente esta acción estableciendo `DIFFUSERS_TRUST_REMOTE_KERNELS=true`. Consulta [Confianza en kernels remotos](../optimization/attention_backends#trusting-remote-kernels) para más detalles.

## Cargar un pipeline cuantizado

Cargue el pipeline precuantizado con [from_pretrained()](/docs/diffusers/v0.43.0/es/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained), que lee la configuración de cuantización desde `config.json`.

```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]
> El state dict exportado debe coincidir exactamente con la arquitectura del modelo Diffusers de destino. Por ejemplo, un checkpoint cuantizado con proyecciones QKV fusionadas no se cargará en una configuración de modelo que espere módulos de proyección Q, K y V separados.

## Tipos de cuantización admitidos

Nunchaku Lite admite los siguientes formatos de capas lineales cuantizadas.

> [!TIP]
> Use `nvfp4` en GPUs Blackwell. Ejecutar puntos de control `int4` en Blackwell puede ser más lento que `nvfp4`.

Los núcleos de CUDA actualmente admiten las siguientes arquitecturas de GPU de NVIDIA:

- `sm_75` (Turing, por ejemplo RTX 2080)
- `sm_80` (Ampere, por ejemplo A100)
- `sm_86` (Ampere, por ejemplo RTX 3090 y RTX A6000)
- `sm_89` (Ada, por ejemplo RTX 4090)
- `sm_120` (Blackwell, por ejemplo, RTX 5090)

> [!NOTE]
> Las GPU Hopper, como `sm_90` H100 y H200, no están soportadas actualmente.

Los puntos de control `nvfp4` requieren una GPU NVIDIA Blackwell o más reciente. En las GPUs Blackwell, use PyTorch >= 2.7 con CUDA >= 12.8. Los puntos de control `int4` requieren una GPU NVIDIA Turing o más reciente.

| Método | Precisión | Tamaño del grupo | Notas |
|---|---:|---:|---|
| `svdq_w4a4` | `nvfp4` | 16 | Utiliza kernels de tiempo de ejecución NVFP4 con corrección de bajo rango SVDQ. |
| `svdq_w4a4` | `int4` | 64 | Utiliza núcleos INT4 W4A4 con corrección de bajo rango SVDQ. |
| `awq_w4a16` | `int4` | 64 | Utiliza núcleos de solo pesos INT4 de estilo AWQ. |

## NunchakuLiteQuantizationConfig

El archivo `config.json` debe incluir una [NunchakuLiteQuantizationConfig](/docs/diffusers/v0.43.0/es/api/quantization#diffusers.NunchakuLiteQuantizationConfig). Define el `compute_dtype` de tiempo de ejecución y los módulos objetivo para cada método de cuantización de Nunchaku Lite.

- `compute_dtype`: dtype de ejecución para los búferes de punto flotante en los módulos cuantizados, típicamente `torch.bfloat16`.
- `svdq_w4a4`: configuración objetivo SVDQ W4A4 con `precision`, `group_size`, `rank` y `targets`.
- `awq_w4a16`: configuración objetivo AWQ W4A16 con `precision`, `group_size` y `targets`.

Cada entrada en `targets` debe apuntar a una capa lineal. Diffusers reemplaza cada destino `svdq_w4a4` por una capa SVDQ W4A4 y cada destino `awq_w4a16` por una capa AWQ W4A16. El ejemplo siguiente muestra la forma esperada con listas de destinos abreviadas.

Liste cada módulo que desea cuantizar bajo `svdq_w4a4` o `awq_w4a16`. Un módulo solo puede usar un método, por lo que no liste el mismo destino bajo ambos.

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

## Kernels fusionados

El motor original [Nunchaku](https://github.com/nunchaku-ai/nunchaku) obtiene gran parte de su velocidad de las rutas de ejecución fusionadas específicas del modelo. Combina las proyecciones Q, K y V con RMSNorm y RoPE, y utiliza un kernel GELU fusionado para el MLP. Nunchaku Lite, en cambio, utiliza el modelo estándar de Diffusers con capas lineales cuantizadas genéricas, por lo que no incluye estas fusiones.

Las siguientes mediciones muestran el impacto en la latencia por paso de estas fusiones en el motor original de Nunchaku, medido con Flux Schnell en una RTX 5090.

| Optimización | Latencia con él DESACTIVADO | Latencia con él ACTIVADO | Aceleración |
| --- | --- | --- | --- |
| Fusión QKV+norm+RoPE (combinada) | 1.057 s | 0.834 s | **1.27×** |
| — agrupar Q/K/V en una sola matmul, por separado | 1.059 s | 1.034 s | 1.025× |
| — Fusión del epílogo de RMSNorm+RoPE, además del agrupamiento | 1.034 s | 0.836 s | 1.236× |
| Fusión GELU-MLP | 0.766 s | 0.722 s | **1.06×** |

Sin estas fusiones, la GPU lanza las operaciones de proyección, normalización, incrustación rotacional y MLP como núcleos separados, lo que añade una sobrecarga de lanzamiento. `torch.compile` puede reducir parte de esta sobrecarga, aunque no necesariamente reproduce los núcleos fusionados del motor original. Realice una prueba de rendimiento del pipeline compilado para su modelo y carga de trabajo.

## torch.compile

Los kernels de Nunchaku Lite y las capas lineales cuantizadas son compatibles con [`torch.compile`](../optimization/fp16#torchcompile). Compila el transformer cuantizado después de cargar el pipeline para una inferencia más rápida.

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

El pipeline compilado de Nunchaku Lite NVFP4 se ejecuta 1,8 veces más rápido que el pipeline original BF16 (2,271 s → 1,675 s en una RTX PRO 6000).

## Recursos

- [diffuse-compressor](https://github.com/rootonchair/diffuse-compressor)
- [Requisitos de instalación de Nunchaku](https://nunchaku.tech/docs/nunchaku/installation/installation.html)