ترحيل GitHub CI الخاص بك إلى وظائف الوجه المعانقة

إذا كان لديك مستودع GitHub وقمت بتمكين GitHub Actions، فمن المحتمل أنك تستخدم برامج تشغيل مستضافة على GitHub لـ CI. هذا هو الوضع الافتراضي للعديد من المشاريع لأنه بسيط: أضف سير عمل، ثم اكتب runs-on: ubuntu-latest، ويمنحك GitHub آلة.

وهذا الوضع الافتراضي مناسب، لكن له حدودًا أيضًا. يمكن أن تكون إجراءات GitHub بطيئة أو معطلة بسبب الصيانة، وتكون الأجهزة المستضافة عامة، ولا يعد الوصول إلى وحدة معالجة الرسومات أمرًا يمكن تشغيله في معظم المشاريع مفتوحة المصدر. بالنسبة لـ Trackio، بدأت هذه الحدود مهمة. أردنا كلاً من CPU CI الموثوق به لاختبارات الوحدة الأساسية وفحوصات الواجهة الأمامية، ولكن أيضًا GPU CI للاختبارات التي تحتاج إلى التشغيل على أجهزة CUDA الفعلية.

لذا، تم إنشاء بديل: إبقاء GitHub Actions مسؤولاً عن CI، ولكن تشغيل المهام على Hugging Face Jobs.

النتيجة: يعمل CI الخاص بـ Trackio الآن على Hugging Face Jobs ويقوم بتدفق السجلات في الوقت الفعلي، تقليل وقت CI الخاص بمهام وحدة المعالجة المركزية بحوالي 30% وتمكين مجموعة اختبار جديدة بالكامل تعمل على أجهزة GPU!

في هذه المقالة، نشرح خطوة بخطوة كيفية إعادة إنشاء نفس الإعداد لمستودع GitHub الخاص بك. إذا كنت تستخدم وكيلًا، فيمكنك الإشارة إلى هذه المقالة، نظرًا لأننا نقدم تعليمات CLI جنبًا إلى جنب مع التعليمات المستندة إلى المتصفح لنا نحن البشر.

لنبدأ بمقدمة سريعة عن وظيفة Hugging Face Jobs!

ما هي وظائف معانقة الوجه؟

تتيح لك Hugging Face Jobs تشغيل الأوامر أو البرامج النصية على البنية الأساسية بدون خادم لـ Hugging Face مع أي نكهة أجهزة تقريبًا. الوظيفة هي في الأساس:

• أمر للتشغيل
• صورة Docker، من Docker Hub أو Hugging Face Space
• نكهة الأجهزة، مثل وحدة المعالجة المركزية أو t4-small أو h200 GPU
• متغيرات البيئة الاختيارية والأسرار

على سبيل المثال، يمكنك تشغيل:

hf jobs run python:3.12 python -c "print('Hello world')"

أو

hf jobs uv run --flavor a10g-small "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py" 

وهذا يجعل جوبز مناسبًا بشكل طبيعي لـ CI. تعتمد وظائف CI بالفعل على الأوامر، ويتم تشغيلها بالفعل في بيئات نظيفة، وغالبًا ما تستفيد من اختيار الأجهزة المناسبة تمامًا. بالنسبة لمكتبات ML، تعد حالة وحدة معالجة الرسومات (GPU) مقنعة بشكل خاص: يمكنك تشغيل مجموعة اختبار على أجهزة وحدة معالجة الرسومات (GPU) الحقيقية دون الحفاظ على مشغلك الخاص الذي يعمل دائمًا.

الخطوة الأساسية هي ربط إجراءات GitHub بوظائف HF، والتي سنصفها أدناه.

العمارة

لهذا الإعداد، أنشأنا huggingface/jobs-actions، وهو جسر صغير يحول وظيفة GitHub Actions إلى عداء سريع الزوال مستضاف ذاتيًا يعمل داخل وظيفة HF.

