Inicio / Artículos

Cómo docling-pipelines almacena vectores de documentos para RAG con OpenSearch o Milvus

La capa de base de datos vectoriales de IBM docling-pipelines para RAG: adaptadores OpenSearch y Milvus conectables, limpieza de fragmentos obsoletos, dimensiones automáticas, flujos JSON.

Editor: REACTAPP.TOP7 min de lectura1688 palabras

Fuentes: The Indexing Layer: How docling-pipelines Prepares Your Documents for RAG

Cualquier aplicación moderna que responde preguntas sobre documentos privados se basa en un mismo patrón: la Generación Aumentada por Recuperación de Información, o RAG. Supongamos que alguien pregunta cuáles son los términos de renovación aplicables a los contratos del año pasado, o qué límites de responsabilidad aparecen en los acuerdos con proveedores. Antes de que un modelo de lenguaje pueda responder, algo debe encontrar los pasajes adecuados entre miles de archivos y transmitirlos en un formato utilizable. Ese algo es una base de datos vectorial, y el operador vectordb del proyecto de código abierto docling-pipelines de IBM cumple esa función.

A continuación se explica el razonamiento detrás de las bases de datos vectoriales, cómo RAG depende de ellas y cómo docling-pipelines convierte la parte de almacenamiento de un pipeline RAG en algo declarativo: se configura a través de un archivo de flujo JSON y se puede ampliar con operadores personalizados cuando sea necesario.

RAG y el papel de la base de datos vectorial

Con RAG, un modelo de lenguaje no responde únicamente a partir de su memoria. El sistema primero obtiene los pasajes más relevantes de una colección de documentos y los incluye en la solicitud como contexto. Luego, el modelo elabora una respuesta basada en esos pasajes y no en patrones estadísticos adquiridos durante el entrenamiento.

Una base de datos vectorial hace posible este paso de recuperación. En la práctica, funciona de la siguiente manera.

En el momento de indexar, cada fragmento de la colección se convierte en un vector numérico, su embedding, mediante un modelo que ha aprendido a colocar cerca en un espacio de alta dimensión al texto con significados similares. Los vectores se almacenan junto al texto original.

En el momento de la consulta, la pregunta del usuario se procesa con el mismo modelo. La base de datos realiza una búsqueda de vecinos más cercanos y devuelve los fragmentos cuyos vectores están más cerca del vector de la pregunta. Dichos fragmentos son relevantes desde el punto de vista semántico, incluso cuando no comparten ninguna palabra clave con la pregunta. El modelo los recibe como contexto y puede generar una respuesta fundamentada.

Por qué una base de datos ordinaria no puede hacerlo

Una base de datos relacional o de documentos puede coincidir palabras clave, pero no el significado. Una búsqueda de “cláusulas de terminación” no devolverá un párrafo sobre “condiciones de finalización del contrato”, aunque expresen lo mismo. Una base de datos vectorial funciona con el significado y no con los caracteres.

A gran escala, comparar una consulta con millones de vectores de forma exhaustiva sería demasiado lento. Por lo tanto, las bases de datos vectoriales utilizan índices de vecino más cercano aproximados, como HNSW (gráficos jerárquicos navegables de mundo pequeño) e IVF (índice de archivo invertido). Estos sacrifican un poco la precisión en la recuperación de resultados a cambio de una gran reducción en la latencia, y ambos tipos de índices son opciones de configuración habituales en el operador vectordb.

Qué backends soportan los pipelines de docling

El proyecto incluye soporte integrado para dos backends de bases de datos vectoriales: OpenSearch y Milvus. Ambos se configuran a través del JSON del flujo sin necesidad de modificar código alguno. Una clave "provider" en la configuración del operador selecciona el backend, y todo lo demás se determina a partir de esa elección.

La arquitectura hexagonal del operador facilita la adición de otros backends. Para soportar Qdrant, pgvector, Weaviate o cualquier otro, basta con escribir una clase de adaptador y registrarla. Ni el operador ni el framework del pipeline necesitan modificarse.

Cómo funciona el operador

Dentro del pipeline de indexación, el operador vectordb se encarga del almacenamiento. Las filas que llegan a su tabla PyArrow ya están enriquecidas con estos campos:

  • el texto original del documento;
  • doc_id_hash, que asigna a cada documento un identificador fijo que permanece igual en cada ejecución;
  • una columna chunked_content, que representa al documento dividido en ventanas superpuestas;
  • una columna embeddings con un vector numérico por bloque, generado por el operador embeddings anterior en el flujo.

El operador toma esa tabla y escribe cada bloque, junto con su incrustación y metadatos, en la base de datos vectorial. En el proceso crea o valida el esquema del índice, agrupa las inserciones masivas, hace un seguimiento de qué bloques tuvieron éxito o fallaron, y elimina los bloques obsoletos de ejecuciones anteriores cuando un documento ha cambiado.

Diseño hexagonal: se puede conectar cualquier almacén

El operador no está intencionalmente vinculado a una sola base de datos. Transfiere el trabajo de backend a un adaptador que cumple con una interfaz VectorStorePort, un contrato abstracto que detalla qué debe ofrecer cada almacén vectorial, incluyendo create_index(), index_documents(), refresh_index() y delete_documents_by_ids().

Este es el patrón de arquitectura hexagonal aplicado a un operador de pipeline. La lógica sobre qué almacenar se encuentra en el operador. La cuestión de infraestructura relativa a cómo comunicarse con un backend específico está en el adaptador. El operador solo llama a la interfaz de puerto y nunca interactúa directamente con los protocolos OpenSearch o Milvus.

