Esempio di fine-tuning LoRA: dal dataset al modello on-premise

Addestrare un modello AI da zero richiede migliaia di GPU e mesi di tempo — fuori dalla portata di qualsiasi PMI. Ma personalizzare un modello già esistente sul proprio dominio aziendale è un'altra storia. LoRA (Low-Rank Adaptation) è la tecnica che ha reso questo possibile su hardware accessibile: una singola GPU da gaming, pochi gigabyte di dati, qualche ora di addestramento. Il risultato è un modello che parla il linguaggio della tua azienda — letteralmente.

Fine-tuning: significato

Fine-tuning significa letteralmente "regolazione fine". Nel machine learning indica il proseguimento dell'addestramento di un modello già addestrato su un insieme di dati più piccolo e mirato, in modo che si adatti a un compito o a un dominio specifico. Il modello di partenza ha già imparato la lingua e una grande quantità di conoscenze generali; il fine-tuning gli insegna come rispondere in un contesto preciso.

Un modello linguistico come quelli che usiamo nei progetti passa in genere da tre fasi:

• Pre-addestramento: il produttore lo addestra su migliaia di miliardi di parole per prevedere il testo. Costa milioni di euro e lo fanno solo pochi laboratori.
• Post-addestramento: sempre il produttore lo rende capace di seguire istruzioni e dialogare. È la versione "instruct" o "chat" che si scarica, ad esempio da Hugging Face o con Ollama.
• Fine-tuning dell'utente: un'azienda lo specializza sui propri esempi, con il proprio gergo e il formato di risposta che le serve. È la fase di cui parla questa guida.

Esistono più modi di fare fine-tuning. Il full fine-tuning aggiorna tutti i parametri del modello; le tecniche PEFT (Parameter-Efficient Fine-Tuning), di cui LoRA e la sua variante QLoRA sono le più usate, ne aggiornano una piccola parte o aggiungono pochi parametri nuovi. Il fine-tuning può insegnare un compito (classificare ticket, estrarre dati da documenti), uno stile (il tono delle risposte ai clienti) o un formato (JSON per un gestionale), mentre è poco adatto a far "memorizzare" fatti che cambiano spesso: per quelli si usa il RAG, come vedremo più avanti.

Transfer learning vs fine-tuning

I due termini si usano spesso come sinonimi, ma non lo sono. Il transfer learning è il principio generale: riutilizzare ciò che un modello ha imparato su un compito per risolverne un altro, invece di partire da zero. Il fine-tuning è uno dei modi di metterlo in pratica, quello in cui i pesi del modello preaddestrato vengono effettivamente aggiornati.

L'altro modo classico è la feature extraction: il modello preaddestrato resta congelato e si addestra solo un piccolo strato finale. È l'approccio storico della visione artificiale, dove una rete addestrata su milioni di immagini generiche viene riutilizzata, ad esempio, per riconoscere i difetti di un prodotto. LoRA si colloca a metà strada: il modello originale resta congelato come nella feature extraction, ma le piccole matrici aggiunte modificano il comportamento di tutti gli strati come nel fine-tuning.

Il problema che LoRA risolve

I grandi modelli linguistici (LLM) come Qwen3, Gemma o Mistral vengono addestrati su enormi quantità di testo generico. Conoscono quasi tutto, ma non il tuo specifico dominio: il gergo tecnico dei tuoi macchinari, le clausole contrattuali standard del tuo settore, le procedure operative specifiche della tua azienda.

Il metodo tradizionale per specializzare un modello — il full fine-tuning — richiede di aggiornare tutti i miliardi di parametri del modello. Per un modello da 7 miliardi di parametri, questo significa:

• Decine di gigabyte di VRAM (spesso più GPU professionali in parallelo)
• Giorni di addestramento anche su hardware dedicato
• Costi computazionali proibitivi per una PMI
• Rischio concreto di "catastrophic forgetting" — il modello dimentica le conoscenze generali

LoRA risolve tutto questo con un'idea matematicamente elegante: invece di modificare i pesi originali del modello, aggiunge una piccola struttura ausiliaria che impara l'adattamento necessario.

