MAX AI BOT — персональный AI-ассистент в MAX в docer

AI | ML | CV
, ,
1

MAX AI BOT — персональный AI-ассистент в MAX на собственном сервере или NAS

Всем привет!

Хочу представить MAX AI Assistant — открытый self-hosted проект, который превращает отдельный пользовательский аккаунт MAX в личный интерфейс к современным AI-моделям. Ассистент работает постоянно на вашем компьютере, сервере или Synology-совместимом NAS: ему можно написать из обычного приложения MAX, отправить фотографию, документ или голосовое сообщение и получить ответ прямо в личном чате.

Проект создавался не как публичный бот для всех желающих, а как персональный ассистент одного владельца. После однократной привязки он принимает команды только от заданной пары sender ID + chat ID, игнорируя группы, каналы, исходящие сообщения и обращения других пользователей.

Репозиторий: https://github.com/usmanovcloud-dotcom/max-ai-assistant

Лицензия: MIT.

Как это выглядит

max-ai-dashboard-overview
max-ai-dashboard-overview1265×712 54.6 KB

Главный экран: состояние MAX и AI, выбранный провайдер, очередь, лимиты и управление ассистентом.

max-ai-dashboard-auth
max-ai-dashboard-auth1280×720 52.8 KB

Подключение второго аккаунта: наглядные этапы от запуска клиента и QR-кода до привязки владельца командой /claim.

Главная особенность: доступен обычному физическому лицу

Для создания официального чат-бота платформа MAX для партнёров требует верифицированный профиль юридического лица (например, ООО), ИП или самозанятого — это прямо указано в официальной документации MAX. MAX AI Assistant устроен иначе: он не регистрирует официального бизнес-бота, а работает от имени второго обычного пользовательского аккаунта MAX через неофициальный клиентский интерфейс PyMax.

Поэтому для технического запуска личного ассистента не нужны ООО, статус ИП или самозанятость, регистрация на платформе MAX для партнёров и модерация карточки бота. Достаточно завести второй аккаунт MAX, развернуть проект на своём устройстве и один раз привязать к нему основной аккаунт владельца.

Именно в этом главное преимущество проекта для домашнего и личного использования: физическое лицо может получить собственного AI-помощника в MAX без оформления бизнес-профиля только ради доступа к официальному Bot API.

Но есть и обратная сторона. Такой аккаунт не получает официальный статус бота, публичную карточку и гарантии официального Bot API. PyMax является неофициальным решением, поэтому после изменений MAX интеграция может потребовать обновления или перестать работать. Это техническое отличие способа подключения, а не освобождение от требований закона: если ассистент используется для коммерческой деятельности, владелец самостоятельно соблюдает применимые налоговые правила, условия сервисов и требования к обработке данных.

Зачем это нужно

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

Например, можно:

  • задать обычный текстовый вопрос;
  • сфотографировать устройство, документ или ошибку на экране и попросить объяснить увиденное;
  • отправить PDF, Word, Excel, PowerPoint, CSV, текстовый файл или исходный код на анализ;
  • надиктовать голосовое сообщение — оно будет распознано, после чего основная модель подготовит ответ;
  • начать новый диалог командой /new;
  • проверить состояние и текущие настройки командами /status и /help;
  • управлять ассистентом через локальную веб-панель.

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

Что находится внутри

Проект написан на Python и состоит из нескольких независимых частей:

  • транспорт MAX на базе PyMax;
  • OpenAI-совместимый слой AI-провайдера;
  • локальная SQLite-база с настройками, историей, очередью и статистикой;
  • веб-панель управления;
  • Docker-образ и отдельный compose-файл для Synology Container Manager;
  • набор автоматических тестов и GitHub Actions для проверки и публикации образа.

Основной профиль рассчитан на официальный OpenAI Responses API. Также предусмотрен OpenRouter как дополнительный провайдер. Модель, системную инструкцию, глубину истории, тайм-ауты, дневные лимиты запросов и токенов можно менять из панели.

Важно: это не локальная нейросеть. Сам контейнер, настройки, история и очередь находятся на вашем устройстве, однако содержимое запроса передаётся выбранному AI-провайдеру для обработки. Вызовы OpenAI выполняются с store=false, а история диалога формируется локально. Временные ссылки MAX, содержимое вложений и расшифровка голоса не записываются в SQLite, резервную копию или обычный журнал проекта.

Веб-панель

Через панель можно:

  • увидеть состояние подключения MAX, AI-процесса и очереди;
  • пройти авторизацию MAX по QR-коду и при необходимости ввести 2FA;
  • сохранить API-ключ так, чтобы интерфейс больше не мог показать его открытым текстом;
  • выбрать провайдера и модель из доступного каталога;
  • настроить лимиты, историю, тайм-ауты и системную инструкцию;
  • вести отдельные веб-диалоги и отправлять сообщения владельцу в MAX;
  • смотреть статистику запросов, токенов, задержки и расчётную стоимость;
  • выгружать безопасную резервную копию без API-ключей и MAX-сессии;
  • при желании отправлять обезличенные события в n8n webhook.

Панель предназначена только для локального компьютера или доверенной домашней сети. Встроенной пользовательской авторизации в ней пока нет, поэтому порт 8765 нельзя напрямую публиковать в интернет. Для внешнего доступа потребуется отдельный reverse proxy с HTTPS и аутентификацией либо VPN.

Безопасность по умолчанию

В проекте намеренно заложены ограничения, важные для личного ассистента:

  • владелец привязывается одноразовой командой /claim;
  • claim-код хранится в виде SHA-256, имеет срок действия и удаляется после использования;
  • проверяются одновременно отправитель, конкретный личный чат и направление сообщения;
  • телеметрия PyMax принудительно отключена;
  • QR-ссылка, пароль 2FA, MAX-сессия и API-ключи не выводятся в обычный лог;
  • контейнер запускается без Linux capabilities, с no-new-privileges и read-only root filesystem;
  • логи ротируются, а резервная копия не содержит секреты;
  • лимиты запросов и токенов проверяются до обращения к внешнему API.

Это не отменяет обычных правил эксплуатации: каталоги data и secrets необходимо защищать и резервировать отдельно, панель держать только в доверенной сети, а для ассистента необходимо использовать отдельный аккаунт MAX.

Быстрый запуск на Synology

Для установки потребуется:

  • Synology/совместимый NAS с Container Manager и архитектурой linux/amd64;
  • отдельный аккаунт MAX для ассистента;
  • API-ключ выбранного AI-провайдера и положительный баланс API;
  • доступ к панели из локальной сети.

Подписка ChatGPT и баланс OpenAI API — разные продукты: наличие подписки ChatGPT само по себе не оплачивает API-запросы.

  1. Скачайте файл:

    https://raw.githubusercontent.com/usmanovcloud-dotcom/max-ai-assistant/main/docker-compose.nas.yml

  2. В DSM откройте Container Manager → Проект → Создать, выберите создание из YAML и вставьте содержимое файла.

  3. Перед запуском проверьте пути /volume1/docker/max-ai-assistant/... и значения UID/GID 1032:100. Они соответствуют конкретной исходной установке и при другом томе или пользователе DSM должны быть изменены.

  4. Запустите проект и дождитесь состояния healthy.

  5. Откройте в домашней сети:

    http://IP-АДРЕС-NAS:8765

  6. В панели сохраните API-ключ, авторизуйте отдельный аккаунт MAX по QR-коду, затем отправьте показанную команду /claim ... со своего основного аккаунта в личный чат ассистента.

Готовый образ загружается из:

ghcr.io/usmanovcloud-dotcom/max-ai-assistant:latest

Данные и секреты хранятся в bind-mounted каталогах, поэтому пересоздание контейнера их не удаляет. Для предсказуемого отката вместо latest лучше использовать версионный тег. На момент подготовки публикации последний оформленный тег — v0.3.2, а мультимодальная ветка main продолжает развиваться в направлении v0.4.0.

Подробная установка и локальный запуск описаны в README репозитория.

Текущий статус

Проект уже имеет рабочее ядро, веб-панель, реальный MAX-транспорт, интеграцию с OpenAI/OpenRouter, обработку вложений, голосовую транскрипцию, Docker-сборку и NAS-конфигурацию.

На актуальном исходном коде локально проходят 73 автоматических теста и встроенный healthcheck. Публичный CI ветки main также завершён успешно, а образ latest доступен для анонимной загрузки из GHCR.

При этом проект пока стоит считать ранней пользовательской версией. Поддержка разных типов вложений недавно добавлена и требует более широкого тестирования на реальных событиях MAX и разных моделях. NAS-конфигурация ориентирована на amd64; ARM-устройства пока не заявлены. Интерфейс и формат хранения могут меняться до стабильного релиза.

Важное предупреждение

MAX AI Assistant не является официальным продуктом MAX, OpenAI или OpenRouter. Подключение к пользовательскому аккаунту MAX выполняется через неофициальную библиотеку PyMax, поэтому совместимость может измениться после обновлений сервиса. Используйте отдельный аккаунт, не применяйте проект для спама и учитывайте правила используемых сервисов. Есть вероятность бана аккаунта.

Стоимость работы зависит от выбранной модели, размера истории и количества вложений. Разумно сразу выставить дневные лимиты и небольшой месячный бюджет, а затем скорректировать их по статистике.

Проект полностью создан AI ChatGPT 5.6

Обратная связь

Буду благодарен за тестирование и конструктивные отзывы, особенно по следующим направлениям:

  • запуск на разных моделях Synology и совместимых NAS;
  • авторизация MAX, QR и 2FA;
  • реальные фотографии, PDF и офисные документы;
  • голосовые сообщения и аудиофайлы;
  • стабильность длительной работы и переподключения;
  • удобство первого запуска и веб-панели.

Ошибки и предложения можно оформлять в разделе Issues:

https://github.com/usmanovcloud-dotcom/max-ai-assistant/issues

Если проект окажется полезным, поставьте звезду репозиторию — это поможет понять, стоит ли развивать универсальную установку, ARM-сборки, защищённый удалённый доступ и дополнительные AI-провайдеры.

1 лайк