Questa pagina è la panoramica del fine‑tuning LoRA con Ostris AI Toolkit. Per una ricetta specifica per modello, vai direttamente a una di queste guide:

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

Alla fine di questa guida dovresti:

• Capire le idee fondamentali dietro l’addestramento LoRA (cosa succede davvero quando fai fine‑tuning).
• Sapere com’è organizzato AI Toolkit e cosa controlla ciascun pannello.
• Capire cosa fanno i parametri chiave (learning rate, rank, steps, noise schedule, DOP, ecc.) per poterli regolare in modo consapevole.
• Essere in grado di addestrare LoRA sia sul tuo computer sia con RunComfy Cloud AI Toolkit, e poi riutilizzarle nei tuoi workflow di generazione.

---

Indice

• 1. Cos’è Ostris AI Toolkit? (trainer LoRA per modelli di diffusione)
• 2. Modelli supportati in Ostris AI Toolkit (Flux, Wan, Z‑Image, Qwen‑Image, SDXL)
• 3. Installare Ostris AI Toolkit in locale e su RunComfy Cloud AI Toolkit
• 4. Panoramica della Web UI di Ostris AI Toolkit (Dashboard, Datasets, New LoRA Job)
• 5. Fondamenti dell’addestramento LoRA e iperparametri principali in AI Toolkit
• 6. Mappare i concetti LoRA sui parametri di AI Toolkit
• 7. Workflow rapido: addestrare una LoRA utilizzabile in Ostris AI Toolkit
• 8. Troubleshooting dell’addestramento LoRA in AI Toolkit: errori comuni e soluzioni

1. Cos’è Ostris AI Toolkit? (trainer LoRA per modelli di diffusione)

Ostris AI Toolkit è una suite di training focalizzata sui modelli di diffusione per immagini e video. Non gestisce modelli di linguaggio o audio; tutto ciò che supporta è o un classico modello di diffusione stile DDPM (come SD 1.5 o SDXL) oppure un moderno diffusion‑transformer come Flux, Wan, Qwen‑Image, Z‑Image o OmniGen2. È costruito attorno ad adattatori in stile LoRA: in pratica, quando fai fine‑tuning con AI Toolkit non stai ri‑addestrando l’intera rete, ma stai addestrando piccole LoRA (o adattatori leggeri simili) sopra un modello base congelato.

Caratteristiche chiave di Ostris AI Toolkit per l’addestramento LoRA

AI Toolkit offre un motore di training comune e un sistema di configurazione condiviso per tutte le famiglie supportate. Ogni modello (Flux, Z‑Image Turbo, Wan 2.2, Qwen‑Image, SDXL, ecc.) ha il suo preset, ma tutti si agganciano alla stessa struttura: caricamento del modello, quantizzazione, definizione dell’adattatore LoRA/LoKr, iperparametri di training, gestione del dataset e regole di sampling. Ecco perché la Web UI è familiare sia che tu stia addestrando una LoRA Flux, una LoRA Z‑Image Turbo o una LoRA video Wan.

Oltre a questo motore, AI Toolkit include sia una CLI sia una Web UI completa. La CLI avvia i job direttamente da config YAML; la Web UI è un livello grafico sopra questi YAML. Nell’UI, “AI Toolkit” di solito significa la schermata New Job, dove scegli la famiglia del modello, il tipo di LoRA e il rank, imposti learning rate e steps, colleghi uno o più dataset e definisci ogni quanto generare sample di immagini o video. Hai pannelli dedicati per Job, Model, Quantization, Target, Training, Regularization, Datasets e Sample, quindi raramente serve toccare YAML “a mano”. Che tu lo esegua in locale o via cloud (ad esempio con RunComfy Cloud AI Toolkit), il workflow è lo stesso.

---

Strumenti integrati di training LoRA in Ostris AI Toolkit

AI Toolkit include diverse funzionalità “batteries‑included” che altrimenti dovresti scriptare o integrare manualmente:

• Quantizzazione e modalità low‑VRAM – quantizzazione configurabile del transformer a 8/6/4 bit (e 3 bit con recovery adapters) più offloading dei layer, così modelli grandi come Flux o Wan diventano addestrabili su GPU da 24–48 GB, con compromessi controllabili tra qualità e velocità.
• Adattatori LoRA / LoKr – supporto per LoRA standard e per LoKr (una variante più compatta ma meno universalmente supportata), selezionabile tramite Target Type, così puoi scegliere tra massima compatibilità e adattatori più piccoli/efficienti.
• Differential Output Preservation (DOP) – una loss di regolarizzazione che confronta output del modello base vs output del modello con LoRA su immagini di regolarizzazione e penalizza cambiamenti indesiderati, riducendo il “bleeding” (quando tutto inizia a sembrare il tuo soggetto).
• Differential Guidance per modelli turbo – un termine di guidance opzionale in training (molto usato per Z‑Image Turbo) che focalizza l’update su “cosa deve cambiare” rispetto al modello base, migliorando l’adattamento su modelli few‑step/turbo senza distruggere i vantaggi di velocità.
• Training multi‑stage sul rumore – fasi separate ad alto rumore e basso rumore per bilanciare apprendimento della struttura grossolana (composizione, posa) e affinamento dei dettagli (texture, bordi).
• Caching di latenti e text embeddings – Cache Latents e Cache Text Embeddings scambiano spazio su disco con velocità e minore VRAM, particolarmente utile su GPU piccole o in sessioni cloud dove vuoi iterare in fretta.
• EMA (Exponential Moving Average) – una copia “smussata” opzionale dei pesi LoRA che può rendere la convergenza più stabile, soprattutto su dataset piccoli.

