HF_MIGRATION_GUIDE.md

🚀 Hugging Face Spaces Migration Guide

Complete guide to migrate your Video Transcription Service from Render.com to Hugging Face Spaces with enhanced features and API access.

🎯 Why Hugging Face Spaces?

Advantages over Render.com:

• ✅ Higher Resource Limits: More memory and CPU
• ✅ Better Performance: Optimized for ML workloads
• ✅ Free GPU Access: Available for intensive tasks
• ✅ Gradio Integration: Beautiful web interface
• ✅ Community Features: Easy sharing and discovery
• ✅ Persistent Storage: Better file handling
• ✅ API + Web Interface: Both available simultaneously

📋 Pre-Migration Checklist

• Hugging Face account created
• Git installed locally
• Python environment ready
• Test video files prepared
• Current service functionality documented

🛠️ Step 1: Prepare Deployment Files

Run the automated preparation script:

python deploy_to_hf.py

This creates a hf_spaces_deploy/ directory with all necessary files:

• app.py - Gradio + FastAPI hybrid interface
• requirements.txt - HF Spaces optimized dependencies
• README.md - HF Spaces documentation
• config.py - HF-optimized configuration
• All supporting modules

🌐 Step 2: Create Hugging Face Space

1. Go to Hugging Face Spaces

   • Visit: https://huggingface.co/spaces
   • Click "Create new Space"

2. Configure Your Space

   • Name: video-transcription (or your choice)
   • SDK: Select "Gradio"
   • Hardware: Start with "CPU basic" (free)
   • Visibility: Public (for API access) or Private

3. Create Space

   • Click "Create Space"
   • Note your Space URL: https://username-spacename.hf.space

📤 Step 3: Deploy to Hugging Face Spaces

Option A: Git Deployment (Recommended)

cd hf_spaces_deploy
git init
git add .
git commit -m "Initial deployment of Video Transcription Service"
git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
git push -u origin main

Option B: Web Upload

1. Go to your Space page
2. Click "Files" tab
3. Upload all files from hf_spaces_deploy/
4. Ensure app.py is in the root directory

⏳ Step 4: Monitor Deployment

1. Check Build Logs

   • Go to "Logs" tab in your Space
   • Monitor the build process (5-10 minutes)
   • Look for successful model download

2. Expected Log Output

   🚀 Starting Video Transcription Service on Hugging Face Spaces
   🤖 Loading Whisper model for Hugging Face Spaces...
   ✅ Model 'base' preloaded in 45.2 seconds
   🚀 Starting FastAPI service...
   Running on local URL: http://0.0.0.0:7860
   

3. Troubleshoot Issues

   • Build failures: Check requirements.txt
   • Memory issues: Switch to "CPU upgrade" hardware
   • Model loading issues: Try WHISPER_MODEL=tiny

✅ Step 5: Test Your Deployment

Test Web Interface

1. Visit Your Space

   • URL: https://username-spacename.hf.space
   • Should see Gradio interface

2. Upload Test Video

   • Use "Upload & Transcribe" tab
   • Select a small test video (< 50MB)
   • Choose language or use auto-detect
   • Click "Start Transcription"

3. Check Results

   • Note the transcription ID
   • Use "Check Status" tab to monitor progress
   • Verify transcription completes successfully

Test API Functionality

1. Health Check

   curl "https://username-spacename.hf.space/api/health"
   

2. Upload Video via API

   curl -X POST "https://username-spacename.hf.space/api/transcribe" \
     -F "file=@test_video.mp4" \
     -F "language=en"
   

3. Check Status via API

   curl "https://username-spacename.hf.space/api/transcribe/1"
   

4. Use Python Client

   python hf_api_client.py https://username-spacename.hf.space test_video.mp4
   

🔧 Step 6: Optimize Performance

Hardware Upgrades

If you experience performance issues:

