DEPLOYMENT_GUIDE.md

🚀 HuggingFace Spaces Deployment Guide

Complete step-by-step guide to deploy your Dental AI system to HuggingFace Spaces

---

📋 Prerequisites

1. HuggingFace Account: Create free account at huggingface.co
2. Git: Installed on your machine
3. Git LFS: For large files (optional for models)

---

🎯 Deployment Options

Option 1: Web Interface (Easiest) ⭐

Step 1: Create a Space

1. Go to huggingface.co/new-space
2. Fill in details:
   • Name: dental-ai (or your choice)
   • License: mit
   • SDK: Select Gradio
   • Hardware: Select CPU basic (FREE)
3. Click Create Space

Step 2: Upload Files

1. Click Files tab in your new Space
2. Click Add file → Upload files
3. Upload these files:

   app_gradio_huggingface.py    (rename to: app.py)
   requirements_huggingface.txt (rename to: requirements.txt)
   README_HUGGINGFACE.md        (rename to: README.md)
   

Step 3: Wait for Build

• HuggingFace automatically builds and deploys
• Watch build logs in the Logs tab
• Usually takes 3-5 minutes

Step 4: Test Your App

• Your app will be live at: https://huggingface.co/spaces/YOUR_USERNAME/dental-ai
• Upload a test X-ray image
• Verify analysis works

Step 5: Add Models (Optional)

If you want to include trained models:

1. Install Git LFS:

   git lfs install
   

2. Clone your Space:

   git clone https://huggingface.co/spaces/YOUR_USERNAME/dental-ai
   cd dental-ai
   

3. Add models:

   mkdir checkpoints
   cp /path/to/best_dental_unet.pth checkpoints/
   cp /path/to/yolov8n.pt .
   

4. Track large files:

   git lfs track "*.pth"
   git lfs track "*.pt"
   

5. Commit and push:

   git add .
   git commit -m "Add trained models"
   git push
   

---

Option 2: Git Push (Advanced)

Step 1: Create Space

Same as Option 1, Step 1

Step 2: Clone Space

git clone https://huggingface.co/spaces/YOUR_USERNAME/dental-ai
cd dental-ai

Step 3: Copy Files

# Copy main app (MUST be named app.py)
cp /path/to/app_gradio_huggingface.py app.py

# Copy requirements (MUST be named requirements.txt)
cp /path/to/requirements_huggingface.txt requirements.txt

# Copy README
cp /path/to/README_HUGGINGFACE.md README.md

Step 4: Add Optional Files

