Perché disattivare il Gradient Checkpointing causa OOM in AI Toolkit

Se non hai un motivo ben preciso per cui il Gradient Checkpointing è disattivato, la regola più sicura è semplice:

Riattivalo.

Per i grandi modelli di immagini di AI Toolkit, disattivare gradient_checkpointing è uno dei modi più rapidi per trasformare un addestramento stabile in un crash OOM.

Questa guida spiega:

cosa fa il Gradient Checkpointing
perché disattivarlo può far esplodere la VRAM
quali famiglie di modelli sono le più sensibili
quando è ragionevole testare GC disattivato
cosa cambiare invece se il tuo vero obiettivo è la velocità

Risposta rapida

Il Gradient Checkpointing è principalmente un compromesso memoria vs velocità.

Attivato = picco di VRAM inferiore, generalmente più sicuro
Disattivato = picco di VRAM superiore, a volte più veloce, molto più facile andare in OOM

Per la maggior parte degli utenti, specialmente con modelli di immagini grandi, non è un controllo di qualità. È un controllo di stabilità.

Checklist rapida

✅ Clicca su Show Advanced
✅ Sotto train:, assicurati che gradient_checkpointing: true
✅ Riprova con lo stesso Batch Size e le stesse risoluzioni
✅ Se l'OOM persiste, riduci il Batch Size e rimuovi il bucket di risoluzione più alto
✅ Se il tuo vero problema è il campionamento delle anteprime, riduci Sample Width / Height / Sample Steps invece di disattivare GC

1) Cosa fa realmente il Gradient Checkpointing

Non serve conoscere la teoria PyTorch nel dettaglio per usarlo correttamente.

Un modo pratico di pensarci:

con GC attivato, AI Toolkit conserva meno dati di attivazione intermedi in memoria e ne ricalcola alcuni quando servono
con GC disattivato, più dati rimangono nella VRAM, quindi l'addestramento può essere più veloce se c'è memoria disponibile

Sembra innocuo finché non lo combini con:

alta risoluzione
più bucket di risoluzione
batch size elevato
campionamento costoso
architetture pesanti come Qwen Edit, Z-Image, FLUX / modelli tipo Flex

A quel punto il margine di memoria extra svanisce molto rapidamente.

2) Perché la disattivazione causa OOM "improvviso"

Gli utenti spesso pensano:

"Ho cambiato solo un'impostazione."

Ma quell'impostazione determina quanta memoria di attivazione viene mantenuta durante l'addestramento.

Una configurazione che era "pesante ma funzionante" con GC attivato diventa "al limite o impossibile" con GC disattivato.

Ecco perché il fallimento sembra così improvviso:

stesso dataset
stesso modello
stessi prompt di anteprima
stesso batch size
cambiato solo GC
ora va in OOM allo step 2, step 3 o durante la prima anteprima

3) Famiglie di modelli ad alto rischio con GC disattivato

Basandosi su pattern OOM ricorrenti nel mondo reale con AI Toolkit, queste combinazioni vanno considerate pericolose per impostazione predefinita:

Famiglia di modello	Alto rischio con GC disattivato	Primo tentativo più sicuro
Z-Image	Bucket 1024–1536 con batch elevati	GC attivato, iniziare conservativi, poi scalare
Qwen-Edit	Workflow 1024 con batch elevato / molteplici condizioni pesanti	GC attivato, Batch Size 1, ridurre il carico delle anteprime
FLUX-dev / grandi modelli tipo Flex	batch elevati o addestramento multi-bucket ad alta risoluzione	GC attivato, Batch Size 1–4 a seconda del margine

Un modello mentale utile:

Z-Image diventa rapidamente pericoloso con alta risoluzione + batch grande + GC disattivato
Qwen Edit diventa rapidamente pericoloso con 1024 + condizionamento pesante + GC disattivato
FLUX / tipo Flex diventano rapidamente pericolosi con batch grande + GC disattivato

