Виртуальная файловая система на основе MongoDB для глубоких агентов LangChain

Ожидания от ИИ-агентов вышли за рамки простого ответа на вопросы. От них теперь требуется выполнять целые задачи: составлять многоэтапные планы, изучать исходные файлы, создавать промежуточные результаты и передавать части задач другим агентам, что превращает ранее занимавшие дни процессы в несколько часов. Такая скорость возможна только тогда, когда агент может уверенно работать с файловой системой, выполняя поиск, чтение и обновление файлов по мере необходимости. Виртуальная файловая система MongoDB (VFS) для LangChain Deep Agents решает эту проблему. Она связывает знакомый интерфейс файловой системы с MongoDB Atlas и подключенным к нему хранилищем объектов, таким как контейнер S3, что позволяет агентам использовать поисковую рабочую среду, сохраняющуюся дольше сессий, развертываний и подагентов. Разработчики Deep Agents могут рассматривать Atlas как платформу для хранения данных своих агентов, где всегда доступны полнотекстовый и векторный поиск.

В приведённых ниже разделах объясняются эти два концепта, показано, как работает бэкенд MongoDB внутри приложения-агента, и указано, в каких случаях этот подход подходит для корпоративных систем.

Глубокие агенты и их инструменты файловой системы

Глубокие агенты представляют собой фреймворк, построенный на основе LangChain и LangGraph, предназначенный для решения сложных, многоэтапных задач. Встроены функции планирования, работы с подагентами и инструменты в стиле файловой системы, что позволяет агенту разбивать крупные задачи на мелкие действия вместо того, чтобы помещать всё в одно окно контекста. Встроенные операции включают:

• ls — выводит список каталогов, чтобы агент мог увидеть их структуру
• glob — находит файлы по шаблону пути
• grep — ищет информацию внутри содержимого файлов
• read — возвращает содержимое файла
• write и edit — создают или изменяют файлы

upload_files и download_files обрабатывают массовую передачу файлов

Эти инструменты работают на основе контракта с бэкендом. Агенту не нужно знать, находятся ли файлы на локальном диске, в хранилище LangGraph, в облачном хранилище объектов или в каком-либо другом слое сохранения данных. Он обращается к одинаковому интерфейсу файловой системы, а данные предоставляет настроенный бэкенд.

Что добавляет виртуальная файловая система

Виртуальная файловая система представляет данные в виде логических путей, скрывая место их физического хранения. Агент может видеть такие каталоги, как docs/, reports/ или projects/customer-a/, хотя реальные данные хранятся в облачном хранилище объектов, а данные, доступные для поиска, — в базе данных.

Навигация по файловой системе осуществляется поэтапно, что идеально подходит для агентов. Помимо запроса на обработку всего корпуса данных, агент перечисляет каталоги, сужает поиск по шаблонам имён файлов, ищет нужный концепт, открывает соответствующий файл и записывает полученные результаты в виде нового объекта. Каждый шаг позволяет брать только необходимое, благодаря чему агент остаётся в рамках установленных ограничений по контексту и тратит меньше ресурсов. В этом смысле виртуальная файловая система является инструментом для управления контекстом во время работы агентов, а не просто слоем хранения.

Пакет и способ его работы

Пакет langchain-mongodb-deepagents-vfs реализует протокол BackendProtocol Deep Agents как замену существующему решению. Корпус данных, хранящийся в объектном хранилище, предстаёт перед агентом в виде файловой системы, причём каждый запрос направляется в ту систему, которая лучше всего с ним справляется:

• Операции, ориентированные на поиск (grep, glob, ls), выполняются непосредственно в MongoDB Atlas.
• Операции с байтами файлов (read, write, edit, upload_files, download_files) направляются прямо в хранилище объектов.
• Фоновый слой синхронизации поддерживает соответствие между представлением данных для поиска и содержимым хранилища объектов.

Это обеспечивает чёткое разделение источника истинных данных и индекса поиска. Хранилище объектов хранит оригинальные документы, а Atlas содержит данные, пригодные для поиска, включая эмбеддинги и метаданные путей, которые позволяют находить нужные элементы в корпусе данных.

Может возникнуть вопрос: почему поиск должен находиться в отдельной системе, а не на платформе, совместимой с S3, которая объединяет текстовый, векторный и гибридный поиск над одними и теми же данными? Такое разделение преднамеренно. Хранилище объектов отлично справляется с хранением долговечных, недорогих файлов, но оно не было создано для одновременного ведения актуальных индексов, ранжирования гибридных запросов и обслуживания запросов к структурированным метаданным с низкой задержкой. Atlas — это операционная база данных, в которой поиск, векторный поиск и гибридное ранжирование с самого начала являются индексируемыми функциями. Поэтому механизм поиска работает с программным обеспечением, разработанным специально для этой цели, в то время как хранилище объектов продолжает использовать свои собственные преимущества.

