درّب أول نموذج YOLO لديك·الإعداد·الدرس 1/10

الدرسمبتدئ

تثبيت Ultralytics

ثبّت Ultralytics في بيئة نظيفة، واقرأ تقرير فحوصات yolo للتأكد من جهازك، وأثبت سلامة الإعداد بتنفيذ تنبؤ واحد.

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

تجنّب هذه المشكلات كلتيهما بعشر دقائق من الإعداد. ستثبّت حزمة ultralytics في بيئة جديدة، وتقرأ تقرير yolo checks سطرًا سطرًا، وتشغّل أول تنبؤ باستخدام YOLO26 لإثبات أن كل شيء متصل.

النتيجة

يمكنك تثبيت Ultralytics في بيئة نظيفة ومعرفة ما إذا كان سيعمل على CUDA أو MPS أو CPU من سطر واحد في yolo checks.

المسار السريع

إذا كنت تعرف الأساسيات بالفعل، فإليك النسخة المختصرة.

أنشئ بيئة افتراضية جديدة وفعّلها باستخدام Python 3.10 أو أحدث.
على جهاز NVIDIA، ثبّت PyTorch مع CUDA أولًا؛ ثم pip install ultralytics.
شغّل yolo checks واقرأ اسم الجهاز في نهاية السطر الأول.
شغّل yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg وافتح الصورة المحفوظة.

عملي

إنشاء بيئة نظيفة#

تُثبَّت حزمة ultralytics على Python 3.8 والإصدارات الأحدث، لكن إصدارات PyTorch الحالية تتطلب Python 3.10 أو أحدث، لذا ابدأ المشاريع الجديدة بإصدار حديث مثل 3.12. تحافظ البيئة الافتراضية الجديدة على الحزمة وتبعياتها بمعزل عن مشاريعك الأخرى:

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python --version                 # 3.10 or newer

يتناول دليل البدء السريع من Ultralytics الإعداد نفسه باستخدام Conda أو Docker إن كنت تفضّل أحدهما.

ثبّت PyTorch المناسب، ثم Ultralytics#

أداة «البدء محليًا» من PyTorch، لاختيار نظام التشغيل ومدير الحزم واللغة ومنصة الحوسبة، وإنشاء أمر تثبيت pip المطابق

يعمل Ultralytics على PyTorch، ويثبّت pip إصدار PyTorch افتراضيًا إذا لم يكن موجودًا. ويُعد هذا الإصدار الافتراضي السبب الرئيسي لمشكلات «لماذا يستخدم CPU؟»، لذا اختر الإصدار أولًا:

جهازك	ابدأ بهذا	ثم
GPU من NVIDIA	ثبّت إصدار CUDA من أداة اختيار PyTorch المطابق لبرنامج التشغيل لديك	تتولى `pip install ultralytics` الأمر
جهاز Mac بمعالج Apple Silicon	لا شيء: يتضمن الإصدار الافتراضي MPS	`pip install ultralytics`
CPU فقط	لا شيء	`pip install ultralytics`

pip install ultralytics

يثبّت هذا الأمر الواحد حزمة Python المسماة ultralytics، وأداة سطر الأوامر المسماة yolo، وتبعيات مثل OpenCV وNumPy.

اقرأ تقرير `yolo checks`#

يطبع yolo checks الإصدارات والأجهزة التي سيستخدمها Ultralytics. فيما يلي مخرجات فعلية من جهاز MacBook، بعد اختصارها:

Ultralytics 8.4.175 🚀 Python-3.12.12 torch-2.14.1 CPU (Apple M5 Pro)
Setup complete ✅ (18 CPUs, 48.0 GB RAM, 594.4/926.3 GB disk)

OS                     macOS-27.0.1-arm64-arm-64bit
Python                 3.12.12
Install                pip
GPU                    None

شرح الأسطر واحدًا تلو الآخر:

Ultralytics 8.4.175 ... torch-2.14.1: إصدارات الحزمة وPyTorch. أدرجها في أي تقرير عن خطأ.
CPU (Apple M5 Pro): الجهاز المستخدم عند عدم تمرير device. هذا هو السطر الأهم.
Setup complete ✅: التثبيت نفسه سليم.
GPU None: لا يرى PyTorch أي GPU من CUDA. وهذا متوقع على جهاز Mac، لكنه مشكلة على جهاز NVIDIA.

اتخذ إجراءً بناءً على الجهاز المذكور في السطر الأول:

لا تحتاج إلى GPU لهذه الدورة: صُمّم كل مثال لينتهي في غضون دقائق على CPU محمول. وتبرز أهمية GPU عند التدريب بالحجم الكامل، إذ يكون أسرع غالبًا بعشرة أضعاف أو أكثر.

أثبت ذلك بتنفيذ تنبؤ واحد#