La Web UI espone queste funzioni tramite controlli chiari e, poiché il layout è coerente tra modelli, una volta che capisci come AI Toolkit addestra una LoRA per una base (per esempio Flux), è facile applicare lo stesso ragionamento a Z‑Image Turbo, Wan, Qwen‑Image e altri modelli di diffusione.

---

2. Modelli supportati in Ostris AI Toolkit (Flux, Wan, Z‑Image, Qwen‑Image, SDXL)

AI Toolkit supporta attualmente le seguenti famiglie di modelli:

• Modelli IMMAGINE – immagini singole (Flux, Z‑Image Turbo, Qwen‑Image, SD, ecc.).
• Modelli ISTRUZIONE / EDIT – editing / instruction‑following (Qwen‑Image‑Edit, Flux Kontext, HiDream E1).
• Modelli VIDEO – text‑to‑video e image‑to‑video (serie Wan 2.x).

---

2. Modelli supportati in Ostris AI Toolkit (Flux, Wan, Z‑Image, Qwen‑Image, SDXL)

AI Toolkit supporta attualmente le seguenti famiglie di modelli:

• Modelli IMMAGINE – immagini singole (Flux, Z‑Image Turbo, Qwen‑Image, SD, ecc.).
• Modelli ISTRUZIONE / EDIT – editing / instruction‑following (Qwen‑Image‑Edit, Flux Kontext, HiDream E1).
• Modelli VIDEO – text‑to‑video e image‑to‑video (serie Wan 2.x).

---

3. Installare Ostris AI Toolkit in locale e su RunComfy Cloud AI Toolkit

3.1 Installare Ostris AI Toolkit in locale su Linux e Windows

Il README ufficiale su GitHub fornisce istruzioni semplici per Linux e Windows.

Su Linux:

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

python3 -m venv venv
source venv/bin/activate

# installa PyTorch con CUDA (aggiusta la versione se serve)
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

Su Windows, puoi seguire lo stesso schema con python -m venv venv e .\venv\Scripts\activate, oppure usare lo script batch della community AI‑Toolkit Easy Install, che incapsula l’intero processo in un clic e apre automaticamente la UI nel browser (versione più recente).

Per avviare la Web UI una volta installate le dipendenze:

cd ui
npm run build_and_start

L’interfaccia sarà disponibile su http://localhost:8675. Se la esegui su una macchina remota, imposta prima AI_TOOLKIT_AUTH con una password, così solo tu potrai accedere (vedi note di sicurezza nel repository GitHub di AI Toolkit).

---

3.2 Usare RunComfy Cloud AI Toolkit per addestrare LoRA (senza setup locale)

Se non vuoi gestire driver GPU, CUDA o installazioni locali, puoi usare RunComfy Cloud AI Toolkit. In questa modalità:

• AI Toolkit gira completamente in cloud – apri il browser e sei nella UI.
• Hai accesso a GPU potenti (80 GB e 141 GB di VRAM), ideali per training pesanti su FLUX, Qwen‑Image, Z‑Image Turbo o Wan.
• Dataset, config, checkpoint e job passati restano in un workspace persistente legato al tuo account RunComfy.
• Training, playground per testare i modelli e workflow ComfyUI vivono in un unico posto.

Aprilo direttamente qui: Cloud AI Toolkit su RunComfy

---

4. Panoramica della Web UI di Ostris AI Toolkit (Dashboard, Datasets, New LoRA Job)

Quando apri la Web UI (in locale o su RunComfy), la sidebar sinistra contiene poche pagine ma importanti:

4.1 Dashboard e Training Queue

La Dashboard mostra i job attivi e recenti a colpo d’occhio. È soprattutto una pagina di stato rapido.

La pagina Training Queue è dove puoi:

• vedere lo stato di ogni job (queued, running, finished, failed),
• aprire i log per fare debug,
• fermare o cancellare job,
• scaricare checkpoint di output e sample.

Pensala come il “centro di controllo dei job”. Ogni LoRA che addestri comparirà qui.

---

4.2 Gestore dataset

La pagina Datasets ti permette di definire dataset con un nome che poi puoi collegare ai job:

• selezioni o carichi cartelle di immagini o clip video,
• la UI li scansiona e mostra risoluzioni, conteggi e quante caption / entry metadata esistono,
• ogni dataset riceve un nome interno che poi appare nel menu Target Dataset.

Qui crei:

• dataset principali di training (personaggio, stile, prodotti),
• dataset opzionali di regolarizzazione (altre persone, altri camion, background generici, ecc.) per DOP o regolarizzazione classica.

---

4.3 New Job: la schermata centrale di configurazione LoRA

La pagina New Job è il cuore di AI Toolkit. Un job è essenzialmente:

