Віртуальна файлова система на основі MongoDB для LangChain Deep Agents

Очікування від штучних інтелектуальних агентів вийшли за межі простого відповідання на запитання. Від них вимагають виконувати цілі завдання: розробляти багатоетапні плани, аналізувати вихідні файли, створювати тимчасові результати та делегувати частини завдання іншим агентам, що дозволяє скоротити час виконання з днів до годин. Така швидкість можлива лише тоді, коли агент може впевнено працювати зі своєю файловою системою, шукати, читати та оновлювати файли під час роботи. Віртуальна файлова система 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 через пакет extras, а додаток може безпосередньо використовувати будь-яку реалізацію ембеддингів, сумісну з 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 сховищу об’єктів, агенти, які запускаються пізніше, можуть шукати поточний контент без необхідності створення індексу щоразу під час виконання. Це допомагає асистентам з регламентами, системам моніторингу дотримання правил та політик, дослідницьким асистентам працювати з постійно оновлюваними даними, агентам підтримки — користуватися документацією щодо продукту та усунення проблем, а також асистентам партнерів працювати з спільними документами реалізації.

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

Обмеження у продакшені та точки розширення

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

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

Основною ідеєю є розділення функцій. Агенти бачать єдину просту віртуальну файлову систему, додатки зберігають великі та різноманітні документи у об’єктному сховищі як джерело істини для даних, Atlas перетворює їх на шар для пошуку з метаданими, повнотекстовим пошуком, векторним та гібридним ранжуванням, а шар синхронізації забезпечує відповідність знахідок актуальному корпусу даних.

Пов’язана література

• Файлова система вашого агента — це рішення: пояснення бекендів Deep Agents — Як бекенди LangChain Deep Agents вирішують, що залишити: п’ять вбудованих рішень, механізм маршрутизації CompositeBackend, проблема простору імен у багатокористувацьких сховищах та шаблони сандбоксів.
• LangChain, LangGraph чи Deep Agents: який варіант обрати — Три фреймворки агентів, один приклад роботи. Дізнайтеся, де має сенс використовувати простий цикл LangChain, чіткий робочий процес LangGraph та простір планування Deep Agents.