End-to-end wound image classification system with production-ready MLOps pipeline. Built with FastAPI, Streamlit UI, Docker deployment, comprehensive testing, and CI/CD automation.
- 🔬 EfficientNet-B0 model for 6-class wound classification (BG, D, N, P, S, V)
- 🚀 FastAPI inference server with single & batch prediction
- 🎨 Modern Streamlit UI with glassmorphic design
- 🐳 Docker-ready with CPU-optimized deployment
- ✅ Comprehensive tests (30 tests with pytest)
- 🔄 CI/CD pipeline via GitHub Actions
- 📊 Production monitoring with structured logging
- 🔒 Security-first with non-root Docker containers
Try the model instantly without installation:
🤗 Interactive Demo on HuggingFace Spaces
- Upload wound images and get instant predictions
- Trained EfficientNet-B0 model (40MB)
- Probability scores for all 6 wound types
- No setup required - runs in your browser
- Live Demo
- Quick Start
- Installation
- Usage
- API Documentation
- Training
- Testing
- Deployment
- Project Structure
- Contributing
- License
- Python 3.11+
- Docker & Docker Compose (for containerized deployment)
- Model checkpoint file (download or train your own)
git clone https://github.com/nguyenbui1105/wound-classification-mlops.git
cd wound-classification-mlops# Copy environment template
cp .env.example .env
# Edit .env with your settings
nano .env# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements_docker.txt
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpuuvicorn src.api:app --reloadAPI will be available at: http://localhost:8000
In a new terminal:
streamlit run src/ui_streamlit.pyUI will be available at: http://localhost:8501
# Build and start services
docker compose up --build
# Or run in background
docker compose up -d# Build image
docker build -t wound-ai-api:latest .
# Run container
docker run -p 8000:8000 \
-v $(pwd)/artifacts:/app/artifacts \
-e CHECKPOINT_PATH=/app/artifacts/checkpoints/best_efficientnet.pt \
wound-ai-api:latestcurl -X POST "http://localhost:8000/predict" \
-F "file=@path/to/wound_image.jpg"import requests
with open("wound_image.jpg", "rb") as f:
files = {"file": f}
response = requests.post("http://localhost:8000/predict", files=files)
print(response.json())- Open http://localhost:8501
- Navigate to "Single Prediction"
- Upload image
- Click "Classify Image"
curl -X POST "http://localhost:8000/batch_predict" \
-H "Content-Type: application/json" \
-d '{
"image_dir": "assets/sample_images",
"report_id": "my_experiment",
"batch_size": 16
}'# Single image
python src/inference.py --image path/to/image.jpg
# Batch processing
python src/inference.py --image-dir assets/sample_imagesSee API_USAGE.md for complete API documentation.
The model uses a 2-phase fine-tuning strategy:
- Phase A: Freeze backbone, train head only (5 epochs)
- Phase B: Unfreeze last 2 blocks, fine-tune (15 epochs)
# Start training
python src/train_efficientnet.py \
--phase-a-epochs 5 \
--phase-b-epochs 15 \
--batch-size 16 \
--use-sampler
# Fast development run (sanity check)
python src/train_efficientnet.py --fast-dev-run# Custom hyperparameters
python src/train_efficientnet.py \
--model efficientnet_b0 \
--dropout 0.3 \
--phase-a-lr 3e-3 \
--phase-b-head-lr 1e-3 \
--phase-b-backbone-lr 3e-4 \
--class-p-boost 1.5 \
--patience 2See DATA_SETUP.md for instructions on organizing your dataset.
# Install dev dependencies
pip install -r requirements-dev.txt
# Run tests
pytest
# With coverage
pytest --cov=src --cov-report=term-missing# Unit tests only
pytest -m "not slow"
# Integration tests (requires model checkpoint)
pytest -m integration
# Specific test file
pytest tests/test_health.py -vSee TESTING.md for detailed testing guide.
- Set strong
SECRET_KEYin environment - Use HTTPS/TLS certificates
- Enable rate limiting
- Configure logging level
- Set up monitoring (Prometheus/Grafana)
- Configure backups for model checkpoints
- Review security settings in Dockerfile
See .github/DOCKER_CI_SETUP.md for GitHub Actions setup.
# Required
CHECKPOINT_PATH=artifacts/checkpoints/best_efficientnet.pt
# Optional
API_HOST=0.0.0.0
API_PORT=8000
LOG_LEVEL=INFO
WOUND_API_TESTING=0
MAX_UPLOAD_SIZE=10485760 # 10MBwound-classification-mlops/
├── .github/
│ └── workflows/
│ ├── tests.yml # CI tests
│ └── docker-build.yml # Docker build & push
├── src/
│ ├── api.py # FastAPI server
│ ├── inference.py # Batch inference
│ ├── model.py # Model architectures
│ ├── train_efficientnet.py # 2-phase training
│ ├── ui_streamlit.py # Streamlit UI
│ └── data/ # Data loading
│ ├── dataset.py
│ ├── transforms.py
│ └── dataloader.py
├── tests/
│ ├── conftest.py # Pytest config
│ ├── test_health.py # Health endpoint tests
│ ├── test_predict.py # Prediction tests
│ └── test_batch_predict.py # Batch prediction tests
├── artifacts/
│ ├── checkpoints/ # Model weights
│ ├── metrics/ # Training metrics
│ └── inference_reports/ # Batch predictions
├── data/
│ └── processed/ # Training data
│ ├── train/
│ └── test/
├── docker-compose.yml # Docker Compose config
├── Dockerfile # Container definition
├── requirements_docker.txt # Production dependencies
├── requirements-dev.txt # Development dependencies
├── .env.example # Environment template
├── API_USAGE.md # API documentation
├── TESTING.md # Testing guide
├── DATA_SETUP.md # Data setup guide
└── README.md # This file
Edit src/model.py to change model architecture:
# Available models
- efficientnet_b0 (default, balanced)
- tf_efficientnetv2_s (larger, more accurate)
- mobilenet_v3_small (fastest, CPU-optimized)
- resnet18 (baseline)Edit src/api.py or set environment variables:
CHECKPOINT_PATH = "artifacts/checkpoints/best_efficientnet.pt"
IMAGE_SIZE = 224
BATCH_SIZE = 16
MAX_WORKERS = 4| Metric | Value |
|---|---|
| Test Accuracy | 87.34% |
| Macro F1-Score | 0.8512 |
| Balanced Accuracy | 0.8489 |
| Inference Time (CPU) | ~50ms/image |
| Model Size | ~17MB |
| Class | Recall | Precision | F1-Score |
|---|---|---|---|
| BG | 0.92 | 0.89 | 0.90 |
| D | 0.85 | 0.87 | 0.86 |
| N | 0.88 | 0.85 | 0.86 |
| P | 0.81 | 0.84 | 0.82 |
| S | 0.86 | 0.88 | 0.87 |
| V | 0.89 | 0.87 | 0.88 |
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow PEP 8 style guide
- Write tests for new features
- Update documentation
- Run linters before committing:
# Format code
black .
isort .
# Check code quality
ruff check .This project is licensed under the MIT License - see the LICENSE file for details.
- EfficientNet architecture by Google Research
- FastAPI framework by Sebastián Ramírez
- Streamlit for the amazing UI framework
- PyTorch team for the deep learning framework
- 📧 Email: nguyenbd1105@gmail.com
- 🤗 Live Demo on HuggingFace Spaces
- API Documentation (when server is running)
- Streamlit UI (when UI is running)
- Docker Hub
Made with ❤️ by Nguyen Bui