Netology Transcription Bot

Telegram бот для автоматической транскрипции видеоуроков с платформы Netology. Бот получает ссылку на урок, скачивает видео, извлекает аудио и создает текстовую транскрипцию с помощью OpenAI Whisper.

🎯 Возможности

• 📹 Автоматическое скачивание видео с уроков Netology
• 🎵 Извлечение аудио из видео
• 🎤 Транскрипция аудио через Whisper (OpenAI)
• 💾 Кэширование результатов транскрипции
• 📋 Очередь задач на ARQ (Asynchronous RQ) для обработки нескольких запросов
• 🔄 Автоматический retry при ошибках обработки
• 🔐 Контроль доступа по списку разрешенных пользователей
• 📊 Мониторинг статуса задач через команды бота

🏗️ Архитектура

См. подробное описание архитектуры в документации.

📋 Требования

• Python 3.13+
• Docker и Docker Compose
• Redis (запускается через docker-compose)
• FFmpeg (устанавливается в Docker образе)

🚀 Быстрый старт

1. Клонирование репозитория

git clone <repository-url>
cd netology

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

Скопируйте .env.example в .env и заполните необходимые переменные:

cp .env.example .env

Отредактируйте .env и укажите:

Обязательные переменные:

• NETOLOGY_LOGIN - ваш логин на Netology
• NETOLOGY_PASSWORD - ваш пароль на Netology
• TELEGRAM_BOT_TOKEN - получите у @BotFather
• ALLOWED_TELEGRAM_USER_IDS - список ID пользователей через запятую (можно узнать у @userinfobot)

Опциональные переменные:

• WHISPER_MODEL - модель Whisper (по умолчанию: turbo)
• WHISPER_DEVICE - устройство для обработки (cpu или cuda)
• REDIS_URL - URL Redis (по умолчанию: redis://localhost:6379/0)
• ARQ_MAX_JOBS - количество одновременно выполняемых задач (рекомендуется: 1)
• И другие настройки ARQ (см. .env.example)

Важно:

• Полный список переменных с описаниями доступен в .env.example
• Для транскрипции рекомендуется использовать ARQ_MAX_JOBS=1, так как Whisper требует много памяти

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

С помощью Makefile (рекомендуется):

make up-build    # Собрать и запустить
make logs-bot    # Просмотр логов бота
make help        # Список всех команд

Или напрямую через Docker Compose:

docker compose up -d --build

Важно: Docker Compose автоматически создаст следующие директории на хосте:

• ./data/ - база данных транскрипций (сохраняется между перезапусками)
• ./temp/ - временные файлы (очищается при перезапуске)
• Docker volume whisper_cache - кэш модели Whisper (~10 ГБ, сохраняется между перезапусками)

Сервисы:

• bot - Telegram бот (принимает запросы от пользователей)
• arq-worker - ARQ воркер (обрабатывает задачи транскрипции)
• redis - Redis сервер (брокер сообщений для ARQ)

⚠️ Требования к памяти:

• Модель "turbo" требует минимум 8-12 ГБ RAM для загрузки и работы
• Если контейнер падает с кодом 137 (OOM), увеличьте лимит памяти в docker-compose.yml или используйте меньшую модель (например, base или small)

4. Первый запуск - загрузка модели Whisper

⚠️ Важно: При первом запуске контейнера бот автоматически начнет загрузку модели Whisper.

• Модель "turbo" весит ~10 ГБ
• Загрузка может занять 10-30 минут в зависимости от скорости интернета
• После первой загрузки модель сохраняется в Docker volume и не будет скачиваться повторно
• База данных транскрипций сохраняется в ./data/transcriptions.db и не теряется при перезапуске контейнера

Вы можете отслеживать процесс загрузки:

make logs-bot        # Логи бота
make logs-arq        # Логи ARQ воркера
# Или: docker compose logs -f bot arq-worker

Важно: После запуска убедитесь, что оба сервиса работают:

• bot - должен быть в статусе "Up"
• arq-worker - должен быть в статусе "Up"

Проверить статус:

docker compose ps

После завершения загрузки модели бот автоматически запустится.

5. Проверка работы

Откройте Telegram и найдите вашего бота. Отправьте команду /start или /help для получения справки.

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

См. подробное руководство по использованию в документации.

🔧 Локальная разработка

См. руководство по локальной разработке в документации.

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

См. подробную информацию о конфигурации в документации.

🐳 Docker команды

С помощью Makefile (рекомендуется)

make help           # Показать все доступные команды
make up-build       # Собрать и запустить контейнеры
make logs-bot       # Просмотр логов бота
make logs-arq       # Просмотр логов ARQ воркера
make logs-redis     # Просмотр логов Redis
make logs           # Просмотр логов всех сервисов
make restart        # Перезапустить контейнеры
make down           # Остановить контейнеры
make shell          # Открыть shell в контейнере бота
make ps             # Показать статус контейнеров
make rebuild        # Пересобрать и перезапустить
make clean          # Остановить и удалить контейнеры
make clean-all      # Полная очистка (включая volumes)
make download-model # Скачать модель Whisper вручную
make redis-cli      # Открыть Redis CLI

Напрямую через Docker Compose

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

docker compose build

Запуск:

docker compose up -d

Просмотр логов:

# Все логи
docker compose logs -f

# Только бот
docker compose logs -f bot

# Или напрямую
docker logs netology-bot-1 -f

Остановка:

docker compose down

Очистка данных:

# Остановить и удалить контейнеры
docker compose down

# Удалить volumes (включая кэш Whisper и Redis данные)
docker compose down -v

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

См. руководство по устранению неполадок в документации.

🤝 Внесение вклада

Если вы хотите внести свой вклад в проект:

1. Создайте ветку от develop:

   git checkout develop
   git pull origin develop
   git checkout -b feature/your-feature-name

2. Внесите свои изменения и закоммитьте их

3. Отправьте изменения в ваш форк:

   git push origin feature/your-feature-name

4. Создайте Merge Request (MR) на ветку develop

Важно: Все изменения должны быть направлены в ветку develop, а не в main.

📝 Лицензия

👤 Автор

dark_loop (alexander@gvozdev.net)