Come funziona: la matematica semplificata

Ogni strato di un modello trasformer contiene matrici di pesi che trasformano i dati in ingresso. Queste matrici sono grandi — per un modello da 7B parametri, alcune possono avere dimensioni di 4096×4096, cioè oltre 16 milioni di valori per singolo strato.

L'intuizione chiave di LoRA: gli aggiornamenti necessari per l'adattamento a un nuovo dominio hanno una struttura a basso rango. Non serve modificare tutti i 16 milioni di valori — basta aggiungere due piccole matrici il cui prodotto approssima l'aggiornamento necessario.

Se il modello originale ha una matrice 4096×4096 (≈16M parametri), con rango r=16 bastano due matrici: 4096×16 + 16×4096 = circa 131K parametri. Una riduzione di oltre il 99% dei parametri da addestrare, con risultati spesso indistinguibili dal full fine-tuning.

I numeri concreti: hardware necessario

Un esempio pratico di fine-tuning LoRA

Prendiamo uno scenario concreto: un'azienda manifatturiera vuole un assistente che risponda alle domande tecniche dei clienti usando la terminologia esatta dei propri macchinari, non un italiano generico da manuale.

1. Il dataset: esempi istruzione → risposta

Si parte da un file con coppie domanda/risposta nel formato che il modello deve imparare a riprodurre. Un estratto realistico:

Per questo caso d'uso servono in genere 300–500 coppie di questo tipo, estratte da manuali interni, ticket di assistenza risolti e verbali di manutenzione.

2. I parametri usati

3. Il codice: l'addestramento in una trentina di righe

Il dataset si salva in un file JSONL, una conversazione per riga (qui la riga va a capo solo per leggibilità):

{"messages": [{"role": "user", "content": "Il pressostato PZ-40 va in allarme, cosa controllo?"}, {"role": "assistant", "content": "Verifica prima la taratura del pressostato PZ-40 a 6 bar; se l'allarme persiste, controlla la valvola di sfiato a monte del gruppo compressore."}]}

Lo script seguente, scritto con le librerie open source di Hugging Face (transformers, peft, trl), addestra l'adapter su un modello base Qwen3 8B caricato in 4 bit (la variante chiamata QLoRA). In questo modo l'intero addestramento sta su una singola GPU da 16–24GB:

import torch
from datasets import load_dataset
from peft import LoraConfig
from transformers import (AutoModelForCausalLM, AutoTokenizer,
                          BitsAndBytesConfig)
from trl import SFTConfig, SFTTrainer

# Modello base open source (licenza Apache 2.0)
BASE = "Qwen/Qwen3-8B"
tok = AutoTokenizer.from_pretrained(BASE)

# Pesi del modello base caricati in 4 bit: molta meno VRAM
quant = BitsAndBytesConfig(
    load_in_4bit=True, bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16)
model = AutoModelForCausalLM.from_pretrained(
    BASE, quantization_config=quant, device_map="auto")

dataset = load_dataset("json", data_files="manutenzione.jsonl",
                       split="train")

# Gli stessi parametri visti sopra: rango 16, alpha 32
lora = LoraConfig(r=16, lora_alpha=32, lora_dropout=0.05,
                  target_modules="all-linear",
                  task_type="CAUSAL_LM")

args = SFTConfig(output_dir="adapter-manutenzione",
                 num_train_epochs=3,
                 per_device_train_batch_size=2,
                 gradient_accumulation_steps=8,
                 learning_rate=2e-4,
                 bf16=True,
                 gradient_checkpointing=True)

# Si addestrano solo le matrici A e B dell'adapter
trainer = SFTTrainer(model=model, processing_class=tok,
                     train_dataset=dataset,
                     peft_config=lora, args=args)
trainer.train()

# Salva solo l'adapter (poche centinaia di MB)
trainer.save_model("adapter-manutenzione")

Il risultato è la cartella adapter-manutenzione, che contiene solo le matrici LoRA. In produzione si carica sopra lo stesso modello base, ad esempio con vLLM:

