DrHo1y
4b5e5edf5b
Some checks failed
Build and push Docker image (Gitea) / build (push) Has been cancelled
150 lines
9.6 KiB
Markdown
150 lines
9.6 KiB
Markdown
# UfaHack2024
|
||
|
||
Хакатон UfaHack2024 в Уфе
|
||
|
||
---
|
||
|
||
## Описание проекта
|
||
Проект представляет систему распознавания лиц актёров (США / СССР-Россия) и блогеров с веб-камеры и по загруженным фотографиям. Пайплайн обработки: MTCNN (детекция лица) → DeepFace (Facenet, выделение эмбеддингов) → CatBoost (градиентный бустинг, классификация).
|
||
|
||
На основе десктопного приложения на CustomTkinter пользователь может запускать распознавание как из файловой папки с фотографиями, так и в реальном времени через веб-камеру. Дополнительно реализован Android-клиент на Kotlin, который отправляет фото на серверную часть по TCP-сокету.
|
||
|
||
Система обучена на нескольких категориях: актёры США, актёры СССР-Россия и блогеры. Для каждой категории строится отдельная модель CatBoost, использующая эмбеддинги лиц, извлечённые предобученной сетью Facenet.
|
||
|
||
## Стек технологий
|
||
- Python (основной язык)
|
||
- CustomTkinter (графический интерфейс)
|
||
- DeepFace + Facenet (извлечение эмбеддингов лиц)
|
||
- MTCNN / FastMTCNN (детекция лиц)
|
||
- CatBoost (градиентный бустинг)
|
||
- OpenCV + opencv-contrib-python (обработка изображений и видео)
|
||
- PyTorch + torchvision (фреймворк для нейросетей)
|
||
- CUDA (ускорение на GPU)
|
||
- Kotlin (Android-клиент)
|
||
|
||
## Структура проекта
|
||
```
|
||
UfaHack2024/
|
||
├── notebooks/
|
||
│ ├── app/
|
||
│ │ ├── main.py # Точка входа, CustomTkinter
|
||
│ │ ├── Predict_photo.py # Распознавание из папки с фото
|
||
│ │ ├── Predict_video.py # Распознавание с веб-камеры
|
||
│ │ ├── PredictServer.py # TCP-сервер (192.168.120.240:12345)
|
||
│ │ ├── Start.py # Стартовое окно
|
||
│ │ ├── FastMtcnn.py # Ускоренный MTCNN
|
||
│ │ └── FDJ.jpg # Тестовое изображение
|
||
│ ├── model/
|
||
│ │ ├── saved_dictionary.pkl # Словарь имён (категория)
|
||
│ │ ├── saved_dictionary_russia.pkl # Словарь имён (Россия)
|
||
│ │ ├── saved_dictionary_bloggers.pkl # Словарь имён (блогеры)
|
||
│ │ ├── actors_usa_embeddings.pkl # Эмбеддинги (США)
|
||
│ │ └── actors_ussr_embeddings.pkl # Эмбеддинги (СССР-Россия)
|
||
│ ├── saved_dictionary.pkl # Словарь имён (корневой)
|
||
│ ├── EDA.ipynb # Разведочный анализ данных
|
||
│ ├── blur_detection.ipynb # Детекция размытия
|
||
│ ├── catboost.ipynb # Обучение CatBoost
|
||
│ ├── deepface_notebooks.ipynb # Работа с DeepFace
|
||
│ ├── FastMTCNN.py # Вспомогательный модуль
|
||
│ └── tester.py # Тестирование
|
||
├── MyApplication6.rar # Android-клиент (Kotlin)
|
||
├── .gitignore
|
||
├── requirements.txt
|
||
├── server/
|
||
│ ├── __init__.py
|
||
│ └── server.py
|
||
├── Dockerfile
|
||
├── docker-compose.yml
|
||
├── .dockerignore
|
||
├── .github/
|
||
│ └── workflows/
|
||
│ └── docker-build.yml
|
||
├── .gitea/
|
||
│ └── workflows/
|
||
│ └── docker-build.yml
|
||
└── c4715817-515e-4815-aa0d-bfcc75d45388.jfif
|
||
```
|
||
|
||
## Установка и запуск
|
||
|
||
1. Клонируйте репозиторий:
|
||
```
|
||
git clone https://github.com/DrHo1y/UfaHack2024.git
|
||
cd UfaHack2024
|
||
cd notebooks/app
|
||
```
|
||
2. Установите зависимости (см. раздел Зависимости ниже).
|
||
3. Запустите приложение:
|
||
```
|
||
python main.py
|
||
```
|
||
|
||
### Зависимости
|
||
|
||
Все необходимые зависимости (15 пакетов) перечислены в `requirements.txt`. Установка выполняется одной командой:
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## Важные замечания
|
||
- Файлы `.cbm` (catboost_usa.cbm, catboost_ussr.cbm) **не включены** в репозиторий. Их необходимо обучить из блокнота `catboost.ipynb` или получить отдельно.
|
||
- Каталоги `data/` с фотографиями находятся в `.gitignore` и **не приложены** к репозиторию. В коде жёстко прописаны абсолютные пути вида `C://Users//fatik//PycharmProjects//UfaHack2024//data//...` — перед запуском требуется скорректировать пути под ваше окружение.
|
||
- `requirements.txt` содержит все зависимости — см. раздел «Зависимости».
|
||
- Серверная часть (`PredictServer.py`) ожидает IP-адрес `192.168.120.240:12345` — измените под свою сеть.
|
||
|
||
## Приложение для Android
|
||
В корне репозитория находится архив `MyApplication6.rar` — проект Android-приложения на Kotlin. Клиент подключается к серверу (`PredictServer.py`) по TCP-сокету, отправляет фотографию и получает результат распознавания.
|
||
|
||
## Docker / локальная разработка
|
||
|
||
В репозитории добавлена конфигурация для запуска headless-сервера распознавания лиц в Docker-контейнере (без GUI). Серверная часть находится в каталоге `server/` — это Python-скрипт без графического интерфейса, который может работать независимо от десктопного приложения.
|
||
|
||
### Быстрый старт
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
После сборки и запуска сервер будет доступен на порту `12345` (адрес `127.0.0.1:12345`).
|
||
|
||
### Ручной запуск (без docker compose)
|
||
|
||
Собрать образ:
|
||
|
||
```bash
|
||
docker build -t ufahack2024 .
|
||
```
|
||
|
||
Запустить контейнер:
|
||
|
||
```bash
|
||
docker run -p 12345:12345 -v ./models:/app/models ufahack2024
|
||
```
|
||
|
||
Контейнер запускает headless TCP-сервер из `server/server.py`, слушает порт 12345 и требует файлы `.cbm` в каталоге `./models/`. Логи выводятся в stdout. Для выполнения команд необходим установленный Docker CLI.
|
||
|
||
### Переменные окружения
|
||
|
||
| Переменная | По умолчанию | Описание |
|
||
|-------------|----------------|----------------------------------|
|
||
| `HOST` | `0.0.0.0` | Адрес для привязки сокета |
|
||
| `PORT` | `12345` | Порт TCP-сервера |
|
||
| `MODEL_DIR` | `/app/models` | Каталог с моделями CatBoost |
|
||
| `DATA_DIR` | `/data` | Каталог с данными (фотографиями) |
|
||
|
||
### Важно
|
||
|
||
- Файлы `.cbm` (catboost_usa.cbm и др.) **не включены** в репозиторий. Поместите их в каталог `./models/` на хосте перед запуском контейнера. Без них контейнер запустится, но распознавание будет недоступно (в логах появится предупреждение).
|
||
- Каталоги `./models/` и `./data/` создаются Docker автоматически, если их нет на хосте.
|
||
- Файл `.dockerignore` исключает из контекста сборки ненужные файлы (исходники блокнотов, Android-клиент, `.git` и др.).
|
||
|
||
### CI / CD
|
||
|
||
В репозитории определены два workflow-файла:
|
||
|
||
- **GitHub Actions** (`.github/workflows/docker-build.yml`) — при пуше в ветку `main` автоматически собирает образ и публикует его в `ghcr.io/drho1y/ufahack2024` (все символы в нижнем регистре). Аутентификация через `secrets.GITHUB_TOKEN`, теги — `:latest` и `:${{ github.sha }}`.
|
||
- **Gitea Actions** (`.gitea/workflows/docker-build.yml`) — публикует образ в `git.byte-mate.ru/coder/ufahack2024`. Аутентификация: имя пользователя `${{ github.repository_owner }}`, пароль из секрета `GIT_PASSWORD` (не `GITEA_TOKEN`). Требуется зарегистрированный Gitea Actions runner.
|
||
|
||
## Благодарности
|
||
Для обучения модели использовали [CatBoost](https://catboost.ai/) |