Telegram-ассистент с двумя режимами AI: локальными Ollama + faster-whisper или облачными YandexGPT + SpeechKit через Yandex AI Studio, контекстом текущего диалога, долговременной памятью, заметками, напоминаниями и отслеживанием статусов.

Вся переписка сохраняется в SQLite отдельно для каждого чата. В текущий контекст попадают последние реплики активной темы, причем более свежие сообщения имеют больший приоритет. При явной смене темы модель начинает новый контекст, не удаляя архив. К старому обсуждению можно вернуться обычной просьбой к боту или найти сообщения командой /history ключевые слова. Команда /new вручную начинает новую тему и также сохраняет предыдущую переписку.

Структура

main.py — совместимая точка входа;
assistant_bot/application.py — сборка Telegram-приложения;
assistant_bot/config.py — переменные окружения и настройки;
assistant_bot/storage.py — SQLite-хранилище;
assistant_bot/ollama.py — HTTP-клиент Ollama;
assistant_bot/yandex_ai.py — адаптер Yandex AI Studio SDK;
assistant_bot/agent.py — агентный цикл и выполнение внутренних tools;
assistant_bot/agent_tools.py — единый реестр и исполнители agent tools;
assistant_bot/services.py — типизированный контейнер сервисов приложения;
assistant_bot/handlers.py — Telegram-команды и сообщения;
assistant_bot/reminders.py — разбор времени напоминаний;
assistant_bot/jobs.py — фоновые задачи;
assistant_bot/migrations.py — версионируемые миграции SQLite;
tests/ — модульные тесты ядра.

Запуск

conda activate kandrusyak_bot
python -m pip install -r requirements.txt
python main.py

Также пакет можно запустить командой python -m assistant_bot.

Обязательная настройка в .env:

BOT_TOKEN=...
ASSISTANT_PASSWORD=...
ASSISTANT_MODE=local

ASSISTANT_PASSWORD — общий пароль доступа к боту. Новый пользователь должен один раз отправить его боту в личном чате; после успешной проверки авторизация сохраняется в SQLite, а сам пароль в базу данных не записывается.

ASSISTANT_MODE принимает local (значение по умолчанию) или yandex. Общие дополнительные настройки: ASSISTANT_DB, ASSISTANT_TIMEZONE и VOICE_MAX_DURATION_SECONDS.

Локальный режим

В режиме local текст обрабатывает Ollama, а голосовые сообщения распознаются локально через faster-whisper. Настройки:

ASSISTANT_MODE=local
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen3.5:9b

При первом голосовом сообщении модель faster-whisper будет загружена автоматически. Настройки распознавания:

WHISPER_MODEL=large-v3
WHISPER_DEVICE=cuda
WHISPER_COMPUTE_TYPE=int8
WHISPER_LANGUAGE=ru
VOICE_MAX_DURATION_SECONDS=120

По умолчанию используется полная модель large-v3 на NVIDIA GPU с вычислениями INT8 и beam size 5. Крупная модель сохраняет приоритет качества, а INT8 уменьшает расход видеопамяти. Для этого режима необходимы CUDA 12, cuBLAS для CUDA 12 и cuDNN 9. Чтобы определять язык автоматически, укажите WHISPER_LANGUAGE=auto.

На Windows используется зафиксированная версия CTranslate2 4.6.0: более новые сборки 4.7.x могут аварийно завершаться при инициализации модели. Проект настроен для Conda-окружения kandrusyak_bot. Полный набор DLL cuDNN 9 должен находиться в системном PATH или рядом с библиотекой CTranslate2.

Режим Yandex AI Studio

В режиме yandex бот использует официальный Yandex AI Studio SDK: YandexGPT для текста и SpeechKit для Telegram-аудио в формате OGG Opus. Создайте API-ключ с необходимыми ролями и укажите стандартные переменные авторизации SDK:

ASSISTANT_MODE=yandex
YANDEX_CLOUD_FOLDER=...
YC_API_KEY=...
YANDEX_CLOUD_MODEL=yandexgpt/latest
YANDEX_STT_MODEL=general
YANDEX_STT_LANGUAGE=ru-RU
VOICE_MAX_DURATION_SECONDS=120

YANDEX_CLOUD_FOLDER — идентификатор каталога Yandex Cloud (например, значение вида b1g...), а не имя модели. Имя и версия модели указываются отдельно в YANDEX_CLOUD_MODEL, например qwen3.6-35b-a3b/latest.

Значения моделей можно посмотреть командой /models, а пользовательский выбор сохранить командой /model имя-модели. Выбор хранится отдельно для локального и облачного режимов. Короткое имя облачной модели автоматически преобразуется в URI gpt://<YANDEX_CLOUD_FOLDER>/<YANDEX_CLOUD_MODEL>.

Docker

Один Dockerfile содержит два независимых target. Облачный Yandex-образ является target по умолчанию и не содержит CUDA, faster-whisper и CTranslate2:

docker build --target yandex -t kandrusyak-bot:yandex .
docker run -d \
  --name kandrusyak-bot \
  --restart unless-stopped \
  --env-file .env \
  -e ASSISTANT_MODE=yandex \
  -v kandrusyak-data:/data \
  kandrusyak-bot:yandex

Локальный образ содержит CUDA 12, cuDNN 9 и faster-whisper. Для него требуется NVIDIA Container Toolkit:

docker build --target local -t kandrusyak-bot:local .
docker run -d \
  --name kandrusyak-bot \
  --restart unless-stopped \
  --gpus all \
  --env-file .env \
  -e ASSISTANT_MODE=local \
  -v kandrusyak-data:/data \
  kandrusyak-bot:local

Ollama должна быть доступна контейнеру по адресу из OLLAMA_BASE_URL; адрес localhost внутри контейнера указывает на сам контейнер, а не на Linux-хост.

Проверка

conda activate kandrusyak_bot
python -m unittest discover -v

Для локальных проверок качества установите dev-зависимости:

python -m pip install -r requirements-common.txt -r requirements-dev.txt
python -m ruff check .
python -m coverage run -m unittest discover -v
python -m coverage report

README.md Unescape Escape

KAndrusyak Bot