DEPLOYMENT.md

Deployment Guide for Hugging Face Spaces

This guide will help you deploy the GenVidBench project on Hugging Face Spaces.

🚀 Quick Start

1. Prepare Your Repository

Make sure your repository contains these files:

• app.py - Main Gradio application
• requirements.txt - Python dependencies
• README.md - Space metadata and description
• download_model.py - Model download script
• setup.py - Setup script (optional)

2. Create a Hugging Face Space

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Fill in the details:
   • Space name: genvidbench (or your preferred name)
   • License: Apache 2.0
   • SDK: Gradio
   • Hardware: CPU Basic (or GPU if needed)
   • Visibility: Public or Private

3. Upload Your Code

You can either:

• Option A: Push your code to a GitHub repository and connect it
• Option B: Upload files directly through the web interface

4. Configure the Space

The space will automatically:

• Install dependencies from requirements.txt
• Run app.py as the main application
• Display the Gradio interface

📁 Required Files

app.py

Your main Gradio application file. Should contain:

• Model initialization
• Gradio interface definition
• Video processing logic

requirements.txt

List of Python packages needed:

torch>=1.13.0
torchvision>=0.14.0
mmcv>=2.0.0
mmengine>=0.7.1
gradio>=4.0.0
opencv-python>=4.6.0
decord>=0.6.0
# ... other dependencies

README.md

Space metadata and description: ```yaml

title: GenVidBench - Video Action Recognition emoji: 🎬 colorFrom: blue colorTo: purple sdk: gradio sdk_version: 4.0.0 app_file: app.py pinned: false license: apache-2.0

## 🔧 Model Setup

### Option 1: Automatic Download
The app will try to download the model checkpoint automatically using `download_model.py`.

### Option 2: Manual Upload
1. Download the model checkpoint manually
2. Upload it to your space's file system
3. Place it in the `checkpoints/` directory

### Option 3: Hugging Face Hub
Store the model on Hugging Face Hub and load it programmatically:
```python
from huggingface_hub import hf_hub_download
checkpoint_path = hf_hub_download(repo_id="your-username/your-model", filename="model.pth")

🐛 Troubleshooting

Common Issues

1. Model not found

   • Ensure the checkpoint file is in the correct location
   • Check file permissions
   • Verify the download completed successfully

2. Import errors

   • Check that all dependencies are in requirements.txt
   • Verify package versions are compatible

3. Memory issues

   • Consider using a smaller model
   • Optimize batch size
   • Use CPU instead of GPU if needed

4. Slow loading

   • Pre-download models during setup
   • Use model caching
   • Optimize model size

Debug Mode

Add debug information to your app:

import logging
logging.basicConfig(level=logging.DEBUG)

📊 Performance Optimization

For Hugging Face Spaces

1. Model Size: Keep models under 2GB for faster loading
2. Dependencies: Minimize the number of packages
3. Caching: Use model caching to avoid re-downloading
4. Lazy Loading: Load models only when needed

Example Optimizations

# Lazy model loading
model = None

def get_model():
    global model
    if model is None:
        model = init_recognizer(config_file, checkpoint_file, device='cpu')
    return model

def analyze_video(video):
    model = get_model()  # Load only when needed
    # ... rest of the function

🔒 Security Considerations

1. File Upload Limits: Set appropriate limits for video uploads
2. Input Validation: Validate video formats and sizes
3. Resource Limits: Monitor CPU/memory usage
4. Error Handling: Graceful error handling for edge cases

📈 Monitoring

Monitor your space:

• Check logs in the Hugging Face interface
• Monitor resource usage
• Track user interactions
• Set up alerts for failures

🚀 Going Live

Once everything is working:

1. Test thoroughly with different video types
2. Optimize performance for your target audience
3. Add documentation for users
4. Monitor usage and gather feedback
5. Iterate and improve based on user needs

📞 Support

If you encounter issues:

• Check the Hugging Face Spaces documentation
• Review the logs in your space
• Test locally first
• Ask for help in the Hugging Face community

---

Happy deploying! 🎉