Любая база знаний поначалу выглядит простой. Пишешь заметки, складываешь документы, ищешь по ключевым словам. Работает — до тех пор, пока не перестаёт. Когда документов пять тысяч на двух языках, поиск по ключевым словам перестаёт находить то, что ты точно знаешь — там есть. Хуже того — находит то, что совпадает лексически, но полностью мимо по смыслу.
Это та проблема, которую решает Scrutator.
Что такое Scrutator
Название из латыни: scrutator — «тот, кто тщательно исследует». Scrutator — это фундаментальный движок поиска, ретривинга и извлечения смыслов для экосистемы Arcanada. Он обеспечивает единый поиск по всем источникам знаний: вики, документация проектов, память агентов, переписки.
Это не обёртка над векторной базой. Это полный pipeline ретривинга: чанкинг, эмбеддинг, индексация, гибридный поиск, ранжирование и модуль Сновидений, который периодически реорганизует и укрепляет связи в базе знаний.
Scrutator — открытый проект, лицензия MIT. Никаких секретов, никаких скрытых соусов — только добротная инженерия, которую каждый может изучить, форкнуть и улучшить.
Архитектура
Система состоит из пяти основных слоёв, все работают в production:
- Chunking Engine — Адаптивное семантическое разбиение документов с четырьмя стратегиями: markdown-заголовки, границы кода, скользящее окно и single-mode для коротких документов. Чанкер уважает структуру документа, а не тупо режет по лимиту токенов. Иерархия «родитель-потомок» сохраняет контекст. Лимит: 1 МБ на документ, ноль внешних зависимостей.
- Embedding Server — Модель BAAI/bge-m3, генерирующая три типа векторов одновременно: dense (1024-мерные), sparse (лексические веса) и ColBERT (мультивектор на уровне токенов). Три воркера, fp16-квантизация, работает на своём железе без внешних API.
- Hybrid Search — Трёхсторонний ретривинг: плотное векторное сходство, разреженное лексическое совпадение и полнотекстовый поиск PostgreSQL. Результаты объединяются через Reciprocal Rank Fusion (RRF, k=60). Три сигнала ловят то, что один метод пропустит.
- Storage — PostgreSQL 16 с pgvector 0.8.2 (HNSW-индексы, m=16, ef_construction=64) для векторов, tsvector с dual-language generated columns для полнотекстового поиска (русский + английский). Шесть таблиц, 22 индекса. Одна база, без внешних зависимостей.
- Dreaming — Периодический процесс реорганизации базы знаний: построение перекрёстных ссылок, усиление семантических связей, обнаружение противоречий, удаление избыточности. Интегрирован с Agent Dreamer для автономных циклов обслуживания знаний.
Что работает в Production
Все пять слоёв задеплоены и работают на нашей инфраструктуре (доступ только через Tailscale).
Embedding Server (v2.1)
Использует BAAI/bge-m3 через BGEM3FlagModel из FlagEmbedding. Пять эндпоинтов:
POST /v1/embeddings— dense-векторы (OpenAI-compatible)POST /v1/embeddings/sparse— sparse лексические весаPOST /v1/embeddings/colbert— ColBERT мультивекторыPOST /v1/embeddings/hybrid— все три типа за один вызовGET /health— статус сервера с потреблением RAM и Prometheus-метриками
Три воркера, fp16-квантизация, только CPU (GPU не нужен). Кросс-лингвальное сходство: 0.887 между русским и английским переводами одного текста — на 45% выше ближайшего конкурента по нашим бенчмаркам.
Chunking Engine
Четыре стратегии разбиения: markdown_headers для структурированных документов, code_boundaries для исходного кода, sliding_window для плоского текста и single для коротких документов. Автодетекция языка (русский и английский). Дедупликация при загрузке через ON CONFLICT (source_path, chunk_index) DO UPDATE.
Hybrid Search Pipeline
Ядро ретривинга. Трёхсторонний поиск: dense cosine similarity по pgvector HNSW-индексам, sparse лексическое совпадение и полнотекстовый поиск PostgreSQL с dual-language tsvector-колонками. Результаты объединяются через RRF (k=60).
Модуль Сновидений
Семантический анализ всей базы знаний: 1 148 чанков проиндексировано, 20 семантических дубликатов обнаружено, 50 перекрёстных ссылок построено, 50 чанков-сирот найдено. Анализ завершается за 5.5 секунд. Модуль интегрирован с Agent Dreamer для автономных циклов сновидений — периодическое обслуживание знаний без участия человека.
Memory Layer
Интеграция с LTM (Long Term Memory) даёт AI-агентам постоянную память, опирающуюся на ретривинг Scrutator. Маппинг чанков на исходные документы позволяет модулю Сновидений записывать найденные связи обратно в источники.
Бенчмарки
Живые замеры в production (медиана по 20 итерациям на arcana-db):
| Метрика | Значение |
|---|---|
| 2-way поиск (dense + FTS), p50 | 383 мс |
| 2-way поиск, p95 | 399 мс |
| 3-way поиск (dense + sparse + FTS), p50 | 749 мс |
| 3-way поиск, p95 | 768 мс |
| Embedding API round-trip | ~350 мс |
| Запрос к БД | <50 мс |
| Прогрев API | 238 мс |
| Анализ сновидений (1 148 чанков) | 5.5 с |
3-way поиск добавляет ~366 мс к 2-way из-за дополнительного round-trip для sparse-эмбеддинга. Основная стоимость — всегда вызов Embedding API, а не запрос к базе данных.
Тестирование и проблемы, которые мы решили
В проекте 174 автоматических теста по всем компонентам — юнит, интеграционные, API и тесты на реальных файлах. Ноль регрессий на протяжении всех этапов сборки. Каждый компонент тестировался на реальных документах (Python-код, вики-страницы, workflow-файлы), а не только на синтетических данных.
Проблемы, с которыми мы столкнулись
Сюрприз с RAM. Изначальный план предсказывал 450 МБ для Embedding Server с fp16-квантизацией. Реальное потребление: 2 400 МБ на воркер. С тремя воркерами — 6.9 ГБ суммарно. BGE-M3 подгружает дополнительные компоненты (sparse_linear, colbert_linear), которые не учитываются в базовом footprint dense-модели. Задокументировали, скорректировали спеки сервера и двинулись дальше.
Поломка transformers 5.x. Рутинное обновление зависимости transformers 5.x сломало пайплайн эмбеддингов — функция is_torch_fx_available была удалена в апстриме. Решение: зафиксировать transformers>=4.45,<5.0 до стабилизации экосистемы.
Путаница deploy vs. install. Первый деплой на production упал с ModuleNotFoundError: No module named 'scrutator'. План деплоя использовал pip install -r requirements.txt, но проект собирается через pyproject.toml. Решение: pip install -e . — 30-секундный фикс после 10 минут разбирательств.
Права на таблицы в БД. Таблицы схемы были созданы от суперпользователя postgres вместо scrutator_app. API работал в разработке, но молча падал в production. Решение: ALTER TABLE ... OWNER TO scrutator_app для всех шести таблиц.
Архитектура edge write-back. Модуль Сновидений изначально записывал связи по путям страниц, но база хранит UUID чанков. Это вызывало 100–200 лишних HTTP-запросов за цикл сновидения. Решение: выделенный эндпоинт для batch-резолвинга путей в UUID на стороне сервера — один API-вызов вместо сотен.
Лимит длины входных данных. Документы длиннее 32K символов молча ломались на токен-лимите BGE-M3. Добавили консервативный лимит в 24 000 символов с понятными сообщениями об ошибке.
Как это связано
Scrutator — backend ретривинга для всей экосистемы Arcanada:
- Long Term Memory — Scrutator является слоем поиска. Когда агенту нужно вспомнить что-то из прошлых разговоров или документов, он обращается к Scrutator.
- Agent Dreamer — Модуль Сновидений подключается к автономному pipeline Dreamer. Обслуживание знаний работает по расписанию — не пассивное хранение, а активная реорганизация.
- Model Connector — Интеграция с LLM для семантического понимания запросов. Мы работаем над использованием Model Connector как LLM-бэкенда для анализа Scrutator, с Cursor в качестве основного коннектора и Claude как запасной вариант.
Каждый AI-агент экосистемы получает доступ к единому, мультиязычному, гибридному поиску по всей базе знаний. Не просто совпадение ключевых слов — семантическое понимание.
Почему Open Source
Ретривинг знаний — это инфраструктура. Как базы данных и веб-серверы — она должна быть прозрачной, проверяемой и улучшаемой сообществом. Мы публикуем всё: архитектурные решения, результаты бенчмарков и даже наши ошибки (прогноз RAM оказался в 5 раз ниже реальности — это задокументировано в репо). Загляните в репозиторий на GitHub — лицензия MIT.
Что дальше
Ядро движка построено и работает. Следующий этап — сделать его умнее:
- LLM-анализ — Использование Model Connector для доступа Scrutator к языковым моделям, чтобы глубже анализировать знания во время циклов сновидений.
- Бенчмарки Long Term Memory — Production-замеры качества ретривинга и сохранности памяти между сессиями агентов.
- Self-hosted эмбеддинги для внешних потребителей — Сделать Embedding API доступным другим проектам экосистемы без зависимости от внешних API.
Серия статей
Этот пост — полная картина после запуска всех компонентов. Технические разборы на подходе:
- Embedding Server: BGE-M3 sparse + ColBERT + fp16 — как мигрировали с SentenceTransformer на BGEM3FlagModel, сюрприз с RAM и что мы узнали.
- Chunking Engine: как разбивать знания на смыслы — четыре стратегии, тестирование на реальных файлах и почему структурное разбиение важно.
- Hybrid Search: Dense + Sparse + FTS + RRF — почему три сигнала лучше одного, с production-бенчмарками.
- Dreaming: когда знания начинают думать — периодическая реорганизация, интеграция с Agent Dreamer и архитектура edge write-back.
Подписывайтесь на блог или ставьте звезду репозиторию на GitHub, чтобы не пропустить.