simple-asr-server/README.MD

Simple ASR Service на базе Whisper

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

Особенности

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

Требования

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

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

• Docker + Docker Compose
• GPU AMD с поддержкой ROCm (опционально)

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

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

git clone https://github.com/SlavaVlad/simple-asr-server.git ./asr
cd asr
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

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

Создайте файл .env для настройки переменных окружения:

HOST=0.0.0.0
PORT=9854
DEFAULT_MODEL=turbo
MODEL_DOWNLOAD_ROOT=./models
KEYS_FILE=./data/keys.txt
LOG_LEVEL=info

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

• tiny - самая быстрая, наименее точная
• base - баланс скорости и качества
• small - хорошее качество
• medium - лучшее качество
• large - максимальное качество
• turbo - оптимизированная версия (рекомендуется)

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

Создание ключей

При первом запуске автоматически создается файл data/keys.txt с демонстрационным ключом.

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

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

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

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

key1
key2

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"
}

POST /keys/reload

Перезагрузка API-ключей без перезапуска:

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

GET /keys/count

Количество активных ключей:

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

Коды ошибок

• 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 секунд