Z-Image Turbo: Configuração Local e Treinamento

TL;DR

• Rode o Z-Image Turbo localmente com 6B de parâmetros, inferência em 8 passos, latência de menos de um segundo em 16 GB de VRAM; instale via pip install git+https://github.com/huggingface/diffusers e carregue Tongyi-MAI/Z-Image-Turbo em bfloat16.
• Monte fluxos leves de img2img e inpainting no ComfyUI usando ImageScaleToMaxDimension, VAE Encode (for inpainting) e Repeat Latent Batch — sem ControlNet; mantenha o denoise entre 0.75–0.90 no img2img.
• Treine LoRAs de personagem com o ostris zimage_turbo_training_adapter_v2 (324 MB) no AI Toolkit: 3.000 passos, rank 16, lr 1e-4, AdamW8bit, buckets multi-resolução (512/768/1024), legendas de uma palavra; ~15–22 min em RTX 5090, ~8–12 h em RTX 4090.

O Z-Image Turbo é um modelo destilado de 6 bilhões de parâmetros da Tongyi-MAI que gera imagens em 8 NFEs (número de avaliações de função), igualando ou superando concorrentes maiores em benchmarks de qualidade. Ele ocupa o #1 entre modelos de código aberto no leaderboard da Artificial Analysis e renderiza texto bilíngue chinês/ingles nativamente. Este guia cobre inferência local, fluxos de img2img e inpainting no ComfyUI que evitam ControlNet, e uma receita reproduzível de treinamento de LoRA usando o adaptador de destilação da ostris.

Configuração de inferência local

pip install git+https://github.com/huggingface/diffusers

import torch
from diffusers import ZImagePipeline

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

prompt = "Young woman in red Hanfu, intricate embroidery, neon lightning-bolt lamp above palm, pagoda silhouette at night"

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("zimage_turbo.png")

Ajustes-chave: guidance_scale=0.0, num_inference_steps=9 (gera 8 forwards), bfloat16 em CUDA. O modelo cabe em 16 GB de VRAM; ative pipe.enable_model_cpu_offload() se precisar rodar com menos.

Fluxo img2img no ComfyUI (sem ControlNet)

A comunidade da Civitai convergiu em um grafo leve de img2img que controla a resolução de entrada e saída sem ControlNet. Parta do template padrão ZiT Text to Image e religue os nós como abaixo.

Nós a adicionar

Nó | Propósito ------|--------- Load Image | Entrada da imagem de origem ImageScaleToMaxDimension | Redimensiona para uma aresta máxima mantendo a proporção VAE Encode | Codifica pixels em latente Repeat Latent Batch | Iguala o tamanho do batch para o KSampler

Conexões

1. Load VAE → entrada VAE do VAE Encode
2. Load Image → entrada Image do ImageScaleToMaxDimension
3. ImageScaleToMaxDimension → entrada Pixels do VAE Encode
4. VAE Encode → entrada Samples do Repeat Latent Batch
5. Repeat Latent Batch → entrada latent_image do KSampler

ImageScaleToMaxDimension usa 512 como aresta máxima por padrão; aumente para 1024 ou 1536 para mais fidelidade. Valores de upscale_method suportados: area, lanczos, bilinear, nearest-exact, bicubic.

Ponto ideal do denoise

Testes da comunidade indicam os melhores resultados de img2img com denoise 0.75–0.90 no KSampler:

Denoise menor = mais fidelidade à fonte; maior = mais aderência ao prompt. Comece em 0.85 e ajuste.

Fluxo de inpainting no ComfyUI

Inpainting usa o nó VAE Encode (for inpainting), que aceita a imagem e uma máscara. O mesmo nó ImageScaleToMaxDimension pode dirigir a resolução.

Nós a adicionar

Nó | Propósito ------|--------- Load Image | Imagem de origem + máscara (canal alfa ou entrada separada de máscara) VAE Encode (for inpainting) | Codifica pixels + máscara em latente Repeat Latent Batch | Alinhamento de batch para o KSampler ImageScaleToMaxDimension (opcional) | Controle de resolução

Conexões