Addestra una LoRA di tipo X sul modello Y, usando il dataset Z, con questi iperparametri.

La schermata è divisa in pannelli:

• JOB – naming e scelta GPU.
• MODEL – quale modello base fare fine‑tuning.
• QUANTIZATION – quanto viene compresso il modello base.
• TARGET – LoRA vs LoKr e rank.
• SAVE – precisione e frequenza di salvataggio.
• TRAINING – learning rate, steps, optimizer, schedule dei timesteps.
• ADVANCED / Regularization – EMA, Differential Guidance, DOP.
• DATASETS – quali dataset usare e come.
• SAMPLE – ogni quanto generare sample durante il training.

Il resto di questa guida serve soprattutto a collegare questi pannelli ai concetti base della LoRA.

---

5. Fondamenti dell’addestramento LoRA e iperparametri principali in AI Toolkit

Prima di toccare i controlli, è utile avere un modello mentale di cosa sta facendo LoRA “sotto al cofano”.

5.1 Come funziona LoRA nei modelli di diffusione

Un modello di diffusione moderno è in gran parte uno stack di blocchi transformer con grandi matrici di peso. Nel fine‑tuning classico aggiorneresti direttamente tutti questi pesi, cosa costosa e facile da overfittare.

In tutti i modelli supportati (Flux, Z‑Image Turbo, Wan, Qwen‑Image), il backbone è un grande diffusion‑transformer. LoRA non sostituisce la matrice di peso originale W; aggiunge un piccolo update low‑rank costruito da due matrici apprese A e B. Puoi pensarlo così: W_new = W + alpha A B, dove W è congelata, A e B sono matrici piccole addestrabili, e alpha è un fattore di scala che controlla quanto è forte l’update LoRA in inferenza.

Il rank determina la “larghezza” di A e B e quindi quanto complesso può essere l’update. Un rank più alto rende la LoRA più espressiva ma anche più pesante (parametri e compute). Un rank più basso produce un adattatore più piccolo e focalizzato, e in genere è più difficile da overfittare.

---

5.2 Iperparametri chiave della LoRA spiegati

Questi nomi compaiono in ogni trainer; AI Toolkit li rende semplicemente più chiari.

Learning Rate (Learning Rate)

• Controlla quanto grande è il passo nello spazio dei parametri a ogni update dell’optimizer.
• Troppo basso: training lento e potrebbe non adattarsi bene al dataset.
• Troppo alto: la loss oscilla o esplode e la LoRA diventa rumorosa/instabile o fortemente overfittata.

Per le LoRA di diffusione, 0.0001 è un default molto sensato. Molte config pubblicate per Wan e Flux stanno tra 0.0001 – 0.0002.

---

Batch Size e Gradient Accumulation

• Batch Size è quante immagini/clip il modello vede in parallelo per ogni calcolo del gradiente.
• Gradient Accumulation significa “accumula gradienti per N batch prima di applicare un update”, simulando un batch più grande senza usare più VRAM.

Il batch effettivo è: Batch Size × Gradient Accumulation

Un batch effettivo più alto dà gradienti più stabili e spesso migliore generalizzazione, ma costa più compute. Molti usano Batch Size = 1 e Gradient Accumulation = 2–4 su GPU da 24 GB.

---

Steps (Steps)

È il numero di update dell’optimizer. È la manopola principale per “quanto a lungo addestrare”.

• Troppi pochi steps → underfitting: la LoRA quasi non cambia il modello base.
• Troppi steps → overfitting: la LoRA memorizza e “sanguina” ovunque.

Il numero giusto dipende da: dimensione del dataset, varietà, rank, learning rate.

Per LoRA tipiche di personaggi (20–50 immagini) su modelli moderni, 2 000–3 000 steps è un buon intervallo iniziale.

---

Rank (Linear Rank)

• Il rank determina quanti gradi di libertà ha la LoRA.
• Raddoppiare il rank raddoppia grossomodo capacità e numero di parametri.

Intuizione pratica:

• Rank 16–32 basta per la maggior parte di personaggi e stili su modelli grandi come Flux o Wan.
• Rank più alti overfittano più facilmente dataset piccoli; rank più bassi costringono a generalizzare.

---

Weight Decay (Weight Decay)

Il weight decay è una tecnica di regolarizzazione: tira delicatamente i pesi verso zero a ogni step.

• Riduce la probabilità che la LoRA “scatti” verso valori estremi che ricreano perfettamente i training set ma non generalizzano.
• Valori come 0.0001 sono comuni e di solito sicuri. Raramente serve toccarlo finché non vedi overfitting evidente.

---

Timestep schedule

I modelli di diffusione imparano a denoisare su un range di livelli di rumore. Scegli quali timesteps campionare più spesso:

• Rumore alto: struttura grossolana, composizione, forme grandi.
• Rumore basso: texture e dettagli fini.
• Rumore medio: dove struttura e dettaglio si incontrano; ottimo per volti/personaggi.

I parametri Timestep Type e Timestep Bias in AI Toolkit sono controlli UI per questo scheduling, che analizzeremo nella sezione parametri.

---

Composizione del dataset e caption

Anche con iperparametri perfetti, dati scarsi producono una LoRA scarsa:

