From f3e3da16963d885f81e8dd51b278476232d37d92 Mon Sep 17 00:00:00 2001 From: poturaevpetr Date: Tue, 24 Feb 2026 13:48:24 +0500 Subject: [PATCH] =?UTF-8?q?=D1=83=D0=B4=D0=B0=D0=BB=D0=B5=D0=BD=D0=B8?= =?UTF-8?q?=D0=B5=20=D0=BA=D1=8D=D1=88=D0=B0=20=D1=81=D0=B5=D0=B3=D0=BC?= =?UTF-8?q?=D0=B5=D0=BD=D1=82=D0=BE=D0=B2=20=D0=B0=D1=83=D0=B4=D0=B8=D0=BE?= =?UTF-8?q?=20=D0=BF=D0=BE=D1=81=D0=BB=D0=B5=20=D0=BE=D0=B1=D1=80=D0=B0?= =?UTF-8?q?=D0=B1=D0=BE=D1=82=D0=BA=D0=B8,=20=D0=B4=D0=BE=D0=B1=D0=B0?= =?UTF-8?q?=D0=B2=D0=BB=D0=B5=D0=BD=D0=B0=20=D0=B8=D0=BD=D1=81=D1=82=D1=80?= =?UTF-8?q?=D1=83=D0=BA=D1=86=D0=B8=D1=8F=20=D0=B4=D0=BB=D1=8F=20=D0=BE?= =?UTF-8?q?=D1=87=D0=B8=D1=81=D1=82=D0=BA=D0=B8=20=D0=BA=D0=BE=D0=BD=D1=82?= =?UTF-8?q?=D0=B5=D0=B9=D0=BD=D0=B5=D1=80=D0=BE=D0=B2=20=D0=B8=20=D0=BE?= =?UTF-8?q?=D0=B1=D1=80=D0=B0=D0=B7=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 211 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 210 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a84d03a..b2bdd55 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,212 @@ # FileAudioAPI -Сервис для хранения файлов аудио, индексации файлов, записи и выдачи результатов распознавания \ No newline at end of file +Сервис для хранения аудиофайлов, индексации файлов, записи и выдачи результатов распознавания, реализованный на **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)