simple-asr-server/README.MD

Simple ASR Service на базе Whisper

Простой сервис для распознавания речи с использованием OpenAI Whisper. Поддерживает различные форматы ответов, управление API-ключами без перезапуска и все параметры модели Whisper.

Особенности

• 🎯 Эндпоинт /transcribe для распознавания речи
• 🔑 Управление API-ключами без перезапуска сервиса
• 📊 Три формата ответа: json, simple, text/plain
• ⚙️ Поддержка всех параметров whisper.transcribe()
• 🐳 Docker и native запуск
• 🏥 Health check эндпоинт
• 🔄 Горячая перезагрузка API-ключей
• 🚀 GPU ускорение по умолчанию (NVIDIA/AMD)
• ⚙️ Централизованная конфигурация через .env файл

Требования

• Python 3.8+
• FFmpeg (для обработки аудио)
• Минимум 4GB RAM
• Свободное место для моделей (turbo ~1GB, large ~3GB)
• GPU с поддержкой CUDA или ROCm (рекомендуется)

Для Docker дополнительно:

• Docker + Docker Compose
• NVIDIA Docker runtime (для NVIDIA GPU)
• ROCm (для AMD GPU)

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

Запуск через Docker

git clone https://github.com/SlavaVlad/simple-asr-server.git ./asr
cd asr

# Для AMD GPU оставьте как есть
# Для NVIDIA GPU раскомментируйте соответствующую секцию в docker-compose.yml

docker compose up -d

Нативный запуск

git clone https://github.com/SlavaVlad/simple-asr-server.git ./asr
cd asr

chmod +x start_server.sh
./start_server.sh

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

Переменная	По умолчанию	Описание
HOST	0.0.0.0	IP адрес для привязки
PORT	9854	Порт сервера
DEFAULT_MODEL	turbo	Модель Whisper для загрузки
MODEL_DEVICE	cuda	Устройство: cuda, cpu, или auto
MODEL_DOWNLOAD_ROOT	./models	Директория для моделей
KEYS_FILE	./data/keys.txt	Файл с API ключами
LOG_LEVEL	info	Уровень логирования
HSA_OVERRIDE_GFX_VERSION	10.3.0	Версия GPU для AMD ROCm
AUDIO_SPEEDUP	1.25	Ускорение обработки аудио

Настройка GPU

По умолчанию сервис настроен для работы с NVIDIA GPU.

Для использования CPU:

MODEL_DEVICE=cpu

Доступные модели Whisper

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

Управление API-ключами

Автоматическое создание ключей

При первом запуске:

1. Если установлен openssl - генерируется безопасный 64-символьный ключ
2. Если openssl отсутствует - создается пустой файл ключей

Добавление/удаление ключей

1. Отредактируйте файл data/keys.txt (один ключ на строку, 64 hex символа)
2. Вызовите эндпоинт перезагрузки:

curl -X POST "http://localhost:9854/keys/reload" \
  -H "X-API-Key: your-api-key"

Пример data/keys.txt:

key1
key2

Генерация новых ключей

# Генерация нового ключа
openssl rand -hex 32

# Добавление в файл ключей
echo "$(openssl rand -hex 32)" >> data/keys.txt

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

POST /transcribe

Основной эндпоинт для распознавания речи.

Параметры

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

• audio_file - аудиофайл (form-data)

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

• format - формат ответа: json (по умолчанию), simple, text
• Все параметры whisper.transcribe():
  • language - язык аудио (auto-detect по умолчанию)
  • task - transcribe или translate
  • temperature - температура для генерации (0.0-1.0)
  • beam_size - размер луча для поиска
  • best_of - количество кандидатов для выбора лучшего
  • compression_ratio_threshold - порог сжатия для фильтрации
  • logprob_threshold - порог логарифмической вероятности
  • no_speech_threshold - порог отсутствия речи
  • condition_on_previous_text - использовать предыдущий текст как контекст
  • initial_prompt - начальная подсказка для модели
  • word_timestamps - временные метки слов (true/false)
  • prepend_punctuations - знаки препинания для добавления в начало
  • append_punctuations - знаки препинания для добавления в конец
  • clip_timestamps - временные метки для обрезки аудио
  • hallucination_silence_threshold - порог тишины для отрезания галлюцинаций

Примеры запросов

Простая транскрибация:

curl -X POST "http://localhost:9854/transcribe" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{}' \
  --form "audio_file=@audio.wav"

С параметрами:

curl -X POST "http://localhost:9854/transcribe" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "ru",
    "format": "simple",
    "word_timestamps": true,
    "temperature": 0.2
  }' \
  --form "audio_file=@audio.wav"

Только текст:

curl -X POST "http://localhost:9854/transcribe" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"format": "text"}' \
  --form "audio_file=@audio.wav"

Расширенные параметры:

curl -X POST "http://localhost:9854/transcribe" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en",
    "task": "translate",
    "temperature": 0.1,
    "beam_size": 5,
    "word_timestamps": true,
    "initial_prompt": "This is a technical presentation about AI",
    "format": "json"
  }' \
  --form "audio_file=@audio.wav"

Форматы ответов

json (полный ответ от Whisper):

{
  "text": "Привет, как дела?",
  "segments": [
    {
      "start": 0.0,
      "end": 2.5,
      "text": "Привет, как дела?",
      "words": [...]
    }
  ],
  "language": "ru"
}

simple (только текст):

{
  "text": "Привет, как дела?"
}

text (plain text):

Привет, как дела?

GET /health

Проверка состояния сервиса:

curl "http://localhost:9854/health"

Ответ:

{
  "status": "healthy",
  "model_loaded": true,
  "model_name": "turbo"
}

Коды ошибок

• 401 - API ключ не предоставлен
• 403 - Неверный API ключ
• 422 - Неверные параметры запроса
• 500 - Ошибка сервера/модели

Systemd сервис

Для автоматического запуска создайте systemd сервис:

sudo cp asr.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable asr
sudo systemctl start asr

Поддерживаемые форматы аудио

Все форматы, поддерживаемые FFmpeg:

• WAV, MP3, FLAC, M4A, OGG
• Видео форматы (извлекается аудио): MP4, AVI, MKV

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

Время обработки зависит от:

• Выбранной модели
• Длительности аудио
• Доступных ресурсов (CPU/GPU)

Примерные времена для 1 минуты аудио:

• tiny: ~2-5 секунд
• turbo: ~5-10 секунд
• large: ~15-30 секунд