@mcptoolshop/backpropagate 1.4.0 → 1.6.0

package/README.it.md

@@ -15,9 +15,9 @@
   <a href="https://mcp-tool-shop-org.github.io/backpropagate/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
 </p>
 
-# Addestra un adattatore. Inoltralo a Ollama. Finito
+# Addestra un adattatore. Caricalo su Ollama. Passa oltre
 
-Backpropagate è una libreria Python per l'affinamento di modelli linguistici di grandi dimensioni su una singola GPU. Tre righe di codice addestrano un modello da 7 miliardi di parametri su una scheda da 16 GB. Un altro comando lo esporta in Ollama, così puoi eseguire il tuo modello affinato con `ollama run`. Funziona perfettamente anche su Windows.
+Backpropagate è una libreria Python per l'affinamento di modelli linguistici di grandi dimensioni su una singola GPU. Tre righe di codice addestrano un modello da 7B su una scheda da 16 GB. Un comando aggiuntivo lo esporta su Ollama in modo che tu possa eseguire `ollama run` sul tuo modello affinato. Funziona perfettamente su Windows.
 
 ```python
 from backpropagate import Trainer
@@ -32,9 +32,9 @@ backprop export ./output/lora --format gguf --quantization q4_k_m --ollama --oll
 ollama run my-model
 ```
 
-Ecco tutto. Non c'è bisogno di un file di configurazione YAML. Non c'è la "cerimonia" di `accelerate launch`. Non c'è un tutorial separato su come "convertirlo in GGUF". Se hai una GPU CUDA e un file JSONL con i tuoi dati di addestramento, sei a solo tre righe di codice dall'avere un modello affinato funzionante.
+Questo è tutto. Non c'è un file di configurazione YAML. Non c'è una procedura complessa con `accelerate launch`. Non c'è un tutorial separato del tipo "ora convertilo in GGUF". Se hai una GPU CUDA e un file JSONL con i tuoi dati di addestramento, ti servono solo tre righe per ottenere un modello affinato funzionante.
 
-## Installazione
+## Installa
 
 ```bash
 # Recommended: isolated Python install (no conflicts with system Python or other projects)
@@ -54,20 +54,20 @@ pipx install "backpropagate[standard]"   # adds Unsloth (2x faster training) + t
 pipx install "backpropagate[full]"       # adds everything: unsloth, ui, monitoring, export, etc.
 ```
 
-Preferisci Docker? `docker pull ghcr.io/mcp-tool-shop-org/backpropagate:latest` funziona anche. Sono disponibili immagini per `linux/amd64` e `linux/arm64`, quindi gli utenti con Apple Silicon e ARM Linux hanno a disposizione un'immagine nativa. Un file `compose.yaml` standard per "UI in un container" si trova nella directory principale del repository: `docker compose up` avvia l'interfaccia web su `http://localhost:7860` con un volume persistente `~/.backpropagate` montato.
+Preferisci Docker? Anche `docker pull ghcr.io/mcp-tool-shop-org/backpropagate:latest` funziona. Sono disponibili immagini sia per `linux/amd64` che per `linux/arm64`, quindi gli utenti di Apple Silicon e ARM Linux ottengono un'immagine nativa. Un file `compose.yaml` standard per "UI in un container" si trova nella directory principale del repository: `docker compose up` avvia l'interfaccia utente web su `http://localhost:7860` con un volume persistente `~/.backpropagate`.
 
-## Dove si colloca Backpropagate
+## Dove si colloca Backpropagate nello spazio degli strumenti
 
-Esistono diverse buone librerie per l'affinamento di modelli linguistici di grandi dimensioni. Ognuna è eccellente per cose diverse:
+Esistono diverse buone librerie per l'affinamento di LLM. Ognuna di esse è ottima in ambiti diversi:
 
