Gemma3-1B-CulturaViva-ITA/README.md

---
base_model: google/gemma-3-1b-it
library_name: transformers
language:
- it
tags:
- gemma
- gemma-3
- qlora
- lora
- italian
- culture
- fine-tuning
- gguf
- ollama
license: apache-2.0
datasets:
- DeepMount00/CulturaViva-ITA
---

# 🇮🇹 Gemma3-1B-CulturaViva-ITA

**Gemma3-1B-CulturaViva-ITA** è un modello linguistico basato sull'architettura **Gemma 3 (1B parametri)**, sottoposto a fine-tuning per specializzarsi nella comprensione e generazione di testi relativi alla **cultura, storia e tradizioni italiane**.

Questo modello è stato addestrato per rispondere in italiano in modo accurato e contestualizzato, superando le barriere linguistiche e culturali dei modelli base generalisti. **I pesi LoRA sono già stati uniti al modello base**, rendendolo un modello standalone pronto all'uso.

## 🛠️ Dettagli del Modello

- **Modello Base:** Gemma 3 (1B Instruct)
- **Lingua:** Italiano (`it`)
- **Metodo di Addestramento:** QLoRA (Quantized Low-Rank Adaptation) -> Merged
- **Versione GGUF (Quantizzata):** [nickprock/Gemma3-1B-CulturaViva-ITA-Q4_K_M-GGUF](https://huggingface.co/nickprock/Gemma3-1B-CulturaViva-ITA-Q4_K_M-GGUF)
- **Framework:** PyTorch, Hugging Face `transformers`, `peft`, `trl`
- **Autore:** [nickprock](https://huggingface.co/nickprock)

## 🎯 Uso Previsto (Intended Use)

Il modello è ideale per:
- Assistenti virtuali specializzati in turismo e cultura italiana.
- Generazione di contenuti (articoli, riassunti, guide) su storia, arte e tradizioni del Bel Paese.
- Q&A (Domande e Risposte) su contesti storici e culturali italiani.

---

## 🦙 Come usare il modello in locale con Ollama (GGUF)

Il metodo più veloce per provare il modello sul tuo PC, sfruttando la versione quantizzata a 4-bit (leggerissima ed efficiente), è utilizzare **Ollama**.

### Metodo 1: Avvio Rapido (Consigliato)
Apri il tuo terminale e lancia questo comando. Ollama scaricherà automaticamente il modello da Hugging Face e avvierà la chat:

```bash
ollama run hf.co/nickprock/Gemma3-1B-CulturaViva-ITA-Q4_K_M-GGUF

```

### Metodo 2: Configurazione Avanzata (Modelfile)

Se vuoi personalizzare il comportamento del modello (ad esempio, dandogli un ruolo specifico o cambiando la creatività), crea un file di testo chiamato `Modelfile` sul tuo PC e inserisci questo codice:

```dockerfile
# Usa direttamente il repository di Hugging Face!
FROM hf.co/nickprock/Gemma3-1B-CulturaViva-ITA-Q4_K_M-GGUF

# Imposta i parametri di generazione
PARAMETER temperature 0.7
PARAMETER num_ctx 4096

# Imposta un system prompt per dare contesto al modello
SYSTEM """Sei un assistente virtuale esperto di cultura, storia e tradizioni italiane. Rispondi alle domande in italiano in modo chiaro, accurato e appassionato."""

```

Apri il terminale nella stessa cartella del file e lancia:

```bash
# Crea il tuo assistente personalizzato
ollama create CulturaViva -f Modelfile

# Avvia la chat!
ollama run CulturaViva

```

---

## 🚀 Come usare il modello (Python / Hugging Face)

Per gli sviluppatori che desiderano integrare il modello base a 16-bit nei loro script Python:

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_id = "nickprock/Gemma3-1B-CulturaViva-ITA"

# 1. Carica Tokenizer e Modello
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.float16,
    device_map="auto"
)

# 2. Prepara il prompt utilizzando il chat template
messages = [
    {"role": "user", "content": "Parlami dell'importanza del Rinascimento italiano nell'arte."}
]
prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

# 3. Genera la risposta
outputs = model.generate(**inputs, max_new_tokens=300, temperature=0.7)

# 4. Decodifica e stampa solo la risposta generata
input_length = inputs["input_ids"].shape[1]
response = tokenizer.decode(outputs[0][input_length:], skip_special_tokens=True)
print(response)

```

---

## ⚙️ Dettagli del Training (Dietro le quinte)

Il processo di fine-tuning è stato un percorso di ottimizzazione intensivo, calibrato per estrarre le massime performance dall'hardware limitando il consumo di VRAM.

### Iperparametri e Configurazione (LoRA)

* **Metodo:** LoRA standard caricato in BFLOAT16 per massimizzare la velocità sulle architetture GPU di ultima generazione (Ada Lovelace / Blackwell), con successiva fusione dei pesi (`merge_and_unload`).
* **LoRA Rank (r):** 16
* **LoRA Alpha:** 16 *(Valore conservativo per garantire stabilità e non sovrascrivere eccessivamente i pesi base)*
* **Target Modules:** `all-linear`
* **LoRA Dropout:** 0.05
* **Task Type:** `CAUSAL_LM`
* **Precisione:** `bfloat16` nativo.
* **Ottimizzazione Memoria:** Batch size reale espanso tramite *Gradient Accumulation* (16 steps) mantenendo un *per_device_batch_size* di 1, combinato con *Gradient Checkpointing* per azzerare il VRAM thrashing e mantenere i consumi sotto gli 8 GB di VRAM dedicata.

### Risultati del Training

Il modello ha completato un'epoca intera elaborando oltre **26,4 milioni di token**. La curva di apprendimento si è rivelata estremamente sana, mostrando una totale assenza di Overfitting. La *Validation Loss* ha seguito in parallelo la *Training Loss* fino alla fine, confermando una straordinaria capacità di generalizzazione del modello sui dati non visti. L'accuratezza media sui token ha superato il 70%.

**Evoluzione delle Metriche (Campionamento sull'Epoca):**

| Progresso Epoca | Training Loss | Validation Loss | Token Accuracy |
| --- | --- | --- | --- |
| **~20%** | 1.155 | 1.178 | 69.8% |
| **~40%** | 1.147 | 1.146 | 70.3% |
| **~60%** | 1.136 | 1.132 | 70.5% |
| **~80%** | 1.108 | 1.124 | 70.7% |
| **~100%** | 1.142 | 1.120 | 70.7% |

**Performance di Sistema:**

* **Training Loss Globale Finale:** 1.156
* **Token elaborati:** ~26.47 Milioni
* **Accuratezza Media Token (Training):** 70.09%
* **Tempo di Addestramento (Runtime):** 34.670 secondi (~9 ore e 38 minuti)
* **Velocità:** 1.492 sample/sec