Guia de Início Rápido do Kandinsky 5.0 Image¶

Neste exemplo, vamos treinar um LoRA do Kandinsky 5.0 Image.

Requisitos de hardware¶

Kandinsky 5.0 usa um enorme encoder de texto Qwen2.5-VL de 7B parâmetros além de um encoder CLIP padrão e o VAE do Flux. Isso coloca uma demanda significativa tanto em VRAM quanto em RAM do sistema.

Apenas carregar o encoder Qwen exige cerca de 14GB de memória por si só. Ao treinar um LoRA rank 16 com gradient checkpointing completo:

• 24GB de VRAM é o mínimo confortável (RTX 3090/4090).
• 16GB de VRAM é possível, mas exige offload agressivo e provavelmente quantização int8 do modelo base.

Você vai precisar:

• RAM do sistema: Pelo menos 32GB, idealmente 64GB, para lidar com o carregamento inicial do modelo sem travar.
• GPU: NVIDIA RTX 3090 / 4090 ou placas profissionais (A6000, A100, etc.).

Offload de memória (recomendado)¶

Defina "offload_during_startup": true no seu config.json para reduzir uso de VRAM durante a inicialização e cache. Isso garante que o encoder de texto e o VAE não sejam carregados ao mesmo tempo.

Pré-requisitos¶

Certifique-se de que você tem Python instalado; o SimpleTuner funciona bem com 3.10 até 3.12.

Você pode verificar executando:

python --version

Se você não tem o Python 3.12 instalado no Ubuntu, pode tentar o seguinte:

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

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¶

Método da interface web¶

A WebUI do SimpleTuner torna a configuração bastante direta. Para rodar o servidor:

simpletuner server

Acesse em http://localhost:8001.

Método manual / linha de comando¶

Para rodar o SimpleTuner via linha de comando, 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 ajudar você a pular esta seção:

simpletuner configure

Se você preferir configurar manualmente:

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

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

Você precisará modificar as seguintes variáveis:

• model_type: lora
• model_family: kandinsky5-image
• model_flavour:
• t2i-lite-sft: (Padrão) Checkpoint SFT padrão. Melhor para fine-tuning de estilos/personagens.
• t2i-lite-pretrain: Checkpoint de pré-treino. Melhor para ensinar conceitos totalmente novos do zero.
• i2i-lite-sft / i2i-lite-pretrain: Para treino imagem-para-imagem. Requer imagens de condicionamento no seu dataset.
• output_dir: onde salvar seus checkpoints.
• train_batch_size: comece com 1.
• gradient_accumulation_steps: use 1 ou maior para simular batches maiores.
• validation_resolution: 1024x1024 é o padrão para este modelo.
• validation_guidance: 5.0 é o padrão recomendado para Kandinsky 5.
• flow_schedule_shift: 1.0 é o padrão. Ajustar isso muda como o modelo prioriza detalhes vs composição (veja abaixo).

Prompts de validação¶

Dentro de config/config.json está o "prompt de validação principal". Você também pode criar uma biblioteca de prompts em 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"
}

Habilite adicionando isto ao config.json:

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

Ajuste de schedule de flow¶

Kandinsky 5 é um modelo de flow-matching. O parâmetro shift controla a distribuição de ruído durante treino e inferência.

• Shift 1.0 (Padrão): Treino equilibrado.
• Shift baixo (< 1.0): Foca mais em detalhes de alta frequência (textura, ruído).
• Shift alto (> 1.0): Foca mais em detalhes de baixa frequência (composição, cor, estrutura).

Se o modelo aprende estilos bem, mas falha na composição, tente aumentar o shift. Se aprende composição, mas falta textura, tente diminuir.

Treino com modelo quantizado¶

Você pode reduzir significativamente a VRAM quantizando o transformer para 8 bits.

No 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: Não recomendamos quantizar os encoders de texto (no_change), pois o Qwen2.5-VL é sensível a quantização e já é a parte mais pesada do pipeline.

Recursos experimentais avançados¶

[
  {
    "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
      }
    ]
  }
}