Run #6 in poi — diario attivo

# Conversione con il converter aggiornato (Run #4 o Run #6):
python3 tools/convert_to_gguf.py --checkpoint checkpoints/run4_best.pt \
  --tokenizer checkpoints/tokenizer.model --output slm-run4.gguf

# Test inferenza:
llama-cli -m slm-run4.gguf -p "Il Parlamento europeo" -n 50 \
  --chat-template "" --no-jinja

python3 -c "import json; print(json.dumps([[i,-100] for i in range(16000,16256)]))"

# Shard 1 — articoli da 200 MB a 1300 MB
python3 tools/wiki_to_corpus.py data/itwiki.xml.bz2 \
  --skip-mb 200 --max-mb 1100 --out data/wiki_run7_s1.txt --processes 8

# Shard 2 — articoli da 1300 MB a 2400 MB
python3 tools/wiki_to_corpus.py data/itwiki.xml.bz2 \
  --skip-mb 1300 --max-mb 1100 --out data/wiki_run7_s2.txt --processes 8

# Shard 3 — articoli da 2400 MB a 3500 MB
python3 tools/wiki_to_corpus.py data/itwiki.xml.bz2 \
  --skip-mb 2400 --max-mb 1100 --out data/wiki_run7_s3.txt --processes 8

Run #7 — Esecuzione su Vast.ai (2026-10-07/08)

Parametri training

Progressione val loss

Dinamica shard 3 — val loss dettagliata

Run #7 — Benchmark locale (2026-10-08)

Risultati per prompt

GGUF Run #7 — shard 3

Run #7 — Confronto con Minerva (2026-10-08)

Minerva 350M base — risultati per prompt

Minerva 3B instruct — inutilizzabile

Tabella comparativa: SLM s3 vs Minerva 350M

Ritorno alla roadmap — fasi 05–10 (2026-10-08)

Fase 05 — Sampling avanzato (2026-10-08)

Cosa esisteva già

• temperature — scala i logit prima del softmax. Già presente, default 1.0.
• top_k — mantiene solo i top-k logit. Già presente, default None (disabilitato).

Aggiunto — repetition penalty

Prima di applicare la temperatura, penalizza i token già presenti nel contesto corrente. Per ogni token già generato: se il suo logit è positivo, viene diviso per il valore della penalità (abbassato); se negativo, viene moltiplicato (abbassato ulteriormente). Con repetition_penalty=1.3 un token già visto diventa ~30% meno probabile al passo successivo.

Questo risolve direttamente i loop osservati nel benchmark Run #7: "Foggia" × 20 (prompt Puglia) e "pourfail" (prompt pasta) erano entrambi casi di attrazione toponomastica senza penalty. La penalità viene applicata sui token nel contesto corrente (finestra max_seq_len), non sull'intera storia del training.

Aggiunto — nucleus sampling (top_p)

Dopo il filtro top_k (se attivo), ordina i logit per probabilità decrescente, calcola la probabilità cumulata e azzera tutto ciò che supera la soglia p. Si mantiene almeno il primo token.

La differenza rispetto a top_k: top_k taglia sempre a un numero fisso di candidati. Top_p si adatta alla confidenza del modello. Quando la distribuzione è concentrata (il modello sa cosa dire) il nucleo è piccolo — 3–5 token. Quando è piatta (incertezza alta) ne include di più. Con top_p=0.9 il campionamento avviene sempre sul 90% della massa probabilistica, mai sulla coda lunga di token improbabili.

Fase 06 — Valutazione quantitativa: eval.py con sliding window (2026-10-08)

Il problema della stima stocastica

Durante tutti i run #5–7, la val loss registrata nel journal è il risultato di estimate_loss(): campiona eval_steps=100 batch casuali dalla split di validazione e calcola la media. È una stima — due run sullo stesso checkpoint danno numeri leggermente diversi. Non è comparabile tra checkpoint quando il corpus di validazione cambia.

eval.py è deterministico: scorre tutto il corpus in ordine, nessun token escluso. Dato lo stesso checkpoint e lo stesso file, restituisce sempre la stessa PPL. Questo rende il confronto tra checkpoint affidabile.

Sliding window — perché non basta troncare

Il modello elabora al massimo max_seq_len = 512 token alla volta. Per corpus da centinaia di migliaia di token, l'approccio naive divide il corpus in blocchi non sovrapposti di 512. Problema: i token all'inizio di ogni blocco non hanno contesto — il modello li vede "a freddo". La sua incertezza su quei token è artificialmente alta, alzando la PPL stimata.

