- рефакторинг приложения

- снова изменения в Readme - работа над валидацией параметров - большая гибкость и конфигурироемость
2025-09-06 21:05:56 +03:00
parent 3f97810f89
commit fcae47cad1
8 changed files with 475 additions and 334 deletions
--- a/README.MD
+++ b/README.MD
@@ -1,113 +1,269 @@
-# ASR service на базе Whisper + AMD ROCm
+# Simple ASR Service на базе Whisper

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

 ## Требования

- GPU AMD с поддержкой ROCm (RX5000, RX6000 +)
- Установленный ROCm
- Docker + Compose plugin
- Debian based linux (для инструкции)
- Минимум 8GB RAM
- Минимум 2GB свободного места + место для ROCm + Модели (turbo ~3.5GB)
+- Python 3.8+
+- FFmpeg (для обработки аудио)
+- Минимум 4GB RAM
+- Свободное место для моделей (turbo ~1GB, large ~3GB)

-## Установка и запуск
+Для Docker дополнительно:
+- Docker + Docker Compose
+- GPU AMD с поддержкой ROCm (опционально)

-### 1. Клонирование репозитория
+## Быстрый старт
+
+### Запуск через Docker

 ```bash
 git clone https://github.com/SlavaVlad/simple-asr-server.git ./asr
 cd asr
-```
-
-### 2. Создание Docker-образа
-
-Перед запуском в файле docker-compose.yml можно изменить всякие переменные окружения, например модель по умолчанию.
-```bash
 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-ключами

-При первом запуске сервиса автоматически создается файл `keys.txt` со случайно сгенерированным API-ключом. 
+### Создание ключей

-### Добавление новых ключей
-1. Откройте файл `keys.txt`
-2. Добавьте новые ключи, каждый с новой строки
-3. Перезапустите сервис
+При первом запуске автоматически создается файл `data/keys.txt` с демонстрационным ключом.

-Пример содержимого `keys.txt`:
-```
-f7a9c2b3d4e5a6b7c8d9e0f1a2b3c4d5
-e8b9a2c3d4f5g6h7i8j9k0l1m2n3o4p5
-```
+### Добавление/удаление ключей

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

 ```bash
-curl -X POST "http://localhost:9854/transcribe" \
-     -H "x-api-key: ВАШ_КЛЮЧ" \
-     -F "file=@путь_к_аудио_файлу" \
-     -F "model_name=turbo" # (необязательно, по умолчанию turbo)
+curl -X POST "http://localhost:9854/keys/reload" \
+  -H "X-API-Key: your-api-key"
 ```

-### Ответ API
+Пример `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
 {
-    "transcription": [...],
-    "text": "распознанный текст",
-    "metrics": {
-        "processing_time_seconds": 1.23,
-        "characters_per_second": 45.6,
-        "audio_realtime_ratio": 2.34,
-        "audio_duration": 5.67,
-        "text_length": 89
+  "text": "Привет, как дела?",
+  "segments": [
+    {
+      "start": 0.0,
+      "end": 2.5,
+      "text": "Привет, как дела?",
+      "words": [...]
    }
+  ],
+  "language": "ru"
 }
 ```

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

-## Метрики производительности
+**text (plain text):**
+```
+Привет, как дела?
+```

-API возвращает следующие метрики:
- `processing_time_seconds`: время обработки в секундах
- `characters_per_second`: скорость обработки (символов в секунду)
- `audio_realtime_ratio`: отношение длительности аудио к времени обработки
- `audio_duration`: длительность аудио в секундах
- `text_length`: количество символов в распознанном тексте
+### GET /health

-## Поддерживаемые форматы
+Проверка состояния сервиса:

-Поддерживаются все аудиоформаты, которые может обработать FFmpeg. Файлы автоматически конвертируются в нужный формат.
-
-## Решение проблем
-
-### Проверка статуса сервиса
 ```bash
-curl http://localhost:9854/docs
+curl "http://localhost:9854/health"
 ```

-### Частые проблемы
+Ответ:
+```json
+{
+  "status": "healthy",
+  "model_loaded": true,
+  "model_name": "turbo"
+}
+```

-1. **Ошибка доступа к GPU**
-   ```bash
-   sudo usermod -a -G video,render $USER
-   sudo reboot
-   ```
+### POST /keys/reload

-2. **Ошибка 403**
-   - Проверьте правильность API-ключа
-   - Убедитесь, что ключ добавлен в файл keys.txt
-   - Перезапустите сервис
+Перезагрузка API-ключей без перезапуска:

-## Лицензия
+```bash
+curl -X POST "http://localhost:9854/keys/reload" \
+  -H "X-API-Key: your-api-key"
+```

-MIT License
+### 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 секунд