Por que desativar o Gradient Checkpointing causa OOM no AI Toolkit

Se você não tem certeza de por que o Gradient Checkpointing está desativado, a regra mais segura é simples:

Reative-o.

Para os grandes modelos de imagem do AI Toolkit, desativar gradient_checkpointing é uma das formas mais rápidas de transformar um treino estável em um crash de OOM.

Este guia explica:

o que o Gradient Checkpointing faz
por que desativá-lo pode estourar a VRAM
quais famílias de modelos são mais sensíveis
quando é razoável testar GC desativado
o que mudar no lugar se o seu objetivo real é velocidade

Resposta rápida

Gradient Checkpointing é essencialmente uma troca de memória vs velocidade.

Ativado = pico de VRAM mais baixo, geralmente mais seguro
Desativado = pico de VRAM mais alto, às vezes mais rápido, muito mais fácil de dar OOM

Para a maioria dos usuários, especialmente com modelos de imagem grandes, não é um controle de qualidade. É um controle de estabilidade.

Checklist rápido

✅ Clique em Show Advanced
✅ Em train:, confirme que gradient_checkpointing: true
✅ Tente novamente com o mesmo Batch Size e Resoluções primeiro
✅ Se ainda der OOM, reduza o Batch Size e remova o bucket de resolução mais alto
✅ Se o problema real é a amostragem de preview, reduza Sample Width / Height / Sample Steps em vez de desativar GC

1) O que o Gradient Checkpointing realmente faz

Você não precisa dominar a teoria profunda do PyTorch para usá-lo corretamente.

Uma forma prática de entender:

com GC ativado, o AI Toolkit mantém menos dados de ativação intermediários na memória e recalcula parte deles quando necessário
com GC desativado, mais dados ficam residentes na VRAM, permitindo que o treino seja mais rápido se houver memória disponível

Parece inofensivo até você combinar com:

alta resolução
múltiplos buckets de resolução
batch size grande
amostragem custosa
arquiteturas pesadas como Qwen Edit, Z-Image, FLUX / modelos tipo Flex

Aí a margem de memória extra desaparece muito rapidamente.

2) Por que desativar causa OOM "de repente"

Usuários costumam pensar:

"Só mudei uma chave."

Mas essa chave determina quanta memória de ativação é mantida durante o treino.

Uma configuração que era "pesada mas viável" com GC ativado se torna "no limite ou impossível" com GC desativado.

Por isso a falha parece tão abrupta:

mesmo dataset
mesmo modelo
mesmos prompts de preview
mesmo batch size
só GC mudou
agora dá OOM no passo 2, passo 3 ou durante o primeiro preview

3) Famílias de modelos de alto risco com GC desativado

Com base em padrões reais e recorrentes de OOM no AI Toolkit, estas combinações devem ser tratadas como perigosas por padrão:

Família de modelo	Alto risco com GC desativado	Primeira tentativa mais segura
Z-Image	Buckets 1024–1536 com batches maiores	GC ativado, começar conservador, depois escalar
Qwen-Edit	Workflows 1024 com batch maior / múltiplas condições pesadas	GC ativado, Batch Size 1, reduzir carga de preview
FLUX-dev / grandes modelos tipo Flex	batches maiores ou treino multi-bucket de alta resolução	GC ativado, Batch Size 1–4 dependendo da margem

Um modelo mental útil:

Z-Image fica perigoso rapidamente com alta resolução + batch grande + GC desativado
Qwen Edit fica perigoso rapidamente com 1024 + condicionamento pesado + GC desativado
FLUX / tipo Flex ficam perigosos rapidamente com batch grande + GC desativado

4) Onde alterar no RunComfy AI Toolkit

Na interface atual do RunComfy, você pode ver diretamente:

Batch Size
Gradient Accumulation
Steps
Unload TE
Cache Text Embeddings

Porém, gradient_checkpointing é mais fácil de verificar pela configuração avançada.

Passo a passo

Abra seu job
Clique em Show Advanced
Encontre o bloco train:
Defina:

train:
  gradient_checkpointing: true

Salve o job
Tente novamente sem mudar mais nada

Se a mesma configuração funcionar agora, está confirmado que GC era o problema.

5) O que fazer em vez disso se seu objetivo real é velocidade

Muitos usuários desativam GC porque querem treino mais rápido.

Isso é compreensível — mas geralmente é o primeiro experimento de velocidade errado.

Tente estas opções antes de desativar GC:

A. Tornar a amostragem de preview mais barata

No painel Sample:

reduza Width / Height
reduza Sample Steps
aumente Sample Every
ative temporariamente Disable Sampling para verificar a estabilidade do treino

Isso frequentemente proporciona mais ganho prático de velocidade do que buscar uma configuração arriscada com GC desativado.

B. Manter o batch pequeno, escalar com accumulation se necessário

No painel Training:

mantenha Batch Size conservador
aumente Gradient Accumulation apenas se quiser um batch efetivo ligeiramente maior sem um grande salto no pico de VRAM

C. Remover primeiro o bucket mais alto

Em Datasets:

mantenha 512 / 768
reintroduza 1024 / 1536 somente após um treino estável

D. Usar o caminho de baixa memória previsto para o modelo

Para algumas arquiteturas, o caminho correto não é "GC desativado", mas sim:

low_vram: true
quantização específica do modelo
otimização do text-encoder específica do modelo

Siga o guia do modelo, não suposições genéricas.

6) Quando é realmente aceitável testar GC desativado?

Trate GC desativado como um experimento avançado, não como padrão.

Condições razoáveis:

você já tem um treino estável
o Batch Size ainda é conservador
você não está já no limite com o bucket mais alto
os previews são leves ou desativados
você tem margem de VRAM suficiente
está mudando uma variável, não várias

Um bom fluxo de teste:

estabilize o job com GC ativado
mantenha o resto da configuração idêntica
desative GC
observe:

OOM nos primeiros passos
OOM durante amostragem
picos intermitentes de bucket

Se qualquer um desses ocorrer, reative GC e pare por aí.

7) O que GC desativado não é

Gradient Checkpointing não é:

um potencializador mágico de qualidade
uma chave para melhorar semelhança
a primeira solução correta para amostras ruins
um bom primeiro experimento quando você já está em OOM

Se suas amostras estão fracas, verifique:

qualidade do dataset
captions
rank
steps
paridade de preview

Não assuma que GC desativado é a resposta.

8) Perguntas frequentes

Ativar GC prejudica a qualidade da saída?

Na prática, geralmente não é a diferença que os usuários percebem.

A verdadeira troca é principalmente memória vs velocidade.

Ativei GC e ainda tenho OOM. E agora?

Suas próximas alavancas são:

Batch Size
bucket de resolução mais alto
custo da amostragem de preview
para vídeo, Num Frames

Devo alguma vez iniciar um primeiro treino com GC desativado?

Para a maioria dos usuários: não.

Prove a estabilidade primeiro, depois experimente.

Resumo em uma linha

Se você está tendo OOM no AI Toolkit e gradient_checkpointing está desativado, corrija isso primeiro.

GC ativado é o padrão seguro. GC desativado é um experimento avançado de velocidade.