evo-foundation-models-tg-bot-lab

ИИ-бот для Telegram, который автоматически сохраняет сообщения из чатов и предоставляет интеллектуальный анализ, включая краткие изложения и извлечение задач. Построен на Python, LangChain с поддержкой локального и облачного хранения.

Возможности

Основной функционал

• Автоматическое логирование сообщений: Сохраняет все сообщения чата в оптимизированном JSON формате
• ИИ-анализ: Использует LangChain с пользовательскими ИИ-моделями для интеллектуальной обработки
• Краткие изложения чатов: Генерирует краткие изложения разговоров в чате на русском языке
• Извлечение задач: Автоматически выявляет и извлекает задачи, поручения и пункты действий
• Отслеживание отправителей: Захватывает информацию об отправителе и метаданные сообщений
• Поддержка множественных платформ: Работает с приватными чатами, публичными каналами и групповыми беседами

Варианты хранения

• Локальное хранение: Сохраняет данные в локальных JSON файлах, организованных по чатам и датам
• S3 хранение: Поддержка облачного хранения с AWS S3 или совместимыми с S3 сервисами
• Гибкая организация: Данные структурированы как chat_id/DDMMYYYY.json для легкого доступа

ИИ-возможности

• Умные краткие изложения: ИИ-генерируемые краткие изложения чатов с основными темами и ключевыми моментами
• Управление задачами: Извлекает задачи с исполнителями, описаниями и сроками
• Осведомленность о контексте: Понимает контекст разговора и взаимосвязи
• Поддержка русского языка: Оптимизирован для обработки русского языка

Технические особенности

• Конфигурация окружения: Гибкая настройка через переменные окружения
• Типобезопасность: Полная валидация моделей Pydantic и проверка типов
• Асинхронная обработка: Высокопроизводительная асинхронная обработка сообщений
• Статистика: Статистика сообщений и аналитика
• Поддержка Docker: Полная контейнеризация с Docker и Docker Compose
• Health Check: Встроенные эндпоинты для мониторинга состояния на порту 8080

Установка

Требования

• Python 3.10 или выше
• Токен Telegram-бота (получить у @BotFather)
• ИИ API ключ (для ИИ-функций)
• S3 учетные данные (опционально, для облачного хранения)

Быстрая настройка

1. Клонировать репозиторий:

   git clone <repository-url>
   cd evo-foundation-models-tg-bot-lab

2. Автоматическая настройка окружения:

   # Создать виртуальное окружение и установить зависимости
   python setup.py venv
   
   # Или для разработки с дополнительными инструментами
   python setup.py dev

3. Активировать виртуальное окружение:

   # Windows
   .venv\Scripts\activate
   
   # Linux/Mac
   source .venv/bin/activate

4. Настроить окружение:

   cp env.example .env
   # Отредактировать .env с вашими учетными данными

Использование

Запуск бота

python -m chat_bot.bot

Команды бота

• /summary - Генерировать ИИ-краткое изложение недавних сообщений чата
• /tasks - Извлекать и перечислять задачи из разговоров в чате

Добавление бота в чаты

1. Приватные чаты: Добавить бота как администратора
2. Публичные каналы: Добавить бота как администратора
3. Групповые чаты: Добавить бота как администратора

Необходимые разрешения бота:

• Читать сообщения
• Отправлять сообщения (для ответов на команды)

Структура данных

Организация файлов

chat_logs/
├── chat_id_1/
│   ├── 12082025.json
│   ├── 13082025.json
│   └── ...
├── chat_id_2/
│   ├── 12082025.json
│   └── ...
└── ...

Формат сообщений

{
  "messages": [
    {
      "timestamp": "2023-12-25T10:30:45.123456",
      "message_id": 12345,
      "sender_name": "Иван Иванов",
      "text": "Привет, мир!"
    }
  ]
}

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

Переменные окружения

Переменная	Обязательно	По умолчанию	Описание
TELEGRAM_BOT_TOKEN	Да	-	Токен бота Telegram от @BotFather
AI_API_KEY	Да	-	ИИ API ключ сервиса
AI_MODEL	Нет	t-tech/T-pro-it-2.0	ИИ модель для использования
AI_BASE_URL	Нет	https://foundation-models.api.cloud.ru/v1/	Базовый URL ИИ сервиса
AI_TEMPERATURE	Нет	0.3	Температура генерации ИИ
AI_MAX_TOKENS	Нет	500	Максимальное количество токенов для ответов ИИ
USE_LOCAL_STORAGE	Нет	false	Принудительно использовать локальное хранение вместо S3
DATA_DIR	Нет	chat_logs	Локальная директория данных
OBJECT_STORAGE_BUCKET_NAME	Нет*	-	Имя S3 бакета (*обязательно если не используется локальное хранение)
OBJECT_STORAGE_ACCESS_KEY_ID	Нет*	-	AWS ключ доступа (*обязательно если не используется локальное хранение)
OBJECT_STORAGE_SECRET_ACCESS_KEY	Нет*	-	AWS секретный ключ (*обязательно если не используется локальное хранение)
OBJECT_STORAGE_REGION	Нет	us-east-1	AWS регион
OBJECT_STORAGE_ENDPOINT_URL	Нет	-	Пользовательский S3 URL эндпоинта
OBJECT_STORAGE_ROOT_DIR	Нет	chat_logs	Корневая S3 директория

