DEPLOYMENT.md

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

هذا الدليل يوضح كيفية نشر مستشار هيئة أسواق المال على Hugging Face Spaces للحصول على رابط دائم ومجاني.

📋 المتطلبات المسبقة

1. حساب Hugging Face: إنشاء حساب مجاني على huggingface.co
2. Google Gemini API Key: الحصول على مفتاح API من Google AI Studio

🔧 خطوات النشر

الطريقة الأولى: الرفع المباشر (الأسهل)

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

   • اذهب إلى huggingface.co/new-space
   • اختر اسماً للمشروع (مثل: cma-arabic-chatbot)
   • اختر Gradio كـ SDK
   • اختر Public للوصول العام

2. رفع الملفات

   • ارفع جميع الملفات من هذا المجلد:
     • app.py (الملف الرئيسي)
     • requirements.txt
     • README.md
     • LICENSE
   • يمكنك سحب وإفلات الملفات مباشرة في واجهة الويب

3. إعداد المتغيرات السرية

   • اذهب إلى إعدادات Space
   • أضف متغير سري جديد:
     • Name: GEMINI_API_KEY
     • Value: مفتاح Google Gemini API الخاص بك

4. تشغيل التطبيق

   • سيتم بناء وتشغيل التطبيق تلقائياً
   • ستحصل على رابط دائم مثل: https://huggingface.co/spaces/username/cma-arabic-chatbot

الطريقة الثانية: استخدام Git

# 1. استنساخ المستودع
git clone https://huggingface.co/spaces/username/cma-arabic-chatbot
cd cma-arabic-chatbot

# 2. نسخ الملفات
cp -r /path/to/cma-chatbot-hf/* .

# 3. رفع التغييرات
git add .
git commit -m "Initial commit: CMA Arabic Chatbot"
git push

⚙️ إعدادات متقدمة

تخصيص المظهر

يمكنك تعديل ملف app.py لتخصيص:

• الألوان والتصميم
• النصوص والرسائل
• الأمثلة المعروضة

إضافة المزيد من المعرفة

لإضافة المزيد من الأسئلة والأجوبة:

1. عدّل قائمة _load_default_knowledge() في app.py
2. أضف الأسئلة والأجوبة الجديدة
3. احفظ وارفع التغييرات

تحسين الأداء

• استخدم نموذج AI أسرع إذا لزم الأمر
• قلل من حجم قاعدة المعرفة للاستجابة الأسرع
• أضف تخزين مؤقت للاستعلامات المتكررة

🔒 الأمان والخصوصية

حماية مفتاح API

• لا تضع مفتاح API في الكود مباشرة
• استخدم Secrets في إعدادات Hugging Face Space
• تأكد من أن .env مدرج في .gitignore

خصوصية البيانات

• لا يتم حفظ محادثات المستخدمين
• جميع المعالجات تتم في الوقت الفعلي
• لا يتم مشاركة البيانات مع أطراف ثالثة

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

مشاكل شائعة وحلولها

1. خطأ في مفتاح API

Error: No API key found

الحل: تأكد من إضافة GEMINI_API_KEY في إعدادات Secrets

2. خطأ في التبعيات

ModuleNotFoundError: No module named 'gradio'

الحل: تأكد من أن requirements.txt يحتوي على جميع المكتبات المطلوبة

3. مشاكل في العرض العربي

Arabic text not displaying correctly

الحل: تأكد من أن المتصفح يدعم UTF-8 وأن CSS يحتوي على direction: rtl

4. بطء في الاستجابة

Timeout errors or slow responses

الحل:

• تحقق من حالة Google Gemini API
• قلل من حجم السياق المرسل للنموذج
• أضف معالجة أخطاء أفضل

📊 مراقبة الأداء

مقاييس مهمة

• وقت الاستجابة: يجب أن يكون أقل من 10 ثوانٍ
• معدل النجاح: يجب أن يكون أعلى من 95%
• رضا المستخدمين: من خلال التقييمات والتعليقات

تحسين الأداء

• راقب استخدام API quota
• حسّن صياغة الأسئلة للنموذج
• أضف ردود سريعة للأسئلة الشائعة

🔄 التحديثات والصيانة

تحديث المحتوى

1. عدّل قاعدة المعرفة في app.py
2. اختبر التغييرات محلياً
3. ارفع التحديثات إلى Hugging Face

تحديث التقنيات

• راقب تحديثات Gradio
• حدّث مكتبات Python في requirements.txt
• اختبر التوافق مع إصدارات جديدة

📞 الدعم

للمساعدة التقنية

• Hugging Face Community
• Gradio Documentation
• Google AI Documentation

للمساهمة في المشروع

• افتح Issue للإبلاغ عن مشاكل
• اقترح تحسينات عبر Pull Requests
• شارك تجربتك مع المجتمع

---

نصيحة: احتفظ بنسخة احتياطية من مفتاح API وإعدادات المشروع في مكان آمن!