Гибридный поиск за кулисами grep

За функционалом grep стоит сочетание инструментов MongoDB Search и MongoDB Vector Search. Поиск по полному тексту эффективен для точных терминов, идентификаторов, имен файлов и редких строк, в то время как векторный поиск подходит для парафраз и вопросов на естественном языке. Сочетание этих инструментов позволяет агенту искать такие литеральные элементы, как MAX_RETRIES, или спрашивать, где настроены попытки повтора, всё это через один интерфейс.

Два списка результатов объединяются на этапе агрегации $rankFusion в MongoDB. Поскольку ранжирование происходит непосредственно в базе данных, не требуется дополнительный инструмент ранжирования с клиентской стороны, что исключает необходимость дополнительных запросов к серверу. Здесь также существует баланс между преимуществами и недостатками. На платформах, совместимых с S3, для получения полнотекстового, векторного и гибридного ранжирования обычно требуется использование нескольких специализированных систем: движка для обработки текста, векторной базы данных для хранения векторных представлений и слоя ранжирования для их объединения, причем каждая из этих систем имеет собственную систему индексации, отвечающую за отслеживание исходных данных. В Atlas один движок обеспечивает все три типа ранжирования, а $rankFusion объединяет их в один встроенный запрос.

Чанкирование, форматы и векторные представления

Функция разбиения на части учитывает структуру токенов. Поддерживаемыми форматами входных данных являются обычный текст, Markdown, PDF, DOCX, XLSX, XLS, PPTX и PPT. Каждая часть сохраняет метаданные о положении, а именно путь к исходному файлу, номер страницы, смещения символов и информацию о строках, что позволяет получать результаты в формате, ожидаемом системами типа Deep Agents, ориентированными на строки.

По умолчанию используются модели эмбеддингов Amazon Bedrock; также доступна опция OpenAI через дополнения к пакету, причем приложение может напрямую использовать любую реализацию эмбеддингов, совместимую с LangChain. Типичная конфигурация выглядит следующим образом:

from deepagents import create_deep_agent
from langchain_mongodb_deepagents_vfs import MongoFilesystemBackend

backend = MongoFilesystemBackend(
    s3_bucket_name="acme-docs",
    mongodb_connection_string="mongodb+srv://<user>:<password>@<cluster>/",
)

agent = create_deep_agent(
    tools=[],
    instructions="You are a research assistant over the ACME documents corpus.",
    backend=backend,
)

После этого агент использует обычные инструменты файловой системы; в его цикле принятия решений не применяются специальные инструменты MongoDB или S3.

Архитектура с двумя уровнями

Представьте систему как два уровня. Хранилище объектов — это уровень данных, где хранятся байты файлов, а MongoDB Atlas — уровень управления и поиска, отвечающий за метаданные, фрагменты данных и индексы поиска.

На рисунке показано, как бэкенд передает байты файлов через хранилище объектов, а операции поиска — через Atlas.

После создания объекта на бэкенде инициализация продолжается в фоновом режиме. Создание индексов, первая синхронизация и запуск механизма мониторинга выполняются в фоновом потоке. Операции с файлами выполняются немедленно, тогда как операции поиска ждут завершения первой синхронизации. Процесс загрузки данных происходит следующим образом:

1. Список объектов в настроенном бакете S3 и указанном префиксе.
2. Скачайте каждый подходящий объект.
3. Извлеките текст с помощью парсера для данного формата.
4. Разделите текст на фрагменты, содержащие метаданные о позиции.
5. Создайте эмбеддинги.
6. Запишите фрагменты и метаданные в Atlas.
7. Настроите или проверьте индексы поиска и векторного поиска.

Каждый фрагмент состоит из 512 токенов с перекрытием в 64 токена. ETags обеспечивают идемпотентность первоначальной синхронизации и обработки данных, поэтому неизменные объекты пропускаются и не скачиваются, а также не преобразуются в эмбеддинги повторно.

Вот что делает каждый вызов. Команда ls запрашивает у Atlas метаданные путей и группирует их в записи каталогов. Команда glob использует стандартные правила шаблонов путей для поиска соответствующих файлов. Команда grep заставляет Atlas сочетать полнотекстовый и векторный поиск внутри корпуса данных и возвращать результаты в порядке ранжирования. Команда read загружает текущие данные непосредственно из хранилища объектов, а не из индекса, и это имеет значение, поскольку результаты поиска предназначены для открытия информации, тогда как операции чтения предназначены для получения оригинальных документов.

Существуют два режима отслеживания. Отслеживание с опросами происходит путем периодической проверки хранилища объектов и не требует дополнительной инфраструктуры событий AWS. Отслеживание через SQS обрабатывает уведомления о событиях S3 через Amazon SQS и подходит для синхронизации в производственной среде с низкой задержкой.

