🚗 inDrive Car Condition Assessment API

AI-powered car condition assessment system for enhanced safety and trust in ride-sharing services.

📋 Описание проекта

Этот проект представляет собой ML-модель и REST API для определения состояния автомобиля по фотографии. Система анализирует два ключевых параметра:

• Чистота: чистый/грязный автомобиль
• Целостность: битый/небитый автомобиль

Проект разработан для повышения безопасности и доверия пассажиров в сервисе inDrive.

⭐ Особенности

• 🧠 Нейронная сеть на базе PyTorch с архитектурой ResNet50
• 🚀 FastAPI для высокопроизводительного REST API
• 🖼️ Продвинутая обработка изображений с улучшением качества
• 🎯 Мультизадачная классификация (чистота + повреждения)
• 📱 Веб-интерфейс для демонстрации
• 📊 Детальная аналитика с рекомендациями
• 🔒 Валидация входных данных и обработка ошибок

🏗️ Архитектура системы

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Web Interface │────│   FastAPI Server │────│  Neural Network │
│   (HTML/JS)     │    │   (REST API)     │    │   (PyTorch)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                       ┌──────────────────┐
                       │ Image Processing │
                       │   (OpenCV/PIL)   │
                       └──────────────────┘

🛠️ Технический стек

• Backend: Python 3.9+, FastAPI, Uvicorn
• ML/AI: PyTorch, TorchVision, OpenCV
• Image Processing: Pillow, NumPy
• Package Management: uv (быстрый пакетный менеджер)
• Validation: Pydantic
• Documentation: Swagger/OpenAPI

📦 Установка и запуск

Предварительные требования

• Python 3.9+
• uv - быстрый пакетный менеджер для Python
• 4GB+ RAM
• GPU (опционально, для ускорения)

Установка uv (если не установлен)

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

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

1. Переход в директорию проекта:

cd d:\Dev\indriver-photo-ai

2. Создание виртуального окружения и установка зависимостей:

uv venv
uv pip install -e .

3. Активация окружения:

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

4. Запуск API сервера:

# Простой запуск
uv run python main.py

# Или с использованием uvicorn для большего контроля
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --reload

5. Открыть в браузере:

• Демо интерфейс: http://localhost:8000
• API документация: http://localhost:8000/docs
• Альтернативная документация: http://localhost:8000/redoc

🚀 Использование API

Проверка состояния системы

curl http://localhost:8000/health

Анализ изображения автомобиля

curl -X POST "http://localhost:8000/analyze" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@path/to/car_image.jpg"

Пример ответа API

{
    "cleanliness": {
        "prediction": "clean",
        "confidence": 0.8542,
        "probabilities": {
            "clean": 0.8542,
            "dirty": 0.1458
        }
    },
    "damage": {
        "prediction": "intact",
        "confidence": 0.9123,
        "probabilities": {
            "intact": 0.9123,
            "damaged": 0.0877
        }
    },
    "overall_confidence": 0.8833,
    "processing_time_ms": 245.7,
    "timestamp": "2025-09-13T10:30:45.123456",
    "recommendations": ["✅ Vehicle appears to be in good condition for passenger service"]
}

� Обучение модели на реальных данных

Сейчас модель использует демо-предсказания. Для получения реальных результатов необходимо обучить её на вашем датасете с царапинами и ржавчиной.

Подготовка датасета

1. Организуйте ваши изображения в папки:

dataset/
├── clean_intact/          # Чистые автомобили без повреждений
├── clean_damaged/         # Чистые автомобили с повреждениями (царапины, вмятины)
├── dirty_intact/          # Грязные автомобили без повреждений
└── dirty_damaged/         # Грязные автомобили с повреждениями (ржавчина, царапины)

2. Или используйте CSV файл с аннотациями:

image_path,cleanliness,damage
car001.jpg,clean,intact
car002.jpg,dirty,damaged
car003.jpg,clean,damaged
...

3. Подготовьте данные для обучения:

# Из папок
uv run python scripts/prepare_dataset.py \
  --mode folders \
  --data-dir path/to/your/dataset \
  --output-csv dataset_annotations.csv \
  --validate

# Из CSV аннотаций
uv run python scripts/prepare_dataset.py \
  --mode annotations \
  --data-dir path/to/images \
  --annotations-file your_annotations.csv \
  --output-csv prepared_dataset.csv \
  --validate

