Guida AI locale 4: fine-tuning con Unsloth — quando ha senso e quando basta il prompt

Quarta puntata della serie sull'AI locale. Nella puntata 1 abbiamo deciso se ha senso uscire dal cloud, nella puntata 2 quale runtime usare, nella puntata 3 quanto modello entra nella tua VRAM. Qui la domanda è un'altra: il modello sbaglia, e devi decidere se allenarlo o se basta cambiare quello che gli dai in input.

Il pezzo è costruito solo sulla documentazione ufficiale, letta il 26 ottobre 2026: docs e repository di Unsloth, documentazione Hugging Face di PEFT e TRL, guida all'import di Ollama, guide di OpenAI e Anthropic sull'ottimizzazione dei modelli. Non ho fatto test né allenato modelli per scriverlo: niente tempi di training, niente benchmark miei. I numeri che trovi sono quelli pubblicati dalle fonti, e lo dico ogni volta.

Le versioni di riferimento, lo stesso giorno: il pacchetto Python unsloth è alla 2026.10.8 su PyPI (pubblicata il 23 ottobre), l'ultima release dell'app Unsloth su GitHub è la v0.1.910-beta, sempre del 23 ottobre.

In breve:

• Prima del fine-tuning chiediti cosa sbaglia il modello. Istruzioni poco chiare si sistemano nel prompt, un formato con qualche esempio, informazioni che mancano o cambiano spesso con un RAG.
• Il fine-tuning ha senso quando gli esempi che servono non entrano nel contesto, quando vuoi prompt più corti su volumi alti, quando un modello piccolo deve fare bene un compito stretto, quando il comportamento resta incoerente nonostante prompt ed esempi.
• Senza un set di prove non puoi saperlo. Sia OpenAI sia Anthropic mettono le eval prima del prompt engineering.
• Unsloth è un framework open source per allenare e far girare modelli in locale: LoRA, QLoRA, full fine-tuning, RL. Si usa come app desktop, come interfaccia web (Studio) o come libreria Python (Core).
• Per il training la documentazione indica GPU NVIDIA, AMD e Intel e i Mac; Unsloth Core richiede una GPU NVIDIA con CUDA capability 7.0 o superiore, oppure le guide dedicate per AMD e Intel. La tabella VRAM parte da 3,5 GB per un 3B in QLoRA, come minimo assoluto.
• Alla fine esporti un adapter LoRA, un modello fuso a 16 bit in safetensors (per vLLM) o un GGUF (per Ollama, llama.cpp e LM Studio). Il chat template va tenuto uguale tra training e inferenza.

Prima domanda: cosa sbaglia il modello

"Il modello non va bene" non è un problema che il fine-tuning sa risolvere. Lo è "il modello risponde in un formato sbagliato una volta su cinque", oppure "non conosce i nomi dei nostri prodotti", oppure "è troppo lento per il volume che dobbiamo servire". Ognuno di questi errori ha uno strumento diverso.

La guida all'ottimizzazione dei modelli di OpenAI descrive un ciclo in quest'ordine: scrivi eval che misurano l'output e fissano una base, lavori sul prompt, e solo per alcuni casi passi al fine-tuning, misurando ogni modifica con le stesse eval. Sul prompt la guida scrive che il prompt engineering "può essere tutto ciò che ti serve" e indica tre leve: dare il contesto che il modello non ha, istruzioni chiare, esempi di output corretti, cioè il few-shot.

La panoramica sul prompt engineering di Anthropic parte dallo stesso punto: prima di lavorare sul prompt servono criteri di successo definiti e un modo empirico per verificarli. E aggiunge che non tutti i criteri si risolvono con il prompt: latenza e costo, per esempio, a volte si sistemano prima cambiando modello.

Tradotto per chi lavora in locale:

Due note su questa tabella. Il prompt lungo con molti esempi costa token a ogni richiesta, e lì la cache del prompt cambia il conto sulle API cloud. E un RAG locale è un argomento a sé, che la serie tratterà in una delle prossime puntate.

Quando il fine-tuning ha senso

La guida di OpenAI elenca i vantaggi del fine-tuning rispetto al solo prompt. Valgono per qualsiasi modello, non solo per quelli di OpenAI:

• Più esempi di quanti ne entrino nel contesto. Il modello vede migliaia di casi durante l'allenamento, non i quattro che stanno nel prompt.
• Prompt più corti. Meno esempi e meno contesto a ogni richiesta vuol dire meno token, e secondo la guida anche latenza più bassa.
• Dati sensibili fuori dal prompt. Gli esempi stanno nei pesi, non viaggiano in ogni richiesta.
• Un modello più piccolo per un compito preciso. Quando un modello grande non conviene per costo, se ne allena uno piccolo a fare bene quella cosa.

L'ultimo punto è quello che interessa di più in locale. La puntata 3 finiva con una domanda: invece di comprare VRAM per un modello più grande, ha senso adattare un modello piccolo? Il fine-tuning è la risposta quando il compito è stretto e ripetitivo: classificare, estrarre campi, rispondere in un formato fisso, adottare un tono.

Una nota di contesto: sulla piattaforma di OpenAI il fine-tuning è in chiusura. La stessa guida scrive che non è più accessibile ai nuovi utenti e che chi lo usa già potrà creare job di training ancora per alcuni mesi. Per chi vuole allenare un modello, la strada passa sempre più dai modelli open-weight, ed è il terreno di questa serie.

Quando basta il prompt, o serve un RAG

La documentazione di Unsloth ha una pagina dedicata, FAQ + Is Fine-tuning Right For Me?, e la sua posizione è chiara: il fine-tuning può aggiungere conoscenza al modello e può fare quasi tutto quello che fa un RAG, ma non il contrario. È la posizione di chi vende il fine-tuning, quindi va letta come tale. La stessa pagina, però, riconosce al RAG un vantaggio netto: accedere a informazioni aggiornate. E consiglia di combinare i due approcci invece di scegliere.

Il vincolo che decide, nella pratica, è quanto cambiano i dati. Se cambiano ogni settimana, allenare un modello a ogni modifica non regge: il RAG li legge al momento della richiesta. Se il problema è il modo di rispondere, cioè formato, tono, struttura, un RAG non lo risolve, perché non cambia i pesi.

Ci sono poi casi in cui il fine-tuning è la scelta sbagliata a prescindere:

• Non hai un set di prove. Senza casi da confrontare prima e dopo non sai se il modello allenato è migliore del base. La puntata 5 è dedicata a questo.
• Non hai dati. La guida ai dataset di Unsloth indica come minimo indispensabile almeno 100 righe per risultati ragionevoli, e preferibilmente oltre 1.000. Precisa che conta soprattutto la qualità.
• La licenza del modello non lo permette. Prima di allenare e distribuire un modello derivato, leggi i termini: le differenze tra Apache 2.0, Llama, Gemma e Qwen sono nel pezzo sulle licenze dei modelli open-weight.

Cosa fa Unsloth

Unsloth è un progetto open source per allenare e far girare modelli sulla propria macchina. La documentazione lo presenta in tre forme:

• Unsloth Desktop, l'app nativa per macOS, Windows e Linux.
• Unsloth Studio, un'interfaccia web che si installa in locale e permette il fine-tuning senza codice, con esportazione dei modelli e creazione dei dataset (Data Recipes).
• Unsloth Core, la libreria Python originale, per il training da codice.

Sulla licenza il README del repository è preciso: il pacchetto principale è Apache 2.0, alcuni componenti opzionali come l'interfaccia di Studio sono AGPL-3.0. Se lo integri in un prodotto, la differenza conta.

Sul fronte dei metodi, la documentazione elenca LoRA, QLoRA, full fine-tuning, pretraining, training a 8 bit e FP8, e reinforcement learning con GRPO e DPO. Il progetto dichiara un training 2 volte più veloce con il 70% di VRAM in meno e senza perdita di accuratezza. È un dato del vendor, non l'ho verificato: la pagina di integrazione di Hugging Face TRL riporta "fino a 2 volte" e "fino all'80%". Prendilo come ordine di grandezza dichiarato, non come garanzia sul tuo hardware.

La parte tecnica che conta: Unsloth si appoggia all'ecosistema Hugging Face. Secondo la documentazione di TRL è compatibile con SFTTrainer, e il modello salvato è compatibile con la libreria transformers. Non cambi stack, sostituisci il caricamento del modello.