La soluzione è usare uno stride più piccolo di max_seq_len (default: stride = max_seq_len // 2 = 256). Ogni finestra si sovrappone con la precedente per 256 token. Di ogni finestra si scorano solo i token nuovi — quelli non ancora scorati dalla finestra precedente. In questo modo ogni token riceve il massimo contesto disponibile (fino a 511 token di storia) pur essendo scorato una volta sola.

Aggregazione corretta della PPL

La PPL totale non è la media delle PPL per finestra. Quello è biased perché finestre più corte (l'ultima del corpus) peserebbero uguale alle finestre complete. La formula corretta pesa ogni token allo stesso modo:

PPL_totale = exp( (Σ NLL_i) / (Σ n_token_i) )

dove la somma è su tutte le finestre e NLL_i è la negative log-likelihood totale (loss × n_token) della finestra i. È la media geometrica della perplexity per token sull'intero corpus.

Utilizzo

Fase 07 — Efficienza del training: gradient accumulation e BF16 (2026-10-09)

Gradient accumulation — --accumulate N

Con --accumulate 4 ogni "step" esegue 4 forward/backward consecutivi prima di chiamare optimizer.step(). Il batch effettivo diventa batch_size × accum_steps senza aumentare la VRAM: il modello elabora sempre batch_size sequenze alla volta.

La loss di ogni mini-batch viene scalata di 1/accum_steps prima del backward. I gradienti si accumulano (sommano) ad ogni chiamata a .backward() — senza lo scaling si sommerebbero N volte e l'aggiornamento sarebbe N× troppo grande. Il zero_grad() avviene una volta sola all'inizio del ciclo, non tra i mini-batch.

BF16 mixed precision — --bf16

BF16 (Brain Float 16) ha lo stesso range di float32 (8 bit di esponente) ma meno precisione decimale (7 bit di mantissa invece di 23). Su CUDA il forward pass e il calcolo della loss girano in BF16 via torch.autocast; i gradienti e i pesi master dell'ottimizzatore rimangono in float32. Risultato: ~1.5–2× speedup sul forward, ~50% meno memoria per le attivazioni.

BF16 è preferibile a FP16 per il training perché non può fare overflow (stesso range di float32 — nessun bisogno di GradScaler). Su M2 MPS il flag viene ignorato silenziosamente: MPS gestisce già mixed precision internamente. Su Vast.ai RTX 4090 è il formato nativo per i tensor core: attivarlo è sempre corretto.

Modifica al loop di training

Il loop precedente era: zero_grad → forward → backward → clip → step. Il loop aggiornato è:

Output di verifica

Il log di avvio mostra ora i parametri di efficienza:

Fase 08 — Inference ottimizzata: KV-cache (2026-10-09)

Il problema — lavoro ridondante nella generazione

In generate(), ad ogni passo t il modello riceve l'intera sequenza generata fino a quel momento e ricalcola Q, K, V per tutti i token 0..t-1. Al passo t=100, ricalcola 99 coppie K/V già calcolate al passo precedente. Il costo totale per generare n token è proporzionale a 1 + 2 + ... + n = n(n+1)/2, cioè O(n²).

Perché K e V si possono cachare. Il transformer è causale: il token alla posizione t dipende solo da 0..t-1, mai dal futuro. I K e V di un token già generato non cambieranno mai — sono determinati solo dall'embedding di quel token e dal suo indice di posizione. Q invece no: la query del token corrente serve per interrogare il contesto, è sempre nuova e non ha senso accumularla.

Meccanismo

Con la cache attiva, ogni passo di generate() lavora così:

1. Calcola Q, K, V per il solo token corrente (tensore di lunghezza 1).
2. Concatena K_nuovo con K_cache e V_nuovo con V_cache lungo la dimensione sequenza.
3. Calcola l'attention: softmax(Q · K_totaleᵀ / √d_k) · V_totale.
4. Restituisce (output, nuovo stato cache) al chiamante.

Il costo per token diventa O(n) invece di O(n²): ogni passo elabora un solo token nuovo, non l'intera sequenza.

Memoria occupata dalla cache

Per il modello medium (12 layer, d_model=512, 8 teste, d_k=64):

Trascurabile rispetto ai 175 MB dei pesi del modello.

Modifiche al codice — tre punti

1. attention.py — MultiHeadAttention.forward()
Aggiunto parametro past_kv=None (tupla (K_cache, V_cache) o None). Se presente, K e V appena calcolati vengono concatenati con la cache prima di fare l'attention. La firma diventa:

2. model.py — GPT.forward()
Aggiunto past_key_values=None (lista di tuple, una per layer). Ogni blocco riceve la sua tupla e restituisce il nuovo stato; present_key_values viene accumulato e restituito insieme ai logit:

3. model.py — GPT.generate()
Il primo passo elabora l'intero prompt e ottiene la cache iniziale. I passi successivi passano solo l'ultimo token generato (shape (1, 1)), usando la cache accumulata:

Impatto sul training — zero

train.py chiama sempre model(x, y) senza passare past_key_values. Il valore di default None preserva esattamente il comportamento precedente: nessuna concatenazione, nessuna lista da accumulare, backprop intatta. Il path di training non esegue mai la riga if past_kv is not None.

Verifica — test in locale

Due test quantitativi da eseguire dopo l'implementazione:

Risultati del test — run7_shard_s3.pt (vocab=16000, step=20000, val=2.8165)

Parametro use_cache=True è il default. Per disabilitare (debug, confronto): use_cache=False.

Fase 09 — SFT: Supervised Fine-Tuning con intent recognition (2026-10-09)

Pre-training vs SFT — la differenza fondamentale

Durante il pre-training il modello impara a fare una cosa sola: predire il token successivo. Sa continuare il testo, non sa rispondere. Se gli scrivi "Chi ha scritto la Divina Commedia?" risponde con un'altra domanda — perché nel corpus le liste di domande sono frequenti e continuarle è statisticamente plausibile. Il modello non "sa" che deve rispondere: sa solo che dopo una domanda spesso viene un'altra domanda.

SFT cambia il comportamento senza cambiare la conoscenza. Il modello sa già cos'è Dante. Non sa ancora che deve rispondere invece di continuare liberamente. Il dataset SFT lo insegna attraverso esempi.

La loss mascherata (masked loss)

La differenza tecnica rispetto al pre-training è nella funzione di loss. Il dataset SFT è una lista di coppie:

Durante il pre-training la cross-entropy viene calcolata su tutti i token della sequenza. Durante SFT viene calcolata solo sui token del completion. I token del prompt ricevono target=-100, che F.cross_entropy ignora per convenzione PyTorch. Il modello impara a produrre risposte, non a predire le domande.

Catastrophic forgetting

Con full fine-tuning (SFT senza LoRA), tutti i parametri del modello vengono aggiornati su ogni esempio. Con un dataset piccolo (100–200 esempi) su un modello da 45.9M parametri, il rischio è che il modello dimentichi il pre-training: i pesi si spostano verso il nuovo dataset e le connessioni per il vocabolario generale si indeboliscono.

train_sft.py monitora questo con un probe set: un campione fisso di generazioni sul corpus originale, valutato prima e dopo ogni checkpoint. Se la qualità del testo libero degrada significativamente, il fine-tuning sta sovrascrivendo la conoscenza di base. Con pochi step (300–500) su dataset piccolo, il forgetting è generalmente limitato.

Orientamenti possibili del dataset SFT

Il dataset SFT non descrive il mondo (quello è il pre-training): descrive come il modello deve rispondere al mondo. Ogni orientamento corrisponde a un tipo di dataset:

Orientamento scelto: intent recognition

Il modello deve imparare a classificare l'intenzione di una richiesta in linguaggio naturale e a estrarne i parametri strutturati. È il comportamento di base di qualsiasi sistema calendario o routing di comandi.

Piano del dataset — sft_mini.jsonl

Target: 120–150 coppie in italiano, distribuite su 6 intent:

Comandi di esecuzione

Risultati del run SFT — sft_intent_v1.pt

Metriche per epoca

Il forgetting ha toccato il picco a epoch 4 (×1.156, appena sopra soglia) e si è ripreso spontaneamente a epoch 5 (×1.120). Il LR era già in discesa cosine nella fase finale — il modello ha smesso di "forzare" il nuovo task e le connessioni originali hanno parzialmente recuperato. Comportamento atteso con dataset piccolo e LR conservativo.

Confronto generazioni — base vs SFT

Stesso prompt, temperature=0.1, top_k=10:

Osservazioni tecniche

• Intent detection: 5/6 corretti — il task principale funziona. Il 6° errore (delete_event → create_reminder) è plausibile con 20 soli esempi per intent.
• Valori dei campi: parzialmente corretti — il modello capisce la struttura JSON ma allucinica alcuni valori. Con più esempi e più epoche migliora.
• Trailing brackets "}"}"}"}} — artifact di generazione: il modello non ha un token di stop esplicito. In produzione: parser JSON che estrae il primo oggetto valido, oppure stop token }\n.
• Catastrophic forgetting: lieve e reversibile — il probe ha funzionato. Picco +15.6%, recovery spontaneo. LR conservativo (2e-5) ha protetto il base model.

