استخدام صور Docker

يعمل كل مهمة داخل صورة Docker، التي توفر بيئتها البرمجية، بما في ذلك أدوات النظام والمكتبات المثبتة. باستخدام hf jobs run، تقوم بتوفير صورة وأمر. أما باستخدام hf jobs uv run، فيقوم uv بإعداد بيئة Python لسكربت الخاص بك، وتختار Jobs صورة افتراضية ما لم تحدد صورة معينة.

اختر طريقة تشغيل حمل العمل الخاص بك

ابدأ باستخدام hf jobs uv run عندما يمكن تثبيت تبعيات سكربت بايثون الخاص بك باستخدام uv، كما هو موضح في البدء السريع. اختر صورة عندما تحتاج إلى أدوات نظام إضافية أو ترغب في استخدام بيئة برمجية جاهزة.

يتضمن الصورة الافتراضية Python وuv. راجع إعدادات مهام UV للاطلاع على الصورة الافتراضية الحالية والخيارات المتاحة.

يمكنك استخدام صورة موجودة مسبقًا من مستودع مثل Docker Hub، أو بناء واستضافة صورتك الخاصة باستخدام Docker Space.

استخدام صورة جاهزة

استخدم hf jobs run مع صورة والأمر الذي سيتم تنفيذه داخلها. تعمل أي صورة عامة من Docker Hub أو أي سجل آخر، بما في ذلك وسم محدد. ابدأ بصغيرة:

hf jobs run ubuntu echo 'Hello from the cloud!'

يسحب Job الصورة، ثم ينفّذ الأمر وينتهي. لاستخدام برنامج توفره صورة بالفعل، اختر صورة تتضمنه. على سبيل المثال، استخدم صورة PyTorch لإنشاء tensor على وحدة معالجة رسومية (GPU) ومضاعفة قيمته:

hf jobs run --flavor t4-small --timeout 5m \
    pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
    -- python -c 'import torch; x = torch.ones(3, device="cuda"); print(x * 2)'

توفر الصورة PyTorch ومكدس برمجيات CUDA الخاص بها. يختار --flavor t4-small وحدة المعالجة الرسومية، ويحدد --timeout 5m وقت تشغيل المهمة، ويستخدم أمر Python حزمة PyTorch المثبتة في الصورة. يظهر ناتجه في سجلات المهمة.

-- يفصل خيارات Jobs عن الأمر وحوامله. على سبيل المثال، يُمرَّر --help الذي يأتي بعد هذا الفاصل إلى أمرِك. راجع تمرير الحوامل.

شغّل سكربت خاص بك مع ملفات إدخال وإخراج

يجب أن يكون السكربت الذي يُنفَّذ بواسطة hf jobs run متاحًا داخل المهمة. يمكنك استخدام سكربت مضمّن في الصورة، أو إرفاق مجلد محلي.

على سبيل المثال، افترض أن لديك سكربت استدلال يستخدم حزم Transformers وPyTorch في صورة huggingface/trl. يحتوي مجلد work المحلي لديك على inference.py وinputs.jsonl، ويقبل السكربت مسارات --input و--output. بعد إنشاء Storage Bucket للنتائج، شغّله باستخدام:

hf jobs run --flavor t4-small --timeout 10m \
    -v ./work:/work \
    -v hf://buckets/YOUR_USERNAME/results:/output \
    huggingface/trl \
    -- python /work/inference.py --input /work/inputs.jsonl --output /output/results.jsonl

استبدل YOUR_USERNAME باسم مساحة العمل الخاصة بمالك الدلو. يقوم CLI برفع المجلد المحلي وتثبيته في /work. يقرأ سكربتك المدخلات من هناك ويكتب النتائج إلى الدلو المثبت في /output، حيث تبقى متاحة بعد انتهاء المهمة. عدّل معاملات الأمر والعتاد والوقت المحدد ليناسب سكربتك؛ راجع Volumes لمعرفة خيارات الإدخال والإخراج الأخرى.

استخدام صورة مع uv

استخدم hf jobs uv run --image عندما يحتاج سكربتك إلى أدوات نظام تتجاوز الصورة الافتراضية مع الحفاظ على سير عمل اعتماديات Python الخاص بـ uv. يجب أن تكون الصورة المختارة مثبتًا فيها uv.

يتكون البيئة من ثلاثة أجزاء:

