Home
Whales Identification (EcoMarineAI) — библиотека машинного обучения для автоматической детекции и идентификации морских млекопитающих (китов и дельфинов) по аэрофотосъёмке.
- ✅ 13 837 активных индивидуальных особей китов и дельфинов (15 587 слотов ArcFace-головы)
- ✅ EfficientNet-B4 ArcFace в production + CLIP anti-fraud gate (отсев не-китов)
- ✅ REST API с batch processing
- ✅ Docker Compose для быстрого развёртывания
- ✅ Metric Learning (ArcFace) для масштабируемости
- ✅ Background removal с rembg
- Installation - Пошаговая установка и настройка
- Usage - Примеры использования API, Streamlit, notebooks
- FAQ - Часто задаваемые вопросы и решения проблем
- Architecture - Архитектура проекта и компоненты
- Model Cards - Подробные характеристики моделей
- API Reference - Полная документация API с примерами
- Testing - Запуск тестов и coverage requirements
- Contributing - Git workflow, code style, pre-commit hooks
- GitHub Repository - Исходный код
- Документация (docs/) - Документация с полным содержанием
- Hugging Face (production) - Производственная модель EfficientNet-B4 ArcFace
- Hugging Face (legacy) - Исторические чекпоинты
- Yandex Disk - Альтернативное хранилище моделей
# 1. Клонировать репозиторий
git clone https://github.com/0x0000dead/whales-identification.git
cd whales-identification
# 2. Запустить полный стек
docker compose up --buildМодели запечены в Docker-образ; недостающие веса докачиваются автоматически при первом старте — предварительно скачивать ничего не нужно. Для локальной разработки без Docker:
pip install huggingface_hub==0.20.3 && ./scripts/download_models.sh(см. Installation).
Сервисы:
- Backend API: http://localhost:8000
- Frontend UI: http://localhost:8080
- API Docs: http://localhost:8000/docs
| Модель | Precision | Время GPU (с) | Время CPU (с) | Статус |
|---|---|---|---|---|
| EfficientNet-B4 ArcFace + CLIP gate | TPR 0.95 / TNR 0.902 (anti-fraud) | ~1.5s | ~3.5s | ✅ Production |
| Vision Transformer L/32 | 93% | ~3.5s | ~7.5s | ⭐ Best research accuracy |
| Vision Transformer B/16 | 91% | ~2.0s | ~5.0s | Research |
| EfficientNet-B5 | 91% | ~1.8s | ~4.5s | Research |
| EfficientNet-B0 | 88% | ~1.0s | ~2.5s | ⚡ Fast |
| ResNet-101 | 85% | ~1.2s | ~3.0s | Baseline |
Все модели укладываются в требование ТЗ: ≤8 секунд для изображения 1920x1080
Подробности: Model Cards
- Framework: FastAPI (Python 3.11.6)
- ML: PyTorch 2.4.1, TIMM, Vision Transformers
- Inference: ArcFace metric learning, GeM pooling
- Package Manager: Poetry
- Framework: React 18 + TypeScript
- Build Tool: Vite
- Visualization: Recharts
- CI/CD: GitHub Actions (6-stage pipeline)
- Quality: 20 pre-commit hooks
- Containerization: Docker + Docker Compose
- Documentation: GitHub Pages + Wiki
Проект использует трёхуровневую модель лицензирования:
- Исходный код: MIT License (свободное использование)
- Обученные модели: CC-BY-NC-4.0 (наследует от тренировочных данных)
- Датасеты: CC-BY-NC-4.0 + Government Research-Only
❌ Коммерческое использование запрещено из-за:
- Happy Whale (CC-BY-NC-4.0)
- Данные Минприроды РФ (research-only)
- ImageNet pretrained weights (non-commercial)
Подробности:
- LICENSE - Исходный код
- LICENSE_MODELS.md - Модели
- LICENSE_DATA.md - Датасеты
- LICENSES_ANALYSIS.md - Анализ зависимостей
⚠️ Disclaimer: Информация о лицензиях предоставлена для ознакомительных целей и не является юридической консультацией. Для коммерческого использования рекомендуется консультация с квалифицированным юристом.
- Baltsat Konstantin - ML Engineering, CI/CD
- Tarasov Artem - Backend Development
- Vandanov Sergey - Frontend Development
- Serov Alexandr - ML Research
- Issues: Report a bug or ask a question
Проект использует comprehensive GitHub Actions pipeline:
- ✅ Lint: black, flake8, isort, mypy
- ✅ Security: bandit, safety, trivy
- ✅ Tests: pytest with coverage >80%
- ✅ Docker: Build, integration tests, health checks
- ✅ Docs: Auto-deploy to GitHub Pages
Статус:
Последнее обновление: 11 июня 2026 Версия: 0.1.0