Guia rápido do Qwen Image (v1.0 / v2.0)¶

Este guia cobre os modelos antigos de 20B. Defina explicitamente model_flavour: "v1.0" ou "v2.0"; o padrão atual é 2.1. Para exemplos e configurações atuais, use o guia do Qwen Image 2.1.

🆕 Procurando os checkpoints de edição? Veja o guia de Início Rápido do Qwen Image Edit para instruções de treino com referência pareada.

Neste exemplo, vamos treinar um LoRA para o Qwen Image, um modelo visão-linguagem de 20B parâmetros. Devido ao tamanho, precisaremos de técnicas agressivas de otimização de memória.

Uma GPU de 24GB é o mínimo absoluto e, mesmo assim, você precisará de quantização extensa e configuração cuidadosa. 40GB+ é fortemente recomendado para uma experiência mais tranquila.

Ao treinar em 24G, as validações vão dar OOM a menos que você use resolução menor ou quantização agressiva além de int8.

Requisitos de hardware¶

Qwen Image é um modelo de 20B parâmetros com um encoder de texto sofisticado que, sozinho, consome ~16GB de VRAM antes de quantização. O modelo usa um VAE customizado com 16 canais latentes.

Pré-requisitos¶

Use Python 3.12–3.14. Siga o guia de instalação para configurar Python e CUDA.

Instalação¶

Instale o SimpleTuner via pip:

pip install 'simpletuner[cuda]'

# CUDA 13 / Blackwell users (NVIDIA B-series GPUs)
pip install 'simpletuner[cuda13]' --extra-index-url https://download.pytorch.org/whl/cu130

Para instalação manual ou setup de desenvolvimento, veja a documentação de instalação.

Configurando o ambiente¶

Para rodar o SimpleTuner, você precisará configurar um arquivo de configuração, os diretórios de dataset e modelo, e um arquivo de configuração do dataloader.

Arquivo de configuração¶

Um script experimental, configure.py, pode permitir que você pule esta seção inteiramente por meio de uma configuração interativa passo a passo. Ele contém alguns recursos de segurança que ajudam a evitar armadilhas comuns.

Nota: Isso não configura seu dataloader. Você ainda precisará fazer isso manualmente depois.

Para executá-lo:

simpletuner configure

⚠️ Para usuários localizados em países onde o Hugging Face Hub não é facilmente acessível, você deve adicionar HF_ENDPOINT=https://hf-mirror.com ao seu ~/.bashrc ou ~/.zshrc dependendo de qual $SHELL seu sistema usa.

Se você preferir configurar manualmente:

Copie config/config.json.example para config/config.json:

cp config/config.json.example config/config.json

Lá, você provavelmente precisará modificar as seguintes variáveis:

• model_type - Defina como lora.
• lora_type - Defina como standard para PEFT LoRA ou lycoris para LoKr.
• model_family - Defina como qwen_image.
• model_flavour - Defina como v1.0.
• output_dir - Defina como o diretório onde você quer armazenar seus checkpoints e imagens de validação. É recomendado usar um caminho completo aqui.
• train_batch_size - Ajuste de acordo com a VRAM disponível. Os overrides atuais de Qwen no SimpleTuner suportam batch sizes maiores que 1.
• gradient_accumulation_steps - Configure em 2-8 se quiser um batch efetivo maior sem aumentar a VRAM por passo.
• validation_resolution - Defina 1024x1024 ou menos por restrições de memória.
• 24G não aguenta validações 1024x1024 atualmente - você precisará reduzir o tamanho
• Outras resoluções podem ser especificadas usando vírgulas: 1024x1024,768x768,512x512
• validation_guidance - Use um valor em torno de 3.0-4.0 para bons resultados.
• validation_num_inference_steps - Use algo em torno de 30.

• use_ema - Definir como true ajuda a obter resultados mais suaves, mas usa mais memória.

• optimizer - Use optimi-lion para bons resultados, ou adamw_bf16 se tiver memória de sobra.

• mixed_precision - Deve ser definido como bf16 para o Qwen Image.
• gradient_checkpointing - Obrigatório habilitar (true) para uso de memória aceitável.
• base_model_precision - Fortemente recomendado definir int8-quanto ou nf4-bnb para placas de 24GB.
• quantize_via - Defina como cpu para evitar OOM durante a quantização em GPUs menores.
• quantize_activations - Mantenha como false para preservar qualidade de treino.

Configurações de otimização de memória para GPUs 24GB: - lora_rank - Use 8 ou menos. - lora_alpha - Igual ao valor de lora_rank. - flow_schedule_shift - Defina como 1.73 (ou experimente entre 1.0-3.0).

Seu config.json vai ficar mais ou menos assim para um setup mínimo:

