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. Клонировать репозиторий:

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

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

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

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

Запуск бота

Команды бота

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Разработка

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

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

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

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

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. Ошибки разрешений:

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

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

Мониторинг

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

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

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

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

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

Docker Health Check

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

Логи

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

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

Лицензия

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

Поддержка

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

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

Ссылки

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