Test di inferenza con tools/infer.py — esiti (2026-10-10)

Eseguiti 4 test con python3 tools/infer.py --checkpoint checkpoints/sft_intent_v1.pt --stop-on-json.

Analisi delle cause

• Dataset troppo piccolo per l'entity extraction. Con 20–25 esempi per intent il modello classifica parzialmente l'intent ma non ha visto abbastanza variazioni per imparare a estrarre correttamente i campi. Risultato: hallucina valori ("gioco", "martedì" come title) invece di estrarli dal testo.
• Classi difficili sottorappresentate. delete_event (20 esempi) è semanticamente vicino a create_event (25). Il modello collassa verso la classe dominante. Stesso meccanismo per reschedule_event vs create_reminder.
• Nessun intent "sconosciuto". Il dataset non contiene esempi di query fuori distribuzione. Il modello non può rifiutare: produce sempre uno degli intent di training, anche quando il prompt non corrisponde a nessuno.
• Full SFT su dataset piccolo = overfitting. Con 45,9M parametri aggiornati e soli 140 esempi, il modello ha troppa capacità per troppo poco segnale. Le hallucination sui valori degli entity sono un segnale di overfit locale su pattern lessicali specifici.

Proposte

Opzione A — Espansione dataset: portare ogni intent a 60–80 esempi con variazioni lessicali ampie ("annulla"/"elimina"/"rimuovi" per delete_event), aggiungere 20–30 esempi con completion {"intent": "unknown"} per query fuori distribuzione.

Opzione B — Semplificazione dello schema: rimuovere l'entity extraction dalla completion (solo {"intent": "..."}) finché la classificazione non è affidabile, poi reintrodurre le entità in un secondo SFT. Isola il problema di classificazione da quello di estrazione.

Fase 10 — LoRA: Low-Rank Adaptation (2026-10-10)

Il meccanismo matematico

Ogni proiezione lineare target (W_q, W_k, W_v, W_o in ogni blocco attention) viene sostituita da:

y = W·x  +  (alpha/r) · B(A(x))

Dove:

• W — peso originale congelato, shape (d_out, d_in)
• A — matrice (r × d_in), inizializzata con Kaiming uniform
• B — matrice (d_out × r), inizializzata a zero → delta nullo all'inizio
• r — rango (rank), tipicamente 4–32. Con r=8: delta = 512×8 + 8×512 = 8192 parametri per layer
• alpha/r — fattore di scala (hyperparameter di stabilità)

Il delta effettivo su W è ΔW = (alpha/r) · B @ A, shape (d_out, d_in) — identica a W. L'inizializzazione B=0 garantisce che all'inizio del training il modello LoRA si comporti esattamente come il base model, senza perturbazioni.

Perché solo le proiezioni attention

Le matrici W_q, W_k, W_v, W_o controllano come il modello dirige l'attenzione: cosa guardare, come pesare le informazioni e come ricombinarle. Specializzare queste quattro proiezioni è sufficiente per orientare il modello su task nuovi mantenendo la conoscenza pre-addestrata nelle FFN (che rimangono congelate). I feed-forward contengono la "memoria fattuale"; le attention heads controllano il "ragionamento procedurale". Si modifica il secondo senza toccare il primo.

Parametri trainabili

Implementazione — lora.py

Il file lora.py espone quattro funzioni:

• apply_lora(model, r, alpha, target_modules): congela tutti i parametri, sostituisce i Linear target con LoRALinear (wrapper frozen W + trainabili A,B). Ritorna (model, n_trainable, n_total).
• save_lora(model, path): salva solo A e B in un file ~1.5 MB. Include anche r, alpha e target_modules per il reload.
• load_lora(model, path): applica la struttura LoRA al base model e carica i pesi A,B salvati. Uso tipico: caricare best.pt, poi load_lora.
• merge_lora_model(model): crea un nuovo GPT plain con W' = W + ΔW. Compatibile con infer.py e tutti gli strumenti esistenti. Il modello restituito è in eval mode.

Bug risolto — dropout nel test di merge

Il test confrontava i logits del modello LoRA con quelli del modello merged in train mode. In train mode il dropout applica maschere casuali diverse ai due modelli → diff logits ~1.6. Con model.eval() il dropout viene disabilitato e i logits sono identici (diff = 0.00e+00). La funzione merge_lora_model è corretta; il test era nel contesto sbagliato. Fix: aggiunto .eval() nel test e nel modello restituito da merge.

