Описание проекта
Проект представляет собой Telegram-бота, реализующего функционал интеллектуального ассистента. Поведение бота полностью определяется содержимым системного промпта, что позволяет гибко менять его роль (например, на консультанта, оператора технической поддержки или творческого собеседника) без изменения программного кода.
Архитектура приложения следует четкому разделению ответственности и состоит из следующих ключевых компонентов:
Модуль bot.py: Является точкой входа и ядром приложения. Отвечает за:
Инициализацию и запуск бота с использованием токена из среды окружения.
Регистрацию и обработку команд (например, /start) и всех текстовых сообщений от пользователей.
Управление контекстной историей диалога для каждого отдельного чата, которая сохраняется в памяти на время сессии и передается в LLM для обеспечения связности беседы.
Организацию логирования работы приложения для отладки.
Модуль models.py: Содержит бизнес-логику взаимодействия с языковой моделью. Включает:
Класс LLMService, инкапсулирующий работу с Yandex GPT API. Его методы загружают системный промпт из файла, формируют структурированный запрос с историей сообщений и возвращают сгенерированный моделью ответ.
Единую точку входа для получения ответа от модели, что упрощает интеграцию и потенциальную замену LLM-провайдера.
Каталог prompts/: Содержит текстовые файлы (например, prompt_1.txt) с системными инструкциями для бота. Это позволяет отделить логику поведения ("что делать") от логики работы приложения ("как делать") и оперативно тестировать различные сценарии общения.
Файл конфигурации .env: Используется для безопасного хранения всех чувствительных данных: TELEGRAM_BOT_TOKEN, YA_API_KEY, YA_FOLDER_ID. Данный подход соответствует лучшим практикам в области безопасности и упрощает развертывание приложения на различных платформах и серверах.
Такая модульная структура обеспечивает слабую связанность компонентов, высокую сопровождаемость кода и простоту расширения функциональности.
Установка и настройка компонентов приложения
Для запуска проекта необходимо выполнить последовательность шагов по подготовке среды разработки и получению необходимых ключей доступа. Все операции выполнялись в среде разработки Visual Studio Code под управлением операционной системы Windows.
Клонирование репозитория и открытие проекта: Исходный код проекта был получен с GitHub с помощью системы контроля версий Git. В интегрированном терминале VS Code была выполнена команда:
git clone https://github.com/labintsev/python-telegram-ai-bot . (рис. 1).
Рисунок 1 – Клонирование репозитория с GitHub.
Символ точки в конце команды указывает на клонирование в текущую директорию, что позволило сразу получить структуру проекта с основными файлами: bot.py, model.py, каталогом prompts/ и другими вспомогательными файлами.
Создание и активация виртуального окружения: Для изоляции зависимостей проекта от глобальной системы Python было создано виртуальное окружение с помощью команды:
py -m venv venv --without-pip (рис. 2).
Рисунок 2 – Создание виртуального окружения.
Параметр --without-pip был использован для упрощения первоначальной настройки в Windows. После создания окружения оно было активировано с помощью скрипта PowerShell:
.\venv\Scripts\Activate.ps1 (рис. 3).
Рисунок 3 – Активация виртуального окружения.
Активация подтверждается появлением префикса (venv) в приглашении командной строки.
Установка менеджера пакетов pip и зависимостей: Поскольку окружение было создано без pip, он был установлен отдельно. Для этого с помощью утилиты curl был загружен установочный скрипт:
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python get-pip.py (рис. 4).
Рисунок 4 – Установка менеджера пакетов pip и зависимостей.
После успешной установки pip были установлены все библиотеки, необходимые для работы приложения:
pip install python-telegram-bot python-dotenv openai requests (рис. 5 - 6).
Рисунки 5-6 – Установка всех необходимых библиотек.
Библиотеки были выбраны исходя из требований проекта: python-telegram-bot для работы с Telegram API, python-dotenv для управления конфигурацией, openai (в совместимом режиме) для взаимодействия с Yandex GPT API и requests для HTTP-запросов.
Получение и настройка аутентификационных ключей: Работа приложения требует двух типов ключей доступа:
Токен Telegram-бота (TELEGRAM_BOT_TOKEN) был получен через официального бота @BotFather в мессенджере Telegram после создания нового бота с помощью команды /newbot (рис. 7).
Рисунок 7 – Создание чат-бота в Telegram и получения его токена.
Ключи Yandex Cloud API были получены в консоли Yandex Cloud:
YA_API_KEY: Ключ сервисного аккаунта, созданный в разделе "Сервисные аккаунты" → ai-bot-sa → "Создать новый ключ". (рис. 8).
Рисунок 8 – Создание API-ключа в консоли Yandex Cloud.
YA_FOLDER_ID: Идентификатор каталога, скопированный из URL (рис. 9).
Рисунок 9 – Получение идентификатора каталога.
Все полученные ключи были помещены в файл конфигурации .env в корневой директории проекта для безопасного хранения и изоляции от исходного кода (рис. 10).
Рисунок 10 – Структура файла .env (ключи частично замазаны).