PDF → Chunk RAG-ready
Converte PDF digitali in chunk semantici pronti per la vettorizzazione RAG, senza LLM né OCR.
Pipeline: PDF → Markdown strutturato → chunk semantici
Stack: Python · PyMuPDF · pdfplumber
Non supportati: PDF scansionati (solo immagini), PDF protetti da password.
Setup
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Flusso completo
1. Posiziona il PDF
sources/<nome>.pdf
2. Converti il PDF in Markdown
# Singolo documento
.venv/bin/python conversione/ --stem <nome>
# Tutti i PDF in sources/
.venv/bin/python conversione/
# Forza riesecuzione (sovrascrive output esistente)
.venv/bin/python conversione/ --stem <nome> --force
Output in conversione/<nome>/:
| File | Descrizione |
|---|---|
raw.md |
Markdown grezzo — non modificare |
clean.md |
Markdown pulito — input per il chunker |
structure_profile.json |
Struttura rilevata e strategia di chunking |
report.json |
Metriche di qualità della conversione |
3. Verifica la qualità del Markdown (opzionale)
.venv/bin/python conversione/ validate <nome> --detail
Se lo score è ≥ 80 e valid=true, procedi. Altrimenti usa /prepare-md per
correzioni manuali (sillabazione residua, header malformati, ecc.).
4. Genera i chunk
.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
.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)
# 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.
Configurazione del chunking
Tutti i parametri sono in chunks/config.py:
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
.venv/bin/python -m pytest tests/
Riferimenti
conversione/README.md— dettagli sulla pipeline PDF→Markdown e sui tipi di documento supportati