Bug risolto — weight tying nel merge

In GPT, lm_head.weight e embedding.weight condividono la stessa memoria (weight tying). named_parameters() deduplica e salta lm_head.weight; state_dict() le include entrambe. La prima implementazione di merge usava named_parameters() e non trasferiva correttamente tutte le chiavi. Fix: switch a state_dict() con remap delle chiavi .linear.weight → .weight.

Risultati dei test (lora.py —— main)

Parametri totali  : 46,390,272
Parametri trainabili (LoRA): 393,216  (0.85%)
Parametri congelati: 45,997,056
Forward ok — logits shape: torch.Size([2, 64, 16000])
Merge ok — diff max logits: 0.00e+00  (atteso ~0)
Adapter salvato: 1564 KB  (atteso ~1500 KB)
Reload ok — diff max logits: 0.00e+00  (atteso ~0)

Tutti i test passati.

Integrazione in train_sft.py — Lettura B (2026-10-10)

Modifiche a train_sft.py

• Import: apply_lora, save_lora, merge_lora_model da lora.py
• Nuovi flag: --lora (bool), --lora-rank (default 8), --lora-alpha (default 16), --lora-out (path adapter)
• Dopo il caricamento del modello: apply_lora() + model.to(device) (le matrici A e B vengono create su CPU, vanno spostate sul device corretto)
• L'optimizer filtra già per p.requires_grad → riceve automaticamente solo A e B quando LoRA è attivo
• Al checkpoint save: save_lora() per l'adapter + merge_lora_model() per il merged checkpoint compatibile con infer.py

Bug risolto — device mismatch

apply_lora() crea i nuovi nn.Linear (A e B) sul device di default (CPU). Se il base model è già su MPS o CUDA, il forward passa fallisce con "Tensor for argument weight is on cpu but expected on mps". Fix: aggiunta chiamata esplicita model.to(device) dopo apply_lora().

Output del training LoRA

Ogni best checkpoint produce due file:

• Adapter (--lora-out, ~1.5 MB): solo A e B, per il dynamic/unmerged mode. Richiede il base model a runtime.
• Merged (--out, ~179 MB senza optimizer state): W' = W + ΔW, checkpoint standard compatibile con infer.py e tutti gli strumenti esistenti. Non richiede lora.py a runtime.

Comando di training reale (da eseguire)

python3 train_sft.py \
  --checkpoint checkpoints/best.pt \
  --train data/sft_mini.jsonl \
  --lora --lora-rank 8 --lora-alpha 16 \
  --epochs 10 --batch 4 --lr 2e-4 \
  --lora-out checkpoints/lora_calendar.pt \
  --out checkpoints/lora_calendar_merged.pt

Base: run7_shard_s3 (val 2.8165). Dataset: sft_mini.jsonl (140 esempi, 6 intent). Parametri trainabili: 393,216 (0.85%). Stima tempo su MPS: ~2 min per epoca, ~20 min totali.

Run LoRA — Vast.ai RTX 4090 (2026-10-10)

Setup: dataset data/sft_mini_v2.jsonl — 1 200 esempi, 200 per intent, 6 intent. Base model: run7_shard_s3 (best.pt, val 2.8165). Infra: Vast.ai istanza 55244097, NVIDIA RTX 4090 24 GB, Svezia.

Parametri:

--lora-rank 8  --lora-alpha 16
--epochs 10    --batch 4     --lr 2e-4
--device cuda
Parametri trainabili: 393 216 / 45.9 M  (0.85%)

Risultati:

Test inferenza locale (merged checkpoint):

PROMPT: Crea un appuntamento con Marco venerdì alle 15.
OUTPUT: {"intent": "create_event", "title": "appuntamento", "contact": "Marco", "date": "venerdì", "time": "15:00"}

PROMPT: Cosa ho in agenda lunedì prossimo?
OUTPUT: {"intent": "query_schedule", "date": "lunedì prossimo"}

PROMPT: Cancella tutti gli impegni di mercoledì.
OUTPUT: {"intent": "delete_event", "date": "mercoledì", "scope": "all"}

Il modello estrae correttamente intent, entità e termini temporali grezzi ("venerdì", "lunedì prossimo", "mercoledì") senza risolverli — comportamento corretto per NLU extraction. Il rumore dopo la } finale è un artefatto di generazione senza stop token e si rimuove con la prima parse JSON completa.

GGUF Export e fix inferenza (2026-10-10)

Export GGUF: stesso converter di Run #4 (tools/convert_to_gguf.py) — il merged checkpoint ha architettura identica al base model, la conversione funziona senza modifiche.

Fix inferenza Python (tools/infer_lora.py): il training usa il separatore \n\n tra prompt e completion (parametro --sep di train_sft.py). Il blocco inline originale in run_lora.sh non aggiungeva il separatore e non faceva stop al primo JSON valido — il modello generava token corretti ma continuava a produrre rumore dopo la } finale. Il nuovo script:

• Aggiunge \n\n al prompt prima dell'encoding
• Estrae il primo JSON ben formato con il parser a bilanciamento delle parentesi
• Separa raw output da JSON estratto

Risultati inferenza Python — 7 prompt:

IN : Crea un appuntamento con Marco venerdì alle 15.
OUT: {"intent": "create_event", "title": "appuntamento", "contact": "Marco", "date": "venerdì", "time": "15:00"}

IN : Sposta la riunione di domani a giovedì pomeriggio.
OUT: {"intent": "reschedule_event", "event_ref": "riunione domani", "new_date": "giovedì", "new_time": "pomeriggio"}

IN : Cosa ho in agenda lunedì prossimo?
OUT: {"intent": "query_schedule", "date": "lunedì prossimo"}

IN : Ricordami di chiamare il medico domani mattina.
OUT: {"intent": "create_reminder", "note": "chiamare il medico", "date": "domani", "time": "mattina"}

IN : Cancella tutti gli impegni di mercoledì.
OUT: {"intent": "delete_event", "event_ref": "call", "date": "mercoledì"}    ← scope mancante

