внутренний проект · передача в эксплуатацию

UserGate Docs Bot

Telegram-ассистент техподдержки, который отвечает на вопросы по продуктам UserGate строго по документации — со ссылками на источники, самопроверкой каждого ответа и честным «в документации этого нет», когда ответа действительно нет.

80%полезных ответов на вопросы, покрытые документацией
0%выдуманных фактов — порты, команды и пути меню не фабрикуются
~12 слатентность ответа (было 52 с в первой версии)
20 451фрагмент базы знаний: полные доки + курированный опыт сообщества

Все цифры — из воспроизводимого измерительного стенда, входящего в комплект; методика в RESULTS.md.

Открыть бота в Telegram Спросить прямо здесь ↓

попробовать

Задайте вопрос — прямо отсюда

Та же система, что отвечает в Telegram: поиск по базе знаний, генерация строго по фрагментам, самопроверка. Ответ занимает 10–20 секунд.

как это работает

Конвейер одного ответа

Нормализация вопроса

Живой сленг админов («вафка», «мц», «нгфв») приводится к терминам документации — только для поиска, модель видит оригинал вопроса.

Гибридный поиск

Лексический BM25 с русским стеммингом + нейросетевые эмбеддинги (multilingual-e5), слияние RRF. Поверх — диверсификация выдачи, приоритет продукта из вопроса и квота на community-фрагменты.

Генерация строго по фрагментам

LLM получает 20 найденных фрагментов и жёсткую редполитику: отвечать только по ним, не смешивать продукты, помечать версии и опыт сообщества.

Самопроверка заземления

Второй LLM-проход проверяет ключевые утверждения ответа по тем же фрагментам. Не подтвердилось — ответ перегенерируется с указанием, что именно не так; не прошло снова — честный отказ вместо догадки.

Ответ с доказательствами

Источники подбираются по фактическому содержанию ответа, под ответом — индикатор уверенности (🟢 проверено по документации / 🟡 сверьтесь с источниками).

почему это ценно

Система решений, а не скрипт со промптом

Собрать «бота с RAG» можно за выходные. Довести его до 0% выдуманных фактов при живой скорости — это журнал из 15+ измеренных экспериментов, где каждое решение прошло гейт на реальных вопросах из чата экспертов, а модные техники, не давшие прироста, отвергнуты по данным — с сэкономленными на этом ресурсами. Журнал воспроизводим: стенд в комплекте.

РешениеЗамер (n=50 реальных вопросов)Статус
Дедупликация корпуса (48% дублей после двойного скрейпа) 40 701 → 20 451 фрагм.в проде
Версионные аннотации опыта сообщества (советы «стареют») выдумки 4% → 0%в проде
Проверка заземления + перегенерация вместо отказа полезных 40% → 48%в проде
Русский стемминг + диверсити + продуктовый приоритет hit@10 0.588 → 0.664в проде
Отключение reasoning с компенсацией проверкой 52 с → 12 с, без роста ошибокв проде
Cross-encoder reranker +10 с, прирост 0отвергнут по данным
LLM-переписывание запросов полезных −10 п.п.отвергнут по данным
Contextual Retrieval (Anthropic) +0…1.7 п.п. — в шумеотвергнут по данным

Отдельная ценность — измерительный стенд: 50 реальных экспертных вопросов + LLM-судья с reasoning + автоматическое различение «бот ошибся» и «документация расходится с полевой практикой». Без него любая доработка бота — игра вслепую; с ним любое изменение проверяется за ~20 минут.

комплект поставки

Что внутри

Код бота

~1 800 строк Python: aiogram-бот, RAG-ядро, гибридный ретрив, LLM-клиент с fallback-бэкендом и ретраями.

База знаний + конвейер сборки

Готовый корпус (доки + community) и скрипты полного цикла: скрейп → чанкинг → аннотации → эмбеддинги.

Измерительный стенд

eval-наборы, судья, кросс-проверка вторым судьёй, retrieval-метрики. Гейты качества для любых будущих правок.

Эксплуатация

Docker + compose (non-root), референс systemd-юнита, мониторинг с Telegram-алертами, HANDOVER.md со справочником всех настроек.

Журнал решений

RESULTS.md — каждое изменение с цифрами до/после; RESEARCH_LOG.md — почему выбраны именно эти техники.

Готовность к самохостному LLM

Миграция на корпоративный vLLM/qwen — три строки конфигурации + обязательный прогон стенда (инструкция в HANDOVER §8).

развёртывание

Три шага до работающего бота

# 1. настроить окружение (токен бота, эндпоинт LLM — см. HANDOVER.md §3)
cp .env.example .env

# 2. положить базу знаний (chunks.jsonl + embeddings.npy + manifest)
cp -r /path/to/corpus/* ./data/

# 3. запустить
docker compose up -d --build   # ждать в логах: «бот запущен, polling...»

Ресурсы: 2 CPU, ~2.5 ГБ RAM, ~5 ГБ диска. GPU не требуется — эмбеддинги считаются на CPU, генерация ходит в любой OpenAI-совместимый эндпоинт (облачный гейтвей или корпоративный vLLM).

куда расти

Дорожная карта

  • Автообновление базы знаний — дельта-скрейп docs.usergate.com по расписанию (сейчас снимок пересобирается вручную).
  • Рост community-слоя — отобраны 202 новые пары из чата экспертов (уже отфильтрованы от пересечений с тестовым набором); конвейер курирования и аннотирования готов.
  • Миграция на корпоративный LLM — избавление от внешнего гейтвея; методика замера деградации готова.
  • Версионный фильтр — ответы с учётом конкретной версии ПО пользователя (метаданные в корпусе уже есть).

передача

Забрать систему

Полный комплект: код, база знаний, стенд, документация эксплуатации. Секретов в архиве нет — токены и ключи передаются отдельно. Доступ к файлам по логину-паролю — запросите у автора.

Архив: код + база знаний (.tar.gz, 6 МБ) Git-история решений (.bundle)

Вопросы по архитектуре, методике замеров и планам развития — Святослав Тарасов. Передача включает часовую сессию вопросов-ответов с командой эксплуатации.