Развертывание в Cloud.ru Artifact Registry

Сборка образа

docker build -t evo-foundation-models-tg-bot-lab .

Загрузка образа в Artifact Registry

docker tag evo-foundation-models-tg-bot-lab <REGISTRY-NAME>.cr.cloud.ru/evo-foundation-models-tg-bot-lab:latest
docker push <REGISTRY-NAME>.cr.cloud.ru/evo-foundation-models-tg-bot-lab:latest

Замените на название вашего Artifact Registry

Разработка

Настройка среды разработки

# Установить с зависимостями разработки
python setup.py dev

# Или вручную
pip install -e .[dev]

Инструменты качества кода

Проект использует строгие стандарты качества кода:

# Форматирование кода
black .
isort .

# Линтинг кода
flake8 chat_bot/
pylint chat_bot/

# Проверка типов
mypy --strict chat_bot/

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

chat_bot/
├── models/           # Pydantic модели данных
├── prompts/          # Шаблоны ИИ промптов
├── assistant.py      # Реализация ИИ ассистента
├── bot.py           # Основная логика бота
├── config.py        # Управление конфигурацией
├── formatter.py     # Форматирование сообщений
├── repository.py    # Реализация S3 хранения
├── repository_local.py  # Реализация локального хранения
└── repository_base.py   # Базовый интерфейс репозитория

Соображения безопасности

• Храните чувствительные токены в файле .env (никогда не коммитьте в систему контроля версий)
• Используйте непривилегированного пользователя в Docker контейнерах
• Реализуйте соответствующий контроль доступа для логов чатов
• Регулярные обновления безопасности для зависимостей
• Мониторинг разрешений бота в Telegram

Устранение неполадок

Частые проблемы

1. Бот не отвечает:

   • Проверьте правильность токена бота
   • Убедитесь, что бот добавлен как администратор
   • Проверьте разрешения бота в Telegram

2. ИИ функции не работают:

   • Проверьте действительность ИИ API ключа
   • Проверьте доступность ИИ сервиса
   • Проверьте конфигурацию ИИ модели

3. Проблемы с хранением:

   • Проверьте S3 учетные данные (если используется облачное хранение)
   • Проверьте разрешения файлов для локального хранения
   • Убедитесь в достаточном дисковом пространстве

4. Ошибки разрешений:

   • Проверьте разрешения пользователя контейнера
   • Проверьте разрешения монтирования томов
   • Проверьте права доступа к файловой системе

Режим отладки

# Запустить в интерактивном режиме
docker run -it --rm \
  -e TELEGRAM_BOT_TOKEN=your_token \
  -e AI_API_KEY=your_key \
  telegram-chat-bot bash

Мониторинг

Проверки здоровья

Бот включает встроенный веб-сервер для проверок здоровья на порту 8080:

Доступные эндпоинты

• GET / - Информация о сервисе
• GET /health - Базовая проверка здоровья
• GET /health/ready - Проверка готовности (для Kubernetes)
• GET /health/live - Проверка жизнеспособности (для Kubernetes)

Примеры использования

# Проверить здоровье контейнера
docker inspect telegram-chat-bot | grep Health -A 10

# Проверить эндпоинт здоровья (с curl)
curl http://localhost:8080/health

# Проверить эндпоинт здоровья (с Python)
python -c "import urllib.request; print(urllib.request.urlopen('http://localhost:8080/health').read().decode())"

# Проверить готовность
curl http://localhost:8080/health/ready

# Получить информацию о сервисе
curl http://localhost:8080/

Docker Health Check

Контейнер автоматически проверяет здоровье через HTTP запросы с использованием Python:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')" || exit 1

Логи

# Просмотр логов в реальном времени
docker-compose logs -f

# Или для ручного Docker
docker logs -f telegram-chat-bot

Вклад в проект

1. Форкните репозиторий
2. Создайте ветку функции
3. Внесите изменения
4. Добавьте тесты, если применимо
5. Убедитесь, что инструменты качества кода проходят
6. Отправьте pull request

Лицензия

Этот проект лицензирован под MIT License.

Поддержка

Для проблем и вопросов:

1. Проверьте раздел устранения неполадок
2. Просмотрите логи для сообщений об ошибках
3. Создайте issue с подробной информацией
4. Включите детали окружения и логи ошибок

Ссылки

• Telegram Bot API
• LangChain Documentation
• Pydantic Documentation
• Docker Documentation