1. Load Image → Pixels + Mask → VAE Encode (for inpainting)
2. Load Image → Pixels → ImageScaleToMaxDimension → image → VAE Encode (for inpainting)
3. Load VAE → vae → VAE Encode (for inpainting)
4. VAE Encode (for inpainting) → Latent → Repeat Latent Batch → Samples
5. **Repeat Latent Batch → Latent → **KSampler** → latent_image`

Opcional: adicione o nó Image Compare (via ComfyUI Manager) para visualizar lado a lado image_a (entrada escalada) e image_b (saída do VAE Decode).

Treinando um LoRA de personagem com AI Toolkit

O Z-Image Turbo é um modelo destilado; treinar um LoRA diretamente nele quebra a velocidade de 8 passos ("Turbo Drift"). O ostris zimage_turbo_training_adapter_v2 resolve isso: é um LoRA de destilação de 324 MB treinado em milhares de saídas do Z-Image Turbo a lr 1e-5. Você treina seu LoRA em cima desse adaptador, depois remove o adaptador na inferência — seu LoRA mantém a velocidade de 8 passos.

Pré-requisitos

Item | Especificação | Source ------|----------------|-------- GPU (NVIDIA) | Mínimo 12 GB de VRAM, recomendado 24 GB | https://kawaiipromptlab.com/en/tutorials/lora-training-guide/ GPU (Apple Silicon) | Mínimo 32 GB unificados, recomendado 64 GB | https://kawaiipromptlab.com/en/tutorials/lora-training-guide/ Disco | 50 GB livres (recomendado 100 GB) | https://github.com/ostris/ai-toolkit Python | 3.10+ | https://github.com/ostris/ai-toolkit PyTorch | 2.0+ (2.8+ para MPS) | https://github.com/ostris/ai-toolkit

Instale o AI Toolkit:

git clone https://github.com/ostris/ai-toolkit.git
cd ai-toolkit
git submodule update --init --recursive
pip install -r requirements.txt

Baixe o adaptador:

huggingface-cli download ostris/zimage_turbo_training_adapter zimage_turbo_training_adapter_v2.safetensors
# Place in your weights folder, e.g. ./weights/zimage_turbo_training_adapter_v2.safetensors

Preparação do dataset

• LoRA de personagem: 70–80 imagens para alta qualidade (textura de pele), 15+ para um teste funcional
• LoRA de estilo: 30–120 imagens (~45 é o ponto ideal)
• Resolução: 1024×1024 recomendado; 512 funciona mas com menos fidelidade
• Composição: 40–50% close-ups, 30–40% planos médios, 10–20% corpo inteiro
• Legendas: gatilho de uma palavra por imagem (ex.: sks ou ohwx). Não escreva frases descritivas — o modelo já sabe "roupas", "fundo", etc. Legendas demais causam rostos "mushy" e perda de detalhe.

Layout de pastas:

datasets/
└── my_character/
    ├── img_001.jpg
    ├── img_001.txt   # contains only: sks
    ├── img_002.jpg
    ├── img_002.txt   # contains only: sks
    └── ...

Configuração de treino (YAML)

Salve como config/my_zimage_lora.yaml:

job: extension
config:
  name: "my_zimage_lora_v1"
  process:
    - type: "sd_trainer"
      training_folder: "output"
      device: "cuda:0"
      trigger_word: "sks"
      network:
        type: "lora"
        linear: 16
        linear_alpha: 16
      save:
        dtype: "float16"
        save_every: 250
        max_step_saves_to_keep: 4
      datasets:
        - folder_path: "/path/to/datasets/my_character"
          caption_ext: "txt"
          caption_dropout_rate: 0.05
          cache_latents_to_disk: true
          resolution: [512, 768, 1024]
      train:
        batch_size: 1
        steps: 3000
        gradient_accumulation_steps: 1
        train_unet: true
        train_text_encoder: false
        gradient_checkpointing: true
        noise_scheduler: "flowmatch"
        optimizer: "adamw8bit"
        lr: 1e-4
        ema_config:
          use_ema: true
          ema_decay: 0.99
        dtype: "bf16"
      model:
        name_or_path: "Tongyi-MAI/Z-Image-Turbo"
        arch: "zimage"
        assistant_lora_path: "./weights/zimage_turbo_training_adapter_v2.safetensors"
        quantize: true
      sample:
        sampler: "flowmatch"
        sample_every: 250
        width: 1024
        height: 1024
        prompts:
          - "sks, portrait photo, natural lighting"
        seed: 42
        guidance_scale: 1
        sample_steps: 8

Ajustes para Apple Silicon (MPS): mude device: "mps:0", optimizer: "adamw" (adamw8bit é só para CUDA), quantize: false, adicione num_workers: 0 em datasets.

Executar treino

cd ai-toolkit
python run.py config/my_zimage_lora.yaml

Tempos de execução esperados (3.000 passos):

Monitore a queda da loss e as imagens de amostra a cada 250 passos. Pare cedo se a identidade estabilizar; vá a 5.000 passos só com dados e legendas limpos.

Inferência com o LoRA treinado

ComfyUI: coloque my_zimage_lora_v1.safetensors em ComfyUI/models/loras/, adicione um nó Load LoRA entre o model loader e o KSampler, ajuste a força para 0.8–1.0.

Python (Diffusers):

from diffusers import ZImagePipeline
import torch

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

pipe.load_lora_weights("./output/my_zimage_lora_v1.safetensors", adapter_name="character")
pipe.set_adapters(["character"], adapter_weights=[0.9])

image = pipe(
    prompt="sks, portrait photo, natural lighting, 85mm lens",
    num_inference_steps=9,
    guidance_scale=0.0,
    width=1024,
    height=1024,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]

image.save("lora_result.png")

Crítico: não carregue o adaptador de treino na inferência. Seu LoRA sozinho preserva a velocidade destilada de 8 passos.

Sources

Navegação

• Configuração de inferência local
• Fluxo de inpainting no ComfyUI
• Treinamento de LoRA de personagem
• Aluguel de GPU na RunPod
• Seleção de VAE para modelos de difusão

Erros comuns e correções

FAQ

Quantas imagens preciso para um LoRA de personagem? 15+ imagens e 1.000+ passos para um teste funcional; 70–80 imagens em 1024×1024 para qualidade de produção que reproduz a textura da pele.

Qual a memória mínima para treinar um LoRA? 12 GB de VRAM no mínimo, 24 GB recomendado; em Apple Silicon, 32 GB unificados mínimos, 64 GB recomendados.

O que acontece se eu carregar o adaptador de treino na inferência? O LoRA fica maior e pode perder velocidade; remova o adaptador para preservar os 8 passos do modelo destilado.

Denoise no img2img é seguro com ControlNet? Com ControlNet, o denoise pode ser mais baixo; sem ControlNet, use 0.75–0.90 para manter equilíbrio.

Quantos passos devo treinar? Comece com 3.000 passos; suba para 5.000 apenas com dados e legendas limpos.

Qual a diferença entre o adaptador v1 e v2? O v2 oferece melhor qualidade e é o recomendado para treinamento; em 2026, só o v2 é suportado.