Telegram Audio Bot

Телеграм бот для распознавания аудио сообщений на базе aiogram 3.x и Faster-Whisper

Требования

Для локального запуска:

• Python 3.11, 3.12 или 3.13 (Python 3.14 пока не поддерживается из-за зависимостей)
• ffmpeg (для обработки аудио файлов)

Для запуска через Docker (рекомендуется для продакшена):

• Docker и Docker Compose

Быстрый старт с Docker (рекомендуется)

Самый простой способ запустить бота:

# 1. Клонируйте репозиторий
git clone https://github.com/ваш-username/audio_bot.git
cd audio_bot

# 2. Создайте .env файл
cp .env.example .env
nano .env  # Добавьте ваш BOT_TOKEN

# 3. Запустите бота
docker compose up -d

# 4. Посмотрите логи
docker compose logs -f

Готово! Бот работает. Подробная инструкция по деплою на сервер: DEPLOY.md

Установка (без Docker)

1. Установите Python 3.13 (если еще не установлен):

Вариант А: Через Homebrew (рекомендуется для macOS)

brew install python@3.13

Вариант Б: Скачать с официального сайта Скачайте и установите Python 3.13 с python.org

2. Установите ffmpeg:

macOS:

brew install ffmpeg

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install ffmpeg

Windows: Скачайте с ffmpeg.org и добавьте в PATH

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

# Удалите старое окружение если оно есть:
rm -rf .venv

# Создайте новое с Python 3.13:
python3.13 -m venv .venv

# Или если команда выше не работает:
/opt/homebrew/bin/python3.13 -m venv .venv

# Активируйте окружение:
source .venv/bin/activate  # На Windows: .venv\Scripts\activate

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

pip install -r requirements.txt

5. Создайте файл .env на основе .env.example:

cp .env.example .env

6. Добавьте токен вашего бота в файл .env:

BOT_TOKEN=your_actual_bot_token

Примечание: При первом запуске бота автоматически скачается модель Whisper (~150 MB для модели "base"). Это займет несколько минут.

Запуск

python bot.py

Функциональность

• /start - приветственное сообщение с инструкциями
• Распознавание голосовых сообщений - отправьте голосовое сообщение, бот распознает речь и вернет текст
• Распознавание аудио файлов - отправьте аудио файл, бот распознает речь и вернет текст
• Поддержка русского языка с высоким качеством распознавания
• Работает полностью локально (не требует интернета после установки)

Технологии

• aiogram 3.x - фреймворк для Telegram ботов
• Faster-Whisper - быстрая и точная модель распознавания речи от OpenAI
• Python 3.13 - основной язык программирования

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

audio_bot/
├── bot.py                  # Основной файл бота с обработчиками
├── speech_recognition.py   # Модуль распознавания речи через Whisper
├── config.py               # Конфигурация и загрузка переменных окружения
├── requirements.txt        # Зависимости проекта
├── Dockerfile              # Docker образ для бота
├── docker-compose.yml      # Docker Compose конфигурация
├── .dockerignore           # Исключения для Docker
├── deploy.sh               # Автоматический скрипт деплоя на сервер
├── test-docker.sh          # Скрипт для локального тестирования Docker
├── .env.example            # Пример файла с переменными окружения
├── .env                    # Ваши переменные окружения (не коммитится)
├── .gitignore              # Исключения для git
├── .python-version         # Версия Python для проекта
├── temp/                   # Временные аудио файлы (создается автоматически)
├── DEPLOY.md               # Подробная инструкция по деплою на сервер
├── GITHUB.md               # Инструкция по загрузке проекта на GitHub
└── README.md               # Документация (этот файл)

Настройка модели Whisper

По умолчанию используется модель "base" (~150 MB). Вы можете изменить модель в файле speech_recognition.py:21:

• tiny - самая быстрая, но менее точная (~75 MB)
• base - хороший баланс (используется по умолчанию, ~150 MB)
• small - более точная, медленнее (~500 MB)
• medium - высокая точность, требует больше ресурсов (~1.5 GB)
• large - максимальная точность, очень медленная (~3 GB)

Управление Docker контейнером

# Запуск бота
docker compose up -d

# Просмотр логов
docker compose logs -f

# Остановка бота
docker compose stop

# Перезапуск бота
docker compose restart

# Полная остановка и удаление
docker compose down

# Обновление бота после изменений
docker compose up -d --build

# Проверка статуса
docker compose ps

# Статистика использования ресурсов
docker stats telegram-audio-bot

Деплой на сервер

Подробная пошаговая инструкция по развертыванию бота на сервере через SSH: DEPLOY.md

Краткая версия:

1. Установите Docker на сервер
2. Клонируйте репозиторий
3. Создайте .env с токеном бота
4. Запустите docker compose up -d

Производительность

• Скорость распознавания: ~8-15 секунд на голосовое сообщение (на CPU)
• Использование памяти: ~500 MB - 1 GB
• Модель загружается один раз и остается в памяти
• Поддержка до 3 параллельных запросов

Возможные проблемы

Бот не отвечает на второе сообщение

Проблема решена использованием ThreadPoolExecutor для асинхронной обработки

Медленное распознавание

• Используйте модель tiny вместо base
• Убедитесь что на сервере достаточно CPU
• Рассмотрите использование GPU (требует другой сборки faster-whisper)

Ошибка "ModuleNotFoundError: No module named 'requests'"

pip install requests
# Или переустановите зависимости:
pip install -r requirements.txt