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](https://huggingface.co/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:
```python
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

```python
# 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! 🎉**