Guía rápida de Qwen Image (v1.0 / v2.0)¶

Esta guía cubre los modelos antiguos de 20B. Configura explícitamente model_flavour: "v1.0" o "v2.0"; el predeterminado actual es 2.1. Para ejemplos y ajustes actuales, usa la guía de Qwen Image 2.1.

🆕 ¿Buscas los checkpoints de edición? Consulta la guía rápida de Qwen Image Edit para instrucciones de entrenamiento con referencia emparejada.

En este ejemplo, entrenaremos un LoRA para Qwen Image, un modelo visión‑lenguaje de 20B parámetros. Debido a su tamaño, necesitaremos técnicas agresivas de optimización de memoria.

Una GPU de 24GB es el mínimo absoluto, y aun así necesitarás cuantización extensa y configuración cuidadosa. Se recomiendan encarecidamente 40GB+ para una experiencia más fluida.

Al entrenar en 24G, las validaciones se quedarán sin memoria a menos que uses menor resolución o un nivel de cuantización agresivo más allá de int8.

Requisitos de hardware¶

Qwen Image es un modelo de 20B parámetros con un codificador de texto sofisticado que por sí solo consume ~16GB de VRAM antes de la cuantización. El modelo usa un VAE personalizado con 16 canales latentes.

Requisitos previos¶

Usa Python 3.12–3.14. Sigue la guía de instalación para configurar Python y CUDA.

Instalación¶

Instala SimpleTuner vía 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 instalación manual o entorno de desarrollo, consulta la documentación de instalación.

Configuración del entorno¶

Para ejecutar SimpleTuner, necesitas configurar un archivo de configuración, los directorios del dataset y del modelo, y un archivo de configuración del dataloader.

Archivo de configuración¶

Un script experimental, configure.py, puede permitirte omitir por completo esta sección mediante una configuración interactiva paso a paso. Incluye funciones de seguridad que ayudan a evitar errores comunes.

Nota: Esto no configura tu dataloader. Aún tendrás que hacerlo manualmente más adelante.

Para ejecutarlo:

simpletuner configure

⚠️ Para usuarios ubicados en países donde Hugging Face Hub no es fácilmente accesible, debes agregar HF_ENDPOINT=https://hf-mirror.com a tu ~/.bashrc o ~/.zshrc dependiendo de cuál $SHELL use tu sistema.

Si prefieres configurarlo manualmente:

Copia config/config.json.example a config/config.json:

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

Allí, probablemente necesitarás modificar las siguientes variables:

• model_type - Configúralo en lora.
• lora_type - Configúralo en standard para PEFT LoRA o lycoris para LoKr.
• model_family - Configúralo en qwen_image.
• model_flavour - Configúralo en v1.0.
• output_dir - Configúralo al directorio donde quieres guardar tus checkpoints y las imágenes de validación. Se recomienda usar una ruta completa aquí.
• train_batch_size - Ajústalo según la VRAM disponible. Los overrides actuales de Qwen en SimpleTuner admiten tamaños de lote mayores que 1.
• gradient_accumulation_steps - Configúralo en 2-8 si quieres un batch efectivo mayor sin subir la VRAM por paso.
• validation_resolution - Debes configurarlo en 1024x1024 o menor por restricciones de memoria.
• 24G no puede manejar validaciones 1024x1024 actualmente - tendrás que reducir el tamaño
• Se pueden especificar otras resoluciones separándolas con comas: 1024x1024,768x768,512x512
• validation_guidance - Usa un valor alrededor de 3.0-4.0 para buenos resultados.
• validation_num_inference_steps - Usa alrededor de 30.

• use_ema - Configurar esto en true ayudará a obtener resultados más suaves pero usa más memoria.

• optimizer - Usa optimi-lion para buenos resultados, o adamw_bf16 si tienes memoria de sobra.

• mixed_precision - Debe configurarse en bf16 para Qwen Image.
• gradient_checkpointing - Obligatorio habilitar (true) para un uso razonable de memoria.
• base_model_precision - Muy recomendado configurar en int8-quanto o nf4-bnb para tarjetas de 24GB.
• quantize_via - Configúralo en cpu para evitar OOM durante la cuantización en GPUs más pequeñas.
• quantize_activations - Mantén esto en false para conservar la calidad de entrenamiento.

Ajustes de optimización de memoria para GPUs de 24GB: - lora_rank - Usa 8 o menos. - lora_alpha - Iguala esto a tu valor de lora_rank. - flow_schedule_shift - Configura en 1.73 (o experimenta entre 1.0-3.0).