Sui modelli, la documentazione parla di oltre 500 modelli supportati tra testo, visione, audio, embedding. Il catalogo dei modelli include le famiglie Qwen, Gemma, Llama, Mistral, DeepSeek, GLM, Phi e gpt-oss, con versioni GGUF per l'inferenza e versioni a 4 bit in safetensors per il fine-tuning.

Cosa sono LoRA e QLoRA, quanta memoria chiedono e perché il full fine-tuning è quasi sempre fuori portata su una GPU consumer è spiegato nel pezzo su LoRA, QLoRA o full fine-tuning. Qui basta il riassunto: si congela il modello e si allenano piccole matrici aggiuntive, l'adapter. QLoRA fa lo stesso con il modello base quantizzato a 4 bit, e la guida al fine-tuning di Unsloth consiglia di partire da lì.

Requisiti hardware, come li scrive la documentazione

La pagina Unsloth Requirements distingue tra Studio e Core:

Due dettagli dalla stessa pagina. Le GTX 1070 e 1080 funzionano, ma la documentazione le definisce lente. E sul Mac la pagina è disallineata: la parte su Studio dice che il training è supportato, quella su Core che il supporto Apple Silicon e MLX è ancora in lavorazione. Su Mac, quindi, la strada documentata per allenare è Studio o Desktop.

Per la VRAM la pagina pubblica una tabella per dimensione del modello, avvertendo che sono minimi assoluti e che alcuni modelli chiedono di più. Qualche riga, così come è pubblicata:

Se vai fuori memoria, la causa più comune secondo la documentazione è una batch size troppo alta: il consiglio è scendere a 1, 2 o 3. Se invece la scelta è tra un Mac e una GPU NVIDIA, i vincoli sono in Mac con Apple Silicon o GPU NVIDIA.

Quale modello allenare e quanti dati servono

La guida What Model Should I Use? dà due indicazioni pratiche.

La prima: per chi inizia, un modello instruct piccolo. La guida al fine-tuning cita Llama 3.1 8B come esempio. I modelli instruct si allenano con i template di conversazione (ChatML, ShareGPT) e chiedono meno dati dei modelli base.

La seconda: la scelta tra instruct e base dipende dai dati.

• Meno di 300 righe: di solito meglio il modello instruct.
• Da 300 a 1.000 righe di buona qualità: vanno bene entrambi.
• Oltre 1.000 righe: in genere conviene il modello base.

Sui nomi dei file, la documentazione spiega una convenzione utile: i modelli che finiscono in unsloth-bnb-4bit sono i quant dinamici a 4 bit di Unsloth, che usano un po' più VRAM dei bnb-4bit standard ma con accuratezza più alta, secondo il vendor. Quelli senza suffisso sono gli originali a 16 o 8 bit, a volte con correzioni al chat template o al tokenizer.

Il flusso in codice

Questo è lo schema documentato nella pagina TRL su Unsloth, ridotto all'essenziale. Non l'ho eseguito: serve a vedere dove stanno le scelte.

from unsloth import FastLanguageModel
from trl import SFTConfig, SFTTrainer

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/llama-3.1-8b-unsloth-bnb-4bit",
    max_seq_length=2048,
    load_in_4bit=True,  # QLoRA; False per LoRA a 16 bit
)
model = FastLanguageModel.get_peft_model(
    model,
    r=16,
    lora_alpha=16,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                    "gate_proj", "up_proj", "down_proj"],
)
trainer = SFTTrainer(
    model=model,
    args=SFTConfig(output_dir="./output", max_length=2048),
    train_dataset=dataset,  # il tuo dataset
)
trainer.train()

Le scelte sono tre: il modello di partenza, il metodo (load_in_4bit per QLoRA; full_finetuning=True per il fine-tuning completo, uno alla volta) e il dataset. Gli iperparametri di partenza (rank, alpha, learning rate 2e-4, da 1 a 3 epoche) sono discussi nel pezzo su LoRA e QLoRA.

Durante il training la guida di Unsloth suggerisce di guardare la loss: per molti casi un valore intorno a 0,5–1,0 è un buon segnale, ma dipende da dataset e compito. Una loss che va a zero può voler dire overfitting, quindi serve anche una validazione. Per la valutazione la guida propone di tenere da parte il 20% dei dati, o di valutare a mano chattando con il modello.

