| --- |
| title: Image Classification Service |
| emoji: 🖼️ |
| colorFrom: indigo |
| colorTo: purple |
| sdk: docker |
| pinned: false |
| --- |
| |
| # High-Throughput Image Classification Service |
|
|
| A production-ready image classification API using ResNet-18 with ONNX optimization, FastAPI, and CI/CD pipeline. |
|
|
| ## Features |
|
|
| - **Optimized Model**: ResNet-18 converted to ONNX with dynamic quantization (~70% size reduction) |
| - **High Performance**: ProcessPoolExecutor for concurrent request handling |
| - **Production Ready**: Docker containerization, comprehensive error handling |
| - **CI/CD Pipeline**: Automated testing and deployment to Hugging Face Spaces |
| - **Comprehensive Testing**: pytest unit tests with 100% endpoint coverage |
|
|
| ## Project Structure |
|
|
| ``` |
| image-classification-service/ |
| ├── app/ |
| │ ├── __init__.py |
| │ ├── main.py # FastAPI application |
| │ ├── model.py # ONNX inference logic |
| │ └── schemas.py # Pydantic models |
| ├── models/ |
| │ └── resnet18_quantized.onnx # Optimized model |
| ├── tests/ |
| │ └── test_api.py # Unit tests |
| ├── scripts/ |
| │ ├── 01_baseline_test.py # PyTorch baseline benchmark |
| │ ├── 02_export_onnx.py # Export to ONNX |
| │ ├── 03_quantize.py # Dynamic quantization |
| │ └── 04_benchmark_onnx.py # ONNX benchmark |
| ├── .github/ |
| │ └── workflows/ |
| │ └── ci-cd.yml # GitHub Actions pipeline |
| ├── Dockerfile |
| ├── .dockerignore |
| ├── requirements.txt |
| └── README.md |
| ``` |
|
|
| ## Quick Start |
|
|
| ### 1. Install Dependencies |
|
|
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| ### 2. Prepare the Model |
|
|
| Run the optimization scripts in order: |
|
|
| ```bash |
| cd scripts |
| python 01_baseline_test.py # Measure PyTorch baseline |
| python 02_export_onnx.py # Export to ONNX |
| python 03_quantize.py # Apply quantization |
| python 04_benchmark_onnx.py # Compare performance |
| cd .. |
| ``` |
|
|
| ### 3. Run the API |
|
|
| ```bash |
| uvicorn app.main:app --host 0.0.0.0 --port 7860 |
| ``` |
|
|
| ### 4. Test the API |
|
|
| ```bash |
| # Health check |
| curl http://localhost:7860/health |
| |
| # Predict |
| curl -X POST "http://localhost:7860/predict" \ |
| -H "accept: application/json" \ |
| -F "file=@/path/to/image.jpg" |
| ``` |
|
|
| ## Docker Deployment |
|
|
| ### Build and Run |
|
|
| ```bash |
| docker build -t image-classifier . |
| docker run -p 7860:7860 image-classifier |
| ``` |
|
|
| ## Testing |
|
|
| ```bash |
| pytest tests/ -v |
| ``` |
|
|
| ## API Endpoints |
|
|
| ### GET /health |
|
|
| Health check endpoint. |
|
|
| **Response:** |
| ```json |
| { |
| "status": "ok" |
| } |
| ``` |
|
|
| ### POST /predict |
|
|
| Image classification endpoint. |
|
|
| **Request:** |
| - Content-Type: `multipart/form-data` |
| - Body: `file` (image file) |
|
|
| **Response:** |
| ```json |
| { |
| "label": "tabby, tabby cat", |
| "score": 0.8234, |
| "label_id": 281, |
| "inference_time_ms": 45.123 |
| } |
| ``` |
|
|
| **Error Codes:** |
| - `400`: Corrupted or invalid image |
| - `413`: File too large (max 10MB) |
| - `415`: Unsupported media type |
| - `500`: Inference error |
|
|
| ## Performance Metrics |
|
|
| | Format | File Size | Avg Latency | P95 Latency | |
| |--------|-----------|-------------|-------------| |
| | PyTorch | ~45 MB | baseline | baseline | |
| | ONNX | ~45 MB | ~20% faster | - | |
| | ONNX Quantized | ~12 MB | ~40% faster | - | |
|
|
| *Run benchmark scripts to get actual measurements on your hardware* |
|
|
| ## CI/CD Pipeline |
|
|
| The GitHub Actions workflow automatically: |
| 1. Runs unit tests on every push/PR |
| 2. Deploys to Hugging Face Spaces on main branch (requires `HF_TOKEN` secret) |
|
|
| ### Setup Hugging Face Deployment |
|
|
| 1. Create a Hugging Face Space |
| 2. Generate an access token with write permissions |
| 3. Add `HF_TOKEN` to GitHub repository secrets |
| 4. Update `.github/workflows/ci-cd.yml` with your Space URL |
|
|
| ## Model Details |
|
|
| - **Base Model**: microsoft/resnet-18 (Hugging Face) |
| - **Task**: Image Classification (ImageNet-1k) |
| - **Input**: RGB images (224x224) |
| - **Output**: 1000 class probabilities |
| - **Optimization**: ONNX + Dynamic Quantization (QUint8) |
|
|
| ## Cloud API Usage |
|
|
| The service is deployed on Hugging Face Spaces. You can access the API directly using the following endpoint: |
|
|
| **Endpoint:** `https://phonepixelghost-image-classification-service.hf.space/predict` |
|
|
| ### 1. Using cURL |
| You can test the API from your terminal using this command: |
|
|
| ```bash |
| curl -X POST https://phonepixelghost-image-classification-service.hf.space/predict \ |
| -F "file=@test.jpg" |
| ``` |
|
|
| ### 2. Interactive UI |
| Visit the Space URL to use the modern web interface: |
| [Hugging Face Space Demo](https://huggingface.co/spaces/PhonePixelGhost/Image_Classification_Service) |
|
|
| ## Local Development |
|
|
| ### Adding New Features |
|
|
| 1. Update code in `app/` |
| 2. Add tests in `tests/` |
| 3. Run tests: `pytest tests/ -v` |
| 4. Update documentation |
|
|
| ### Performance Testing |
|
|
| Use JMeter or similar tools to test throughput: |
| - Concurrent users: 10, 50, 100 |
| - Measure: TPS, P95 latency, error rate |
|
|
| ## License |
|
|
| MIT |
|
|
| ## Acknowledgments |
|
|
| - Model: microsoft/resnet-18 from Hugging Face |
| - Framework: FastAPI, ONNX Runtime |
|
|
