Guia de Início Rápido do FLUX.2¶

Este guia cobre o treinamento de LoRAs no FLUX.2, a mais recente família de modelos de geração de imagens da Black Forest Labs.

Nota: O flavour padrão é klein-9b, mas este guia foca no dev (o transformer completo de 12B com encoder de texto Mistral-3 de 24B) por ter os maiores requisitos de recursos. Os modelos Klein são mais fáceis de executar - veja Variantes do modelo abaixo.

Variantes do modelo¶

O FLUX.2 vem em três variantes:

Diferenças principais: - dev: Usa encoder de texto Mistral-Small-3.1-24B autônomo, possui embeddings de orientação - modelos klein: Usam encoder de texto Qwen3 incluso no repositório do modelo, sem embeddings de orientação (opções de treinamento de orientação são ignoradas)

Para selecionar uma variante, defina model_flavour na sua configuração:

{
  "model_flavour": "dev"
}

Importante: Para klein-4b e klein-9b, deixe qwen_text_encoder_model_name_or_path sem definir para usar o encoder Qwen3 incluído. Defina-o apenas ao substituir o encoder Qwen3 incluído por outra fonte compatível com Qwen.

Visão geral do modelo¶

O FLUX.2-dev introduz mudanças arquiteturais significativas em relação ao FLUX.1:

• Encoder de texto: Mistral-Small-3.1-24B (dev) ou Qwen3 (klein)
• Arquitetura: 8 DoubleStreamBlocks + 48 SingleStreamBlocks (dev)
• Canais latentes: 32 canais no VAE → 128 após pixel shuffle (vs 16 no FLUX.1)
• VAE: VAE customizado com batch normalization e pixel shuffling
• Dimensão de embedding: 15.360 para dev (3×5.120), 12.288 para klein-9b (3×4.096), 7.680 para klein-4b (3×2.560)

Requisitos de hardware¶

Os requisitos de hardware variam significativamente por variante do modelo.

Modelos Klein (Recomendado para a maioria dos usuários)¶

Os modelos Klein são muito mais acessíveis:

Recomendado para klein-9b: GPU única de 24GB (RTX 3090/4090, A5000) Recomendado para klein-4b: GPU única de 16GB (RTX 4080, A4000)

FLUX.2-dev (Avançado)¶

O FLUX.2-dev tem requisitos de recursos significativos devido ao encoder de texto Mistral-3:

Requisitos de VRAM¶

O encoder de texto Mistral 24B sozinho exige VRAM considerável:

RAM do sistema¶

• Mínimo: 96GB de RAM do sistema (carregar o encoder 24B exige memória substancial)
• Recomendado: 128GB+ para operação confortável

Hardware recomendado¶

• Mínimo: 2x GPUs 48GB (A6000, L40S) com FSDP2 ou DeepSpeed
• Recomendado: 4x H100 80GB com fp8-torchao
• Com quantização pesada (int4): 2x GPUs 24GB podem funcionar, mas é experimental

Treinamento distribuído multi-GPU (FSDP2 ou DeepSpeed) é essencialmente obrigatório para o FLUX.2-dev devido ao tamanho combinado do encoder de texto Mistral-3 e do transformer.

Pré-requisitos¶

Versão do Python¶

FLUX.2 exige Python 3.10 ou superior com transformers recentes:

python --version  # Should be 3.10+
pip install transformers>=4.45.0

Acesso ao modelo¶

Os modelos FLUX.2 exigem aprovação de acesso no Hugging Face:

Para dev: 1. Visite black-forest-labs/FLUX.2-dev 2. Aceite o acordo de licença

Para modelos klein: 1. Visite black-forest-labs/FLUX.2-klein-base-9B ou black-forest-labs/FLUX.2-klein-base-4B 2. Aceite o acordo de licença

Garanta que você esteja logado no Hugging Face CLI: huggingface-cli login

Instalação¶

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 setup de desenvolvimento:

git clone https://github.com/bghira/SimpleTuner
cd SimpleTuner
pip install -e ".[cuda]"

Configuração¶

Interface web¶

simpletuner server

Acesse http://localhost:8001 e selecione FLUX.2 como família de modelo.

Configuração manual¶

Crie config/config.json:

{
  "model_type": "lora",
  "model_family": "flux2",
  "model_flavour": "dev",
  "pretrained_model_name_or_path": "black-forest-labs/FLUX.2-dev",
  "output_dir": "/path/to/output",
  "train_batch_size": 1,
  "gradient_accumulation_steps": 1,
  "gradient_checkpointing": true,
  "mixed_precision": "bf16",
  "learning_rate": 1e-4,
  "lr_scheduler": "constant",
  "max_train_steps": 10000,
  "validation_resolution": "1024x1024",
  "validation_num_inference_steps": 20,
  "flux_guidance_mode": "constant",
  "flux_guidance_value": 1.0,
  "lora_rank": 16
}

Opções-chave de configuração¶

Configuração de guidance¶

Nota: Os modelos Klein (klein-4b, klein-9b) não possuem embeddings de orientação. As seguintes opções de guidance aplicam-se apenas ao dev.

FLUX.2-dev usa embedding de guidance semelhante ao FLUX.1:

{
  "flux_guidance_mode": "constant",
  "flux_guidance_value": 1.0
}

Ou para guidance aleatório durante o treinamento:

{
  "flux_guidance_mode": "random-range",
  "flux_guidance_min": 1.0,
  "flux_guidance_max": 5.0
}

Quantização (otimização de memória)¶

Para reduzir o uso de VRAM:

