Chunky ist ein Open-Source-Toolkit zum Erstellen zuverlässiger RAG-Ingestionspipelines, konzentriert auf die oft vernachlässigte Chunking-Phase. Es konvertiert PDFs zu Markdown, ermöglicht es dir, Chunks zu inspizieren und Chunking-Strategien nebeneinander zu vergleichen, und bereichert Chunk-Metadaten für LLM-Anwendungen. Da die Abrufqualität durch die Aufteilung von Dokumenten begrenzt ist, besteht der Wert von Chunky darin, den Chunking-Schritt sichtbar und abstimmbar zu machen, anstatt ihn als blindes Standard-Verfahren zu behandeln.
Installation
| Methode | Befehl |
|---|
| pip | pip install chunky |
| uv | uv add chunky |
| Aus Quelle | git clone https://github.com/GiovanniPasq/chunky && cd chunky && pip install -e . |
| Überprüfung | python -c "import chunky; print('ok')" |
Pipeline-Stufen
| Stufe | Zweck |
|---|
| Convert | PDFs/Dokumente in sauberes Markdown umwandeln |
| Clean | Boilerplate entfernen, Artefakte beheben |
| Chunk | Text mit gewählter Strategie aufteilen |
| Inspect | Resultierende Chunks visualisieren |
| Compare | Mehrere Strategien ausführen und vergleichen |
| Enrich | Metadaten anfügen (Überschriften, Quelle, Position) |
Konvertieren und Bereinigen
import chunky
# PDF in sauberes Markdown konvertieren
md = chunky.to_markdown("report.pdf")
# Häufige Artefakte bereinigen (Kopfzeilen/Fußzeilen, Silbentrennung, Rauschen)
md = chunky.clean(md)
| Funktion | Beschreibung |
|---|
to_markdown(path) | Dokument in Markdown konvertieren |
clean(text) | Boilerplate entfernen und normalisieren |
Chunking-Strategien
| Strategie | Teilt auf |
|---|
| Fixed-size | N Token/Zeichen mit Überlappung |
| Recursive | Absätze → Sätze → Wörter bei Bedarf |
| Markdown / Header-Aware | Dokumentstruktur (#, ##, Abschnitte) |
| Semantic | Embedding-Ähnlichkeitsgrenzen |
| Token-Aware Refinement | Untergeordnete zusammenführen, übergroße aufteilen |
chunks = chunky.chunk(
md,
strategy="header_aware",
max_tokens=512,
overlap=64,
repeat_headers=True, # Abschnittskopfzeilen über Tabellensplits tragen
)
for c in chunks:
print(len(c.tokens), c.metadata["heading"])
Inspizieren und Vergleichen
Der Unterschied: Sehe und vergleiche, was jede Strategie produziert, bevor du dich festlegst.
# Chunk-Grenzen und Größen inspizieren
chunky.inspect(chunks) # Größen, Überlappungen, Grenzen
# Strategien am selben Dokument vergleichen
report = chunky.compare(
md,
strategies=["fixed", "recursive", "header_aware", "semantic"],
max_tokens=512,
)
print(report) # Pro-Strategie-Statistiken: Anzahl, Größenverteilung, Fragmentierung
| Funktion | Zeigt |
|---|
inspect(chunks) | Größenverteilung, Überlappung, Grenzen |
compare(text, strategies=[...]) | Nebeneinander-Strategie-Metriken |
| Metadaten | Verwendung bei Abruf |
|---|
| Überschriftspfad | Kontexterweiterung / Filterung |
| Quelle + Seite | Zitierungen |
| Position/Index | Reihenfolge und Nachbar-Suche |
| Token-Anzahl | Budget-Verwaltung bei Eingabezeit |
enriched = chunky.enrich(chunks, source="report.pdf")
# jeder chunk.metadata trägt jetzt Überschriftspfad, Seite, Quelle, Index
Häufige Workflows
# End-to-End: PDF → sauberes Markdown → Header-Aware Chunks → angereichert
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")
# chunk.text einbetten, chunk.metadata daneben im Vector DB speichern
# Strategie mit Belegen wählen, nicht nach Vermutung
print(chunky.compare(md, strategies=["recursive", "header_aware", "semantic"]))
Chunky vs Andere Ansätze
| Aspekt | Chunky | Framework Standard Splitter | Docling |
|---|
| Strategie-Vergleich | Erste Klasse | Manuell | Begrenzt |
| Konvertierung + Bereinigung | Eingebaut | Separate | Eingebaut |
| Am besten für | Chunking-Phase abstimmen | Schneller Start | Vollständige Parse + Chunk |
Funktioniert gut mit Docling zum Parsen und deinem Vector DB zum Speichern — Chunkys Aufgabe ist es, die Aufteilung richtig zu machen.
Ressourcen