# Sample X-rays for examples
mkdir examples
cp /path/to/sample_xrays/* examples/

# Trained models (if you have them)
mkdir checkpoints
cp /path/to/best_dental_unet.pth checkpoints/
cp /path/to/yolov8n.pt .

# Track large files with Git LFS
git lfs track "*.pth"
git lfs track "*.pt"
git add .gitattributes

Step 5: Commit and Push

git add .
git commit -m "Initial deployment"
git push

Step 6: Monitor Build

# Watch build logs
# Go to: https://huggingface.co/spaces/YOUR_USERNAME/dental-ai
# Click "Logs" tab

---

📦 File Checklist

Required Files (Minimum Deployment)

• ✅ app.py (renamed from app_gradio_huggingface.py)
• ✅ requirements.txt (renamed from requirements_huggingface.txt)

Recommended Files

• ✅ README.md (for Space documentation)
• ✅ examples/ folder with sample X-rays
• ✅ .gitignore (if using git push method)

Optional Files (For Full Functionality)

• checkpoints/best_dental_unet.pth (trained U-Net model)
• yolov8n.pt or yolo11n.pt (YOLO model - auto-downloads if missing)

---

🔧 Configuration

Hardware Tiers

Tier	CPU	RAM	GPU	Cost	Best For
CPU basic	2 cores	16GB	None	FREE	Demo, testing
CPU upgrade	8 cores	32GB	None	$0.03/hr	Production
T4 small	4 cores	16GB	T4	$0.60/hr	Fast inference
A10G small	4 cores	16GB	A10G	$3.15/hr	Maximum speed

Recommendation: Start with CPU basic (FREE) - our app is optimized for CPU!

Changing Hardware

1. Go to Space settings
2. Click Manage → Hardware
3. Select desired tier
4. Click Update

---

🎨 Customization

Branding

Edit app.py:

# Line 1: Update title
gr.Blocks(title="YOUR COMPANY - Dental AI", ...)

# Lines ~580-600: Update markdown header
gr.Markdown("""
# 🦷 YOUR COMPANY Dental AI
...
""")

# Bottom of file: Update footer
Made with ❤️ by YOUR COMPANY

Colors & Theme

Edit app.py:

# Line ~575: Change theme
gr.Blocks(theme=gr.themes.Soft())  # Options: Soft, Base, Monochrome, etc.

# Or create custom theme:
my_theme = gr.themes.Soft(
    primary_hue="blue",
    secondary_hue="green",
    neutral_hue="slate"
)
gr.Blocks(theme=my_theme)

Examples

Add sample images in app.py:

# After gr.Blocks(...):
with gr.Blocks(...) as demo:
    # ... existing code ...
    
    # Add examples
    gr.Examples(
        examples=[
            ["examples/sample1.jpg", 0.4],
            ["examples/sample2.jpg", 0.5],
        ],
        inputs=[input_image, confidence_slider]
    )

---

🐛 Troubleshooting

Build Fails

Error: ModuleNotFoundError: No module named 'X'

• Fix: Add missing package to requirements.txt

Error: CUDA error or GPU not available

• Fix: Our app forces CPU, but if you see this, add to app.py:

  torch.cuda.is_available = lambda: False
  

App Crashes

Error: Out of memory

• Fix: Upgrade to CPU upgrade tier (more RAM)
• Or: Reduce image processing size in app.py

Error: Timeout after 30 minutes

• Fix: Normal for free tier - app automatically restarts

Slow Performance

Solution 1: Model optimization

# In app.py, add model quantization:
import torch.quantization
model = torch.quantization.quantize_dynamic(model, {torch.nn.Linear}, dtype=torch.qint8)

Solution 2: Upgrade hardware tier

Solution 3: Use smaller models

• Replace yolo11n.pt with yolov8n.pt (smaller)
• Or remove YOLO entirely (use classical CV only)

Models Not Loading

Issue: Models not found

• Fix: Check file paths in app.py match your uploaded files
• Fix: Ensure Git LFS is configured for .pt and .pth files

---

📊 Monitoring

View Usage Stats

1. Go to Space settings
2. Click Analytics
3. See visitor counts, API calls, etc.

Check Logs

1. Go to your Space
2. Click Logs tab
3. View real-time application logs

Performance Metrics

HuggingFace provides:

• Request count
• Average response time
• Error rates
• Uptime percentage

---

🔒 Privacy & Security

Make Space Private

1. Go to Space settings
2. Toggle Private (requires HuggingFace Pro: $9/month)

Add Authentication

Edit app.py:

# At bottom of file:
app.launch(
    share=False,
    server_name="0.0.0.0",
    server_port=7860,
    auth=("username", "password")  # Add this line
)

Rate Limiting

HuggingFace automatically handles:

• 1000 requests/hour for free tier
• Unlimited for paid tiers

---

💰 Cost Estimation

Free Tier

• Cost: $0/month
• Limits: CPU only, 30min timeout, public only
• Best for: Demos, portfolios, testing

Pro Subscription ($9/month)

• Benefits: Private Spaces, no timeout, priority support
• Still: CPU basic is free

GPU Upgrade (Pay-as-you-go)

• T4 GPU: $0.60/hour = ~$18/month (24/7)
• A10G GPU: $3.15/hour = ~$95/month (24/7)
• Recommendation: Only upgrade if need <1s inference

Total Cost Scenarios

Usage	Hardware	Cost
Client Demo	CPU basic	$0
Portfolio	CPU basic + Pro	$9/month
Small Practice	CPU upgrade	~$20/month
Large Clinic	T4 GPU + Pro	~$27/month

---

🚀 Going Live Checklist

Before sharing with client:

• App deployed and accessible
• Tested with multiple X-ray images
• Branding updated (company name, logo)
• README.md documentation complete
• Sample images in examples/ folder
• Error handling tested
• Mobile responsiveness checked
• Loading/processing feedback works
• Reports generate correctly
• Analytics enabled
• Backup deployment plan ready

---

📞 Support

HuggingFace Support

• Docs: huggingface.co/docs/hub/spaces
• Forum: discuss.huggingface.co
• Discord: hf.co/join/discord

Gradio Support

• Docs: gradio.app/docs
• GitHub: github.com/gradio-app/gradio

---

🎉 Next Steps After Deployment

1. Share with Client: Send them the HuggingFace Space URL
2. Gather Feedback: Use analytics to see usage patterns
3. Iterate: Update app based on client requests
4. Scale: Upgrade hardware if needed
5. Monetize: Consider paid tier with API access

---

📝 Quick Reference

Essential Commands

# Clone Space
git clone https://huggingface.co/spaces/USERNAME/SPACE_NAME

# Update Space
git add .
git commit -m "Update message"
git push

# Install Git LFS
git lfs install
git lfs track "*.pth"

Essential Files

• app.py - Main application (REQUIRED)
• requirements.txt - Dependencies (REQUIRED)
• README.md - Documentation (RECOMMENDED)

Essential URLs

• Your Space: https://huggingface.co/spaces/USERNAME/SPACE_NAME
• Create Space: huggingface.co/new-space
• Dashboard: huggingface.co/spaces

---

Ready to deploy? Let's go! 🚀

If you encounter any issues, refer to the troubleshooting section or reach out for support.