IN : Aggiungi Giulia Bianchi, cell 347-1234567.
OUT: {"intent": "add_contact", "name": "Simone Bianchi", "phone": "347-12345616"}  ← nome sbagliato

IN : Elimina la riunione del martedì.
OUT: {"intent": "delete_event", "event_ref": "riunione martedì", "new_date": "martedì"}  ← new_date spurio

5/7 corretti o molto buoni, 2 con errori minori su campi opzionali. Causa probabile: le varianti "cancella tutto" e "aggiungi contatto" hanno pattern più eterogenei nel dataset sintetico. Risolvibile con dataset expansion o esempi validati aggiuntivi per quei due intent.

llama.cpp: il GGUF è valido e caricabile. Limitazione: llama-cli avvolge il prompt in una chat mode che non corrisponde al separatore \n\n usato in training — la qualità di estrazione è inferiore al path Python. Per uso con llama.cpp raccomandato solo come GGUF base per quantizzazione/distribuzione; l'inferenza di produzione usa tools/infer_lora.py.

Dataset expansion v2 — 21 intent (2026-10-11)

Motivazione

Test con tools/infer_lora.py ha rivelato che "dammi il numero di Lorena" → query_schedule (sbagliato). Il problema: il dataset v1 aveva 6 intent (create_event, reschedule_event, delete_event, create_reminder, query_schedule, add_contact) — nessun intent per interrogare i contatti, operazioni su promemoria, compleanni, festività o stato utente. Il modello non aveva alternative e classificava tutto come il più simile tra i 6 disponibili.

Architettura del dataset v2

Dataset generato da tools/gen_sft_synth_v2.py. Risolve tre problemi della v1:

1. Copertura intent: da 6 a 21 intent + unknown (22 bucket totali)
2. Genere grammaticale: EVENTI_GEN usa tuple (parola, genere, iniziale) con 4 helper per gli articoli — nessun "il videochiamata" o "una workshop"
3. Intent sconosciuto: 200 domande fuori dominio (intent: "unknown") per gestire input non supportati

Articoli italiani — implementazione

Il bug nella v1 era un EVENTI = [lista piatta di stringhe] con articoli hardcoded nei template. La v2 usa:

EVENTI_GEN = [("appuntamento","m","v"), ("riunione","f","c"), ("workshop","m","c"),
              ("videochiamata","f","c"), ("intervista","f","v"), ...]

def art_indef(eg): # un / una / un'
    word, g, i = eg
    if g == "f" and i == "v": return "un'" + word    # un'intervista
    elif g == "f":             return "una " + word  # una riunione
    else:                      return "un " + word   # un appuntamento (mai "un'")

def art_def(eg):   # il / la / l'
    word, g, i = eg
    if i == "v": return "l'" + word                  # l'appuntamento, l'intervista
    return ("la " if g == "f" else "il ") + word     # la riunione / il workshop

Regola chiave: il maschile davanti a vocale usa "un" (non "un'"). "Un appuntamento" è corretto; "un'appuntamento" è sbagliato. Solo il femminile davanti a vocale usa l'elision: "un'intervista".

Intent v2 — 21 intent

Separazione extractor / resolver

Il modello estrae i termini linguistici raw, non date assolute:

"Crea un appuntamento con Marco venerdì alle 15"
→ {"intent":"create_event","contact":"Marco","date":"venerdì","time":"15:00"}

# Non: {"date": "2026-10-16"} — quella risoluzione avviene nell'application layer
# tramite dateparser.parse("venerdì") o strumenti equivalenti

Questo disaccoppiamento rende il modello invariante rispetto alla data di training: "domani" funziona sempre, indipendentemente da quando è stato addestrato il modello.

set_status — stati supportati

Stato utente nel calendario: fuori ufficio, assente, non disponibile, in ferie, in malattia, in trasferta, non raggiungibile.

Esempi: "Sono fuori ufficio da lunedì a venerdì" → {"intent":"set_status","status":"fuori ufficio","date_start":"lunedì","date_end":"venerdì"}

Training v2 — da capo

Il training v2 parte da zero rispetto al LoRA v1. Non è possibile riutilizzare lora_calendar.pt: i 21 nuovi intent non esistevano nell'adapter v1, e le matrici A e B sono state allocate solo per i 6 pattern precedenti. Il base model (checkpoints/best.pt) rimane invariato — è congelato durante il training LoRA, non viene toccato dal fine-tuning.

• Adapter v2: checkpoints/lora_calendar_v2.pt
• Merged v2: checkpoints/lora_calendar_v2_merged.pt
• Dataset: data/sft_v2.jsonl (4200 esempi, 21 intent × 200)
• Script: run_lora.sh aggiornato, log in logs/lora_v2/

Risultati training v2

Inference test v2 (2026-10-11)

Test su checkpoint merged (--device cpu) al termine del training remoto:

IN : Crea un appuntamento con Marco venerdì alle 15.
OUT: {"intent": "create_event", "title": "appuntamento", "contact": "Marco", "date": "venerdì", "time": "15.00"}

IN : Sposta la riunione di domani a giovedì pomeriggio.
OUT: {"intent": "update_event", "event_ref": "riunione domani", "new_date": "giovedì pomeriggio", "new_time": "pomeriggio"}

IN : Cosa ho in agenda lunedì prossimo?
OUT: {"intent": "query_schedule", "date": "lunedì prossimo"}

IN : Ricordami di chiamare il medico domani mattina.
OUT: {"intent": "add_reminder", "note": "chiamare il medico", "date": "domani", "time": "mattina"}

IN : Cancella tutti gli impegni di mercoledì.
OUT: {"intent": "delete_event", "date": "mercoledì", "scope": "all"}

Tutti i 5 prompt producono JSON valido con intent corretto. Il test del caso originale problematico ("dammi il numero di Lorena") non è incluso nel test inline ma può essere verificato localmente con tools/infer_lora.py.

Test v2 su llama-server + slm-chat.html (2026-10-11)

