docs/deployment_guide.md

Deployment Guide - Hugging Face Spaces

This guide walks you through deploying the Plant Disease Detection app to Hugging Face Spaces.

Prerequisites

• Hugging Face account (free): https://huggingface.co/join
• Trained model weights
• Git installed locally

Deployment Options

You have three options for deploying your model:

Option 1: Upload Model Weights to Space (Recommended)

Pros: Simple, no external dependencies Cons: Weights are part of the repo

Option 2: Load from Hugging Face Model Hub

Pros: Separate model versioning, smaller Space repo Cons: Need to upload model separately

Option 3: Fetch from ClearML

Pros: Direct integration with training pipeline Cons: Requires ClearML credentials in Space secrets

Step-by-Step: Option 1 (Upload Weights)

1. Create a Hugging Face Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in details:
   • Name: plant-disease-detection
   • License: Apache 2.0
   • Space SDK: Gradio
   • Visibility: Public
4. Click "Create Space"

2. Prepare Files for Deployment

Create a new directory for your Space:

mkdir hf-space-deployment
cd hf-space-deployment

Copy and flatten the UI structure:

# Copy main app file
cp ../ui/app.py ./

# Copy supporting files
cp ../ui/config.py ./
cp ../ui/model_loader.py ./
cp ../ui/utils.py ./
cp ../models/mock_model.py ./

# Copy requirements
cp ../requirements.txt ./

# Copy your trained model weights
cp ../path/to/best_model.pth ./

3. Modify app.py for Deployment

Edit app.py to work with the flat structure:

# Change imports at the top of app.py
import config
from model_loader import ModelLoader
from utils import preprocess_image, postprocess_predictions, ...
from mock_model import create_mock_predictions

# At the bottom, change:
demo = create_interface(use_mock=False)  # Use real model
demo.launch()  # Remove server_name and server_port

4. Modify model_loader.py

Update the model loading to use your actual architecture:

# In _load_real_model method, replace mock model with your actual model:

def _load_real_model(self, model_name, model_path=None):
    if model_config["model_type"] == "cnn":
        # Import your actual model class
        from your_model_module import YourCNNModel
        model = YourCNNModel(num_classes=len(config.CLASS_NAMES))

    # Load weights
    if model_path:
        model.load_state_dict(torch.load(model_path, map_location=self.device))
    else:
        # Load default model
        model.load_state_dict(torch.load("best_model.pth", map_location=self.device))

    return model

5. Create README for Space

Create README.md in the deployment directory:

---
title: Plant Disease Detection
emoji: 🌱
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
pinned: false
license: apache-2.0
---

# 🌱 Plant Disease Detection

AI-powered plant disease detection from leaf images.

## About

This application uses a Convolutional Neural Network (CNN) trained on the PlantVillage
dataset to identify plant diseases from leaf images.

**Developed by:** [Your Team Name]
**Course:** 5CCSAGAP - AI Group Project, King's College London
**Academic Year:** 2024-2025

## Features

- Upload plant leaf images for disease detection
- Support for 39 different plant disease categories
- Multiple model options (CNN, Transfer Learning)
- Batch processing capability
- Confidence threshold adjustment

## How to Use

1. Go to the "Single Image" tab
2. Upload a photo of a plant leaf
3. Click "Predict Disease"
4. View the top predictions with confidence scores

## Dataset

