HUGGING-FACE-DEPLOYMENT.md

Hugging Face Spaces Deployment Guide

This guide provides detailed steps for deploying the Image Description application to Hugging Face Spaces.

Prerequisites

• A Hugging Face account
• A GitHub repository containing your application code
• The code should include all files created in this project

Step 1: Prepare Your GitHub Repository

1. Make sure your GitHub repository contains all necessary files:

   • image_descriptor.py (Flask API)
   • app.py (Gradio UI)
   • Dockerfile
   • entrypoint.sh
   • image_descriptor_requirements.txt
   • data_temp/ directory with sample images
   • .env file with configuration
   • .gitignore

2. Commit all changes to your repository:

   git add .
   git commit -m "Prepare for Hugging Face Spaces deployment"
   git push
   

Step 2: Create a New Hugging Face Space

1. Go to Hugging Face Spaces

2. Click on "Create new Space"

3. Fill out the form:

   • Owner: Your Hugging Face username or organization
   • Space name: Choose a unique name (e.g., "image-description-qwen")
   • License: Choose an appropriate license (e.g., Apache 2.0)
   • SDK: Select "Docker"
   • Hardware: Select "A10G" for best performance with this model
   • Visibility: Choose public or private based on your needs

4. Click "Create Space"

Step 3: Link Your GitHub Repository

1. On your new Space page, go to the "Settings" tab
2. Under "Repository", click "Link external repository"
3. Enter your GitHub repository URL
4. Click "Link repository"
5. Choose the branch to deploy (e.g., "main" or "master")
6. Click "Save"

Step 4: Configure the Space

1. Stay on the "Settings" tab
2. Under "Variables", you can add environment variables if needed (most are already in the Dockerfile)
3. Under "Advanced settings", enable "Secret HTTPS Frontend"

Step 5: Deploy and Monitor

1. Go to the "Factory" tab to see the build progress
2. Wait for the build and deployment to complete (this may take 10-20 minutes)
3. Check the logs for any errors
4. Once deployment is successful, go to the "App" tab to use your application

Step 6: Test Your Deployed Application

1. On the "App" tab, upload an image
2. Click "Analyze Image"
3. Verify that the model generates descriptions correctly

Troubleshooting Common Issues

• Build Failures: Check the "Factory" logs for detailed error messages
• Memory Issues: If the model crashes, you may need to adjust the quantization settings or use a smaller model
• Slow Performance: The first run will be slow as the model is downloaded; subsequent runs will be faster
• UI Issues: If the UI loads but the model doesn't work, check the browser console and server logs

Updating Your Space

To update your Space after making changes to your code:

1. Make changes to your code
2. Commit and push to GitHub
3. The Space will automatically rebuild and deploy the updated code

Sharing Your Space

• You can share your Space by giving others the URL
• You can embed your Space in other websites using the iframe code provided in the "Embed" tab
• You can collaborate with others by adding them as contributors in the "Settings" tab

Additional Resources

• Hugging Face Spaces Documentation
• Docker SDK Documentation
• Gradio Documentation