davide
1a0ebafda5
fix(step-9): passa SYSTEM_PROMPT come campo system nell'API Ollama anziche concatenato nel prompt — risolve risposte di fallback errate con modelli piccoli
Step 8 — Vettorizzazione
Legge i chunk prodotti da step-6, genera gli embedding tramite Ollama e li salva in ChromaDB (vector store persistente su disco).
Prerequisiti
- Step-6 completato (esiste
step-6/<stem>/chunks.json) - Ollama attivo con il modello di embedding scaricato
chromadbinstallato (pip install -r requirements.txt)
Configurazione modello
Il modello di embedding viene letto da step-9/config.py:
# step-9/config.py
EMBED_MODEL = "nomic-embed-text" # ← cambia qui
Il modello scelto qui deve corrispondere a quello usato in step-9. Se lo cambi dopo aver già vettorizzato, devi rieseguire step-8 con
--force.
Uso
# Vettorizza un singolo documento
python step-8/ingest.py --stem <nome>
# Vettorizza tutti i documenti trovati in step-6/
python step-8/ingest.py
# Sovrascrive una collection già esistente
python step-8/ingest.py --stem <nome> --force
# Override modello (senza modificare config.py)
python step-8/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 step-7.
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 step-8 e step-9
EMBED_MODEL deve essere identico in step-8 e step-9.
ChromaDB memorizza i vettori generati con un certo modello. Se step-9 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 step-9.
# Cambio modello → ricrea sempre la collection
python step-8/ingest.py --stem <nome> --force
Quando usare --force
| Situazione | --force necessario? |
|---|---|
| Prima esecuzione | No |
Hai cambiato EMBED_MODEL |
Sì |
| Hai migliorato i chunk in step-6 | 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.