# استضافة النماذج على المهام

بفضل [المنافذ المكشوفة](./jobs-configuration#expose-ports)، يمكن أن يعمل Job كخادم استدلال مؤقت: شغّل vLLM على نكهة GPU، وجّه أي عميل متوافق مع OpenAI إلى عنوان URL الخاص بالـ job، ثم ألغِ الـ job عند الانتهاء. تدفع مقابل كل دقيقة أثناء تشغيل الـ job، ويختفي نقطة النهاية مع اختفاء الـ job.

يُعدّ هذا الخيار مناسبًا عندما يكون نقطة النهاية وسيلةً وليس غايةً: كجلسة تقييم، أو جلسة تسمية بيانات، أو تكرار صياغة الأوامر (Prompts) مقابل نموذج نشط، أو عرض توضيحي لا يحتاج إلى البقاء سوى بعدّة ساعات.

> [!TIP]
> إذا كنت ترغب في نقطة نهاية أكثر دواماً لا تختفي، فإن ما تحتاجه هو [نقاط النهاية للاستدلال](https://huggingface.co/docs/inference-endpoints)، التي توفر بنية تحتية مُدارة مع التوسع التلقائي، والمراقبة، وعناوين URL مستقرة.

## بدء خادم vLLM

يحتوي صورة `vllm/vllm-openai` على كل شيء مثبت مسبقًا. أمر واحد يبدأ خادمًا متوافقًا مع OpenAI:

```bash
>>> hf jobs run --detach --expose 8000 --flavor a10g-small -s HF_TOKEN \
...   vllm/vllm-openai \
...   vllm serve LiquidAI/LFM2.5-8B-A1B --max-model-len 8192
✓ Job started
  id: 6a2b137a59bbdade52d4a58c
  url: https://huggingface.co/jobs/davanstrien/6a2b137a59bbdade52d4a58c
Hint: Exposed ports are reachable at (requires an HF token with read access to the job):
  https://6a2b137a59bbdade52d4a58c--8000.hf.jobs
```

`-s HF_TOKEN` يمرر رمز Hugging Face الخاص بك إلى المهمة كسرّ، مما يجعل تنزيل النموذج مصادَقًا — وهو مطلوب للنماذج المقيدة أو الخاصة، ويمنحك حدود معدل أعلى وتنزيلات أسرع لبقية النماذج.

> [!NOTE]
> تنفّذ Jobs الأمر الذي توفّره مباشرةً — فهي لا تمرّر الحُجج إلى نقطة دخول الصورة كما تفعل `docker run`. اكتب دائمًا الأمر الكامل (`vllm serve ...`، وليس فقط `--model ...`).

يستغرق الخادم بضع دقائق حتى يصبح جاهزًا (سحب الصورة، تنزيل النموذج، تحميل النموذج). تابع التقدم باستخدام `hf jobs logs -f <job_id>`؛ يكون الخادم جاهزًا عندما تظهر في السجلات `Application startup complete`.

## الاتصال بعميل

تتطلب المنافذ المكشوفة رمز HF مع صلاحية `read` على مساحة اسم المهمة، ويُمرَّر كرمز Bearer. بالنسبة لخادم متوافق مع OpenAI، يُدرج هذا مباشرةً في مفتاح API الخاص بالعميل — حيث يكون عنوان URL الأساسي هو عنوان منفذ URL المكشوف مضافًا إليه `/v1`:

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://6a2b137a59bbdade52d4a58c--8000.hf.jobs/v1",
    api_key=os.environ["HF_TOKEN"],  # any token with read access to the job's namespace
)

response = client.chat.completions.create(
    model="LiquidAI/LFM2.5-8B-A1B",
    messages=[{"role": "user", "content": "Write a haiku about ephemeral compute."}],
)
print(response.choices[0].message.content)
```

LFM2.5 هو نموذج استدلال، لذا تتضمن الاستجابة استدلاله داخل وسوم `<think>` قبل الإجابة النهائية.

أو باستخدام `curl`:

```bash
>>> curl https://6a2b137a59bbdade52d4a58c--8000.hf.jobs/v1/chat/completions \
...   -H "Authorization: Bearer $HF_TOKEN" \
...   -H "Content-Type: application/json" \
...   -d '{"model": "LiquidAI/LFM2.5-8B-A1B", "messages": [{"role": "user", "content": "Hello!"}]}'
```

بما أن الرمز الرمزي (token) يسافر في ترويسة `Authorization`، فإن هذه الروابط تعمل من السكربتات ودفاتر الملاحظات (notebooks) والوكلاء — أي مكان تستخدم فيه واجهة برمجة تطبيقات متوافقة مع OpenAI. ولا يمكن فتحها مباشرةً في المتصفح. لخدمة منفذ (port) دون رمز HF، استخدم `--expose-public` — راجع [إظهار المنافذ](./jobs-configuration#expose-ports).

## استضافة نماذج GGUF باستخدام llama.cpp

يعمل النمط نفسه مع أي خادم يتعامل مع بروتوكول HTTP. حيث يجلب `llama serve` في llama.cpp ملفات GGUF مباشرةً من Hub باستخدام علم `-hf` ويقدم نفس واجهة API المتوافقة مع OpenAI. على سبيل المثال، لتقديم [Gemma 4 E4B](https://huggingface.co/ggml-org/gemma-4-E4B-it-GGUF) باستخدام إعدادات أخذ العينات الموصى بها من Gemma:

```bash
>>> hf jobs run --detach --expose 8080 --flavor a10g-small -s HF_TOKEN \
...   ghcr.io/ggml-org/llama.cpp:server-cuda -- \
...   /app/llama serve -hf ggml-org/gemma-4-E4B-it-GGUF \
...   --host 0.0.0.0 --port 8080 -ngl 99 \
...   --temp 1.0 --top-p 0.95 --top-k 64
```

يفصل `--` بين أمر المهمة وخيارات `hf jobs run` الخاصة به — وهو ضروري هنا لأن أعلام `llama serve` ستُحلَّل بواسطة سطر الأوامر نفسه في حال عدم وجوده.

> [!TIP]
> يمكنك تجاوز تنزيل النموذج بالكامل عن طريق تركيب مستودع النموذج كحجم للقراءة فقط وتوجيه الخادم إلى الملف مباشرةً:
>
> ```bash
> >>> hf jobs run --detach --expose 8080 --flavor a10g-small -s HF_TOKEN \
> ...   -v hf://ggml-org/gemma-4-E4B-it-GGUF:/model:ro \
> ...   ghcr.io/ggml-org/llama.cpp:server-cuda -- \
> ...   /app/llama serve --model /model/gemma-4-E4B-it-Q4_K_M.gguf \
> ...   --host 0.0.0.0 --port 8080 -ngl 99
> ```
>
> يبدأ الخادم بسرعة أكبر بكثير لأنه لا يوجد شيء لتحميله — يتم بث النموذج من المستودع المُثبَّت أثناء تحميله.

> [!WARNING]
> يجب أن يستمع خادمك إلى `0.0.0.0`. يرتبط `llama serve` بـ `127.0.0.1` افتراضيًا، وهو ما لا يمكن للوكيل الوسيط للمهام الوصول إليه — قم بتمرير `--host 0.0.0.0` بشكل صريح.

ينطبق الأمر نفسه على أي خادم متوافق مع OpenAI آخر (SGLang، ...): شغّل الخادم على منفذ مكشوف، واستمع على `0.0.0.0`، واتصل باستخدام رمز HF الخاص بك كمفتاح API.

## إيقاف الخادم

يتوقف العمل — وفاتورته — عند إلغائه أو عند بلوغ مهلة انتهائه (30 دقيقة افتراضيًا؛ اضبط `--timeout` صراحةً للجلسات الأطول):

```bash
>>> hf jobs cancel <job_id>
```

> [!NOTE]
> تتطلب المنافذ المكشوفة `huggingface_hub` >= 1.19.0 وتُحتسب رسومها فوق سعر عتاد المهمة — راجع [أسعار المهام](./jobs-pricing).