Export: GGUF per Ollama, safetensors per vLLM

Alla fine del training hai tre cose che puoi salvare. Sono le stesse tre opzioni della pagina Export di Unsloth Studio, e da codice corrispondono a funzioni diverse:

Per il GGUF, la pagina Saving to GGUF mostra q4_k_m, q8_0 e f16 come metodi principali, e Unsloth usa llama.cpp per la conversione. Per Ollama la guida Saving to Ollama aggiunge un dettaglio comodo: Unsloth genera da solo il Modelfile che Ollama richiede, con dentro il chat template usato nel training.

Per vLLM, la guida di Unsloth usa il salvataggio merged_16bit, poi vllm serve sulla cartella. La stessa guida sconsiglia esplicitamente di fondere il modello a 4 bit, salvo casi specifici.

Se l'adapter l'hai allenato con PEFT invece che con Unsloth, la strada è la stessa: merge_and_unload() fonde l'adapter nel modello base. La guida LoRA di PEFT ricorda che non è un'operazione in place: devi usare il modello che la funzione restituisce.

Poi l'import in Ollama, secondo la documentazione ufficiale: un Modelfile con FROM che punta alla cartella dei safetensors o al file GGUF, poi ollama create.

FROM ./modello-finetuned-q4_k_m.gguf

Attenzione a un dettaglio: Ollama non quantizza i GGUF durante l'import. Il file va preparato e quantizzato prima, con Unsloth o con llama-quantize di llama.cpp. Le differenze tra GGUF, safetensors e MLX, e quale runtime legge cosa, sono nel pezzo su GGUF, safetensors o MLX. Per esporre il modello ai tuoi tool c'è la guida alle API OpenAI-compatible in locale.

L'errore più comune dopo l'export

Le guide di Unsloth su GGUF e Ollama descrivono lo stesso problema: il modello risponde bene dentro Unsloth e male in Ollama o vLLM, con testo senza senso, generazioni che non finiscono o output ripetuti. La causa più comune, secondo la documentazione, è un chat template sbagliato. Va usato lo stesso template del training anche nel runtime, con il token di fine sequenza corretto, e va controllato che il runtime non aggiunga (o tolga) un token di inizio sequenza.

È il primo controllo da fare se l'export "rompe" il modello, prima di rifare il training.

Errori comuni

• Allenare prima di misurare. Senza un set di prove non sai se il modello allenato è migliore del base, né se il problema si risolveva con il prompt.
• Usare il fine-tuning per dati che cambiano. Per informazioni aggiornate la stessa documentazione di Unsloth riconosce il vantaggio del RAG.
• Partire dal full fine-tuning. La guida di Unsloth lo indica come errore comune: si prova prima con LoRA o QLoRA, e se non funziona lì quasi certamente non funzionerà nemmeno il fine-tuning completo.
• Leggere la tabella VRAM come garanzia. Sono minimi: batch size e contesto lungo fanno salire il conto.
• Prendere i numeri di velocità del vendor come promessa. "2 volte più veloce" e "70% di VRAM in meno" sono dichiarazioni del progetto, non misure sul tuo hardware.
• Cambiare chat template tra training e inferenza. È la causa principale degli output rotti dopo l'export.

Cosa conviene fare adesso

• Scrivi in una riga cosa sbaglia il modello, con tre o quattro esempi reali.
• Prova prima prompt più chiaro, poi few-shot, poi RAG se mancano informazioni. Misura ogni passaggio sugli stessi casi.
• Se arrivi al fine-tuning, controlla la licenza del modello e conta le righe del dataset: la documentazione di Unsloth indica 100 righe come minimo indispensabile.
• Controlla la tua GPU sulla pagina dei requisiti e trova la riga della tabella VRAM che ci sta con margine. Su Mac, guarda Studio o Desktop.
• Parti da QLoRA su un modello instruct piccolo, poi esporta in GGUF per Ollama o in merged_16bit per vLLM, con lo stesso chat template del training.

La prossima puntata della serie è sulle eval locali: come costruire il set di casi che serve prima di ogni decisione di questo pezzo. Le puntate uscite sono nell'hub AI Engineering, i termini tecnici (adapter, quantizzazione, VRAM) nel glossario.