davide/rag-from-scratch
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: allinea README alla struttura reale del progetto

Browse Source 
Corregge struttura progetto (step-N/ invece di scripts/ e processed/),
aggiorna script, comandi e path per step 1–3, rimuove riferimenti a
marker-pdf (sostituito da pymupdf4llm), snellisce step 7 e 9 con
rimando ai README dedicati, segna step 10 come da implementare
This commit is contained in:
Davide Grilli
2026-04-14 15:57:49 +02:00
parent f27ebfa101
commit 8fa07784ae
1 changed files with 80 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+80 -111
View File
@@ -3,7 +3,7 @@
Sistema RAG (Retrieval-Augmented Generation) costruito da zero, senza framework di alto livello. Sistema RAG (Retrieval-Augmented Generation) costruito da zero, senza framework di alto livello.
Funziona su qualsiasi PDF digitale. Gira interamente in locale, senza GPU, senza cloud. Funziona su qualsiasi PDF digitale. Gira interamente in locale, senza GPU, senza cloud.
**Stack:** Python · Ollama · nomic-embed-text · Qwen3 8B · ChromaDB **Stack:** Python · Ollama · nomic-embed-text · Qwen3.5 · ChromaDB
**Compatibile con:** Linux · macOS · Windows (WSL2) · CPU Only · ~8 GB RAM libera **Compatibile con:** Linux · macOS · Windows (WSL2) · CPU Only · ~8 GB RAM libera
--- ---
@@ -72,25 +72,54 @@ rag-from-scratch/
├── sources/ # PDF originali — non modificare mai ├── sources/ # PDF originali — non modificare mai
│ └── documento.pdf │ └── documento.pdf
│ │
├── processed/ # Output di ogni step per ogni documento ├── step-0/
│ └── documento/ │ └── check_pdf.py # Verifica requisiti del PDF
│ ├── raw.md # MD grezzo da marker (non toccare) │
│ ├── clean.md # MD revisionato a mano ├── step-1/
│ ├── structure_profile.json # Profilo struttura da step 3 │ └── inspect_pdf.py # Ispezione automatica del PDF
│
├── step-2/
│ ├── convert_pdf.py # Conversione PDF → Markdown grezzo
│ └── <stem>/
│ └── raw.md # MD grezzo (non toccare)
│
├── step-3/
│ ├── detect_structure.py # Rilevamento struttura MD
│ └── <stem>/
│ └── structure_profile.json # Profilo struttura
│
├── step-4/
│ ├── revise.py # Pre-processing automatico MD
│ ├── revision_log.md # Log modifiche manuali
│ └── <stem>/
│ ├── clean.md # MD revisionato
│ └── structure_profile.json # Profilo aggiornato
│
├── step-5/
│ ├── chunker.py # Chunking adattivo
│ └── <stem>/
│ └── chunks.json # Chunk pronti per la vettorizzazione │ └── chunks.json # Chunk pronti per la vettorizzazione
│ │
├── scripts/ ├── step-6/
│ ├── inspect.py # Step 1 — ispezione PDF │ ├── verify_chunks.py # Verifica chunk
│ ├── detect_structure.py # Step 3 — analisi struttura MD │ ├── fix_chunks.py # Fix chunk problematici
│ ├── chunker.py # Step 5 — chunking adattivo │ └── <stem>/
│ ├── verify_chunks.py # Step 6 — verifica chunk │ └── chunks.json # Chunk verificati
│ ├── ingest.py # Step 8 — vettorizzazione
│ ├── rag.py # Step 9 — pipeline RAG
│ └── test_pipeline.py # Step 10 — test automatici
│ │
├── chroma_db/ # Vector store — generato da ingest.py ├── step-7/
├── notes/ │ ├── check_env.py # Verifica ambiente locale
│ └── revision_log.md # Log delle modifiche manuali al MD │ └── README.md # Guida installazione Ollama e dipendenze
│
├── step-8/
│ └── ingest.py # Vettorizzazione → ChromaDB
│
├── step-9/
│ ├── config.py # Configurazione pipeline RAG ← modifica qui
│ ├── rag.py # Pipeline RAG interattiva
│ ├── test_ollama.py # Test chat Ollama senza RAG
│ └── README.md
│
├── chroma_db/ # Vector store — generato da step-8
├── requirements.txt ├── requirements.txt
├── .gitignore ├── .gitignore
└── README.md └── README.md
@@ -136,15 +165,15 @@ Se ottieni caratteri strani o testo nell'ordine sbagliato, il PDF ha problemi.
### Step 1 — Ispezione automatica ### Step 1 — Ispezione automatica
**Tipo:** automatico **Tipo:** automatico
**Input:** `sources/documento.pdf` **Input:** tutti i PDF in `sources/`
**Output:** report testuale con score e lista problemi **Output:** `step-1/<stem>_step1_report.txt`
**Script:** `scripts/inspect.py` **Script:** `step-1/inspect_pdf.py`
```bash ```bash
python scripts/inspect.py sources/documento.pdf --save python step-1/inspect_pdf.py
``` ```
Lo script analizza il PDF pagina per pagina e produce un report. Lo script scansiona automaticamente tutti i PDF in `sources/`, analizza ogni documento pagina per pagina e produce un report.
Serve per capire la qualità del documento e mappare i problemi Serve per capire la qualità del documento e mappare i problemi
prima di affrontare la revisione manuale. prima di affrontare la revisione manuale.
@@ -186,33 +215,29 @@ PROSSIMI PASSI:
### Step 2 — Conversione in Markdown grezzo ### Step 2 — Conversione in Markdown grezzo
**Tipo:** automatico **Tipo:** automatico
**Input:** `sources/documento.pdf` **Input:** tutti i PDF in `sources/` (o uno solo con `--pdf`)
**Output:** `processed/documento/raw.md` **Output:** `step-2/<stem>/raw.md` + `step-2/<stem>/clean.md`
**Tool:** marker-pdf **Script:** `step-2/convert_pdf.py`
```bash ```bash
marker_single sources/documento.pdf processed/documento/raw.md python step-2/convert_pdf.py # tutti i PDF in sources/
python step-2/convert_pdf.py --pdf sources/doc.pdf # un solo PDF
``` ```
Converte il PDF in Markdown. Il risultato non è perfetto — è la base Converte il PDF in Markdown usando `pymupdf4llm`. Il risultato non è perfetto — è la base
su cui lavorerai nello step 4. su cui lavorerai nello step 4.
**Regola fondamentale:** `raw.md` non va mai modificato. Lo script crea due file:
È il punto di partenza di riferimento. Se qualcosa va storto - `raw.md` — conversione grezza, **non modificare mai**. È il punto di partenza di riferimento.
nella revisione, puoi sempre ripartire da qui. - `clean.md` — copia di lavoro che verrà modificata negli step successivi.
```bash **Cosa produce la conversione:**
# Crea subito la copia su cui lavorare
cp processed/documento/raw.md processed/documento/clean.md
```
**Cosa produce marker:**
- Titoli riconosciuti e convertiti in `#` `##` `###` - Titoli riconosciuti e convertiti in `#` `##` `###`
- Paragrafi separati da righe vuote - Paragrafi separati da righe vuote
- Sillabazione parzialmente risolta - Sillabazione parzialmente risolta
**Cosa non produce marker:** **Cosa non produce:**
- Rimozione intestazioni e piè di pagina - Rimozione intestazioni e piè di pagina
- Correzione completa del layout a colonne - Correzione completa del layout a colonne
@@ -223,15 +248,17 @@ cp processed/documento/raw.md processed/documento/clean.md
### Step 3 — Rilevamento struttura ### Step 3 — Rilevamento struttura
**Tipo:** automatico **Tipo:** automatico
**Input:** `processed/documento/raw.md` **Input:** `step-2/<stem>/`
**Output:** `processed/documento/structure_profile.json` **Output:** `step-3/<stem>/structure_profile.json`
**Script:** `scripts/detect_structure.py` **Script:** `step-3/detect_structure.py`
```bash ```bash
python scripts/detect_structure.py processed/documento/raw.md python step-3/detect_structure.py # tutti i documenti in step-2/
python step-3/detect_structure.py --stem <nome> # un solo documento
python step-3/detect_structure.py --force # riesegui anche se già presente
``` ```
Analizza la struttura del Markdown grezzo senza modificarlo. Copia `raw.md` e `clean.md` da `step-2/<stem>/` e analizza la struttura del Markdown senza modificarla.
Il profilo prodotto guida sia la revisione manuale che il chunker. Il profilo prodotto guida sia la revisione manuale che il chunker.
**I quattro livelli strutturali:** **I quattro livelli strutturali:**
@@ -472,35 +499,14 @@ Distribuzione lunghezze:
**Output:** ambiente locale funzionante **Output:** ambiente locale funzionante
**Script:** `step-7/check_env.py` **Script:** `step-7/check_env.py`
Installa Ollama, scarica i modelli e verifica l'ambiente. Si esegue una volta sola.
Vedi [`step-7/README.md`](step-7/README.md) per istruzioni dettagliate e scelta dei modelli.
```bash ```bash
# Installa Ollama
curl -fsSL https://ollama.com/install.sh | sh
# Scarica un modello di embedding e un LLM
ollama pull nomic-embed-text # Embedding — ~274 MB (consigliato)
ollama pull qwen3.5:4b # LLM — ~3.4 GB (consigliato per 8 GB RAM)
# Installa dipendenze Python nel venv
source .venv/bin/activate
pip install -r requirements.txt
# Verifica tutto
python step-7/check_env.py python step-7/check_env.py
``` ```
**Modelli consigliati per 8 GB RAM:**
| Modello | Ruolo | Dimensione |
|---|---|---|
| `nomic-embed-text` | Embedding | ~274 MB |
| `qwen3.5:4b` | LLM | ~3.4 GB |
Per guide dettagliate su modelli alternativi, installazione e disinstallazione
di Ollama e ChromaDB, vedi [`step-7/README.md`](step-7/README.md).
Questo step si esegue una volta sola. Da questo momento
Ollama è sempre disponibile sul sistema.
--- ---
### Step 8 — Vettorizzazione ### Step 8 — Vettorizzazione
@@ -575,53 +581,16 @@ Non è necessario ripetere questo step a meno che il documento cambi.
**Tipo:** interattivo **Tipo:** interattivo
**Input:** `chroma_db/` + domanda dell'utente **Input:** `chroma_db/` + domanda dell'utente
**Output:** risposta basata sul documento **Output:** risposta basata sul documento
**Script:** `scripts/rag.py` **Script:** `step-9/rag.py`
```bash ```bash
python scripts/rag.py source .venv/bin/activate
python step-9/rag.py --stem <nome>
``` ```
Mette insieme retrieval e generation in un loop interattivo. Loop interattivo che risponde a domande sul documento. Configura i parametri in `step-9/config.py` prima di avviare.
**Flusso per ogni domanda:** Vedi [`step-9/README.md`](step-9/README.md) per la configurazione completa.
```
La tua domanda in testo
│
▼ embedding della domanda (nomic-embed-text)
vettore 768 dimensioni
│
▼ ricerca per similarità coseno in ChromaDB
top 3 chunk semanticamente più vicini
│
▼ costruzione del prompt
"Rispondi SOLO dal contesto:
[chunk 1]
[chunk 2]
[chunk 3]
Domanda: ..."
│
▼ Ollama (Qwen3 8B)
risposta generata
```
**Come si usa:**
```
Domanda: La tua domanda qui
Domanda: La tua domanda qui -v ← aggiunge i chunk recuperati
Domanda: exit
```
**La similarità coseno:**
Misura l'angolo tra due vettori — non la distanza ma l'orientamento.
Due testi semanticamente simili puntano nella stessa direzione
nello spazio a 768 dimensioni, indipendentemente dalla loro lunghezza.
**Regola del prompt:**
Il LLM risponde SOLO dal contesto fornito.
Se la risposta non è nel documento lo dice esplicitamente.
Non inventa, non integra con conoscenza esterna.
--- ---
@@ -630,10 +599,10 @@ Non inventa, non integra con conoscenza esterna.
**Tipo:** automatico **Tipo:** automatico
**Input:** sistema completo **Input:** sistema completo
**Output:** tutti i test verdi **Output:** tutti i test verdi
**Script:** `scripts/test_pipeline.py` **Script:** `step-10/test_pipeline.py` *(da implementare)*
```bash ```bash
python scripts/test_pipeline.py python step-10/test_pipeline.py --stem <nome>
``` ```
Verifica ogni componente in isolamento e poi nel sistema completo. Verifica ogni componente in isolamento e poi nel sistema completo.