ИНСТРУКЦИЯ ПО ЭКСПЛУАТАЦИИ
ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ «АССИСТЕНТ ПРО»

Документ: Руководство пользователя и администратора
Правообладатель: ИП Белоусов Дмитрий Владимирович (ИНН 665206580503)
Дата: 24 сентября 2026 г.
Документ предназначен для пользователей и администраторов программного обеспечения «Ассистент ПРО». Содержит сведения, необходимые для подготовки рабочего места, эксплуатации функций системы и действий в нештатных ситуациях.

ВВЕДЕНИЕ
Область применения
Настоящая инструкция распространяется на штатное использование программного обеспечения «Ассистент ПРО» — программного комплекса для построения интеллектуальных диалоговых ассистентов и баз знаний на основе технологий RAG и больших языковых моделей. Документ применим как к локальной (on-premise) установке, так и к развёртыванию в собственной облачной инфраструктуре заказчика.
Уровень подготовки персонала
Документ рассчитан на следующие категории пользователей:

Конечные пользователи — владение веб-браузером, навыки переписки в мессенджерах. Специальной подготовки не требуется.
Администраторы проекта — навыки работы с веб-интерфейсами, представление о REST API; не требуется навыков программирования.
Операторы — владение веб-интерфейсом, основы корпоративных коммуникаций.
Системные администраторы — опыт работы с Linux, Docker, утилитами командной строки.

Условные обозначения

Обозначение	Значение
⚠	Важное предупреждение, несоблюдение которого может привести к нарушению работы
ℹ	Информационная заметка, поясняющая контекст
✱	Опциональный шаг или функция
[…]	Параметр, заполняемый пользователем
→	Последовательное действие в интерфейсе (пункт меню → пункт меню)

1. ПОДГОТОВКА К РАБОТЕ
1.1. Предварительные требования к рабочему месту
Для выполнения операций, описанных в настоящей инструкции, необходимо:

Современный веб-браузер: Mozilla Firefox 115+, Google Chrome / Chromium 120+, Яндекс.Браузер последних версий, Microsoft Edge 120+, Safari 17+.
Сетевой доступ к адресу административной панели и (при необходимости) к публичному URL веб-виджета.
Учётная запись в системе с соответствующей ролью (выдаётся системным администратором заказчика).

1.2. Запуск системы
Запуск экземпляра ПО осуществляется системным администратором сервера через консоль управления Docker:
sudo docker compose up -d
После успешного запуска все компоненты системы (FastAPI-приложение, MongoDB, Redis, Qdrant, Celery workers, опционально Ollama и клиенты ботов) становятся доступны через единый веб-интерфейс.
Проверить состояние сервисов можно командой:
sudo docker compose ps
1.3. Вход в систему (административная панель)

Откройте веб-браузер.
Введите в адресной строке URL панели управления, например: https://<host>:18080/admin/ (для локальной установки — http://localhost:18080/admin/).
На экран будет выведена форма авторизации.
Введите имя пользователя в поле «Логин».
Введите пароль в поле «Пароль».
Нажмите кнопку «Войти».

При успешной аутентификации система создаёт сессию и перенаправляет на главную страницу административной панели — раздел «Обзор».
1.4. Завершение сеанса
Для безопасного выхода из системы необходимо нажать кнопку «Выход» (значок входа/выхода в шапке интерфейса). Сессия будет завершена немедленно. Также сессия завершается автоматически при истечении таймаута (30 минут бездействия по умолчанию).

2. ОПИСАНИЕ РАБОТЫ
2.1. Главная панель управления
После входа в систему пользователь попадает в основное окно административной панели. Главная панель управления состоит из боковой навигации и рабочей области и включает следующие разделы:

