دليل البدء السريع باستخدام Docker مع Ultralytics#
يقدّم هذا الدليل مقدمة شاملة لإعداد بيئة Docker لمشروعاتك باستخدام Ultralytics. يُعدّ Docker منصة لتطوير التطبيقات وشحنها وتشغيلها داخل حاويات. وهو مفيد بشكل خاص لضمان تشغيل البرنامج دائمًا بالطريقة نفسها، بغضّ النظر عن مكان نشره. لمزيد من التفاصيل، تفضّل بزيارة مستودع Ultralytics على Docker Hub.
ما ستتعلّمه#
- إعداد Docker مع دعم NVIDIA
- تثبيت صور Docker الخاصة بـ Ultralytics
- تشغيل Ultralytics في حاوية Docker مع دعم CPU أو GPU
- استخدام خادم عرض مع Docker لإظهار نتائج الكشف الخاصة بـ Ultralytics
- تحميل الأدلة المحلية داخل الحاوية
Watch: How to Get started with Docker | Usage of Ultralytics Python Package inside Docker live demo 🎉
المتطلبات الأساسية#
- تأكّد من تثبيت Docker على نظامك. وإذا لم يكن مثبتًا، يمكنك تنزيله وتثبيته من موقع Docker.
- لتسريع GPU، تأكّد من احتواء نظامك على GPU من NVIDIA وتثبيت برامج تشغيل NVIDIA. لا تتطلب صور CPU عتاد NVIDIA.
- إذا كنت تستخدم أجهزة NVIDIA Jetson، فتأكّد من تثبيت إصدار JetPack المناسب. راجع دليل NVIDIA Jetson لمزيد من التفاصيل.
إعداد Docker مع دعم NVIDIA (اختياري)#
أولًا، تحقّق من تثبيت برامج تشغيل NVIDIA بصورة صحيحة عبر تشغيل:
nvidia-smiتثبيت NVIDIA Container Toolkit#
لنثبّت الآن NVIDIA Container Toolkit لتمكين دعم GPU في حاويات Docker:
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
&& curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
| sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
| sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.listحدّث قوائم الحزم وثبّت NVIDIA Container Toolkit:
sudo apt-get updatesudo apt-get install -y nvidia-container-toolkitالتحقّق من أجهزة CDI باستخدام Docker#
شغّل nvidia-ctk cdi list للتأكّد من توفّر أجهزة GPU من نوع CDI (تُنشئ خدمة nvidia-cdi-refresh الخاصة بمجموعة الأدوات المواصفة وتحافظ عليها تلقائيًا في toolkit >= 1.18):
nvidia-ctk cdi listيُفترض أن ترى إدخالات مثل nvidia.com/gpu=0 وnvidia.com/gpu=all. وتظهر أجهزة CDI المكتشفة أيضًا في docker info.
تثبيت صور Docker الخاصة بـ Ultralytics#
تنشر Ultralytics الصور التالية على Docker Hub. تُبنى كل صورة من Dockerfile المرتبط بها بواسطة سير عمل نشر Docker.
| الوسم | المنصة والغرض | المصدر |
|---|---|---|
latest | Linux AMD64 مع CUDA لتدريب GPU والاستدلال | Dockerfile |
latest-export | Linux AMD64 مع CUDA وتبعيات التصدير للتحويل وقياس الأداء | Dockerfile-export |
latest-python | صورة Python خفيفة الوزن لنظام Linux AMD64 للاستدلال باستخدام CPU | Dockerfile-python |
latest-python-export | صورة CPU لنظام Linux AMD64 مع تبعيات التصدير | Dockerfile-python-export |
latest-cpu | صورة CPU لنظام Linux AMD64 مع Bash بوصفه الأمر الافتراضي | Dockerfile-cpu |
latest-jupyter | صورة CPU لنظام Linux AMD64 مع JupyterLab ودفاتر دروس Ultralytics التعليمية | Dockerfile-jupyter |
latest-arm64 | صورة CPU لنظام Linux ARM64 لشرائح Apple silicon وRaspberry Pi وأنظمة ARM64 الأخرى | Dockerfile-arm64 |
latest-nvidia-arm64 | نظام Linux ARM64 لنظام DGX Spark (DGX OS) وPyTorch على Thor (JetPack 7.1)؛ TensorRT المرفق لا يدعم JetPack | Dockerfile-nvidia-arm64 |
latest-jetson-jetpack6 | Linux ARM64 لأجهزة NVIDIA Jetson التي تشغّل JetPack 6 | Dockerfile-jetson-jetpack6 |
latest-jetson-jetpack5 | Linux ARM64 لأجهزة NVIDIA Jetson التي تشغّل JetPack 5 | Dockerfile-jetson-jetpack5 |
latest-jetson-jetpack4 | Linux ARM64 لأجهزة NVIDIA Jetson التي تشغّل JetPack 4 | Dockerfile-jetson-jetpack4 |
latest-runner | صورة Linux AMD64 مع CUDA لعامل GPU مستضاف ذاتيًا لإجراءات GitHub Actions | Dockerfile-runner |
latest-runner-cpu | صورة Linux AMD64 لعامل CPU مستضاف ذاتيًا لإجراءات GitHub Actions | Dockerfile-runner-cpu |
تستخدم صور وحدة معالجة الرسومات AMD64 (latest وlatest-export وlatest-runner) مكتبة PyTorch 2.14 وCUDA 13.2. تحقق من دعم CUDA لبرنامج تشغيل المضيف باستخدام nvidia-smi قبل تشغيل صور وحدة معالجة الرسومات AMD64؛ تثبيت حاوية أحدث لا يترقى برنامج تشغيل المضيف. تزيل CUDA 13 الدعم لوحدات معالجة الرسومات Maxwell وPascal وVolta، بما في ذلك Tesla P100 وV100. راجع ملاحظات إصدار CUDA من NVIDIA ومتطلبات توافق برامج التشغيل.
تستخدم صورة NVIDIA ARM64 إصدار NVIDIA PyTorch 26.08 مع CUDA 13.4 وTensorRT 11.2. دعم PyTorch لنظام Thor لا يمتد ليشمل TensorRT: لا تدعم NVIDIA إصدار TensorRT 11.2 على JetPack. لعمليات تصدير Jetson TensorRT، استخدم وقت تشغيل TensorRT 10.x المدعوم لإصدار JetPack الخاص بك. اتبع متطلبات المنصة في دليل Jetson أو دليل DGX Spark. تحتفظ صور JetPack 4 و5 و6 بمجموعات الأجهزة الخاصة بها المنفصلة.
ملف Dockerfile الخاص بـ Conda متاح للإنشاءات المحلية؛ النشر التلقائي لـ latest-conda معطل، لذا فإن علامة السجل تلك لا تحتوي على هذه التحديثات.
استخدم latest-python-export لتصدير LiteRT. تحتفظ صورة وحدة معالجة الرسومات latest-export بـ PyTorch 2.14 وتتخلى عن LiteRT لأن تبعيته الحالية تتطلب PyTorch أقل من 2.14.
تتتبّع الوسوم التي تبدأ بـ latest أحدث إصدار منشور من بناء الفرع الرئيسي. تستبدل الوسوم ذات الإصدار السابقة latest بإصدار من إصدارات Ultralytics، مثل VERSION أو VERSION-cpu أو VERSION-jetson-jetpack6. استخدم وسمًا ذا إصدار للحصول على بيئة قابلة لإعادة الإنتاج.
لسحب أحدث صورة:
# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latestلبناء صورة بنفسك بدلًا من ذلك، استنسخ المستودع ومرّر Dockerfile المطابق من الجدول أعلاه، مع استخدام جذر المستودع كسياق للبناء:
# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .تشغيل Ultralytics في حاوية Docker#
إليك كيفية تنفيذ حاوية Docker الخاصة بـ Ultralytics:
استخدام CPU فقط#
# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpuاستخدام وحدات GPU#
# Run with all GPUs
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest
# Run specifying which GPUs to use
sudo docker run -it --ipc=host --device nvidia.com/gpu=2 --device nvidia.com/gpu=3 ultralytics/ultralytics:latestيعيّن الخيار -it طرفية زائفة ويحافظ على إبقاء stdin مفتوحًا، ما يتيح لك التفاعل مع الحاوية. ويمكّن الخيار --ipc=host من مشاركة مساحة أسماء IPC الخاصة بالمضيف، وهو أمر ضروري لمشاركة الذاكرة بين العمليات. ويمنح الخيار --device nvidia.com/gpu=... الحاوية إمكانية الوصول إلى وحدات GPU الخاصة بالمضيف عبر CDI.
في Linux، تتطلب طلبات أجهزة CDI إصدار Docker >= 28.2.0 (يكون CDI مفعّلًا افتراضيًا) وإصدار nvidia-container-toolkit >= 1.18 (إنشاء مواصفة CDI تلقائيًا). حدّث مضيفي Linux الأقدم قبل تشغيل حاويات GPU. يمكن أن يفقد الخيار القديم --gpus all إمكانية الوصول إلى GPU (Failed to initialize NVML: Unknown Error) عند إعادة تحميل المضيف لـ systemd أثناء تحديثات الحزم الروتينية (nvidia-container-toolkit#48). تتضمن طلبات CDI --device عقد الأجهزة في تكوين الحاوية، ولذلك تحافظ الحاويات طويلة التشغيل، مثل عمال التدريب أو عوامل CI، على إمكانية الوصول إلى GPU بعد عمليات إعادة التحميل.
يستخدم دعم GPU في Docker Desktop على Windows حاليًا --gpus all مع الواجهة الخلفية WSL 2، لأن أجهزة NVIDIA CDI غير متاحة هناك. لا يستخدم Windows نظام Linux systemd، ولذلك لا ينطبق عليه فشل daemon-reload المذكور أعلاه.
ملاحظة حول إمكانية الوصول إلى الملفات#
للعمل مع الملفات الموجودة على جهازك المحلي داخل الحاوية، يمكنك استخدام وحدات تخزين Docker:
# Mount a local directory into the container
sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latestاستبدل /path/on/host بمسار الدليل على جهازك المحلي، واستبدل /path/in/container بالمسار المطلوب داخل حاوية Docker.
الاحتفاظ بمخرجات التدريب#
تُحفظ مخرجات التدريب في /ultralytics/runs/<task>/<name>/ داخل الحاوية افتراضيًا. ومن دون تحميل دليل من المضيف، تُفقد المخرجات عند إزالة الحاوية.
للاحتفاظ بمخرجات التدريب:
# Recommended: mount workspace and specify project path
sudo docker run --rm -it -v "$(pwd)":/w -w /w ultralytics/ultralytics:latest \
yolo train model=yolo26n.pt data=coco8.yaml project=/w/runsيحفظ هذا جميع مخرجات التدريب في ./runs على جهازك المضيف.
تشغيل تطبيقات واجهة المستخدم الرسومية (GUI) في حاوية Docker#
يُستخدم Docker أساسًا لوضع التطبيقات التي تعمل في الخلفية وبرامج CLI داخل حاويات، لكنه يستطيع أيضًا تشغيل البرامج الرسومية. وفي عالم Linux، يتولى خادمان رسوميّان رئيسيان عرض الرسومات: X11 (المعروف أيضًا باسم نظام النوافذ X) وWayland. قبل البدء، من الضروري تحديد خادم الرسومات الذي تستخدمه حاليًا. شغّل هذا الأمر لمعرفة ذلك:
env | grep -E -i 'x11|xorg|wayland'يخرج إعداد خادم عرض X11 أو Wayland وتكوينه عن نطاق هذا الدليل. إذا لم يُرجع الأمر أعلاه أي نتيجة، فستحتاج أولًا إلى تشغيل أحدهما على نظامك قبل المتابعة.
تشغيل حاوية Docker بواجهة مستخدم رسومية#
استخدام وحدات GPU
إذا كنت تستخدم وحدات GPU، فيمكنك إضافة الخيار --device nvidia.com/gpu=all إلى الأمر.
إذا كنت تستخدم X11، فيمكنك تشغيل الأمر التالي للسماح لحاوية Docker بالوصول إلى مقبس X11:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v ~/.Xauthority:/root/.Xauthority \
-it --ipc=host ultralytics/ultralytics:latestيعيّن هذا الأمر متغير البيئة DISPLAY على شاشة المضيف، ويحمّل مقبس X11، ويربط ملف .Xauthority بالحاوية. ويتيح الأمر xhost +local:docker لحاوية Docker الوصول إلى خادم X11.
استخدام Docker مع واجهة مستخدم رسومية#
يمكنك الآن عرض التطبيقات الرسومية داخل حاوية Docker. على سبيل المثال، يمكنك تشغيل أمر CLI التالي لتصوير التنبؤات من نموذج YOLO26:
yolo predict model=yolo26n.pt show=Trueالاختبار
تتمثل إحدى الطرق البسيطة للتحقّق من أن مجموعة Docker تتمتع بإمكانية الوصول إلى خادم X11 في تشغيل حاوية ببرنامج ذي واجهة رسومية مثل xclock أو xeyes. وبدلًا من ذلك، يمكنك أيضًا تثبيت هذه البرامج في حاوية Docker الخاصة بـ Ultralytics لاختبار الوصول إلى خادم X11 في خادم العرض GNU-Linux لديك. وإذا واجهت أي مشكلات، ففكّر في تعيين متغير البيئة -e QT_DEBUG_PLUGINS=1. يؤدي تعيين متغير البيئة هذا إلى تفعيل إخراج معلومات تصحيح الأخطاء، ما يساعد في استكشاف المشكلات وإصلاحها.
عند الانتهاء من استخدام واجهة Docker الرسومية#
في كلتا الحالتين، لا تنسَ إلغاء الوصول من مجموعة Docker عند الانتهاء.
xhost -local:dockerهل تريد عرض نتائج الصور مباشرةً في الطرفية؟
راجع الدليل التالي حول عرض نتائج الصور باستخدام الطرفية
أصبحت الآن مستعدًا لاستخدام Ultralytics مع Docker والاستفادة من إمكاناته. لاستضافة تطبيق الويب الخاص بـ Ultralytics ذاتيًا، راجع دليل منصة التشغيل المحلي. وللاطلاع على طرق بديلة لتثبيت حزمة Python، راجع وثائق البدء السريع لـ Ultralytics.
الأسئلة الشائعة#
لإعداد Ultralytics باستخدام Docker، تأكّد أولًا من تثبيت Docker على نظامك. وإذا كان لديك GPU من NVIDIA، فثبّت NVIDIA Container Toolkit لتمكين دعم GPU. ثم اسحب أحدث صورة Docker من Ultralytics من Docker Hub باستخدام الأمر التالي:
sudo docker pull ultralytics/ultralytics:latestللاطلاع على الخطوات التفصيلية، راجع دليل البدء السريع باستخدام Docker.
يضمن استخدام صور Docker من Ultralytics بيئة متسقة عبر الأجهزة المختلفة، مع تكرار البرامج والتبعيات نفسها. وهذا مفيد بشكل خاص للتعاون بين الفرق، وتشغيل النماذج على عتاد متنوع، والحفاظ على قابلية إعادة الإنتاج. استخدم
latestلتدريب GPU العام باستخدام NVIDIA، أو اختر الصورة المطابقة لإصدار JetPack الخاص بجهاز NVIDIA Jetson. راجع جدول الصور الكامل أو استكشف Ultralytics Docker Hub.أولًا، تأكّد من تثبيت NVIDIA Container Toolkit وتكوينه. ثم استخدم الأمر التالي لتشغيل Ultralytics YOLO مع دعم GPU:
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUsيُعدّ هذا الأمر حاوية Docker مع إمكانية الوصول إلى GPU. لمزيد من التفاصيل، راجع دليل البدء السريع باستخدام Docker.
لتصوير نتائج تنبؤات YOLO باستخدام واجهة رسومية في حاوية Docker، تحتاج إلى السماح لـ Docker بالوصول إلى خادم العرض لديك. بالنسبة إلى الأنظمة التي تشغّل X11، يكون الأمر:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v ~/.Xauthority:/root/.Xauthority \ -it --ipc=host ultralytics/ultralytics:latestبالنسبة إلى الأنظمة التي تشغّل Wayland، استخدم:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \ --net=host -it --ipc=host ultralytics/ultralytics:latestيمكن العثور على مزيد من المعلومات في قسم تشغيل تطبيقات واجهة المستخدم الرسومية (GUI) في حاوية Docker.
نعم، يمكنك تحميل أدلة محلية داخل حاوية Docker الخاصة بـ Ultralytics باستخدام الخيار
-v:sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latestاستبدل
/path/on/hostبالدليل الموجود على جهازك المحلي، واستبدل/path/in/containerبالمسار المطلوب داخل الحاوية. يتيح لك هذا الإعداد العمل مع ملفاتك المحلية داخل الحاوية. لمزيد من المعلومات، راجع قسم ملاحظة حول إمكانية الوصول إلى الملفات.