Telegram LLM Bot

Асинхронный Telegram-бот на Python и aiogram 3, который отправляет сообщения пользователей в языковую модель через OpenAI-совместимый API.

Проект поддерживает локальный запуск моделей через Ollama, а также подключение внешних LLM-провайдеров, например OpenAI и OpenRouter.

Проект работает в stateless-режиме: каждое сообщение обрабатывается независимо, без сохранения истории диалога.

Возможности

обработка команд /start и /help;
асинхронное взаимодействие с Telegram Bot API;
подключение к OpenAI-совместимым LLM API;
переключение между локальными и внешними моделями через .env;
настройка модели, API endpoint и таймаута без изменения кода;
обработка таймаутов, сетевых ошибок и ошибок LLM-провайдера;
отображение статуса typing во время генерации ответа;
автоматическое разбиение длинных ответов на несколько сообщений;
запуск локально или в Docker;
хранение конфигурации и секретов в переменных окружения.

Как работает приложение

flowchart LR
    User[Пользователь Telegram]
    Bot[Telegram-бот<br/>aiogram]
    Service[LLMService]
    Provider[OpenAI-compatible API<br/>Ollama / OpenAI / OpenRouter]

    User -->|Сообщение| Bot
    Bot -->|Prompt| Service
    Service -->|Chat Completions API| Provider
    Provider -->|Ответ модели| Service
    Service -->|Текст ответа| Bot
    Bot -->|Сообщение| User

Каждый запрос проходит следующий путь:

Пользователь отправляет текстовое сообщение боту.
Обработчик aiogram передаёт текст в LLMService.
LLMService отправляет запрос в выбранную языковую модель.
Полученный ответ возвращается пользователю.
История предыдущих сообщений не сохраняется.

Стек технологий

Компонент	Технология
Язык	Python 3.11+
Telegram-фреймворк	aiogram 3
LLM-клиент	openai-python (`AsyncOpenAI`)
Конфигурация	pydantic-settings
Локальный LLM backend	Ollama
Контейнеризация	Docker, Docker Compose
Взаимодействие с LLM	OpenAI-compatible Chat Completions API

Структура проекта

llm_integration/
├── bot/
│   ├── __init__.py
│   ├── config.py          # Загрузка и валидация переменных окружения
│   ├── handlers.py        # Telegram-команды и обработка сообщений
│   └── llm_client.py      # Асинхронный клиент для взаимодействия с LLM
├── .env.example           # Пример конфигурации
├── .gitignore
├── Dockerfile             # Сборка контейнера Telegram-бота
├── docker-compose.yml     # Запуск бота и локальной Ollama
├── main.py                # Точка входа
├── requirements.txt       # Python-зависимости
└── README.md

Требования

Для запуска без Docker:

Python 3.11 или новее;
Telegram-бот и его токен;
доступ к OpenAI-совместимому LLM API;
Ollama — если используется локальная модель.

Для запуска в контейнерах:

Docker;
Docker Compose.

Получение Telegram Bot Token

Откройте Telegram.
Найдите официального бота @BotFather.
Выполните команду /newbot.
Укажите имя и username нового бота.
Скопируйте полученный токен.
Добавьте токен в переменную TELEGRAM_BOT_TOKEN файла .env.

Не публикуйте настоящий Telegram-токен и API-ключи в репозитории.

Конфигурация

Скопируйте пример конфигурации:

cp .env.example .env

Для Windows PowerShell:

Copy-Item .env.example .env

Основные переменные окружения:

Переменная	Обязательная	Описание
`TELEGRAM_BOT_TOKEN`	да	Токен Telegram-бота
`LLM_BASE_URL`	да	URL OpenAI-совместимого API
`LLM_API_KEY`	да	API-ключ провайдера; для локальной Ollama может быть произвольным
`LLM_MODEL`	да	Название используемой модели
`LLM_TIMEOUT`	нет	Таймаут запроса к LLM в секундах; по умолчанию `60`

Локальная Ollama

TELEGRAM_BOT_TOKEN=your-telegram-bot-token

LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=ollama
LLM_MODEL=tinyllama
LLM_TIMEOUT=60

OpenRouter

TELEGRAM_BOT_TOKEN=your-telegram-bot-token

LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=your-openrouter-api-key
LLM_MODEL=qwen/qwen-2.5-7b-instruct
LLM_TIMEOUT=60

OpenAI

TELEGRAM_BOT_TOKEN=your-telegram-bot-token

LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=your-openai-api-key
LLM_MODEL=gpt-4o-mini
LLM_TIMEOUT=60

Названия и доступность облачных моделей зависят от выбранного провайдера.

Локальный запуск

1. Клонируйте репозиторий

git clone https://github.com/BulatKSMNT/llm_integration.git
cd llm_integration