Раздел	Назначение
Обзор (Overview)	Сводная информация о состоянии сервисов, потреблении ресурсов, числе диалогов
Проекты (Projects)	Создание и настройка независимых проектов в рамках одной инсталляции
База знаний (Knowledge)	Загрузка документов, управление парами «вопрос — ответ»
Краулер (Crawler)	Автоматический обход сайтов и индексация контента
Боты (Bots)	Подключение и настройка Telegram, ВКонтакте, MAX
Голос (Voice)	Загрузка голосовых образцов и обучение голосового профиля
Чтение (Reading)	Управление режимом чтения длинных документов
Операторы (Operators)	Очередь обращений, переадресованных живому сотруднику
Журналы (Logs)	Структурированные логи системы
Статистика (Stats)	Аналитика запросов, экспорт CSV
Настройки (Settings)	Бэкап, конфигурация LLM, доступы

2.2. Создание и настройка проекта

Перейдите в раздел «Проекты» (Projects).
Нажмите кнопку «Создать проект» (Create project).
В открывшейся форме укажите:

Техническое имя проекта (латиница, без пробелов; пример: support_main).
Отображаемое название (кириллица допустима; пример: Поддержка пользователей).
Домен (опционально, для виджета).
Системный промпт (инструкция для LLM, определяющая стиль и ограничения ответов).
Параметры модели: имя LLM (например, Vikhr-YandexGPT-5-Lite-8B-it), температура (0,0–1,0), максимальное число токенов в ответе.
Параметры RAG: количество фрагментов в контексте, размер фрагмента, веса dense/BM25.

Нажмите «Сохранить». Проект становится доступным в общем списке.

2.3. Наполнение базы знаний
2.3.1. Загрузка документов

Перейдите в раздел «База знаний» (Knowledge) и убедитесь, что выбран целевой проект (выпадающий список в шапке).
Нажмите «Загрузить документ» (Upload document).
Выберите файл на локальном диске. Поддерживаемые форматы: PDF, DOCX, DOC, TXT, XLSX, XLS, HTML, JSON, CSV, XML. Максимальный размер по умолчанию — 50 МБ.
Укажите наименование документа в поле «Заголовок».
Заполните поля «Описание» и «Категория» (опционально). При желании активируйте опцию «Автоматически сформировать описание» — система создаст описание средствами LLM.
Нажмите «Сохранить». Документ будет загружен, его текст извлечён, сегментирован и проиндексирован в векторном хранилище.
После завершения индексации документ появляется в общем списке с пометкой «Индексирован».

2.3.2. Управление парами «вопрос — ответ» (Q&A)

Перейдите во вкладку «Q&A» в разделе «База знаний».
Нажмите «Добавить пару».
Заполните поля:

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

Сохраните пару. Q&A учитывается с приоритетом, превышающим обычные результаты RAG-поиска.

2.3.3. Удаление и переиндексация
Для удаления документа нажмите значок корзины напротив записи и подтвердите действие. Связанные векторы автоматически удаляются из Qdrant.
Для полной переиндексации всей базы знаний используйте кнопку «Переиндексировать» (Reindex) в верхней панели раздела. Операция может занять от нескольких минут до часов в зависимости от объёма данных.
2.4. Индексация веб-сайта (краулер)

Перейдите в раздел «Краулер» (Crawler).
Введите начальный адрес сайта (например, https://mmvs.ru).
Задайте параметры обхода:

Максимальная глубина (Depth) — количество уровней переходов от стартовой страницы (рекомендуется 3–5).
Максимальное число страниц (Page limit) — общий лимит обработанных URL.
Список разрешённых доменов (Allowed domains) — ограничение зоны обхода.
Включить рендеринг JavaScript — для одностраничных приложений (SPA), требует ресурсов.

Нажмите «Запустить» (Start). На странице отобразится индикатор прогресса (URL обработано / в очереди / ошибки).
По завершении обхода контент автоматически индексируется в базе знаний выбранного проекта.

Для остановки активного обхода используйте кнопку «Остановить» (Stop). Текущее состояние сохраняется, обход можно возобновить позднее.
2.5. Подключение каналов связи
2.5.1. Telegram-бот

Получите токен бота у @BotFather в Telegram (команда /newbot).
В разделе «Боты» выберите проект и вкладку «Telegram».
Вставьте полученный токен в поле «Bot Token».
Нажмите «Сохранить», затем «Запустить». Сервис telegram-bot автоматически подключится.
Найдите вашего бота в Telegram, нажмите /start. Любое сообщение будет обрабатываться через RAG-конвейер выбранного проекта.

2.5.2. ВКонтакте

Создайте сообщество в ВКонтакте, в настройках сообщения → API → создайте ключ доступа с правами «Сообщения сообщества».
В разделе «Боты» выберите вкладку «ВКонтакте» и вставьте полученный токен.
Включите длинный опрос (Long Poll) в настройках сообщества ВКонтакте.
Сохраните и нажмите «Запустить».

2.5.3. Веб-виджет
Виджет встраивается на любой сайт через JavaScript-код, доступный во вкладке «Виджет» проекта. Скопируйте сниппет вида:
<script src="https://<host>/widget/loader.js"
data-project="support_main"></script>
Разместите его перед закрывающим тегом </body> на нужных страницах сайта.
2.6. Мониторинг и статистика
2.6.1. Раздел «Обзор»
Отображает текущее состояние всех сервисов системы (MongoDB, Redis, Qdrant, Ollama), потребление CPU и RAM, число активных диалогов и задач Celery.
2.6.2. Раздел «Статистика»
Содержит:

Количество запросов за период (день / неделя / месяц).
Среднее время ответа.
Долю успешных и неотвеченных запросов.
Топ источников знаний, попавших в ответы.
Кнопку экспорта данных в формат CSV.

2.6.3. Раздел «Журналы»
Просмотр последних N (по умолчанию 200) структурированных событий системы. Поддерживается фильтрация по уровню (DEBUG / INFO / WARNING / ERROR), модулю и временному окну.
2.7. Резервное копирование

Перейдите в раздел «Настройки» → «Резервные копии» (Backups).
Включите автоматическое расписание (например, ежедневно в 03:00) — заполните поля «Час», «Минута», «Часовой пояс».
При необходимости укажите параметры Яндекс.Диска (токен, целевая папка) для удалённого хранения.
Нажмите «Сохранить настройки».

Для создания резервной копии вручную нажмите «Создать сейчас» (Run now). По завершении в журнале появится запись с указанием размера, времени и расположения архива.
Для восстановления — нажмите «Восстановить из архива» (Restore), выберите архив и подтвердите операцию. ⚠ Восстановление полностью замещает текущие данные — перед запуском убедитесь, что это действительно требуется.

3. ВЗАИМОДЕЙСТВИЕ КОНЕЧНОГО ПОЛЬЗОВАТЕЛЯ
3.1. Чат-виджет на сайте

Откройте сайт, на котором установлен виджет «Ассистент ПРО».
Нажмите кнопку с иконкой помощника в правом нижнем углу страницы.
Введите вопрос в поле ввода и отправьте.
Ответ ассистента отображается в реальном времени, токен за токеном (стриминг). По завершении ниже ответа выводятся ссылки на источники (если доступны).
Поставьте оценку ответу (👍/👎) — это улучшит качество в дальнейшем.

Если ответ не устраивает или не получен, можно нажать «Связаться с оператором» — обращение будет передано в очередь раздела «Операторы».
3.2. Telegram-бот

Откройте Telegram и найдите бота по имени, указанному при настройке (например, @your_assistant_bot).
Отправьте команду /start.
Введите вопрос в свободной форме.
Получите ответ. Команды управления:

/help — справка по доступным командам.
/reset — сбросить контекст текущего диалога.
/operator — переадресовать обращение оператору.

3.3. Голосовой режим (если активирован)

В виджете нажмите иконку микрофона.
Дайте разрешение браузеру на использование микрофона (всплывающий запрос).
Произнесите вопрос.
Система распознает речь, обработает запрос и при необходимости озвучит ответ.

4. РОЛЬ ОПЕРАТОРА
4.1. Очередь обращений
Оператор работает с переадресованными обращениями в разделе «Операторы». Очередь содержит:

Идентификатор сессии и пользователя.
Канал поступления (виджет / Telegram / ВК / MAX / почта).
Историю последних N сообщений.
Время поступления и приоритет.

4.2. Обработка обращения

Откройте обращение в очереди.
Ознакомьтесь с историей диалога.
Введите ответ в поле «Сообщение оператора» и нажмите «Отправить». Ответ доставляется пользователю в исходный канал.
При необходимости пометьте обращение «Решено» (Closed) или передайте другому оператору («Передать»).

4.3. Журналы
Все действия операторов фиксируются в системных журналах. Просмотр доступен администратору в разделе «Журналы».

5. АВАРИЙНЫЕ СИТУАЦИИ И УСТРАНЕНИЕ НЕИСПРАВНОСТЕЙ
5.1. Типовые ситуации и действия

Симптом	Возможная причина	Действия
Не открывается административная панель	Не запущен сервис app или закрыт порт	Проверить sudo docker compose ps; перезапустить sudo docker compose restart app; проверить firewall
Ошибка авторизации	Неверные логин/пароль; сессия истекла	Проверить ADMIN_USERNAME / ADMIN_PASSWORD в .env; обратиться к системному администратору
Бот не отвечает	Неверный токен; сервис telegram-bot остановлен	Проверить токен в проекте; sudo docker compose restart telegram-bot
Долгое время ответа (> 10 с)	Высокая нагрузка LLM; нет GPU; большая база знаний без кэша	Проверить состояние Ollama; включить кэш Redis; рассмотреть переход на меньшую модель
Документ загружен, но не индексируется	Сервис celery_worker не запущен или перегружен	sudo docker compose logs celery_worker; перезапустить worker
Ошибка 502 Bad Gateway	Сервис app перезапускается / не готов	Подождать 1–2 минуты, повторить; проверить healthcheck
Краулер «застрял»	Целевой сайт блокирует обход / медленная сеть	Нажать «Остановить»; снизить параметры глубины и лимита; проверить robots.txt
Исчерпано место на диске	Растёт объём GridFS / резервных копий	Удалить старые архивы в разделе «Бэкапы»; настроить ротацию; добавить дисковое пространство
Резервная копия не создаётся	Неверный токен Яндекс.Диска / нет места	Проверить настройки в разделе «Бэкапы»; см. журнал ошибок

5.2. Контакт с технической поддержкой
При невозможности устранить ситуацию собственными силами обратитесь в службу технической поддержки правообладателя:

Электронная почта: rtfdeamon@mail.ru
Адрес: 620078, Свердловская область, г. Екатеринбург, ул. Комсомольская, стр. 37, помещ. 406
Режим работы: понедельник–пятница, 09:00–18:00 (Мск).

При обращении укажите: версию ПО, дату инцидента, описание проблемы, ожидаемое и фактическое поведение, выдержки из журналов (раздел «Журналы» → экспорт CSV) и снимки экрана при возможности.
5.3. Рекомендации по штатной эксплуатации

Контролируйте свободное место на сервере (мониторить раздел «Обзор»).
Регулярно проверяйте резервные копии и время последнего успешного бэкапа.
Не реже одного раза в месяц анализируйте раздел «Неотвеченные» и пополняйте базу знаний.
Не передавайте учётные данные администратора третьим лицам; для каждого сотрудника заводите отдельную учётную запись.
При обновлении версии ПО — предварительно создавайте резервную копию.

Правообладатель: ИП Белоусов Дмитрий Владимирович
Контакт службы поддержки: rtfdeamon@mail.ru

Скачать документ