Spaces:
Sleeping
Sleeping
| # 🚀 Hugging Face Spaces Deployment Guide (Docker + Streamlit) | |
| This guide will walk you through deploying your RAG system to Hugging Face Spaces using **Docker with Streamlit**. | |
| ## 📋 Prerequisites | |
| - Hugging Face account | |
| - All files from the `huggingface_deploy/` folder | |
| - Basic understanding of Docker (optional) | |
| ## 🎯 Step-by-Step Deployment | |
| ### Step 1: Create a New Space | |
| 1. **Go to Hugging Face Spaces:** | |
| - Visit [https://huggingface.co/spaces](https://huggingface.co/spaces) | |
| - Click "Create new Space" | |
| 2. **Configure your Space:** | |
| - **Owner**: Choose your username or organization | |
| - **Space name**: Choose a unique name (e.g., `my-rag-system`) | |
| - **License**: Choose appropriate license (e.g., MIT) | |
| - **SDK**: Select **Docker** | |
| - **Visibility**: Choose Public or Private | |
| - **Hardware**: Select appropriate hardware (CPU is sufficient for basic usage) | |
| 3. **Click "Create Space"** | |
| ### Step 2: Upload Files | |
| #### Option A: Using Git (Recommended) | |
| 1. **Clone your Space repository:** | |
| ```bash | |
| git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME | |
| cd YOUR_SPACE_NAME | |
| ``` | |
| 2. **Copy files from the deployment folder:** | |
| ```bash | |
| cp -r ../huggingface_deploy/* . | |
| ``` | |
| 3. **Commit and push:** | |
| ```bash | |
| git add . | |
| git commit -m "Initial RAG system deployment with Docker" | |
| git push | |
| ``` | |
| #### Option B: Using Web Interface | |
| 1. **Upload files manually:** | |
| - Go to your Space's "Files" tab | |
| - Click "Add file" → "Upload files" | |
| - Upload all files from the `huggingface_deploy/` folder: | |
| - `app.py` | |
| - `rag_system.py` | |
| - `pdf_processor.py` | |
| - `requirements.txt` | |
| - `Dockerfile` | |
| - `.dockerignore` | |
| - `README.md` | |
| ### Step 3: Configure the Space | |
| 1. **Set up environment variables (optional):** | |
| - Go to your Space's "Settings" tab | |
| - Add environment variables if needed: | |
| ``` | |
| EMBEDDING_MODEL=all-MiniLM-L6-v2 | |
| GENERATIVE_MODEL=Qwen/Qwen2.5-1.5B-Instruct | |
| ``` | |
| 2. **Configure hardware (if needed):** | |
| - Go to "Settings" → "Hardware" | |
| - Select appropriate hardware based on your needs | |
| ### Step 4: Deploy and Test | |
| 1. **Wait for deployment:** | |
| - Hugging Face will automatically build and deploy your Docker container | |
| - This may take 10-15 minutes for the first deployment (model downloads) | |
| 2. **Test your application:** | |
| - Visit your Space URL: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME` | |
| - Upload a PDF document | |
| - Ask questions to test the RAG system | |
| ## 🔧 Docker Configuration | |
| ### Dockerfile Features | |
| - **Base Image**: Python 3.10 slim | |
| - **System Dependencies**: build-essential, curl | |
| - **Health Check**: Monitors Streamlit health endpoint | |
| - **Environment Variables**: Configured for Streamlit | |
| - **Port**: Exposes port 8501 | |
| ### Local Docker Testing | |
| You can test the Docker build locally: | |
| ```bash | |
| # Build the Docker image | |
| docker build -t rag-system . | |
| # Run the container | |
| docker run -p 8501:8501 rag-system | |
| # Or use docker-compose | |
| docker-compose up --build | |
| ``` | |
| ## 🔧 Configuration Options | |
| ### Environment Variables | |
| You can customize your deployment by setting these environment variables in your Space settings: | |
| ```bash | |
| # Model configuration | |
| EMBEDDING_MODEL=all-MiniLM-L6-v2 | |
| GENERATIVE_MODEL=Qwen/Qwen2.5-1.5B-Instruct | |
| # Chunk sizes | |
| CHUNK_SIZES=100,400 | |
| # Vector store path | |
| VECTOR_STORE_PATH=./vector_store | |
| # Streamlit configuration | |
| STREAMLIT_SERVER_PORT=8501 | |
| STREAMLIT_SERVER_ADDRESS=0.0.0.0 | |
| STREAMLIT_SERVER_HEADLESS=true | |
| ``` | |
| ### Hardware Options | |
| - **CPU**: Sufficient for basic usage, slower inference | |
| - **T4**: Good for faster inference, limited memory | |
| - **A10G**: High performance, more memory | |
| - **A100**: Maximum performance, highest cost | |
| ## 🐛 Troubleshooting | |
| ### Common Issues | |
| 1. **Build Fails** | |
| - Check that all required files are uploaded | |
| - Verify `requirements.txt` and `Dockerfile` are correct | |
| - Check the build logs for specific errors | |
| 2. **Model Loading Errors** | |
| - Ensure internet connectivity for model downloads | |
| - Check model names are correct | |
| - Verify sufficient disk space | |
| 3. **Memory Issues** | |
| - Use smaller models | |
| - Reduce chunk sizes | |
| - Upgrade to higher-tier hardware | |
| 4. **Slow Performance** | |
| - Upgrade hardware tier | |
| - Use smaller embedding models | |
| - Optimize chunk sizes | |
| 5. **Docker Build Issues** | |
| - Check `.dockerignore` excludes unnecessary files | |
| - Verify Dockerfile syntax | |
| - Check for missing dependencies | |
| ### Debug Mode | |
| To enable debug logging, add this to your `app.py`: | |
| ```python | |
| import logging | |
| logging.basicConfig(level=logging.DEBUG) | |
| ``` | |
| ## 📊 Monitoring | |
| ### Space Metrics | |
| - **Build Status**: Check if Docker build was successful | |
| - **Runtime Logs**: Monitor application logs | |
| - **Resource Usage**: Track CPU and memory usage | |
| - **Error Logs**: Identify and fix issues | |
| ### Docker Logs | |
| Check Docker logs in your Space: | |
| - Go to "Settings" → "Logs" | |
| - Monitor build and runtime logs | |
| - Look for error messages | |
| ## 🔒 Security Considerations | |
| 1. **File Upload:** | |
| - Validate PDF files before processing | |
| - Implement file size limits | |
| - Check file types | |
| 2. **Model Access:** | |
| - Use appropriate model access tokens | |
| - Consider private models for sensitive data | |
| 3. **Data Privacy:** | |
| - Be aware that uploaded documents are processed | |
| - Consider data retention policies | |
| 4. **Docker Security:** | |
| - Use non-root user in Dockerfile | |
| - Minimize attack surface | |
| - Keep base images updated | |
| ## 📈 Scaling | |
| ### For Production Use | |
| 1. **Multiple Spaces:** | |
| - Create separate Spaces for different use cases | |
| - Use different hardware tiers as needed | |
| 2. **Custom Domains:** | |
| - Set up custom domains for your Spaces | |
| - Use proper SSL certificates | |
| 3. **Load Balancing:** | |
| - Consider multiple Space instances | |
| - Implement proper caching strategies | |
| ## 🎉 Success Checklist | |
| - [ ] Space created successfully with Docker SDK | |
| - [ ] All files uploaded (including Dockerfile) | |
| - [ ] Docker build completed without errors | |
| - [ ] Application loads correctly | |
| - [ ] PDF upload works | |
| - [ ] Question answering works | |
| - [ ] Search results display correctly | |
| - [ ] Performance is acceptable | |
| ## 📞 Support | |
| If you encounter issues: | |
| 1. **Check the logs** in your Space's "Logs" tab | |
| 2. **Review this guide** for common solutions | |
| 3. **Search Hugging Face documentation** | |
| 4. **Create an issue** in the project repository | |
| 5. **Contact Hugging Face support** for Space-specific issues | |
| ## 🚀 Next Steps | |
| After successful deployment: | |
| 1. **Test thoroughly** with different document types | |
| 2. **Optimize performance** based on usage patterns | |
| 3. **Add custom features** as needed | |
| 4. **Share your Space** with others | |
| 5. **Monitor usage** and gather feedback | |
| ## 🔄 Updates and Maintenance | |
| ### Updating Your Space | |
| 1. **Make changes locally** | |
| 2. **Test with Docker locally** | |
| 3. **Push changes to your Space repository** | |
| 4. **Monitor the rebuild process** | |
| ### Version Management | |
| - Use specific versions in `requirements.txt` | |
| - Tag your Docker images | |
| - Keep track of model versions | |
| --- | |
| **Happy deploying with Docker! 🐳🚀** | |