Sana Zimage Sdxl

---
name: sana-zimage-sdxl
description: "Operate Nunchaku's non-FLUX Diffusers replacements for Sana,
  Z-Image, SDXL, and SDXL-Turbo."
metadata:
  disco-role: operating
disable-model-invocation: true
license: Apache 2.0
---

# sana-zimage-sdxl

Use this sub-skill when a task needs Nunchaku's non-FLUX image-generation replacements:

- `NunchakuSanaTransformer2DModel` with `SanaPipeline` or `SanaPAGPipeline`.
- `NunchakuZImageTransformer2DModel` with `ZImagePipeline`.
- `NunchakuSDXLUNet2DConditionModel` with `StableDiffusionXLPipeline` for SDXL or SDXL-Turbo.

Do **not** use this sub-skill for FLUX, Qwen-Image, LoRA/adapters, or performance-cache/offload tuning beyond the family-specific notes here. Do not claim CPU-only inference support: Nunchaku quantized inference requires a compatible CUDA backend even when Diffusers sequential CPU offload is used for memory placement.

## Route by family

| User intent | Use | Read next |
| --- | --- | --- |
| Sana 1.6B text-to-image | `NunchakuSanaTransformer2DModel.from_pretrained(...)` then `SanaPipeline.from_pretrained(..., transformer=...)` | `references/non-flux-models.md#sana` |
| Sana with PAG | Same Sana transformer, pass `pag_layers`, then `SanaPAGPipeline` with matching `pag_applied_layers` | `references/non-flux-models.md#sana-pag` |
| Z-Image-Turbo | `NunchakuZImageTransformer2DModel.from_pretrained(...)` then `ZImagePipeline.from_pretrained(..., transformer=...)` | `references/non-flux-models.md#z-image-turbo` |
| SDXL base | `NunchakuSDXLUNet2DConditionModel.from_pretrained(...)` then `StableDiffusionXLPipeline(..., unet=...)` | `references/non-flux-models.md#sdxl-and-sdxl-turbo` |
| SDXL-Turbo | Same SDXL UNet class with the SDXL-Turbo quantized asset and base pipeline | `references/non-flux-models.md#sdxl-and-sdxl-turbo` |
| Failure, asset, precision, or backend issue | Diagnose family/class mismatch, CUDA support, safetensors, dtype, offload, or PAG setup | `references/troubleshooting.md` |

## Safe operating workflow

1. Identify the model family first; never swap a quantized Sana/Z-Image transformer into an SDXL UNet slot or vice versa.
2. Require the caller to provide both the Diffusers base model ID/path and the Nunchaku quantized `.safetensors`/`.sft` asset path. Avoid silent repo defaults.
3. Choose dtype/device from the target GPU: `torch.bfloat16` is the normal Ampere/Ada path; Z-Image uses `torch.float16` on Turing GPUs. Sana and SDXL native candidates skip Turing and FP4 paths.
4. Construct the Diffusers pipeline by passing the Nunchaku replacement component at `from_pretrained` time, then move or offload the pipeline according to the family notes.
5. Run a bounded smoke generation only when model assets, credentials, CUDA, and output budget are explicitly available.

## Bundled template

Use `scripts/non_flux_template.py` as a parameterized starter. It supports `--family sana|zimage|sdxl`, requires explicit `--base-model` and `--quantized-path`, and fails clearly for missing local assets or unsupported family/variant combinations.

## Verification candidates

The following native tests/examples are evidence and future verification candidates only; this skill does not claim they were run:

- `examples/sana1.6b.py`, `examples/sana1.6b_pag.py`, `tests/sana/test_examples.py`
- `examples/v1/z-image-turbo.py`, `tests/v1/z_image/test_z_image_turbo.py`
- `examples/v1/sdxl.py`, `examples/v1/sdxl-turbo.py`, `tests/v1/sdxl/test_sdxl.py`