Обзор Vault Audit AI для Obsidian: от локального аудита заметок к семантическому поиску и RAG

Как развивался плагин Vault Audit AI для Obsidian: от локального аудита к семантическому поиску и RAG

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

Из попытки эффективно решить эту проблему вырос плагин Vault Audit AI для Obsidian. Первоначально инструмент задумывался как решение для проведение комплексного AI-аудита заметок с использованием алгоритма MapReduce. Он собирал общую структуру, находил изолированные файлы (orphan notes), формировал карты содержания (MOC) и генерировал учебные карточки (flashcards). Однако со временем стало очевидно: разового аудита постфактум недостаточно. Системе необходим постоянный семантический слой, способный мгновенно находить информацию по смыслу непосредственно в момент запроса.

В актуальной версии Vault Audit AI (1.7.0) плагин превратился в полноценную систему управления знаниями. Я детально изучил его архитектуру, внутреннее устройство семантического индекса и RAG-механику, чтобы разобраться, как локальный векторный поиск трансформирует ежедневную работу с личной базой заметок.

Парсинг и деление заметок на фрагменты: зачем нужен MarkdownChunker

Превращение всей заметки объемом в 10–15 тысяч символов в один единый вектор — крайне неэффективный подход. Если документ содержит сразу несколько тем (например, базовые настройки СУБД, векторные расширения и архитектуру RAG), итоговый вектор смыслово усредняется. В результате точечные идеи теряются в общем объеме текста.

Чтобы избежать этой проблемы, перед отправкой в модель эмбеддингов документ передается в специализированный модуль MarkdownChunker. Он бережно разбирает структуру Markdown, сохраняя иерархию заголовков и смысловую связность блоков. Для каждого полученного фрагмента (chunk) формируется расширенный набор метаданных:

• относительный путь к файлу в хранилище;
• иерархия заголовков (heading path);
• смещения строк и символов в исходном документе;
• хэш содержимого (content hash);
• уникальный стабильный идентификатор фрагмента (chunk ID).

Наличие точных метаданных позволяет поисковой системе не просто указывать на релевантный файл, а направлять пользователя к конкретному абзацу или разделу заметки.

Локальное векторное хранилище LocalVectorStore без тяжелых СУБД

На этапе проектирования часто возникает соблазн подключить внешнюю векторную СУБД — Qdrant, расширение SQLite или алгоритмы HNSW. Однако для личной базы знаний в несколько тысяч заметок это создает лишнюю сложность. На стандартных объемах персонального Obsidian-хранилища линейное сканирование (linear scan) по локальным векторам выполняется практически мгновенно.

Именно поэтому в Vault Audit AI реализован собственный модуль LocalVectorStore. Индекс хранится непосредственно внутри рабочей директории плагина в Obsidian. Пользователю не требуется устанавливать Docker, разворачивать сторонние серверы или настраивать базы данных. Достаточно включить семантические функции в настройках плагина, выбрать провайдера эмбеддингов и запустить первичную индексацию.

Автоматическая синхронизация индекса: борьба с лишними запросами через SemanticAutoSync

Ручной перерасчет индекса после каждого редактирования быстро свел бы на нет всё удобство использования. Однако прямое реагирование на каждое событие файловой системы тоже недопустимо: во время активного набора текста Obsidian генерирует десятки событий модификации файла в секунду.

Для оптимизации этого процесса был создан сервис SemanticAutoSync. Он собирает события файловой системы и применяет алгоритм задержки (debounce) с последующим схлопыванием (coalescing) операций:

• серия подряд идущих модификаций одного файла объединяется в одну операцию чтения с диска по завершении ввода;
• операции создания и последующего удаления файла взаимно аннулируют друг друга;
• переименование файла превращается в атомарную пару из удаления старого пути и добавления нового без повторного вызова API эмбеддингов.

Параллельный доступ и гонки данных: создание барьера чтений и записей

