Einleitung

Unstructured.io ist ein Open-Source-Framework zur strukturierten Aufbereitung unstrukturierter Dokumente wie PDFs, Word-Dateien, HTML-Seiten oder E-Mails. Ziel ist es, aus diesen heterogenen Formaten semantisch verwertbare Inhalte zu extrahieren, etwa Überschriften, Absätze, Tabellen oder Listen, und sie in ein einheitliches, maschinenlesbares Format zu überführen. Der Hauptanwendungsfall liegt in der Vorbereitung von Textdaten für nachgelagerte KI-Verarbeitung, insbesondere für Systeme mit Retrieval-Augmented Generation (RAG).

Der typische Einsatz erfolgt im Rahmen von Dokumentenanalyse, Wissensmanagement oder zur Vorbereitung von Eingaben für Embedding-Modelle. Dabei kommen mehrere Verarbeitungsschritte zum Einsatz. Diese vier Schritte bilden den Kern der Unstructured.io-Pipeline und werden bei jeder regulären Nutzung der Bibliothek durchlaufen.

• Partitioning
  Zerlegung des Dokuments in logische Content-Elemente wie Absätze, Überschriften oder Tabellen.
• Cleaning
  Entfernung irrelevanter Bestandteile wie Kopfzeilen, Fußzeilen oder Wasserzeichen.
• Extracting
  Extraktion des reinen Textinhalts sowie begleitender Metadaten.
• Staging
  Aufbereitung dieser Informationen in einem konsistenten strukturierten Format (z. B. JSON oder Markdown).

Darüber hinaus existieren optionale Erweiterungen:

• Chunking: Längere Inhalte werden in kleinere Texteinheiten zerlegt, die besser für Embedding-Modelle geeignet sind. Dieser Schritt ist nicht zwingend Teil der Kernbibliothek, aber für viele KI-Anwendungen notwendig.
• Embedding: Die entstandenen Text-Chunks werden an externe Modelle (z. B. OpenAI, HuggingFace, SentenceTransformers) übergeben, um Vektorrepräsentationen zu erzeugen. Dieser Schritt erfolgt außerhalb von Unstructured und muss vom Nutzer selbst implementiert oder über vorhandene Beispielpipelines ergänzt werden.

Damit ist klar: Unstructured.io übernimmt die Dokumentvorverarbeitung bis zur strukturierten Textausgabe. Für eine vollständige RAG-Pipeline – bestehend aus Embedding, Vektordatenbank, Retrieval-Logik und Sprachmodell – sind zusätzliche Werkzeuge notwendig. Unstructured stellt somit den ersten, vorbereitenden Abschnitt einer solchen Architektur dar.

Beispiel PDF-Dokumente zum Experimentieren

https://github.com/Unstructured-IO/unstructured/tree/main/example-docs/pdf

Unterstützte Datentypen

Benötigte externe Bibliotheken

Daten-Pipeline (Data Pipeline)

Der unstructured.io-Workflow ist eine mehrstufige Datenpipeline, die Rohdokumente systematisch in KI-fertige Informationen umwandelt. Der Prozess beginnt mit dem Partitioning, bei dem ein Dokument in seine logischen Elemente wie Titel, Absätze und Tabellen zerlegt wird. Im anschließenden Cleaning-Schritt werden diese Elemente von störenden Inhalten wie Kopf- oder Fußzeilen befreit. Darauf folgt das Extracting, bei dem die reinen Textinhalte sowie wichtige Metadaten aus den Elementen extrahiert werden. Der Staging-Bereich dient dann dazu, diese extrahierten Daten zu strukturieren und für die nächsten Phasen vorzubereiten. Im Chunking werden längere, zusammenhängende Texte in kleinere, für Modelle optimierte Abschnitte unterteilt. Der finale Schritt, das Embedding, wandelt diese Text-Chunks in numerische Vektoren um, die von KI-Systemen wie RAG-Anwendungen verarbeitet und durchsucht werden können.

[ Partitioning ] > [ Cleaning ] > [ Extracting ] > [ Staging ] > [ Chunking ] > [ Embedding ]

Kern-Pipeline Schritte (Pflichtschritte)

[ Partitioning ] > [ Cleaning ] > [ Extracting ] > [ Staging ]

Partitioning

Die Bibliothek unstructured bietet Partitionierungsfunktionen, um rohe Dokumente in strukturierte Bausteine wie Titel, Fließtext oder Listenelemente zu zerlegen. Dies erlaubt es Anwendern, gezielt nur die Inhalte auszuwählen, die sie für ihre spezifische Aufgabe benötigen, zum Beispiel nur den Fließtext für das Training eines Zusammenfassungs-Modells.