2. Создайте виртуальное окружение

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1

3. Установите зависимости

python -m pip install --upgrade pip
pip install -r requirements.txt

4. Настройте переменные окружения

Linux/macOS:

cp .env.example .env

Windows PowerShell:

Copy-Item .env.example .env

Откройте .env и укажите Telegram-токен и параметры LLM-провайдера.

5. Запустите приложение

python main.py

После успешного запуска откройте Telegram и отправьте боту команду:

/start

Запуск с локальной Ollama

Установите Ollama и загрузите модель:

ollama pull tinyllama

Убедитесь, что Ollama запущена:

ollama serve

Настройте .env:

TELEGRAM_BOT_TOKEN=your-telegram-bot-token
LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=ollama
LLM_MODEL=tinyllama
LLM_TIMEOUT=60

Запустите Telegram-бота:

python main.py

Можно использовать другую установленную в Ollama модель, указав её название в переменной LLM_MODEL.

Запуск через Docker Compose

Текущий docker-compose.yml предназначен для запуска Telegram-бота вместе с локальной Ollama.

1. Подготовьте конфигурацию

cp .env.example .env

Укажите настоящий токен:

TELEGRAM_BOT_TOKEN=your-telegram-bot-token
LLM_API_KEY=ollama
LLM_MODEL=tinyllama
LLM_TIMEOUT=60

Внутри Docker Compose адрес Ollama автоматически устанавливается в:

http://ollama:11434/v1

2. Запустите Ollama

docker compose up -d ollama

3. Загрузите модель в контейнер Ollama

docker compose exec ollama ollama pull tinyllama

Название загруженной модели должно совпадать со значением LLM_MODEL в файле .env.

4. Соберите и запустите бота

docker compose up -d --build bot

5. Посмотрите логи

docker compose logs -f bot

6. Остановите приложение

docker compose down

Чтобы также удалить volume с загруженными моделями:

docker compose down -v

Запуск Docker-контейнера с облачным LLM

В текущем docker-compose.yml адрес LLM переопределяется адресом контейнера Ollama. Для запуска бота с OpenAI, OpenRouter или другим внешним провайдером можно собрать и запустить только контейнер бота:

docker build -t telegram-llm-bot .
docker run --rm --env-file .env telegram-llm-bot

В этом случае значения LLM_BASE_URL, LLM_API_KEY и LLM_MODEL будут загружены из файла .env.

Доступные команды

Команда	Описание
`/start`	Показывает приветствие и краткое описание бота
`/help`	Показывает справку по использованию
Любое текстовое сообщение	Отправляется в выбранную LLM

Нетекстовые сообщения не отправляются в языковую модель.

Обработка ошибок

Приложение обрабатывает основные ошибки при работе с LLM:

превышение времени ожидания;
отсутствие соединения с LLM API;
ошибки внешнего провайдера;
непредвиденные ошибки приложения;
пустой ответ модели;
ответы, превышающие ограничение одного сообщения Telegram.

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

Архитектурные решения

Stateless-режим

История диалога не сохраняется. Каждый пользовательский запрос отправляется в модель независимо.

Преимущества:

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

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

Универсальный LLM-клиент

Взаимодействие с моделью реализовано через AsyncOpenAI и OpenAI-совместимый API. Для переключения провайдера достаточно изменить:

LLM_BASE_URL=...
LLM_API_KEY=...
LLM_MODEL=...

Основную бизнес-логику Telegram-бота изменять не требуется.

Известные ограничения

история диалога не сохраняется;
бот обрабатывает только текстовые сообщения;
отсутствует потоковая отправка ответа пользователю;
отсутствует ограничение частоты запросов;
отсутствует база данных;
отсутствуют роли пользователей и административная панель;
системный промпт и параметры генерации пока задаются в коде;
тесты и CI/CD пока не добавлены;
Docker Compose в текущей конфигурации ориентирован на локальную Ollama.

Безопасность

Не добавляйте .env в Git.
Не публикуйте Telegram Bot Token и API-ключи.
Используйте .env.example только как шаблон.
При компрометации Telegram-токена перевыпустите его через @BotFather.
В production-окружении передавайте секреты через переменные окружения или систему управления секретами.

Файл .env уже добавлен в .gitignore.

Автор

Булат Хатыпов

GitHub: BulatKSMNT
Telegram: @khat911

Статус проекта

Проект разработан как демонстрация интеграции Telegram-бота с локальными и облачными языковыми моделями через единый OpenAI-совместимый интерфейс. Проект разработан как демонстрация интеграции Telegram-бота с локальными и облачными языковыми моделями через единый OpenAI-совместимый интерфейс.

Name		Name	Last commit message	Last commit date
bot		bot
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
main.py		main.py
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation