poturaevpetr
213 lines
6.1 KiB
Markdown
213 lines
6.1 KiB
Markdown
# FileAudioAPI
|
||
|
||
Сервис для хранения аудиофайлов, индексации файлов, записи и выдачи результатов распознавания, реализованный на **FastAPI**.
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
```bash
|
||
# Клонировать и перейти в директорию
|
||
cd /Users/petr/SpeechAnalytics/FileAudioAPI
|
||
|
||
# Запуск с Docker (рекомендуется)
|
||
docker-compose up -d
|
||
|
||
# Или использовать Makefile
|
||
make up
|
||
```
|
||
|
||
Приложение будет доступно по адресу: **http://localhost:8000**
|
||
|
||
API документация:
|
||
- 📚 **Swagger UI**: http://localhost:8000/api/v1/docs
|
||
- 📖 **ReDoc**: http://localhost:8000/api/v1/redoc
|
||
|
||
## 📚 Документация
|
||
|
||
- 📘 [Quick Start Guide](START.md) - Быстрый старт
|
||
- 📗 [API Documentation](README_FASTAPI.md) - Полная документация API
|
||
- 📕 [Docker Deployment](README_DOCKER.md) - Развертывание в Docker
|
||
|
||
## 🎯 Возможности
|
||
|
||
- ✅ Загрузка аудиофайлов (MP3, WAV, OGG, FLAC, M4A, AAC)
|
||
- ✅ Хранение файлов с автоматической индексацией
|
||
- ✅ Асинхронное распознавание аудио в фоне
|
||
- ✅ Отслеживание статуса распознавания
|
||
- ✅ Получение результатов распознавания
|
||
- ✅ RESTful API с автоматической документацией
|
||
- ✅ Валидация данных с Pydantic
|
||
- ✅ Docker поддержка
|
||
|
||
## 🏗️ Архитектура
|
||
|
||
```
|
||
apiApp/
|
||
├── schemas/ # Pydantic модели (валидация)
|
||
├── services/ # Business logic (CRUD операции)
|
||
├── routers/ # API endpoints (контроллеры)
|
||
├── database/ # SQLAlchemy модели
|
||
├── dbApi/ # Legacy compatibility layer
|
||
├── config.py # Конфигурация
|
||
└── database.py # SQLAlchemy настройка
|
||
```
|
||
|
||
## 🔧 Технологии
|
||
|
||
- **FastAPI** - Современный веб-фреймворк
|
||
- **SQLAlchemy 2.0** - ORM для работы с БД
|
||
- **Pydantic** - Валидация данных
|
||
- **Uvicorn** - ASGI сервер
|
||
- **Docker** - Контейнеризация
|
||
|
||
## 📋 Основные endpoints
|
||
|
||
| Метод | Endpoint | Описание |
|
||
|-------|----------|----------|
|
||
| POST | `/api/v1/upload` | Загрузка аудиофайла |
|
||
| GET | `/api/v1/audio/list` | Список всех файлов |
|
||
| GET | `/api/v1/audio/{id}` | Информация о файле |
|
||
| GET | `/api/v1/audio/file/{id}` | Скачать файл |
|
||
| DELETE | `/api/v1/audio/delete/{id}` | Удалить файл |
|
||
| POST | `/api/v1/recognize/{id}` | Запустить распознавание |
|
||
| GET | `/api/v1/recognize/{id}` | Статус распознавания |
|
||
| GET | `/api/v1/recognize/task/{task_id}` | Статус по task_id |
|
||
| GET | `/api/v1/recognize/{id}/result` | Результат распознавания |
|
||
|
||
## 🛠️ Установка и запуск
|
||
|
||
### С Docker (рекомендуется)
|
||
|
||
```bash
|
||
# Использование Makefile
|
||
make up
|
||
|
||
# Или напрямую с Docker Compose
|
||
docker-compose up -d
|
||
|
||
# Просмотр логов
|
||
make logs
|
||
# или
|
||
docker-compose logs -f
|
||
```
|
||
|
||
### Локально
|
||
|
||
```bash
|
||
# Установка зависимостей
|
||
make install
|
||
# или
|
||
pip3 install -r requirements.txt
|
||
|
||
# Создание базы данных
|
||
make db-migrate
|
||
|
||
# Запуск
|
||
make dev
|
||
# или
|
||
python3 run.py
|
||
```
|
||
|
||
## 🔧 Makefile команды
|
||
|
||
```bash
|
||
make help # Показать все команды
|
||
make build # Собрать Docker образ
|
||
make up # Запустить контейнеры
|
||
make down # Остановить контейнеры
|
||
make restart # Перезапустить
|
||
make logs # Логи
|
||
make shell # Shell в контейнере
|
||
make test # Запуск тестов
|
||
make clean # Очистка
|
||
```
|
||
|
||
## 📝 Примеры использования
|
||
|
||
### Загрузка файла
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/upload \
|
||
-F "file=@audio.mp3"
|
||
```
|
||
|
||
### Запуск распознавания
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/recognize/{audio_id}
|
||
```
|
||
|
||
### Получение статуса
|
||
|
||
```bash
|
||
curl http://localhost:8000/api/v1/recognize/{audio_id}
|
||
```
|
||
|
||
### Получение результата
|
||
|
||
```bash
|
||
curl http://localhost:8000/api/v1/recognize/{audio_id}/result
|
||
```
|
||
|
||
## 🔒 Production
|
||
|
||
Для production развертывания:
|
||
|
||
1. Используйте PostgreSQL вместо SQLite
|
||
2. Настройте Redis для хранения статусов задач
|
||
3. Ограничьте CORS origins
|
||
4. Добавьте аутентификацию
|
||
5. Настройте SSL/HTTPS
|
||
6. Используйте несколько workers
|
||
|
||
Подробнее в [Docker Deployment Guide](README_DOCKER.md)
|
||
|
||
## 🧪 Тестирование
|
||
|
||
```bash
|
||
# Запуск тестов
|
||
make test
|
||
|
||
# Или напрямую
|
||
pytest tests/ -v
|
||
```
|
||
|
||
## 📊 Мониторинг
|
||
|
||
```bash
|
||
# Health check
|
||
curl http://localhost:8000/health
|
||
|
||
# Docker stats
|
||
docker stats file-audio-api
|
||
|
||
# Логи
|
||
docker-compose logs -f app
|
||
```
|
||
|
||
## 🤝 Рефакторинг
|
||
|
||
Проект был успешно рефакторин из Flask в FastAPI с улучшением архитектуры:
|
||
|
||
**Основные изменения:**
|
||
- ✅ Многослойная архитектура (schemas → services → routers)
|
||
- ✅ Разделение по доменам
|
||
- ✅ Асинхронная обработка задач
|
||
- ✅ Автодокументация API
|
||
- ✅ Type hints и валидация
|
||
- ✅ Docker поддержка
|
||
|
||
## 📄 Лицензия
|
||
|
||
[MIT License](LICENSE)
|
||
|
||
## 👨💻 Автор
|
||
|
||
Speech Analytics Team
|
||
|
||
---
|
||
|
||
📖 Более подробная информация в документации:
|
||
- [Quick Start](START.md)
|
||
- [API Docs](README_FASTAPI.md)
|
||
- [Docker Guide](README_DOCKER.md)
|