DEPLOY_TO_HF.md

🚀 Deploy to HuggingFace Spaces

Complete guide for deploying the Translation AI Agent to HuggingFace Spaces.

📋 Prerequisites

1. HuggingFace Account: Create account at huggingface.co
2. Git (Optional): For command-line deployment
3. Files Ready: All required files in this directory

🛠️ Pre-Deployment Testing

Run local tests before deployment:

# Test all functionality
python test_local.py

# Run examples to verify features  
python examples.py

# Test locally (optional)
python app.py

🌐 Method 1: Web Interface Deployment (Recommended)

Step 1: Create New Space

1. Go to HuggingFace Spaces
2. Click "Create new Space"
3. Fill in details:
   • Space name: translation-ai-agent
   • License: MIT
   • SDK: Gradio
   • Hardware: GPU Basic (recommended) or CPU Basic
   • Visibility: Public

Step 2: Upload Files

Upload these files to your Space:

Required Files:

• app.py - Main application
• requirements.txt - Dependencies
• README.md - Documentation

Optional Files (recommended):

• config.py - Configuration
• utils.py - Utilities
• examples.py - Usage examples
• Dockerfile - Container config

Step 3: Configuration

1. Go to Settings tab
2. Set Hardware to GPU Basic for best performance
3. Enable Auto-build if desired
4. Set any required Environment Variables (if needed):

   HUGGING_FACE_HUB_TOKEN=your_token_here (optional)
   

Step 4: Launch

1. Space will automatically build and deploy
2. Monitor Logs tab for any issues
3. Visit your Space URL when ready

💻 Method 2: Git Deployment

Step 1: Clone Space Repository

# Replace with your space name
git clone https://huggingface.co/spaces/your-username/translation-ai-agent
cd translation-ai-agent

Step 2: Add Files

# Copy all files to the repository
cp path/to/your/files/* .

# Add files to git
git add .
git commit -m "Initial deployment of Translation AI Agent"

Step 3: Push to HuggingFace

git push origin main

🔧 Configuration Options

Hardware Options

Hardware	RAM	GPU	Cost	Best For
CPU Basic	16GB	None	Free	Text translation only
GPU Basic	16GB	T4	$0.6/hour	Full functionality
GPU A10G	24GB	A10G	$3.15/hour	High performance

Recommendation: Start with GPU Basic for full functionality.

Environment Variables

Set in Space Settings > Repository secrets:

# Optional: HuggingFace token for private models
HUGGING_FACE_HUB_TOKEN=hf_your_token_here

# Optional: CUDA device selection
CUDA_VISIBLE_DEVICES=0

# Optional: Model cache directory
TRANSFORMERS_CACHE=/tmp/transformers_cache

Model Configuration

Edit config.py to customize models:

# Use smaller models for faster loading
TRANSLATION_MODEL = "facebook/nllb-200-distilled-600M"  # Default
# TRANSLATION_MODEL = "facebook/nllb-200-1.3B"         # Better quality

SPEECH_RECOGNITION_MODEL = "openai/whisper-base"        # Default
# SPEECH_RECOGNITION_MODEL = "openai/whisper-small"     # Better quality

📊 Performance Optimization

1. Model Selection

• Small models: Faster loading, less GPU memory
• Large models: Better quality, more GPU memory

2. Hardware Selection

• CPU Basic: Free, text-only functionality
• GPU Basic: Recommended for full features
• GPU A10G: Best performance for heavy usage

3. Caching Strategy

# In config.py, adjust cache settings
CACHE_CONFIG = {
    "translation_cache_size": 1000,  # Increase for better caching
    "cache_ttl": 3600               # 1 hour cache lifetime
}

🐛 Troubleshooting

Common Issues

1. Build Timeout

Solution: Use smaller models or GPU hardware
- Switch to "whisper-base" instead of "whisper-large"
- Use "nllb-200-distilled-600M" instead of larger NLLB models

2. Out of Memory

Error: CUDA out of memory
Solution: 
- Upgrade to GPU A10G hardware
- Reduce batch_size in config.py
- Use smaller models

3. Model Download Fails

Error: Model download timeout
Solution:
- Retry deployment
- Check internet connection in Space logs
- Use HuggingFace token for private models

4. Audio Processing Errors

Error: librosa/soundfile issues
Solution:
- Ensure all audio dependencies in requirements.txt
- Check ffmpeg availability
- Use supported audio formats only

Debug Steps

1. Check Logs: Space > Logs tab
2. Test Locally: Run python test_local.py
3. Verify Files: Ensure all required files uploaded
4. Check Hardware: GPU recommended for audio features
5. Model Cache: Clear and retry if models fail to load

📈 Monitoring & Analytics

Built-in Metrics

The app includes performance tracking:

• Translation counts
• Processing times
• Error rates
• Uptime statistics

HuggingFace Analytics

Monitor in Space settings:

• User visits
• API calls
• Resource usage
• Costs (for paid hardware)

🔄 Updates & Maintenance

Updating Your Space

Method 1: Web Interface

1. Edit files directly in Space interface
2. Save changes to trigger rebuild

Method 2: Git Push

# Make changes locally
git add .
git commit -m "Update models/features"
git push origin main

Version Management

# In config.py, update version
VERSION = "1.0.1"

# Add changelog to README.md
## Changelog
- v1.0.1: Improved audio processing
- v1.0.0: Initial release

🌟 Post-Deployment

1. Test Your Space

• Visit your Space URL
• Test all features:
  • Text translation
  • Audio upload
  • Live microphone
• Check different language pairs

2. Share Your Space

• Add to your HuggingFace profile
• Share on social media
• Submit to HuggingFace community

3. Monitor Performance

• Check logs regularly
• Monitor resource usage
• Update models as needed

📚 Advanced Features

Custom Domain (Pro)

# For HuggingFace Pro users
# Configure custom domain in Space settings
# Point DNS to HuggingFace Spaces

API Integration

# Your Space automatically gets an API endpoint
import requests

response = requests.post(
    "https://your-username-translation-ai-agent.hf.space/api/predict",
    json={"data": ["Hello world", "en", "es"]}
)

Embedding in Websites

<!-- Embed your Space in any website -->
<iframe 
    src="https://your-username-translation-ai-agent.hf.space"
    width="100%" 
    height="600"
    frameborder="0">
</iframe>

🆘 Support

• HuggingFace Forums: discuss.huggingface.co
• Documentation: huggingface.co/docs/hub/spaces
• Discord: HuggingFace Discord server
• Issues: Create issue in your Space repository

---

✅ Deployment Checklist

• HuggingFace account created
• Local tests passing (python test_local.py)
• Space created with correct SDK (Gradio)
• All required files uploaded
• Hardware set to GPU Basic or higher
• Space successfully built and running
• All features tested in deployed Space
• README.md updated with Space URL
• Space made public (if desired)

🎉 Congratulations! Your AI Agent is now live on HuggingFace Spaces!

Space URL: https://huggingface.co/spaces/your-username/translation-ai-agent