rag-from-scratch/step-7/README.md

# Step 7 — Verifica ambiente

Prima di procedere con la vettorizzazione (step 8) devi avere installato:

- **Ollama** — server locale per LLM e embedding
- un **modello di embedding** (es. `nomic-embed-text`, `bge-m3`)
- un **modello LLM** (es. `qwen3.5:4b`, `qwen3:4b`)
- **chromadb** — libreria Python per il vector store

---

## 1. Installa Ollama

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

Verifica che il servizio sia attivo:

```bash
ollama list
```

### Disinstalla Ollama

```bash
# Ferma e rimuovi il servizio systemd
sudo systemctl stop ollama
sudo systemctl disable ollama
sudo rm /etc/systemd/system/ollama.service
sudo systemctl daemon-reload

# Rimuovi il binario
sudo rm /usr/local/bin/ollama

# Rimuovi modelli e dati (opzionale — occupa spazio su disco)
# I modelli sono salvati sotto l'utente di sistema "ollama", non nella tua home
sudo rm -rf /usr/share/ollama

# Rimuovi l'utente e il gruppo di sistema creati dall'installer (opzionale)
sudo userdel ollama
sudo groupdel ollama
```

---

## 2. Scarica i modelli

### Modello di embedding

Per testi in italiano serve un modello multilingue — i modelli English-first producono embeddings di qualità inferiore su lingue diverse dall'inglese, con retrieval meno preciso.

Prima scelta consigliata:

```bash
ollama pull qwen3-embedding:0.6b
```

Stessa famiglia del LLM in uso (`qwen3.5`), multilingue, recente, gira comodamente in CPU.

| Modello | Dim | Dimensione | Lingue | Consigliato |
|---|---|---|---|---|
| `qwen3-embedding:0.6b` | 1024 | ~522 MB | multilingue | ✅ prima scelta |
| `nomic-embed-text-v2-moe` | 768 | ~523 MB | multilingue | ✅ seconda scelta |
| `bge-m3` | 1024 | ~1.2 GB | 100+ lingue incl. IT | ✅ terza scelta |
| `nomic-embed-text` | 768 | ~274 MB | principalmente EN | ⚠️ default corrente |
| `mxbai-embed-large` | 1024 | ~670 MB | principalmente EN | ❌ |
| `paraphrase-multilingual` | 768 | ~278 MB | multilingue | ❌ obsoleto |
| `all-minilm` | 384 | ~46 MB | principalmente EN | ❌ troppo piccolo |

Se cambi modello rispetto a quello usato in step-8, devi rieseguire la vettorizzazione con `--force` e aggiornare `EMBED_MODEL` in `step-9/config.py`.

### Modello LLM

Per RAG su testi italiani servono: buon instruction following, supporto multilingue e context window ampia (i prompt RAG includono più chunk).

Prima scelta consigliata per 8 GB RAM:

```bash
ollama pull qwen3.5:4b
```

Il progetto è pensato per la famiglia **Qwen3.5** — stessa famiglia dell'embedding consigliato (`qwen3-embedding`), context window 256K, ottimo italiano. Altri modelli sono compatibili ma non testati.

| Modello | RAM | Note |
|---|---|---|
| `qwen3.5:0.8b` | ≥ 1 GB | minimo assoluto |
| `qwen3.5:2b` | ≥ 3 GB | leggero |
| `qwen3.5:4b` | ≥ 5 GB | **consigliato per 8 GB** |
| `qwen3.5:9b` | ≥ 8 GB | lento su CPU, meglio con GPU |

Se usi un modello diverso da `qwen3.5:4b`, aggiorna `OLLAMA_MODEL` in `step-9/config.py`.

### Disinstalla un modello

```bash
ollama rm qwen3.5:4b
ollama rm nomic-embed-text
```

Per vedere tutti i modelli installati:

```bash
ollama list
```

---

## 3. Installa le dipendenze nel venv

Assicurati di avere `chromadb` installato nel `.venv`:

```bash
source .venv/bin/activate
pip install -r requirements.txt
```

---

## 4. Verifica tutto

```bash
source .venv/bin/activate
python step-7/check_env.py
```

Output atteso se tutto è a posto:

```
✅ ollama trovato nel PATH
✅ ollama risponde correttamente
✅ modello embedding trovato: nomic-embed-text:latest
✅ modello LLM trovato: qwen3.5:4b

✅ chromadb importabile

✅ Ambiente pronto — procedi con la vettorizzazione:
   python step-8/ingest.py --stem <nome>
```

---

## Prossimo step

```bash
python step-8/ingest.py --stem <nome>
```