vllm serve Qwen/Qwen3-8B \
  --enable-lora \
  --lora-modules manutenzione=./adapter-manutenzione

4. La verifica: con e senza adapter

Prima dell'addestramento si mettono da parte 30–50 domande, nello stesso formato JSONL, che non entrano nel dataset di training (qui il file verifica.jsonl). Dopo l'addestramento si fanno le stesse domande al modello base e al modello con l'adapter, e si confrontano le risposte:

import torch
from datasets import load_dataset
from peft import PeftModel
from transformers import (AutoModelForCausalLM, AutoTokenizer,
                          BitsAndBytesConfig)

BASE = "Qwen/Qwen3-8B"
tok = AutoTokenizer.from_pretrained(BASE)
quant = BitsAndBytesConfig(
    load_in_4bit=True, bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16)
base = AutoModelForCausalLM.from_pretrained(
    BASE, quantization_config=quant, device_map="auto")

# L'adapter si aggancia al modello base senza modificarlo
model = PeftModel.from_pretrained(base, "adapter-manutenzione")

verifica = load_dataset("json", data_files="verifica.jsonl",
                        split="train")

def rispondi(domanda):
    inp = tok.apply_chat_template(
        [{"role": "user", "content": domanda}],
        add_generation_prompt=True, enable_thinking=False,
        return_dict=True, return_tensors="pt").to(model.device)
    out = model.generate(**inp, max_new_tokens=200, do_sample=False)
    n = inp["input_ids"].shape[1]
    return tok.decode(out[0][n:], skip_special_tokens=True)

for riga in verifica:
    domanda = riga["messages"][0]["content"]
    attesa = riga["messages"][1]["content"]
    with model.disable_adapter():      # modello base, senza LoRA
        prima = rispondi(domanda)
    dopo = rispondi(domanda)           # modello con adapter
    print(f"DOMANDA: {domanda}\nATTESA:  {attesa}\n"
          f"PRIMA:   {prima}\nDOPO:    {dopo}\n")

Con do_sample=False le risposte sono ripetibili, quindi il confronto è onesto. Se le risposte "dopo" sono giuste sulle domande di training ma sbagliate su quelle di verifica, il modello ha imparato a memoria (overfitting): di solito basta ridurre le epoche o aggiungere esempi più vari.

5. Il risultato: prima e dopo

La differenza non è la correttezza generica — è la precisione specifica: il modello con adapter cita il componente esatto (PZ-40), il valore di taratura reale dell'impianto e la procedura di verifica usata effettivamente dai tecnici dell'azienda, perché li ha "visti" durante l'addestramento sui dati aziendali.

È un esempio volutamente minimo. In un progetto reale la parte che richiede più lavoro non è lo script ma il resto: preparare e ripulire le coppie domanda/risposta e far giudicare le risposte di verifica a chi conosce il dominio, cioè i tecnici che quelle domande le ricevono davvero.

Perché Gaulin.ai usa LoRA

Non proponiamo il fine-tuning a tutti: per la maggior parte dei progetti bastano un buon sistema RAG e istruzioni ben scritte. Quando invece serve un modello che parli davvero la lingua dell'azienda, usiamo LoRA per motivi precisi:

• I dati di addestramento sono i più riservati che un'azienda abbia. Ticket di assistenza, verbali di manutenzione, contratti: con LoRA l'addestramento gira sui server del cliente, quindi il dataset non viene mai inviato a un servizio di fine-tuning in cloud.
• Basta l'hardware dell'inferenza. Una GPU da 16–24GB, la stessa che fa girare il modello ogni giorno, è sufficiente per addestrare l'adapter. Non serve noleggiare cluster né comprare GPU dedicate solo all'addestramento.
• Nessun vincolo con il fornitore del modello. Il modello base resta intatto e l'adapter è un file separato di poche centinaia di MB. Quando esce un modello base migliore si riaddestra l'adapter sullo stesso dataset, che rimane di proprietà del cliente.
• Un modello, più specializzazioni. Sullo stesso server possono convivere più adapter, per esempio uno per l'assistenza tecnica e uno per l'ufficio commerciale, caricati sopra un unico modello base senza moltiplicare la memoria necessaria.
• Si combina con il RAG. LoRA insegna al modello il gergo e il formato delle risposte, il RAG gli fornisce i dati aggiornati (listini, normative, documenti nuovi) con la citazione della fonte.

