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

```bash
git clone https://github.com/SlavaVlad/simple-asr-server.git ./asr
cd asr
docker compose up -d
```

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

```bash
git clone https://github.com/SlavaVlad/simple-asr-server.git ./asr
cd asr
chmod +x start_server.sh
./start_server.sh
```

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

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

```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. Вызовите эндпоинт перезагрузки:

```bash
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` - порог тишины для детекции галлюцинаций

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

**Простая транскрибация:**
```bash
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"
```

**С параметрами:**
```bash
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"
```

**Только текст:**
```bash
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"
```

**Расширенные параметры:**
```bash
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):**
```json
{
  "text": "Привет, как дела?",
  "segments": [
    {
      "start": 0.0,
      "end": 2.5,
      "text": "Привет, как дела?",
      "words": [...]
    }
  ],
  "language": "ru"
}
```

**simple (только текст):**
```json
{
  "text": "Привет, как дела?"
}
```

**text (plain text):**
```
Привет, как дела?
```

### GET /health

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

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

Ответ:
```json
{
  "status": "healthy",
  "model_loaded": true,
  "model_name": "turbo"
}
```

### POST /keys/reload

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

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

### GET /keys/count

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

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

## Коды ошибок

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

## Systemd сервис

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

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