• System tools and libraries in the image, such as ffmpeg or the CUDA toolkit, are available to the Job according to the image’s configuration.
• التبويبات Python packages installed in the image تنتمي إلى بيئة Python الموجودة مسبقًا في الصورة.
• اعتماديات السكربت. عند استخدام ترويسة اعتماديات مضمّنة، يقوم uv بتثبيت حزم Python الخاصة بك في بيئة معزولة. الحزم المثبتة مسبقًا في الصورة غير متاحة تلقائيًا.

على سبيل المثال، قد يحتاج سكربت vLLM إلى صورة تحتوي على أدوات CUDA بينما يستخدم uv لتثبيت تبعيات Python الخاصة به المُعلَنة. يجب أن تبقى أدوات النظام متوافقة مع الحزم التي يثبّتها uv.

إذا كنت ترغب في استخدام PyTorch أو TRL أو vLLM المثبتة مسبقًا في الصورة مباشرةً، فاستخدم hf jobs run. وإذا كنت بحاجة أيضًا إلى uv لتثبيت تبعيات إضافية، فراجع إعادة استخدام حزم الصورة وإضافة تبعيات باستخدام uv.

أنشئ صورتك الخاصة باستخدام مساحة Docker

يمكن لمساحة Docker بناء صورة واستضافتها تتضمن الأدوات التي يحتاجها عملك، بما في ذلك سكربتاتك الخاصة، ويمكن أن تكون الصورة خاصة دون الحاجة إلى حساب في مستودع. على سبيل المثال، أضف FFmpeg إلى صورة Python لتحضير بيئة لمعالجة الصوت أو الفيديو.

أنشئ Docker Space وأضف هذا Dockerfile في جذر مستودعه:

FROM python:3.12-slim-bookworm

# Install FFmpeg for audio and video processing.
RUN apt-get update \
    && apt-get install -y --no-install-recommends ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Match the non-root user ID used by Docker Spaces.
RUN useradd --create-home --uid 1000 user
USER user

# Check that FFmpeg is available.
CMD ["ffmpeg", "-version"]

يوفر FROM بايثون. لا يتضمن هذا الصورة الأساسية FFmpeg، لذا يقوم RUN بتثبيته وقت البناء. ينشئ useradd مستخدمًا مع مجلد منزلي ومعرف مستخدم 1000، بما يتوافق مع Docker Spaces؛ بينما يشغّل USER الأوامر باسم ذلك المستخدم. يحدد CMD أمرًا افتراضيًا، وهنا يتم التحقق من تثبيت FFmpeg.

التزم بالملف وانتظر حتى تُظهر سجلات بناء المساحة أن الصورة تم دفعها. ثم مرر عنوان المساحة حيث كنت تضع اسم الصورة عادةً، مع استبدال YOUR_USERNAME/video-tools بمعرّف مساحتك:

hf jobs run --flavor cpu-basic --timeout 5m \
    hf.co/spaces/YOUR_USERNAME/video-tools -- ffmpeg -version

تظهر الإصدار في سجلات المهمة. قدّم أمرًا مختلفًا بعد عنوان URL الخاص بالمساحة لاستخدام FFmpeg أو Python لأعباء العمل الخاصة بك. لتشمل سكربتك الخاص في الصورة، أضف سطرًا مثل COPY --chown=user:user process.py /app/process.py إلى ملف Dockerfile وشغّل python /app/process.py. راجع ملفات الإدخال والإخراج لتركيب البيانات وحفظ النتائج.

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

لا يُكفَل بقاء الصورة المبنية لـ Space قابلةً للسحب. فقد تُفقد بسبب صيانة السجل أو نقل المنطقة. إذا أبلغ Job عن عدم العثور على الصورة، أعد تشغيل Space من المصنع لإعادة بنائها. تستخدم Jobs دائمًا أحدث نسخة مبنية، لذا فإن أي commit جديد يستبدل الصورة أيضًا.

صور أمثلة

تُدار صور السجل من قبل ناشريها ويمكن تثبيتها على وسم محدد.

استخدم hf jobs run لتنفيذ الأوامر باستخدام الحزم المثبتة في الصورة. أما بالنسبة إلى hf jobs uv run، فتأكد من أن الصورة تحتوي على uv مثبتًا، واتبع إرشادات البيئة المذكورة أعلاه. تصفح أمثلة ودروسًا تعليمية للاطلاع على أحمال العمل التي يمكن تشغيلها وتكييفها.

إعادة استخدام حزم الصورة وإضافة التبعيات باستخدام uv

