davide
12effa1a51
- step-9/: config.py, rag.py, retrieve.py → root; test_ollama.py → ollama/ - step-7/: eliminata, già coperta da ollama/ - sys.path aggiornati in rag.py, retrieve.py, ingest.py, check_env.py (step-7 e ollama) - Riferimenti step-9/config.py → config.py in tutti i file
115 lines
3.4 KiB
Markdown
115 lines
3.4 KiB
Markdown
# 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
|
|
- `chromadb` installato (`pip install -r requirements.txt`)
|
|
|
|
---
|
|
|
|
## 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 step-8 con `--force`.
|
|
|
|
---
|
|
|
|
## Uso
|
|
|
|
```bash
|
|
# 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 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
|
|
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.
|