Всем привет! Для меня электричество — это магия, и ИИ — тоже. После того, как я приделал к стене водостойкую розетку, решил что и ИИ можно покорить.
Первым упражнением в вайбкодинге локальной RAG системы стало приложение, которое позволит управлять коллекцией векторных документов и кормить локального агента нужными и вкусными данными.
Сразу к делу — вот репозиторий на ГитХабе, в нем исходники по лицензии MPL 2.0. Приложение для macos 14+, написано на SWIFT и для своей работы тянет только системные зависимости и (при необходимости) пакет установки ChromaDB.
Теперь подробнее
Решаемая задача традиционно‑велосипедна: нужен полностью локальный ИИ, который работает без внешних подключений и разбирает массив файлов, который хранится на этой же машине. Документация технического характера, а качество работы должно быть минимум на уровне стажера (в идеале конечно на уровне высоко‑ /квалифицированных /оплачиваемых /мотивированных сотрудников).
Бюджет разработки: две подписки Claude Pro (по 2 600 ₽ в месяц) и 40 часов моего и Opus 5 High времени.
Железная обвязка: macbook pro 13 m1 16gb, macbook pro 14 m5 pro 64gb, imac 27 2020 5500 XT.
Что тут на****кодил?
Методом антинаучного тыка я перебирал разные элементы локальной цепочки RAG. Мне нужно поговорить с ИИ про документ, поискать определенные сведения среди имеющихся материалов, затем провести обработку по определенному алгоритму.
В начале цепочки — приложение для выбора и запуска LLM на ноутбуке. Выбор пал на LM Studio, также пробовал Ollama c Open WebUI. Причина выбора — удобство установки и скачивания. Кроме того, интерфейс чата позволил закрыть задачу «поговорить про конкретный документ в вакууме» без лишних движений.
В конце цепочки — локальный агент. Остановился на Hermes, пробовал — Bionic, Anything LLM, Msty Studio. Причина выбора — наиболее «послушное» поведение в связке с LM Studio. Абсолютно субъективно. Работа по цепочке задач вполне себе сносная, прошлые действия немного помнит.
А вот по центру цепочки случился провал — почти каждое из приложений (даже LM Studio) предлагает набор способов работы с локальными документами. Множественные опыты показали, что документ полностью «впихнутый» в контекстное окно локальной модели разбирается великолепно и единоразово целевую магию показывает. Однако как только возникают нарезки, методы и методологии работы с локальными документами — получаешь увлекательный разбор оглавления документа, фантазии о 5 лучших наборах из 50 слов в тысяча‑страничном документе, неспособность найти банальное вхождение термина и в целом — полностью хаотичный и произвольный результат.
Как ни крути:
температуру на градуснике;
лимит на ретривере (это блохи какие‑то?);
размер чанка (Норриса?);
шаблон обращения «Уважаемая локальная модель! \n/n В рамках исполнения пункта 6 поручения …».
С глубоким уважением и разочарованием — я понял что хочу полностью контролировать как мои документы из душевных буков предложений превращаются в бездушные цифири векторов, как они хранятся и извлекаются, ранжируются и, не дай бог, перезаписываются или удаляются.
И вот само приложение
Целевая функция — управлять сервером ChromaDB, работать с использованием моделей доступных в LM Studio и через MCP‑сервер отдавать данные в Hermes.
Непосредственно сервер ChromaDB можно установить через CLI приложения, в venv с питоном или подключаться к базе по реквизитам.
Подключившись к серверу мы видим доступные коллекции, их атрибуты, содержание.
Приложение позволяет сразу добавить документы в коллекцию и контролирует модель эмбеддинга (если коллекция делалась через приложение) или размерность нарезки (если нарезалось не через приложение).
Дальше интерфейс подключения к LM Studio. Модели для эмбеддинга и для оценки данных разделяются автоматически. Имеется возможность перезагрузить модель с максимальным контекстом из приложения.
История работы моделей хранится и в разных местах дает предположения о том, сколько времени может занять та или иная операция.
Затем добавляем источники. В качестве источника могут быть папки или ссылки на сайты. Стратегии нарезки с произвольными настройками взяты отсюда.
При добавлении источника можно определять дополнительные метаданные, в том числе вложенность по папкам отправлять текстом в базу.
Для подключения агента поднимается MCP‑сервер, к нему выдаются ключи. Сейчас есть возможности:
обычного поиска лучшего подходящего (по вектору и через фильтры «умного поиска»);
поиска всех связанных вхождений;
запроса файла целиком по найденному чанку.
А за тем что делают агенты и что делает приложение следят логи.
А еще есть бекапы, стенд оценки и куча разных странных галочек о назначении которых даже я почти ничего не знаю. Но жмакать их интересно.
Теперь функционал «по‑суше», табличкой
Наименование | Описание |
Встроенный сервер | Установка ChromaDB в изолированное окружение, запуск и остановка локального экземпляра, проверка окружения. |
Внешние подключения | Создание, редактирование и удаление профилей подключения к локальным и удалённым экземплярам ChromaDB. |
Аутентификация и авторизация | Передача токенов через заголовки Authorization или X‑Chroma‑Token. Секреты в Keychain. |
Безопасность и прокси | Локальный обратный прокси с TLS, ключи клиентов, разграничение прав, лимиты и журнал доступа. |
Управление коллекциями | CRUD‑операции для коллекций ChromaDB, включая создание с явным указанием метрики (cosine, l2, ip). |
Управление документами | Добавление, обновление, удаление и поиск документов с фильтрацией по метаданным и тексту. |
Схемы метаданных и фильтры | Сводка полей коллекции, сохранённые фильтры, история запросов. |
Источники и синхронизация | Папки, файлы, сайты и git‑репозитории как источники: инкрементальная синхронизация по журналу и манифесту, наблюдение за папкой, расписание. |
Извлечение текста | Извлекает текст и структуру из PDF, DOCX, RTF, ODT, EPUB, веб‑страниц и git‑репозиториев, включая таблицы. |
Таблицы как источник | XLSX, XLS, ODS, Numbers и CSV: строка становится документом, колонки размечаются профилем листа. |
Стратегии чанкинга | Fixed‑size, Recursive, Document‑based, Hierarchical, Semantic, Adaptive, LLM‑based стратегии с настраиваемыми параметрами. |
Управление эмбеддингами | Подключение к LM Studio, привязка модели к коллекции, кэш векторов, лимиты входа, повторная векторизация при смене модели. |
Конвейер поиска | Многоэтапный поиск: генерация кандидатов, слияние, MMR, расширение контекста, переранжирование, ручные пометки, усечение. Профиль на коллекцию; поиск сразу по нескольким коллекциям. |
Оценка качества | Стенд для оценки поиска: наборы запросов, варианты, метрики (Hit rate, Recall, MRR, nDCG), разметка, отчёты. |
Инспектор здоровья | Проверка коллекции на пустые и короткие документы, чанки без слов, разрывы нумерации, дубли и near‑дубликаты, с рекомендациями. |
Кластеризация и темы | Разбиение коллекции на темы по векторам с отчётом и примерами. |
Просмотр источника | Открытие исходного файла документа прямо в приложении. |
Экспорт и импорт | Экспорт и импорт коллекций в формате.chromaexport (JSONL) с сохранением векторов и метаданных. |
Резервные копии и обслуживание | Копии базы и настроек, перенос настроек, обслуживание и полное стирание данных. |
Корзина | Удалённые документы уходят в корзину и возвращаются оттуда. |
Журналы | Журнал событий приложения, журнал доступа к прокси и журнал сервера. |
Очередь задач | Единая очередь к моделям и базе с приоритетами: человек у экрана, агент, фоновая синхронизация. |
MCP‑сервер | Инструменты для внешних агентов через stdio и HTTP (через прокси с TLS), права и лимиты у каждого ключа. |
Интеграция с macOS | MenuBarExtra, глобальная горячая клавиша, перетаскивание, «Службы» и App Intents для Shortcuts. |
Оформление и язык | Светлая и тёмная тема, русский и английский интерфейс. |
Благодарю за внимание
Подписывайтесь на мой телеграмм‑канал (хотя вряд ли я его когда‑то заведу), ставьте лайки на ютубе (где захотите) и пишите про баги на ГитХабе (Спасибо!)
Если проблематика настройки локальной LLM через велосипеды и вайбкод актуальна, расскажу про настройки стратегий чанкинга, какие модели на моем железе работают, про проблемы оценки результата и всякие другие радости через которые прошел за потраченные 40 часов.
Главное, что в теме стал лучше разбираться.
