Comment docling-pipelines stocke les vecteurs de documents pour RAG avec OpenSearch ou Milvus
La couche de base de données vectorielles d’IBM docling-pipelines pour RAG : adaptateurs OpenSearch et Milvus interchangeables, nettoyage des blocs obsolètes, dimensions automatiques, flux JSON.
Sources: The Indexing Layer: How docling-pipelines Prepares Your Documents for RAG
Toute application moderne qui répond à des questions concernant des documents privés s’appuie sur un même modèle : la génération augmentée par la recherche, ou RAG. Supposons que quelqu’un demande quels termes de renouvellement s’appliquent aux contrats de l’année dernière, ou quels plafonds de responsabilité figurent dans les accords avec les fournisseurs. Avant que un modèle de langage ne puisse répondre, il faut que quelque chose trouve les passages appropriés parmi des milliers de fichiers et les transmette sous une forme utilisable. Ce « quelque chose » est une base de données vectorielle, et l’opérateur vectordb du projet open source docling-pipelines d’IBM remplit cette fonction.
Ci-dessous sont expliqués les principes fondamentaux des bases de données vectorielles, la manière dont RAG en dépend, ainsi que la façon dont docling-pipelines transforme la partie de stockage d’un pipeline RAG en quelque chose de déclaratif : configuré à l’aide d’un fichier JSON et pouvant être étendu avec des opérateurs personnalisés si nécessaire.
RAG et le rôle de la base de données vectorielle
Avec RAG, un modèle de langage ne répond pas uniquement en s’appuyant sur sa mémoire. Le système récupère d’abord les passages les plus pertinents d’une collection de documents et les intégre dans la demande en tant que contexte. Le modèle rédige ensuite une réponse basée sur ces passages et non sur des habitudes statistiques issues de son entraînement.
Une base de données vectorielle rend possible cette étape de récupération. En pratique, cela fonctionne ainsi.
Lors de l’indexation, chaque fragment de la collection est converti en un vecteur numérique, son embedding, par un modèle qui a appris à placer les textes ayant un sens similaire proche les uns des autres dans un espace à haute dimension. Ces vecteurs sont stockés à côté du texte original.
Lors de la requête, la question de l’utilisateur est traitée avec le même modèle. La base de données effectue une recherche du voisin le plus proche et renvoie les fragments dont les vecteurs sont les plus proches du vecteur de la question. Ces fragments sont pertinents sur le plan sémantique, même s’ils ne partagent aucune mot-clé avec la question. Le modèle les reçoit comme contexte et peut ainsi produire une réponse fondée.
Pourquoi une base de données ordinaire ne peut pas le faire
Une base de données relationnelle ou documentaire peut matcher des mots-clés mais pas le sens. Une recherche pour "termination clauses" ne renverra pas un paragraphe sur "conditions de sortie du contrat", même si les deux expressions signifient la même chose. Une base de données vectorielle fonctionne sur le sens et non sur les caractères.
À grande échelle, comparer une requête avec des millions de vecteurs de manière exhaustive serait trop lent. Les bases de données vectorielles utilisent donc des index d’approximation des voisins les plus proches, tels que HNSW (graphes hiérarchiques navigables de petit monde) et IVF (index de fichiers inversé). Elles sacrifient un peu de précision pour gagner beaucoup en latence, et ces deux types d’index sont des options de configuration courantes dans l’opérateur vectordb.
Quels backends docling-pipelines prend en charge
Le projet intègre par défaut un support intégré pour deux backends de bases de données vectorielles : OpenSearch et Milvus. Tous deux sont configurés via le JSON du flux sans modification de code. Une clé "provider" dans la configuration de l’opérateur choisit le backend, et tout le reste en dépend.
L’architecture hexagonale de l’opérateur permet d’ajouter facilement d’autres backends. Pour prendre en charge Qdrant, pgvector, Weaviate ou tout autre système, il suffit d’écrire une classe d’adaptateur et de la enregistrer. Ni l’opérateur ni le framework de pipeline n’ont besoin d’être modifiés.
Comment fonctionne l’opérateur
Dans le pipeline d’indexation, l’opérateur vectordb gère le stockage. Les lignes arrivant dans sa table PyArrow sont déjà enrichies des champs suivants :
- le texte du document original ;
doc_id_hash, qui attribue à chaque document un identifiant fixe identique à chaque exécution ;- une colonne
chunked_contentreprésentant le document divisé en fenêtres superposées ; - une colonne
embeddingscontenant un vecteur numérique par morceau, généré par l’opérateurembeddingsen amont.
L’opérateur prend cette table et écrit chaque morceau, avec son encodage et ses métadonnées, dans la base de données vectorielle. Au cours de ce processus, il crée ou valide le schéma de l’index, groupe les insérations en lots, suit les morceaux qui ont réussi ou échoué, et supprime les morceaux obsolètes issues de sessions antérieures lorsque un document a été modifié.
Conception hexagonale : intégration avec n’importe quelle base de données
L’opérateur n’est pas intentionnellement lié à une seule base de données. Il confie le travail backend à un adaptateur qui implémente une interface VectorStorePort, un contrat abstrait décrivant les fonctionnalités offertes par chaque base de données vectorielle, notamment create_index(), index_documents(), refresh_index() et delete_documents_by_ids().
C’est le pattern d’architecture hexagonale appliqué à un opérateur de pipeline. La logique concernant ce qui doit être stocké se trouve dans l’opérateur. La question d’infrastructure relative à la manière de communiquer avec un backend spécifique est gérée par l’adaptateur. L’opérateur n’appelle que l’interface de port et ne touche jamais directement aux protocoles OpenSearch ou Milvus.
VectorDBOperator
│
└── VectorStorePort (interface / abstract contract)
├── OpenSearchAdapter (ships with docling-pipelines)
├── MilvusAdapter (ships with docling-pipelines)
└── YourCustomAdapter (implement VectorStorePort → plug in)
Pour prendre en charge une base de données qui n’est pas encore couverte, implémentez VectorStorePort et enregistrez l’adaptateur auprès de la factory. Par la suite, le nom de votre adaptateur pourra être utilisé comme "provider" dans un fichier JSON de flux. Rien d’autre ne change, que ce soit l’opérateur, le pipeline environnant ou les flux existants avec type: vectordb.
Documents en morceaux et non divisés
Les deux modes sont gérés de manière transparente. Lorsque chunked_content existe et est rempli, ce qui correspond à la sortie de l’opérateur chunker en amont, chaque morceau est indexé en tant que document distinct. Sa clé primaire est dérivée de l’ID du fichier parent, de l’index du morceau et du texte du morceau. Lorsque la table contient des documents complets sans segmentation en morceaux, chaque ligne est indexée en tant qu’unité unique. L’opérateur choisit automatiquement le chemin, et aucun indicateur n’est nécessaire.
Nettoyage des morceaux obsolètes
Les mises à jour représentent un problème récurrent avec les index en blocs. Lorsqu’un fichier est retraité une seconde fois après que son contenu a été modifié, les nouveaux blocs ne correspondent plus à ceux stockés précédemment. L’opérateur y remédie en recherchant les IDs des blocs existants pour chaque document avant d’effectuer l’insertion, en calculant la différence entre les ensembles anciens et nouveaux, puis en supprimant les blocs obsolètes avant d’écrire le nouveau lot. L’index reflète ainsi le document actuel, quel que soit le nombre de fois où le pipeline a été exécuté sur le même corpus.
Dimensions vectorielles détectées pour vous
Vous n’avez pas besoin de compter les dimensions ni de les définir manuellement. Lorsque le pipeline s’exécute, l’opérateur lit la première valeur d’embedding non nulle dans le tableau et prend la dimension en fonction de sa longueur. L’index est ensuite créé avec cette taille, ou vérifié si un index existant correspond déjà à celle-ci.
Un flux complet d’indexation RAG
Un pipeline d’indexation complet se compose ici de cinq opérateurs reliés par des arêtes depends_on. Cet exemple local utilise 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"
}
}
}
]
}
Exécutez-le depuis la ligne de commande :
docling-pipelines --flow-file rag-pipeline.json
Tous les fichiers PDF, DOCX et de texte brut situés dans ./documents sont découverts, extraits et divisés en blocs de 512 tokens chacun, avec une superposition de 50 tokens ; ces paramètres se trouvent dans le nœud chunker et peuvent être modifiés librement. Les blocs sont ensuite intégrés à l’aide du modèle nomic-embed-text exécuté localement via Ollama, avant d’être enregistrés dans un index OpenSearch conçu pour des recherches de similarité.
L’exemple montre comment lire depuis un dossier local, mais l’ingestion prend également en charge S3, SharePoint, Google Drive, Box, OneDrive ainsi que des chargeurs personnalisés. Seul le nœud ingest_source change ; tous les opérateurs suivants, y compris vectordb, restent identiques quel que soit l’origine des documents.
Milvus avec deux modèles d’incorporation
Les équipes qui souhaitent intégrer des documents avec deux modèles différents en même temps, par exemple un modèle polyvalent et un modèle spécialisé dans un domaine particulier, peuvent utiliser les opérateurs branching et merge. Le flux comprend les étapes d’ingestion, d’extraction, de segmentation en blocs, de bifurcation en deux étapes d’incorporation, de fusion, puis d’écriture dans Milvus.
L’adaptateur Milvus accepte plusieurs colonnes vectorielles. La sortie de chaque modèle est stockée dans son propre champ vectoriel au sein de la collection, ce qui permet une recherche par ensemble au moment de la requête : on prend les meilleurs résultats de l’index de chaque modèle et on les combine avant de procéder au classement.
Indexation incrémentale
L’opérateur est conçu pour fonctionner encore et encore sur un corpus en constante augmentation sans devoir réindexer tout le contenu. L’opérateur d’ingestion se souvient également des exécutions précédentes et saute les fichiers dont le hash et l’heure de modification sont inchangés. Ainsi, seuls les documents nouveaux ou modifiés parviennent jusqu’au pipeline. Leurs fragments sont enregistrés, les fragments obsolètes de documents mis à jour sont supprimés, et tout le reste reste inchangé.
Pour un pipeline planifié sur un stock de documents en croissance continue, le temps d’exécution est proportionnel à l’ampleur des modifications et non à la taille totale du corpus.
Sa place dans le contexte global
Dans un flux RAG utilisant des pipelines docling, l’opérateur vectordb représente le nœud de stockage vectoriel. Selon la conception, il peut être le dernier nœud ou être suivi d’autres nœuds. Un opérateur document_set, par exemple, peut conserver la table PyArrow enrichie dans son intégralité dans DuckDB afin d’en effectuer une analyse ultérieure en même temps que l’index vectoriel.
Chaque opérateur communique via un schéma de table standard PyArrow, de sorte que vectordb est indifférent à l’origine de ses lignes, qu’il s’agisse d’un dossier local, de S3, de SharePoint ou d’un chargeur personnalisé. La portabilité des sources et du stockage est une propriété structurelle imposée par l’architecture et non le fruit de conventions. L’opérateur gère la création d’index, les écritures en masse par lots, plusieurs colonnes vectorielles, le nettoyage des blocs obsolètes ainsi que la détection automatique des dimensions, tout cela étant piloté par le fichier de flux, avec la taille des blocs, l’overlap, le modèle d’incorporation, l’algorithme d’indexation et la métrique de similarité exposés en tant que paramètres de configuration.
Ce composant fait partie d’un écosystème de pipelines en constante évolution, et le projet est open source sous licence IBM. Si votre base de données vectorielle n’est pas encore prise en charge, l’interface d’adaptateur constitue un bon point de départ.