الوحدة 9 — النشر على مساحة Hugging Face

بلوغ عرض دائم متاح للجميع دون خادم شخصيّ ولا فاتورة سحابيّة كبيرة: هذا هو ما تُقدّمه Hugging Face Spaces. النطاق المجّانيّ يكفي لكثير من العروض التعليميّة والبحثيّة، والانتقال إلى GPU مدفوع سلس عند الحاجة. هذه الوحدة تشرح إنشاء المساحة، والملفّات المطلوبة، وإدارة الأسرار، ودورة النوم والاستيقاظ.

ما هي مساحة Hugging Face

المساحة (Space) هي مستودع Git مستضاف على Hugging Face يحتوي شيفرة تطبيق Gradio (أو Streamlit، أو Docker). عند كلّ دفع (git push)، تُعاد البناء والنشر تلقائيًّا. الخدمة تعطي عنوانًا دائمًا بشكل https://huggingface.co/spaces/<utilisateur>/<nom>.

الميزات الرئيسة:

مجّانيّ لخيار CPU basic: 2 vCPU و16 GiB ذاكرة، كافٍ لعروض صغيرة أو نماذج مُحسَّنة.
مدفوع لخيارات GPU: من دولار يتجاوز 0.05 في الساعة على T4، إلى A100 وغيره.
النوم التلقائيّ: بعد 48 ساعة من الخمول (على النطاق المجّانيّ)، تُوقَف المساحة وتعود عند أوّل زائر.
الاستيقاظ يستغرق ثواني إلى دقيقتين بحسب حجم النموذج.

إنشاء المساحة في ستّ خطوات

تسجيل حساب على huggingface.co.
صفحة الشخصيّة > New Space.
اختيار اسم، ترخيص (mit أو apache-2.0 غالبًا)، ونوع SDK: Gradio.
اختيار العتاد (CPU basic للبدء).
تحديد ما إذا كان المستودع عامًّا أو خاصًّا.
النقر على Create Space.

يُنشأ مستودع Git فارغ يحوي بيانات وصفيّة في README.md. تُستنسَخ المساحة محلّيًّا:

git clone https://huggingface.co/spaces/mon-utilisateur/mon-app
cd mon-app

الملفّات المطلوبة

مساحة Gradio تحتاج ثلاثة ملفّات كحدّ أدنى:

app.py (نقطة الدخول):

import gradio as gr

def repondre(message, historique):
    return f"استلمت: {message}"

demo = gr.ChatInterface(
    fn=repondre,
    title="مساعد على Space",
    description="أوّل مساحة لك.",
)

if __name__ == "__main__":
    demo.launch()

requirements.txt (الاعتماديّات):

gradio>=5.0
openai>=1.30

README.md (يُنشئه Hugging Face تلقائيًّا مع بيانات وصفيّة):

---
title: مساعد عربيّ
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.0.0
app_file: app.py
pinned: false
license: mit
---

sdk_version مهمّ: إذا استعملت ميزة جديدة في Gradio، ضع النسخة المناسبة كي لا يفشل البناء. بعد الدفع بـgit push، تبدأ عمليّة البناء التي تشاهدها في تبويب Logs على صفحة المساحة.

إدارة الأسرار

مفتاح API لا يُكتب أبدًا في app.py. الحلّ: إعدادات المساحة > Variables and secrets. تُضاف كلّ متغيّرة سرّيّة هناك، وتُقرأ في الشيفرة عبر os.environ:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

المتغيّرات المُعرَّفة كـsecret تظهر في متغيّرات البيئة لكنّها لا تُعرَض في السجلّ ولا في واجهة الويب بعد الحفظ الأوّل. المتغيّرات العامّة (variable) تُعرَض في السجلّ، وتستعمل لقيم غير سرّيّة كنموذج الوصلة (base_url).

تنبيه مهمّ: نسخ نموذج آخر يحوي مفتاحك مباشرة في شيفرته يُسرّبه للعموم. راجع دائمًا شيفرة أيّ مساحة قبل النسخ (Duplicate this Space).

اختيار العتاد

جدول قرار سريع:

العتاد	الكلفة الشهريّة	مناسب لـ
`CPU basic` (2 vCPU)	مجّانيّ	نموذج مكمّم صغير، عرض تعليميّ، بثّ بطيء مقبول
`CPU upgrade` (8 vCPU)	حوالى 0.03 دولار في الساعة	نماذج صغيرة، خدمة متوسّطة
`T4 small` (16 GB)	حوالى 0.40 دولار في الساعة	نموذج لغويّ 7B مكمّم مع بثّ محترم
`A10G large`	حوالى 3.15 دولار في الساعة	نماذج 13B غير مكمّمة، عرض أداء عالٍ
`A100 large`	حوالى 4.13 دولار في الساعة	نماذج ضخمة، صور، فيديو