• Usa immagini pulite e varie che rappresentano tutte lo stesso concetto (stessa persona, stessa marca, stesso stile) ma con pose, luci e background diversi.
• Le caption dovrebbero legare chiaramente un trigger word unico al concetto, così puoi attivare la LoRA dopo senza competere con significati già presenti nel modello base.

Per LoRA video (Wan, HiDream E1) la logica è identica, ma con clip corti invece di immagini singole, e il frame sampling diventa parte del design del dataset.

---

6. Mappare i concetti LoRA sui parametri di AI Toolkit

Ora percorriamo la schermata New Job pannello per pannello e colleghiamo ogni parametro ai concetti precedenti.

6.1 Pannello JOB: progetto, GPU e trigger word

Il pannello JOB è semplice ma importante:

Training Name - è l’etichetta del job e diventa parte dei nomi delle cartelle/file di output. Molti includono modello + trigger, ad esempio flux_dev_skschar_v1.

GPU ID - su installazione locale seleziona la GPU fisica. Nel cloud AI Toolkit su RunComfy, lascialo di default: il tipo reale di GPU (H100 / H200, ecc.) viene scelto più tardi quando avvii il job dalla Training Queue.

Trigger Word - se inserisci una parola qui, AI Toolkit la preporrà a tutte le caption del dataset durante il training (senza modificare in modo permanente i file). È utile se le caption non hanno un trigger consistente. Usa un token inventato che il modello base non conosce (es. sks_char_neo), così la LoRA non compete con significati già presenti.

---

6.2 Pannello MODEL: scegliere e caricare il modello base

Model Architecture è dove scegli dalla lista (Flux, Z‑Image Turbo, Wan 2.2, Qwen‑Image, ecc.). Quando ne scegli uno:

• AI Toolkit carica un preset adatto a quel modello: sampler, default del noise schedule e talvolta percorsi di adattatori.

Name or Path è l’id Hugging Face (repo id) del checkpoint base.

• Nella maggior parte dei build, scegliendo Model Architecture l’id consigliato viene autocompilato: lascialo così a meno che tu non abbia un motivo per cambiarlo.
• Se lo sovrascrivi, usa il formato org-o-user/model-name (opzionalmente org-o-user/model-name@revision).

Se il modello è gated (Flux.1‑dev, Flux.2‑dev, alcune varianti Wan, ecc.), devi accettare la licenza e impostare HF_TOKEN in un file .env perché AI Toolkit possa scaricarlo.

A seconda del modello, vedrai anche opzioni come Low VRAM o Layer Offloading qui o in pannelli vicini:

• Low VRAM comprime/offloada parti del modello per farlo entrare in GPU più piccole, a costo di velocità.
• Layer Offloading sposta aggressivamente parti tra CPU e GPU; usalo solo se Low VRAM non basta, perché può essere più lento e talvolta meno stabile.

Questi switch non cambiano cosa impara la LoRA; cambiano solo come AI Toolkit impacchetta il modello in memoria, scambiando velocità/stabilità con la possibilità di entrare nel tuo hardware.

---

6.3 Pannello QUANTIZATION: precisione vs VRAM

Il pannello QUANTIZATION di solito include:

• Transformer (es. float8, 6-bit, 4-bit, 3-bit ARA),
• Text Encoder (tipicamente float8 (default)).

Cosa significano:

• Il transformer è la parte grande che processa i latenti e la cross‑attention con il testo.
• Il text encoder trasforma i prompt in embeddings.

Quantizzare il transformer:

• float8 è il più sicuro e preciso; usa più VRAM ma con perdita minima di qualità.
• 6-bit è un ottimo compromesso per 24 GB: piccolo calo di qualità per un buon risparmio.
• 4-bit e 3-bit ARA sono più aggressivi; 3-bit ARA combina pesi a 3 bit con un accuracy recovery adapter che recupera parte della precisione.

Quantizzare il text encoder:

• È molto più piccolo, quindi in genere resta a float8.
• In setup avanzati lo si congela o lo si unload (vedi Unload TE e Cache Text Embeddings), quindi la quantizzazione conta meno.

Praticamente:

• Su una GPU da 24 GB per Flux/Wan, Transformer = 6-bit, Text Encoder = float8 è un punto di partenza molto valido.
• Se hai 48 GB+, tieni float8 ovunque salvo bisogno di memoria per risoluzioni molto alte o molti frame.

---

6.4 Pannello TARGET: tipo di LoRA e rank

Il pannello TARGET descrive l’adattatore che stai addestrando:

• Target Type - di solito LoRA. Alcuni build mostrano anche LoKr (Low‑Rank Kronecker), una variante più compatta ma non universalmente supportata. Per massima compatibilità—specie se vuoi usare la LoRA in molte configurazioni ComfyUI o Automatic1111—LoRA è il default più sicuro.
• Linear Rank - è il rank LoRA: più alto = più capacità, file più grande, più VRAM, più rischio di overfitting su dataset piccoli. Intuizione per diffusion‑transformer moderni (Flux, Z‑Image Turbo, Wan 2.x, Qwen‑Image, OmniGen2, Chroma, Lumina2, ecc.):
• 8–16: compatto e generalizza bene. Ottimo punto di partenza per basi forti come Z‑Image Turbo e molte config SDXL/SD 1.5, soprattutto con dataset piccoli (5–40 immagini o pochi clip).
• 16–32: range tipico per LoRA stile/personaggio su modelli grandi come Flux, Wan 2.x e Qwen. In pratica inizi spesso a 16 e sali a 32 solo se hai abbastanza dati e la LoRA è ancora troppo debole.
• 64+: raramente necessario.

