Como instalar e rodar o Z-Image-Turbo localmente (Python, Diffusers e baixo VRAM)

Este guia mostra passo a passo como instalar e executar o Z-Image-Turbo (Tongyi-MAI/Z-Image-Turbo) localmente no Windows, Linux ou macOS. Construído sobre a arquitetura S3-DiT (Scalable Single-Stream Diffusion Transformer) de 6 bilhões de parâmetros, o modelo gera imagens fotorrealistas em 1024×1024 e tipografia nítida em apenas 8 NFEs (num_inference_steps=9, guidance_scale=0.0).

Não tem uma placa de vídeo com 16 GB de VRAM? Pule o download de mais de 12 GB de pesos e a configuração de CUDA: faça login no estúdio online do Z-Image ou acesse a página do Z-Image-Turbo para usar créditos iniciais gratuitos em GPUs na nuvem.

Requisitos de hardware e software

Para rodar o pipeline nativo em precisão bfloat16 com máxima velocidade, recomendamos:

• GPU recomendada: placa NVIDIA com 16 GB de VRAM ou mais (ex.: RTX 4080, RTX 4090, RTX 3090, RTX 4060 Ti 16 GB, A10G ou H100).
• GPUs de 8 GB a 12 GB de VRAM: suportadas via enable_model_cpu_offload() (offload para RAM do sistema) ou pesos quantizados FP8 / GGUF no ComfyUI, com tempo de geração maior.
• Memória RAM e disco: mínimo de 24 GB de RAM e cerca de 20 GB livres em SSD.
• Software: Python 3.10+ e instalação ativa do NVIDIA CUDA 12.1 ou superior.

1. Criar um ambiente virtual Python

Isole as dependências do projeto para evitar conflitos com outras instalações de PyTorch ou Diffusers. Abra o terminal e crie o ambiente zimage-env:

python -m venv zimage-env

Ative o ambiente virtual:

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

# No Windows (Prompt de Comando / PowerShell)
zimage-env\Scripts\activate

2. Instalar PyTorch e Hugging Face Diffusers

Instale uma versão do PyTorch compatível com sua versão do CUDA (o comando abaixo usa CUDA 12.4; ajuste --index-url se utilizar CUDA 12.1 ou 12.6). Como a classe ZImagePipeline exige suporte recente à arquitetura S3-DiT, instale o diffusers diretamente do repositório oficial no GitHub junto com transformers, accelerate e 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. Carregar o pipeline Z-Image-Turbo

Crie um script Python (por exemplo, run_zimage.py) e carregue o checkpoint Tongyi-MAI/Z-Image-Turbo em precisão torch.bfloat16 na sua 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. Gerar uma imagem 1024×1024 (8 NFEs)

Devido à destilação de passos Decoupled-DMD, os parâmetros ideais do Z-Image-Turbo diferem de modelos tradicionais de 30–50 passos:

• Defina num_inference_steps=9 (correspondente a 8 avaliações S3-DiT / NFEs).
• Mantenha guidance_scale=0.0 (o modelo destilado dispensa Classifier-Free Guidance adicional).

prompt = (
    "Night street scene in Sao Paulo after rain, warm glowing coffee shop sign clearly "
    "reading 'CAFÉ AURORA', wet asphalt reflections, cinematic 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. Otimização de desempenho (Flash Attention e compilação)

Em GPUs compatíveis (séries RTX 30/40, A100, H100), ativar o Flash Attention 2 e compilar o módulo transformer reduz ainda mais a latência em gerações contínuas:

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

# Opcional: compilar o backbone S3-DiT após aquecimento inicial
# pipe.transformer.compile()

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

Caso ocorram erros CUDA out of memory em placas de 8 GB ou 12 GB, substitua pipe.to("cuda") por enable_model_cpu_offload() para transferir automaticamente submódulos inativos para a memória RAM:

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 uso imediato na nuvem

• Precisa treinar LoRAs personalizados, usar ControlNet ou controlar prompts negativos com CFG completo? Conheça o checkpoint base em Z-Image-Base.
• Prefere gerar direto no navegador sem instalação local? Acesse Z-Image-Turbo Online.