القاعدة: ابدأ بأصغر عتاد يعمل، وارتقِ فقط عند رؤية بيانات فعليّة تُبرّر ذلك.

النوم والاستيقاظ

المساحات المجّانيّة تنام بعد 48 ساعة من الخمول. المساحات المدفوعة تنام بعد ساعة افتراضيًّا (يُضبَط في الإعدادات). عواقب:

زمن أوّل زائر بعد النوم: تنزيل النموذج + بدء الخادم = ثواني إلى دقيقة.
cache_examples="lazy": يُطبَّق على أوّل زائر بعد كلّ استيقاظ.
المتغيّرات في الذاكرة تُفقَد: أيّ حالة تخزّنها في متغيّر عامّ تختفي مع كلّ نوم.

للحفاظ على مساحة نشطة، استعمل تنبيه دوريّ:

إعدادات > Sleep time لضبط الحدّ الأقصى قبل النوم.
سكربت خارجيّ ينبّه كلّ ساعة (لكنّه يُبطل هدف النوم أساسًا، ولا يُحبَّذ على النطاق المجّانيّ).

تضمين المساحة في موقع

كلّ مساحة تعرض نسخة قابلة للتضمين بـiframe. على صفحة المساحة، تبويب Embed this Space يعطي شفرة جاهزة:

<iframe
  src="https://mon-utilisateur-mon-app.hf.space"
  frameborder="0"
  width="850"
  height="700"
></iframe>

هذا يسمح بدمج العرض في موقع الشركة، أو مدوّنة، أو صفحة توثيق. الاعتبار الوحيد: الحمل يبقى على المساحة، ومحسوبيّة الطلبات كذلك.

سير عمل النشر النموذجيّ

# 1. النسخ المحلّيّ للمساحة الفارغة
git clone https://huggingface.co/spaces/mon-utilisateur/assistant

# 2. إضافة الملفّات
cd assistant
cp -r ../code/* .

# 3. الاختبار المحلّيّ
python app.py

# 4. الدفع
git add app.py requirements.txt README.md
git commit -m "premiere version"
git push

سطر أخير مهمّ: git push يستدعي بيانات اعتماد Hugging Face. الأسرع هو إنشاء «Access Token» بصلاحية write من صفحة الشخصيّة > Settings > Access Tokens، ثمّ استعماله ككلمة مرور عند الدفع.

قراءة السجلّ عند فشل البناء

فشل البناء يظهر في تبويب Logs على صفحة المساحة. الأسباب الشائعة:

اعتماديّة غير متوافقة: نسخة torch تتطلّب CUDA غير متوفّرة على العتاد المختار. الحلّ: تحديد torch بنسخة CPU في requirements.txt.
ذاكرة غير كافية: النموذج أكبر من ذاكرة العتاد. الحلّ: نموذج مكمّم، أو ترقية عتاد.
مفتاح API مفقود: الشيفرة تقرأ os.environ["KEY"] والمتغيّر غير معرّف. الحلّ: إضافته في Secrets.
مهلة بناء: التنزيل بطيء جدًّا. الحلّ: تخفيض حجم الاعتماديّات، أو استعمال cache Hugging Face.

تعقّب استعمال الموارد

مساحة GPU مدفوعة تستمرّ تستهلك حتّى وأنت لا تعمل عليها. راجع تبويب Billing في الحساب أسبوعيًّا. مستخدم واحد نسي مساحة A100 مفتوحة لأسبوع يُنتج فاتورة بمئات الـ«USD» أو الـ«دولار».

الخلاصة

مساحة Hugging Face بديل مثاليّ لـshare=True للنشر الدائم؛ مجّانيّة لخيار CPU basic، مدفوعة لخيار GPU.
ثلاثة ملفّات كافية: app.py، requirements.txt، README.md مع بيانات وصفيّة.
الأسرار تُدار عبر إعدادات المساحة، لا تُكتب في الشيفرة.
النوم والاستيقاظ ظاهرة عادية على النطاق المجّانيّ؛ خطّط للتأخّر عند أوّل زائر بعد الخمول.
التضمين بـiframe يدمج المساحة في موقعك، مع بقاء الحمل عليها.

الوحدة التالية: مشروع كامل يجمع كلّ ما رأيناه في مساعد لغويّ منشور، مع أمثلة وبثّ وقائمة انتظار وجمع ملاحظات.

ما هي مساحة Hugging Face​

إنشاء المساحة في ستّ خطوات​

الملفّات المطلوبة​

إدارة الأسرار​

اختيار العتاد​

النوم والاستيقاظ​

تضمين المساحة في موقع​

سير عمل النشر النموذجيّ​

قراءة السجلّ عند فشل البناء​

الخلاصة​