Su SD 1.5 / SDXL potresti anche vedere Conv Rank (rank convoluzionale), più focalizzato su texture/stile. Un Conv Rank alto enfatizza come viene renderizzata l’immagine (pennellate, pattern di rumore), mentre Linear Rank tende a influenzare cosa c’è nell’immagine.

---

6.5 Pannello SAVE: precisione dei checkpoint e frequenza di salvataggio

SAVE controlla come vengono scritti i checkpoint LoRA:

• Data Type
• BF16 (bfloat16) è un ottimo default: stabile ed efficiente.
• FP16 è leggermente più preciso, ma di solito non si nota.
• FP32 è molto preciso e molto pesante; usalo solo se sai che ti serve.
• Save Every

  Numero di steps tra i checkpoint. Se imposti Save Every = 250 e Steps = 3000, potresti ottenere 12 checkpoint (ma vedi il campo successivo). Di solito conviene che Save Every coincida con Sample Every nel pannello SAMPLE, così ogni checkpoint ha preview corrispondenti.

• Max Step Saves to Keep

  Quanti checkpoint mantenere su disco. Se è 4, vengono conservati solo i 4 più recenti; i più vecchi vengono eliminati per risparmiare spazio.

---

6.6 Pannello TRAINING: optimizer, steps e noise schedule

Batch Size e Gradient Accumulation

Come detto prima:

• Batch Size = immagini/clip per forward pass.
• Gradient Accumulation = quante di queste passate accumuli prima di un update dell’optimizer.

Se la VRAM è stretta, puoi fare:

• Batch Size = 1, Gradient Accumulation = 4 → si comporta come batch 4 ma richiede quattro volte più passate.

Assicurati che il batch effettivo non sia più grande del tuo dataset: non vuoi simulare 16 immagini per step se in totale ne hai 10.

---

Steps

È il totale di steps dell’optimizer, non “epoch”.

• 2000–3000 steps è spesso una baseline per LoRA Flux/Qwen/Z‑Image Turbo/OmniGen2/Chroma (e molte LoRA Wan 2.x) con dataset da 20–50 immagini o clip piccoli.

Spesso è meglio addestrare un po’ meno e tenere un checkpoint intermedio buono che spingere a counts assurdi sperando che l’ultimo sia il migliore.

---

Optimizer (Optimizer)

Tipicamente vedrai:

• AdamW8Bit – AdamW con stati dell’optimizer a 8 bit. Risparmia memoria e funziona molto bene su dataset piccoli/medi.
• Adafactor – più efficiente in memoria e scala a dataset enormi, ma può essere più difficile da tarare.

Per la maggior parte delle LoRA in AI Toolkit, AdamW8Bit è la scelta giusta, a meno che tu non stia andando in OOM sugli stati dell’optimizer.

---

Learning Rate

Un buon default è 0.0001. Se:

• la LoRA sembra non imparare quasi nulla, prova 0.00015–0.0002,
• vedi overfitting rapido o sample rumorosi, prova 0.00005–0.00008.

Evita di saltare subito a valori alti come 0.0005 a meno che una guida specifica del modello non lo consigli.

---

Weight Decay

Come detto, 0.0001 è un default “gentile”. Se la LoRA sta chiaramente memorizzando immagini anche con steps moderati, aumentarlo leggermente è uno degli strumenti disponibili.

---

Timestep Type e Timestep Bias

Questi due parametri modellano quali timesteps vengono privilegiati.

• Timestep Type può essere:
• Linear – campiona timesteps in modo uniforme.
• Sigmoid – concentra sui timesteps medi (buono per volti/personaggi).
• Weighted o altri preset – schedule specifici per modello.
• Timestep Bias può essere:
• Balanced – nessun bias extra.
• High Noise – sposta verso timesteps iniziali (latenti molto rumorosi); enfatizza struttura e composizione.
• Low Noise – sposta verso timesteps finali (quasi pulito); enfatizza dettagli fini.

Per LoRA di personaggi su modelli FlowMatch, Weighted + Balanced è un ottimo punto di partenza: la LoRA impara dove il modello è “a metà” del denoise, che spesso corrisponde a ciò che vedi in inferenza.

---

Sampler / Noise Type in training

Sui vecchi modelli SD, AI Toolkit usa sampler in stile DDPM; sui modelli FlowMatch (Flux, Z‑Image Turbo, Wan 2.x) usa FlowMatch di default. In genere non devi cambiarlo: il preset imposta sampler e schedule corretti.

---

EMA (Exponential Moving Average)

• Use EMA attiva una copia smussata dei pesi LoRA nel tempo.
• Se attivo, EMA Decay (es. 0.99) controlla quanto velocemente EMA “dimentica” update precedenti:
• 0.9 = reagisce più rapidamente, meno smooth.
• 0.99 = più smooth.
• 0.999+ = molto smooth ma più lento ad adattarsi.