Beispiel *.PDF Datei zum Testen der unstructured.io Bibliotkek:

Die partition-Funktion hat das obige PDF-Dokument analysiert. Anstatt das Dokument nur als eine lange, unformatierte Textsequenz zu betrachten, hat sie die visuelle Struktur und das Layout der Seite interpretiert, um einzelne logische Bausteine (Document Elements), z.B. „Titel“ und „NarrativeText“ zu identifizieren.

....
    {
        "type": "Title",
        "element_id": "42a9c358d559f0be7034cffd155ae0b4",
        "text": "OPITZ CONSULTING UND STACKIT WERDEN CLOUD-PARTNER",
        "metadata": {
            "detection_class_prob": 0.6857117414474487,
            "coordinates": {
                "points": [
                    [
                        197.0,
                        771.6636962890625
                    ],
                    [
                        197.0,
                        903.3959999999997
                    ],
                    [
                        1249.1890000000003,
                        903.3959999999997
                    ],
                    [
                        1249.1890000000003,
                        771.6636962890625
                    ]
                ],
                "system": "PixelSpace",
                "layout_width": 1654,
                "layout_height": 2339
            },
            "last_modified": "2025-05-31T08:21:16",
            "filetype": "application/pdf",
            "languages": [
                "deu",
                "eng"
            ],
            "page_number": 1,
            "filename": "test_oc.pdf"
        }
    },
    {
        "type": "NarrativeText",
        "element_id": "32dd7508dbc59793a297552a980b06e0",
        "text": "MIT STACKIT holt sich OPITZ CONSULTING einen souveränen deutschen Cloud- Provider mit ins Boot – mit Rechenzentren in Deutschland und Österreich",
        "metadata": {
            "detection_class_prob": 0.8894028067588806,
            "coordinates": {
                "points": [
                    [
                        192.57095336914062,
                        932.173583984375
                    ],
                    [
                        192.57095336914062,
                        1014.2666666666665
                    ],
                    [
                        1392.389892578125,
                        1014.2666666666665
                    ],
                    [
                        1392.389892578125,
                        932.173583984375
                    ]
                ],
                "system": "PixelSpace",
                "layout_width": 1654,
                "layout_height": 2339
            },
            "last_modified": "2025-05-31T08:21:16",
            "filetype": "application/pdf",
            "languages": [
                "deu",
                "eng"
            ],
            "page_number": 1,
            "parent_id": "42a9c358d559f0be7034cffd155ae0b4",
            "filename": "test_oc.pdf"
        }
    },
....

Erklärung der einzelnen Element-Typen aus dem PDF z.B. Title:

Das hier ist die Lister der wichtigsten Dokumentelemente wie z.B. Text, Header, Image usw. Die komplette Liste der Elemente ist hier zu finden: Link

Cleaning

Die cleaning-Funktion dient dazu, unerwünschte Inhalte aus Dokumenten zu entfernen, um die Daten für nachgelagerte Aufgaben wie die Verarbeitung durch Sprachmodelle (LLMs) vorzubereiten. Das Ziel ist es, „saubere“ und relevantere Daten zu erhalten.

Die folgende Tabelle bietet einen Überblick über die verschiedenen cleaning-Funktionen. Quelle: Link

Extraction

Der Schritt „Extracting“ isoliert gezielt spezifische Informationen aus bereits bereinigten Textelementen.

Angenommen, ein Text enthält den Satz: Für weitere Informationen kontaktieren Sie bitte support@example.com. Anstatt den ganzen Satz zu verarbeiten, würde eine Extraktionsfunktion wie extract_email_address nur den gewünschten Datenpunkt, nämlich support@example.com, herausziehen.

Staging

Staging-Funktionen im unstructured-Paket dienen der Aufbereitung extrahierter Dokumentelemente für nachgelagerte Verarbeitungsschritte. Als Eingabe wird eine Liste strukturierter Elemente erwartet, beispielsweise Title oder NarrativeText. Die Ausgabe ist ein sogenanntes formatgerechtes Dictionary. Darunter ist eine strukturierte Sammlung von Daten in Form von Schlüssel-Wert-Paaren zu verstehen. Die einzelnen Informationen, etwa ein Textabschnitt oder ein Metadatum, werden dabei einem eindeutigen Bezeichner zugeordnet. Diese Bezeichner, sogenannte Schlüssel, können zum Beispiel „text“, „metadata“ oder „type“ heißen. Ziel ist es, die Daten so aufzubereiten, dass sie vom jeweils vorgesehenen Zielsystem direkt weiterverarbeitet werden können.