يبدو التدفق الكامل كما يلي:

1. يؤدي طلب السحب إلى تشغيل سير عمل GitHub Actions.
2. يصطف GitHub في قائمة الانتظار لأي وظيفة runs-on التسمية غير متوفرة، على سبيل المثال hf-jobs-cpu-upgrade أو hf-jobs-t4-small، ويرسل موقعة workflow_job.queued ربط الويب بالمرسل من خلال تطبيق GitHub.
3. يتحقق المرسل Space من خطاف الويب، ويتحقق من وجود hf-jobs-* التسمية، وإصدار رمز تسجيل عداء GitHub قصير العمر، وبدء مهمة HF على الأجهزة المطابقة.
4. تقوم وظيفة HF بتشغيل عداء GitHub Actions سريع الزوال وتسجيله في الريبو باستخدام رمز اللقطة الواحدة هذا.
5. يقوم GitHub بتعيين مهمة سير العمل المعلقة لهذا العداء؛ ينفذ العداء مهمة CI، ويرسل تقارير الحالة إلى GitHub، ثم يخرج.

من وجهة نظر GitHub، هذا مجرد عداء مستضاف ذاتيًا. من وجهة نظر Hugging Face، إنها مجرد وظيفة تطلق حاوية لتشغيل خطوات سير العمل من إجراءات GitHub الخاصة بالريبو.

الخطوة 1: تكرار مساحة المرسل

أول شيء تحتاجه هو المرسل. هذه مساحة Docker صغيرة تستقبل GitHub workflow_job أحداث webhook وتطلق وظائف HF ردًا على ذلك.

أنشئ هذا أولاً لأن تطبيق GitHub يحتاج إلى عنوان URL للخطاف على الويب، ويأتي عنوان URL هذا من المساحة. يجب أن تكون هذه المساحة ضمن مساحة الاسم الخاصة بك أو ضمن مؤسسة Hugging Face التي يمكنك الوصول إليها للكتابة.

إعداد الويب

اذهب الى huggingface/jobs-actions-dispatcher وانقر تكرار هذه المساحة.

يستخدم:

Owner: your HF user or org
Name: jobs-actions-dispatcher
Hardware: cpu-upgrade

يستخدم cpu-upgrade للحصول على CI حقيقي، يظل المرسل متاحًا لخطافات الويب لـ GitHub. cpu-basic إنه جيد للاختبار ومن المحتمل أن يعمل، لكنه يمكن أن ينام بعد عدم النشاط؛ إذا وصل خطاف الويب الخاص بـ GitHub أثناء تنبيهه، فقد يظل سير العمل في قائمة الانتظار إلى الأبد.

بعد أن يبني، افتح المساحة المكررة. سيظهر لك قسم بعنوان “أسرار المساحة المطلوبة”، والذي يمكنك تجاهله في الوقت الحالي. يجب أن تعرض الصفحة المقصودة عنوان URL للويب هوك لتطبيق GitHub الذي تحتاجه في الخطوة التالية. سوف يبدو مثل هذا:

https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space/webhook

إعداد CLI

إذا كنت تفضل إعداد مساحة المرسل مع وكيل أو استخدام سير عمل واجهة سطر الأوامر:

export HF_NAMESPACE=your-hf-user-or-org
export SPACE_ID="$HF_NAMESPACE/jobs-actions-dispatcher"

hf repo duplicate huggingface/jobs-actions-dispatcher "$SPACE_ID" \
  --type space \
  --flavor cpu-upgrade \
  --exist-ok

ثم قم بتعيين:

export DISPATCHER_URL="https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space"

الخطوة 2: إنشاء وتثبيت تطبيق GitHub

بعد ذلك، قم بإنشاء وتثبيت تطبيق GitHub من المرسل Space نفسه. يحتاج هذا التطبيق إلى إذن للاستماع إلى وظائف سير العمل في قائمة الانتظار وإنشاء رموز تسجيل عداء ذاتية الزوال.