EMA può migliorare la stabilità su dataset piccoli ma consuma memoria extra. Su VRAM stretta è ragionevole lasciarlo off a meno che una guida non lo consigli.

---

Ottimizzazioni del Text Encoder

• Unload TE – scarica il text encoder dalla VRAM tra gli step. Risparmia memoria ma costringe a ricaricare spesso, e può essere lento su HDD.
• Cache Text Embeddings – esegue il text encoder una volta per caption e salva gli embeddings; gli step successivi li riusano. Scambia spazio su disco con velocità/VRAM.

Per la maggior parte dei workflow:

• Se hai VRAM sufficiente: lascia entrambi off.
• Se la VRAM è stretta ma hai un SSD veloce e le caption sono effettivamente statiche (niente DOP, niente riscrittura dinamica del trigger, niente dropout che dipende da cambi di testo per step): attiva Cache Text Embeddings.
• Se usi funzionalità che modificano i prompt a ogni step — per esempio DOP, sostituzione dinamica del trigger nelle caption, o setup che dipendono da dropout per‑step — lascia Cache Text Embeddings = OFF, così il text encoder ricodifica il prompt reale a ogni batch.
• Usa Unload TE solo quando è davvero necessario (per LoRA molto “trigger‑only” dove le caption vengono ignorate), perché di fatto disabilita l’addestramento basato sulle caption.

---

6.7 Pannello ADVANCED / Regularization: DOP e Differential Guidance

Differential Output Preservation (Differential Output Preservation)

Quando lo attivi, stai chiedendo ad AI Toolkit di:

1. Eseguire sia il modello base sia il modello con LoRA su un set di immagini di regolarizzazione.
2. Aggiungere un termine di loss che penalizza la LoRA quando cambia output che dovrebbero restare invariati.

Controlli:

• DOP Loss Multiplier – quanto pesa questa loss; 0.1–1.0 è tipico. 1.0 significa “prendi la preservazione molto sul serio”.
• DOP Preservation Class – un’etichetta testuale che descrive cosa stai proteggendo, ad esempio "person" o "truck". Aiuta il text encoder a interpretare le caption di regolarizzazione.

Per usare DOP in modo efficace devi:

• avere almeno un dataset marcato come Is Regularization nel pannello DATASETS,
• captionare quelle immagini senza il trigger word (sono esempi “generici”).

Buoni scenari per DOP:

• La LoRA personaggio rende tutte le persone simili al tuo soggetto.
• La LoRA prodotto trasforma tutti i loghi nel tuo brand anche senza trigger word.

Blank Prompt Preservation è una variante in cui la regolarizzazione usa prompt vuoti, incoraggiando la LoRA a non disturbare il comportamento “senza prompt”.

---

Do Differential Guidance (Do Differential Guidance)

Usato principalmente per LoRA Z‑Image Turbo:

• AI Toolkit confronta output del modello base e del modello adattato e usa un segnale di differenza per focalizzare cosa dovrebbe cambiare la LoRA.
• Differential Guidance Scale controlla quanto questa differenza influenza gli update; la guida di Hugging Face su Z‑Image Turbo include valori di esempio che funzionano bene nella pratica.

Abilitare Differential Guidance:

• aiuta le LoRA Z‑Image Turbo ad adattarsi in profondità nonostante la distillazione few‑step,
• funziona meglio insieme a text embeddings in cache e learning rate/steps ben tarati.

Per modelli non‑turbo (Flux, Qwen, SDXL), di solito lo lasci off a meno che un tutorial specifico non lo consigli.

---

6.8 Pannello DATASETS: su cosa addestri davvero

Ogni blocco dataset nel pannello DATASETS corrisponde a un dataset definito nella pagina Datasets.

Campi chiave:

• Target Dataset – quale dataset questo blocco sta usando.
• LoRA Weight – importanza relativa di questo dataset rispetto ad altri nello stesso job.
• Default Caption – caption di fallback quando un’immagine non ha un file caption.
• Caption Dropout Rate
• Num Frames (per modelli video)
• Cache Latents
• Is Regularization
• Flip X, Flip Y
• Resolutions (bucket 256–1536)

Cosa significano in pratica:

• Combinare dataset con LoRA Weight

  Se hai più dataset (per esempio “close‑up” e “full‑body”), puoi bilanciarli con LoRA Weight. Un dataset con peso 2 viene campionato circa il doppio rispetto a uno con peso 1.

• Default Caption e Caption Dropout Rate
• Default Caption è utile se ti sei dimenticato di captionare alcune immagini e vuoi almeno una descrizione minimale (incluso il trigger).
• Caption Dropout Rate rimuove o svuota casualmente le caption per una parte degli esempi:
• vicino a 0 → la LoRA impara una forte dipendenza dalla caption,
• vicino a 1 → la LoRA si comporta più come uno stile “sempre attivo”.
• Is Regularization

  Attivalo quando il dataset deve essere usato per DOP/regolarizzazione, non come dati principali. Queste immagini non dovrebbero contenere il trigger e di solito coprono esempi generici (altre persone, altri camion, ecc.).