Für verschiedene Anwendungsfälle standen ursprünglich spezialisierte Konvertierungsfunktionen zur Verfügung:

• Eine Basis-Konvertierung wie convert_to_csv zur Überführung in tabellarische Formate
• Eine Konvertierung für maschinelles Lernen und NLP-Plattformen wie stage_for_transformers zur Vorbereitung von Trainingsdaten
• Eine Konvertierung für Vektordatenbanken wie stage_for_weaviate zur semantischen Indexierung

Diese Funktionen sind mittlerweile veraltet. Die weitere Entwicklung konzentriert sich auf das Konzept sogenannter Destination Connectors z.B. für Kafka, Weaviate oder MongoDB. Damit lassen sich Daten nach der Extraktion automatisiert an externe Plattformen übergeben.

Die Auswahl unterstützter Plattformen wird laufend erweitert. Falls eine gewünschte Zielumgebung nicht enthalten ist, kann diese im Community-Slack vorgeschlagen werden.

Erweiterte-Pipeline Schritte (Optional)

[ Chunking ] > [ Embedding ]

Chunking

Unstructured verwenden Metadaten und Dokumentelemente, die mit Partitionsfunktionen erkannt wurden, um Elemente zu nützlicheren „Chunks“ umzuwandeln.

Chunking Strategie

Aktuell bietet Unstructured die beiden Chunking-Strategien „basic“ und „by_title“ an. Wesentliche Bestandteile der basic-Strategie sind:

basic

Die „basic“-Strategie ist die einfachste und eine der am häufigsten verwendeten Methoden in der unstructured-Bibliothek. Ihre Hauptaufgabe ist es, sequenzielle (aufeinanderfolgende) Elemente eines Dokuments zu kombinieren, um Chunks zu erstellen, die so groß wie möglich sind, ohne eine festgelegte maximale Zeichenzahl zu überschreiten:

• max_characters: eine harte Grenze, die nicht überschritten werden darf
• new_after_n_chars: eine weiche Grenze. Bei der Überschreitung wird ein neuer Chunk begonnen, auch wenn die harte Grenze noch nicht erreicht ist. Wird diese Schwelle überschritten, wird vorzugsweise ein neuer Chunk begonnen, wenn es semantisch sinnvoll oder technisch machbar ist. Sie kann also ignoriert werden, wenn das Modell erkennt, dass es sich besser kombinieren lässt, solange die harte Grenze eingehalten wird.
• overlap: Wenn ein einzelnes Element zu groß ist und zerschnitten werden muss, gibt dieser Parameter an, wie viele Zeichen sich am Ende des einen und am Anfang des nächsten Chunks überlappen sollen. Dies hilft, den Kontext über die Chunk-Grenzen hinweg zu erhalten.
• overlap_all: Wenn auf True gesetzt, wird ein Überlapp nicht nur bei übergroßen, geteilten Elementen angewendet, sondern zwischen allen aufeinanderfolgenden Chunks.

Eingabe:
Element A: 200 Zeichen
Element B: 250 Zeichen
Element C: 300 Zeichen
Element D: 400 Zeichen

Einstellungen:
max_characters = 1000
new_after_n_chars = 600

Ergebnis:
Chunk 1: A   B (450 Zeichen d.h. unterhalb der weichen Grenze)
Chunk 2: C (300 Zeichen d.h. nach Überschreiten von 600 startet neuer Chunk)
Chunk 3: D (400 Zeichen)

Sonderfall Tabellen: Tabellen (Table-Elemente) werden immer als eigenständige Chunks behandelt und niemals mit anderen Elementen kombiniert. Ist eine Tabelle selbst zu groß, wird sie ebenfalls aufgeteilt.

Bei „basic“ stoßen wir bei stark strukturierten Dokumenten wie Berichten, wissenschaftlichen Arbeiten oder Handbüchern an die Grenzen dieser Strategie.

by_title

Die by_title-Strategie erbt alle grundlegenden Verhaltensweisen der basic-Strategie (wie z. B. das Respektieren von max_characters), fügt aber drei entscheidende, neue Regeln hinzu:

• Die Strategie identifiziert Title-Elemente (Überschriften) als Beginn eines neuen Abschnitts. Wenn der Algorithmus auf eine Überschrift stößt, führt er folgende Aktion aus:
  • Der aktuelle Chunk wird sofort geschlossen.
  • Ein neuer Chunk wird gestartet, beginnend mit diesem Title-Element.

