Esta página é uma visão geral de fine‑tuning de LoRA com o Ostris AI Toolkit. Para uma receita específica por modelo, vá direto para um destes guias:

• Treinamento LoRA de FLUX.2 Dev com AI Toolkit
• Treinamento LoRA de LTX-2 com AI Toolkit
• Treinamento LoRA de Z‑Image Turbo com AI Toolkit
• Treinamento LoRA de Qwen Image 2512 com AI Toolkit
• Treinamento LoRA de Qwen‑Image‑Edit‑2511 com AI Toolkit
• Treinamento LoRA de Qwen‑Image‑Edit‑2509 com AI Toolkit
• Treinamento LoRA de Wan 2.2 I2V 14B com AI Toolkit
• Treinamento LoRA de Wan 2.2 T2V 14B com AI Toolkit

Ao final deste guia, você deve:

• Entender as ideias centrais do treinamento LoRA (o que realmente está acontecendo quando você faz fine‑tuning).
• Saber como o AI Toolkit é organizado e o que cada painel controla.
• Entender o que fazem os principais parâmetros (learning rate, rank, steps, noise schedule, DOP, etc.) para ajustar de forma consciente.
• Conseguir treinar LoRAs na sua máquina ou no RunComfy Cloud AI Toolkit e depois reaproveitá-las no seu fluxo normal de geração.

---

Índice

• 1. O que é o Ostris AI Toolkit? (treinador LoRA para modelos de difusão)
• 2. Modelos suportados no Ostris AI Toolkit (Flux, Wan, Z‑Image, Qwen‑Image, SDXL)
• 3. Instalar o Ostris AI Toolkit localmente e usar o RunComfy Cloud AI Toolkit
• 4. Visão geral da Web UI do Ostris AI Toolkit (Dashboard, Datasets, New LoRA Job)
• 5. Fundamentos do treinamento LoRA e hiperparâmetros principais no AI Toolkit
• 6. Mapeando conceitos de LoRA para parâmetros do AI Toolkit
• 7. Fluxo rápido: treine um LoRA utilizável no Ostris AI Toolkit
• 8. Troubleshooting do treinamento LoRA no AI Toolkit: erros comuns e correções

1. O que é o Ostris AI Toolkit? (treinador LoRA para modelos de difusão)

Ostris AI Toolkit é uma suíte de treinamento focada em modelos de difusão para imagens e vídeos. Ele não cobre modelos de linguagem nem de áudio; tudo que ele suporta é um modelo de difusão estilo DDPM (por exemplo SD 1.5 ou SDXL) ou um diffusion‑transformer moderno como Flux, Wan, Qwen‑Image, Z‑Image ou OmniGen2. O toolkit é construído em torno de adaptadores do tipo LoRA: na prática, quando você faz fine‑tuning com AI Toolkit, você não está re‑treinando a rede inteira, e sim treinando pequenas LoRAs (ou adaptadores leves similares) sobre um modelo base congelado.

Principais recursos do Ostris AI Toolkit para treinamento de LoRA

O AI Toolkit fornece um motor de treinamento e um sistema de configuração comum para todas as famílias suportadas. Cada modelo (Flux, Z‑Image Turbo, Wan 2.2, Qwen‑Image, SDXL, etc.) tem seu preset, mas todos se encaixam na mesma estrutura: carregamento do modelo, quantização, definição do adaptador LoRA/LoKr, hiperparâmetros de treino, tratamento do dataset e regras de sampling. Por isso a Web UI é consistente, seja para treinar uma LoRA de Flux, uma LoRA de Z‑Image Turbo ou uma LoRA de vídeo de Wan.

Além do motor, o AI Toolkit vem com CLI e Web UI completa. A CLI roda jobs a partir de YAML; a Web UI é uma camada gráfica sobre esses YAMLs. Na UI, “AI Toolkit” geralmente significa a tela de New Job: você escolhe a família do modelo, o tipo de LoRA e o rank, define learning rate e steps, conecta um ou mais datasets e define com que frequência gerar samples. Há painéis dedicados (Job, Model, Quantization, Target, Training, Regularization, Datasets, Sample), então raramente você precisa mexer no YAML. O fluxo é o mesmo localmente ou no RunComfy Cloud AI Toolkit.

---

Ferramentas integradas para treinamento de LoRA no Ostris AI Toolkit

O AI Toolkit traz uma série de recursos “batteries‑included”:

• Quantização e modos de baixa VRAM – quantização configurável do transformer (8/6/4 bits e 3‑bit com recovery adapters) + offloading, para treinar modelos grandes (Flux/Wan) em GPUs de 24–48GB, controlando trade‑offs de qualidade/velocidade.
• Adaptadores LoRA / LoKr – suporte a LoRA padrão e LoKr (mais compacto, mas nem sempre universalmente compatível), selecionável via Target Type.
• Differential Output Preservation (DOP) – loss de regularização que compara saída do modelo base vs com LoRA em imagens de regularização e penaliza mudanças indesejadas, reduzindo “bleeding”.
• Differential Guidance para modelos turbo – opção muito usada em Z‑Image Turbo para focar o update no “que deve mudar” vs base, ajudando adaptação em modelos few‑step/turbo.
• Treino multi‑stage por ruído – etapas de alto/baixo ruído para equilibrar estrutura e detalhe.
• Cache de latentes e embeddings de texto – Cache Latents e Cache Text Embeddings trocam disco por velocidade/VRAM.
• EMA – média móvel exponencial opcional para estabilizar convergência em datasets pequenos.

