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:

.venv/bin/python ollama/check_env.py

---

Configurazione modello

Il modello di embedding viene letto da config.py:

# 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

# 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. 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.

# 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.