Cómo instalar y ejecutar Z-Image-Turbo localmente (Python, Diffusers y modo bajo VRAM)

Esta guía explica paso a paso cómo instalar y ejecutar Z-Image-Turbo (Tongyi-MAI/Z-Image-Turbo) en tu propio equipo con Linux, Windows o macOS. Basado en la arquitectura S3-DiT (Scalable Single-Stream Diffusion Transformer) de 6.000 millones de parámetros, Z-Image-Turbo genera fotografías hiperrealistas en 1024×1024 y tipografía nítida en tan solo 8 NFEs (num_inference_steps=9, guidance_scale=0.0).

¿No tienes una GPU con 16 GB de VRAM? Ahorra más de 12 GB de descarga y evita configurar CUDA: inicia sesión en el espacio online de Z-Image o prueba directamente Z-Image-Turbo en la nube con tus créditos gratuitos de bienvenida.

Requisitos de hardware y software

Para ejecutar el pipeline nativo en precisión bfloat16 con fluidez, recomendamos:

• GPU recomendada: tarjeta gráfica NVIDIA con 16 GB de VRAM o más (RTX 4080, RTX 4090, RTX 3090, RTX 4060 Ti 16 GB, A10G o H100).
• GPUs de 8 GB a 12 GB de VRAM: compatibles activando enable_model_cpu_offload() (descarga en RAM) o usando pesos cuantizados FP8 / GGUF en ComfyUI, con mayor tiempo por imagen.
• Memoria y almacenamiento: al menos 24 GB de RAM del sistema y unos 20 GB libres en SSD.
• Software: Python 3.10 o superior y controladores NVIDIA con CUDA 12.1+.

1. Crear un entorno virtual de Python

Aísla las dependencias del proyecto para evitar conflictos con otras instalaciones de PyTorch o Diffusers. Abre tu terminal y crea el entorno zimage-env:

python -m venv zimage-env

Activa el entorno virtual:

# En Linux o macOS
source zimage-env/bin/activate

# En Windows (CMD o PowerShell)
zimage-env\Scripts\activate

2. Instalar PyTorch y Hugging Face Diffusers

Instala PyTorch compilado para tu versión de CUDA (el comando inferior apunta a CUDA 12.4; ajusta --index-url si utilizas CUDA 12.1 o 12.6). Como ZImagePipeline requiere soporte actualizado para S3-DiT, instala diffusers directamente desde su repositorio oficial en GitHub junto con transformers, accelerate y 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. Cargar el pipeline Z-Image-Turbo

Crea un script en Python (por ejemplo, run_zimage.py) y carga Tongyi-MAI/Z-Image-Turbo desde Hugging Face en precisión torch.bfloat16:

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. Generar una imagen 1024×1024 (8 NFEs)

Gracias a la destilación de pasos Decoupled-DMD, Z-Image-Turbo utiliza dos ajustes clave distintos a los modelos de difusión tradicionales:

• Configura num_inference_steps=9 (equivalente a 8 evaluaciones hacia delante del DiT / NFEs).
• Mantén guidance_scale=0.0 (el guiado ya está integrado en el modelo destilado y no requiere CFG adicional).

prompt = (
    "Night street photography in Madrid after rain, warm neon bakery sign clearly reading "
    "'CAFÉ NOCTURNO', realistic reflections on wet cobblestones, 35mm lens f/1.4"
)

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. Optimización de rendimiento (Flash Attention y compilación)

En GPUs NVIDIA compatibles (series RTX 30/40, A100, H100), puedes reducir aún más la latencia activando Flash Attention 2 y compilando el transformador:

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

# Opcional: compilar el módulo S3-DiT para acelerar lotes sucesivos
# pipe.transformer.compile()

6. Modo de bajo VRAM (GPUs de 8 GB a 12 GB)

Si recibes errores CUDA out of memory en tarjetas de 8 GB o 12 GB, sustituye pipe.to("cuda") por enable_model_cpu_offload() para mover dinámicamente a la memoria RAM los submódulos inactivos:

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 o generación directa en el navegador

• Si necesitas entrenar LoRAs propios, usar ControlNet o aplicar guiado CFG completo, consulta nuestro modelo fundacional en Z-Image-Base.
• Si prefieres empezar al instante sin instalar nada localmente, abre Z-Image-Turbo Online.