Временная согласованность при поиске

Поиск преднамеренно работает с конечной согласованностью. Запись сначала успешно сохраняется в S3, затем монитор обнаруживает изменения, снова разбивает объект на части и вставляет его, а также обновляет индексы. Поэтому чтение сразу отображает состояние S3, тогда как команды grep, glob и ls могут отставать до завершения синхронизации и индексации.

Для совместной работы существуют несколько рекомендаций: читайте данные напрямую, когда они активно используются и доступны всем; для оптимистичной конкурентности при работе с общими файлами используйте команду edit; а для поиска информации после стабилизации корпуса данных применяйте поиск. Предоставление каждому агенту собственного пространства имен вывода, например shared/outputs//, дополнительно снижает конфликты между параллельными процессами.

Где применим этот подход

Исследование кода. Вместо того чтобы получать огромный набор кода, агент для программирования может пошагово просматривать крупный репозиторий: просматривать его структуру, находить файлы с помощью glob, выполнять гибкий поиск по концепции или идентификатору с использованием grep, читать конкретный файл и вносить изменения с защитой через ETag. Типичные сценарии применения — ознакомление с репозиторием, расследование инцидентов, анализ зависимостей и конфигурации, поиск тестов для целенаправленных исправлений и генерация документации на основе кода.

Корпуса документов. Политики, контракты, процедуры, руководства, документация к продуктам и файлы клиентов часто накапливаются в системах хранения объектов, причем бэкенд предоставляет агенту способ доступа к ним, аналогичный файловой системе. Агент, занимающийся документами, может искать политику возврата средств для корпоративных клиентов, находить фрагменты текста, сформулированные иначе, открывать исходные файлы PDF или DOCX и составлять краткое резюме с ссылками на другие пути. Это подходит для генерации с усилением с помощью поиска, когда требуется навигация, а не просто один поиск.

Команды из нескольких агентов. Координатор может поручать специализированные задачи подагентам-специалистам в рамках одного общего корпуса данных. Агент по безопасности ищет рискованные шаблоны кода, агент по документации собирает инструкции по развертыванию и ссылки на конфигурации, агент по тестированию находит соответствующие файлы для тестирования и пишет записи об охвате тестирования, а агент по синтезу читает всё это и составляет отчет. Все они используют один пространство имён, причем Atlas выполняет функцию слоя обнаружения.

Хранилища динамических документов. Корпоративный контент постоянно меняется: поступают отчеты, изменяются правила, пересматриваются операционные документы. Поскольку механизм мониторинга поддерживает согласованность Atlas с хранилищем объектов, агенты, запущенные позже, могут искать актуальный контент без необходимости каждый раз пересоздавать индекс. Это помогает ассистентам по руководствам, отвечающим за соблюдение правил, ассистентам по исследованиям работать с постоянно обновляемыми данными, агентам поддержки — использовать документы по продукту и устранению неполадок, а ассистентам партнеров — работать с совместными инструментами реализации.

Долговечные рабочие пространства. Глубокие агенты могут сохранять планы, заметки, краткие выводы и окончательные результаты в виде файлов. Хранение их в хранилище объектов и индексация в Atlas позволяет создавать рабочие пространства, которые сохраняются после перезагрузок и могут быть просмотрены людьми или другими агентами.

Ограничения в производственной среде и точки расширения

Для промышленного использования необходимо обеспечение контроля доступа, изоляции тенантов, соблюдения правил размещения данных, хранения и аудита, которые должны реализовываться приложением, конфигурацией хранилища и моделью метаданных. Сам пакет отвечает за соблюдение условий файловой системы Deep Agents, а также за маршрутизацию данных от хранилища объектов к системе поиска Atlas.

Его можно дополнить: добавлением других хранилищ объектов, таких как Azure Blob Storage или Google Cloud Storage, большим количеством поставщиков встраивания и настраиваемых стратегий, дополнительными парсерами документов и ускоренной обработкой данных, более надежными механизмами мониторинга с возможностью восполнения данных и обновления информации, улучшением качества поиска, фильтрации, ранжирования и работы с метаданными, а также более полными примерами, тест-данными и рекомендациями по развертыванию. Хорошим правилом является размещение всего, что связано непосредственно с хранением, за интерфейсом хранилища объектов, чтобы механизмы разбиения данных, встраивания, синхронизации и маршрутизации поиска обрабатывали только пути, байты, метаданные и результаты поиска, а не API конкретного поставщика услуг.

Основная идея — разделение ответственностей. Агенты видят единую простую виртуальную файловую систему; приложения хранят крупные и разнообразные документы в объектном хранилище как источник истинных данных, Atlas преобразует их в поисковый слой с метаданными, полнотекстовым поиском, векторным и гибридным ранжированием, а слой синхронизации обеспечивает соответствие найденных данных актуальному корпусу.