-- **[Axolotl](https://github.com/OpenAccess-AI-Collective/axolotl)** — se ti piacciono le configurazioni YAML e vuoi una comunità di ricette da cui prendere spunto.
-- **[LLaMA-Factory](https://github.com/hiyouga/LLaMA-Factory)** — se desideri un'interfaccia grafica web e un supporto integrato per DPO/PPO/RLHF.
-- **[Unsloth](https://github.com/unslothai/unsloth)** — se hai bisogno della formazione più veloce possibile e utilizzi una famiglia di modelli supportata.
-- **[torchtune](https://github.com/pytorch/torchtune)** — se desideri le ricette native di PyTorch di Meta che puoi modificare.
+- **[Axolotl](https://github.com/OpenAccess-AI-Collective/axolotl)** — se ti piacciono le configurazioni YAML e desideri una community di ricette da cui copiare
+- **[LLaMA-Factory](https://github.com/hiyouga/LLaMA-Factory)** — se vuoi DPO/PPO/RLHF e un'interfaccia utente web
+- **[Unsloth](https://github.com/unslothai/unsloth)** — se hai bisogno dell'addestramento più rapido possibile e utilizzi una famiglia di modelli supportata
+- **[torchtune](https://github.com/pytorch/torchtune)** — se desideri le ricette PyTorch native di Meta che puoi modificare
 
-Backpropagate è l'opzione mancante: **un'API Python di 3 righe per gli utenti singoli che utilizzano una singola GPU consumer e che desiderano addestrare un adattatore e distribuirlo.** Nessun YAML, nessuna interfaccia grafica, nessun DPO/PPO, nessuna configurazione multi-nodo. Solo il ciclo di lavoro di cui tutti hanno bisogno e la fase di esportazione che crea problemi.
+Backpropagate è l'opzione mancante: **un'API Python a 3 righe per gli utenti singoli su una singola GPU consumer che desiderano addestrare un adattatore e caricarlo.** Nessun YAML, nessuna GUI, nessun RL online (PPO/GRPO), nessun nodo multiplo. Solo il ciclo di cui tutti hanno realmente bisogno e il passaggio di esportazione che crea problemi.
 
-Se hai provato una delle librerie sopra e ti sei sentito frustrato dalla "cerimonia" del file di configurazione, o hai riscontrato un problema con la famiglia di modelli, o volevi impostazioni predefinite per Windows — Backpropagate è quello che fa per te.
+Se hai provato una delle librerie sopra elencate e ti sei scontrato con la procedura del file di configurazione, o hai riscontrato un problema con la famiglia di modelli, o desideravi impostazioni predefinite per Windows, Backpropagate è quello che fa per te.
 
 ## Cosa puoi affinare su una GPU consumer da 16 GB
 
@@ -75,53 +75,55 @@ Ecco i limiti pratici su una scheda da 16 GB (RTX 4080 / 5080 / 4070 Ti Super):
 
 | Modello | Metodo | Stato |
 |---|---|---|
-| Qwen-3.5-4B / Phi-4-mini-3.8B / SmolLM3-3B | LoRA / QLoRA / DoRA | Comodo. Lunghezza della sequenza completa, con spazio extra. |
-| Phi-4-mini-3.8B / Qwen-3.5-4B / SmolLM3-3B (limite massimo di 3 miliardi di parametri) | `mode="full"` (affinamento completo) | v1.4 — utilizzare l'opzione `--mode=full` con `backprop train` oppure `Trainer(..., mode="full")`. Il checkpointing del gradiente e l'utilizzo di Adam a 8 bit con paginazione mantengono la memoria delle attivazioni a sqrt(L). |
+| Qwen-3.5-4B / Phi-4-mini-3.8B / SmolLM3-3B | LoRA / QLoRA / DoRA | Ottimo. Lunghezza di sequenza completa, con spazio a sufficienza. |
+| SmolLM3-3B / Qwen2.5-3B / Llama-3.2-3B / Llama-3.2-1B | `mode="full"` (affinamento completo) | v1.4: passa `--mode=full` in `backprop train` o `Trainer(..., mode="full")`. Carica i pesi a piena precisione (bf16), senza 4 bit, senza adattatore; il checkpointing del gradiente e l'Adam a 8 bit con paging mantengono l'impronta entro i 16 GB. |
 | Qwen-2.5-7B / Llama-3.1-8B / Mistral-7B | QLoRA | Standard. Circa 7-8 GB. Impostazioni predefinite di Backpropagate. |
-| Llama-3 13B | QLoRA + sample packing | Limitato ma funzionante. Utilizza sequenze più corte. |
-| Mixtral 8x7B (47 miliardi di parametri totali) | AQLM 2-bit + LoRA | Previsto per la v1.5 — consultare il documento V1_5_BRIEF quando sarà disponibile. |
+| Llama-3 13B | QLoRA + sample packing | Stretto, ma funziona. Utilizza sequenze più brevi. |
+| Mixtral 8x7B (47 miliardi di parametri totali) | — | Fuori portata: la quantizzazione a 2 bit (AQLM / QuIP#) interrompe il contratto dell'adattatore unificabile + esportazione GGUF, quindi è stata abbandonata nella [breve descrizione della traiettoria v1.5](docs/V1_5_BRIEF.md). Su una scheda da 16 GB, utilizza una base ≤8B. |
 
-La quantizzazione AQLM a 2 bit (`quant_method="aqlm"`, opzione sperimentale per Mixtral-8x7B su 16GB) era prevista per la v1.4 ed è ora pianificata per la v1.5. La libreria `aqlm` è matura; nella versione 1.4, la priorità è stata data al supporto per l'affinamento completo per modelli con un massimo di 3 miliardi di parametri (`mode="full"`) piuttosto che all'aggiunta di un nuovo backend di quantizzazione. Consultare il documento V1_5_BRIEF quando sarà disponibile per il piano di implementazione della v1.5.
+`mode="full"` consente modelli fino a **4 miliardi di parametri**. Le quattro impostazioni nella riga dell'affinamento completo sopra sono autentici ~3B (numero effettivo di parametri 3,08–3,24B) e si adattano a una scheda da 16 GB. La classe 3,8–4B (Phi-4-mini-3,8B, Qwen-3,5-4B) è accettata anche dal limite massimo, ma richiede una scheda da **24 GB o superiore** per l'affinamento completo: i soli pesi e gradienti si avvicinano già a 16 GB prima dell'ottimizzatore e delle attivazioni; quindi, su una scheda da 16 GB, utilizza `mode="lora"` per questi (si trovano nella riga LoRA). I modelli >4B restituiscono un errore con `RUNTIME_FULL_FT_MODEL_TOO_LARGE`.
 
-Per i modelli da 3 miliardi di parametri in giù, l'affinamento completo (e non solo LoRA) è possibile su 16GB ed è ora disponibile nella v1.4 con `mode="full"`. Per abilitarlo, utilizzare `Trainer(..., mode="full")` oppure `backprop train --mode=full --model phi-4-mini-3.8b`. Un meccanismo di controllo impedisce l'utilizzo di questa modalità per modelli superiori a 3 miliardi di parametri, suggerendo LoRA e le configurazioni predefinite inferiori a 3 miliardi come alternative. Consultare la [pagina completa del manuale sull'affinamento completo](https://mcp-tool-shop-org.github.io/backpropagate/handbook/full-fine-tuning/) per i dettagli sulla configurazione e per il confronto della qualità tra Biderman 2024 e Thinking Machines 2025. Per i modelli da 7 miliardi di parametri in su, l'affinamento completo richiede una GPU da 24GB o superiore; si consiglia di utilizzare un servizio di cloud con una GPU A100 oppure di utilizzare LoRA, che, secondo recenti ricerche, offre una qualità equivalente all'affinamento completo nella maggior parte delle attività successive all'addestramento (vedere la [sezione "cosa Backpropagate non è"](#what-backpropagate-is-not-for) per le citazioni).
+La quantizzazione a 2 bit (AQLM / QuIP#) è **fuori portata**. È stata prevista per la v1.4, quindi abbandonata nella [breve descrizione della traiettoria v1.5](docs/V1_5_BRIEF.md): una base a 2 bit non può essere unificata in modo pulito con i pesi a piena precisione, il che interrompe il contratto dell'adattatore unificabile → GGUF → Ollama (il punto principale della pipeline). Le opzioni di ottimizzazione offerte da Backpropagate sono invece il percorso di calcolo FP8 v1.5 (`--fp8`, Blackwell/Hopper) e `mode="full"` per i modelli ≤4B: entrambi rimangono unificabili ed esportabili.
 
-## Cosa Backpropagate NON è
+Per i modelli da 3B o inferiori, l'affinamento completo (non solo LoRA) è fattibile su 16 GB ed è ora disponibile nella v1.4 come `mode="full"`. Passa `Trainer(..., mode="full")` o `backprop train --mode=full --model phi-4-mini-3.8b` per abilitarlo. Un blocco rigido rifiuta la modalità per i modelli > 4B con `RUNTIME_FULL_FT_MODEL_TOO_LARGE`, indicando LoRA e le impostazioni predefinite inferiori a 4B come opzioni di ripristino. Consulta [la pagina del manuale sull'affinamento completo](https://mcp-tool-shop-org.github.io/backpropagate/handbook/full-fine-tuning/) per i calcoli della configurazione e il confronto sulla qualità con Biderman 2024 / Thinking Machines 2025. Per i modelli da 7B o superiori, l'affinamento completo richiede una GPU da 24 GB o superiore: valuta la possibilità di noleggiare un A100 nel cloud oppure attieniti a LoRA, che le ricerche più recenti dimostrano essere altrettanto efficace dell'affinamento completo nella maggior parte delle attività post-addestramento (consulta [la sezione "anti-pitch"](#what-backpropagate-is-not-for) per i riferimenti).
 
-Se il vostro caso d'uso rientra nelle categorie seguenti, otterrete risultati migliori con un'altra libreria. Backpropagate non è la scelta giusta e cercare di farlo funzionare costerebbe più che utilizzare lo strumento appropriato. Leggere questa sezione prima di iniziare vi farà risparmiare tempo e tentativi.
+## Per cosa NON è adatto Backpropagate
 
-- **Affinamento completo dei parametri per modelli da 7 miliardi di parametri in su** — Backpropagate utilizza LoRA / QLoRA, che addestra un piccolo adattatore invece di aggiornare tutti i pesi. Per i modelli da 7 miliardi di parametri in su, l'affinamento completo richiede 24GB+ di memoria GPU e non è possibile su una scheda consumer da 16GB. Per i modelli da 3 miliardi di parametri in giù, l'affinamento completo è possibile su 16GB ed è disponibile nella v1.4 con `mode="full"` (utilizzare `Trainer(..., mode="full")` oppure `--mode=full` dalla riga di comando; un meccanismo di controllo impedisce l'utilizzo di questa modalità per modelli superiori a 3 miliardi di parametri, suggerendo LoRA e le configurazioni predefinite inferiori a 3 miliardi come alternative). In sintesi: recenti ricerche ([Biderman 2024](https://arxiv.org/abs/2405.09673), [Thinking Machines 2025](https://thinkingmachines.ai/blog/lora/)) dimostrano che LoRA, con la configurazione corretta, offre una qualità equivalente all'affinamento completo nella maggior parte delle attività successive all'addestramento (istruzioni, adattamento al dominio, personalità/stile) con il 67% della potenza di calcolo; quindi, per il lavoro che la maggior parte degli operatori desidera svolgere, non si perde nulla utilizzando LoRA. `mode="full"` è disponibile per i casi in cui si è riscontrata una differenza di qualità e si è deciso di utilizzare una maggiore potenza di calcolo. Se è necessario affinare completamente un modello da 7 miliardi di parametri, utilizzare direttamente il modulo `transformers.Trainer` di HuggingFace su una scheda da 24GB o superiore.
-- **DPO / PPO / GRPO / ottimizzazione delle preferenze** — Backpropagate esegue solo l'affinamento supervisionato in una singola fase. Per l'apprendimento delle preferenze, utilizzare direttamente TRL o LLaMA-Factory.
-- **Addestramento multi-nodo** — supporta solo una GPU su una singola macchina. L'utilizzo di più GPU su una singola macchina è possibile (tramite `accelerate launch`) ma non è ufficialmente supportato.
-- **Addestramento su macOS** — Apple Silicon non dispone di CUDA, quindi l'addestramento deve essere eseguito su una macchina Linux o Windows con una GPU NVIDIA. È comunque possibile eseguire il modello addestrato su un Mac tramite Ollama.
-- **Qualsiasi modello al di fuori delle famiglie di modelli testate** — Qwen 2.5 / 3.5 (7B / 4B), Phi-4-mini-3.8B, SmolLM3-3B, Llama 3.2 (3B / 1B), Mistral 7B. Altri modelli potrebbero funzionare, ma non sono inclusi nei test automatizzati.
+Se il tuo caso d'uso rientra nelle seguenti categorie, otterrai risultati migliori con una libreria diversa: Backpropagate non è la scelta giusta e cercare di farlo funzionare costerebbe più che semplicemente utilizzare lo strumento corretto. Leggere questa sezione prima di iniziare ti eviterà di installare e poi abbandonare il progetto:
 
-Se avete bisogno di queste funzionalità, utilizzate una delle librerie elencate sopra. Sono più adatte per questo scopo.
+- **Ottimizzazione completa dei parametri per modelli da 7B+** — Backpropagate utilizza LoRA/QLoRA, che addestra un piccolo adattatore anziché aggiornare tutti i pesi. Per i modelli da 7B e superiori, l'ottimizzazione completa richiede 24 GB o più di memoria GPU e non è adatta per una scheda consumer da 16 GB. Per i modelli da 3B e inferiori, l'ottimizzazione completa È fattibile con 16 GB ed è disponibile nella versione 1.4 come `mode="full"` (passare `Trainer(..., mode="full")` o `--mode=full` dalla riga di comando; un controllo rigido genera `RUNTIME_FULL_FT_MODEL_TOO_LARGE` per i modelli > 4B e nomina LoRA + le configurazioni predefinite inferiori a 4B come soluzioni alternative). Nel complesso: ricerche recenti ([Biderman 2024](https://arxiv.org/abs/2405.09673), [Thinking Machines 2025](https://thinkingmachines.ai/blog/lora/)) mostrano che LoRA, con la configurazione corretta, corrisponde alla qualità dell'ottimizzazione completa nella maggior parte delle attività di post-addestramento (seguimento delle istruzioni, adattamento al dominio, personalità/stile) con il 67% della potenza di calcolo. Quindi, per il lavoro che la maggior parte degli utenti desidera effettivamente, non si perde nulla utilizzando LoRA. `mode="full"` è disponibile per i casi in cui si è misurata una differenza di qualità e si è deciso di investire più risorse computazionali. Se si ha realmente bisogno dell'ottimizzazione completa di un modello da 7B+, utilizzare direttamente HuggingFace `transformers.Trainer` su una scheda da 24 GB o superiore.
+- **RL online — PPO / GRPO / RLVR** — Backpropagate esegue l'addestramento SFT in una sola fase più l'ottimizzazione delle preferenze senza riferimenti (ORPO nella versione 1.5; SimPO + KTO nella versione 1.6). Non esegue l'apprendimento per rinforzo online, come PPO, GRPO o RLVR, che richiede un modello di ricompensa o un ciclo di generazione e valutazione in aggiunta alla fase di addestramento. Per questi casi, utilizzare direttamente TRL o LLaMA-Factory. (L'ottimizzazione delle preferenze senza riferimenti si adatta all'ambito della singola fase perché non è necessario mantenere un modello di riferimento separato in memoria; vedere la nota su ORPO sotto [Guida rapida](#guida-rapida)).
+- **Addestramento multi-nodo** — una sola GPU su una sola macchina. L'addestramento multi-GPU su una singola macchina funziona (tramite `accelerate launch`), ma non è ufficialmente supportato.
+- **Addestramento macOS con CUDA** — Apple Silicon non dispone di CUDA, quindi il percorso CUDA deve essere eseguito su un sistema Linux o Windows con una GPU NVIDIA. È comunque possibile eseguire il modello addestrato su un Mac tramite Ollama. **Novità nella versione 1.5:** un percorso MLX sperimentale (`--backend mlx`) addestra in modo nativo un adattatore LoRA su Apple Silicon; vedere [Apple Silicon (MLX)](#apple-silicon-mlx--sperimentale-v15). È disponibile solo l'addestramento LoRA-SFT ed è stato implementato, ma non ancora verificato su hardware reale. Pertanto, per qualsiasi operazione che vada oltre un addestramento LoRA SFT (ORPO, ottimizzazione completa, FP8, esecuzioni multiple), si consiglia di utilizzare il percorso CUDA.
+- **Qualsiasi cosa al di fuori delle famiglie di modelli testate** — Qwen 2.5 / 3.5 (7B / 4B), Phi-4-mini-3.8B, SmolLM3-3B, Llama 3.2 (3B / 1B), Mistral 7B. Altri modelli spesso funzionano, ma non sono inclusi nei test CI.
 
-## Cosa offre Backpropagate:
+Se si necessita di una qualsiasi di queste funzionalità, utilizzare una delle librerie elencate sopra. Sono più adatte a questo scopo.
 
-Quattro cose, in un'unica installazione:
+## Cosa offre Backpropagate
 
-**1. Un'API semplice, composta da sole 3 righe, che funziona senza un file di configurazione.**
-Lo snippet di codice all'inizio di questo file README viene eseguito completamente. Non è necessario `accelerate config`, né file YAML, né override di Hydra. Basta `Trainer(model).train(data)` e avrete un modello ottimizzato.
+Quattro elementi, in un'unica installazione:
 
-**2. Funzionalità che funzionano effettivamente su Windows.**
-La maggior parte delle librerie di machine learning trattano Windows come un'aggiunta secondaria. Backpropagate è stato testato in modo approfondito su Windows + RTX 5080. La libreria gestisce automaticamente le peculiarità del sistema operativo, ad esempio pre-tokenizzando i dati per evitare che il multiprocessing di Windows si blocchi, disabilitando automaticamente xformers su schede RTX 40/50 dove causerebbe problemi, e impostando le opzioni del dataloader in modo da evitare errori. Non è necessario conoscere questi dettagli; il sistema funziona semplicemente.
+**1. Una vera API di 3 righe che funziona senza un file di configurazione.**
+Lo snippet all'inizio di questo README viene eseguito dall'inizio alla fine. Non è necessario `accelerate config`, YAML o override Hydra. Basta `Trainer(model).train(data)` e si ottiene un modello ottimizzato.
 
-**3. Progettato per l'esecuzione in background.**
-L'addestramento richiede ore. Non volete doverlo controllare costantemente. Backpropagate è progettato per essere lasciato in esecuzione:
+**2. Windows che funziona davvero.**
+La maggior parte delle librerie ML trattano Windows come un'aggiunta successiva. Backpropagate viene testata in modo completo su Windows + RTX 5080. La libreria gestisce le peculiarità dell'ambiente di runtime: sa come pre-tokenizzare i dati in modo che l'elaborazione parallela di Windows non si blocchi, disabilita automaticamente xformers sulle schede RTX 40/50 dove causerebbe problemi e seleziona le impostazioni del caricatore di dati che non causano errori. Non è necessario sapere nulla di tutto questo. Funziona semplicemente.
 
-- Se si esaurisce la memoria della GPU, riduce automaticamente la dimensione del batch e riprova, fino a tre volte. Non è necessario alcun intervento manuale.
-- Se la GPU si surriscalda, si interrompe fino a quando la temperatura non si abbassa e poi riprende.
-- Ogni checkpoint viene salvato in modo atomico: se il laptop si blocca durante il salvataggio, il checkpoint precedente rimane intatto.
-- Ogni esecuzione di addestramento riceve un ID univoco che viene aggiunto a ogni riga del log, a ogni checkpoint e a ogni voce di Weights & Biases. Se qualcosa va storto, un singolo ID consente a un manutentore di correlare tutti i dati.
-- Gli errori vengono segnalati con codici standard (`RUNTIME_GPU_OOM`, `DEP_OLLAMA_REGISTRATION_FAILED`, ecc.), in modo da poter cercare nei log e nella [guida alla risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/) per trovare la soluzione. Gli errori specifici di CUDA hanno una [pagina dedicata alla risoluzione dei problemi di CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/).
+**3. Progettato per esecuzioni senza supervisione.**
+L'addestramento richiede ore. Non si vuole doverlo monitorare costantemente. Backpropagate è progettata per essere lasciata in esecuzione:
 
-**4. Un solo comando per passare dall'adattatore addestrato all'esecuzione con `ollama run`.**
-Molte librerie addestrano un modello. Pochi di essi semplificano l'utilizzo del modello una volta addestrato. Backpropagate esporta il modello nel formato GGUF (il formato utilizzato da Ollama) e registra un modello Ollama con un solo comando. Si passa dallo stato di "addestramento completato" allo stato di "posso chattare con il mio modello ottimizzato" in circa 30 secondi.
+- Se la memoria della GPU si esaurisce, dimezza automaticamente le dimensioni del batch e riprova, fino a tre volte. Non è necessario effettuare alcuna regolazione manuale.
+- Se la GPU diventa troppo calda, si mette in pausa finché non si raffredda e poi continua.
+- Ogni checkpoint viene scritto in modo atomico: se il laptop si blocca durante il salvataggio, il checkpoint precedente valido rimane intatto.
+- Ogni esecuzione di addestramento riceve un ID univoco che viene stampato su ogni riga del log, su ogni checkpoint e su ogni voce di Weights & Biases. Se qualcosa va storto, un singolo ID consente a un manutentore di correlare tutto.
+- Gli errori sono accompagnati da codici stabili (`RUNTIME_GPU_OOM`, `DEP_OLLAMA_REGISTRATION_FAILED`, ecc.) in modo che sia possibile cercare nei log e nella [guida alla risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/) per trovare la soluzione. I guasti specifici di CUDA hanno una pagina dedicata per la [risoluzione dei problemi di CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/).
+
+**4. Un solo comando, dall'adattatore addestrato a `ollama run`.**
+Molte librerie addestrano un modello. Poche di esse si mettono di mezzo quando si vuole effettivamente utilizzarlo. Backpropagate esporta in GGUF (il formato utilizzato da Ollama) e registra un modello Ollama con un solo comando. Si passa da "addestramento completato" a "posso chattare con il mio modello ottimizzato" in circa 30 secondi.
 
 ## Guida rapida
 
-Il repository include un piccolo set di dati di esempio, in modo che lo script all'inizio di questo file README possa essere eseguito con un'installazione pulita:
+Il repository include un piccolo set di dati di esempio, quindi lo snippet all'inizio di questo README funziona su una nuova installazione:
 
 ```bash
 pipx install "backpropagate[standard]"
@@ -134,31 +136,80 @@ trainer.export('gguf', quantization='q4_k_m')
 "
 ```
 
-Questo addestra un adattatore Qwen 2.5 7B su 5 brevi conversazioni in formato ShareGPT, quindi esporta il risultato in formato GGUF. Per i tuoi dati, formatta il file JSONL con un esempio per riga:
+Questo addestra un adattatore Qwen 2.5 da 7B su 5 brevi conversazioni in formato ShareGPT, quindi esporta il risultato in GGUF. Per i propri dati, formattare il file JSONL con un esempio per riga:
 
 ```jsonl
 {"conversations": [{"from": "human", "value": "What is Python?"}, {"from": "gpt", "value": "A programming language."}]}
 {"conversations": [{"from": "human", "value": "Explain recursion."}, {"from": "gpt", "value": "A function that calls itself."}]}
 ```
 
-Anche i formati Alpaca (`instruction` / `output`), OpenAI chat (`messages`) e testo semplice funzionano: Backpropagate rileva automaticamente il formato.
+I formati Alpaca (`instruction` / `output`), OpenAI chat (`messages`) e testo semplice funzionano anche; Backpropagate rileva automaticamente il formato.
+
+### Ottimizzazione delle preferenze (ORPO, SimPO, KTO)
+
+Addestrare sulle preferenze anziché su semplici dimostrazioni. ORPO non richiede riferimenti ed è una singola fase: integra il segnale di preferenza nella fase SFT, quindi non esiste un modello di ricompensa o di riferimento separato e la struttura a 3 righe rimane invariata. Passare `--method orpo` (CLI) o `method="orpo"` (Python) e fornire un set di dati con righe nel formato `{prompt, chosen, rejected}` (o solo `{chosen, rejected}`):
+
+```jsonl
+{"prompt": "What is Python?", "chosen": "A high-level programming language known for readability.", "rejected": "idk look it up"}
+{"prompt": "Explain recursion.", "chosen": "A function that calls itself with a smaller input until a base case.", "rejected": "when something repeats"}
+```
+
+```python
+from backpropagate import Trainer
+
+trainer = Trainer("Qwen/Qwen2.5-7B-Instruct", method="orpo")
+trainer.train("preferences.jsonl", steps=100)
+trainer.export("gguf", quantization="q4_k_m")
+```
+
+```bash
+backprop train --data preferences.jsonl --method orpo --steps 100
+```
+
+Il tasso di apprendimento predefinito si riduce automaticamente a `8e-6` per ORPO (la perdita è più marcata rispetto al semplice SFT); regola `--orpo-beta` (predefinito `0.1`) per ponderare la penalità del rapporto delle probabilità. ORPO è solo in modalità `"lora"`.
 
-Per flussi di lavoro più complessi (fine-tuning e pubblicazione su Hugging Face Hub, ripresa dopo errori di memoria, esecuzione multipla di SLAO su una campagna lunga, ecc.), consultare la [pagina delle ricette del manuale](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/).
+**Novità nella versione 1.6: SimPO e KTO.** `--method simpo` ([Meng et al. 2024](https://arxiv.org/abs/2405.14734)) è indipendente dai dati di riferimento, utilizza una ricompensa normalizzata in base alla lunghezza e accetta gli stessi dati a coppie `{prompt, scelto, rifiutato}` di ORPO (`--simpo-beta`, `--simpo-gamma`). `--method kto` ([Ethayarajh et al. 2024](https://arxiv.org/abs/2402.01306)) accetta dati **non a coppie** `{prompt, completamento, etichetta}` — valutazioni positive/negative per ogni esempio — per l'ampia classe di feedback che non sono coppie A/B curate; bilancia automaticamente i pesi della perdita desiderabile/indesiderabile in base al conteggio delle etichette. Entrambi sono solo in modalità `"lora"` e rimangono nell'ambito SFT su una singola GPU (nessun modello di riferimento separato). Consulta il [manuale sull'ottimizzazione delle preferenze](https://mcp-tool-shop-org.github.io/backpropagate/handbook/preference-tuning/) per capire quale utilizzare. Per l'RL online (PPO/GRPO), consulta [Cosa NON è Backpropagate](#what-backpropagate-is-not-for).
 
-### Interfaccia web (opzionale)
+### SFT con traccia del ragionamento (distillazione R1)
 
-Se preferisci utilizzare un'interfaccia grafica invece di scrivere codice Python, installa il componente aggiuntivo dell'interfaccia utente e avvialo:
+Novità nella versione 1.5: distilla un modello di ragionamento in modo semplice. Passa `--reasoning-trace` (CLI) o `Trainer(..., reasoning_trace=True)` (Python) e fornisci tracce che mantengono una catena di pensiero `<think>...</think>` all'interno del turno dell'assistente — la metà SFT pura della distillazione di [DeepSeek-R1](https://arxiv.org/abs/2501.12948), senza necessità di RL. Backpropagate mantiene `<think>` nell'obiettivo di addestramento, elimina le tracce vuote o troppo lunghe (filtraggio della lunghezza delle tracce) e aumenta il valore predefinito di `max_seq_length` a 8192 per la catena di pensiero più lunga. Fondamentalmente, `<think>` rimane in **testo semplice** — nessun token speciale, nessuna ridimensionamento dell'embedding — quindi l'adattatore unificato esporta ancora in GGUF e può essere utilizzato con Ollama come qualsiasi altro modello ottimizzato. Solo SFT. Consulta la [ricetta per la traccia del ragionamento](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/#reasoning-trace-sft-r1-distillation) per la forma del set di dati e i token regolabili.
+
+### Apple Silicon (MLX) — sperimentale, versione 1.5
+
+Novità nella versione 1.5: **un'API, due opzioni.** CUDA rimane il backend canonico e verificato; MLX è una seconda opzione che esegue l'addestramento su un Mac della serie M tramite lo strumento [`mlx_lm.lora`](https://github.com/ml-explore/mlx-lm) di Apple (memoria unificata, nessuna necessità di CUDA). La stessa struttura a 3 righe seleziona l'opzione in base all'hardware: `backend='auto'` (predefinito) indirizza verso CUDA su NVIDIA e verso MLX su Apple Silicon, quindi le configurazioni CUDA esistenti sono identiche.
+
+```python
+from backpropagate import Trainer
+
+# On an M-series Mac with `pip install 'backpropagate[mlx]'`:
+trainer = Trainer("mlx-community/Qwen2.5-0.5B-Instruct-4bit", backend="mlx")
+trainer.train("examples/quickstart.jsonl", steps=100)
+```
+
+```bash
+backprop train --data my_data.jsonl --backend mlx --steps 100
+```
+
+Nella versione 1.5, l'opzione MLX è **solo SFT LoRA** — nessun ORPO, nessun FP8, nessuna modalità `'full'`, nessun addestramento multiplo su MLX (ognuno viene rifiutato con `CONFIG_INVALID_SETTING`; utilizza `backend='cuda'`/`'auto'` su una macchina NVIDIA per queste opzioni). L'adattatore risultante è in formato safetensors e può essere esportato verso Ollama tramite lo stesso percorso dell'opzione CUDA.
+
+> ⚠️ **Stato reale:** l'opzione MLX viene fornita nella versione 1.5 **costruita + testata con unità (simulata)** ma **NON ancora verificata su Apple Silicon reale** — `mlx-lm` è solo per Apple e non poteva essere eseguito sulla macchina NVIDIA su cui è stato creato questo progetto. Considerala sperimentale — lo stesso approccio che è stato utilizzato per il percorso FP8 nella versione 1.5 (FP8 è passato alla fase di verifica su Blackwell nella versione 1.6; MLX deve ancora superare questa fase su hardware reale) — e segnala eventuali anomalie [qui](#reporting-bugs) una volta che verrà eseguita su un Mac della serie M. Forzare `--backend mlx` su un host non Apple genera un errore `CONFIG_INVALID_SETTING`; la mancanza dello strumento `mlx_lm` su un Mac genera `DEP_MLX_UNAVAILABLE`.
+
+Per flussi di lavoro end-to-end più completi (ottimizzazione e caricamento su HF Hub, ripresa dopo esaurimento della memoria, SLAO multi-esecuzione in una lunga campagna, ecc.), consulta la [pagina delle ricette del manuale](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/).
+
+### Interfaccia utente web (opzionale)
+
+Se preferisci fare clic invece di digitare in Python, installa il pacchetto aggiuntivo dell'interfaccia utente e avvia:
 
 ```bash
 pipx install "backpropagate[ui]"
 backprop ui --port 7862
 ```
 
-Si apre un'interfaccia web locale all'indirizzo `http://localhost:7862`, dove puoi selezionare un set di dati, scegliere un modello, eseguire l'addestramento e l'esportazione. L'interfaccia utente è attiva solo localmente per impostazione predefinita. Per renderla accessibile da altri dispositivi, consulta la sezione [Interfaccia web](#web-ui) riportata di seguito per le opzioni `--share` e `--auth` relative alla sicurezza.
+Si apre un'interfaccia web locale all'indirizzo `http://localhost:7862` per sfogliare i set di dati, convalidare i formati e assemblare visivamente una configurazione di addestramento. L'addestramento stesso viene eseguito tramite `backprop train` (l'addestramento basato sull'interfaccia utente è in programma — il pulsante Avvia mostra attualmente tale nota). L'interfaccia utente è locale per impostazione predefinita. Per renderla accessibile da altri dispositivi, consulta la sezione [Interfaccia utente web](#web-ui) qui sotto per il contratto di sicurezza `--share` + `--auth`.
 
-## Addestramento multiplo
+## Addestramento multi-esecuzione
 
-Se desideri eseguire il fine-tuning in modo incrementale su più set di dati (ad esempio, ricevi nuovi dati di addestramento ogni settimana e desideri aggiungerli senza dimenticare ciò che hai imparato in precedenza), la modalità `multi_run` di Backpropagate è ciò che fa per te:
+Se desideri ottimizzare in modo incrementale su più set di dati — ad esempio, se ricevi nuovi dati di addestramento ogni settimana e vuoi aggiungerli senza dimenticare ciò che hai imparato prima — la modalità `multi_run` di Backpropagate è quella giusta per te:
 
 ```python
 from backpropagate import Trainer
@@ -173,9 +224,9 @@ result = trainer.multi_run(
 )
 ```
 
-Questo esegue cinque cicli di addestramento, unendo l'adattatore tra un ciclo e l'altro in modo da preservare le conoscenze precedenti e incorporare nuovi esempi. Questa tecnica si basa su recenti ricerche sull'apprendimento continuo: consulta la sezione [Riferimenti](#references) in fondo a questo file README.
+Questo esegue cinque passaggi di addestramento, unendo l'adattatore tra le esecuzioni in modo da preservare le conoscenze precedenti e incorporare nuovi esempi. La tecnica si basa su recenti ricerche sull'apprendimento continuo — consulta la sezione [Riferimenti](#references) in fondo a questo file README.
 
-La versione da riga di comando (CLI):
+La versione CLI:
 
 ```bash
 backprop multi-run --data my_data.jsonl --runs 5 --steps 100 --samples 1000
@@ -183,7 +234,7 @@ backprop multi-run --data my_data.jsonl --runs 5 --steps 100 --samples 1000
 
 ## Ripresa da un checkpoint
 
-Un addestramento di 5 cicli che si interrompe al quarto ciclo può essere ripreso. Ogni sessione di addestramento multiplo scrive l'ID del ciclo nel file di cronologia e nel manifest del checkpoint, quindi per riprendere da dove ti eri interrotto, è sufficiente un comando:
+Un addestramento di 5 esecuzioni che si interrompe alla quarta esecuzione può essere ripreso. Ogni sessione multi-esecuzione scrive l'ID dell'esecuzione nella cronologia e nel manifesto dei checkpoint su disco, quindi riprendere da dove ti sei interrotto richiede un solo comando:
 
 ```bash
 backprop resume <run-id>
@@ -191,11 +242,11 @@ backprop multi-run --data ... --resume <run-id>
 backprop train --data ... --resume <run-id>     # single-run resume
 ```
 
-Il comportamento predefinito di `backprop multi-run` (senza `--resume`) rileva automaticamente una sessione in corso nella stessa directory di output e la continua. Per forzare un nuovo inizio, indica una directory di output diversa.
+Il comportamento predefinito di `backprop multi-run` (nessun `--resume`) rileva automaticamente una voce in corso nella stessa directory di output e la continua. Per forzare un nuovo inizio, punta a una nuova directory di output.
 
 ## Cronologia dell'addestramento
 
-Ogni invocazione di `backprop train` e `backprop multi-run` registra una riga in `<output>/run_history.json`, contenente informazioni sul modello utilizzato, il set di dati, gli iperparametri, lo stato, la perdita finale e la cronologia delle perdite. Puoi visualizzare e analizzare le esecuzioni precedenti:
+Ogni invocazione di `backprop train` e `backprop multi-run` registra una riga in `<output>/run_history.json` — modello utilizzato, set di dati, iperparametri, stato, perdita finale, cronologia delle perdite. Puoi elencare e ispezionare le esecuzioni passate:
 
 ```bash
 backprop list-runs                         # last 20 runs
@@ -206,7 +257,7 @@ backprop show-run abcd1234                 # detail view (partial ID is fine)
 
 ## Monitoraggio degli esperimenti
 
-Backpropagate rileva automaticamente i sistemi di monitoraggio degli esperimenti installati (Weights & Biases, TensorBoard, MLflow) e li configura. Se `wandb` è installato e sei autenticato, ogni esecuzione registra automaticamente i dati su W&B con un nome che corrisponde all'ID del ciclo presente nel file di output, in modo da poter utilizzare un unico identificatore per cercare i dati su W&B, nei tuoi log e nel file `run_history.json`.
+Backpropagate rileva automaticamente i tracker di esperimenti installati (Weights & Biases, TensorBoard, MLflow) e li configura. Se `wandb` è installato e sei autenticato, ogni esecuzione registra automaticamente i dati su W&B con un nome che corrisponde all'ID dell'esecuzione salvato sul disco, in modo da poter effettuare ricerche su W&B, nei tuoi log e nel file `run_history.json` utilizzando un unico identificatore.
 
 ```bash
 pip install backpropagate[monitoring]   # installs wandb + psutil
@@ -214,23 +265,25 @@ wandb login                             # one-time setup
 backprop train --data my_data.jsonl
 ```
 
-Per disabilitare questa funzionalità, utilizza `Trainer(report_to=["wandb"])`, `Trainer(report_to=["tensorboard"])` oppure `Trainer(report_to="none")`.
+È possibile sovrascrivere le impostazioni con `Trainer(report_to=["wandb"])`, `Trainer(report_to=["tensorboard"])` o `Trainer(report_to="none")` per disattivare la funzionalità.
 
-## Interfaccia web
+## Interfaccia utente web
 
-L'interfaccia web Reflex è opzionale: installala con `pipx install "backpropagate[ui]"` e avviala:
+L'interfaccia web di Reflex è attivabile; installala con `pipx install "backpropagate[ui]"` e avviala:
 
 ```bash
 backprop ui --port 7862
 ```
 
-L'interfaccia utente viene eseguita localmente all'indirizzo `http://localhost:7862`. Per renderla accessibile da altri dispositivi (altri utenti sulla tua rete, un URL pubblico, ecc.), devi combinare le opzioni `--share` (o `--host`) con `--auth`:
+L'interfaccia utente viene eseguita localmente all'indirizzo `http://localhost:7862`. Attualmente, copre la metà del flusso di lavoro relativa a **esplorazione / convalida / configurazione**: punta l'interfaccia su un set di dati, verifica il formato e le statistiche rilevate automaticamente, seleziona un modello e crea una configurazione per l'esecuzione. **L'avvio dell'esecuzione viene eseguito dalla riga di comando** (`backprop train` / `backprop multi-run`); il pulsante "Avvia" nell'interfaccia utente visualizza una nota che indica dove avviare l'esecuzione. L'addestramento guidato dall'interfaccia utente è un aggiornamento futuro; per ora, l'interfaccia utente funge da punto di accesso e la riga di comando è il trigger.
+
+Per renderla accessibile ad altri dispositivi (altre persone sulla tua rete, un URL pubblico, ecc.), devi combinare `--share` (o `--host`) con `--auth`:
 
 ```bash
 backprop ui --share --auth alice:hunter2
 ```
 
-`backprop ui --share` senza `--auth` genera un errore. Il motivo è che `--share` pubblica un URL a cui chiunque su Internet può accedere, e senza autenticazione ciò significa che chiunque può controllare la tua pipeline di addestramento e leggere il tuo token di Hugging Face. Non è possibile disabilitare questa funzionalità: se non desideri impostare le credenziali, utilizza il port-forwarding SSH.
+`backprop ui --share` senza `--auth` genera un errore. Il motivo: `--share` pubblica un URL a cui chiunque su Internet può accedere e, in assenza di autenticazione, ciò significa che chiunque può controllare la tua pipeline di addestramento e leggere il tuo token HuggingFace. Non è possibile disattivare questa funzionalità; se non desideri impostare le credenziali, utilizza invece il port forwarding SSH:
 
 ```bash
 # On the client:
@@ -240,32 +293,32 @@ backprop ui                             # no --share
 # Then open http://localhost:7860 in your local browser
 ```
 
-Consulta il file [handbook/security.md](https://mcp-tool-shop-org.github.io/backpropagate/handbook/security/) per un'analisi completa dei rischi.
+Consulta [handbook/security.md](https://mcp-tool-shop-org.github.io/backpropagate/handbook/security/) per la descrizione completa del modello di minaccia.
 
 Le operazioni di scrittura sul file system dall'interfaccia utente sono limitate a una singola directory:
 
-- Valore predefinito: `~/.backpropagate/ui-outputs`
-- Per sovrascrivere: impostare `BACKPROPAGATE_UI__OUTPUT_DIR=/path/you/own`
-- La sovrascrittura è validata tramite una lista di elementi non consentiti: i percorsi di sistema o di credenziali (`/etc`, `~/.ssh`, `~/.aws`, `C:\Windows\System32`, ecc.) non sono ammessi.
+- Predefinito: `~/.backpropagate/ui-outputs`
+- Sovrascrittura: imposta `BACKPROPAGATE_UI__OUTPUT_DIR=/path/you/own`
+- La sovrascrittura viene convalidata tramite una lista di esclusione: i percorsi di sistema o delle credenziali (`/etc`, `~/.ssh`, `~/.aws`, `C:\Windows\System32`, ecc.) vengono rifiutati.
 
 ## Note sulla piattaforma
 
-**Requisiti:** Python 3.10+ · GPU CUDA (8GB+ di VRAM) · PyTorch 2.0+
+**Requisiti:** Python 3.10+ · GPU CUDA (8 GB o più di VRAM) · PyTorch 2.0+
 
-Python 3.10 raggiungerà la fine del suo ciclo di vita ufficiale nell'ottobre 2026, e Backpropagate prevede di rimuovere il supporto per la versione 3.10 nella versione 1.4. Per le nuove installazioni, è preferibile utilizzare Python 3.11 o 3.12; la versione 3.11 è quella più testata.
+Python 3.10 è supportato almeno fino alla versione v1.6; il supporto terminerà a ottobre 2026 e la rimozione è prevista nella prima versione successiva. Per le nuove installazioni, preferisci Python 3.11 o 3.12: la versione 3.11 è quella più testata.
 
-Backpropagate gestisce le peculiarità dell'ambiente di runtime durante l'addestramento su diverse piattaforme, ma non può risolvere i problemi che si verificano durante l'installazione. I due problemi più comuni sono:
+Backpropagate gestisce le peculiarità di runtime dell'addestramento su diverse piattaforme, ma non può risolvere i problemi che si verificano durante l'installazione. I due più comuni sono:
 
-- **Driver CUDA errato.** PyTorch viene distribuito con una versione binaria per ogni versione di CUDA. Se si sceglie la versione errata, si ottiene silenziosamente una versione di PyTorch che utilizza solo la CPU, e l'addestramento diventa estremamente lento. Utilizzare lo strumento di selezione dei driver all'indirizzo <https://pytorch.org/get-started/locally/> per il proprio driver. Eseguire il comando `nvidia-smi` per visualizzare la versione del driver e di CUDA.
-- **Windows + esportazione GGUF.** L'opzione `[export]` compila `llama-cpp-python` dal codice sorgente, il che richiede Visual Studio Build Tools (componente C++) e CMake.
+- **Pacchetto CUDA errato.** PyTorch viene pubblicato con un singolo pacchetto per ogni versione di CUDA. Se selezioni quello sbagliato, otterrai silenziosamente solo PyTorch per CPU e l'addestramento sarà estremamente lento. Utilizza lo strumento di selezione dei pacchetti disponibile all'indirizzo <https://pytorch.org/get-started/locally/> per la tua scheda grafica. Esegui `nvidia-smi` per visualizzare la versione del driver / CUDA.
+- **Windows + esportazione GGUF.** L'opzione extra `[export]` crea `llama-cpp-python` dal codice sorgente, il che richiede Visual Studio Build Tools (componente C++) e CMake.
 
-**macOS:** L'addestramento con GPU non è supportato (non è disponibile CUDA). È possibile eseguire l'adattatore addestrato su un Mac tramite Ollama, ma la funzione `trainer.train()` genera un errore `DEP_GPU_NOT_AVAILABLE`. Utilizzare una macchina Linux o Windows con CUDA per l'addestramento vero e proprio.
+**macOS:** la configurazione CUDA non è supportata (nessuna CUDA); l'esecuzione di `trainer.train()` con una configurazione CUDA genera un errore `DEP_GPU_NOT_AVAILABLE` ed è possibile eseguire l'adattatore addestrato su un Mac tramite Ollama. **Novità nella versione v1.5:** una configurazione MLX sperimentale (`--backend mlx`, `pip install 'backpropagate[mlx]'`) esegue nativamente l'addestramento di un adattatore LoRA su Apple Silicon tramite `mlx_lm.lora`: solo SFT LoRA, e compilato e testato, ma non ancora verificato in condizioni reali (vedi [Apple Silicon (MLX)](#apple-silicon-mlx--experimental-v15)). Per il percorso CUDA o per ORPO / fine-tuning completo / FP8 / esecuzioni multiple, utilizza una macchina Linux o Windows con CUDA.
 
-Consultare la [pagina della guida alla risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/) per una guida completa alla risoluzione dei problemi di installazione, e la [pagina dedicata alla risoluzione dei problemi di CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/) per problemi relativi a driver, VRAM, xformers e bf16 rispetto a fp16.
+Consulta la [pagina della guida alla risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/) per la guida completa alla risoluzione dei problemi di installazione e la [pagina dedicata alla risoluzione dei problemi CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/) per i problemi relativi al driver / VRAM / xformers / bf16 rispetto a fp16.
 
-## CLI
+## CLI (riga di comando)
 
-Ogni API Python ha un'interfaccia a riga di comando (CLI) corrispondente:
+Ogni API Python ha un corrispondente nella riga di comando:
 
 ```bash
 backprop train --data my_data.jsonl --model Qwen/Qwen2.5-7B-Instruct --steps 100
@@ -282,80 +335,80 @@ backprop replay <run-id>               # re-run with same config / dataset
 backprop export-runs --format jsonl    # bulk export run history
 ```
 
-La documentazione completa è disponibile nella [pagina della guida alla CLI](https://mcp-tool-shop-org.github.io/backpropagate/handbook/cli-reference/), oppure è possibile utilizzare il comando `backprop <sottocomando> --help`.
+Riferimento completo disponibile nella [pagina della guida alla riga di comando](https://mcp-tool-shop-org.github.io/backpropagate/handbook/cli-reference/), oppure utilizza `backprop <sottocomando> --help`.
 
 ## Configurazione
 
-Ogni impostazione può essere sovrascritta utilizzando una variabile d'ambiente, preceduta dal prefisso `BACKPROPAGATE_`:
+Ogni impostazione può essere sovrascritta con una variabile d'ambiente utilizzando il prefisso `BACKPROPAGATE_`:
 
-| Variabile | Valore predefinito | Note |
+| Variabile | Predefinito | Note |
 |---|---|---|
 | `BACKPROPAGATE_LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
-| `BACKPROPAGATE_LOG_JSON` | auto | Forzare i log in formato JSON o nella console |
+| `BACKPROPAGATE_LOG_JSON` | auto | Forza l'utilizzo di log in formato JSON o nella console. |
 | `BACKPROPAGATE_MODEL__NAME` | `Qwen/Qwen2.5-7B-Instruct` | Modello predefinito |
-| `BACKPROPAGATE_TRAINING__LEARNING_RATE` | `2e-4` | Learning rate (tasso di apprendimento) |
-| `BACKPROPAGATE_LORA__R` | `256` | Rango LoRA (valore predefinito nella versione 1.3; utilizzare l'opzione `--lora-preset=fast` per il valore predefinito della versione 1.2.x, che è 16) |
+| `BACKPROPAGATE_TRAINING__LEARNING_RATE` | `2e-4` | Tasso di apprendimento |
+| `BACKPROPAGATE_LORA__R` | `256` | Rango LoRA (predefinito v1.3; utilizza `--lora-preset=fast` per il valore predefinito della v1.2.x, ovvero 16) |
 | `BACKPROPAGATE_UI__OUTPUT_DIR` | `~/.backpropagate/ui-outputs` | Sandbox del file system dell'interfaccia utente |
 
-Le chiavi nidificate utilizzano il doppio underscore (`MODEL__NAME`, non `MODEL_NAME`). La documentazione completa è disponibile nella [pagina delle variabili d'ambiente](https://mcp-tool-shop-org.github.io/backpropagate/handbook/env-vars/).
+Le chiavi nidificate utilizzano il doppio underscore (`MODEL__NAME`, non `MODEL_NAME`). Il riferimento completo è disponibile nella [pagina della guida alle variabili d'ambiente](https://mcp-tool-shop-org.github.io/backpropagate/handbook/env-vars/).
 
-## Modelli predefiniti
+## Preset dei modelli
 
-| Modello | VRAM | Licenza | Note |
+| Preset | VRAM | Licenza | Note |
 |---|---|---|---|
-| Qwen-3.5-4B | ~8GB | Apache 2.0 | Valore predefinito consigliato per modelli inferiori a 5 miliardi di parametri. Offre la migliore qualità a questa dimensione. |
-| Phi-4-mini-3.8B | ~8GB | MIT | Ottimo per ragionamento, matematica e programmazione. Licenza rigorosamente "clean". |
-| SmolLM3-3B | ~6GB | Apache 2.0 | Ricetta completamente aperta. Contesto nativo a 64K. |
-| Qwen 2.5 7B | ~12GB | Apache 2.0 | Valore predefinito esistente. Offre la migliore qualità tra i preset legacy da 7 miliardi di parametri. |
-| Qwen 2.5 3B | ~8GB | Qwen-Research | ⚠ licenza per la ricerca: consultare i termini della licenza Qwen prima di un utilizzo commerciale. |
-| Llama 3.2 3B | ~8GB | Llama Community | Un'alternativa valida a Qwen 3B, con alcune limitazioni. |
-| Llama 3.2 1B | ~6GB | Llama Community | Ideale per esperimenti rapidi su schede grafiche di piccole dimensioni. |
-| Mistral 7B | ~12GB | Apache 2.0 | Comparabile a Qwen 7B, con un diverso modello di conversazione. |
+| Qwen-3.5-4B | ~8 GB | Apache 2.0 | Predefinito consigliato per modelli inferiori a 5B. Migliore qualità per questa dimensione. |
+| Phi-4-mini-3.8B | ~8 GB | MIT | Ottimo nelle attività di ragionamento, matematica e codice. Licenza completamente aperta. |
+| SmolLM3-3B | ~6 GB | Apache 2.0 | Ricetta completamente open source. Contesto nativo di 64K. |
+| Qwen 2.5 7B | ~12 GB | Apache 2.0 | Predefinito esistente. Migliore qualità tra i preset 7B legacy. |
+| Qwen 2.5 3B | ~8 GB | Qwen-Research | ⚠ licenza di ricerca: consulta i termini della licenza Qwen prima dell'uso commerciale. |
+| Llama 3.2 3B | ~8 GB | Comunità Llama | Un'alternativa valida a Qwen 3B con alcune limitazioni. |
+| Llama 3.2 1B | ~6 GB | Comunità Llama | Per esperimenti rapidi su schede di piccole dimensioni. |
+| Mistral 7B | ~12 GB | Apache 2.0 | Simile a Qwen 7B, con un modello di chat diverso. |
 
-Altri modelli potrebbero funzionare, ma solo questi otto sono inclusi nei test automatizzati. Utilizzare l'opzione `--lora-preset=quality` (predefinita) per ottenere un rango di 256 / target all-linear, come indicato da Biderman 2024 + Thinking Machines 2025, oppure l'opzione `--lora-preset=fast` per ottenere il footprint della versione 1.2.x, con un rango di 16 / target q+v, se necessario.
+Altri modelli spesso funzionano, ma solo questi otto sono configurati in CI. Utilizzare `--lora-preset=quality` (impostazione predefinita) per obiettivi di rango 256 / completamente lineari secondo Biderman 2024 + Thinking Machines 2025, oppure `--lora-preset=fast` per l'obiettivo legacy di rango 16 / q+v se è necessario il footprint della versione 1.2.x.
 
 ## Risoluzione dei problemi
 
-Un breve elenco dei problemi più comuni che si verificano durante la prima esecuzione. L'elenco completo è disponibile nella [pagina della guida alla risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/). Per un'analisi approfondita di driver, VRAM e precisione mista, consultare la [pagina dedicata alla risoluzione dei problemi di CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/).
+Un breve elenco degli errori più comuni che si verificano durante la prima esecuzione. L'indice completo in ordine inverso è disponibile nella [pagina del manuale per la risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/). Per un'analisi approfondita di driver / VRAM / precisione mista, consultare la [pagina della risoluzione dei problemi CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/).
 
 | Sintomo | Codice di errore | Soluzione |
 |---|---|---|
-| La GPU esaurisce la memoria durante l'addestramento. | `RUNTIME_GPU_OOM` | Automatic — Backpropagate dimezza la dimensione del batch e riprova fino a 3 volte. Per disattivare questa funzione: `Trainer(oom_recovery=False)`. Per forzare l'utilizzo di un batch più piccolo: `--batch-size 1`. |
-| HuggingFace restituisce 401 / "modello non trovato" | `DEP_MODEL_LOAD_FAILED` | Eseguire il comando `huggingface-cli login` e riprovare. In caso di errori di battitura, copiare l'ID esatto da <https://huggingface.co/models>. |
-| Rifiuto della connessione `register_with_ollama`. | `DEP_OLLAMA_REGISTRATION_FAILED` | Avviare il demone: `ollama serve`. Installare da <https://ollama.com>. Operazione riprovabile. |
-| Disco pieno durante il salvataggio del checkpoint. | `STATE_CHECKPOINT_INVALID` | In caso di crash, vengono creati file `.partial`. È sicuro eliminarli. Il checkpoint precedente e valido è intatto. |
-| Addestramento interrotto a causa del surriscaldamento della GPU | `RUNTIME_GPU_TEMPERATURE_CRITICAL` | Automatic — Backpropagate mette in pausa l'esecuzione quando viene superata la soglia di temperatura e riprende quando la GPU si raffredda. Migliorare il flusso d'aria se il problema si verifica frequentemente. |
-| Richiesta di `backprop ui --share` rifiutata. | `INPUT_AUTH_REQUIRED` | Utilizzare `--auth user:password` oppure utilizzare la reindirizzamento SSH (vedere [Interfaccia Web](#web-ui)). |
-| Esportazione GGUF non riuscita al primo tentativo. | `RUNTIME_GGUF_EXPORT_FAILED` | Eseguire `pip install backpropagate[export]`; su Windows è necessario anche Visual C++ Build Tools + CMake. |
+| La GPU esaurisce la memoria durante l'addestramento | `RUNTIME_GPU_OOM` | Automatico: Backpropagate dimezza le dimensioni del batch e riprova fino a 3 volte. Per disattivare questa funzione: `Trainer(oom_recovery=False)`. Per forzare una dimensione inferiore: `--batch-size 1`. |
+| HuggingFace restituisce 401 / "modello non trovato" | `DEP_MODEL_LOAD_FAILED` | Eseguire `huggingface-cli login` e riprovare. In caso di errori di battitura, copiare l'ID esatto da <https://huggingface.co/models>. |
+| La connessione a `register_with_ollama` viene rifiutata | `DEP_OLLAMA_REGISTRATION_FAILED` | Avviare il daemon: `ollama serve`. Installare da <https://ollama.com>. Riprovare. |
+| Lo spazio su disco è insufficiente durante il salvataggio del checkpoint | `STATE_CHECKPOINT_INVALID` | Le scritture atomiche lasciano una directory `.partial` in caso di errore: è sicuro eliminarla. Il checkpoint precedente valido è intatto. |
+| L'addestramento viene interrotto a causa del surriscaldamento della GPU | `RUNTIME_GPU_TEMPERATURE_CRITICAL` | Automatico: Backpropagate si interrompe quando viene superata la soglia di temperatura e riprende quando la GPU si raffredda. Migliorare il flusso d'aria se il problema persiste. |
+| `backprop ui --share` rifiutato | `RUNTIME_UI_AUTH_NOT_ENFORCED` | Passare `--auth user:password`, oppure utilizzare invece il port-forwarding SSH (vedere [Interfaccia utente Web](#interfaccia-utente-web)). |
+| Esportazione GGUF non riuscita al primo tentativo | `RUNTIME_GGUF_EXPORT_FAILED` | `pip install backpropagate[export]`; su Windows è necessario anche Visual C++ Build Tools + CMake. |
 
 ## Segnalazione di bug
 
-Quando si verifica un errore, Backpropagate stampa una riga all'avvio, simile a `run_started run_id=<uuid>`, e associa lo stesso ID a ogni riga del log, a ogni checkpoint e a ogni voce di Weights & Biases. **Includere il `run_id` in qualsiasi segnalazione di bug**; questo permette al manutentore di correlare tutti gli elementi relativi a quella specifica esecuzione.
+Quando qualcosa fallisce, Backpropagate stampa una riga all'avvio simile a `run_started run_id=<uuid>` e associa lo stesso ID a ogni riga del log, a ogni checkpoint e a ogni voce di Weights & Biases. **Includere il `run_id` in qualsiasi segnalazione di bug**, in modo che chi si occupa della manutenzione possa correlare tutto per quella specifica esecuzione.
 
-Una segnalazione di bug efficace include:
+Una buona segnalazione di bug include:
 
-1. **L'ID di esecuzione (`run_id`)**: l'UUID visualizzato all'avvio. Un singolo UUID consente a un amministratore di correlare ogni riga del log, ogni punto di controllo e ogni voce di Weights & Biases relativa a quella specifica esecuzione.
-2. **Il codice di errore**: la riga `[NOME_CODICE]: messaggio` presente nello standard error (stderr). Consultare [codici di errore](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/) per l'elenco dei codici stabili.
-3. **La traccia dello stack (traceback) oscurata.** Lo standard error viene automaticamente oscurato in modalità non dettagliata (i token di autorizzazione, le stringhe `sk-*`, `hf_*`, le chiavi AWS, le coppie `password=` / `token=` / `api_key=` vengono eliminate) – è sicuro copiarla. Per visualizzare la traccia dello stack completa e non oscurata, eseguire nuovamente il comando con `BACKPROPAGATE_DEBUG=1` (o `--verbose`); esaminarla prima di pubblicarla.
-4. **L'output di `backprop info`**. Un singolo comando stampa informazioni su Python / PyTorch / CUDA / modello GPU / VRAM / sistema operativo / moduli aggiuntivi installati: tutto ciò di cui un amministratore ha bisogno per identificare una regressione specifica della piattaforma.
+1. **Il `run_id`**: l'UUID stampato all'avvio. Un singolo UUID consente a chi si occupa della manutenzione di correlare ogni riga del log, ogni checkpoint e ogni voce di Weights & Biases per quella specifica esecuzione.
+2. **Il codice di errore**: la riga `[CODE_NAME]: message` in stderr. Consultare [codici di errore](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/) per il catalogo dei codici stabili.
+3. **Il traceback modificato**. Stderr viene automaticamente modificato in modalità non verbose (i token Bearer, `sk-*`, `hf_*`, le chiavi AWS, le coppie `password=` / `token=` / `api_key=` vengono eliminate): è sicuro copiarlo e incollarlo. Per il traceback completo non modificato, rieseguire con `BACKPROPAGATE_DEBUG=1` (o `--verbose`); rivederlo prima di pubblicarlo.
+4. **L'output di `backprop info`**. Un singolo comando stampa Python / PyTorch / CUDA / modello GPU / VRAM / sistema operativo / extra installati: tutto ciò di cui chi si occupa della manutenzione ha bisogno per individuare una regressione specifica della piattaforma.
 
-Il [modello per la segnalazione di bug](https://github.com/mcp-tool-shop-org/backpropagate/issues/new?template=bug_report.yml) richiede esplicitamente queste informazioni, quindi la gestione delle segnalazioni è rapida. Domande, suggerimenti o discussioni del tipo "è un comportamento previsto?" devono essere pubblicate nelle [discussioni di GitHub](https://github.com/mcp-tool-shop-org/backpropagate/discussions). Le problematiche di sicurezza devono essere segnalate privatamente tramite il modulo [GitHub Security Advisory](https://github.com/mcp-tool-shop-org/backpropagate/security/advisories/new) – consultare il file [SECURITY.md](SECURITY.md) per le linee guida e i tempi di risposta.
+Il [modello di segnalazione di bug](https://github.com/mcp-tool-shop-org/backpropagate/issues/new?template=bug_report.yml) richiede esplicitamente ciascuno di questi elementi in modo che la valutazione possa procedere rapidamente. Domande, idee o discussioni su "è questo previsto?" devono essere pubblicate in [Discussioni di GitHub](https://github.com/mcp-tool-shop-org/backpropagate/discussions). I problemi di sicurezza devono essere segnalati privatamente tramite il modulo [Avviso di sicurezza di GitHub](https://github.com/mcp-tool-shop-org/backpropagate/security/advisories/new): consultare [SECURITY.md](SECURITY.md) per le politiche e i tempi di risposta.
 
 ## Privacy
 
-Tutto l'addestramento avviene localmente sulla GPU. Backpropagate non effettua richieste di rete, ad eccezione del download dei modelli da HuggingFace (che viene avviato dall'utente). Non sono presenti telemetrie né dipendenze dal cloud.
+Tutto l'addestramento avviene localmente sulla GPU. Backpropagate non effettua richieste di rete, tranne per scaricare modelli da HuggingFace (che si avvia manualmente). Nessun telemetria, nessuna dipendenza dal cloud.
 
 ## Riferimenti
 
-Le impostazioni predefinite di Backpropagate e la modalità di addestramento multi-run si basano su recenti ricerche. Se si è interessati alle tecniche sottostanti:
+Le impostazioni predefinite e la modalità di addestramento multi-esecuzione di Backpropagate sono basate su ricerche recenti. Se sei interessato alle tecniche sottostanti:
 
-- **Hu et al. 2021.** *LoRA: Low-Rank Adaptation of Large Language Models.* [arXiv:2106.09685](https://arxiv.org/abs/2106.09685) — l'articolo fondamentale che introduce LoRA, la tecnica utilizzata da Backpropagate per addestrare gli adattatori in modo efficiente.
-- **Biderman et al. 2024.** *LoRA Learns Less and Forgets Less.* [arXiv:2405.09673](https://arxiv.org/abs/2405.09673) — evidenze empiriche che dimostrano che LoRA con un rank di 256 e target lineari raggiunge una qualità simile al fine-tuning completo nella maggior parte delle attività di post-addestramento, utilizzando il 67% della potenza di calcolo. Definisce la configurazione LoRA predefinita della versione 1.3 di Backpropagate.
-- **Thinking Machines 2025.** *LoRA Without Regret.* [thinkingmachines.ai/blog/lora](https://thinkingmachines.ai/blog/lora/) — un approfondimento pratico che identifica la correzione del fattore 10 nel learning rate rispetto al fine-tuning completo, necessaria per i rank LoRA elevati.
-- **Kirkpatrick et al. 2017.** *Overcoming catastrophic forgetting in neural networks.* [arXiv:1612.00796](https://arxiv.org/abs/1612.00796) — la caratterizzazione originale del motivo per cui le reti neurali "dimenticano" l'addestramento precedente quando vengono sottoposte a fine-tuning su nuovi dati (EWC — Elastic Weight Consolidation).
-- **Wang et al. 2023.** *Orthogonal Subspace Learning for Language Model Continual Learning.* [arXiv:2310.14152](https://arxiv.org/abs/2310.14152) — O-LoRA, un approccio precedente per utilizzare LoRA per l'apprendimento continuo, che vincola i nuovi adattatori a sottospazi ortogonali.
-- **Yadav et al. 2023.** *TIES-Merging: Resolving Interference When Merging Models.* [arXiv:2306.01708](https://arxiv.org/abs/2306.01708) — una tecnica fondamentale per unire più modelli sottoposti a fine-tuning senza interferenze.
-- **Qiao & Mahdavi 2025.** *Merge before Forget: A Single LoRA Continual Learning via Continual Merging.* [arXiv:2512.23017](https://arxiv.org/abs/2512.23017) — l'algoritmo specifico implementato dal modulo di unione multi-run di Backpropagate. Un preprint di dicembre 2025; Backpropagate è il primo utilizzatore a valle noto di questo articolo.
+- **Hu et al. 2021.** *LoRA: Adattamento a basso rango di modelli linguistici di grandi dimensioni.* [arXiv:2106.09685](https://arxiv.org/abs/2106.09685) — l'articolo fondamentale che introduce LoRA, il metodo con cui Backpropagate addestra gli adattatori in modo efficiente.
+- **Biderman et al. 2024.** *LoRA impara di meno e dimentica di meno.* [arXiv:2405.09673](https://arxiv.org/abs/2405.09673) — evidenze empiriche che LoRA con rango 256 e obiettivi completamente lineari raggiunge una qualità paragonabile al fine-tuning completo nella maggior parte delle attività post-addestramento, utilizzando il 67% della potenza di calcolo. Definisce la configurazione LoRA predefinita di Backpropagate v1.3.
+- **Thinking Machines 2025.** *LoRA senza rimpianti.* [thinkingmachines.ai/blog/lora](https://thinkingmachines.ai/blog/lora/) — il seguito pratico che identifica la correzione del tasso di apprendimento (10 volte) rispetto al fine-tuning completo necessaria con un rango LoRA elevato.
+- **Kirkpatrick et al. 2017.** *Superare l'oblio catastrofico nelle reti neurali.* [arXiv:1612.00796](https://arxiv.org/abs/1612.00796) — la prima descrizione del motivo per cui le reti neurali "dimenticano" gli addestramenti precedenti quando si esegue il fine-tuning su nuovi dati (EWC — Elastic Weight Consolidation).
+- **Wang et al. 2023.** *Apprendimento di sottospazi ortogonali per l'apprendimento continuo di modelli linguistici.* [arXiv:2310.14152](https://arxiv.org/abs/2310.14152) — O-LoRA, un approccio precedente all'utilizzo di LoRA per l'apprendimento continuo, limitando i nuovi adattatori a sottospazi ortogonali.
+- **Yadav et al. 2023.** *TIES-Merging: Risolvere le interferenze durante la fusione dei modelli.* [arXiv:2306.01708](https://arxiv.org/abs/2306.01708) — una tecnica fondamentale per fondere più modelli con fine-tuning senza interferenze.
+- **Qiao & Mahdavi 2025.** *Unisci prima di dimenticare: un singolo apprendimento continuo LoRA tramite fusione continua.* [arXiv:2512.23017](https://arxiv.org/abs/2512.23017) — l'algoritmo specifico che il sistema di fusione multi-esecuzione di Backpropagate implementa. Un preprint di dicembre 2025; Backpropagate è il primo utilizzatore noto di questo articolo.
 
 ## Licenza