Guía rápida de Kandinsky 5.0 Image¶

En este ejemplo, entrenaremos un LoRA de Kandinsky 5.0 Image.

Requisitos de hardware¶

Kandinsky 5.0 emplea un enorme codificador de texto Qwen2.5-VL de 7B parámetros además de un codificador CLIP estándar y el VAE de Flux. Esto exige mucho tanto de VRAM como de RAM del sistema.

Solo cargar el codificador Qwen requiere alrededor de 14GB de memoria por sí solo. Al entrenar un LoRA de rango 16 con gradient checkpointing completo:

• 24GB de VRAM es el mínimo cómodo (RTX 3090/4090).
• 16GB de VRAM es posible pero requiere offloading agresivo y probablemente cuantización int8 del modelo base.

Necesitarás:

• RAM del sistema: Al menos 32GB, idealmente 64GB, para manejar la carga inicial del modelo sin fallos.
• GPU: NVIDIA RTX 3090 / 4090 o tarjetas profesionales (A6000, A100, etc.).

Offloading de memoria (recomendado)¶

Configura "offload_during_startup": true en tu config.json para reducir el uso de VRAM durante la fase de inicialización y caché. Esto asegura que el codificador de texto y el VAE no se carguen simultáneamente.

Requisitos previos¶

Asegúrate de tener python instalado; SimpleTuner funciona bien con 3.10 a 3.12.

Puedes comprobarlo ejecutando:

python --version

Si no tienes python 3.12 instalado en Ubuntu, puedes intentar lo siguiente:

apt -y install python3.13 python3.13-venv

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¶

Método de interfaz web¶

La WebUI de SimpleTuner hace que la configuración sea bastante sencilla. Para ejecutar el servidor:

simpletuner server

Accede en http://localhost:8001.

Método manual / línea de comandos¶

Para ejecutar SimpleTuner mediante herramientas de línea de comandos, necesitarás 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 ayudarte a omitir esta sección:

simpletuner configure

Si prefieres configurarlo manualmente:

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

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

Necesitarás modificar las siguientes variables:

• model_type: lora
• model_family: kandinsky5-image
• model_flavour:
• t2i-lite-sft: (Predeterminado) El checkpoint SFT estándar. Mejor para ajustar estilos/personajes.
• t2i-lite-pretrain: El checkpoint pretrain. Mejor para enseñar conceptos totalmente nuevos desde cero.
• i2i-lite-sft / i2i-lite-pretrain: Para entrenamiento de imagen a imagen. Requiere imágenes de condicionamiento en tu dataset.
• output_dir: Dónde guardar tus checkpoints.
• train_batch_size: Comienza con 1.
• gradient_accumulation_steps: Usa 1 o más para simular lotes más grandes.
• validation_resolution: 1024x1024 es estándar para este modelo.
• validation_guidance: 5.0 es el valor recomendado por defecto para Kandinsky 5.
• flow_schedule_shift: 1.0 es el valor predeterminado. Ajustarlo cambia cómo el modelo prioriza detalles vs composición (ver abajo).

Prompts de validación¶

Dentro de config/config.json está el "prompt de validación principal". También puedes crear una biblioteca de prompts en config/user_prompt_library.json:

{
  "portrait": "A high quality portrait of a woman, cinematic lighting, 8k",
  "landscape": "A beautiful mountain landscape at sunset, oil painting style"
}

Habilítalo agregando esto a tu config.json:

{
  "user_prompt_library": "config/user_prompt_library.json"
}

Desplazamiento del calendario de flujo¶

Kandinsky 5 es un modelo de flow-matching. El parámetro shift controla la distribución de ruido durante entrenamiento e inferencia.

• Shift 1.0 (Predeterminado): Entrenamiento equilibrado.
• Shift bajo (< 1.0): Enfoca el entrenamiento más en detalles de alta frecuencia (textura, ruido).
• Shift alto (> 1.0): Enfoca el entrenamiento más en detalles de baja frecuencia (composición, color, estructura).

Si tu modelo aprende estilos bien pero falla en composición, intenta aumentar el shift. Si aprende composición pero le falta textura, intenta disminuirlo.

Entrenamiento con modelo cuantizado¶

Puedes reducir significativamente el uso de VRAM cuantizando el transformer a 8-bit.

En config.json:

  "base_model_precision": "int8-quanto",
  "text_encoder_1_precision": "no_change",
  "text_encoder_2_precision": "no_change",
  "lora_rank": 16,
  "base_model_default_dtype": "bf16"

Nota: No recomendamos cuantizar los codificadores de texto (no_change) ya que Qwen2.5-VL es sensible a los efectos de cuantización y ya es la parte más pesada del pipeline.

Funciones experimentales avanzadas¶

[
  {
    "id": "my-image-dataset",
    "type": "local",
    "dataset_type": "image",
    "instance_data_dir": "datasets/my_images",
    "caption_strategy": "textfile",
    "resolution": 1024,
    "crop": true,
    "crop_aspect": "square",
    "repeats": 10
  },
  {
    "id": "text-embeds",
    "type": "local",
    "dataset_type": "text_embeds",
    "default": true,
    "cache_dir": "cache/text/kandinsky5",
    "disabled": false
  }
]

mkdir -p datasets/my_images
</details>

# Copy your images and .txt caption files here

wandb login
huggingface-cli login

simpletuner train

./train.sh

{
  "tread_config": {
    "routes": [
      {
        "selection_ratio": 0.5,
        "start_layer_idx": 2,
        "end_layer_idx": -2
      }
    ]
  }
}