# Из Roboflow датасета
uv run python scripts/prepare_dataset.py \
  --mode roboflow \
  --data-dir path/to/roboflow/export \
  --output-csv roboflow_dataset.csv \
  --validate

Обучение модели

# Базовое обучение
uv run python scripts/train_model.py \
  --data-csv dataset_annotations.csv \
  --data-dir path/to/your/dataset \
  --output-dir ./trained_models \
  --epochs 50 \
  --batch-size 32 \
  --lr 0.001

# Продвинутые параметры
uv run python scripts/train_model.py \
  --data-csv dataset_annotations.csv \
  --data-dir path/to/your/dataset \
  --output-dir ./trained_models \
  --epochs 100 \
  --batch-size 16 \
  --lr 0.0005 \
  --test-size 0.15 \
  --val-size 0.15

Параметры обучения

• --epochs: Количество эпох обучения (рекомендуется 50-100)
• --batch-size: Размер батча (уменьшите если не хватает GPU памяти)
• --lr: Скорость обучения (0.001 - хорошая начальная точка)
• --test-size: Доля данных для тестирования (0.2 = 20%)
• --val-size: Доля данных для валидации (0.2 = 20%)

Тестирование обученной модели

# Тест одного изображения
uv run python scripts/test_model.py \
  --model-path trained_models/best_model.pth \
  --image path/to/test_image.jpg

# Тест папки с изображениями
uv run python scripts/test_model.py \
  --model-path trained_models/best_model.pth \
  --images-dir path/to/test_images \
  --output test_results.json

Использование обученной модели в API

После обучения обновите путь к модели:

1. Через переменную окружения:

export MODEL_PATH=./trained_models/best_model.pth
uv run python main.py

2. Через .env файл:

echo "MODEL_PATH=./trained_models/best_model.pth" >> .env
uv run python main.py

3. Скопируйте модель в стандартное место:

mkdir -p models
cp trained_models/best_model.pth models/car_condition_model.pth
# Модель будет загружена автоматически

🎯 Возможные результаты классификации

Чистота (cleanliness)

• clean - Автомобиль чистый
• dirty - Автомобиль грязный

Повреждения (damage)

• intact - Автомобиль без повреждений
• damaged - Автомобиль имеет повреждения

Чистота (cleanliness)

• clean - Автомобиль чистый
• dirty - Автомобиль грязный

Повреждения (damage)

• intact - Автомобиль без повреждений
• damaged - Автомобиль имеет повреждения

💡 Рекомендации системы

Система автоматически генерирует рекомендации на основе результатов анализа:

• 🧽 Требуется мойка - при обнаружении загрязнений
• ⚠️ Требуется осмотр - при обнаружении повреждений
• ✅ Готов к работе - автомобиль в хорошем состоянии
• 🤔 Требуется проверка - низкая уверенность модели

📊 Метрики и производительность

• Время обработки: ~200-500мс на изображение
• Поддерживаемые форматы: JPEG, PNG, BMP, TIFF, WEBP
• Максимальный размер файла: 10MB
• Минимальное разрешение: 100x100 пикселей
• Максимальное разрешение: 4096x4096 пикселей

🔧 Конфигурация

Переменные окружения

# Настройки сервера
HOST=0.0.0.0          # Хост для сервера
PORT=8000             # Порт для сервера
DEBUG=false           # Режим отладки

# Настройки модели
MODEL_PATH=models/trained_model.pth  # Путь к обученной модели (опционально)
DEVICE=auto           # Устройство: auto, cpu, cuda

Создание .env файла

# Создайте файл .env в корне проекта
echo "HOST=0.0.0.0
PORT=8000
DEBUG=true" > .env

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

Установка и запуск тестов

# Установка тестовых зависимостей
uv pip install pytest pytest-asyncio httpx

# Запуск всех тестов
uv run pytest

# Запуск с подробным выводом
uv run pytest -v

# Запуск конкретного теста
uv run pytest tests/test_api.py::test_analyze_endpoint

Тестирование API через curl

# Тест health check
curl http://localhost:8000/health

# Тест анализа изображения (замените на реальный путь к изображению)
curl -X POST http://localhost:8000/analyze \
  -F "file=@test_images/clean_car.jpg"

📁 Структура проекта