VectorDBOperator
      │
      └── VectorStorePort (interface / abstract contract)
              ├── OpenSearchAdapter   (ships with docling-pipelines)
              ├── MilvusAdapter       (ships with docling-pipelines)
              └── YourCustomAdapter   (implement VectorStorePort → plug in)

Para dar soporte a una base de datos que aún no está cubierta, implemente VectorStorePort y registre el adaptador en la fábrica. Después de eso, el nombre de su adaptador puede utilizarse como "provider" en un JSON de flujo. Nada más cambia, ya sea el operador, el pipeline circundante o los flujos existentes con type: vectordb.

Documentos en bloques y sin bloques

Ambos modos se manejan de forma transparente. Cuando chunked_content existe y está completo, que es el resultado del operador chunker anterior, cada bloque se indexa como un documento independiente. Su clave primaria se deriva del ID del archivo padre, del índice del bloque y del texto del bloque. Cuando la tabla contiene documentos completos sin particionamiento en bloques, cada fila se indexa como una unidad. El operador elige la ruta automáticamente y no se necesita ninguna marca.

Limpieza de bloques obsoletos

Las actualizaciones son un problema habitual con los índices fragmentados. Si un archivo se ingresa una segunda vez después de que se editó su contenido, los nuevos fragmentos ya no coinciden con los almacenados anteriormente. El operador soluciona esto buscando los IDs de los fragmentos existentes para cada documento antes de realizar la inserción, calculando la diferencia entre los conjuntos antiguos y nuevos y eliminando los obsoletos antes de escribir el lote actualizado. De este modo, el índice refleja el documento actual, sin importar cuántas veces se haya ejecutado el proceso sobre el mismo corpus.

Dimensiones vectoriales detectadas para usted

No es necesario contar las dimensiones ni codificarlas manualmente. Cuando se ejecuta el proceso, el operador lee la primera representación no nula de la tabla y toma la dimensión a partir de su longitud. El índice se crea entonces con ese tamaño, o se verifica si ya existe según ese mismo tamaño.

Un flujo completo de indexación RAG

Un pipeline completo de indexación consta aquí de cinco operadores conectados por bordes depends_on. Este ejemplo local utiliza 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"
        }
      }
    }
  ]
}

Ejecútelo desde la línea de comandos:

docling-pipelines --flow-file rag-pipeline.json

Cada archivo PDF, DOCX y de texto plano ubicado en ./documents es detectado, extraído y dividido en segmentos de 512 tokens con una superposición de 50 tokens; estas configuraciones se encuentran en el nodo chunker y pueden modificarse libremente. Los segmentos se procesan con el modelo nomic-embed-text ejecutado localmente a través de Ollama, y finalmente se escriben en un índice de OpenSearch configurado para búsquedas por similitud.

El ejemplo muestra cómo leer desde una carpeta local, pero la función de ingesta también funciona con S3, SharePoint, Google Drive, Box, OneDrive y cargadores personalizados. Solo cambia el nodo ingest_source; todos los operadores siguientes, incluido vectordb, permanecen idénticos independientemente de la fuente de los documentos.

Milvus con dos modelos de incrustación

Los equipos que desean incrustar documentos con dos modelos diferentes al mismo tiempo, como un modelo de uso general y uno específico para un dominio, pueden utilizar los operadores branching y merge. El flujo consiste en procesar los datos, extraer información, dividirlos en fragmentos, dividirlos en dos pasos de incrustación, fusionarlos y, finalmente, escribirlos en Milvus.

El adaptador de Milvus acepta varias columnas vectoriales. La salida de cada modelo se almacena en su propio campo vectorial dentro de la colección, lo que permite realizar búsquedas con ensembles en el momento de la consulta: se toman los mejores resultados de cada índice del modelo y se combinan antes de realizar el ranking.

Indexación incremental

El operador está diseñado para ejecutarse una y otra vez sobre un corpus en constante crecimiento sin tener que volver a indexar todo. El operador de ingestión también recuerda las ejecuciones anteriores y omite cualquier archivo cuyo hash y hora de modificación no hayan cambiado. En conjunto, solo los documentos nuevos y modificados pasan por la cadena de procesamiento. Se escriben sus fragmentos, se eliminan los fragmentos obsoletos de los documentos actualizados y todo lo demás permanece intacto.

En el caso de una cadena de procesamiento programada en un almacén de documentos que crece continuamente, el tiempo de ejecución varía según la cantidad de cambios y no según el tamaño total del corpus.

Su lugar en el panorama general

En un flujo RAG con pipelines de docling, el operador vectordb es el nodo de almacenamiento de vectores. Dependiendo del diseño, puede ser el nodo final o puede ir seguido de otros. Por ejemplo, un operador document_set puede guardar la tabla completa enriquecida de PyArrow en DuckDB para su análisis posterior junto con el índice de vectores.

Cada operador se comunica a través de un esquema de tabla estándar de PyArrow, por lo que vectordb es indiferente al lugar de origen de sus filas, ya sea una carpeta local, S3, SharePoint o un cargador personalizado. La portabilidad de las fuentes y del almacenamiento es una propiedad estructural impuesta por la arquitectura y no dejada a la convención. El operador se encarga de la creación de índices, escrituras masivas por lotes, múltiples columnas vectoriales, limpieza de fragmentos obsoletos y detección automática de dimensiones, todo ello controlado por el archivo de flujo, siendo el tamaño del fragmento, la superposición, el modelo de incrustación, el algoritmo de índice y la métrica de similitud elementos expuestos como configuración.

Forma parte de un ecosistema de pipelines en constante expansión, y el proyecto es de código abierto bajo IBM. Si su base de datos vectorial aún no cuenta con soporte, la interfaz del adaptador es el punto de partida.

Leer más