خادم vLLM على Hugging Face Jobs — دليل عملي كامل

🎧 استمع للملخص

بقلم: ليلى | محررة أدوات المطورين · صوت تحريري بإشراف بشري

أمر واحد في الطرفية يكفي الآن لتشغيل خادم LLM خاص ومتوافق مع OpenAI API على بنية Hugging Face — دون إعداد خوادم، ودون Kubernetes، وبفاتورة تُحسب بالثانية. الفكرة تشبه docker run لكن على البنية التحتية لـ HF مباشرةً، مع كشف المنفذ عبر بروكسي عام مؤمَّن بـ token المستخدم.

هذا الدليل يأخذك من الصفر حتى نموذج يعمل فعلياً — مع تفاصيل النماذج الكبيرة، وواجهة المحادثة، والـ SSH، ووكيل البرمجة.

تجهيز المتطلبات الأساسية — تحتاج إلى طريقة دفع أو رصيد مدفوع مسبقاً (الفوترة بالدقيقة حسب نوع الجهاز)، ثم ثبّت huggingface_hub بالإصدار 1.20.0 أو أحدث عبر pip install -U "huggingface_hub>=1.20.0"، وسجّل دخولك بـ hf auth login.
إطلاق الخادم بأمر واحد — الأمر التالي يشغّل صورة vllm/vllm-openai الرسمية على GPU من نوع a10g-large بتكلفة 1.50 دولار/ساعة، ويكشف المنفذ 8000 عبر بروكسي HF:
```
hf jobs run --flavor a10g-large --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3-4B --host 0.0.0.0 --port 8000
```
بعد الإطلاق يطبع الأمر عنوان URL بالشكل https://<job_id>--8000.hf.jobs. احتفظ بالـ job_id، ستحتاجه في كل خطوة تالية. انتظر دقيقتين حتى يظهر في الـ logs السطر Application startup complete.
الاستعلام من أي مكان — vLLM يتحدث OpenAI API بالكامل، وكل طلب يحتاج HF token كـ bearer token فقط. للاختبار السريع عبر curl:
```
curl https://<job_id>--8000.hf.jobs/v1/chat/completions \
  -H "Authorization: Bearer $(hf auth token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-4B",
    "messages": [{"role": "user", "content": "Hello!"}],
    "chat_template_kwargs": {"enable_thinking": false}
  }'
```
أو باستخدام مكتبة openai في Python بتوجيه base_url نحو عنوان الـ job وapi_key=get_token(). للتحقق السريع من أن الخادم يعمل قبل أي استعلام: curl https://<job_id>--8000.hf.jobs/v1/models -H "Authorization: Bearer $(hf auth token)" يجب أن يُعيد قائمة النماذج. الـ endpoint مغلق بالكامل — كل طلب بلا token يُرفض تلقائياً، وهو ما يعني أن البروكسي نفسه يعمل كـ API gateway مقيّد بنطاق حسابك أو مؤسستك.
إيقاف الخادم والتحكم في التكلفة — Jobs تُفوتَر بالثانية، لذا أوقف الخادم صراحةً فور الانتهاء: hf jobs cancel <job_id>. الـ --timeout الذي حددته (مثل 2h) هو شبكة أمان تلقائية فقط، لكن الإلغاء اليدوي أوفر. راجع hf jobs hardware لقائمة كاملة بالأسعار واختر أصغر flavor يستوعب نموذجك.
النماذج الكبيرة: التشظية على عدة GPUs — نفس الأمر يتسع لنماذج ضخمة بتغيير الـ --flavor وإضافة --tensor-parallel-size. مثال على نموذج Qwen3.5-122B-A10B ذي 122 مليار معامل على جهازين H200:
```
hf jobs run --flavor h200x2 --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3.5-122B-A10B \
  --host 0.0.0.0 --port 8000 --tensor-parallel-size 2 \
  --max-model-len 32768 --max-num-seqs 256
```
قيمة --tensor-parallel-size يجب أن تطابق عدد GPUs في الـ flavor: h200x2 تعني 2، h200x8 تعني 8. وأما --max-model-len 32768 --max-num-seqs 256 فضروريان لهذا النموذج تحديداً: Qwen3.5-122B هو معمارية هجينة Mamba/attention بسياق افتراضي يبلغ 256K token، وهذا يستنزف ذاكرة GPU بالكامل مع إعدادات vLLM الافتراضية. إذا فشل نموذج كبير بخطأ out-of-memory أو cache-block، تقليل هذين الرقمين هو الخطوة الأولى.
واجهة محادثة بـ Gradio — بضعة أسطر من Gradio تحوّل الـ endpoint ذاته إلى نافذة دردشة. أضف --reasoning-parser deepseek_r1 إلى أمر vllm serve لتصل تفكير Qwen3 كحقل منفصل، ثم شغّل الكود محلياً باستخدام الـ job_id. عند تشغيله افتح http://127.0.0.1:7860 لترى التفكير يتدفق في لوحة قابلة للطي والإجابة تحتها مباشرة.
SSH داخل الحاوية لتشخيص الأعطال — لتشخيص فشل الإقلاع أو مراقبة ذاكرة GPU أو تتبع الـ logs تفاعلياً، أضف --ssh إلى أمر الإطلاق بعد تسجيل مفتاحك العام في huggingface.co/settings/keys، ثم hf jobs ssh <job_id> يفتح shell مباشراً داخل الحاوية. من هناك يمكنك تشغيل nvidia-smi وفحص العمليات والتفاعل مع النموذج مباشرة. هذه الميزة تتطلب huggingface_hub >= 1.20.0.

استخدام أكثر تقدماً هو توصيل الـ endpoint بوكيل برمجة في الطرفية. Pi هو إطار عمل وكلاء مستقل عن المزوّد — أضف --enable-auto-tool-choice --tool-call-parser hermes إلى أمر vllm serve (الوكلاء يحتاجون tool calls)، ثم عرّف الـ job كـ provider مخصص في ~/.pi/agent/models.json بالـ baseUrl والـ apiKey. بعدها pi في الطرفية يطلق وكيل Read/Write/Edit/Bash يعمل على نموذجك المستضاف بالكامل.

سؤال مشروع يطرحه كثيرون: متى تستخدم HF Jobs بدلاً من Inference Endpoints؟ الإجابة العملية: Jobs هي الأنسب للتجارب والتقييمات والتوليد الدفعي وأي شيء مؤقت — تدفع بالثانية وتتحكم في كل شيء. Inference Endpoints هي الخيار لما تحتاج خدمة دائمة مع تحكم أدق في الوصول (عام/محمي/خاص) وإيقاف تلقائي عند عدم الاستخدام حتى لا تُفوتَر في أوقات الخمول. إذا كنت تختبر نموذجاً قبل الإنتاج، ابدأ بـ Jobs، وانتقل إلى Endpoints حين تكون مستعداً للإطلاق الفعلي.

Hugging Face