SEMINAR_NOTES.md

Building ML Demos with Hugging Face Spaces

Overview

Today we'll build a complete ML demo from scratch and deploy it to Hugging Face Spaces. We'll focus on the process of creating demos, not the ML model itself.

---

Part 1: Project Setup & Structure

Starting from Scratch

Talking Points:

• "Let's say you have a trained model and want to share it with the world"
• "The goal is to create a web interface that anyone can use"
• "We'll use Gradio - it's perfect for ML demos"

Project Structure

simple-vpr-demo/
├── app.py              # Main Gradio application
├── model.py            # Model loading logic
├── dataset.py          # Data handling
├── requirements.txt    # Dependencies
├── README.md           # HF Spaces metadata + docs
└── data/               # Sample data
    ├── database/       # Reference images
    ├── query/          # Test images
    └── ground_truth.json

Key Points:

• Modular design: Separate concerns (UI, model, data)
• Clean structure: Easy to understand and extend
• Data organization: Logical folder structure

---

Part 2: Understanding Gradio

What is Gradio?

Talking Points:

• "Gradio is like Flask for ML - but much simpler"
• "It automatically creates web interfaces from Python functions"
• "Perfect for demos, prototypes, and sharing ML models"

Core Concepts

1. Components

# Input components
gr.Image(type="pil", label="Upload Image")     # File upload
gr.Slider(1, 10, value=5, step=1)              # Range input
gr.Button("Process")                            # Action trigger

# Output components  
gr.Textbox(lines=10, interactive=False)         # Display text
gr.Gallery()                                    # Image grid

Talking Points:

• "Components are like HTML elements, but for ML"
• "Each component has specific parameters for customization"
• "Input components collect data, output components display results"

2. Layout System

with gr.Blocks() as demo:
    gr.Markdown("# Title")                      # Header
    
    with gr.Row():                             # Horizontal layout
        with gr.Column():                       # Left column
            # Input controls
        with gr.Column():                       # Right column  
            # Output display

Talking Points:

• "gr.Blocks() gives you full control over layout"
• "gr.Row() and gr.Column() create responsive layouts"
• "Alternative: gr.Interface() for simpler, auto-generated layouts"

3. Event Handling

button.click(
    fn=my_function,                    # Function to call
    inputs=[input1, input2],          # Input components
    outputs=[output1, output2]        # Output components
)

Talking Points:

• "This is the magic - connecting UI to your ML code"
• "Function signature must match: my_function(input1, input2)"
• "Return values automatically update the output components"

Gradio vs Alternatives

Talking Points:

• Streamlit: Great for data apps, but more complex for ML demos
• Flask/FastAPI: Full control but requires frontend knowledge
• Gradio: Perfect balance - simple but powerful

---

Part 3: Building the Application

The Demo Function

def demo_interface(query_image, top_k):
    # 1. Process the input
    query_tensor = transform(query_image)
    
    # 2. Run your ML model
    matches = find_matches(query_tensor, int(top_k))
    
    # 3. Format results
    result_text = "Top Matches:\n\n"
    result_images = []
    for match in matches:
        result_text += f"Similarity: {match['similarity']:.4f}\n"
        result_images.append(match['image'])
    
    # 4. Return outputs (must match output components)
    return result_text, result_images

Key Points:

• Input processing: Convert UI inputs to model format
• Model inference: Run your ML pipeline
• Output formatting: Make results user-friendly
• Return matching: Must match your output components

Performance Optimization

Talking Points:

• "Notice we pre-compute database features on startup"
• "This makes the demo fast - no waiting for users"
• "Always optimize for user experience in demos"

---

Part 4: Hugging Face Spaces Deployment

What are Hugging Face Spaces?

Talking Points:

• "Think of it as GitHub for ML demos"
• "Free hosting for Gradio, Streamlit, and Docker apps"
• "Automatic deployment from Git repositories"
• "Built-in GPU support for complex models"

Required Files

1. README.md (Critical!)

---
title: Visual Place Recognition Demo
emoji: 🗺️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: mit
short_description: Upload a query image to find similar places
---

Talking Points:

• "This metadata tells HF Spaces how to deploy your app"
• "Must be at the top of README.md"
• "sdk: gradio tells HF this is a Gradio app"
• "app_file: app.py points to your main file"