إعداد الويب

افتح مساحة المرسل المكررة:

https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space

في نموذج الإعداد، أدخل GitHub repo الذي يجب تشغيل CI الخاص به على HF Jobs:

YOUR-GITHUB-ORG/YOUR-REPO

ثم انقر فوق الزر لإنشاء تطبيق GitHub. سيطلب منك GitHub اختيار اسم للتطبيق؛ يمكن أن يكون الاسم أي شيء، طالما أنه متاح في حسابك أو مؤسستك على GitHub. بعد الإرسال، تخبرك الشاشة النهائية بالضبط بكيفية تحميل بيانات اعتماد التطبيق إلى المرسل Space باستخدام ملف hf سطر الأوامر.

ملاحظة هامة: ستحتاج إلى توفير رمز Hugging Face الذي يتمتع بأذونات لتشغيل الوظائف، بما يتوافق مع حسابك الشخصي أو المؤسسة التي يجب أن يتم تحصيل رسوم الوظائف من خلالها. يجب حفظ هذا الرمز المميز باسم HF_TOKEN سر في الفضاء المرسل الخاص بك.

أخيرًا، ستقوم بتثبيت التطبيق على نفس مستودع GitHub الذي أدخلته في المساحة. في إعداد Trackio، قمنا بتثبيته gradio-app/trackio.

الإعداد بمساعدة الوكيل

لا يزال تدفق بيان تطبيق GitHub يعتمد على المتصفح، ولكن يمكن للوكيل اتباع نفس المسار المستند إلى المساحة:

export HF_NAMESPACE=your-hf-user-or-org
export GITHUB_REPO=YOUR-GITHUB-ORG/YOUR-REPO
open "https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space"

لصق $GITHUB_REPO في المساحة، انقر فوق زر إنشاء تطبيق GitHub، واختر أي اسم تطبيق متاح، واتبع تعليمات GitHub التي تم إنشاؤها.

بعد وجود التطبيق، قم بتثبيته على الريبو الخاص بك من صفحة إعدادات التطبيق. بالنسبة لمؤسسة GitHub، توجد إعدادات التثبيت ضمن:

https://github.com/organizations/YOUR-GITHUB-ORG/settings/installations

الخطوة 3: إعدادات المرسل النهائية

عند هذه النقطة، ينبغي تكوين مساحة المرسل. أنشأ تدفق إعداد تطبيق GitHub الأوامر التي تقوم بتحميل بيانات اعتماد التطبيق، وسر خطاف الويب، ورمز Hugging Face المميز إلى المساحة.

افتراضيًا، يتم تشغيل وظائف HF ضمن نفس مساحة الاسم مثل مساحة المرسل. اختياريا، تعيين HF_NAMESPACE كمتغير مسافة إذا كنت تريد إرسال فواتير المهام إلى مستخدم أو مؤسسة Hugging Face مختلفة:

export SPACE_ID=YOUR-HF-NAMESPACE/jobs-actions-dispatcher
hf spaces variables add "$SPACE_ID" -e HF_NAMESPACE=your-billing-namespace
hf spaces restart "$SPACE_ID"

يجب أن يتوافق الرمز المميز الذي قمت بتعيينه في الخطوة 2 مع مساحة الاسم هذه.

الخطوة 4: التغيير runs-on

التغيير الفعلي في سير العمل صغير. بدلاً من:

runs-on: ubuntu-latest

استخدم إحدى التصنيفات التي يتعامل معها المرسل:

runs-on: hf-jobs-cpu-upgrade

بالنسبة لاختبارات GPU، استخدم تسمية GPU:

runs-on: hf-jobs-t4-small

بالنسبة لأي إجراء على GitHub ترغب في تشغيله على HF Jobs، فإن هذا التغيير المكون من سطر واحد هو كل ما تحتاجه!

الخطوة 5: اختبرها

