itsmanask/NVIDIA-Video-Classification-Project

1# 🚀 Quick Start Guide - Single Model (Model 4) - Under 1GB!2 3Deploy your **best performing model (Model 4)** to Hugging Face Spaces - optimized to stay under the 1GB free tier limit.4 5---6 7## ✨ Why Single Model?8 9- ✅ **Under 1GB**: Fits HuggingFace free tier perfectly10- ✅ **Best Performance**: Model 4 is your top performer11- ✅ **Faster Inference**: Single model = faster predictions12- ✅ **95%+ Accuracy**: Still maintains excellent accuracy13- ✅ **Free Hosting**: No cost on HuggingFace14 15---16 17## ⚡ Prerequisites (5 minutes)18 191. **Hugging Face Account**: [Sign up here](https://huggingface.co/join)202. **Git & Git LFS**: Install if not already present21   ```bash22   # Ubuntu/Debian23   sudo apt-get install git git-lfs24   25   # macOS26   brew install git git-lfs27   ```28 293. **Your Model 4**: Single checkpoint file30   - `best_ensemble_model_4.pt` (~250MB)31 32---33 34## 🎯 Method 1: Automated (Recommended - 5 minutes)35 36### Step 1: Prepare Files37 38```bash39# Create deployment directory40mkdir video-classification-single41cd video-classification-single42 43# Copy the 3 provided files:44# - app.py (single model version)45# - requirements.txt46# - deploy_single_model.sh47```48 49### Step 2: Update Configuration (Optional)50 51Edit `app.py` line 335 with your class names:52```python53class_names = ["Animation", "Gaming", "Natural", "flAT"]  # Your classes here54```55 56### Step 3: Run Deployment Script57 58```bash59# Make script executable60chmod +x deploy_single_model.sh61 62# Run deployment (follow prompts)63./deploy_single_model.sh64```65 66The script will:67- ✅ Check prerequisites68- ✅ Verify model size is under 1GB69- ✅ Set up Git LFS70- ✅ Copy ONLY Model 471- ✅ Push to Hugging Face72- ✅ Complete in minutes!73 74**Done!** Visit your Space URL to see the live app.75 76---77 78## 🛠️ Method 2: Manual (10 minutes)79 80### Step 1: Create Space on Hugging Face81 821. Go to [huggingface.co/spaces](https://huggingface.co/spaces)832. Click "Create new Space"843. Settings:85   - Name: `video-classification-model4`86   - SDK: **Gradio**87   - Hardware: **CPU Basic** (free)884. Click "Create Space"89 90### Step 2: Clone and Setup91 92```bash93# Clone your Space94git clone https://huggingface.co/spaces/YOUR_USERNAME/video-classification-model495cd video-classification-model496 97# Initialize Git LFS98git lfs install99```100 101### Step 3: Add Files102 103```bash104# Create .gitattributes105cat > .gitattributes << EOF106*.pt filter=lfs diff=lfs merge=lfs -text107*.pth filter=lfs diff=lfs merge=lfs -text108EOF109 110# Copy application files111cp /path/to/app.py .112cp /path/to/requirements.txt .113 114# Create models directory and copy ONLY Model 4115mkdir models116cp /path/to/best_ensemble_model_4.pt models/117```118 119### Step 4: Verify Size120 121```bash122# Check model size123ls -lh models/best_ensemble_model_4.pt124 125# Should be under 1GB (~250-400MB typical)126```127 128### Step 5: Update Class Names129 130Edit `app.py` line 335:131```python132class_names = ["Your", "Class", "Names", "Here"]133```134 135### Step 6: Push to Hugging Face136 137```bash138# Add all files139git add .140 141# Commit142git commit -m "Deploy single model (Model 4) - optimized for HF"143 144# Push145git push146```147 148Wait 5-10 minutes for build to complete. Your app will be live!149 150---151 152## 📊 Size Comparison153 154| Setup | Model Size | Total Space | HF Compatible |155|-------|------------|-------------|---------------|156| **Ensemble (4 models)** | ~1GB | ~1.2GB | ❌ Too large |157| **Single Model (Model 4)** | ~250MB | ~300MB | ✅ Perfect! |158 159---160 161## 🧪 Testing Before Deployment162 163Always test locally first:164 165```bash166# Install dependencies167pip install -r requirements.txt168 169# Test the single model170python test_single_model.py171 172# If all tests pass, run the app173python app.py174```175 176Open browser to `http://localhost:7860` and test with a video.177 178---179 180## ⚙️ Configuration Changes181 182### Change Class Names183 184Edit `app.py` line 335:185```python186class_names = ["Fighting", "Normal", "Shooting", "Vandalism"]187```188 189### Use Different Model190 191If you want to use Model 1, 2, or 3 instead of Model 4:192 1931. Edit `app.py` line 334:194```python195model_path = "models/best_ensemble_model_1.pt"  # Change 4 to 1, 2, or 3196```197 1982. Copy the corresponding model file to `models/` directory199 200### Add Example Videos201 202```python203# In app.py, around line 480, add:204gr.Examples(205    examples=[206        ["examples/animation.mp4"],207        ["examples/gaming.mp4"],208    ],209    inputs=video_input210)211```212 213---214 215## 🛠️ Troubleshooting216 217### Issue: "Model file too large"218 219**Check Size:**220```bash221ls -lh models/best_ensemble_model_4.pt222```223 224**If over 1GB:**2251. Try model compression (quantization)2262. Use a smaller model architecture2273. Or upgrade to HF Pro ($9/month for unlimited storage)228 229### Issue: "Model not loading"230 231**Solution:**232```bash233# Verify Git LFS is tracking files234git lfs track "*.pt"235git add .gitattributes236git commit -m "Track models with LFS"237git push238```239 240### Issue: "Out of memory"241 242**Solution:** Reduce batch size in `app.py` line 140:243```python244batch_size = 8  # Reduced from 16245```246 247### Issue: "Build failed"248 249**Check Logs:**2501. Go to your Space2512. Click "Logs" tab2523. See error message253 254Common causes:255- Model file not uploaded via LFS256- Missing dependency in `requirements.txt`257- Syntax error in `app.py`258 259---260 261## 📊 Expected Performance262 263| Metric | Single Model (Model 4) | Ensemble (4 models) |264|--------|----------------------|---------------------|265| **Accuracy** | 95-96% | 95-97% |266| **Speed (CPU)** | 10-15 seconds | 12-20 seconds |267| **Speed (GPU)** | 2-4 seconds | 3-5 seconds |268| **Model Size** | ~250MB | ~1GB |269| **HF Compatible** | ✅ Yes | ❌ Too large |270 271**Verdict**: Single model provides 95%+ of ensemble performance at 25% of the size!272 273---274 275## ✅ Deployment Checklist276 277Before going live:278 279- [ ] Test locally with single model280- [ ] Model 4 file size under 1GB (check with `ls -lh`)281- [ ] Class names updated in `app.py`282- [ ] `.gitattributes` configured for LFS283- [ ] Git LFS installed and initialized284- [ ] Pushed to Hugging Face successfully285- [ ] Build completed (check Logs tab)286- [ ] Tested with sample video on live Space287 288---289 290## 🎉 You're Done!291 292Your Model 4 is now deployed and accessible worldwide - completely free!293 294**Share your Space:**295- Public URL: `https://huggingface.co/spaces/YOUR_USERNAME/video-classification-model4`296- Embed code available in Space settings297- Can be added to any website via iframe298 299**Performance:**300- ✅ 95%+ accuracy (single model)301- ✅ Fast inference (10-15s on CPU)302- ✅ Under 1GB total size303- ✅ Free hosting forever304 305---306 307## 💡 Pro Tips308 309### 1. Model Selection310 311All 4 models should perform similarly (95%+ accuracy). If you want to use a different model:312- Model 1, 2, 3, or 4 - choose based on your preference313- All are trained with the same architecture314- Performance differences are typically <1%315 316### 2. Cost Optimization317 318**Free Tier (CPU):**319- Perfect for demos and personal use320- 10-15 second inference321- Unlimited usage322 323**Upgrade Options:**324- CPU Upgrade: $0.60/hour (faster CPU)325- GPU T4: $3/hour (2-4 second inference)326 327### 3. Monitoring328 329Check your Space analytics:3301. Go to Space → Settings → Analytics3312. See usage, errors, and performance3323. Monitor and improve over time333 334---335 336## 🆚 Single Model vs Ensemble337 338### When to Use Single Model:339- ✅ Deploying to HuggingFace free tier340- ✅ Want faster inference341- ✅ Size constraints (<1GB)342- ✅ 95%+ accuracy is sufficient343 344### When to Use Ensemble:345- ✅ Have GPU infrastructure346- ✅ Need maximum accuracy (96-97%)347- ✅ No size constraints348- ✅ Can afford HF Pro ($9/month)349 350**For most use cases, single Model 4 is perfect!**351 352---353 354## 📞 Need Help?355 3561. **Check Space Logs** for build errors3572. **Test locally first** with `python app.py`3583. **Verify model size**: `ls -lh models/best_ensemble_model_4.pt`3594. **Gradio Docs**: [gradio.app/docs](https://gradio.app/docs)3605. **HF Docs**: [huggingface.co/docs/hub/spaces](https://huggingface.co/docs/hub/spaces)361 362---363 364## 🎯 Quick Commands Reference365 366```bash367# Check model size368ls -lh models/best_ensemble_model_4.pt369 370# Test locally371python app.py372 373# Deploy374chmod +x deploy_single_model.sh375./deploy_single_model.sh376 377# Check git lfs status378git lfs ls-files379 380# Force push (if needed)381git push --force origin main382```383 384---385 386**Happy Deploying with Single Model! 🚀**387 388*Optimized for HuggingFace free tier - Model 4 delivers 95%+ accuracy in under 1GB!*