Dies geschieht selbst dann, wenn die Überschrift textlich noch perfekt in den vorherigen Chunk gepasst hätte.

• Standardmäßig behandelt die Strategie Seitenumbrüche nicht als harte Trennung. Das bedeutet, ein Abschnitt kann sich über mehrere Seiten erstrecken, ohne in einen neuen Chunk aufgeteilt zu werden. Dieses Verhalten wird durch den Parameter multipage_sections=True (Standardwert) gesteuert.
• Manchmal werden in Dokumenten sehr kurze Texte, wie z. B. einzelne Listeneinträge, fälschlicherweise als Title-Element identifiziert. Dies kann zu einer Flut von winzigen, unerwünschten Chunks führen. Um dieses Problem zu lösen, gibt es den Parameter combine_text_under_n_chars:
  • Dieser Parameter erlaubt es, mehrere aufeinanderfolgende, kleine Abschnitte zu einem einzigen Chunk zu kombinieren, um das Chunking-Fenster (max_characters) bestmöglich zu füllen.
  • Standardmäßig ist der Wert von combine_text_under_n_chars derselbe wie der von max_characters. Dies stellt sicher, dass kleine Sektionen effizient zusammengefasst werden.
  • Bei 0 wird jeder noch so kleine, als Title erkannte Abschnitt als ein neuer Chunk definiert.

Die by_title-Strategie ist die bessere Wahl für alle Dokumente mit einer klaren, hierarchischen Gliederung wie z.B., Berichten, Forschungsartikeln, Anleitungen oder Verträge.

Embedding

Nach der Extraktion von Inhalten aus Dokumenten mittels der Open-Source-Bibliothek unstructured ist ein häufiger nachgelagerter Schritt die Konvertierung der extrahierten Textelemente in Vektor-Embeddings. Diese Vektoren sind die Grundlage für semantische Suchfunktionen und Retrieval-Augmented Generation (RAG).

Die unstructured-Kernbibliothek selbst enthält keine nativen Funktionen zum Aufrufen von Embedding-Anbietern. Stattdessen existieren zwei primäre Methoden, um Embeddings für unstructured-Ausgaben zu erzeugen.

Metode 1: Das Unstructured-Ökosystem stellt eine erweiterte Funktionalität in Form der Unstructured Ingest Kommandozeile (CLI) und der zugehörigen Python-Bibliothek zur Verfügung. Diese Komponenten sind für die Erstellung vollständiger End-to-End-Verarbeitungspipelines konzipiert und bieten eine eingebaute Unterstützung für die Anbindung an Embedding-Anbieter.

Bei diesem Ansatz wird die Embedding-Erzeugung nahtlos in den Datenaufnahmeprozess („Ingest Pipeline“) integriert. Dies ermöglicht die vollständige Automatisierung des Workflows vom Rohdokument bis zum fertigen Vektor-Embedding. Informationen zur Konfiguration sind in der offiziellen Dokumentation verfügbar.

Methode 2: Eine alternative Methode ist die manuelle Anreicherung der von unstructured erzeugten JSON-Dateien. Dieser Ansatz bietet ein hohes Maß an Flexibilität, insbesondere bei der Auswahl des Embedding-Modells, und eignet sich für Szenarien, in denen keine vollständige Ingest-Pipeline zum Einsatz kommt.

Der Prozess folgt typischerweise einem festen Schema:

• Input: Eine von der unstructured-Bibliothek generierte JSON-Datei dient als Eingangsquelle.
• Einlesen: Der Inhalt der JSON-Datei wird als strukturiertes Objekt in den Speicher geladen.
• Embedding-Generierung: Eine Drittanbieter-Bibliothek, wie beispielsweise sentence-transformers, wird verwendet, um für den Wert des text-Feldes jedes Elements in der JSON-Datei ein Embedding zu erzeugen. Das Modell sentence-transformers/all-MiniLM-L6-v2 von Hugging Face ist ein gängiges Beispiel hierfür.
• Datenanreicherung: Das generierte Embedding wird als neues Feld neben dem korrespondierenden text-Feld in das JSON-Objekt eingefügt.
• Speichern: Das modifizierte JSON-Objekt mit den hinzugefügten Embeddings wird zurück in die Ursprungsdatei oder eine neue Datei geschrieben.

Dieser Ansatz gewährt volle Kontrolle über den Prozess und lässt sich in bestehende Arbeitsabläufe integrieren, die auf dem Austausch von JSON-Dateien basieren.