Wie docling-pipelines Dokumentvektoren für RAG mit OpenSearch oder Milvus speichert
Die Vektordatenbankschicht von IBM docling-pipelines für RAG: einsetzbare OpenSearch- und Milvus-Adapter, Bereinigung veralteter Datenblöcke, automatische Dimensionen, JSON-Flüsse.
Quellen: The Indexing Layer: How docling-pipelines Prepares Your Documents for RAG
Jede moderne Anwendung, die Fragen zu privaten Dokumenten beantwortet, stützt sich auf ein und dasselbe Muster: die retrieval-augmented generation, kurz RAG. Nehmen wir an, jemand fragt, welche Verlängerungsbedingungen für die Verträge vom letzten Jahr gelten oder welche Haftungsgrenzen in Lieferverträgen vorgesehen sind. Bevor ein Sprachmodell antworten kann, muss zunächst etwas die richtigen Passagen unter Tausenden von Dateien finden und sie in einer nutzbaren Form weiterleiten. Das ist eine Vektordatenbank, und der vectordb-Operator im Open-Source-Projekt docling-pipelines von IBM übernimmt genau diese Funktion.
Im Folgenden wird erläutert, warum Vektordatenbanken notwendig sind, wie RAG von ihnen abhängt und wie docling-pipelines den Speicherteil eines RAG-Pipelines in etwas Deklaratives verwandelt – es wird über eine JSON-Flow-Datei konfiguriert und bei Bedarf mit benutzerdefinierten Operatoren erweitert.
RAG und die Rolle der Vektordatenbank
Mit RAG antwortet ein Sprachmodell nicht allein aus dem Gedächtnis. Zunächst holt das System die relevantesten Abschnitte aus einer Dokumentensammlung und fügt sie als Kontext in die Anfrage ein. Das Modell formuliert anschließend eine Antwort, die auf diesen Abschnitten beruht und nicht auf statistischen Mustern aus der Schulung.
Eine Vektordatenbank macht den Abrufschritt möglich. In der Praxis funktioniert das wie folgt.
Zur Indexierung wird jeder Teil der Sammlung durch ein Modell in einen numerischen Vektor, seine Embedding, umgewandelt. Dieses Modell hat gelernt, Texte mit ähnlicher Bedeutung in einem hochdimensionalen Raum in der Nähe voneinander anzuordnen. Die Vektoren werden neben dem ursprünglichen Text gespeichert.
Zur Abfragerzeit wird die Frage des Benutzers mit demselben Modell verarbeitet. Die Datenbank führt eine Suche nach dem nächsten Nachbarn durch und gibt die Abschnitte zurück, deren Vektoren dem Fragevektor am nächsten liegen. Diese Abschnitte sind inhaltlich relevant, selbst wenn sie keine Schlagwörter mit der Frage teilen. Das Modell erhält sie als Kontext und kann daraufhin eine fundierte Antwort liefern.
Warum eine gewöhnliche Datenbank das nicht kann
Eine relationale oder Dokumenten-Datenbank kann Schlagwörter abgleichen, aber nicht die Bedeutung. Eine Suche nach „Beendigungsklauseln“ wird kein Absatz über „Bedingungen für das Vertragsende“ zurückgeben, obwohl beides dasselbe bedeutet. Eine Vektor-Datenbank arbeitet mit Bedeutung und nicht mit Zeichen.
Im großen Maßstab wäre ein vollständiger Vergleich einer Abfrage mit Millionen von Vektoren zu langsam. Deshalb verwenden Vektordatenbanken annähernde Näherungsindexe wie HNSW (Hierarchische, navigierbare kleine Welt-Graphen) und IVF (Umgekehrter Dateiindex). Dadurch wird etwas an Genauigkeit geopfert, um eine erhebliche Verbesserung der Latenzzeit zu erzielen, und beide Indextypen sind gewöhnliche Konfigurationsoptionen im vectordb-Operator.
Welche Backend-Systeme docling-pipelines unterstützt
Das Projekt bietet eine eingebaute Unterstützung für zwei Vektordatenbank-Backends, OpenSearch und Milvus. Beide werden ohne Codeänderungen über die Flow-JSON-Konfiguration eingestellt. Ein Schlüssel „provider“ in der Konfiguration des Operators wählt das Backend aus, und alles Weitere ergibt sich daraus.
Die hexagonale Architektur des Operators macht es einfach, weitere Backends hinzuzufügen. Um Qdrant, pgvector, Weaviate oder alles andere zu unterstützen, schreibt man eine Adapterklasse und registriert sie. Weder der Operator noch das Pipeline-Framework müssen geändert werden.
Wie der Operator funktioniert
Innerhalb des Indexierungs-Pipelines übernimmt der vectordb Operator die Speicherung. Die in seine PyArrow-Tabelle eingehenden Zeilen sind bereits mit folgenden Feldern angereichert:
- der ursprüngliche Dokumenttext;
doc_id_hash, der jedem Dokument eine feste Identifikator gibt, die bei jedem Ausführungsvorgang gleich bleibt;- eine
chunked_content-Spalte, in der das Dokument in überlappende Abschnitte aufgeteilt ist; - eine
embeddings-Spalte mit einem numerischen Vektor pro Abschnitt, der vom vorangegangenenembeddings-Operator erzeugt wird.
Der Operator nimmt diese Tabelle und schreibt jeden Chunk samt seiner Embedding-Daten und Metadaten in die Vektordatenbank. Dabei erstellt oder validiert er das Index-Schema, gruppiert die Masseneinfüge, überwacht, welche Chunks erfolgreich waren oder fehlgeschlagen sind, und entfernt veraltete Chunks aus früheren Ausführungen, wenn sich ein Dokument geändert hat.
Hexagonales Design: Jede Datenbank einsetzbar
Der Operator ist bewusst nicht an eine einzige Datenbank gebunden. Er überträgt die Backend-Arbeit an einen Adapter, der eine VectorStorePort-Schnittstelle erfüllt – einen abstrakten Vertrag, der genau beschreibt, was jede Vektordatenbank bieten muss, einschließlich create_index(), index_documents(), refresh_index() und delete_documents_by_ids().
Das ist das hexagonale Architekturmuster, das auf einen Pipeline-Operator angewandt wird. Die Logik bezüglich dessen, was gespeichert werden soll, befindet sich im Operator. Die Frage der Infrastruktur, wie mit einem bestimmten Backend kommuniziert wird, liegt beim Adapter. Der Operator ruft lediglich die Port-Schnittstelle auf und berührt niemals direkt die OpenSearch- oder Milvus-Protokolle.
VectorDBOperator
│
└── VectorStorePort (interface / abstract contract)
├── OpenSearchAdapter (ships with docling-pipelines)
├── MilvusAdapter (ships with docling-pipelines)
└── YourCustomAdapter (implement VectorStorePort → plug in)
Um eine noch nicht abgedeckte Datenbank zu unterstützen, implementieren Sie VectorStorePort und registrieren Sie den Adapter bei der Factory. Danach kann der Name Ihres Adapters als "provider" in einem Flow-JSON verwendet werden. Nichts anderes ändert sich – weder der Operator noch die umgebende Pipeline noch bestehende Flows mit type: vectordb.
In Blöcken gespeicherte und ungebrochene Dokumente
Sowohl Modi werden transparent behandelt. Wenn chunked_content vorhanden und gefüllt ist – was die Ausgabe des upstream-Operators chunker ist – wird jeder Block als eigenständiges Dokument indiziert. Seine Primärschlüssel werden aus der ID der übergeordneten Datei, dem Blockindex und dem Blocktext abgeleitet. Wenn die Tabelle ganze Dokumente ohne Aufteilung in Blöcke enthält, wird jede Zeile als Einheit indiziert. Der Operator wählt den Pfad automatisch, und es ist kein Flag erforderlich.
Aufräumen von veralteten Blöcken
Updates stellen bei in Blöcken strukturierten Indizes ein bekanntes Problem dar. Wenn eine Datei nach Bearbeitung ihres Inhalts ein zweites Mal eingefügt wird, stimmen die neuen Blöcke nicht mehr mit den zuvor gespeicherten überein. Der Operator begegnet diesem Problem, indem er vor dem Einfügen die vorhandenen Blöck-ID-Listen für jedes Dokument abruft, den Unterschied zwischen den alten und neuen Blöcken berechnet und die veralteten Blöcke löscht, bevor die aktualisierten Daten geschrieben werden. Der Index spiegelt somit immer das aktuelle Dokument wider, unabhängig davon, wie oft der Prozess über denselben Datensatz laufen wurde.
Für Sie erkannte Vektordimensionen
Es ist nicht notwendig, die Dimensionen manuell zu zählen und fest einzuschreiben. Wenn der Prozess läuft, liest der Operator die erste nicht-leere Embedding-Wertung in der Tabelle und entnimmt die Dimension aus deren Länge. Der Index wird anschließend mit dieser Größe erstellt – oder geprüft, falls er bereits existiert.
Ein vollständiger RAG-Indizierungsprozess
Ein vollständiger Indexierungsprozess besteht hier aus fünf Operatoren, die durch depends_on-Kanten miteinander verbunden sind. Dieses lokale Beispiel verwendet OpenSearch:
{
"flow_name": "rag-indexing-pipeline",
"global_config": {
"doc_column": "content",
"storage": "in-memory",
"execute_type": "local",
"enable_micro_batching": true,
"micro_batch_size": 10
},
"flow": [
{
"name": "ingest",
"type": "ingest_source",
"config": {
"provider": "filesystem",
"connection_params": { "paths": ["./documents"], "recursive": true },
"include_filter": "pdf,docx,txt"
}
},
{
"name": "extract",
"type": "extract_operator",
"depends_on": ["ingest"],
"config": {
"text_extraction": { "provider": "docling_library", "doc_column": "content" }
}
},
{
"name": "chunk",
"type": "chunker",
"depends_on": ["extract"],
"config": {
"doc_column": "content",
"chunk_size": 512,
"chunk_overlap": 50
}
},
{
"name": "embed",
"type": "embeddings",
"depends_on": ["chunk"],
"config": {
"provider": "litellm",
"embeddings_column": "embeddings",
"provider_config": {
"model_id": "openai/nomic-embed-text",
"api_base": "http://localhost:11434/v1",
"api_key": "${OLLAMA_API_KEY}"
}
}
},
{
"name": "store",
"type": "vectordb",
"depends_on": ["embed"],
"config": {
"provider": "opensearch",
"doc_id_column": "doc_id_hash",
"create_index": true,
"provider_config": {
"index_name": "my_rag_index",
"host": "localhost",
"port": 9200,
"username": "${OPENSEARCH_USERNAME}",
"password": "${OPENSEARCH_PASSWORD}",
"use_ssl": false,
"engine": "faiss",
"algorithm": "hnsw",
"space_type": "l2"
}
}
}
]
}
Führen Sie es von der Befehlszeile aus aus:
docling-pipelines --flow-file rag-pipeline.json
Jeder PDF-, DOCX- und Textdatei unter ./documents wird nachgefunden, extrahiert und in Blöcke à 512 Token aufgeteilt, wobei ein Überschneidungsbereich von 50 Token besteht. Diese Einstellungen befinden sich im chunker-Node und können frei geändert werden. Die Blöcke werden mithilfe des lokalen nomic-embed-text-Modells über Ollama eingebettet und schließlich in einen für Suchvorgänge nach Ähnlichkeit konfigurierten OpenSearch-Index geschrieben.
Das Beispiel liest aus einer lokalen Ordnerstruktur, doch die Eingabe kann auch aus S3, SharePoint, Google Drive, Box, OneDrive sowie benutzerdefinierten Ladenmechanismen stammen. Nur der ingest_source-Node ändert sich; jeder nachfolgende Operator, einschließlich vectordb, bleibt unabhängig von der Herkunft der Dokumente unverändert.
Milvus mit zwei Embedding-Modellen
Teams, die Dokumente mit zwei verschiedenen Modellen gleichzeitig einbetten möchten – beispielsweise ein allgemein einsetzbares Modell und ein modellspezifisches – können die branching- und merge-Operator verwenden. Der Ablauf umfasst das Einlesen, Extrahieren, Aufteilen in Blöcke, das Aufteilen in zwei Einbettungsschritte, das Zusammenführen sowie schließlich das Schreiben in Milvus.
Der Milvus-Adapter akzeptiert mehrere Vektorspalten. Die Ausgabe jedes Modells wird in ein eigenes Vektorfeld in der Sammlung geschrieben, was eine Ensemble-Suche zum Zeitpunkt der Abfrage ermöglicht: Die besten Ergebnisse aus dem Index jedes Modells werden vor der Rangliste zusammengeführt.
Incrementelles Indexieren
Der Operator ist so konzipiert, dass er immer wieder über ein wachsendes Korpus ausgeführt werden kann, ohne alles erneut indizieren zu müssen. Der Einpflegungsoperator merkt sich zudem frühere Ausführungen und überspringt Dateien, deren Hash und Änderungszeit unverändert sind. So gelangen nur neue und geänderte Dokumente durch den Pipeline-Prozess. Ihre Blöcke werden geschrieben, veraltete Blöcke aktualisierter Dokumente werden entfernt und alles Weitere bleibt unberührt.
Bei einer planmäßigen Pipeline für einen kontinuierlich wachsenden Dokumentenspeicher skaliert die Laufzeit mit der Menge der Änderungen und nicht mit der Gesamtgröße des Korpus.
Platz in der Gesamtstruktur
In einem RAG-Fluss mit Docling-Pipelines ist der Operator vectordb der Vektor-Speicher-Node. Je nach Konfiguration kann er der letzte Node sein oder von weiteren Nodes gefolgt werden. Ein Operator document_set kann beispielsweise die vollständige, erweiterte PyArrow-Tabelle zusammen mit dem Vektorindex in DuckDB speichern, um sie später analysieren zu können.
Jeder Operator kommuniziert über ein standardisiertes PyArrow-Tabellenschema, sodass vectordb unabhängig davon ist, woher seine Zeilen stammen – ob aus einem lokalen Ordner, S3, SharePoint oder einem benutzerdefinierten Lader. Die Portabilität der Quellen sowie der Speicherung ist eine durch die Architektur vorgegebene strukturelle Eigenschaft und nicht auf Konventionen beschränkt. Der Operator übernimmt die Erstellung von Indizes, batchbasierte Massenschreibvorgänge, mehrere Vektorspalten, die Bereinigung veralteter Datenblöcke sowie die automatische Dimensionserkennung – alles gesteuert durch die Flow-Datei, wobei Größe der Datenblöcke, Überschneidungen, das Einbettungsmodell, der Indexalgorithmus sowie die Ähnlichkeitsmetrik als Konfigurationseinstellungen bereitgestellt werden.
Es handelt sich dabei um ein Element eines wachsenden Pipeline-Ökosystems, und das Projekt ist unter IBM als Open Source verfügbar. Falls Ihre Vektordatenbank noch nicht unterstützt wird, ist die Adapter-Schnittstelle der geeignete Ausgangspunkt.