1. Go to Space Settings
2. Hardware → Upgrade
3. Options:
   • CPU basic (free) - 2 vCPU, 16GB RAM
   • CPU upgrade ($0.05/hour) - 8 vCPU, 32GB RAM
   • GPU T4 small ($0.60/hour) - For heavy workloads

Model Optimization

Adjust model size based on your needs:

# In Space settings, add environment variable:
WHISPER_MODEL=tiny    # Fastest, good quality
WHISPER_MODEL=base    # Balanced (default)
WHISPER_MODEL=small   # Better quality, slower

📊 Step 7: Compare Features

Feature	Render.com	Hugging Face Spaces
Memory	512MB	16GB (basic) / 32GB (upgrade)
CPU	Shared	2-8 vCPU dedicated
Storage	Ephemeral	Persistent
GPU	None	T4 available
Interface	API only	Gradio + API
Community	Limited	Built-in sharing
Cost	Free tier limited	More generous free tier

🔄 Step 8: Migration Validation

Functionality Checklist

• ✅ Web interface loads correctly
• ✅ Video upload works (multiple formats)
• ✅ Language detection/selection works
• ✅ Transcription processing completes
• ✅ Results display correctly
• ✅ API endpoints respond correctly
• ✅ Status checking works
• ✅ Error handling functions
• ✅ Automatic cleanup operates
• ✅ Logging provides good visibility

Performance Validation

• ✅ Model loads within 2-3 minutes
• ✅ First transcription completes successfully
• ✅ Subsequent transcriptions are faster
• ✅ Large files (up to 200MB) process correctly
• ✅ Multiple concurrent requests handled
• ✅ Memory usage stays within limits

🌐 Step 9: Update Your Applications

Update API Endpoints

Replace your Render.com URLs:

# Old Render.com URL
OLD_URL = "https://your-service.onrender.com"

# New HF Spaces URL
NEW_URL = "https://username-spacename.hf.space"

# API endpoints remain the same:
# POST /api/transcribe
# GET /api/transcribe/{id}
# GET /api/health

Update Client Code

# Use the new HF API client
from hf_api_client import HFTranscriptionClient

client = HFTranscriptionClient("https://username-spacename.hf.space")
result = client.transcribe_and_wait("video.mp4")

🎉 Step 10: Go Live

Share Your Space

1. Make Public (if desired)

   • Space Settings → Visibility → Public

2. Add to Profile

   • Pin to your HF profile
   • Add description and tags

3. Share URL

   • Web interface: https://username-spacename.hf.space
   • API base: https://username-spacename.hf.space/api

Monitor Usage

• Check Space analytics
• Monitor resource usage
• Review user feedback
• Update documentation as needed

🔧 Troubleshooting

Common Issues

1. Build Fails

   Solution: Check requirements.txt, ensure all dependencies are compatible
   

2. Model Loading Timeout

   Solution: Upgrade to CPU upgrade hardware or use WHISPER_MODEL=tiny
   

3. API Not Accessible

   Solution: Ensure Space is Public and FastAPI is running on port 7860
   

4. Memory Issues

   Solution: Upgrade hardware or reduce MAX_FILE_SIZE in config
   

📞 Support Resources

• HF Spaces Documentation: https://huggingface.co/docs/hub/spaces
• Gradio Documentation: https://gradio.app/docs/
• Community Forum: https://discuss.huggingface.co/
• Your Space Logs: Available in Space dashboard

🎯 Next Steps

After successful migration:

1. Decommission Render.com service
2. Update documentation with new URLs
3. Notify users of the migration
4. Monitor performance and optimize as needed
5. Consider GPU upgrade for heavy workloads

---

🎉 Congratulations! Your Video Transcription Service is now running on Hugging Face Spaces with enhanced capabilities and better performance!

Key Benefits Achieved:

• ✅ Higher resource limits
• ✅ Beautiful Gradio web interface
• ✅ Full API compatibility maintained
• ✅ Better community integration
• ✅ More reliable performance
• ✅ Future GPU upgrade path