При фоновой работе синхронизации неизбежно возникают состояния гонки данных (race conditions). Например, пользователь может запустить поиск или полную пересборку индекса в тот момент, когда автосинхронизация уже записывает новые векторы.

Чтобы исключить повреждение структуры данных, семантический подмодуль оснащен координатором чтений и записей с поддержкой приоритета записи (writer-preferred read/write barrier). Поисковые операции могут выполняться параллельно несколькими потоками чтений. Однако, как только в очередь поступает запрос на эксклюзивную перезапись или полную пересборку индекса, новые операции чтения блокируются до завершения процесса записи. Это гарантирует целостность хранилища при любых действиях пользователя.

Инкрементальная индексация на уровне отдельных чанков

Если заметка состоит из десяти блоков и пользователь изменил всего один абзац, повторная генерация эмбеддингов для всего документа приведет к бесполезной трате сетевых ресурсов и API-лимитов. В Vault Audit AI реализовывана инкрементальная проверка на уровне чанков.

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

Практическое применение семантического слоя

На базе сформированного локального векторного индекса в плагине построены три ключевых инструмента поиска и навигации.

Смысловой поиск по заметкам (Semantic Search)

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

Поиск похожих материалов через Similar Notes

Инструмент позволяет найти логически связанные заметки без необходимости формулировать поисковый запрос. Для текущего документа вычисляется усредненный вектор на основе нормализованных векторов его чанков. Затем этот вектор сравнивается с векторами остальных документов базы. Все вычисления происходят исключительно над уже имеющимися в локальном индексе данными и не требуют дополнительных внешних запросов.

Выявление потенциальных дубликатов

Сравнение векторов документов позволяет выявлять заметки с очень высоким косинусным сходством (например, от 0.98 и выше). Команда поиска потенциальных дубликатов выводит список кандидатов для ручного анализа. Важно отметить, что плагин принципиально ничего не удаляет и не объединяет в автоматическом режиме, оставляя окончательное решение за пользователем.

Интеграция RAG-системы: модуль Ask your Vault

В версии Vault Audit AI 1.7.0 появился модуль Ask your Vault, реализовавший архитектуру RAG (Retrieval-Augmented Generation) поверх уже построенного семантического индекса.

Реконструкция свежего текста из Markdown

В векторном индексе хранятся только короткие превью фрагментов, которых недостаточно для формирования качественного ответа нейросетью. Чтобы гарантировать актуальность данных, перед отправкой контекста в LLM модуль RagContextBuilder заново читает исходные Markdown-файлы с диска. Фрагмент восстанавливается по стабильному идентификатору и хэшу содержимого. Если файл успел измениться и хэши не совпали, устаревший блок отбрасывается.

Разнообразие источников и жесткий лимит контекста

Наивная передача первых двадцати найденных чанков часто приводит к тому, что весь контекст заполняется кусками одного длинного документа. Модуль сборки контекста соблюдает строгие лимиты диверсификации:

• не более 2 фрагментов от одного документа;
• максимум 6 различных документов в итоговом контексте;
• суммарный объем контекста ограничен 12 000 символов Unicode.

Изоляция контекста в Frozen Context

Генерация ответа нейросетью с потоковой передачей (streaming) может занимать длительное время. Чтобы не удерживать блокировку векторного хранилища на весь период ответа, сформированный контекст «замораживается» в оперативной памяти (Frozen Context). В это время фоновая автосинхронизация или очистка индекса могут продолжать работу, не мешая текущей сесси общения с нейросетью.

Защита от фантомных ссылок и инъекций в промптах

Языковые модели склонны выдумывать несуществующие источники при формировании сносок. В Vault Audit AI сопоставление ссылок на документы полностью изолировано от нейросети: плагин сам генерирует идентификаторы источников и проверяет соответствие итоговых сносок реальным путям к файлам.