يختبر التنبؤ المكدس البرمجي بأكمله: ينزّل أوزان YOLO26 nano، ويجلب صورة، ويشغّل النموذج، ويحفظ نسخةً مشروحة.

yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg

image 1/1 bus.jpg: 640x480 4 persons, 1 bus, 20.1ms
Speed: 0.7ms preprocess, 20.1ms inference, 0.5ms postprocess per image at shape (1, 3, 640, 480)
Results saved to runs/detect/predict

640x480 4 persons, 1 bus: جرى تغيير حجم الصورة إلى 640×480 ليتعامل معها النموذج، الذي عثر على خمسة عناصر.
20.1ms: زمن الاستدلال على CPU هذا. سجّل زمنك؛ فهو أول خط أساس للسرعة لديك.
runs/detect/predict: موقع حفظ bus.jpg المشروحة. أعد تشغيل الأمر لتحصل على predict-2؛ إذ لا يستبدل Ultralytics أي تشغيل سابق.

ترد جميع الإعدادات الافتراضية في هذا الأمر — مستوى الثقة وحجم الصورة وموقع الحفظ — في مرجع الإعدادات.

حل المشكلات الشائعة#

التدريب بصمت على CPU

العَرَض: تعرض yolo checks القيمتين CPU وGPU None على جهاز مزود بوحدة NVIDIA GPU، ويكون التدريب بطيئًا للغاية. السبب: ثبّت pip إصدار PyTorch يعمل على CPU فقط. الحل: أزل torch وtorchvision، وثبّت إصدار CUDA من محدد PyTorch، ثم أعد تشغيل yolo checks حتى يعرض السطر الأول CUDA:0.

yolo: command not found

السبب: البيئة الافتراضية غير مفعّلة في هذه الوحدة الطرفية، لذا لا يظهر البرنامج النصي yolo ضمن PATH. الحل: شغّل source .venv/bin/activate (أو ما يعادله في Windows) في كل وحدة طرفية جديدة قبل استخدام yolo.

العَرَض	السبب	الحل
`requirements: ... not found, attempting AutoUpdate` ثم `No module named pip`	أُنشئت البيئة من دون pip، لذا لا يستطيع Ultralytics تثبيت حزمة إضافية تلقائيًا	ثبّت الحزمة المذكورة باستخدام أداة بيئتك، مثل `uv pip install lap`
انتهاء مهلة تنزيل الأوزان أو مجموعة البيانات	تحظر الشبكة ملفات إصدارات GitHub	نزّل `yolo26n.pt` مرة واحدة من موقع آخر، ومرّر مساره المحلي
`PermissionError` يكتب `runs/`	مجلد العمل للقراءة فقط	إلى مجلد مشروع قابل للكتابة: `cd`

تجمع دليل المشكلات الشائعة الحلول المعروفة لأي مشكلة أخرى، وغالبًا ما تجد الإجابة في المشكلات المغلقة ضمن مستودع Ultralytics — ابحث فيها قبل فتح مشكلة جديدة.

جرّبه

في بيئة جديدة، ثبّت Ultralytics وشغّل yolo checks ثم نفّذ تنبؤ الحافلة. قدّم سجل إعداد من ثلاثة أسطر: إصداري Ultralytics وPyTorch لديك، واسم الجهاز الوارد في السطر الأول من yolo checks (وعلى جهاز NVIDIA، ما يثبت أنه يعرض CUDA:0)، وزمن الاستدلال الوارد لـ bus.jpg.

متى يُعدّ مكتملًا

تكون قد أتممت الدرس عند تحقق جميع الشروط التالية.

ينتهي yolo checks بـ Setup complete ✅، ويذكر الجهاز المتوقع.
توجد runs/detect/predict/bus.jpg، وفيها أربعة أشخاص وحافلة واحدة محددة بمربعات.
دوّنت إصداراتك وجهازك وزمن استدلال bus.jpg.

عرض الحل

python -m venv .venv
source .venv/bin/activate
# NVIDIA only: install the CUDA PyTorch build from pytorch.org first
pip install ultralytics
yolo checks
yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg

Versions: Ultralytics 8.4.175, torch 2.14.1
Device:   CPU (Apple M5 Pro); use device=mps for the Apple GPU
bus.jpg:  20.1 ms inference at 640x480

على CPU محمول، توقّع زمنًا يقارب 10–60 ms لـ bus.jpg؛ وعلى GPU حديث من NVIDIA، بضعة ميلي ثوانٍ. إذا ذكر yolo checks جهازًا غير صحيح، فأصلح PyTorch قبل المتابعة.

ما الخطوة التالية

تعمل البيئة. بعد ذلك، نفّذ التنبؤ نفسه من Python وتعلّم قراءة كل حقل يعيده النموذج.

سجّل الدخول لحفظ التقدم

Get Started