{
    "model_type": "lora",
    "model_family": "qwen_image",
    "model_flavour": "v1.0",
    "lora_type": "standard",
    "lora_rank": 8,
    "lora_alpha": 8,
    "output_dir": "output/models-qwen_image",
    "train_batch_size": 1,
    "gradient_accumulation_steps": 4,
    "validation_resolution": "512x512",
    "validation_guidance": 4.0,
    "validation_num_inference_steps": 30,
    "validation_seed": 42,
    "validation_prompt": "A photo-realistic image of a cat",
    "validation_step_interval": 100,
    "vae_batch_size": 1,
    "seed": 42,
    "resume_from_checkpoint": "latest",
    "resolution": 1024,
    "resolution_type": "pixel_area",
    "report_to": "tensorboard",
    "optimizer": "optimi-lion",
    "num_train_epochs": 0,
    "num_eval_images": 1,
    "mixed_precision": "bf16",
    "minimum_image_size": 0,
    "max_train_steps": 1000,
    "max_grad_norm": 0.01,
    "lr_warmup_steps": 100,
    "lr_scheduler": "constant_with_warmup",
    "learning_rate": "1e-4",
    "gradient_checkpointing": "true",
    "base_model_precision": "int2-quanto",
    "quantize_via": "cpu",
    "quantize_activations": false,
    "flow_schedule_shift": 1.73,
    "disable_benchmark": false,
    "data_backend_config": "config/qwen_image/multidatabackend.json",
    "checkpoints_total_limit": 5,
    "checkpoint_step_interval": 500,
    "caption_dropout_probability": 0.0,
    "aspect_bucket_rounding": 2
}

ℹ️ Usuários multi-GPU podem consultar este documento para informações sobre como configurar o número de GPUs a usar.

⚠️ Crítico para GPUs 24GB: O encoder de texto sozinho usa ~16GB de VRAM. Com quantização int2-quanto ou nf4-bnb, isso pode ser reduzido significativamente.

O exemplo qwen_image/v2.1/default/peft-lora agora treina 2.1. Para as variantes anteriores, use sua configuração explícita com simpletuner train em vez desse exemplo.

Recursos experimentais avançados¶

{
  "nickname": "the prompt goes here",
  "another_nickname": "another prompt goes here"
}

  "user_prompt_library": "config/user_prompt_library.json",

{
    "anime_style": "a breathtaking anime-style portrait with vibrant colors and expressive features",
    "chef_cooking": "a high-quality, detailed photograph of a sous-chef immersed in culinary creation",
    "portrait": "a lifelike and intimate portrait showcasing unique personality and charm",
    "cinematic": "a cinematic, visually stunning photo with dramatic and captivating presence",
    "elegant": "an elegant and timeless portrait exuding grace and sophistication",
    "adventurous": "a dynamic and adventurous photo captured in an exciting moment",
    "mysterious": "a mysterious and enigmatic portrait shrouded in shadows and intrigue",
    "vintage": "a vintage-style portrait evoking the charm and nostalgia of a bygone era",
    "artistic": "an artistic and abstract representation blending creativity with visual storytelling",
    "futuristic": "a futuristic and cutting-edge portrayal set against advanced technology"
}

{
  "validation_preview": true,
  "validation_preview_steps": 1
}

[
  {
    "id": "pseudo-camera-10k-qwen",
    "type": "local",
    "crop": true,
    "crop_aspect": "square",
    "crop_style": "center",
    "resolution": 1024,
    "minimum_image_size": 512,
    "maximum_image_size": 1024,
    "target_downsample_size": 1024,
    "resolution_type": "pixel_area",
    "cache_dir_vae": "cache/vae/qwen_image/pseudo-camera-10k",
    "instance_data_dir": "datasets/pseudo-camera-10k",
    "disabled": false,
    "skip_file_discovery": "",
    "caption_strategy": "filename",
    "metadata_backend": "discovery",
    "repeats": 0,
    "is_regularisation_data": true
  },
  {
    "id": "dreambooth-subject",
    "type": "local",
    "crop": false,
    "resolution": 1024,
    "minimum_image_size": 512,
    "maximum_image_size": 1024,
    "target_downsample_size": 1024,
    "resolution_type": "pixel_area",
    "cache_dir_vae": "cache/vae/qwen_image/dreambooth-subject",
    "instance_data_dir": "datasets/dreambooth-subject",
    "caption_strategy": "instanceprompt",
    "instance_prompt": "the name of your subject goes here",
    "metadata_backend": "discovery",
    "repeats": 1000
  },
  {
    "id": "text-embeds",
    "type": "local",
    "dataset_type": "text_embeds",
    "default": true,
    "cache_dir": "cache/text/qwen_image",
    "disabled": false,
    "write_batch_size": 16
  }
]

mkdir -p datasets
pushd datasets
    huggingface-cli download --repo-type=dataset bghira/pseudo-camera-10k --local-dir=pseudo-camera-10k
    mkdir dreambooth-subject
    # place your images into dreambooth-subject/ now
popd

wandb login

huggingface-cli login

