DEPLOY_GUIDE.md

🚀 دليل النشر على Hugging Face Spaces

المتطلبات

• حساب على Hugging Face (مجاني)
• Git مثبّت على جهازك

---

الخطوات

1. إنشاء Space جديد

1. اذهب إلى: https://huggingface.co/new-space
2. Space name: murshid
3. SDK: اختر Docker
4. Visibility: Public (مجاني) أو Private
5. اضغط Create Space

2. رفع المشروع

cd d:\murishd

# تهيئة Git (إذا لم يكن موجوداً)
git init

# إضافة الـ remote (غيّر YOUR_USERNAME باسم حسابك)
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/murshid

# إضافة الملفات والرفع
git add .
git commit -m "Initial deployment"
git push space main

⚠️ إذا طلب كلمة مرور، استخدم Access Token من: https://huggingface.co/settings/tokens

3. إعداد المتغيرات البيئية (Secrets)

اذهب إلى إعدادات الـ Space: Settings → Variables and secrets

أضف هذه المتغيرات:

الاسم	القيمة	النوع
MURSHID_DB_URL	sqlite:////app/data/murshid.db	Variable
MURSHID_MODELS_DIR	/app/Needed	Variable
MURSHID_SKIP_LLM	true	Variable
SECRET_KEY	(اختر كلمة سر عشوائية)	Secret
HF_TOKEN	(اختياري — لو تبغى Llama)	Secret

4. انتظر البناء

• HF Spaces يبني الـ Docker image تلقائياً
• يأخذ 3-5 دقائق للبناء الأول
• بعد النجاح، الرابط يكون:

  https://YOUR_USERNAME-murshid.hf.space
  

---

الروابط بعد النشر

الرابط	الوصف
https://YOUR_USERNAME-murshid.hf.space	الواجهة الرئيسية
https://YOUR_USERNAME-murshid.hf.space/docs	توثيق Swagger
https://YOUR_USERNAME-murshid.hf.space/health	فحص الحالة

---

ملاحظات

الوضع الحالي (LITE mode)

• المشروع ينشر بوضع LITE (بدون torch/SecureBERT+)
• تحليل القواعد يعمل لكن بدقة أقل (embeddings عشوائية)
• مناسب لاختبار الواجهة والـ API

للترقية إلى LOCAL mode (SecureBERT+ بدون Llama)

عدّل Dockerfile وأزل التعليق من سطر torch:

RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu transformers sentencepiece

⚠️ هذا يزيد حجم الصورة ~800MB ويحتاج ذاكرة أكثر

للترقية إلى FULL mode (مع Llama 3)

• غيّر الـ Space إلى GPU (T4) من الإعدادات ($0.60/ساعة)
• عدّل MURSHID_SKIP_LLM=false
• أضف HF_TOKEN في الـ Secrets
• استخدم requirements.txt الكامل بدل requirements_light.txt

---

استكشاف الأخطاء

المشكلة	الحل
Build فشل	تحقق من الـ Logs في تبويب الـ Space
502 Bad Gateway	انتظر دقيقة — الخادم يبدأ
DB خطأ	تحقق من MURSHID_DB_URL في المتغيرات
Frontend لا يتصل	الـ BASE URL أصبح تلقائي (window.location.origin)