LoRA vs RAG: quando usare quale

Prima di decidere se fare fine-tuning con LoRA, è importante capire la differenza con RAG (Retrieval Augmented Generation) — l'altro approccio principale per specializzare un modello su dati aziendali.

Prima del fine-tuning: i tre gradini della personalizzazione

Personalizzare un modello non vuol dire per forza addestrarlo. Ci sono tre livelli, e conviene salire di un gradino solo quando quello precedente non basta più:

1. Istruzioni scritte bene (prompt engineering). Nessun costo aggiuntivo e risultati spesso sorprendenti: è sempre il punto di partenza.
2. RAG sui documenti aziendali. Il modello non cambia, ma risponde usando contratti, manuali, listini e normative dell'azienda. Risolve la maggior parte dei casi d'uso di una PMI e dà risultati in settimane.
3. Fine-tuning (con LoRA). Serve quando il linguaggio del settore è troppo specialistico per un modello generico, o quando ci sono centinaia di esempi di input e output da cui il modello può imparare un comportamento preciso e ripetibile.

Quando il terzo gradino serve davvero, il risultato vale l'investimento. Un modello medio addestrato su un compito ben definito spesso eguaglia modelli molto più grandi e costosi, e gira su hardware accessibile. Inoltre l'adapter addestrato sui dati dell'azienda diventa un patrimonio proprio: procedure, terminologia ed esperienza accumulate non sono replicabili da chi usa gli stessi strumenti generici.

Casi d'uso LoRA per PMI italiane

Ecco quando il fine-tuning con LoRA porta un vantaggio reale rispetto al solo RAG:

• Modello che parla come il vostro ufficio legale: genera contratti, clausole e comunicazioni nel formato e nel tono esatto dello studio, non in italiano generico
• Assistente tecnico per produzione: risponde a domande sui macchinari usando la terminologia precisa dell'impianto, non quella generica del manuale
• Classificazione automatica documenti: riconosce le categorie specifiche della vostra azienda (tipi di clienti, categorie prodotto, classi di urgenza) senza bisogno di regole esplicite
• Generazione report settoriali: produce analisi nel formato e con i KPI specifici del vostro settore (es. OEE per manifattura, conversion rate per retail)
• Chatbot con tono e stile aziendali: risponde ai clienti con la voce del brand, non con un tono generico da assistente AI

Il processo pratico con Gaulin

Un progetto di fine-tuning LoRA on-premise segue questi passi:

1. Raccolta e preparazione del dataset

Il dataset di addestramento è la parte più critica. Servono esempi nel formato istruzione → risposta ideale. Per la maggior parte dei casi d'uso aziendali, bastano 200–1.000 esempi di alta qualità. Gaulin supporta la preparazione del dataset a partire dai vostri documenti esistenti.

2. Scelta del modello base e dei parametri LoRA

Si seleziona il modello base più adatto (ad esempio Qwen3, Gemma 4 o Mistral Small, in base all'hardware disponibile) e si configurano i parametri LoRA: rango r, alpha, layer target. Per la maggior parte dei casi, r=16 con alpha=32 è un buon punto di partenza.

3. Addestramento on-premise

L'addestramento avviene interamente sui server dell'azienda usando tool come LLaMA-Factory o Axolotl. I dati aziendali non escono mai dalla rete. La durata tipica va da 2 a 8 ore su una RTX 4090.

4. Valutazione e deploy dell'adapter

Il risultato dell'addestramento è un piccolo adapter LoRA (file da 50–200 MB) che si carica sopra il modello base in Ollama o vLLM. Il modello base rimane invariato — l'adapter può essere aggiornato o rimosso senza impattare il resto del sistema.