Image Classification Service

REST API for real-time image classification using MobileNetV2 (ImageNet-1k), built with Django REST Framework, TensorFlow, and Redis caching. Fully containerized with Docker Compose for easy deployment.

Features

• Image Classification – POST an image and receive top-k predictions with confidence scores
• Smart Preprocessing – Automatic EXIF rotation, RGBA to RGB conversion, optional center-crop and test-time augmentation (TTA)
• Redis Caching – Cache predictions to speed up repeated classifications
• Health Monitoring – Check model and Redis status
• Metrics Tracking – Monitor latency and cache performance
• Easy Setup – Docker Compose makes it one command to get started

Quick Start

Prerequisites

• Docker & Docker Compose

Installation & Running

# First run (builds the image)
docker compose up --build

# Subsequent runs
docker compose up -d

The API will be available at http://localhost:8000

Verify the service is running:

curl http://localhost:8000/api/health/

Usage

Classify an Image

Linux / macOS:

curl -F "image=@./photo.jpg" -F "top_k=5" http://localhost:8000/api/classify/

Windows PowerShell:

curl -F "image=@C:\path\to\photo.jpg" -F "top_k=5" http://localhost:8000/api/classify/

With Optional Flags:

curl -F "image=@./photo.jpg" \
  -F "top_k=5" \
  -F "tta=true" \
  -F "center_crop=false" \
  http://localhost:8000/api/classify/

API Endpoints

Endpoint	Method	Purpose
/api/classify/	POST	Classify an image (form data: image, optional: top_k, tta, center_crop)
/api/health/	GET	Check model and Redis status
/api/metrics/	GET	View latency and cache statistics
/api/cache/clear/	POST	Clear the Redis cache

Configuration

Create a .env file in the project root:

DEBUG=True
SECRET_KEY=your-secret-key-here
ALLOWED_HOSTS=localhost,127.0.0.1
REDIS_HOST=redis
REDIS_PORT=6379
CORS_ALLOWED_ORIGINS=http://localhost:3000
ENABLE_TTA=false
ENABLE_CENTER_CROP=true
LOW_CONFIDENCE_THRESHOLD=0.35

Environment Variables

• DEBUG – Django debug mode (set to False in production)
• SECRET_KEY – Django secret key (change this in production!)
• ALLOWED_HOSTS – Comma-separated list of allowed hosts
• REDIS_HOST – Redis server hostname
• REDIS_PORT – Redis port
• CORS_ALLOWED_ORIGINS – Comma-separated CORS origins
• ENABLE_TTA – Enable test-time augmentation for better accuracy
• ENABLE_CENTER_CROP – Center-crop images before classification
• LOW_CONFIDENCE_THRESHOLD – Minimum confidence threshold (0–1)

Important Notes

• Access the API via http://localhost:8000, not 0.0.0.0
• The first request will be slower due to model warm-up; subsequent requests are much faster
• Identical images are cached automatically—repeated requests return near-instant results
• PNG icons and graphics with transparency perform better with RGBA→RGB compositing; consider enabling tta=true for such images

Performance

• Model: MobileNetV2 (lightweight & fast)
• Caching: Redis-backed caching for instant repeated predictions
• Typical Response: 30–100ms (excluding network overhead)

Production Deployment

For production, make these changes:

DEBUG=False
SECRET_KEY=<generate-a-strong-random-key>
ALLOWED_HOSTS=your-domain.com,www.your-domain.com

Consider using Nginx as a reverse proxy for SSL/TLS termination and load balancing.

License

MIT

Support

For issues or questions, please open an issue on GitHub.