Dopo la conversione GGUF (slm-lora-calendar-v2-q8_0.gguf, 55 MB Q8_0) e l'avvio di bash slm-chat.sh slm-lora-calendar-v2-q8_0.gguf, test interattivi con l'interfaccia grafica:

Problema: trailing garbage nella risposta

Senza stop token configurato, llama-server continuava a generare dopo il } di chiusura, producendo sequenze tipo }"}"}"}"}. Il modello entra in un loop di ripetizione perché durante il training la posizione dopo } non era mai supervisionata: la loss era calcolata solo sui token di completion, ma senza EOS finale il modello non ha imparato quando fermarsi.

Fix immediata (v2): aggiunta di stop: ["\n\n"] nella request HTTP a llama-server e post-processing JS extractFirstJson() in slm-chat.html che estrae il primo oggetto JSON valido, scartando tutto ciò che segue.

Fix strutturale: EOS token nella completion (v3)

La soluzione corretta è aggiungere esplicitamente il token EOS (ID 3, </s>) in coda alla completion durante il training SFT. Il modello impara così che dopo } deve generare EOS — e llama-server si ferma automaticamente senza bisogno di stop string né post-processing.

Implementato in train_sft.py — SFTDataset:

eos = getattr(tokenizer, 'eos_id', None)   # 3 per SPM-BPE, None per char-level

# Sequenza training: prompt_ids + comp_ids + [eos]
# Target:           [-100 × n_prompt] + comp_ids + [eos] + [-100]
#                                              ↑
#                   il token } predice EOS; l'ultimo slot non ha target
if eos is not None:
    comp_ids = comp_ids + [eos]

Dati concreti: per l'esempio "dammi il numero di Lorena" la sequenza totale è 38 token (7 prompt + 31 completion incluso EOS=3), ben dentro il limite di 512. La troncatura non è mai un problema su questo dataset.

Ogni classe tokenizer espone ora la property eos_id: _SPMTok restituisce sp.eos_id() (=3), _TiktokenTok restituisce eot_token, _CharTok restituisce None (nessun EOS dedicato nel vocabolario char-level).

Gap dataset identificati per v3

Due classi di errori sistematici emersi dal test:

1. query_schedule con granularità settimanale/mensile: "cosa devo fare settimana prossima?" viene classificato come query_datetime. Il dataset v2 copre date singole (oggi, lunedì) ma non periodi estesi (settimana prossima, questo mese, prossimi giorni). Fix: aggiungere varianti con periodi temporali a query_schedule.
2. Slot-filling nomi allucinati in update_event: "sposta con Giulio" → contact "Luca". Il dataset usa un pool ristretto di ~6 nomi ripetuti; il modello ha imparato a copiare il nome più frequente invece di estrarlo dall'input. Fix: pool di ~35 nomi generato programmaticamente in gen_sft_synth_v2.py, un nome diverso per ogni esempio.

Riflessioni architetturali — NLU deterministico e scelte di design (2026-10-11)

Dopo i test v2 è emersa una domanda strategica: stiamo usando lo strumento giusto? Il modello generativo decoder-only produce risposte NLU corrette ma non deterministiche — allucinazione di nomi, confusione tra intent simili, trailing garbage. Vale la pena capire perché e quali alternative esistono.

Il disallineamento architetturale

Il nostro SLM è decoder-only: predice il prossimo token vedendo solo i token a sinistra (causal mask). È costruito per generare. Classificare un intent e estrarre slot è invece un task discriminativo — mappare un input su una struttura fissa. Usare un modello generativo per un task discriminativo eredita tutti i problemi della generazione: output non vincolato, sensibilità ai phrasing non visti in training, slot-filling per memorizzazione invece che per copia.

L'allucinazione di "Luca" per "Giulio" in update_event è un sintomo preciso: il decoder genera il nome più probabile in quella posizione del template, non copia il nome dall'input. Un encoder bidirezionale, avendo visto l'intera frase prima di produrre l'output, estrarrebbe il valore dall'input — non lo inventa.

Encoder BERT — costruzione e differenze

BERT è encoder-only: ogni token vede tutti gli altri simultaneamente (attenzione bidirezionale, senza causal mask). Non genera — capisce. La differenza rispetto al nostro decoder è minima a livello di codice ma fondamentale per funzione:

Il token [CLS] viene preposto a ogni sequenza. Dopo i layer di attenzione bidirezionale, il suo vettore di output aggrega il significato dell'intera frase. Un layer lineare nn.Linear(d_model, 21) su questo vettore produce la distribuzione di probabilità sui 21 intent. L'output è sempre esattamente uno dei 21 valori: zero garbage strutturale possibile.

Per lo slot filling si usa l'output di ogni token — classificazione BIO (Begin-Inside-Outside) per posizione:

"sposta  l'appuntamento  con  Giulio  alle  15:00  di  domani"
   O           O          O   B-name   O    B-time  O   B-date

"Giulio" viene marcato come B-name indipendentemente da quale nome compare nella frase — il modello impara il pattern posizionale, non memorizza nomi. Questo elimina l'allucinazione per definizione.

Nel nostro codebase la distanza tra SLM e BERT è piccola: rimuovere la causal mask in attention.py, preporre [CLS] a ogni sequenza, cambiare il training objective da CLM a MLM (mascherare il 15% dei token, calcolare loss solo su quelli), aggiungere una classification head. I blocchi transformer, la FFN, le norme — identici.

GBNF — Grammar-constrained decoding

Se si vuole mantenere il modello generativo e renderlo deterministico a runtime, llama-server supporta GBNF (Generalized Backus-Naur Form): una grammatica formale che vincola il sampler token per token. A ogni step, dopo temperatura e top-k, vengono azzerati tutti i token che produrrebbero una stringa non valida secondo la grammatica.

root       ::= "{" ws "\"intent\":" ws intent-val ws "}"
intent-val ::= "\"create_event\"" | "\"query_contact\"" | ... (21 opzioni)

