Chunky è un toolkit open-source per costruire pipeline di ingestione RAG affidabili, focalizzato sulla stage di chunking spesso trascurata. Converte PDF a Markdown, pulisce documenti, ti consente di ispezionare i chunk e confrontare le strategie di chunking fianco a fianco, e arricchisce i metadati dei chunk per le applicazioni LLM. Poiché la qualità del retrieval è limitata da come i documenti vengono divisi, il valore di Chunky è rendere lo stage di chunking visibile e sintonizzabile invece di un default cieco.
Installazione
| Metodo | Comando |
|---|
| pip | pip install chunky |
| uv | uv add chunky |
| Da source | git clone https://github.com/GiovanniPasq/chunky && cd chunky && pip install -e . |
| Verifica | python -c "import chunky; print('ok')" |
Stage Pipeline
| Stage | Scopo |
|---|
| Convert | Trasforma PDF/doc in Markdown pulito |
| Clean | Rimuovi boilerplate, ripara artefatti |
| Chunk | Dividi testo usando una strategia scelta |
| Inspect | Visualizza i chunk risultanti |
| Compare | Esegui multiple strategie e confronta |
| Enrich | Allega metadati (intestazioni, sorgente, posizione) |
Convert & Clean
import chunky
# Converti un PDF a Markdown pulito
md = chunky.to_markdown("report.pdf")
# Pulisci artefatti comuni (intestazioni/footer, sillabazione, rumore)
md = chunky.clean(md)
| Funzione | Descrizione |
|---|
to_markdown(path) | Converti un documento a Markdown |
clean(text) | Elimina boilerplate e normalizza |
Strategie di Chunking
| Strategia | Divide su |
|---|
| Fixed-size | N token/caratteri con overlap |
| Recursive | Paragrafi → frasi → parole come necessario |
| Markdown / header-aware | Struttura documento (#, ##, sezioni) |
| Semantic | Limiti di somiglianza dell”embedding |
| Token-aware refinement | Merge undersized, dividi oversized chunk |
chunks = chunky.chunk(
md,
strategy="header_aware",
max_tokens=512,
overlap=64,
repeat_headers=True, # trasporta intestazioni di sezione attraverso split di tabella
)
for c in chunks:
print(len(c.tokens), c.metadata["heading"])
Inspect & Compare
Il differenziatore: vedi e confronta cosa ogni strategia produce prima di committere.
# Ispeziona i limiti dei chunk e le dimensioni
chunky.inspect(chunks) # dimensioni, overlap, limiti
# Confronta strategie sullo stesso documento
report = chunky.compare(
md,
strategies=["fixed", "recursive", "header_aware", "semantic"],
max_tokens=512,
)
print(report) # statistiche per-strategia: conteggio, distribuzione dimensioni, frammentazione
| Funzione | Mostra |
|---|
inspect(chunks) | Distribuzione dimensioni, overlap, limiti |
compare(text, strategies=[...]) | Metriche di strategie fianco a fianco |
| Metadato | Uso in retrieval |
|---|
| Heading path | Espansione contesto / filtraggio |
| Source + page | Citazioni |
| Position/index | Ordinamento e ricerca vicino |
| Token count | Budget management al prompt time |
enriched = chunky.enrich(chunks, source="report.pdf")
# ora ogni chunk.metadata trasporta heading path, page, source, index
Flussi di Lavoro Comuni
# End-to-end: PDF → Markdown pulito → chunk header-aware → arricchito
import chunky
md = chunky.clean(chunky.to_markdown("manual.pdf"))
chunks = chunky.chunk(md, strategy="header_aware", max_tokens=512, overlap=64)
chunks = chunky.enrich(chunks, source="manual.pdf")
# embed chunk.text, archivia chunk.metadata insieme nel tuo vector DB
# Scegli una strategia con evidenza, non col caso
print(chunky.compare(md, strategies=["recursive", "header_aware", "semantic"]))
Chunky vs Altri Approcci
| Aspetto | Chunky | Framework default splitters | Docling |
|---|
| Confronto Strategia | First-class | Manuale | Limitato |
| Conversion + clean | Built-in | Separato | Built-in |
| Migliore per | Sintonizzare lo stage di chunking | Quick start | Parse + chunk completo |
Funziona bene con Docling per il parsing e il tuo vector DB per l”archiviazione — il lavoro di Chunky è ottenere la divisione giusta.
Risorse
