Installer et exécuter Z-Image-Turbo en local (Python, Diffusers & faible VRAM)

Ce guide détaille l'installation et l'exécution locale de Z-Image-Turbo (Tongyi-MAI/Z-Image-Turbo) sous Linux, Windows ou macOS. Conçu autour de l'architecture S3-DiT (Scalable Single-Stream Diffusion Transformer) à 6 milliards de paramètres, ce modèle open source génère des images photoréalistes en 1024×1024 et une typographie nette en seulement 8 NFEs (num_inference_steps=9, guidance_scale=0.0).

Pas de carte graphique 16 Go de VRAM ? Évitez le téléchargement de plus de 12 Go de poids : connectez-vous à l'espace cloud Z-Image ou essayez directement Z-Image-Turbo en ligne avec vos crédits de démarrage gratuits.

Prérequis matériels et logiciels

Pour exécuter le pipeline natif en précision bfloat16 dans des conditions optimales :

• GPU recommandé : carte graphique NVIDIA dotée d'au moins 16 Go de VRAM (RTX 4080, RTX 4090, RTX 3090, RTX 4060 Ti 16 Go, A10G ou H100).
• GPU de 8 Go à 12 Go de VRAM : compatible via le délestage mémoire enable_model_cpu_offload() ou via des poids quantifiés FP8 / GGUF dans ComfyUI, avec un temps d'inférence plus long.
• Mémoire vive et stockage : 24 Go de RAM système minimum et environ 20 Go d'espace SSD libre.
• Logiciels : Python 3.10 ou supérieur et une installation fonctionnelle de NVIDIA CUDA 12.1+.

1. Créer un environnement virtuel Python

Isolez les dépendances du projet afin d'éviter tout conflit avec vos autres environnements PyTorch ou Diffusers. Ouvrez un terminal et créez l'environnement zimage-env :

python -m venv zimage-env

Activez l'environnement virtuel :

# Sous Linux ou macOS
source zimage-env/bin/activate

# Sous Windows (Invite de commandes / PowerShell)
zimage-env\Scripts\activate

2. Installer PyTorch et Hugging Face Diffusers

Installez une version de PyTorch compatible avec votre version de CUDA (la commande ci-dessous cible CUDA 12.4 ; adaptez --index-url si nécessaire). Comme la classe ZImagePipeline repose sur l'intégration récente de S3-DiT, installez diffusers depuis le dépôt GitHub officiel ainsi que transformers, accelerate et 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. Charger le pipeline Z-Image-Turbo

Créez un script Python (par exemple run_zimage.py) pour charger le modèle Tongyi-MAI/Z-Image-Turbo en précision torch.bfloat16 sur votre GPU CUDA :

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. Générer une image 1024×1024 (8 NFEs)

Grâce à la distillation Decoupled-DMD, les paramètres d'inférence diffèrent des modèles de diffusion classiques à 30 ou 50 étapes :

• Réglez num_inference_steps=9 (soit 8 évaluations S3-DiT / NFEs).
• Conservez guidance_scale=0.0 (aucun guidage CFG supplémentaire n'est requis sur le checkpoint Turbo).

prompt = (
    "Parisian corner bistro at dusk under light rain, warm brass sign clearly reading "
    "'ATELIER LUMIÈRE', reflections on wet cobblestones, natural 35mm photography"
)

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. Optimisation des performances (Flash Attention & compilation)

Sur les architectures NVIDIA récentes (séries RTX 30/40, A100, H100), l'activation de Flash Attention 2 et la compilation optionnelle du transformeur accélèrent nettement les générations en série :

# Activer le backend Flash Attention
pipe.transformer.set_attention_backend("flash")

# Optionnel : compiler le module S3-DiT après un premier passage d'initialisation
# pipe.transformer.compile()

6. Mode faible VRAM (GPU de 8 Go à 12 Go)

En cas d'erreur CUDA out of memory sur une carte graphique de 8 Go ou 12 Go, remplacez pipe.to("cuda") par enable_model_cpu_offload() afin de transférer dynamiquement les sous-modules inactifs vers la RAM système :

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 ou génération instantanée dans le cloud

• Pour l'entraînement de LoRA personnalisés, ControlNet ou le contrôle CFG complet, consultez la page du modèle fondation Z-Image-Base.
• Pour générer immédiatement dans votre navigateur sans installation locale, rendez-vous sur Z-Image-Turbo en ligne.