Catalogo dei file

Elenco ragionato di tutti i file rilevanti del progetto: cosa sono, da cosa derivano e come si usano.

CHECKPOINT Pesi del modello (.pt)

I file .pt sono dizionari PyTorch che contengono i pesi del modello, la configurazione architetturale, lo stato dell'ottimizzatore e la val loss al momento del salvataggio. Sono leggibili solo da train.py — per l'inferenza con llama.cpp servono i file GGUF.

Regola fondamentale: checkpoints/best.pt viene sovrascritto da ogni run attivo. Non usarlo come backup permanente. I file con nome esplicito del run (run4_best.pt, run6_shard_*.pt) sono permanenti e non vengono mai toccati dal training.
checkpoints/best.pt VOLATILE 530 MB (fp32)
Checkpoint corrente del training attivo. Viene sovrascritto ogni volta che la val loss scende sotto il minimo storico del run in corso. Durante Run #6 viene aggiornato automaticamente ad ogni shard migliore.
Uso: python3 train.py --resume — carica automaticamente questo file. Non usare per archiviazione.
checkpoints/run4_best.pt PERMANENTE 530 MB (fp32)
Miglior checkpoint di Run #4 (RoPE, Wikipedia IT, 30 000 step, batch 8). Val loss 3.5861 a step 27 500. Baseline di riferimento per il progetto: è il punto di partenza di Run #6 e la fonte dei file GGUF pubblicati su HuggingFace.
Uso: python3 train.py --resume dopo cp checkpoints/run4_best.pt checkpoints/best.pt
checkpoints/run6_best_latest.pt SINCRONIZZATO 530 MB (fp32)
Snapshot di best.pt sul server Vast.ai, sincronizzato in locale ogni 5 minuti dal watcher automatico durante Run #6. Rappresenta il miglior punto raggiunto dall'addestramento in corso. Si aggiorna più volte per shard.
Uso: base per conversione GGUF intermedia. Convertire con output distinto (slm-run6-latest.gguf) per non sovrascrivere i file Run #4.
checkpoints/run6_shard_aa.pt PERMANENTE 530 MB (fp32)
Miglior checkpoint al completamento di shard aa (primo shard di Run #6). Val loss 3.5568 — già sotto Run #4 (3.5861). Aggiornato a fine di ogni shard completato: run6_shard_ab.pt, run6_shard_ac.pt, ecc.
Uso: ripristino in caso di crash di shard successivi, conversione GGUF per shard intermedi.
checkpoints/tokenizer.model PERMANENTE 497 KB
Modello SentencePiece BPE con vocabolario di 16 000 token, addestrato su Wikipedia IT + corpus letterario. È parte integrante del checkpoint: senza di esso il modello non può tokenizzare né generare testo.
Uso: incluso automaticamente in ogni checkpoint .pt come byte serializzati. Richiesto esplicitamente da convert_to_gguf.py e da llama.cpp per l'inferenza.

GGUF File per inferenza con llama.cpp

I file GGUF sono il formato nativo di llama.cpp. Contengono i pesi in un formato ottimizzato per CPU/GPU, con metadati architetturali e vocabolario incorporati. Una volta generati non dipendono più da Python o PyTorch.

Non sovrascrivere mai i GGUF esistenti. Ogni run produce file con nome distinto. I file Run #4 (slm-run4.gguf, slm-run4-q8_0.gguf) sono il riferimento pubblico pubblicato su HuggingFace e devono restare intatti.
Compatibilità llama.cpp: la versione b11146 (ottobre 2026) ha introdotto una modifica al path di tokenizzazione BPE che rompe il caricamento dei GGUF generati da convert_to_gguf.py. Errore: unordered_map::at: key not found al momento del prompt. Il converter va aggiornato prima di usare llama.cpp per l'inferenza. In alternativa, usare PyTorch direttamente (vedi sezione Comandi).
slm-run4.gguf RUN #4 207 MB (fp16)
Modello Run #4 in formato GGUF, precisione fp16. Derivato da run4_best.pt. Pubblicato su HuggingFace (c1cc10/slm-italiano). Architettura mappata su GPT-NeoX per compatibilità con llama.cpp.
Uso: llama-cli -m slm-run4.gguf -p "Il Parlamento europeo" -n 100
slm-run4-q8_0.gguf RUN #4 56 MB (Q8_0)
Versione quantizzata Q8_0 di slm-run4.gguf. Qualità praticamente identica all'fp16 a un terzo del peso. Formato consigliato per test di inferenza su Mac (MPS o CPU).
Uso: llama-cli -m slm-run4-q8_0.gguf -p "Il Parlamento europeo" -n 100
slm-run6-shard-aa.gguf RUN #6 — SHARD AA 217 MB (fp16)
GGUF intermedio generato da run6_shard_aa.pt il 2026-10-05. Val loss 3.5568 — primo shard del training sequenziale Chinchilla. Architettura GPT-NeoX, 147 tensor scritti.
Inferenza tramite PyTorch: python3 /tmp/gen.py "prompt" 150 1.1 50 1.3 — llama.cpp b11146 ha un'incompatibilità API con questo formato (da correggere).
slm-run6-shard-aa-q8_0.gguf RUN #6 — SHARD AA 55 MB (Q8_0)
Versione quantizzata Q8_0 di slm-run6-shard-aa.gguf. Generata con llama-quantize in 447ms. Stessa limitazione llama.cpp b11146.
Test condotti via PyTorch direttamente. Generazione stabile con temp=1.1, top-k=50, rep_pen=1.3.
slm-run6.gguf PIANIFICATO ~207 MB (fp16)
GGUF finale da generare al completamento di Run #6 (tutti e 7 gli shard). Sarà il modello Chinchilla-optimal del progetto.
Da generare da checkpoints/best.pt a fine Run #6.

SORGENTE Architettura e training

train.py37 KB
Script principale di training. Gestisce tokenizer a 3 backend (char, tiktoken, bpe-spm), dataset con sliding window, AdamW con schedule LR, gradient clipping, checkpoint, --resume, --reset-best e generazione periodica. Punto di ingresso unico per tutti i run.
Uso: python3 train.py --help per le opzioni. Flag chiave: --resume --reset-best per training sequenziale multi-shard.
attention.py7.4 KB
Implementazione di scaled dot-product attention, causal mask e MultiHeadAttention con RoPE (Rotary Position Embedding). Cuore architetturale del modello.
transformer.py6.9 KB
TransformerBlock (pre-norm, residual), FeedForward con GELU, LayerNorm. Ogni istanza di TransformerBlock corrisponde a un layer del modello.
model.py9.0 KB
GPTConfig (configurazione architetturale), GPT (forward pass, generazione, weight tying, conteggio parametri). Il modello competo è definito qui.
run6_sequential.sh2.6 KB
Script shell per Run #6 su Vast.ai. Loop su 7 shard (aa→ag), 8 000 step ciascuno, batch=32, --resume --reset-best, salvataggio checkpoint intermedio per shard. Attualmente in esecuzione sul server remoto.
Uso remoto: tmux new-session -d -s run6 'bash run6_sequential.sh'

DATI Corpus e shard pre-tokenizzati

I file .bpe-spm.v16000.tokens.pt sono shard del corpus già tokenizzati e salvati come tensori PyTorch int16. Vengono caricati da train.py all'avvio evitando la tokenizzazione (operazione lenta). Ogni shard copre circa 289-297 milioni di token.

data/shards/shard_{aa…ag}.txt.bpe-spm.v16000.tokens.pt 7 FILE ~553 MB cad. · 3.9 GB totale
Sette shard del corpus CulturaX IT pre-tokenizzati con il tokenizer BPE-SPM a 16 000 vocaboli. Copertura totale: ~917 milioni di token (Chinchilla parity per un modello da 46M parametri). Generati in locale sull'M2 e caricati su Vast.ai per Run #6.
Caricati automaticamente da train.py --data data/shards/shard_aa.txt se il file .pt corrispondente è presente e ha timestamp non più recente del tokenizer.
data/shards/shard_{aa…ag}.txt 7 FILE ~1.2 GB cad. · 8.4 GB totale
Testi grezzi in italiano da CulturaX IT, suddivisi in 7 segmenti da ~1.18 GB. Servono come riferimento per la validazione della cache: train.py confronta il timestamp del .txt con quello del .pt per decidere se la cache è valida.

TOOL Script in tools/

tools/convert_to_gguf.py
Converte un checkpoint .pt SLM in formato GGUF (architettura GPT-NeoX), compatibile con llama.cpp. Gestisce il mapping dei pesi, la configurazione RoPE, il vocabolario SentencePiece. Produce un file fp16.
Uso: python3 tools/convert_to_gguf.py --checkpoint checkpoints/run6_shard_aa.pt --tokenizer checkpoints/tokenizer.model --output slm-run6-shard-aa.gguf
tools/quantize_q8.py
Quantizza un file GGUF fp16 in Q8_0 usando llama-quantize. Q8_0 riduce il peso a ~27% dell'fp16 con perdita di qualità trascurabile per questo modello.
Uso: python3 tools/quantize_q8.py slm-run6-shard-aa.gguf — produce slm-run6-shard-aa-q8_0.gguf
tools/eval_ppl.py
Valutazione di perplexity interattiva su testo libero. Carica un checkpoint .pt e calcola la PPL su qualunque testo passato via stdin o argomento. Utile per confrontare la qualità tra run senza riaddestrare.
Uso: echo "Il governo italiano" | python3 tools/eval_ppl.py
tools/epub_to_text.py
Estrae testo pulito da file EPUB (ebooklib + beautifulsoup4). Gestisce caratteri speciali tipografici (narrow no-break space, BOM, ellissi). Supporta directory intere e modalità append.
Uso: python3 tools/epub_to_text.py libro.epub --out data/corpus_letterario.txt --append
tools/fetch_hf_corpus.py
Streaming generico da HuggingFace: qualsiasi dataset, filtro lingua, campo annidato, limite per GB o numero di documenti. Non scarica il dataset completo — usa lo streaming incrementale.
Uso: python3 tools/fetch_hf_corpus.py --dataset uonlp/CulturaX --lang it --limit-gb 10
tools/filter_corpus.py
Pipeline di qualità a 4 stadi: euristico (lunghezza, ratio alfanumerici) → fastText lingua → deduplicazione MD5 → PPL scorer. Per il corpus CulturaX usato in Run #6 sono stati applicati solo euristico + dedup (senza PPL scorer, per evitare bias verso il registro enciclopedico di Run #4).
tools/convert_to_text.py
Converter universale da PDF, DOCX, PPTX, EPUB, HTML, ODT, TXT, MD a testo piano. Utile per arricchire il corpus con documenti di dominio.

Convenzione di naming per i run futuri

Ogni run e ogni shard produce file con nome che non può collidere con run precedenti. La struttura è:

TipoPatternEsempio
Checkpoint shardrun{N}_shard_{XX}.ptrun6_shard_ab.pt
Checkpoint run (best)run{N}_best.ptrun6_best.pt
Snapshot liverun{N}_best_latest.ptrun6_best_latest.pt
GGUF fp16 shardslm-run{N}-shard-{XX}.ggufslm-run6-shard-aa.gguf
GGUF Q8 shardslm-run{N}-shard-{XX}-q8_0.ggufslm-run6-shard-aa-q8_0.gguf
GGUF fp16 finaleslm-run{N}.ggufslm-run6.gguf
GGUF Q8 finaleslm-run{N}-q8_0.ggufslm-run6-q8_0.gguf
Il pattern slm-run{N}-latest.gguf non va usato come nome permanente: il suffisso latest è riservato agli snapshot intermedi e verrebbe sovrascritto. Usarlo solo per test locali.

Comandi di conversione e inferenza

Conversione GGUF da shard aa (Run #6 intermedio)

# Dal progetto root python3 tools/convert_to_gguf.py \ --checkpoint checkpoints/run6_shard_aa.pt \ --tokenizer checkpoints/tokenizer.model \ --output slm-run6-shard-aa.gguf

Quantizzazione Q8_0

llama-quantize slm-run6-shard-aa.gguf slm-run6-shard-aa-q8_0.gguf Q8_0

Inferenza con llama.cpp (interattiva)

llama-cli -m slm-run6-shard-aa-q8_0.gguf \ -p "Il Parlamento europeo" \ -n 200 --temp 0.8 --top-k 40 --top-p 0.9

Inferenza con llama.cpp (prompt da stdin)

echo "La ricerca scientifica" | llama-cli -m slm-run6-shard-aa-q8_0.gguf \ -n 150 --temp 0.7 -f /dev/stdin

Download checkpoint da Vast.ai (manuale)

rsync -avz -e "ssh -i ~/.ssh/vastai_slm -p 13476" \ root@ssh2.vast.ai:/workspace/slm/checkpoints/best.pt \ checkpoints/run6_best_latest.pt