webapp/README_DEPLOYMENT.md

🚀 Deployment Guide: Hugging Face Spaces

This guide will help you deploy your Multi-Personality Chatbot to Hugging Face Spaces for free public access.

📋 Prerequisites

1. Hugging Face Account (free)

   • Sign up at: https://huggingface.co/join
   • Verify your email

2. Git and Git LFS installed

   • Git: https://git-scm.com/downloads
   • Git LFS: https://git-lfs.github.com/

🎯 Step-by-Step Deployment

Step 1: Create a Hugging Face Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in:
   • Space name: personality-chatbot (or your preferred name)
   • License: MIT or Apache 2.0
   • Select SDK: Choose Gradio
   • Hardware: Start with CPU basic (free), upgrade to GPU if needed
   • Visibility: Public (so anyone can access)
4. Click "Create Space"

Step 2: Set Up Local Repository

Open PowerShell in your project folder:

# Navigate to your project
cd C:\Users\dcast\LLM\Project3\llm-project

# Initialize git (if not already done)
git init

# Install Git LFS (for large model files)
git lfs install

# Track large files with Git LFS
git lfs track "*.safetensors"
git lfs track "*.bin"
git lfs track "*.json"

# Add all files
git add .gitattributes
git add .

# Commit
git commit -m "Initial commit: Multi-personality chatbot"

Step 3: Push to Hugging Face

Replace YOUR_USERNAME and YOUR_SPACE_NAME with your actual values:

# Add Hugging Face remote
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

# Push to Hugging Face
git push --set-upstream space main

Authentication: You'll be prompted for username and password

• Username: Your Hugging Face username
• Password: Use your Hugging Face Access Token (not your account password)
  • Get token at: https://huggingface.co/settings/tokens
  • Create a Write token

Step 4: Wait for Build

1. Go to your Space URL: https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
2. The Space will automatically build (takes 5-15 minutes first time)
3. You'll see build logs in the "Logs" tab
4. Once done, your app will be live! 🎉

Step 5: Share Your App

Your app will be accessible at:

https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space

Anyone can access this URL without authentication!

🐛 Troubleshooting

"Repository too large" error

Problem: Adapter files are too big for free tier

Solution: Upload adapters to Hugging Face Model Hub separately

1. Create model repos for each adapter:

   # Install huggingface-hub
   pip install huggingface-hub
   
   # Upload each adapter (run in Python)
   python -c "from huggingface_hub import HfApi; api = HfApi(); api.upload_folder(folder_path='pirate-lora-adapter', repo_id='YOUR_USERNAME/pirate-lora', repo_type='model')"
   

2. Update app.py to load from Hub:

   ADAPTERS = {
       "🏴‍☠️ Pirate": "YOUR_USERNAME/pirate-lora",
       "🧙 Yoda": "YOUR_USERNAME/yoda-lora",
       "🤓 Nerd": "YOUR_USERNAME/nerd-lora",
       "🧠 Brainrot": "YOUR_USERNAME/brainrot-lora",
   }
   

"Out of memory" on CPU

Solution: Upgrade to GPU hardware

1. Go to Space Settings
2. Click "Change hardware"
3. Select "GPU - T4 small" (free tier)

Build fails with "Module not found"

Solution: Check requirements.txt has all dependencies

gradio>=4.0.0
torch>=2.0.0
transformers>=4.35.0
peft>=0.7.0
accelerate>=0.24.0
safetensors>=0.4.0

🎨 Customization

Change app title/description

Edit app.py - modify the gr.Markdown() sections

Add more personalities

1. Train a new adapter
2. Add to ADAPTERS dict in app.py
3. Upload the new adapter folder
4. Push changes: git add . && git commit -m "Add new personality" && git push space main

Improve performance

• Use GPU hardware (Space settings)
• Reduce max_tokens default
• Add response caching

📊 Free Tier Limits

Hugging Face Spaces Free Tier:

• ✅ CPU: Unlimited (but slow for LLMs)
• ✅ GPU T4: Limited hours/month (check your account)
• ✅ Storage: 50GB total
• ✅ Persistence: 24/7 uptime
• ✅ Public access: Unlimited users

Tips to stay within limits:

• Start with CPU, upgrade to GPU if too slow
• Keep model size small (Qwen2-0.5B is perfect)
• Monitor usage in Space Settings

🔗 Useful Links

• Hugging Face Spaces Docs: https://huggingface.co/docs/hub/spaces
• Gradio Docs: https://www.gradio.app/docs
• Git LFS Guide: https://git-lfs.github.com/

🆘 Need Help?

If you encounter issues:

1. Check Space logs (Logs tab)
2. Check build status
3. Ask in Hugging Face Discord: https://discuss.huggingface.co/

---

That's it! Your chatbot is now publicly accessible to anyone with the URL. 🎉