{
  "base_model_precision": "int8-quanto",
  "text_encoder_1_precision": "int8-quanto",
  "base_model_default_dtype": "bf16"
}

TREAD (aceleração de treinamento)¶

FLUX.2 suporta TREAD para treino mais rápido:

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

Recursos experimentais avançados¶

Configuração de dataset¶

Crie config/multidatabackend.json:

[
  {
    "id": "my-dataset",
    "type": "local",
    "crop": true,
    "crop_aspect": "square",
    "crop_style": "center",
    "resolution": 1024,
    "minimum_image_size": 1024,
    "maximum_image_size": 1024,
    "resolution_type": "pixel_area",
    "cache_dir_vae": "cache/vae/flux2/my-dataset",
    "instance_data_dir": "datasets/my-dataset",
    "caption_strategy": "textfile",
    "metadata_backend": "discovery",
    "repeats": 10
  },
  {
    "id": "text-embeds",
    "type": "local",
    "dataset_type": "text_embeds",
    "default": true,
    "cache_dir": "cache/text/flux2",
    "write_batch_size": 64
  }
]

Veja opções e requisitos de caption_strategy em DATALOADER.md.

Condicionamento opcional de edição/referência¶

O FLUX.2 pode treinar tanto texto-para-imagem (sem condicionamento) quanto com pares de imagens referência/edição. Para adicionar condicionamento, pareie seu dataset principal a um ou mais datasets conditioning usando conditioning_data e escolha um conditioning_type:

[
  {
    "id": "flux2-edits",
    "type": "local",
    "instance_data_dir": "/datasets/flux2/edits",
    "caption_strategy": "textfile",
    "resolution": 1024,
    "conditioning_data": ["flux2-references"],
    "cache_dir_vae": "cache/vae/flux2/edits"
  },
  {
    "id": "flux2-references",
    "type": "local",
    "dataset_type": "conditioning",
    "instance_data_dir": "/datasets/flux2/references",
    "conditioning_type": "reference_strict",
    "resolution": 1024,
    "cache_dir_vae": "cache/vae/flux2/references"
  }
]

• Use conditioning_type=reference_strict quando você precisa de recortes alinhados 1:1 com a imagem de edição. reference_loose permite proporções diferentes.
• Os nomes de arquivo devem corresponder entre os datasets de edição e referência; cada imagem de edição deve ter um arquivo de referência correspondente.
• Ao fornecer múltiplos datasets de condicionamento, defina conditioning_multidataset_sampling (combined vs random) conforme necessário; veja OPTIONS.
• Sem conditioning_data, o FLUX.2 retorna ao treinamento padrão texto-para-imagem.

Alvos de LoRA¶

Presets de alvo de LoRA disponíveis:

• all (padrão): todas as camadas de atenção e MLP
• attention: apenas camadas de atenção (qkv, proj)
• mlp: apenas camadas MLP/feed-forward
• tiny: treinamento mínimo (somente camadas qkv)

{
  "--flux_lora_target": "all"
}

Treinamento¶

Login nos serviços¶

huggingface-cli login
wandb login  # optional

Iniciar treinamento¶

simpletuner train

Ou via script:

./train.sh

Prompts de validação¶

Crie config/user_prompt_library.json:

{
  "portrait_subject": "a professional portrait photograph of <subject>, studio lighting, high detail",
  "artistic_subject": "an artistic interpretation of <subject> in the style of renaissance painting",
  "cinematic_subject": "a cinematic shot of <subject>, dramatic lighting, film grain"
}

Inferência¶

Usando LoRA treinado¶

LoRAs do FLUX.2 podem ser carregadas com o pipeline de inferência do SimpleTuner ou ferramentas compatíveis, à medida que o suporte da comunidade amadurece.

Escala de guidance¶

• Treinar com flux_guidance_value=1.0 funciona bem para a maioria dos casos
• Na inferência, use valores normais de guidance (3.0-5.0)

Diferenças em relação ao FLUX.1¶

Solução de problemas¶

Sem memória durante a inicialização¶

• Ative --offload_during_startup=true
• Use --quantize_via=cpu para quantização do encoder de texto
• Reduza --vae_batch_size

Embedding de texto lento¶

Mistral-3 é grande; considere: - Pré-cachear todas as embeddings de texto antes do treinamento - Usar quantização do encoder de texto - Processamento em lote com write_batch_size maior

Instabilidade no treinamento¶

• Reduza a taxa de aprendizado (tente 5e-5)
• Aumente passos de acumulação de gradiente
• Ative gradient checkpointing
• Use --max_grad_norm=1.0

CUDA sem memória¶

• Ative quantização (int8-quanto ou int4-quanto)
• Ative gradient checkpointing
• Reduza o tamanho do lote
• Use TREAD para eficiência de roteamento de tokens

Avançado: configuração do TREAD¶

TREAD (Token Routing for Efficient Architecture-agnostic Diffusion) acelera o treinamento processando tokens de forma seletiva:

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

• selection_ratio: fração de tokens a manter (0.5 = 50%)
• start_layer_idx: primeira camada para aplicar roteamento
• end_layer_idx: última camada (negativo = a partir do fim)

Aceleração esperada: 20-40% dependendo da configuração.

Veja também¶

• Guia de Início Rápido do FLUX.1 - Para treinar FLUX.1
• Documentação do TREAD - Configuração detalhada de TREAD
• Guia de treinamento LyCORIS - Métodos de treino LoRA e LyCORIS
• Configuração do dataloader - Setup de dataset