Update README.md

README.md

@@ -1,3 +1,156 @@
----
-license: gpl-3.0
----
+---
+license: gpl-3.0
+---
+
+# 🧠 microDAC
+
+**Progetto:** microDAC  
+**Azienda:** M.INC.  
+**Autore:** Mattia  
+**Versione:** 1.0  
+**Modello:** Decoder-only, 40M parametri  
+**Linguaggio target:** Italiano conversazionale
+
+---
+
+## 📌 Descrizione generale
+
+microDAC è un modello linguistico compatto progettato da M.INC. per gestire conversazioni in italiano in modo naturale, fluido e contestuale.  
+È pensato per essere leggero, addestrabile su GPU consumer e facilmente integrabile in chatbot, assistenti vocali o agenti embedded.
+
+Il training è supervisionato e ottimizzato per generare risposte coerenti, evitando la ripetizione dei prompt utente e focalizzandosi sulla qualità delle risposte.
+
+---
+
+## 🧱 Architettura del modello
+
+| Parametro         | Valore         |
+|-------------------|----------------|
+| Tipo              | Decoder-only (GPT2-like) |
+| Parametri totali  | ~40 milioni    |
+| Vocab size        | 32.000         |
+| Context window    | 2048 token     |
+| Embedding dim     | 512            |
+| Layer             | 16             |
+| Attention heads   | 8              |
+| FFN dim           | 2048 (gelu_new)|
+| Attivazione       | GELU (new)     |
+| Precisione        | FP16/BF16      |
+| Gradient checkpointing | ✅ Attivo |
+
+---
+
+## 🗣️ Tokenizer
+
+- Tipo: Byte-Pair Encoding (BPE)  
+- Addestrato da zero su `microDAC_dataset.jsonl`  
+- Special tokens:
+  - `<|user|>`: inizio turno utente
+  - `<|assistant|>`: inizio risposta modello
+  - `<|sep|>`: separatore fine turno
+  - `<|pad|>`, `<|bos|>`, `<|eos|>`: padding e delimitatori
+
+Il tokenizer è salvato in `tokenizer_microDAC/` e viene caricato automaticamente. Se non esiste, viene ricreato.
+
+---
+
+## 🎯 Obiettivo di training
+
+Il modello è addestrato per generare solo le risposte dell’assistente.  
+I token dell’utente vengono mascherati con `-100` nei label per evitare che il modello li imiti.
+
+### Masking logico:
+```text
+<|user|> ... <|sep|>        → label = -100
+<|assistant|> ... <|sep|>   → label = token_id
+```
+
+---
+
+## ⚙️ Parametri di training
+
+| Parametro               | Valore         |
+|-------------------------|----------------|
+| Epochs                  | 2              |
+| Batch per device        | 8              |
+| Gradient accumulation   | 4              |
+| Learning rate           | 3e-4           |
+| Weight decay            | 0.01           |
+| Scheduler               | Cosine         |
+| Warmup ratio            | 0.05           |
+| Max grad norm           | 1.0            |
+| Precision               | FP16/BF16      |
+| Optimizer               | AdamW (torch)  |
+| Checkpointing           | ogni 2000 step |
+| Resume automatico       | ✅             |
+| Save best model         | ✅             |
+
+---
+
+## 🧩 File e struttura
+
+| File / Cartella         | Descrizione                                      |
+|-------------------------|--------------------------------------------------|
+| `train_microDAC.py`     | Script completo di training                      |
+| `microDAC_dataset.jsonl`| Dataset in formato JSONL                        |
+| `tokenizer_microDAC/`   | Tokenizer BPE addestrato                        |
+| `./microDAC-40M/`       | Output training + checkpoint                    |
+| `./microDAC-40M/final/` | Modello finale e tokenizer salvati              |
+
+---
+
+## 🖥️ Compatibilità e ambiente
+
+- Sistema operativo: Windows (con `freeze_support`)
+- GPU consigliata: ≥12 GB VRAM
+- Framework: Hugging Face Transformers + Datasets
+- Precisione: FP16/BF16 automatico
+- Multiprocessing: gestito con `if __name__ == "__main__"` e `dataloader_num_workers=0`
+
+---
+
+## 🔄 Ripresa da checkpoint
+
+Lo script cerca automaticamente l’ultimo checkpoint valido (`checkpoint-XXXX`) e riprende il training.  
+Se non trova nulla, parte da zero.
+
+---
+
+## 📦 Output finale
+
+Alla fine del training, il modello e il tokenizer vengono salvati in:
+```
+./microDAC-40M/final/
+```
+
+Contiene:
+- `pytorch_model.bin`
+- `config.json`
+- `tokenizer.json`
+- `special_tokens_map.json`
+- `vocab.json`
+
+---
+
+## 🛠️ Modifiche consigliate
+
+- Per aumentare la qualità: alza `N_LAYER` a 24 e `N_EMBD` a 768 (→ ~120M parametri)
+- Per ridurre VRAM: abbassa `N_CTX` a 1024 e usa `adamw_bnb_8bit` con bitsandbytes
+- Per training multi-turno: costruisci prompt concatenati con alternanza `<|user|>...<|assistant|>...` e maschera solo l’ultimo blocco
+
+---
+
+## 📣 Autore e contatti
+
+**Mattia — M.INC.**  
+Per domande tecniche, ottimizzazioni o estensioni del progetto, contattare il team AI di M.INC.  
+Questo file è pensato per essere modificabile e aggiornabile da qualsiasi sviluppatore.
+
+---
+
+## 📁 Versioni future
+
+- [ ] Integrazione LoRA per fine-tuning leggero  
+- [ ] Supporto FlashAttention  
+- [ ] Training multi-turno con contesto esteso  
+- [ ] Valutazione automatica su benchmark italiani