Z-Image-Turbo lokal installieren & ausführen (Python, Diffusers & Low-VRAM-Guide)

Diese Anleitung zeigt Schritt für Schritt, wie Sie Z-Image-Turbo (Tongyi-MAI/Z-Image-Turbo) lokal unter Linux, Windows oder macOS einrichten. Das auf der 6-Milliarden-Parameter S3-DiT-Architektur (Scalable Single-Stream Diffusion Transformer) basierende Open-Source-Modell erzeugt fotorealistische 1024×1024-Bilder und präzise Typografie in nur 8 NFEs (num_inference_steps=9, guidance_scale=0.0).

Keine GPU mit 16 GB VRAM vorhanden? Sparen Sie sich den mehr als 12 GB großen Modell-Download: Melden Sie sich im Z-Image Cloud-Workspace oder direkt auf der Z-Image-Turbo Modellseite an, um kostenlose Starter-Credits auf unseren Cloud-GPUs zu nutzen.

Hardware- und Software-Voraussetzungen

Für die native Ausführung in bfloat16-Präzision empfehlen wir folgende Systemkonfiguration:

• Empfohlene Grafikkarte (GPU): NVIDIA-GPU mit mindestens 16 GB VRAM (z. B. RTX 4080, RTX 4090, RTX 3090, RTX 4060 Ti 16 GB, A10G oder H100).
• GPUs mit 8 GB – 12 GB VRAM: Ausführung über sequenzielles CPU-Offloading (enable_model_cpu_offload()) oder quantisierte FP8-/GGUF-Gewichte in ComfyUI möglich (mit entsprechend längerer Generierungszeit).
• Arbeitsspeicher & Speicherplatz: Mindestens 24 GB System-RAM und ca. 20 GB freier SSD-Speicherplatz.
• Software: Python 3.10+ sowie eine funktionierende NVIDIA-CUDA-Installation (CUDA 12.1 oder neuer).

1. Virtuelle Python-Umgebung erstellen

Isolieren Sie die Paketabhängigkeiten in einer eigenen virtuellen Umgebung, um Konflikte mit bestehenden Python- oder PyTorch-Projekten zu vermeiden. Öffnen Sie Ihr Terminal und erstellen Sie zimage-env:

python -m venv zimage-env

Aktivieren Sie anschließend die Umgebung:

# Unter Linux oder macOS
source zimage-env/bin/activate

# Unter Windows (Eingabeaufforderung / PowerShell)
zimage-env\Scripts\activate

2. PyTorch und Hugging Face Diffusers installieren

Installieren Sie PyTorch mit CUDA-Unterstützung (das Beispiel unten nutzt CUDA 12.4; passen Sie --index-url bei Bedarf an Ihre lokale CUDA-Version an). Da ZImagePipeline aktuelle S3-DiT-Unterstützung benötigt, installieren Sie diffusers direkt aus dem offiziellen GitHub-Repository sowie transformers, accelerate und safetensors:

pip install torch --index-url https://download.pytorch.org/whl/cu124
pip install git+https://github.com/huggingface/diffusers
pip install transformers accelerate safetensors

3. Z-Image-Turbo-Pipeline laden

Erstellen Sie ein Python-Skript (z. B. run_zimage.py) und laden Sie das Checkpoint Tongyi-MAI/Z-Image-Turbo in torch.bfloat16-Präzision auf Ihre CUDA-GPU:

import torch
from diffusers import ZImagePipeline

pipe = ZImagePipeline.from_pretrained(
    "Tongyi-MAI/Z-Image-Turbo",
    torch_dtype=torch.bfloat16,
    low_cpu_mem_usage=False,
)
pipe.to("cuda")

4. Bild in 1024×1024 generieren (8 NFEs)

Durch die Decoupled-DMD-Schrittdestillation unterscheidet sich die Konfiguration von klassischen Diffusionsmodellen:

• Setzen Sie num_inference_steps=9 (entspricht exakt 8 DiT-Vorwärtsdurchläufen / NFEs).
• Belassen Sie guidance_scale=0.0, da kein zusätzliches Classifier-Free Guidance (CFG) erforderlich ist.

prompt = (
    "Night street photography in Berlin after rain, illuminated cafe window sign "
    "clearly reading 'NACHTRÖSTEREI', warm tungsten glow on wet cobblestones, 35mm lens"
)

image = pipe(
    prompt=prompt,
    height=1024,
    width=1024,
    num_inference_steps=9,
    guidance_scale=0.0,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]

image.save("z_image_turbo_output.png")

5. Performance-Optimierung (Flash Attention & Torch Compile)

Auf kompatiblen NVIDIA-Architekturen (RTX 30/40-Serie, A100, H100) lässt sich der Durchsatz mit Flash Attention 2 und optionalem torch.compile() weiter steigern:

# Flash-Attention-Backend aktivieren
pipe.transformer.set_attention_backend("flash")

# Optional: S3-DiT-Transformer für schnellere Folgegenerierungen kompilieren
# pipe.transformer.compile()

6. Low-VRAM-Modus (CPU-Offloading für 8 GB – 12 GB GPUs)

Falls auf Grafikkarten mit 8 GB oder 12 GB VRAM CUDA out of memory-Fehler auftreten, ersetzen Sie pipe.to("cuda") durch enable_model_cpu_offload(), um gerade inaktive Teilmodelle dynamisch in den Arbeitsspeicher auszulagern:

import torch
from diffusers import ZImagePipeline

pipe = ZImagePipeline.from_pretrained(
    "Tongyi-MAI/Z-Image-Turbo",
    torch_dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()

Fine-Tuning oder direkte Cloud-Nutzung

• Für eigenes LoRA-Training, ControlNet-Workflows und volle CFG-Kontrolle empfehlen wir das nicht-destillierte Basismodell unter Z-Image-Base.
• Für sofortige Generierung im Browser ohne lokale Einrichtung öffnen Sie direkt Z-Image-Turbo Online.