4) Dove modificarlo in RunComfy AI Toolkit

Nell'interfaccia attuale di RunComfy puoi vedere direttamente:

Batch Size
Gradient Accumulation
Steps
Unload TE
Cache Text Embeddings

Tuttavia, gradient_checkpointing si verifica più facilmente attraverso la configurazione avanzata.

Passo per passo

Apri il tuo job
Clicca su Show Advanced
Trova il blocco train:
Imposta:

train:
  gradient_checkpointing: true

Salva il job
Riprova senza cambiare nient'altro

Se la stessa configurazione ora funziona, hai confermato che GC era il problema.

5) Cosa fare invece se il tuo vero obiettivo è la velocità

Molti utenti disattivano GC perché vogliono un addestramento più veloce.

È comprensibile — ma di solito è il primo esperimento di velocità sbagliato.

Prova queste opzioni prima di disattivare GC:

A. Rendere il campionamento delle anteprime più economico

Nel pannello Sample:

riduci Width / Height
riduci Sample Steps
aumenta Sample Every
attiva temporaneamente Disable Sampling per verificare la stabilità dell'addestramento

Questo spesso offre più velocità pratica rispetto a una configurazione rischiosa con GC disattivato.

B. Mantenere il batch piccolo, scalare con l'accumulation se necessario

Nel pannello Training:

mantieni Batch Size conservativo
aumenta Gradient Accumulation solo se vuoi un batch effettivo leggermente più grande senza un forte aumento del picco VRAM

C. Rimuovere prima il bucket più alto

In Datasets:

mantieni 512 / 768
reintroduci 1024 / 1536 solo dopo un addestramento stabile

D. Usare il percorso a bassa memoria previsto per il modello

Per alcune architetture, la strada corretta non è "GC disattivato", ma:

low_vram: true
quantizzazione specifica del modello
ottimizzazione del text-encoder specifica del modello

Segui la guida del modello, non ipotesi generiche.

6) Quando è davvero accettabile testare GC disattivato?

Tratta GC disattivato come un esperimento avanzato, non come un'impostazione predefinita.

Condizioni ragionevoli:

hai già un addestramento stabile
il Batch Size è ancora conservativo
non sei già al limite con il bucket più grande
le anteprime sono leggere o disattivate
hai abbastanza margine VRAM
stai cambiando una sola variabile, non molte

Un buon flusso di test:

stabilizza il job con GC attivato
mantieni il resto della configurazione identica
disattiva GC
monitora:

OOM nei primi step
OOM durante il campionamento
picchi intermittenti di bucket

Se si verifica uno qualsiasi di questi, riattiva GC e fermati lì.

7) Cosa non è GC disattivato

Il Gradient Checkpointing non è:

un potenziatore magico di qualità
un interruttore per migliorare la somiglianza
la prima soluzione giusta per campioni scadenti
un buon primo esperimento quando sei già in OOM

Se i tuoi campioni sono deboli, controlla:

qualità del dataset
captions
rank
steps
parità delle anteprime

Non dare per scontato che GC disattivato sia la risposta.

8) FAQ

Attivare GC compromette la qualità dell'output?

In pratica, non è di solito il compromesso che gli utenti notano.

Il vero compromesso è principalmente memoria vs velocità.

Ho attivato GC e ho ancora OOM. Che faccio?

Le tue prossime leve sono:

Batch Size
bucket di risoluzione più alto
costo del campionamento delle anteprime
per il video, Num Frames

Dovrei mai iniziare un primo addestramento con GC disattivato?

Per la maggior parte degli utenti: no.

Prima dimostra la stabilità, poi sperimenta.

Riepilogo in una riga

Se stai avendo OOM in AI Toolkit e gradient_checkpointing è disattivato, correggi quello per primo.

GC attivato è l'impostazione sicura predefinita. GC disattivato è un esperimento avanzato di velocità.