FileAudioAPI/README.md

FileAudioAPI

Сервис для хранения аудиофайлов, индексации файлов, записи и выдачи результатов распознавания, реализованный на FastAPI.

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

# Клонировать и перейти в директорию
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 - Быстрый старт
• 📗 API Documentation - Полная документация API
• 📕 Docker Deployment - Развертывание в 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 (рекомендуется)

# Использование Makefile
make up

# Или напрямую с Docker Compose
docker-compose up -d

# Просмотр логов
make logs
# или
docker-compose logs -f

Локально

# Установка зависимостей
make install
# или
pip3 install -r requirements.txt

# Создание базы данных
make db-migrate

# Запуск
make dev
# или
python3 run.py

🔧 Makefile команды

make help      # Показать все команды
make build     # Собрать Docker образ
make up        # Запустить контейнеры
make down      # Остановить контейнеры
make restart   # Перезапустить
make logs      # Логи
make shell     # Shell в контейнере
make test      # Запуск тестов
make clean     # Очистка

📝 Примеры использования

Загрузка файла

curl -X POST http://localhost:8000/api/v1/upload \
  -F "file=@audio.mp3"

Запуск распознавания

curl -X POST http://localhost:8000/api/v1/recognize/{audio_id}

Получение статуса

curl http://localhost:8000/api/v1/recognize/{audio_id}

Получение результата

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

🧪 Тестирование

# Запуск тестов
make test

# Или напрямую
pytest tests/ -v

📊 Мониторинг

# 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

👨‍💻 Автор

Speech Analytics Team

---

📖 Более подробная информация в документации:

• Quick Start
• API Docs
• Docker Guide