UfaHack2024/README.md

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. Установка выполняется одной командой:

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-скрипт без графического интерфейса, который может работать независимо от десктопного приложения.

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

docker compose up --build

После сборки и запуска сервер будет доступен на порту 12345 (адрес 127.0.0.1:12345).

Ручной запуск (без docker compose)

Собрать образ:

docker build -t ufahack2024 .

Запустить контейнер:

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