rag-from-scratch/ingestion/README.md

# Ingestion — Vettorizzazione

Legge i chunk prodotti dal chunker, genera gli embedding tramite Ollama e li
salva in ChromaDB (vector store persistente su disco).

---

## Prerequisiti

- Chunking completato (esiste `chunks/<stem>/chunks.json`)
- Ollama attivo con il modello di embedding scaricato
- `chromadb` installato (`pip install -r requirements.txt`)

---

## Verifica ambiente

Prima di eseguire l'ingestion, verifica che Ollama e i modelli siano disponibili:

```bash
.venv/bin/python ollama/check_env.py
```

---

## Configurazione modello

Il modello di embedding viene letto da **`config.py`**:

```python
# config.py
EMBED_MODEL = "nomic-embed-text"   # ← cambia qui
```

> Il modello scelto qui deve corrispondere a quello usato in rag.py.
> Se lo cambi dopo aver già vettorizzato, devi rieseguire ingestion con `--force`.

---

## Uso

```bash
# Vettorizza un singolo documento
.venv/bin/python ingestion/ingest.py --stem <nome>

# Vettorizza tutti i documenti trovati in step-6/
.venv/bin/python ingestion/ingest.py

# Sovrascrive una collection già esistente
.venv/bin/python ingestion/ingest.py --stem <nome> --force

# Override modello (senza modificare config.py)
.venv/bin/python ingestion/ingest.py --stem <nome> --model bge-m3
```

---

## Output

I vettori vengono salvati in `chroma_db/<stem>/` come collection ChromaDB con
distanza coseno. La directory è ignorata da git (generata automaticamente).

---

## Modelli supportati

Stessi modelli raccomandati nel [README di ollama](../ollama/README.md).
Il modello deve essere scaricato in Ollama prima di eseguire questo script
(`ollama pull <modello>`).

---

## Regole d'oro per parametri ottimali

### Modello di embedding

**Usa un modello multilingue per testi italiani.**
I modelli English-first (`nomic-embed-text`, `mxbai-embed-large`, `all-minilm`)
producono vettori di qualità inferiore su italiano, con retrieval meno preciso.
Prima scelta: `qwen3-embedding:0.6b`.

**Più dimensioni = retrieval più preciso, ma più spazio su disco.**

| Dimensioni | Modelli | Quando usarlo |
|---|---|---|
| 1024 | `qwen3-embedding:0.6b`, `bge-m3` | documenti tecnici, testi lunghi |
| 768 | `nomic-embed-text-v2-moe` | buon compromesso |
| 384 | `all-minilm` | solo per test rapidi |

**Usa la stessa famiglia LLM + embedding quando possibile.**
`qwen3-embedding` + `qwen3.5` condividono tokenizer e spazio semantico —
il retrieval è più coerente rispetto a modelli di famiglie diverse.

### Coerenza tra ingest e retrieval

**`EMBED_MODEL` deve essere identico in `ingest.py` e `rag.py`.**
ChromaDB memorizza i vettori generati con un certo modello. Se `rag.py` usa un
modello diverso per la query di ricerca, gli spazi vettoriali non corrispondono
e il retrieval restituisce risultati casuali — senza alcun errore visibile.

**Dopo aver cambiato `EMBED_MODEL`, riesegui sempre con `--force`.**
Senza `--force` lo script salta la collection già esistente — i vecchi vettori
(generati col modello precedente) restano e continuano a essere usati da `rag.py`.

```bash
# Cambio modello → ricrea sempre la collection
.venv/bin/python ingestion/ingest.py --stem <nome> --force
```

### Quando usare `--force`

| Situazione | `--force` necessario? |
|---|---|
| Prima esecuzione | No |
| Hai cambiato `EMBED_MODEL` | **Sì** |
| Hai migliorato i chunk in chunks/ | **Sì** |
| Hai aggiunto nuovi documenti (stem diverso) | No |
| Vuoi solo verificare che funzioni | No |

### Distanza vettoriale

Lo script usa **distanza coseno** (hardcoded), che è la scelta corretta per
embedding testuali — misura l'angolo tra vettori indipendentemente dalla loro
lunghezza. Non cambiare questo parametro.