Executando o treinamento¶

A partir do diretório do SimpleTuner, basta executar:

./train.sh

Isso vai iniciar o cache em disco das embeddings de texto e saídas do VAE.

Para mais informações, veja os documentos do dataloader e do tutorial.

Dicas de otimização de memória¶

Configuração de menor VRAM (mínimo 24GB)¶

A configuração de menor VRAM do Qwen Image exige cerca de 24GB:

• SO: Ubuntu Linux 24
• GPU: um único dispositivo NVIDIA CUDA (mínimo 24GB)
• Memória do sistema: 64GB+ recomendado
• Precisão do modelo base:
• Para sistemas NVIDIA: int2-quanto ou nf4-bnb (obrigatório para placas de 24GB)
• int4-quanto pode funcionar, mas pode ter qualidade menor
• Otimizador: optimi-lion ou bnb-lion8bit-paged para eficiência de memória
• Resolução: comece com 512px ou 768px, suba para 1024px se a memória permitir
• Batch size: 1
• Gradient accumulation steps: 2-8 para simular batches maiores
• Habilite --gradient_checkpointing (obrigatório)
• Use --quantize_via=cpu para evitar OOM na inicialização
• Use um rank LoRA pequeno (1-8)
• Definir a variável de ambiente PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True ajuda a minimizar uso de VRAM

NOTA: O pré-cache de embeddings do VAE e saídas do encoder de texto vai usar memória significativa. Habilite offload_during_startup=true se você encontrar OOM.

Rodando inferência no LoRA depois¶

Como o Qwen Image é um modelo mais novo, aqui está um exemplo funcional de inferência:

import torch
from diffusers import QwenImagePipeline, QwenImageTransformer2DModel
from transformers import Qwen2Tokenizer, Qwen2_5_VLForConditionalGeneration

model_id = 'Qwen/Qwen-Image'
adapter_id = 'your-username/your-lora-name'

# Load the pipeline
pipeline = QwenImagePipeline.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16
)

# Load LoRA weights
pipeline.load_lora_weights(adapter_id)

# Optional: quantize the model to save VRAM
from optimum.quanto import quantize, freeze, qint8
quantize(pipeline.transformer, weights=qint8)
freeze(pipeline.transformer)

# Move to device
pipeline.to('cuda' if torch.cuda.is_available() else 'cpu')

# Generate an image
prompt = "Your test prompt here"
negative_prompt = 'ugly, cropped, blurry, low-quality, mediocre average'

image = pipeline(
    prompt=prompt,
    negative_prompt=negative_prompt,
    num_inference_steps=30,
    guidance_scale=4.0,
    generator=torch.Generator(device='cuda').manual_seed(42),
    width=1024,
    height=1024,
).images[0]

image.save("output.png", format="PNG")

Notas e dicas de troubleshooting¶

Limitações de batch size¶

Builds antigos do Qwen no diffusers tinham problemas com batch size > 1 por causa do padding dos embeddings de texto e do mascaramento de atenção. Os overrides atuais de Qwen no SimpleTuner corrigem os dois pontos, então batches maiores funcionam se a sua VRAM permitir. - Aumente train_batch_size somente depois de confirmar a folga de memória. - Se ainda aparecerem artefatos em uma instalação antiga, atualize e regenere quaisquer text embeds antigos.

Quantização¶

• int2-quanto oferece a economia de memória mais agressiva, mas pode impactar a qualidade
• nf4-bnb oferece bom equilíbrio entre memória e qualidade
• int4-quanto é uma opção intermediária
• Evite int8 a menos que você tenha 40GB+ de VRAM

Taxas de aprendizado¶

Para treino de LoRA: - LoRAs pequenas (rank 1-8): use learning rates em torno de 1e-4 - LoRAs maiores (rank 16-32): use learning rates em torno de 5e-5 - Com otimizador Prodigy: comece em 1.0 e deixe adaptar

Artefatos de imagem¶

Se você encontrar artefatos: - Reduza sua taxa de aprendizado - Aumente gradient accumulation steps - Garanta que suas imagens são de alta qualidade e bem pré-processadas - Considere usar resoluções menores inicialmente

Treino com múltiplas resoluções¶

Comece o treino em resoluções menores (512px ou 768px) para acelerar o aprendizado inicial, depois faça fine-tune em 1024px. Habilite --flow_schedule_auto_shift ao treinar em diferentes resoluções.

Limitações de plataforma¶

Estas recomendações de memória se aplicam a GPUs NVIDIA. Consulte o guia de instalação para dependências e backends de atenção em outras plataformas.

Para ajuda adicional e troubleshooting, consulte a documentação do SimpleTuner ou entre no Discord da comunidade.

As receitas do Qwen Image 2.1 foram movidas¶

Presets de VRAM

Piloto AnyFlow

Correção do otimizador

Criar um assistente

Assistente multirresolução

Assistente offline