• Cache Latents

  Se attivo, AI Toolkit pre‑calcola i latenti e li salva; gli step successivi non devono ri‑codificare ogni immagine. Il training accelera, ma l’uso disco aumenta molto: centinaia o migliaia di immagini ad alta risoluzione possono consumare decine di GB. Potresti dover pulire manualmente questi latenti se non vuoi che restino.

• Num Frames (solo video)

  Per LoRA Wan/HiDream, decide quanti frame vengono campionati da ogni clip durante il training. Più frame → migliore apprendimento del movimento ma più VRAM; i preset di solito scelgono valori sensati.

• Flip X e Flip Y

  Data augmentation automatica:

• Flip X (flip orizzontale) raddoppia il dataset ma specchia tutto, inclusi dettagli asimmetrici e testo.
• Flip Y (flip verticale) raramente ha senso su immagini realistiche.
• Resolutions

  Definiscono in quali dimensioni AI Toolkit “bucketizza” le immagini. Fa solo downscale; non fa mai upscale. Se attivi 768 e 1024:

• 900×900 → ridotto a 768×768.
• 1200×1200 → ridotto a 1024×1024.

---

6.9 Pannello SAMPLE: vedere la LoRA imparare in tempo reale

Il pannello SAMPLE definisce come AI Toolkit genera preview durante il training.

Campi principali:

• Sample Every – quanti steps tra i preview.
• Sampler – FlowMatch o DDPM, a seconda del modello.
• Width / Height – risoluzione del preview.
• Seed e Walk Seed.
• Guidance Scale.
• Num Frames e FPS (per preview video).
• Sample Steps.
• Toggle avanzati: Skip First Sample, Force First Sample, Disable Sampling.

Sotto puoi aggiungere più Sample Prompts, ognuno con testo del prompt, risoluzione/seed opzionali, LoRA Scale e opzionalmente un’immagine di controllo.

Come si collega al training:

• Sample Every vs Save Every: è meglio che coincidano, così ogni checkpoint salvato ha preview corrispondenti. Se ne cambi uno, cambia anche l’altro.
• Sampler: resta sul sampler raccomandato dal preset:
• FlowMatch per Flux, Z‑Image Turbo, Wan, OmniGen2, ecc.
• DDPM per SD 1.5 / SDXL.
• Risoluzione e steps dei preview
• 1024×1024 con Sample Steps = 20–25 dà preview chiare senza essere troppo lento per la maggior parte dei modelli immagine.
• Per video, più Num Frames/FPS danno preview più realistiche ma costose; i preset sono in genere tarati.
• Seed e Walk Seed
• Un Seed fisso con Walk Seed disattivato significa che ogni checkpoint usa esattamente lo stesso rumore, quindi puoi confrontare direttamente l’evoluzione.
• Attivare Walk Seed incrementa il seed per prompt, aggiungendo varietà. Bello per “sfogliare”, ma un po’ più difficile da confrontare step‑per‑step.

In pratica molti utenti:

• tengono Sample Every = Save Every = 250,
• impostano 3–6 prompt di sample che coprono i casi d’uso,
• mantengono almeno un prompt a seed fisso per confrontare i checkpoint in modo coerente.

---

7. Workflow rapido: addestrare una LoRA utilizzabile in Ostris AI Toolkit

Questa sezione è intenzionalmente compatta. Conosci già cosa significa ogni impostazione dalle sezioni 5–6: ecco il workflow più breve che produce in modo affidabile una buona LoRA in Ostris AI Toolkit senza ritoccare dieci cose insieme.

7.1 Prepara i dati (la parte che non puoi “aggiustare con le impostazioni”)

• Usa prima un dataset piccolo e pulito (LoRA immagine: ~20–50 immagini solide; LoRA video: pochi clip corti di alta qualità).
• Scegli un trigger token unico (parola inventata) e mantienilo consistente nelle caption, oppure usa l’iniezione a livello job.
• Punta alla varietà, non al volume: pose, luci, background e composizioni diverse, mantenendo costante il concetto centrale.

Opzionale (solo se ti aspetti “bleeding”):

• Prepara un dataset di regolarizzazione (stessa classe, identità/oggetti diversi) senza il trigger token — lo userai solo se in seguito abiliti DOP.

---

7.2 Crea un dataset in Ostris AI Toolkit

Nella UI di Ostris AI Toolkit:

1. Vai su Datasets → New Dataset.
2. Carica immagini/clip + caption (o metadata).
3. Sanity check rapido prima di addestrare:
• il conteggio è corretto,
• le caption vengono rilevate (o stai usando intenzionalmente default caption / iniezione trigger),
• le risoluzioni sono ragionevoli per i bucket scelti.

---

7.3 Crea un nuovo job: parti dai preset e cambia solo 5 cose

Apri New Job e scegli la famiglia corretta (o segui la ricetta specifica se addestri FLUX.2, Z‑Image Turbo, Qwen‑Image‑Edit o video Wan).

Ora concentrati solo su questi controlli ad alto impatto:

1) Comportamento del trigger

• Se le caption contengono già il trigger: lascia vuoto il trigger del job.
• Se non lo contengono: imposta Trigger Word così viene preposto automaticamente.

2) Capacità della LoRA

