Как docling-pipelines хранит векторы документов для RAG с использованием OpenSearch или Milvus
Слой векторной базы данных в IBM docling-pipelines для RAG: адаптеры OpenSearch и Milvus с возможностью подключения, очистка устаревших данных, автоматическое определение размерностей, обработка данных в формате JSON.
Источники: The Indexing Layer: How docling-pipelines Prepares Your Documents for RAG
Любое современное приложение, которое отвечает на вопросы о частных документах, опирается на одну и ту же технологию — генерацию с использованием поиска, или RAG. Например, кто-то может спросить, какие условия продления действуют для контрактов прошлого года, или какие лимиты ответственности предусмотрены в соглашениях с поставщиками. Прежде чем языковая модель сможет ответить, необходимо найти соответствующие фрагменты среди тысяч файлов и передать их в пригодном для использования формате. Этой функцией занимается векторная база данных, а оператор vectordb в проекте docling-pipelines от IBM с открытым исходным кодом выполняет именно эту роль.
Ниже приведены обоснования использования векторных баз данных, способ, которым RAG от них зависит, а также то, как docling-pipelines превращает часть системы RAG, связанную с хранением данных, в декларативную структуру: её можно настроить с помощью JSON-файла и при необходимости расширить с помощью пользовательских операторов.
RAG и роль векторной базы данных
С использованием технологии RAG языковая модель не отвечает исключительно на основе собственной памяти. Система сначала извлекает наиболее релевантные фрагменты из коллекции документов и включает их в запрос в качестве контекста. Затем модель формирует ответ, основываясь на этих фрагментах, а не на статистических закономерностях, полученных в процессе обучения.
Векторная база данных обеспечивает возможность выполнения этого шага извлечения. На практике это работает следующим образом.
Во время создания индекса каждый фрагмент коллекции преобразуется в числовой вектор — его эмбеддинг — с помощью модели, которая научилась располагать тексты с похожим значением рядом друг от друга в высокомерноменной пространстве. Эти векторы хранятся рядом с исходным текстом.
В момент запроса вопрос пользователя обрабатывается с помощью того же модели. База данных выполняет поиск ближайших соседей и возвращает те фрагменты, векторы которых наиболее близки к вектору вопроса. Эти фрагменты имеют отношение к смыслу вопроса даже в том случае, если у них нет общих ключевых слов. Модель использует их в качестве контекста и может сформулировать обоснованный ответ.
Почему обычная база данных не справляется с этой задачей
Реляционная или документная база данных может находить совпадения ключевых слов, но не смысл. Поиск по запросу «терминационные положения» не приведет к нахождению абзаца о «условиях прекращения контракта», хотя они означают одно и то же. Векторная база данных работает с смыслом, а не с символами.
При работе в масштабах полное сравнение запроса с миллионами векторов займет слишком много времени. Поэтому векторные базы данных используют приближенные индексы ближайших соседей, такие как HNSW (иерархические навигируемые графы малого мира) и IVF (обратный файловый индекс). В обмен на небольшое снижение точности они обеспечивают значительное сокращение времени обработки, причем оба типа индексов являются стандартными опциями конфигурации в операторе vectordb.
Какие бэкенды поддерживаются docling-pipelines
Проект поставляется с встроенной поддержкой двух бэкендов векторных баз данных — OpenSearch и Milvus. Оба настраиваются через JSON-файл потока без необходимости изменять код. Ключ "provider" в конфигурации оператора выбирает бэкенд, а все остальное определяется на его основе.
Шестиугольная архитектура оператора позволяет легко добавлять новые бэкенды. Чтобы поддержать Qdrant, pgvector, Weaviate или любые другие сервисы, достаточно написать один класс-адаптер и зарегистрировать его. Ни оператор, ни фреймворк обработки потоков не требуют изменений.
Как работает оператор
В рамках пайплайна индексации оператор vectordb отвечает за хранение данных. Строки, поступающие в его таблицу PyArrow, уже содержат следующие поля:
- исходный текст документа;
doc_id_hash— фиксированный идентификатор каждого документа, одинаковый при каждой обработке;- столбец
chunked_content— документ, разделенный на перекрывающиеся фрагменты; - столбец
embeddings— один числовой вектор на каждый фрагмент, генерируемый операторомembeddingsна предыдущем этапе.
Оператор берет эту таблицу и записывает каждый фрагмент вместе с его встроенными данными и метаданными в векторную базу данных. При этом он создает или проверяет схему индекса, группирует массовые вставки, отслеживает, какие фрагменты были успешно вставлены, а какие — нет, а также удаляет устаревшие фрагменты предыдущих операций, когда документ изменился.
Шестиугольный дизайн: возможность использования любой хранилища
Оператор намеренно не привязан к одной конкретной базе данных. Он передает работу с бэкендом адаптеру, который реализует интерфейс VectorStorePort — абстрактный контракт, определяющий функции каждого векторного хранилища, включая create_index(), index_documents(), refresh_index() и delete_documents_by_ids().
Это шаблон гексагональной архитектуры, применяемый к оператору конвейера. Логика, определяющая, что сохранять, находится в самом операторе. Вопросы инфраструктуры, связанные с способом взаимодействия с конкретным бэкендом, решаются с помощью адаптера. Оператор лишь вызывает интерфейс порта и никогда не взаимодействует напрямую с протоколами OpenSearch или Milvus.
VectorDBOperator
│
└── VectorStorePort (interface / abstract contract)
├── OpenSearchAdapter (ships with docling-pipelines)
├── MilvusAdapter (ships with docling-pipelines)
└── YourCustomAdapter (implement VectorStorePort → plug in)
Чтобы поддержать базу данных, которая пока не обслуживается, реализуйте VectorStorePort и зарегистрируйте адаптер в фабрике. После этого имя вашего адаптера можно использовать в качестве "provider" в JSON-описании потока. Ничего другого не меняется — ни оператор, ни окружающая цепочка обработки, ни существующие потоки с type: vectordb.
Документы с разбиением на чанки и без него
Оба режима обрабатываются автоматически. Когда существует и заполнен параметр chunked_content, который является результатом работы оператора chunker, каждый чанк индексируется как отдельный документ. Его первичный ключ формируется на основе ID родительского файла, индекса чанка и текста чанка. Когда в таблице хранятся целые документы без разбиения на чанки, каждая строка индексируется как единое целое. Оператор автоматически выбирает путь, и для этого не требуется никаких флагов.
Удаление устаревших чанков
Обновления представляют собой хорошо известную проблему при использовании индексов с чанками. Если файл загружается второй раз после изменения его содержимого, новые чанки больше не совпадают с теми, что были сохранены ранее. Система справляется с этим, сначала находя идентификаторы существующих чанков для каждого документа перед их добавлением, вычисляя разницу между старыми и новыми наборами и удаляя устаревшие чанки перед записью свежей партии данных. Таким образом индекс всегда отражает текущий состояние документа, независимо от того, сколько раз процесс обработки проходил по одному и тому же корпусу.
Обнаруженные размеры векторов
Вам не нужно считать размеры и вводить их вручную. При запуске процесса система считывает первое ненулевое значение в таблице эмбеддингов и берет размер из его длины. Индекс создается с этим размером, либо проверяется по нему, если он уже существует.
Полный процесс индексации RAG
Полная цепочка индексации здесь состоит из пяти операторов, соединённых рёбрами depends_on. В этом локальном примере используется 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"
}
}
}
]
}
Запустите его из командной строки:
docling-pipelines --flow-file rag-pipeline.json
Все файлы PDF, DOCX и обычного текста, находящиеся в папке ./documents, обнаруживаются, извлекаются и делятся на фрагменты по 512 токенов с перекрытием в 50 токенов; эти настройки задаются в узле chunker и могут быть свободно изменены. Фрагменты обрабатываются с использованием локально запущенной модели nomic-embed-text через Ollama, после чего записываются в индекс OpenSearch, настроенный для поиска по сходству.
Пример работает с локальной папкой, но процесс загрузки документов поддерживает также S3, SharePoint, Google Drive, Box, OneDrive и пользовательские механизмы загрузки. Изменяется только узел ingest_source; все последующие операторы, включая vectordb, остаются прежними независимо от источника документов.
Milvus с двумя моделями вкладки
Команды, которые хотят одновременно встраивать документы с двумя разными моделями — например, универсальной и специализированной по определённой области, — могут использовать операторы branching и merge. Процесс включает захват данных, извлечение информации, разбиение на части, разделение на два этапа встраивания, объединение результатов и их запись в Milvus.
Адаптер Milvus поддерживает несколько векторных столбцов. Результаты работы каждой модели сохраняются в отдельном векторном поле коллекции, что позволяет использовать метод ансамбля при поиске: берутся лучшие результаты из индексов каждой модели и объединяются перед формированием рейтинга.
Инкрементное индексирование
Этот оператор разработан для многократной обработки постоянно расширяющегося корпуса документов без необходимости повторной индексации всего контента. Оператор загрузки также запоминает предыдущие запуски и пропускает те файлы, у которых хэш и время изменения остались прежними. Таким образом, через всю систему проходят только новые и изменённые документы: их фрагменты записываются, устаревшие фрагменты обновлённых документов удаляются, а всё остальное остаётся нетронутым.
Для запланированной обработки постоянно растущего хранилища документов время выполнения операций зависит от объёма изменений, а не от общего размера корпуса.
Место в общей картине
В потоке RAG с использованием docling-pipelines оператор vectordb является узлом хранения векторов. В зависимости от конфигурации он может быть последним узлом или за ним могут следовать другие узлы. Например, оператор document_set может сохранять полную дополненную таблицу PyArrow в DuckDB для дальнейшего анализа вместе с векторным индексом.
Каждый оператор взаимодействует через стандартную схему таблицы PyArrow, поэтому vectordb не зависит от того, откуда поступают его строки — из локальной папки, S3, SharePoint или с помощью пользовательского загрузчика. Портативность источников и мест хранения является структурным свойством, обеспечиваемым архитектурой, а не зависящим от устоявшихся правил. Оператор обеспечивает создание индексов, пакетную запись больших объемов данных, поддержку нескольких векторных столбцов, очистку устаревших блоков и автоматическое обнаружение размерностей; всё это управляется файлом потока, причем размер блоков, степень их перекрытия, модель встраивания, алгоритм индексации и метрика сходства задаются в настройках.
Это лишь одна часть развивающейся экосистемы пайплайнов, причем проект является open source под управлением IBM. Если ваша векторная база данных пока не поддерживается, начать следует с интерфейса адаптера.