Quando il modello deve scegliere l'intent, solo i token che iniziano una delle 21 stringhe valide sopravvivono al sampling. Quando l'oggetto JSON si chiude, la grammatica è esaurita e la generazione termina — non per EOS appreso, ma perché non esiste nessun token ammissibile come continuazione.

La differenza concettuale rispetto al fix EOS:

EOS fix:   il modello impara a voler smettere  (comportamento appreso, può fallire)
GBNF:      il modello non può fisicamente continuare  (vincolo strutturale, non fallisce)

I grandi modelli producono JSON affidabile per i tool call principalmente grazie a logit masking e grammar constraints — non solo per training. La differenza tra "di solito produce JSON valido" e "produce sempre JSON valido" è quasi sempre un vincolo a runtime.

Serve un encoder e un decoder separati per NLU + NLG?

No, non necessariamente. Tre architetture risolvono il problema con approcci diversi:

Encoder-Decoder (T5, BART) — un singolo modello con due metà. L'encoder (bidirezionale) capisce l'input in profondità; il decoder genera condizionato al contesto dell'encoder tramite cross-attention. T5 usa prefix task: "classify: <input>" produce JSON, "respond: <input>" produce linguaggio naturale. Architettura nata esattamente per use case misti NLU + NLG.

Decoder-only a sufficiente scala — con abbastanza parametri e dati, la comprensione bidirezionale emerge implicitamente anche in un decoder. I modelli da 7B+ gestiscono NLU e NLG con un solo modello decoder. Questa emergenza non avviene a piccola scala: a 45M parametri un decoder non capisce davvero, genera — ed è per questo che il nostro modello allucina nomi e confonde intent vicini.

Due modelli in pipeline — encoder per NLU → JSON, decoder per NLG → risposta in linguaggio naturale. Separazione netta ma complessità doppia: due checkpoint, due inference, stato da passare tra i due.

Conclusione pratica: a piccola scala la soluzione elegante è l'encoder-decoder (un modello, due modalità). A grande scala (7B+) un decoder-only è sufficiente per entrambe. Il motivo per cui i sistemi in produzione usano modelli grandi via API invece di due modelli piccoli locali è esattamente il floor qualitativo già discusso: sotto una certa soglia di parametri, nessuna architettura risolve il problema in modo affidabile indipendentemente dalle scelte di design.

LoRA+SFT per task generativi (2026-10-11)

L'uso di LoRA+SFT per la classificazione degli intent è un task discriminativo travestito da generazione: la completion è sempre un JSON di 30 token con vocabolario chiuso. Ma lo stesso meccanismo si applica a task genuinamente generativi — dove l'output è linguaggio naturale di lunghezza variabile.

Il meccanismo è identico, cambia la natura della completion

LoRA+SFT non insegna al modello a capire — gli insegna a mappare un formato di input su un formato di output. Quando il pattern di questa mappatura è regolare e copribile con esempi, funziona indipendentemente dalla comprensione semantica profonda. Il pretraining su Wikipedia italiana ha già fornito grammatica, vocabolario e strutture di testo — LoRA reindirizza questi pattern verso il task specifico senza modificare quei pesi.

Task adatti — requisiti

Tre criteri identificano i task dove LoRA+SFT generativo funziona bene a questa scala:

1. Pattern regolare — la mappatura input→output è sistematica e copribile con esempi
2. Output strutturalmente definito — l'output ha una forma riconoscibile (email, lista, paragrafo con apertura/corpo/chiusura)
3. Input che segnala il formato — il prompt stesso indica chiaramente il tipo di output atteso

Esempi concreti applicabili

La categoria "tono affettivo" è la più incerta: richiede espansione semantica, non semplice slot copy. Il modello potrebbe scrivere correttamente "ti voglio molto bene e mi dispiace" oppure produrre qualcosa di stilisticamente incongruo — dipende dalla copertura di quei pattern nel dataset SFT e nel pretraining.

Dataset per generazione vs. NLU

Per task generativi il rank più alto è giustificato: la mappatura stilistica è più complessa di una classificazione e richiede più gradi di libertà nelle matrici A e B di LoRA.

RAG — architettura e ruolo del modello

Nel RAG il modello non fa retrieval — non sa nemmeno che esiste un vector DB. Riceve solo il chunk e la domanda nel prompt:

Contesto: [testo recuperato dal vector store]