---

2. Modelos suportados no Ostris AI Toolkit (Flux, Wan, Z‑Image, Qwen‑Image, SDXL)

O AI Toolkit atualmente suporta:

• Modelos de IMAGEM – imagem única (Flux, Z‑Image Turbo, Qwen‑Image, SD, etc.).
• Modelos de INSTRUÇÃO / EDIÇÃO – edição/instruction following (Qwen‑Image‑Edit, Flux Kontext, HiDream E1).
• Modelos de VÍDEO – text‑to‑video e image‑to‑video (série Wan 2.x).

---

2. Modelos suportados no Ostris AI Toolkit (Flux, Wan, Z‑Image, Qwen‑Image, SDXL)

O AI Toolkit atualmente suporta:

• Modelos de IMAGEM – imagem única (Flux, Z‑Image Turbo, Qwen‑Image, SD, etc.).
• Modelos de INSTRUÇÃO / EDIÇÃO – edição/instruction following (Qwen‑Image‑Edit, Flux Kontext, HiDream E1).
• Modelos de VÍDEO – text‑to‑video e image‑to‑video (série Wan 2.x).

---

3. Instalar o Ostris AI Toolkit localmente e usar o RunComfy Cloud AI Toolkit

3.1 Instalação local (Linux/Windows)

Veja o README oficial no GitHub.

No Linux:

git clone https://github.com/ostris/ai-toolkit.git
cd ai-toolkit

python3 -m venv venv
source venv/bin/activate

# PyTorch com CUDA (ajuste versões se necessário)
pip3 install --no-cache-dir torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 \
  --index-url https://download.pytorch.org/whl/cu126

pip3 install -r requirements.txt

Para iniciar a Web UI:

cd ui
npm run build_and_start

A UI fica em http://localhost:8675. Em máquina remota, defina AI_TOOLKIT_AUTH para proteger o acesso.

---

3.2 Usar o RunComfy Cloud AI Toolkit (sem instalação local)

No modo cloud:

• Tudo roda na nuvem; você só abre o navegador.
• Você pode usar GPUs grandes (80GB/141GB VRAM).
• Datasets/configs/checkpoints ficam no workspace persistente do RunComfy.

Abra aqui: RunComfy Cloud AI Toolkit

---

4. Visão geral da Web UI do Ostris AI Toolkit (Dashboard, Datasets, New LoRA Job)

4.1 Dashboard e Training Queue

O Dashboard mostra status. A Training Queue é onde você:

• acompanha estado do job (queued/running/finished/failed),
• abre logs, para/encerra jobs,
• baixa checkpoints e samples.

---

4.2 Gerenciador de datasets

Em Datasets, você cria datasets nomeados para anexar a jobs, incluindo datasets principais e, se necessário, datasets de regularização para DOP.

---

4.3 New Job: tela principal de configuração

O New Job reúne painéis de Job/Model/Quantization/Target/Save/Training/Regularization/Datasets/Sample.

---

5. Fundamentos do treinamento LoRA e hiperparâmetros principais no AI Toolkit

LoRA adiciona um update de baixo rank aos pesos congelados (W_new = W + alpha A B).

Rank controla capacidade; learning rate/steps controlam intensidade e duração; dataset/captions controlam “o que” o LoRA aprende.

---

6. Mapeando conceitos de LoRA para parâmetros do AI Toolkit

Pontos práticos:

• JOB: Trigger Word pode ser injetado sem editar arquivos.
• MODEL: modelos gated exigem HF_TOKEN.
• QUANTIZATION: 6‑bit no transformer é um bom ponto de partida em 24GB para Flux/Wan.
• TARGET: comece com rank 16; suba só se necessário.
• SAVE: alinhe Save Every e Sample Every.
• TRAINING: AdamW8Bit é padrão forte; ajuste learning rate conforme under/overfitting.
• Text Encoder: Cache Text Embeddings só quando captions não mudam por step (sem DOP/dinâmica).
• DOP: requer dataset com Is Regularization e captions sem trigger.

---

7. Fluxo rápido: treine um LoRA utilizável no Ostris AI Toolkit

1) Prepare dados limpos e variados, com trigger token único.

2) Crie o dataset (cheque contagem/captions/resoluções).

3) No job, foque em: trigger, rank, steps, learning rate, buckets.

4) Use prompts de sample para: ativação, generalização, leak test.

5) Ajuste uma coisa por vez.

---

8. Troubleshooting do treinamento LoRA no AI Toolkit: erros comuns e correções

• Dataset vazio: conferir Datasets e Target Dataset.
• Erro HF: aceitar licença (se gated) + HF_TOKEN no .env.
• CUDA OOM: reduzir buckets/rank, usar Low VRAM/quantização, reduzir sampling/batch.
• Overfitting/leak: escolher checkpoint mais cedo, reduzir steps/rank, aumentar weight decay, ativar DOP com dataset de regularização.