2. requirements.txt

torch>=1.9.0
torchvision>=0.10.0
gradio>=3.0.0,<4.0.0
huggingface_hub>=0.19.4,<0.20.0
Pillow>=8.0.0
numpy>=1.21.0
tqdm>=4.60.0

Talking Points:

• "Pin your versions! This prevents deployment issues"
• "Notice the huggingface_hub version pin - this prevents the HfFolder error"
• "Only include what you actually import"

3. app.py

Talking Points:

• "This is your main application file"
• "Must be named exactly as specified in README.md"
• "HF Spaces will run: python app.py"

Deployment Process (Git Approach)

Step 1: Create Repository

# Initialize git repo
git init
git add .
git commit -m "Initial commit"

# Create repo on GitHub/Hugging Face
# Copy the remote URL
git remote add origin https://github.com/username/repo-name.git
git push -u origin main

Step 2: Create HF Space

1. Go to huggingface.co/spaces
2. Click "Create new Space"
3. Fill in details:
   • Space name: your-demo-name
   • SDK: Gradio
   • Hardware: CPU (or GPU if needed)
   • Visibility: Public

Step 3: Connect Repository

1. Choose "Git Repository" option
2. Enter your GitHub repo URL
3. Click "Create Space"

Talking Points:

• "HF Spaces will automatically clone your repo"
• "It reads your README.md metadata"
• "Installs dependencies from requirements.txt"
• "Runs your app.py file"

Step 4: Monitor Deployment

Talking Points:

• "Watch the logs for any errors"
• "Common issues: missing dependencies, import errors"
• "The HfFolder error we saw earlier is a perfect example"

Common Deployment Issues

1. Dependency Conflicts

# Problem: Gradio tries to import HfFolder (removed in HF Hub 0.20+)
# Solution: Pin compatible versions
huggingface_hub>=0.19.4,<0.20.0
gradio>=3.0.0,<4.0.0

2. Missing Files

• Ensure all files are committed to git
• Check file paths are correct
• Verify app.py exists and is executable

3. Memory Issues

• Use CPU hardware for simple demos
• Optimize model loading (pre-compute features)
• Consider model quantization for large models

---

Part 5: Best Practices & Tips (2 minutes)

Demo Design Principles

1. Keep it simple: Focus on core functionality
2. Make it fast: Pre-compute what you can
3. Handle errors: Graceful failure messages
4. Clear UI: Intuitive interface design

Code Organization

1. Separate concerns: UI, model, data handling
2. Document everything: Comments for seminar audiences
3. Version control: Pin dependencies
4. Test locally: Run python app.py before deploying

Hugging Face Spaces Features

• Automatic updates: Push to git = auto-deploy
• Public sharing: Easy to share with anyone
• GPU support: For compute-intensive models
• Custom domains: Professional URLs
• Analytics: Usage statistics

---

Demo Script (Live Coding)

1. Show the Working Demo (2 minutes)

• "Let's see what we're building"
• Upload a query image
• Show the results
• Explain the user experience

2. Walk Through the Code (5 minutes)

• Open app.py
• Explain the Gradio components
• Show the function signature matching
• Highlight the layout structure

3. Deploy Live (3 minutes)

• Show the git repository
• Create a new HF Space
• Connect the repository
• Watch it deploy

4. Test Deployment (2 minutes)

• Open the deployed app
• Test the same functionality
• Show it's identical to local version

---

Key Takeaways

1. Gradio makes ML demos accessible - No frontend knowledge needed
2. HF Spaces provides free hosting - Perfect for sharing ML work
3. Git-based deployment - Version control + automatic updates
4. Dependency management matters - Pin versions to avoid conflicts
5. User experience is key - Fast, intuitive interfaces

Questions & Discussion

Common Questions:

• "Can I use my own models?" → Yes, any Python ML library
• "What about GPU costs?" → HF Spaces provides free GPU hours
• "How do I handle large models?" → Use model quantization or HF Hub
• "Can I customize the UI?" → Yes, CSS and custom components
• "What about authentication?" → Gradio supports user management

---

Resources

• Gradio Documentation
• Hugging Face Spaces
• Gradio Examples
• HF Spaces Documentation

---

This seminar demonstrates the complete workflow from local development to public deployment, emphasizing the tools and processes that make ML demos accessible to everyone.