Domanda: [query dell'utente]

Risposta:

Il compito del modello si riduce da "generazione libera" a "lettura + parafrasi": estrarre la risposta dal contesto fornito. Questo è più tractable di qualsiasi task generativo aperto, perché la risposta è già nel prompt — il modello deve solo trovarla e riformularla.

Il dataset SFT per RAG include esempi negativi (contesto irrilevante → "questa informazione non è presente nel testo") per evitare che il modello risponda sempre inventando. La pipeline completa:

query → [embedding model separato] → [FAISS/ChromaDB top-k chunks]
      → build prompt template → [SLM genera risposta]

Il SLM è solo il terzo step. L'embedding, il retrieval e il template building sono infrastruttura Python esterna. Questa separazione di responsabilità è il motivo per cui un modello a 45M può fare RAG utile su dominio ristretto: il problema difficile (trovare il documento rilevante) è già risolto dalla pipeline.

Limite pratico del modello a questa scala

Funziona bene per risposte estrattive — la risposta è una frase nel chunk. Cede quando:

• La risposta richiede di sintetizzare due chunk diversi
• Il contesto è lungo (il modello "dimentica" l'inizio prima di rispondere)
• La domanda richiede inferenza ("se faccio X, cosa succede a Y?")

Per documenti brevi con domande semplici (note personali, schede prodotto, manuali tecnici interni) il task è perfettamente adatto.

Limiti esplorativi del modello (2026-10-11)

Dopo LoRA v2 e la serie di riflessioni architetturali, il progetto ha raggiunto il suo obiettivo primario: ogni componente è stato costruito, compreso e testato. Vale la pena chiedersi esplicitamente cosa mancherebbe ancora da imparare da questo modello.

Cosa è stato completato

Cosa rimarrebbe — e cosa insegnerebbe

Valutazione onesta

Il valore marginale di ogni ulteriore esperimento su questo modello è in discesa. Gli esperimenti rimanenti confermerebbero principi già compresi — la qualità del dataset conta, il rank ottimale per generazione è più alto, il GBNF termina in modo deterministico. Questi sono dettagli implementativi, non scoperte architetturali.

Il modello ha fatto il suo lavoro: è uno strumento di comprensione, non di produzione. Il passo successivo naturale dipende dall'obiettivo:

• NLU in produzione su dominio ristretto → encoder BERT italiano fine-tunato su 200–500 esempi — deterministico per costruzione, nessun allucinazione strutturale
• Assistente o RAG in produzione → LoRA su Minerva o Mistral 7B (track 2 già definito nel progetto) — il floor qualitativo a 45M è reale, e non è una questione di training ma di scala
• Ricerca multimodale → Phase 11 YOLO v3, territorio genuinamente nuovo rispetto a tutto quello che abbiamo esplorato

Phase 11 — Piano YOLO v3 from scratch (2026-10-11)

YOLO v3 (You Only Look Once, versione 2018) è un modello di object detection: prende un'immagine e produce una lista di bounding box con classe e confidenza per ogni oggetto rilevato. L'architettura ha tre componenti costruibili in sequenza, ciascuno con concetti nuovi rispetto a quanto fatto con il transformer.

Componente 1 — Darknet-53 (backbone)

Il backbone estrae feature gerarchiche dall'immagine attraverso 53 layer convoluzionali con residual connections. Il principio del residual è identico a quello dei TransformerBlock: output = f(x) + x. La differenza è l'operazione di base:

Darknet-53 non usa pooling per il downsampling — usa stride=2 nelle convoluzioni, come i transformer usano pos. encoding invece di pooling. Output: feature map a 3 scale per un input 416×416:

Input  416×416  →  52×52  (dettaglio fine, oggetti piccoli)
               →  26×26  (scala media)
               →  13×13  (contesto ampio, oggetti grandi)

Componente 2 — Feature Pyramid Network + detection heads

La FPN combina le tre scale top-down: le feature map 13×13 (contesto) vengono upsamplate e concatenate con le 26×26 (dettaglio), poi di nuovo con le 52×52. Ogni cella della griglia a ogni scala predice 3 anchor box — forme predefinite che coprono diverse proporzioni (orizzontale, verticale, quadrato).

Per ogni anchor box l'output è un vettore di 85 valori (per COCO 80 classi):

[x_offset, y_offset, w_log, h_log, objectness, class_1, ..., class_80]
     2           +      2       +       1     +      80       = 85

Il modello non predice coordinate assolute — predice offset rispetto alla cella e logaritmi rispetto all'anchor. Questo è analogo al modo in cui il decoder predice logit relativi, non valori assoluti.

Componente 3 — Loss multi-componente

L_total = L_xy + L_wh + L_obj + L_noobj + L_class

L_xy, L_obj, L_class: binary cross-entropy (come la nostra cross-entropy per token). L_wh: MSE sui log-ratio bounding box. Anchor matching: ogni ground-truth viene assegnata all'anchor con IoU più alta. Il 99% delle celle non contiene oggetti → L_noobj con peso ridotto per evitare che domini.

File da costruire

Dataset consigliato per studio: Pascal VOC (20 classi, 16k immagini train, 4.9 GB) invece di COCO (80 classi, 118k immagini, 20 GB). Stessa architettura, tempi di training significativamente più bassi. I pesi pre-trainati su ImageNet possono essere usati come backbone initialization per ridurre il training da zero.

Dove si toccano CNN e transformer

La pipeline descritta (YOLO → lista testo → SLM) non connette le due architetture internamente. Ma esiste un secondo livello di integrazione — quello che LLaVA, CLIP e i moderni VLM fanno:

Immagine → CNN encoder → feature vectors [N × d_vision]
                                   ↓
                       layer di proiezione lineare
                       (apprende a mappare d_vision → d_model)
                                   ↓
                    token visivi nello spazio del LM
                                   ↓
         cross-attention con i token della domanda

Il "ponte" è un layer nn.Linear(d_vision, d_model) addestrato congiuntamente. I feature vector della CNN diventano "token visivi" che il decoder può attendere via cross-attention. Questo è il punto di contatto architetturale vero — non a livello di componenti interni, ma a livello di spazio delle rappresentazioni.

Scouting modelli base per LoRA production (2026-10-11)

L'esplorazione architetturale from-scratch è conclusa. Per i task pratici identificati (NLU calendario, writing assistant, RAG, email) serve un modello base a 7B+ su cui applicare LoRA+SFT. La scelta del base model è il punto di partenza critico.

Trovato dalla ricerca — insight chiave

Un benchmark del 2025 sull'italiano (Challenging the Abilities of Large Language Models in Italian) ha misurato che il base LLaMA 3.1 8B supera LLaMAntino-3-ANITA-8B (Italian-tuned) su commonsense, factual, linguistic, reasoning, machine translation e summarization. Conclusione degli autori: la scala del modello pesa più della supervisione language-specific. Implicazione pratica: un modello generico forte + LoRA su dominio specifico è più efficace di un modello italiano specializzato partendo da un base più debole.

Modelli candidati

* La Meta license di LLaMA 3.1 consente uso commerciale fino a 700M utenti mensili — sufficientemente libera per progetti professionali.

Raccomandazione

Per iniziare subito: Qwen2.5 7B Instruct — Apache 2.0 pulito (nessuna ambiguità legale), instruction following eccellente come baseline SFT, Q4 a 4.5 GB entra facilmente su M2 32GB, tooling LoRA maturo su HuggingFace.

Se l'italiano nativo è prioritario: LLaMAntino-3-ANITA-8B — miglior benchmark nativo disponibile oggi, GGUF disponibile, costruito su LLaMA 3.1 quindi stesso ecosistema di tooling.

Da monitorare: Minerva 20B (autunno 2026), EuroLLM-22B Instruct (già disponibile, da valutare su task specifici).