• Inizia con Rank 16 per la maggior parte dei concetti personaggio/stile.
• Passa a Rank 32 solo se la LoRA è ancora troppo debole dopo un run ragionevole (o se hai un dataset più grande e vario).

3) Durata del training

• Inizia con 2 000–3 000 steps per una LoRA tipica da 20–50 immagini.

  (Stai cercando il miglior checkpoint, non “finire il massimo”.)

4) Learning rate

• Usa un default conservativo come 0.0001 a meno che una ricetta specifica del modello dica il contrario.

5) Bucket di risoluzione (e realtà VRAM)

• Scegli un bucket “comfort” che la tua GPU regge in modo consistente (comune: 768 o 1024 per modelli immagine moderni).
• Aggiungi bucket più alti solo se hai margine VRAM e sai che ti servono.

Due piccole abitudini che fanno risparmiare ore:

• Imposta Save Every = Sample Every (es. ogni 250 steps), così ogni checkpoint ha preview corrispondenti.
• Usa almeno un prompt di sample a seed fisso, per confrontare checkpoint “mele con mele”.

---

7.4 Sampling che ti aiuta davvero a scegliere il checkpoint giusto

Invece di molti prompt, usane tre: diagnosticano il 90% dei problemi:

• Prompt di attivazione (con trigger): dimostra che la LoRA “si accende”.
• Prompt di generalizzazione (con trigger, attributi diversi): controlla la flessibilità oltre le caption del training.
• Leak test (senza trigger): controlla se la LoRA “hijacka” il modello base.

Se il leak test inizia a spostarsi verso il tuo concetto, sei oltre il punto dolce: scegli un checkpoint precedente.

---

7.5 Diagnosi rapida: cambia una manopola, non dieci

Quando i risultati non sono giusti, modifica una sola di queste cose alla volta:

• Troppo debole / quasi non si attiva → aumenta prima gli steps, poi valuta il rank.
• Troppo forte / overfit / leak senza trigger → usa prima un checkpoint precedente, poi riduci steps (o rank).

  Se continua a “bleedare”: abilita DOP con un dataset di regolarizzazione adeguato.

• OOM / VRAM instabile → abbassa prima bucket/risoluzione, poi riduci rank; solo dopo usa opzioni più aggressive di risparmio memoria.

---

7.6 Esporta e usa la tua LoRA

Dalla Training Queue o dalla cartella di output di AI Toolkit:

• Scarica il checkpoint migliore (un file LoRA .safetensors).
• Se usi RunComfy Cloud AI Toolkit, questi file LoRA verranno anche salvati nella pagina Custom Models, dove puoi copiare il link del modello, scaricarli e testarli nel playground o in ComfyUI.

---

8. Troubleshooting dell’addestramento LoRA in AI Toolkit: errori comuni e soluzioni

Dataset non trovato o vuoto

Sintomi:

• Il job termina subito.
• I log menzionano “no images found” o simili.

Controlli:

• In Datasets, conferma che il dataset mostri il conteggio atteso.
• Assicurati che Target Dataset nel job punti al dataset corretto.
• Se usi metadata JSONL, verifica che il file sia presente e formattato correttamente.

---

Download del modello base / errori Hugging Face

Sintomi:

• Errori 403/404 durante il download.
• Log che indicano accesso mancante.

Soluzioni:

• Accetta la licenza su Hugging Face se il modello è gated (Flux dev, alcune varianti Wan, ecc.).
• Aggiungi HF_TOKEN=your_read_token in un file .env nella root di AI Toolkit.

---

CUDA out‑of‑memory durante training o sampling

Sintomi:

• Errori “CUDA out of memory” all’avvio del job o durante la generazione dei sample.

Opzioni:

• In DATASETS:
• Disabilita alte risoluzioni (1280, 1536) e resta su 768/1024.
• In TARGET:
• Abbassa Linear Rank (32 → 16).
• In QUANTIZATION / MODEL:
• Attiva Low VRAM.
• Usa quantizzazione più aggressiva del transformer (float8 → 6‑bit).
• In TRAINING:
• Riduci Batch Size o Gradient Accumulation.
• In SAMPLE:
• Abbassa risoluzione preview e Sample Steps,
• Riduci Num Frames per preview video.

Se stai usando RunComfy Cloud AI Toolkit, la via più semplice è alzare il job a una GPU con più VRAM e rilanciare, spesso riducendo alcune impostazioni aggressive di quantizzazione/Low VRAM e usando una config più semplice e veloce. Con più VRAM e meno “hacks”, ogni step è più rapido e puoi iterare su più checkpoint invece di perdere tempo a micromanage della memoria.

---

La LoRA overfitta e “hijacka” il modello base

Sintomi:

• Ogni persona sembra il tuo soggetto.
• Ogni camion sembra il tuo prodotto anche senza trigger word.

Mitigazioni:

• Abbassa Linear Rank.
• Usa un checkpoint precedente (es. 2000 steps invece di 3000).
• Aumenta leggermente Weight Decay.
• Aggiungi un dataset di regolarizzazione della stessa classe (Is Regularization = on).
• Abilita Differential Output Preservation con un DOP Loss Multiplier ragionevole (es. 0.2–0.5) e una DOP Preservation Class adatta ("person", "truck", ecc.).