Tu config.json se verá algo así para un 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
}

ℹ️ Usuarios multi-GPU pueden consultar este documento para información sobre cómo configurar la cantidad de GPUs a usar.

⚠️ Crítico para GPUs de 24GB: El codificador de texto por sí solo usa ~16GB de VRAM. Con cuantización int2-quanto o nf4-bnb, esto se puede reducir significativamente.

El ejemplo qwen_image/v2.1/default/peft-lora ahora entrena 2.1. Para las variantes anteriores, usa tu configuración explícita con simpletuner train en lugar de ese ejemplo.

Funciones experimentales avanzadas¶

{
  "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

Ejecutar el entrenamiento¶

Desde el directorio de SimpleTuner, solo hay que ejecutar:

./train.sh

Esto iniciará el caché a disco de text embeds y salidas del VAE.

Para más información, consulta los documentos de dataloader y tutorial.

Consejos de optimización de memoria¶

Configuración de VRAM más baja (mínimo 24GB)¶

La configuración de VRAM más baja de Qwen Image requiere aproximadamente 24GB:

• OS: Ubuntu Linux 24
• GPU: Un solo dispositivo NVIDIA CUDA (mínimo 24GB)
• Memoria del sistema: Se recomienda 64GB+
• Precisión del modelo base:
• Para sistemas NVIDIA: int2-quanto o nf4-bnb (requerido para tarjetas de 24GB)
• int4-quanto puede funcionar pero con menor calidad
• Optimizador: optimi-lion o bnb-lion8bit-paged para eficiencia de memoria
• Resolución: Comienza con 512px o 768px, sube a 1024px si la memoria lo permite
• Tamaño de lote: 1
• Pasos de acumulación de gradiente: 2-8 para simular lotes más grandes
• Habilitar --gradient_checkpointing (obligatorio)
• Usa --quantize_via=cpu para evitar OOM durante el arranque
• Usa un rango LoRA pequeño (1-8)
• Configurar la variable de entorno PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True ayuda a minimizar el uso de VRAM

NOTA: El pre-caché de embeddings del VAE y salidas del codificador de texto usará memoria significativa. Habilita offload_during_startup=true si encuentras problemas de OOM.

Ejecutar inferencia en el LoRA después¶

Como Qwen Image es un modelo más nuevo, aquí hay un ejemplo funcional de inferencia:

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 y consejos de solución de problemas¶

Limitaciones de tamaño de lote¶

Las compilaciones antiguas de diffusers para Qwen tenían problemas con batch size > 1 por el padding de embeddings de texto y el enmascarado de atención. Los overrides actuales de Qwen en SimpleTuner corrigen ambos puntos, así que los lotes mayores funcionan si tu VRAM lo permite. - Aumenta train_batch_size solo después de confirmar que tienes memoria suficiente. - Si todavía ves artefactos en una instalación antigua, actualiza y regenera cualquier embedding de texto obsoleto.

Cuantización¶

• int2-quanto brinda el mayor ahorro de memoria pero puede afectar la calidad
• nf4-bnb ofrece un buen equilibrio entre memoria y calidad
• int4-quanto es una opción intermedia
• Evita int8 a menos que tengas 40GB+ de VRAM

Tasas de aprendizaje¶

Para entrenamiento LoRA: - LoRAs pequeñas (rango 1-8): usa tasas alrededor de 1e-4 - LoRAs grandes (rango 16-32): usa tasas alrededor de 5e-5 - Con optimizador Prodigy: empieza con 1.0 y deja que se adapte

Artefactos de imagen¶

Si encuentras artefactos: - Baja la tasa de aprendizaje - Aumenta los pasos de acumulación de gradiente - Asegúrate de que tus imágenes sean de alta calidad y estén bien preprocesadas - Considera usar resoluciones más bajas al inicio

Entrenamiento de múltiples resoluciones¶

Comienza el entrenamiento en resoluciones más bajas (512px o 768px) para acelerar el aprendizaje inicial, luego ajusta fino en 1024px. Habilita --flow_schedule_auto_shift al entrenar en diferentes resoluciones.

Limitaciones de plataforma¶

Estas recomendaciones de memoria son para GPU NVIDIA. Consulta la guía de instalación para dependencias y backends de atención en otras plataformas.

Para ayuda adicional y solución de problemas, consulta la documentación de SimpleTuner o únete al Discord de la comunidad.

Las recetas de Qwen Image 2.1 se han trasladado¶

Preajustes de VRAM

Prueba AnyFlow

Corrección del optimizador

Crear un asistente

Asistente multirresolución

Asistente offline