Aigenthix/Graph_RAG

1# Hugging Face Spaces Deployment - RAG Comparison Suite2 3**Version:** 2.0  4**Status:** Production Ready  5**Date:** 2026-06-256 7---8 9## 🎯 Quick Summary10 11Deploy a complete RAG comparison application to Hugging Face Spaces with:12- **3 RAG modes:** Simple, Agentic, Graph13- **4 Groq models:** Llama 3.1 8B, Llama 3.3 70B, GPT-OSS 120B, GPT-OSS 20B14- **Benchmarking:** Automatic performance tracking15- **Web UI:** Professional interface for testing16- **Comparison reports:** HTML reports with metrics17 18**Time to Deploy:** 15 minutes19**Cost:** Free (HF Spaces) + Groq API usage20 21---22 23## 📋 Pre-Deployment Checklist24 25- [ ] Groq account created (https://console.groq.com)26- [ ] API key obtained27- [ ] Hugging Face account (https://huggingface.co)28- [ ] Docker basics understood29- [ ] Git installed locally30 31---32 33## 📁 Files to Upload34 35### Directory Structure36```37your-rag-space/38├── Dockerfile                     (256 bytes)39├── app_docker.py                 (19 KB)40├── requirements_hf.txt           (850 bytes)41├── benchmark.py                  (12 KB)42├── rag_comparison_report.py      (8 KB)43├── backend/                       (entire folder)44│   ├── app/45│   │   ├── __init__.py46│   │   ├── core/47│   │   ├── services/48│   │   ├── processors/49│   │   ├── models/50│   │   └── api/51│   └── config/52├── data/                         (optional)53│   └── sample_documents/54└── README.md                     (deployment guide)55```56 57**Total Size:** ~600 KB58 59---60 61## 🚀 Step-by-Step Deployment62 63### Step 1: Create Hugging Face Space64 651. Go to https://huggingface.co/new-space662. Fill in details:67   - **Space name:** `rag-comparison` (or your choice)68   - **License:** Apache 2.069   - **Space SDK:** Docker703. Click "Create Space"714. Clone the space locally:72   ```bash73   git clone https://huggingface.co/spaces/YOUR_USERNAME/rag-comparison74   cd rag-comparison75   ```76 77---78 79### Step 2: Copy Files from POC180 81Copy these files from your local POC1 directory:82 83```bash84# From POC1 directory85cp Dockerfile /path/to/rag-comparison/86cp app_docker.py /path/to/rag-comparison/87cp requirements_hf.txt /path/to/rag-comparison/88cp benchmark.py /path/to/rag-comparison/89cp rag_comparison_report.py /path/to/rag-comparison/90 91# Copy entire backend folder92cp -r backend/ /path/to/rag-comparison/93 94# Optional: Copy sample documents95mkdir -p /path/to/rag-comparison/data/sample_documents96# Add sample PDFs/CSVs if desired97```98 99---100 101### Step 3: Create README.md102 103Create `README.md` in your space:104 105```markdown106---107title: RAG Comparison Suite108emoji: 🔬109colorFrom: purple110colorTo: blue111sdk: docker112app_port: 7860113---114 115# RAG Comparison Suite116 117Compare Simple RAG, Agentic RAG, and Graph RAG performance on your documents.118 119## Features120 121✅ Upload PDF/CSV documents122✅ Compare 3 RAG modes123✅ 4 Groq models124✅ Real-time benchmarking125✅ Performance metrics126✅ Export results127 128## Getting Started129 1301. Add your `GROQ_API_KEY` to Secrets1312. Upload a document1323. Submit a query1334. View results for each RAG mode1345. Compare performance metrics135 136## Benchmark Locally137 138```bash139python benchmark.py --mode all --iterations 10140python rag_comparison_report.py141```142 143## Documentation144 145- See `HF_RAG_COMPARISON.md` for detailed comparison146- See `BENCHMARK_DATA_SAMPLES.md` for sample results147- See `app_docker.py` for API documentation148```149 150---151 152### Step 4: Git Commit and Push153 154```bash155cd /path/to/rag-comparison156 157# Stage all files158git add .159 160# Commit161git commit -m "Add RAG comparison suite with benchmarking"162 163# Push to HF164git push165```166 167The space will start building automatically.168 169---170 171### Step 5: Add API Key Secret172 173While the space builds (3-5 minutes):174 1751. Go to your space page (hf.co/spaces/YOUR_USERNAME/rag-comparison)1762. Click "Settings" (gear icon)1773. Scroll to "Repository secrets"1784. Click "New secret"1795. Add:180   - **Name:** `GROQ_API_KEY`181   - **Value:** Your key from https://console.groq.com/keys182 183---184 185### Step 6: Deploy & Wait186 1871. After adding the secret, rebuild the space:188   - Settings → "Factory reset" button1892. Wait for build to complete (5-10 minutes)1903. Space will be live at: `hf.co/spaces/YOUR_USERNAME/rag-comparison`191 192---193 194## ✅ Verification After Deployment195 196Test the deployed application:197 198### Check Status199- [ ] Web UI loads without errors200- [ ] Header shows "✅ Using HF Spaces Secrets"201 202### Test Upload203- [ ] Can upload PDF file204- [ ] Can upload CSV file205- [ ] Documents appear in list206 207### Test Query208- [ ] Can type query209- [ ] Can select RAG mode210- [ ] Can select model211- [ ] Query returns results212 213### Check Metrics214- [ ] Results show latency215- [ ] Results show token count216- [ ] Results show cost217- [ ] Results show sources used218 219### Test All Modes220- [ ] Simple RAG works221- [ ] Agentic RAG works222- [ ] Graph RAG works223 224### Compare Models225- [ ] Llama 3.1 8B works226- [ ] Llama 3.3 70B works227- [ ] GPT-OSS 120B works228- [ ] GPT-OSS 20B works229 230---231 232## 🔧 Configuration Files233 234### requirements_hf.txt235 236```txt237Flask==3.0.0238python-dotenv==1.0.0239PyPDF2==4.0.1240pandas==2.1.0241chromadb==0.4.10242sentence-transformers==2.3.0243groq==0.4.1244requests==2.31.0245```246 247### Dockerfile248 249```dockerfile250FROM python:3.11-slim251 252WORKDIR /app253 254# Install system dependencies255RUN apt-get update && apt-get install -y \256    && rm -rf /var/lib/apt/lists/*257 258# Copy requirements259COPY requirements_hf.txt .260 261# Install Python dependencies262RUN pip install --no-cache-dir -r requirements_hf.txt263 264# Copy application265COPY . .266 267# Create data directory268RUN mkdir -p data/uploads data/chroma_data269 270# Expose port271EXPOSE 7860272 273# Run application274CMD ["python", "app_docker.py"]275```276 277---278 279## 📊 Monitoring & Metrics280 281### View Logs2821. Go to space page2832. Click "Logs" tab2843. View real-time build/runtime logs285 286### Check API Usage2871. Go to https://console.groq.com2882. View API usage dashboard2893. Monitor token counts and costs290 291### Performance Metrics292- Each query logs metrics to stdout293- Access via space logs294- CSV export available in web UI295 296---297 298## 🚨 Troubleshooting299 300### Problem: Build Fails301 302**Symptom:** "Build failed" message303 304**Solution:**3051. Check `requirements_hf.txt` versions3062. Verify all imports in `app_docker.py`3073. Check `backend/` folder is complete3084. View logs for specific error309 310### Problem: "API Key not found"311 312**Symptom:** "GROQ_API_KEY not set" error313 314**Solution:**3151. Go to space Settings3162. Verify `GROQ_API_KEY` is in Secrets3173. Trigger "Factory reset"3184. Wait 2 minutes for restart319 320### Problem: No Models in Dropdown321 322**Symptom:** Model selector is empty323 324**Solution:**3251. Check `app_docker.py` lines 310-3163262. Verify `GROQ_MODELS` constant has all 4 models3273. Check browser console for JavaScript errors3284. Try hard refresh (Cmd+Shift+R)329 330### Problem: Queries Time Out331 332**Symptom:** Requests take >30 seconds333 334**Solution:**3351. Check Groq API status (console.groq.com)3362. Try with smaller document3373. Check network latency3384. Try different model (8B faster than 70B)3395. Check Groq API rate limits340 341### Problem: "Permission Denied" on Uploads342 343**Symptom:** File upload fails344 345**Solution:**3461. Verify file size < 50MB3472. Check file format (PDF or CSV)3483. Verify `data/uploads/` directory exists3494. Check disk space in logs350 351---352 353## 📈 Performance Tuning354 355### For Speed356- Use Llama 3.1 8B model357- Use Simple RAG mode358- Reduce `top_k` from 5 to 3359- Reduce `max_tokens` from 1024 to 512360 361### For Accuracy362- Use Llama 3.3 70B or GPT-OSS 120B363- Use Agentic RAG mode364- Increase `top_k` to 7-10365- Increase `temperature` to 0.9366 367### For Cost368- Use Simple RAG mode369- Use Llama 3.1 8B model370- Batch queries if possible371- Reuse documents372 373---374 375## 💰 Cost Estimation376 377### API Costs (using Groq)378```379Simple RAG:   $0.0018/query380Graph RAG:    $0.0030/query381Agentic RAG:  $0.0045/query382 383Monthly (10k queries):384  Simple:     $18385  Graph:      $30386  Agentic:    $45387```388 389### HF Spaces Costs390- **Free tier:** Up to 2 CPU, 16GB RAM (enough for this app)391- **Paid:** $7/month for better hardware (optional)392 393---394 395## 🔒 Security Checklist396 397- [ ] API key in HF Secrets (not in code)398- [ ] No credentials in Dockerfile399- [ ] No sensitive data in logs400- [ ] File upload size limited (50MB)401- [ ] Input validation on queries402- [ ] CORS properly configured403 404---405 406## 📞 Support407 408### Common Issues409- See "Troubleshooting" section above410- Check HF Spaces documentation: https://huggingface.co/docs/hub/spaces411- Check Groq API docs: https://console.groq.com/docs412 413### Getting Help4141. Check logs in HF Spaces dashboard4152. Review error messages carefully4163. Try with sample document4174. Check Groq API status page4185. Test locally first: `python app_docker.py`419 420---421 422## 📦 Advanced Usage423 424### Local Testing Before Deployment425 426```bash427# Install dependencies428pip install -r requirements_hf.txt429 430# Set API key431export GROQ_API_KEY=your_key_here432 433# Run locally434python app_docker.py435 436# Visit http://localhost:5000437```438 439### Run Benchmarks Locally440 441```bash442# Benchmark all modes443python benchmark.py --mode all --iterations 10444 445# Benchmark specific mode446python benchmark.py --mode simple --model llama-3.1-8b-instant447 448# View results449python rag_comparison_report.py450open rag_comparison_report.html451```452 453### Export Results454 455Via web UI:4561. Upload document4572. Submit queries4583. Click "Export Results" button4594. Receive JSON/CSV460 461Via CLI:462```bash463python benchmark.py --output my_results.json464```465 466---467 468## 🎯 Next Steps469 4701. **Deploy:** Follow steps 1-6 above4712. **Test:** Verify all functionality4723. **Benchmark:** Run comparison on your documents4734. **Share:** Share space link with team4745. **Monitor:** Track API usage4756. **Optimize:** Use recommendations to select RAG mode476 477---478 479## 📊 Sample Deployment Timeline480 481```48200:00 - Start deployment48305:00 - Create space and clone48410:00 - Copy files and push48515:00 - Build starts (auto)48620:00 - Build complete, add secrets48722:00 - Factory reset trigger48827:00 - App live and running ✅489```490 491**Total time: ~30 minutes (mostly waiting for builds)**492 493---494 495## ✨ What You Get496 497**Immediately:**498- Working RAG application499- All 3 modes available500- All 4 Groq models available501- Professional web UI502- Real-time metrics503 504**After first query:**505- Benchmark data506- Performance comparison507- Cost analysis508- Recommendations509 510**Over time:**511- Usage patterns512- Model performance trends513- Cost optimization insights514 515---516 517## 🎉 Success Criteria518 519Your deployment is successful when:520 521✅ Web UI loads  522✅ Can upload documents  523✅ Can select RAG mode  524✅ Can select model  525✅ Queries return results  526✅ Metrics display correctly  527✅ Different modes show different results  528✅ No API errors in logs  529 530**Congratulations!** Your RAG comparison suite is live! 🚀531 532---533 534**Last Updated:** 2026-06-25  535**Version:** 2.0  536**Status:** Production Ready537 538For questions or issues, refer to the troubleshooting section or check HF Spaces documentation.539