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

docs(readme): flusso completo conversione → chunking

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Davide Grilli
2026-05-11 15:46:52 +02:00
parent e264bc52b1
commit efb02fa955
1 changed files with 103 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+103 -34
View File
@@ -1,9 +1,11 @@
# PDF → Markdown # PDF → Chunk RAG-ready
Converte PDF digitali in Markdown strutturato e pulito. Converte PDF digitali in chunk semantici pronti per la vettorizzazione RAG,
senza LLM né OCR.
**Stack:** Python · opendataloader-pdf (XY-Cut++) · Java 11+ **Pipeline:** PDF → Markdown strutturato → chunk semantici
**Compatibile con:** Linux · macOS · Windows (WSL2) **Stack:** Python · PyMuPDF · pdfplumber
**Non supportati:** PDF scansionati (solo immagini), PDF protetti da password.
--- ---
@@ -15,54 +17,121 @@ source .venv/bin/activate
pip install -r requirements.txt pip install -r requirements.txt
``` ```
**Java 11+** richiesto:
```bash
sudo apt install default-jdk # Ubuntu/Debian/WSL
java -version
```
--- ---
## Utilizzo ## Flusso completo
### 1. Posiziona il PDF
```
sources/<nome>.pdf
```
### 2. Converti il PDF in Markdown
```bash ```bash
# Singolo PDF # Singolo documento
python conversione/pipeline.py --stem <nome> .venv/bin/python conversione/ --stem <nome>
# Tutti i PDF in sources/ # Tutti i PDF in sources/
python conversione/pipeline.py .venv/bin/python conversione/
# Forza riesecuzione # Forza riesecuzione (sovrascrive output esistente)
python conversione/pipeline.py --stem <nome> --force .venv/bin/python conversione/ --stem <nome> --force
``` ```
`--stem` = nome file PDF senza estensione. Output in `conversione/<nome>/`:
Esempio: `sources/analisi1.pdf` → `--stem analisi1`
---
## Output
Per ogni stem in `conversione/<stem>/`:
| File | Descrizione | | File | Descrizione |
|------|-------------| |------|-------------|
| `raw.md` | Markdown grezzo — **non modificare** | | `raw.md` | Markdown grezzo — **non modificare** |
| `clean.md` | Markdown pulito — copia di lavoro | | `clean.md` | Markdown pulito — input per il chunker |
| `structure_profile.json` | Struttura rilevata e metriche | | `structure_profile.json` | Struttura rilevata e strategia di chunking |
| `report.json` | Statistiche complete della conversione | | `report.json` | Metriche di qualità della conversione |
--- ### 3. Verifica la qualità del Markdown (opzionale)
## Validazione batch
```bash ```bash
python conversione/validate.py .venv/bin/python conversione/ validate <nome> --detail
``` ```
Stampa una tabella di stato su tutti gli stem convertiti. Se lo score è ≥ 80 e `valid=true`, procedi. Altrimenti usa `/prepare-md` per
correzioni manuali (sillabazione residua, header malformati, ecc.).
### 4. Genera i chunk
```bash
.venv/bin/python chunks/chunker.py --stem <nome>
# Forza riesecuzione
.venv/bin/python chunks/chunker.py --stem <nome> --force
```
La strategia di chunking (`h3_aware`, `h2_paragraph_split`, `paragraph`,
`sliding_window`) viene scelta automaticamente da `structure_profile.json`.
Output in `chunks/<nome>/`:
| File | Descrizione |
|------|-------------|
| `chunks.json` | Lista di chunk con testo, sezione, titolo e metadati |
| `report.json` | Statistiche e anomalie del chunking |
### 5. Verifica i chunk
```bash
.venv/bin/python chunks/verify_chunks.py --stem <nome>
```
Verdict possibili:
| Verdict | Significato | Cosa fare |
|---------|-------------|-----------|
| `ok` | Nessun problema | Procedi alla vettorizzazione |
| `warnings_only` | Solo avvisi minori | Puoi procedere o eseguire il fix |
| `blocked` | Problemi bloccanti (chunk incompleti) | Esegui il fix |
### 6. Correggi i problemi (se necessario)
```bash
# Anteprima delle correzioni senza applicarle
.venv/bin/python chunks/fix_chunks.py --stem <nome> --dry-run
# Applica le correzioni (ricorsivo, fino a 3 iterazioni)
.venv/bin/python chunks/fix_chunks.py --stem <nome>
```
Il fix gestisce automaticamente: chunk incompleti (frase spezzata), chunk
troppo corti (accorpa al successivo), chunk eccessivamente lunghi (spezza
su punteggiatura). Ogni chunk termina sempre su un confine di frase.
--- ---
Vedi [`conversione/README.md`](conversione/README.md) per dettagli sulla pipeline e i tipi di documento supportati. ## Configurazione del chunking
Tutti i parametri sono in [`chunks/config.py`](chunks/config.py):
```python
TARGET_CHARS = 600 # dimensione target dei chunk
CHUNK_TOLERANCE = 0.25 # ±25% → range accettabile [450, 750]
OVERLAP_SENTENCES = 1 # frasi di overlap tra chunk consecutivi
PROTECT_TABLES = True # tabelle emesse come chunk atomici
FIX_MAX_ITERATIONS = 3 # iterazioni massime del fix ricorsivo
```
Per ogni strategia è possibile definire valori diversi tramite `STRATEGY_OVERRIDES`.
Modificare solo questo file — chunker, verify e fix si aggiornano automaticamente.
---
## Test
```bash
.venv/bin/python -m pytest tests/
```
---
## Riferimenti
- [`conversione/README.md`](conversione/README.md) — dettagli sulla pipeline PDF→Markdown e sui tipi di documento supportati