Кроме того, текст извлекаемых заметок явным образом помечается в системном промпте как недоверенные данные (untrusted data). Это предотвращает атаки класса Prompt Injection, когда находящиеся внутри заметки текстовые инструкции пытаются перехватить управление языковой моделью.

Что происходит, если в базе нет нужного ответа

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

Рендеринг разметки Markdown

При потоковой генерации текста используется быстрый вывод plain-text, чтобы не перегружать интерфейс Obsidian частой перерисовкой DOM. По завершении ответа итоговый текст однократно проходит через стандартный MarkdownRenderer Obsidian, формируя аккуратное форматирование со списками и выделениями.

Две разные системы индексации: Audit Index и Semantic Index

В процессе анализа Vault Audit AI важно разделять два независимых индекса, выполняющих разные задачи:

1. Audit Index (файл `note-index.json`): хранит выводы прошлых LLM-анализов (резюме, ключевые тезисы, теги, оценки качества и тематические кластеры). Его главная задача — исключить повторную обработку неизменившихся файлов при проведении аудита базы.
2. Semantic Index: содержит числовые векторы и метаданные чанков. Используется для семантического поиска, поиска похожих заметок, обнаружения дубликатов и работы RAG.

Такое разделение полностью оправдано: кеш выводов нейросети и поисковая векторная память имеют разный жизненный цикл, стоимость обновления и сценарии использования.

Дополнительные возможности Vault Audit AI

Помимо семантического слоя, в плагине сохраняется весь ранее разработанный инструментарий для работы с заметочными массивами.

Структурная аналитика и Deep Audit

Плагин умеет строить наглядные дашборды со статистикой по папкам, тегам, связности документов и сиротским заметкам с возможностью экспорта результатов на холст Canvas. В режиме Deep Audit нейросеть формирует глубокие отчеты о структуре хранилища, выявляет смысловые проблемы и автоматически собирает карты содержания (MOC).

Инструменты работы с текстом

В плагине доступны функцииумного дополнения текста, генерации запросов Dataview, автоматического разделения монолитных документов на атомарные заметки, а также генерации учебных карточек (flashcards). Пакетный режим (batch processing) позволяет массово применять произвольные AI-преобразования к выбранным группам файлов.

Гибкая настройка провайдеров и защита данных

Пользователь может гибко комбинировать сервисы: использовать локальную модель через Ollama для генерации эмбеддингов, а ответы на вопросы получать через сторонние API (OpenRouter, OpenAI, Groq). Сами векторные индексы и текстовые базы всегда остаются строго на локальном устройстве.

Надежность системы: 698 автотестов и реальные ограничения

Стабильность работы всех компонентов обеспечивается тестовым покрытием из 698 автотестов. Автор активно использует подход мутационного тестирования, проверяя поведение системы при искусственном введении ошибок в логику сверки хэшей и очереди записей.

Среди текущих ограничений архитектуры стоит отметить:

• режим диалога Ask your Vault пока является разовым (one-shot) и не хранит историю сообщений;
• индексации подлежат только файлы разметки Markdown (PDF и медиафайлы не учитываются);
• поиск использует линейное сканирование, ориентированное на базы малого и среднего объема.

Перспективы развития: экосистема Companion и протокол MCP

Следующим шагом в развитии проекта станет создание внешнего сервиса Vault Audit AI Companion, работающего на базе Node.js. Он будет выполнять роль сервера по протоколу Model Context Protocol (MCP), позволяя сторонним AI-клиентам (Claude Desktop, Cursor, Codex) безопасно обращаться к сформированному знаниевому слою Obsidian в режиме чтения.

Подводя итог, можно сказать, что Vault Audit AI эволюционировал из набора простых AI-команд в зрелую локальную инфраструктуру работы со знаниями. Семантический поиск и RAG-механики делают поиск информации в Obsidian максимально естественным и приближенным к работе человеческой памяти.

Источник: habr.com