indriver-photo-ai/
├── main.py                 # Главный файл FastAPI приложения
├── pyproject.toml          # Конфигурация проекта и зависимости
├── README.md               # Документация проекта
├── .env.example            # Пример файла с переменными окружения
├── models/                 # ML модели
│   ├── __init__.py
│   └── car_classifier.py   # Нейронная сеть для классификации
├── utils/                  # Утилиты
│   ├── __init__.py
│   └── image_processing.py # Обработка изображений
├── tests/                  # Тесты (создаются по необходимости)
│   ├── __init__.py
│   ├── test_api.py        # Тесты API
│   ├── test_models.py     # Тесты моделей
│   └── test_utils.py      # Тесты утилит
└── examples/              # Примеры использования
    ├── api_examples.py    # Примеры вызовов API
    └── test_images/       # Тестовые изображения

🎨 Веб-интерфейс

Система включает встроенный веб-интерфейс для демонстрации возможностей:

1. Откройте http://localhost:8000 в браузере
2. Загрузите фотографию автомобиля
3. Получите результаты анализа в реальном времени
4. Просмотрите рекомендации и метрики

🔗 API Endpoints

Метод	Endpoint	Описание
GET	/	Веб-интерфейс для демонстрации
GET	/health	Проверка состояния системы
POST	/analyze	Анализ изображения автомобиля
GET	/docs	Swagger документация
GET	/redoc	ReDoc документация

🚀 Развертывание в production

Docker

FROM python:3.11-slim

WORKDIR /app

# Установка uv
RUN pip install uv

# Копирование файлов проекта
COPY pyproject.toml .
COPY . .

# Установка зависимостей
RUN uv pip install -e .

EXPOSE 8000

CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Создание образа и запуск

# Создание Docker образа
docker build -t indriver-car-ai .

# Запуск контейнера
docker run -p 8000:8000 indriver-car-ai

🧠 ML Модель

Архитектура

• Backbone: ResNet50 (предобученная на ImageNet)
• Классификаторы: Два отдельных классификатора для чистоты и повреждений
• Входные данные: RGB изображения 224x224 пикселей
• Выходные данные: Вероятности классов с softmax активацией

Особенности

• Мультизадачное обучение (multi-task learning)
• Transfer learning с предобученной ResNet50
• Dropout для регуляризации
• Адаптивная глобальная пулинг

📈 Мониторинг и логирование

Система включает встроенное логирование:

• Уровни логов: INFO, WARNING, ERROR
• Метрики: Время обработки, уверенность модели, ошибки
• Форматы: Структурированные логи с временными метками

🔐 Безопасность и приватность

• ✅ Валидация входных данных - проверка типов и размеров файлов
• ✅ Обработка ошибок - безопасная обработка исключений
• ✅ Ограничения ресурсов - лимиты на размер файлов и время обработки
• ✅ Логирование - отслеживание всех операций
• ✅ Приватность фото - изображения не сохраняются на сервере

⚠️ Ограничения текущей версии

• Модель использует демо-данные (для production требуется обучение на реальном датасете)
• Базовая детекция автомобилей (рекомендуется использование специализированных моделей)
• Ограниченная поддержка различных условий съемки (ночь, дождь, снег)
• Отсутствие многоклассовой классификации (например, степень загрязнения)

🗺️ Roadmap

Ближайшие улучшения

• Обучение на реальном датасете автомобилей inDrive
• Улучшенная детекция автомобилей с YOLO/RCNN
• Многоклассовая классификация состояния (слабо/сильно грязный, незначительные/серьезные повреждения)
• Поддержка анализа видео
• API для батч-обработки множества изображений

Долгосрочные планы

• Интеграция с мобильным приложением inDrive
• Поддержка различных типов транспорта (мотоциклы, автобусы)
• Анализ интерьера автомобиля
• Система оценки и рейтинга водителей
• A/B тестирование различных архитектур моделей

🤝 Вклад в проект

1. Форкните репозиторий
2. Создайте feature branch (git checkout -b feature/amazing-feature)
3. Коммитьте изменения (git commit -m 'Add amazing feature')
4. Пушьте в branch (git push origin feature/amazing-feature)
5. Откройте Pull Request

📄 Лицензия

Проект распространяется под лицензией MIT. См. файл LICENSE для деталей.

📞 Поддержка

Если у вас возникли проблемы или вопросы:

1. Проверьте FAQ
2. Создайте Issue
3. Свяжитесь с командой в Slack: #car-condition-ai

🙏 Благодарности

• PyTorch team за отличный ML framework
• FastAPI team за современный веб-framework
• OpenCV community за инструменты компьютерного зрения
• inDrive ML team за поддержку и обратную связь

---

Разработано с ❤️ для inDrive