Trained on the [PlantVillage dataset](https://huggingface.co/datasets/EdBianchi/plant-village)
containing 55,400 images across 39 disease categories.

## Model Performance

- **Test Accuracy:** [Add your test accuracy]
- **Architecture:** Custom CNN / ResNet18 Transfer Learning
- **Training Framework:** PyTorch
- **Experiment Tracking:** ClearML

## Links

- **GitHub:** [Add your repo link]
- **Team Project:** [Add project documentation link]

---

**Disclaimer:** This is an educational project. Predictions should be verified by agricultural experts.

6. Upload to Hugging Face Space

Initialize Git and push:

# Initialize git
git init

# Add Hugging Face Space as remote
git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/plant-disease-detection

# Create .gitignore
cat > .gitignore << EOF
__pycache__/
*.pyc
.DS_Store
EOF

# Add files
git add .

# Commit
git commit -m "Initial deployment of Plant Disease Detection app"

# Push to Hugging Face
git push origin main

You'll be prompted for credentials:

• Username: Your HF username
• Password: Your HF access token (create at https://huggingface.co/settings/tokens)

7. Verify Deployment

1. Go to your Space URL: https://huggingface.co/spaces/YOUR_USERNAME/plant-disease-detection
2. Wait for the build to complete (check "Building" status)
3. Test the app with sample images

Step-by-Step: Option 2 (HF Model Hub)

1. Upload Model to HF Model Hub

from huggingface_hub import HfApi, create_repo

# Create repository for model
repo_id = "YOUR_USERNAME/plant-disease-cnn"
create_repo(repo_id=repo_id, repo_type="model", exist_ok=True)

# Upload model
api = HfApi()
api.upload_file(
    path_or_fileobj="path/to/best_model.pth",
    path_in_repo="pytorch_model.pth",
    repo_id=repo_id,
    repo_type="model"
)

# Create model card
model_card = """
---
license: apache-2.0
tags:
- image-classification
- plant-disease
- pytorch
---

# Plant Disease CNN

CNN model for plant disease detection, trained on PlantVillage dataset.

## Model Details

- **Architecture:** Custom CNN
- **Framework:** PyTorch
- **Classes:** 39 plant disease categories
- **Input Size:** 256x256 RGB images
- **Test Accuracy:** [Add your accuracy]

## Usage

```python
import torch
from huggingface_hub import hf_hub_download

model_path = hf_hub_download(
    repo_id="YOUR_USERNAME/plant-disease-cnn",
    filename="pytorch_model.pth"
)
model.load_state_dict(torch.load(model_path))

"""

api.upload_file( path_or_fileobj=model_card.encode(), path_in_repo="README.md", repo_id=repo_id, repo_type="model" )

### 2. Modify model_loader.py

```python
# In model_loader.py, set default to load from HF:

def _load_real_model(self, model_name, model_path=None):
    if model_path is None:
        # Download from HF Hub
        from huggingface_hub import hf_hub_download
        model_path = hf_hub_download(
            repo_id="YOUR_USERNAME/plant-disease-cnn",
            filename="pytorch_model.pth"
        )

    # Load model architecture
    model = YourCNNModel(num_classes=39)
    model.load_state_dict(torch.load(model_path, map_location=self.device))

    return model

3. Deploy to Space

Follow steps 1-7 from Option 1, but you don't need to include the .pth file.

Step-by-Step: Option 3 (ClearML)

1. Get ClearML Credentials

1. Log in to https://5ccsagap.er.kcl.ac.uk/
2. Go to Settings → Workspace → Create new credentials
3. Copy the credentials

2. Add Secrets to Space

1. Go to your Space settings
2. Click "Repository secrets"
3. Add three secrets:
   • CLEARML_API_HOST: https://5ccsagap.er.kcl.ac.uk
   • CLEARML_API_ACCESS_KEY: Your access key
   • CLEARML_API_SECRET_KEY: Your secret key

3. Modify model_loader.py

def _load_real_model(self, model_name, model_path=None):
    if model_path is None:
        # Load from ClearML
        import os
        from clearml import Task, Model

        # Initialize ClearML with environment variables
        Task.init(
            project_name="Plant Disease Detection",
            task_name="UI Model Loading",
            api_host=os.environ.get("CLEARML_API_HOST"),
            api_access_key=os.environ.get("CLEARML_API_ACCESS_KEY"),
            api_secret_key=os.environ.get("CLEARML_API_SECRET_KEY")
        )

        # Get the model
        model_id = "YOUR_MODEL_ID"  # Get this from ClearML
        model_obj = Model(model_id)
        model_path = model_obj.get_local_copy()

    # Load model
    model = YourCNNModel(num_classes=39)
    model.load_state_dict(torch.load(model_path, map_location=self.device))

    return model

Troubleshooting

Build Failures

Error: "Out of Memory"

• Your model might be too large
• Try using a smaller model or quantization

Error: "Module not found"

• Check all dependencies are in requirements.txt
• Verify imports work with flat file structure

Runtime Errors

Error: "Model file not found"

• Verify the .pth file is uploaded
• Check file path in model_loader.py

Error: "Incompatible architecture"

• Ensure your model class definition matches the saved weights
• Check num_classes=39

Updating the Deployment

To update your deployed app:

# Make changes to files
# Commit and push
git add .
git commit -m "Update: description of changes"
git push origin main

The Space will automatically rebuild.

Best Practices

1. Test locally first: Always test the app locally before deploying
2. Use small example images: Don't upload large images to the repo
3. Version your models: Tag model versions in HF Hub or ClearML
4. Monitor usage: Check Space analytics to see usage patterns
5. Update README: Keep the model card and space README up to date

Resources

• HF Spaces Documentation
• Gradio Documentation
• HF Hub Python API

Support

If you encounter issues:

1. Check the Space build logs
2. Test locally with the exact same file structure
3. Consult the course TAs
4. Check HF Community forums