لإضافة الحد الأدنى من سير عمل اختبار الدخان من CLI:

mkdir -p .github/workflows
cat > .github/workflows/hf-jobs-test.yml <<'EOF'
name: HF Jobs Test

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  test:
    runs-on: hf-jobs-cpu-upgrade
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from Hugging Face Jobs"
EOF

git add .github/workflows/hf-jobs-test.yml
git commit -m "Run CI on Hugging Face Jobs"
git push

للتحقق من CLI:

gh run list --repo YOUR-GITHUB-ORG/YOUR-REPO --limit 5
hf jobs ps --namespace "$HF_NAMESPACE"
hf spaces logs "$SPACE_ID"

من المفترض أن تكون قادرًا على رؤية السجلات تمامًا مثل إجراء GitHub العادي، على سبيل المثال، في Trackio PR #565.

وهذا كل شيء!

ملاحظة حول اختيار صورة Docker الصحيحة

تم استخدام أول إعداد لوحدة المعالجة المركزية لدينا ubuntu:22.04 وتثبيت حزم النظام المفقودة أثناء كل عملية تشغيل. وقد نجح ذلك، لكنه كان أبطأ مما ينبغي. جيثب ubuntu-latest تتضمن الصورة الكثير من أدوات المطورين بشكل افتراضي؛ صورة Ubuntu العارية لا تفعل ذلك.

بالنسبة إلى Trackio، تحتاج اختبارات واجهة المستخدم إلى اعتماديات بناء متصفحات Playwright وNode وffmpeg وsqlite وgit وLinux العادية. يدعم Hugging Face Jobs استخدام أي صورة من صور Docker، لذلك قمنا بالتبديل إلى صورة Microsoft Playwright، والتي عملت بشكل جيد:

mcr.microsoft.com/playwright:v1.60.0-jammy

بالنسبة لوظائف GPU، استخدمنا:

nvidia/cuda:12.4.0-runtime-ubuntu22.04

نتائج

فيما يلي الأرقام من Trackio CI:

وكان الفوز الأكبر هو GPU CI. تم تشغيل فحص Trackio GPU على HF Jobs وتم تمريره 45s، بتكلفة أقل من سنت واحد في t4-small معدل لتلك المدة.

وكانت نتيجة وحدة المعالجة المركزية مشجعة أيضًا. باستخدام الصورة الصحيحة، كانت مهمة اختبار Linux أسرع من خط الأساس المستضاف على GitHub. يشير ذلك إلى أن HF Jobs يمكن أن تكون بمثابة واجهة خلفية عملية لـ CI، خاصة بالنسبة لمشاريع ML التي تحتاج إلى صور أو مسرعات مخصصة.

وكانت السجلات مفاجأة سارة أخرى. تعد سجلات GitHub Actions مفيدة، ولكن يمكن أن تكون واجهة مستخدم الويب ثقيلة بالنسبة للسجلات الكبيرة. من السهل جلب سجلات وظائف HF من واجهة سطر الأوامر:

hf jobs logs <job_id> > logs.txt

وهذا يجعلها سهلة الفحص باستخدام الأدوات المحلية أو وكلاء الترميز. في جسرنا، قمنا أيضًا بعكس سجل وظائف GitHub Actions في سجل وظائف HF، بحيث يكون لدى أي نظام معلومات كافية لتصحيح أخطاء التشغيل.

أخيرًا، على الرغم من أننا لم نكن بحاجة إليها من أجل CI الخاص بـ Trackio، فإن HF Jobs تدعم أيضًا وحدات التخزين المتصاعدة، والتي يمكن أن تكون مفيدة جدًا إذا كنت بحاجة إلى تحميل مجموعات البيانات أو النماذج من Hugging Face بسرعة كجزء من CI الخاص بك.

نأمل أن يمنحك هذا كل ما تحتاجه لتجربة HF Jobs لتشغيل إجراءات GitHub الخاصة بك!