توفر صور الإطارات (Framework images) حزمًا مثبتة مسبقًا قد تكون بطيئة أو صعبة البناء، مثل PyTorch وvLLM وتوسعات CUDA الخاصة بها. قد لا تزال بحاجة إلى حزم Python إضافية لسكربتاتك — على سبيل المثال، لتحميل صيغة بيانات معينة أو لتتبع التجارب.

يمكنك إعادة استخدام مجموعة الحزم المثبتة مسبقًا في الصورة مع استخدام uv لتثبيت الإضافات. حدد الحزم الإضافية في ترويسة الاعتماديات # /// script في سكربتك، ثم وجّه uv إلى مُفسّر الصورة وأضف حزم الموقع الخاصة به إلى مسار الاستيراد:

hf jobs uv run \
    --image vllm/vllm-openai \
    --flavor l4x4 \
    --python /usr/bin/python3 \
    -e PYTHONPATH=/usr/local/lib/python3.12/dist-packages \
    -s HF_TOKEN \
    generate-responses.py

• --python ينشئ بيئة uv باستخدام مُفسِّر الصورة، بما يتوافق مع إصدار Python المستخدم في الامتدادات المُجمَّعة الخاصة بها. ولا يكشف عن حزم الصورة بحد ذاته.
• -e PYTHONPATH=... يجعل import vllm يشير إلى النسخة المُجمّعة مسبقًا في الصورة لتلك العملية.
• قَصِّ تبعيات # /// script إلى ما تفتقر إليه الصورة. يُبحث في PYTHONPATH قبل بيئة uv، لذا تُخفي الصورة أي شيء تعلنه الترويسة للحزمة نفسها — بما في ذلك إصدار أحدث قمت بتثبيته. التبعيات التي تحتفظ بها لا تزال قادرة على جلب تلك الحزم بشكل غير مباشر؛ لا يستخدم uv PYTHONPATH لإشباع حل التبعيات.

تختلف المسارات من صورة إلى أخرى، لذا افحصها على cpu-basic بدلاً من تثبيتها:

hf jobs run --flavor cpu-basic vllm/vllm-openai bash -c 'which python3; which uv; python3 -m pip show vllm | grep Location'

/usr/bin/python3                              # pass to --python
/usr/local/bin/uv                             # uv is present, so `uv run` works
Location: /usr/local/lib/python3.12/dist-packages   # pass to PYTHONPATH

استبدل vllm بأي مكتبة أخرى تعيد استخدامها. تختلف الترتيبات — فـvllm/vllm-openai وlmsysorg/sglang تستخدم نظام dist-packages المذكور أعلاه، بينما تستخدم unsloth/unsloth بيئة افتراضية (/opt/venv/...)، وتستخدم huggingface/trl بيئة conda (/opt/conda/lib/python3.11/site-packages، الموروثة من pytorch/pytorch).

يختار هذا عمليات بناء الصورة للاستيرادات، وليس لمحلل تبعيات uv. يمكن أن يقلل تقليم الترويسة من التثبيتات المكررة، لكنه لا يضمن التخلص منها. تم طلب uv run --system-site-packages الذي يتخطى خطوة PYTHONPATH من المصدر.

فيما يلي مسارات المفسر والحزم المقابلة لصورة huggingface/trl:

hf jobs uv run \
    --image huggingface/trl \
    --flavor a100-large \
    --python /opt/conda/bin/python3 \
    -e PYTHONPATH=/opt/conda/lib/python3.11/site-packages \
    -s HF_TOKEN \
    train.py

تستخدم هذه الأوامر generate-responses.py وtrain.py كأسماء لسكربتاتك الخاصة.

استكشاف الأخطاء وإصلاحها

استخدام صور الإطارات لمكتبات وحدات معالجة الرسوميات

تتطلب بعض مكتبات وحدات معالجة الرسوميات أدوات نظام إضافية، مثل مُجمِّع CUDA (nvcc) أو NCCL أو cuDNN. لا يضمن تثبيت حزمها الخاصة بلغة بايثون أن تحتوي الصورة على كل أداة يحتاجونها. على سبيل المثال، قد يفشل مُعيّن FlashInfer عند محاولته تجميع نواة في صورة لا تحتوي على مجموعة أدوات CUDA:

RuntimeError: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist

إن تمرير صورة إطار عمل تتضمن أدوات CUDA المطلوبة يعالج خطأ غياب مجموعة الأدوات هذا:

hf jobs uv run --image vllm/vllm-openai --flavor l4x4 -s HF_TOKEN generate-responses.py

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