HUGGINGFACE_DEPLOYMENT.md

🚀 Hugging Face Spaces Deployment Guide

✅ Step 1: Repository is Ready!

Your code has been successfully pushed to GitHub with all the modular architecture and automatic fine-tuning features.

🌐 Step 2: Create Hugging Face Space

Option A: Web Interface (Recommended)

1. Go to https://huggingface.co/new-space
2. Space Settings:
   • Name: vietnamese-sentiment-analysis (or your choice)
   • License: MIT (or your preferred license)
   • Hardware: CPU Basic (free) or GPU T4 (for faster fine-tuning)
   • Visibility: Public (free) or Private
   • SDK: Gradio

Option B: Using Git

# Clone your Hugging Face Space (replace with your space URL)
git clone https://huggingface.co/spaces/your-username/your-space-name
cd your-space-name

# Add your repository as remote
git remote add upstream https://github.com/your-username/SentimentAnalysis.git
git pull upstream main
git push origin main

📋 Step 3: Files to Upload

Make sure these files are in your Space:

SentimentAnalysis/
├── app.py                    # ✅ Main application
├── requirements.txt          # ✅ Dependencies
├── py/
│   ├── __init__.py          # ✅ Package
│   ├── api_controller.py    # ✅ API controller
│   ├── fine_tune_sentiment.py # ✅ Fine-tuning script
│   └── pages/               # ✅ UI pages
│       ├── __init__.py
│       ├── single_analysis.py
│       ├── batch_analysis.py
│       ├── model_info.py
│       └── api_endpoints.py

⚙️ Step 4: Space Configuration

Requirements.txt Check:

Ensure your requirements.txt includes:

torch>=2.0.0
transformers>=4.21.0
datasets>=2.0.0
gradio>=4.44.1
fastapi>=0.104.0
uvicorn>=0.24.0
pydantic>=2.5.0
psutil>=5.9.0
accelerate>=0.21.0

Hardware Selection:

• CPU Basic: Free, but fine-tuning will be slow (30-60 minutes)
• GPU T4: Paid, but fine-tuning will be fast (5-10 minutes)
• GPU A10G: More expensive, best performance

🚀 Step 5: Deployment Process

What Happens Automatically:

1. Environment Detection: App detects it's running on Hugging Face Spaces
2. Model Loading: Tries to load fine-tuned model, runs fine-tuning if needed
3. API Server: Starts REST API on port 7861 automatically
4. Gradio Interface: Launches with all 4 tabs

Expected Timeline:

• Initial Build: 2-5 minutes (installing dependencies)
• First Run: 10-30 minutes (fine-tuning, depends on hardware)
• Subsequent Runs: 1-2 minutes (model already created)

📱 Step 6: Testing Your Space

Once deployed, your Space will have:

Main Interface (Main URL):

• 📝 Single Text Analysis - Analyze individual Vietnamese texts
• 📊 Batch Analysis - Process multiple texts
• ℹ️ Model Information - View model details and memory usage
• 🌐 REST API Endpoints - API documentation and examples

REST API (Your Space URL + :7861):

• Interactive Docs: https://your-space.hf.space:7861/docs
• Health Check: GET /health
• Analysis: POST /analyze
• Batch: POST /analyze/batch

🎯 Step 7: API Usage Examples

Python Example:

import requests

response = requests.post(
    "https://your-space.hf.space:7861/analyze",
    json={"text": "Giảng viên dạy rất hay và tâm huyết."}
)
result = response.json()
print(f"Sentiment: {result['sentiment']}")
print(f"Confidence: {result['confidence']:.2%}")

cURL Example:

curl -X POST "https://your-space.hf.space:7861/analyze" \
     -H "Content-Type: application/json" \
     -d '{"text": "Giảng viên dạy rất hay và tâm huyết."}'

⚠️ Step 8: Troubleshooting

Common Issues:

1. Build Fails:

   • Check requirements.txt has all dependencies
   • Ensure no syntax errors in Python files
   • Check Space logs for specific error messages

2. Fine-Tuning Takes Too Long:

   • Consider upgrading to GPU hardware
   • The process will complete eventually on CPU

3. API Not Working:

   • API runs on port 7861 (different from main Gradio port)
   • Check if CORS is enabled (included in our setup)

4. Memory Issues:

   • The app includes automatic memory cleanup
   • Batch size is limited to 10 texts
   • GPU spaces have more memory available

🔧 Step 9: Advanced Configuration

Custom Fine-Tuned Model:

If you have your own fine-tuned model on Hugging Face Hub:

1. Update line 32 in app.py:

   self.finetuned_model = "your-username/your-model-name"
   

Custom Fine-Tuning Parameters:

Modify py/fine_tune_sentiment.py to adjust:

• Learning rate
• Number of epochs
• Batch size
• Dataset

📊 Step 10: Monitoring

Space Metrics:

• Usage statistics in your Space dashboard
• API endpoint performance
• Model loading time
• Memory usage (shown in Model Info tab)

🎉 Success Indicators:

Your deployment is successful when you see:

• ✅ Gradio interface loads with all 4 tabs
• ✅ Model information shows "vietnamese_sentiment_finetuned"
• ✅ API documentation is accessible at /docs
• ✅ Test analysis returns correct sentiment predictions
• ✅ Health check endpoint returns status "healthy"

📞 Support

If you encounter issues:

1. Check the Space logs for error messages
2. Verify all files are uploaded correctly
3. Test locally with python app.py first
4. Review the fine-tuning process in the logs

Your modular Vietnamese Sentiment Analysis app is now ready for production deployment! 🚀