Nika ASR Service

Сервис автоматического распознавания речи (ASR) для асинхронной обработки аудио/видео файлов на основе WhisperX и Redis Queue. Предоставляет масштабируемый REST API для фоновой транскрибации с поддержкой управления моделями и задачами.

Основные возможности

• Фоновая транскрибация: Загрузка аудио/видео файлов и асинхронная обработка через очереди
• Управление моделями: Динамическая загрузка и кеширование моделей WhisperX
• Управление задачами: Просмотр, отмена и перезапуск задач транскрибации
• Масштабируемость: Поддержка нескольких воркеров для обработки нагрузки
• API аутентификация: Простая защита через API Key
• Rate Limiting: Ограничение количества одновременных задач на пользователя
• Логирование: Структурированное логирование с loguru
• Health Checks: Проверка здоровья сервиса

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

• FastAPI — асинхронный веб-фреймворк для создания API (ASGI)
• PostgreSQL — СУБД
• WhisperX — модели и инструменты для ASR
• pyannote.audio — (опционально) диаризация и выделение говорящих
• Redis — брокер и хранилище для очередей и кеша
• RQ (Redis Queue) — очередь фоновых задач
• Loguru — структурированное логирование
• Docker & Docker Compose — контейнеризация и оркестрация

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

nika-asr/
├── Dockerfile
├── docker-compose.yml
├── README.md
├── models/                      # Модели Whisper
├── src/                         # Код модулей
├── tests/                       # Тесты
│   ├── __init__.py
│   └── test_api.py
└── .env.example                 # Файл с переменными окружения (пример)

Примечание: структура отражает текущее содержимое репозитория — основные модули находятся в

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

Docker

Сервис будет доступен на http://localhost:8030

API Документация

После запуска FastAPI автоматически генерирует OpenAPI документацию:

• Swagger UI: http://localhost:8030/docs
• ReDoc: http://localhost:8030/redoc

Аутентификация

Все API вызовы требуют заголовка

Основные эндпоинты

• POST /api/v1/transcribe
  - Загрузка файла для транскрибации
• GET /api/v1/tasks/{task_id}/status
  - Статус задачи
• GET /api/v1/tasks/{task_id}/result
  - Результат транскрибации
• GET /api/v1/models
  - Список доступных моделей
• POST /api/v1/models/{model_name}/load
  - Загрузка модели
• GET /api/v1/tasks
  - Список задач
• POST /api/v1/tasks/{task_id}/cancel
  - Отмена задачи
• POST /api/v1/tasks/{task_id}/restart
  - Перезапуск задачи

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

Модели WhisperX

Сервис поддерживает следующие модели WhisperX для транскрибации:

Рекомендации по выбору модели

• tiny/base: Используйте для быстрого прототипирования или когда точность не критична
• small: Хороший баланс между скоростью и качеством для большинства задач
• medium/large-v2: Для высококачественной транскрибации
• large-v3: Самая новая и точная модель (рекомендуется по умолчанию)

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

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

Сервис настраивается через переменные окружения (с префиксом

Основные настройки

• ASR_API_KEY
  - API ключ для аутентификации (по умолчанию:
  development-key-123
  )

Redis настройки

• ASR_REDIS_URL
  - URL Redis сервера (по умолчанию:
  redis://localhost:6379/0
  )

WhisperX модели

• ASR_MODEL_CACHE_DIR
  - Директория для кеша моделей (по умолчанию:
  ~/.cache/whisperx-models
  )
• ASR_DEFAULT_MODEL
  - Модель по умолчанию для транскрибации (по умолчанию:
  large-v2
  )

Файловые ограничения

• ASR_MAX_UPLOAD_SIZE_MB
  - Максимальный размер загружаемого файла в MB (по умолчанию:
  100
  )
• ASR_TEMP_DIR
  - Директория для временных файлов (по умолчанию:
  /tmp/nika-asr
  )

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

• ASR_DEFAULT_JOB_TIMEOUT
  - Таймаут выполнения задачи в секундах (по умолчанию:
  600
  )

CORS настройки

• ASR_ALLOWED_ORIGINS
  - Разрешенные origins для CORS (по умолчанию:
  ["http://localhost", "http://localhost:8000"]
  )

Пример .env файла

Архитектура

• FastAPI приложение обрабатывает HTTP запросы
• Redis Queue управляет фоновыми задачами
• WhisperX выполняет транскрибацию аудио
• Модели кешируются локально для повторного использования
• Временные файлы удаляются после обработки

Масштабируемость

• Запуск нескольких воркеров:
  docker-compose up --scale worker=3
• Использование кластера Redis для высокой доступности
• Horizontal scaling через балансировку нагрузки

Разработка

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

Аутентификация

• API Key: Все эндпоинты защищены фиксированным API ключом
• Header:
  X-API-Key: your-api-key
• Рекомендация: Используйте сильные, уникальные ключи в продакшене

Rate Limiting

• Ограничения: Максимум 3 одновременные задачи на пользователя
• Реализация: Через slowapi middleware
• Масштабирование: Настраивается через конфигурацию

Валидация данных

• Файлы: Проверка типа, размера и формата файлов
• Модели: Валидация доступности моделей перед загрузкой
• Параметры: Строгая типизация через Pydantic

Мониторинг

Логирование

Сервис использует структурированное логирование с loguru:

• Уровни: DEBUG, INFO, WARNING, ERROR
• Формат: JSON для продакшена, читаемый для разработки
• Ротация: Автоматическая ротация лог файлов

Метрики

• Health Check:
  /api/v1/health
  - проверка работоспособности
• Queue Status: Мониторинг состояния RQ очередей
• Model Loading: Отслеживание загрузки моделей
• Task Progress: Прогресс выполнения задач

Развертывание

Production Docker Compose

Environment Variables

Масштабирование воркеров

Благодарности/использованные решения

• Whisper - Whisper is an ASR model developed by OpenAI, trained on a large dataset of diverse audio. Whilst it does produces highly accurate transcriptions, the corresponding timestamps are at the utterance-level, not per word, and can be inaccurate by several seconds. OpenAI's whisper does not natively support batching.
• WhisperX - library for fast automatic speech recognition with word-level timestamps and speaker diarization.
• Pyannote - pyannote.audio is an open-source toolkit written in Python for speaker diarization.

Лицензия

MIT License