ابدأ

التنبؤ باستخدام النماذج مع Ultralytics YOLO

Ultralytics YOLO ecosystem and integrations

مقدمة#

في التعلّم الآلي والرؤية الحاسوبية، يُسمّى فهم البيانات المرئية باستخدام نموذج مدرّب الاستدلال أو التنبؤ. ينفّذ وضع التنبؤ في Ultralytics YOLO26 استدلالًا آنيًا سريعًا على مجموعة واسعة من مصادر البيانات.

اطّلع على معاينة YOLO27 غير المُصدرة للتعرّف على أمثلة الاستدلال المخطط لها.



شاهد: استخراج مربعات الإحاطة والأقنعة والنقاط المفتاحية وOBB والعمق والمزيد باستخدام Ultralytics YOLO26 في Python 🚀

تطبيقات واقعية#

التصنيعالرياضةالسلامة
الكشف عن قطع غيار المركباتالكشف عن لاعبي كرة القدمالكشف عن سقوط الأشخاص

لماذا تستخدم Ultralytics YOLO للاستدلال؟#

أهم أسباب استخدام وضع التنبؤ في YOLO26:

  • تعدد الاستخدامات: أجرِ الاستدلال على الصور ومقاطع الفيديو والتدفقات المباشرة.
  • الأداء: صُمم لمعالجة البيانات بسرعة عالية وفي الوقت الفعلي دون التضحية بـ الدقة.
  • سهولة الاستخدام: واجهتا Python وCLI بديهيتان للتطوير والاختبار بسرعة.
  • قابلية عالية للتخصيص: تتوفر إعدادات ومعلمات متنوعة لضبط سلوك استدلال النموذج وفقًا لمتطلباتك المحددة.
  • جاهز للإنتاج: انشر النماذج على هيئة نقاط نهاية للاستدلال في منصة Ultralytics مع التوسع التلقائي والمراقبة، أو أجرِ الاستدلال محليًا.

الميزات الرئيسية لوضع التنبؤ#

يتضمن وضع التنبؤ في YOLO26 ما يلي:

  • التوافق مع مصادر بيانات متعددة: يقبل وضع التنبؤ الصور الفردية ومجموعات الصور وملفات الفيديو وتدفقات الفيديو الآنية.
  • وضع البث: استخدم ميزة البث لإنشاء مولّد موفّر للذاكرة لكائنات Results. فعّل هذه الميزة بتعيين stream=True في طريقة الاستدعاء الخاصة بالمُتنبئ. وعلى عكس السلوك الافتراضي (stream=False)، الذي يعيد قائمة تضم جميع النتائج، فإن stream=True يُصدر النتائج واحدة تلو الأخرى، ما يجعله مفيدًا على نحو خاص لمقاطع الفيديو الطويلة والبث المباشر.
  • معالجة الدُفعات: عالج عدة صور أو إطارات فيديو في دفعة واحدة، مما يقلل إجمالي زمن الاستدلال بدرجة أكبر.
  • سهولة التكامل: التكامل مع مسارات البيانات الحالية ومكونات البرامج الأخرى عبر API مرنة.

تعيد نماذج Ultralytics YOLO إما قائمة Python من كائنات Results أو مولّدًا موفّرًا للذاكرة من كائنات Results عند تمرير stream=True إلى النموذج أثناء الاستدلال:

التنبؤ
from ultralytics import YOLO

# ⁨تحميل نموذج⁩
model = YOLO("yolo26n.pt")  # ⁨نموذج YOLO26n مُدرّب مسبقًا⁩

# ⁨إجراء استدلال دفعِي على قائمة من الصور⁩
results = model(["image1.jpg", "image2.jpg"])  # ⁨إرجاع قائمة من كائنات Results⁩

# ⁨معالجة قائمة النتائج⁩
for result in results:
    boxes = result.boxes  # ⁨كائن Boxes لمخرجات مربعات الإحاطة⁩
    masks = result.masks  # ⁨كائن Masks لمخرجات أقنعة التجزئة⁩
    keypoints = result.keypoints  # ⁨كائن Keypoints لمخرجات تقدير الوضعية⁩
    probs = result.probs  # ⁨كائن Probs لمخرجات التصنيف⁩
    obb = result.obb  # ⁨كائن الصناديق الموجّهة لمخرجات OBB⁩
    result.show()  # ⁨العرض على الشاشة⁩
    result.save(filename="result.jpg")  # ⁨الحفظ على القرص⁩

مصادر الاستدلال#

يمكن لـ YOLO26 معالجة أنواع مختلفة من مصادر الإدخال للاستدلال، كما هو موضح في الجدول أدناه. وتشمل المصادر الصور الثابتة وتدفقات الفيديو وتنسيقات بيانات متنوعة. ويوضح الجدول أيضًا إمكانية استخدام كل مصدر في وضع البث مع الوسيط stream=True ✅. يفيد وضع البث في معالجة مقاطع الفيديو أو البث المباشر، إذ ينشئ مولّدًا للنتائج بدلًا من تحميل جميع الإطارات إلى الذاكرة.

نصيحة

استخدم stream=True لمعالجة مقاطع الفيديو الطويلة أو مجموعات البيانات الكبيرة وإدارة الذاكرة بكفاءة. عند استخدام stream=False، تُخزّن نتائج جميع الإطارات أو نقاط البيانات في الذاكرة، وقد يتراكم حجمها سريعًا ويتسبب في أخطاء نفاد الذاكرة عند التعامل مع مدخلات كبيرة. في المقابل، يستخدم stream=True مولّدًا لا يحتفظ في الذاكرة إلا بنتائج الإطار أو نقطة البيانات الحالية، مما يقلل استهلاك الذاكرة بدرجة كبيرة ويمنع مشكلات نفادها.

المصدرمثالالنوعملاحظات
صورة'image.jpg'str أو Pathملف صورة واحد.
عنوان URL'https://ultralytics.com/images/bus.jpg'strعنوان URL لصورة.
لقطة شاشة ✅'screen'strالتقط الشاشة باستمرار حتى إيقاف العملية.
PILImage.open('image.jpg')PIL.Imageتنسيق HWC بقنوات RGB.
OpenCVcv2.imread('image.jpg')np.ndarrayتنسيق HWC بقنوات BGR uint8 (0-255).
NumPynp.zeros((640,1280,3))np.ndarrayتنسيق HWC بقنوات BGR uint8 (0-255).
torchtorch.zeros(16,3,320,640)torch.Tensorتنسيق BCHW بقنوات RGB float32 (0.0-1.0).
CSV'sources.csv'str أو Pathملف CSV يتضمن مسارات الصور أو مقاطع الفيديو أو المجلدات.
فيديو ✅'video.mp4'str أو Pathملف فيديو بتنسيقات مثل MP4 وAVI وغيرها.
دليل ✅'path/'str أو Pathمسار إلى دليل يحتوي على صور أو مقاطع فيديو.
نمط glob ✅'path/*.jpg'strنمط Glob لمطابقة عدة ملفات. استخدم الحرف * كحرف بدل.
YouTube ✅'https://youtu.be/LNwODJXcvt4'strعنوان URL لفيديو على YouTube.
بث ✅'rtsp://example.com/media.mp4'strعنوان URL لبروتوكولات البث مثل RTSP أو RTMP أو TCP، أو عنوان IP.
بث متعدد ✅'list.streams'str أو Pathملف نصي *.streams يحتوي على عنوان URL واحد للبث في كل صف؛ أي إن 8 تدفقات ستعمل بحجم دفعة 8.
كاميرا ويب ✅0intفهرس جهاز الكاميرا المتصل المراد إجراء الاستدلال عليه.

فيما يلي أمثلة برمجية لاستخدام كل نوع من المصادر:

مصادر التنبؤ

أجرِ الاستدلال على ملف صورة.

from ultralytics import YOLO

# ⁨تحميل نموذج YOLO26n مُدرّب مسبقًا⁩
model = YOLO("yolo26n.pt")

# ⁨تحديد مسار ملف الصورة⁩
source = "path/to/image.jpg"

# ⁨إجراء الاستدلال على المصدر⁩
results = model(source)  # ⁨قائمة من كائنات Results⁩

وسيطات الاستدلال#

يقبل model.predict() عدة وسيطات يمكن تمريرها وقت الاستدلال لتجاوز القيم الافتراضية:

الحجم الثابت مقابل المستطيل الأدنى (rect)#

افتراضيًا، يستخدم predict rect=True، ما يتيح الحشو بالمستطيل الأدنى متى أمكن. تُقاس الصورة لتلائم imgsz، ثم تُحشى إلى أقرب مضاعف للخطوة فقط، لذا قد يكون الموتر النهائي أصغر من imgsz. لا يُستخدم الحشو بالمستطيل الأدنى إلا عندما تكون جميع الصور في الدفعة بالشكل نفسه وتدعمه الواجهة الخلفية (PyTorch .pt، أو تصدير بأشكال ديناميكية مثل ONNX ديناميكي). وإلا، تُحشى الصور إلى الهدف الكامل imgsz. تتجاهل نماذج العمق وRT-DETR rect، وتُمدد كل صورة إلى imgsz كاملًا دون حشو.

استخدم rect=False لاستخدام الهدف الكامل imgsz دائمًا. يُوصى بذلك عندما تحتاج إلى حجم إدخال ثابت لمطابقة النماذج المُصدَّرة (ONNX وTensorRT وغيرهما).

عدد صحيح مقابل صف imgsz

  • تُحوّل قيمة imgsz=640 الصحيحة إلى هدف مربع (640, 640) بعد تقريبها إلى مضاعف خطوة النموذج.
  • تحدد قيمة imgsz=(384, 672) الصفّية هدفًا مستطيلًا. مع rect=True، قد يكون الموتر الفعلي أصغر من هذا الهدف.

التدريب مقابل predict/export

لا يقبل التدريب سوى قيمة imgsz صحيحة واحدة (وتُحوّل قائمة [h, w] إلى أكبر قيمة فيها). أما predict وexport فيقبلان عددًا صحيحًا أو صفًا (height, width).

مثال
from ultralytics import YOLO

# ⁨تحميل نموذج YOLO26n مُدرّب مسبقًا⁩
model = YOLO("yolo26n.pt")

# ⁨تشغيل الاستدلال على 'bus.jpg' باستخدام الوسيطات⁩
model.predict("https://ultralytics.com/images/bus.jpg", save=True, imgsz=320, conf=0.25)

وسائط الاستدلال:

المعاملالنوعالافتراضيالوصف
sourcestr أو int أو NoneNoneيحدّد مصدر البيانات للاستدلال. يمكن أن يكون مسار صورة أو ملف فيديو أو دليلًا أو عنوان URL أو معرّف جهاز للتدفقات المباشرة. إذا لم يُحدّد، يُسجّل تحذير ويعود النموذج إلى الأصول التجريبية المضمّنة (ultralytics/assets، أو عنوان URL تجريبي لـ OBB). ويدعم نطاقًا واسعًا من التنسيقات والمصادر، ما يتيح تطبيقًا مرنًا على أنواع مختلفة من المدخلات.
conffloat0.25يعيّن الحد الأدنى لعتبة الثقة لعمليات الكشف. تُهمَل الأجسام المكتشفة التي تقل ثقتها عن هذا الحد. ويمكن أن يساعد تعديل هذه القيمة على تقليل الإيجابيات الكاذبة.
ioufloat0.5عتبة التقاطع على الاتحاد (IoU) لقمع غير الأعظميات (NMS). تؤدي القيم الأقل إلى عدد أقل من عمليات الكشف عبر إزالة الصناديق المتداخلة، ما يفيد في تقليل التكرارات.
imgszint أو tuple640هدف letterbox. يحدد العدد الصحيح N×N مربعًا؛ بينما يحدد الصف (height, width). مع rect=True، قد يكون موتر الإدخال الفعلي أصغر من هذا الهدف بسبب الحشو بالحد الأدنى للمستطيل. استخدم rect=False لتحديد حجم ثابت. راجع الشكل الثابت مقابل الحد الأدنى للمستطيل.
rectboolTrueإذا كان True، فاستخدم الحشو بالمستطيل الأدنى متى أمكن (دفعة ذات أشكال متطابقة وواجهة خلفية مدعومة). وإذا كان False، فاستخدم دائمًا imgsz كاملًا. راجع الشكل الثابت مقارنةً بالمستطيل الأدنى. يُتجاهل ذلك في نماذج depth وRT-DETR، التي تمدد الصور إلى imgsz كاملًا دون حشو.
quantizeint أو strNoneدقة الاستدلال: تحدد 16/"fp16" و32/"fp32"/unset استخدام حساب FP16 أو FP32 لنماذج PyTorch وTorchScript (FP32 على CPU)؛ أما التنسيقات الأخرى فتستخدم الدقة التي يحددها الملف الاصطناعي وبيئة التشغيل. عند 16، يظل OpenVINO يقرّب الإدخال إلى FP16 على العميل ثم يوسّعه مجددًا إلى FP32، من دون تغيير دقة بيئة التشغيل. تُضبط عملية التكميم INT8/PTQ أثناء التصدير، ثم تُستخدم بتحميل النموذج المُصدَّر. يحل هذا الخيار محل العلامة half المهملة.
devicestrNoneيحدّد جهاز الاستدلال (مثل cpu أو cuda:0 أو 0 أو npu أو npu:0). يتيح للمستخدمين الاختيار بين CPU أو وحدة GPU محددة أو Huawei Ascend NPU أو أجهزة حوسبة أخرى لتنفيذ النموذج. تعمل نماذج OpenVINO وLiteRT باستخدام xpu وnpu على وحدة GPU وNPU من Intel؛ راجع أجهزة الاستدلال للاطلاع على كل تنسيق.
dnnboolFalseإذا كان True، فسيستخدم وحدة DNN في OpenCV بدلًا من ONNX Runtime لاستدلال نماذج ONNX.
datastrNoneمسار ملف YAML لمجموعة البيانات (مثل coco8.yaml)، يُقرأ منه names فقط، وذلك عندما لا يحتوي النموذج المحمّل على أسماء فئات خاصة به: كأن يكون تصديرًا من جهة خارجية، أو تصديرًا من Ultralytics منفصلًا عن البيانات الوصفية المرفقة به. وفي غير ذلك، يُبلغ النموذج عن class0 وclass1 وما إلى ذلك.
batchint1يحدد حجم الدفعة للاستدلال (ولا يعمل إلا عندما يكون المصدر دليلًا أو ملف فيديو أو ملف .txt). يمكن أن يؤدي حجم الدفعة الأكبر إلى زيادة معدل المعالجة، ما يقلل إجمالي الوقت اللازم للاستدلال.
tilebool أو intFalseينفّذ الاستدلال باستخدام رقع ثابتة، ويُرجع المخرجات بإحداثيات الصورة الأصلية. يستخدم True القيمة imgsz؛ ويحدّد العدد الصحيح الموجب حجم الرقعة. راجع تقسيم الصور عالية الدقة إلى رقع.
max_detint300الحد الأقصى لعدد الاكتشافات المسموح بها لكل صورة. يحد هذا الخيار من العدد الإجمالي للكائنات التي يمكن للنموذج اكتشافها في عملية استدلال واحدة، ويمنع المخرجات المفرطة في المشاهد الكثيفة.
vid_strideint1خطوة الإطارات لمدخلات الفيديو. تتيح تخطي إطارات الفيديو لتسريع المعالجة، على حساب الدقة الزمنية. تعالج القيمة 1 كل إطار، بينما تؤدي القيم الأعلى إلى تخطي الإطارات.
stream_bufferboolFalseيحدد ما إذا كان سيتم وضع الإطارات الواردة في قائمة انتظار لبث الفيديو. إذا كان False، فسيتم إسقاط الإطارات القديمة لإفساح المجال للإطارات الجديدة (وهذا محسّن للتطبيقات الآنية). وإذا كان True، فستُضاف الإطارات الجديدة إلى مخزن مؤقت، ما يضمن عدم تخطي أي إطار، لكنه سيسبب تأخرًا إذا كان معدل الإطارات للاستدلال أقل من معدل إطارات البث.
visualizeboolFalseيحفظ خريطة حرارية لتنشيط الفئات بجوار كل تنبؤ، وتوضح وحدات البكسل التي رفعت درجات الفئة المتنبأ بها. يراعي الخيارين conf وclasses، لذا لا يرسم classes=[0] إلا خريطة تلك الفئة. متاح فقط لنماذج Ultralytics المعتمدة على PyTorch.
augmentboolFalseيفعّل زيادة البيانات وقت الاختبار (TTA) للتنبؤات، ما قد يحسن متانة الاكتشاف على حساب سرعة الاستدلال. متاح فقط لنماذج Ultralytics المعتمدة على PyTorch.
agnostic_nmsboolFalseيفعّل كبت غير الأعظمية (NMS) غير المرتبط بالفئة، فيكبت الصناديق المتداخلة ذات الدرجات الأقل عبر الفئات المختلفة بدلًا من الاقتصار على الفئة نفسها. يفيد ذلك في سيناريوهات الاكتشاف متعددة الفئات التي يشيع فيها تداخل الفئات. في الاستدلال الخالي من NMS (nms=False على YOLO26 أو YOLOv10)، لا يفعل هذا الخيار سوى منع ظهور الاكتشاف نفسه بتسميات فئات متعددة (التكرارات ذات IoU=1.0)، ولا يجري كبتًا قائمًا على عتبة IoU بين الصناديق المختلفة.
classeslist[int]Noneيرشح التنبؤات وفق مجموعة من معرّفات الفئات. لن تُعاد إلا الاكتشافات المنتمية إلى الفئات المحددة. يفيد ذلك في التركيز على الكائنات ذات الصلة ضمن مهام الاكتشاف متعددة الفئات.
retina_masksboolFalseيعيد أقنعة تقسيم عالية الدقة. ستطابق الأقنعة المعادة (masks.data) حجم الصورة الأصلية عند التفعيل. وإذا عُطّل الخيار، فستكون الأقنعة بحجم الصورة المستخدمة أثناء الاستدلال.
embedlist[int]Noneيحدد الطبقات التي تُستخرج منها متجهات السمات أو التضمينات. استخدم model.embed(source) لتضمينات الطبقة قبل الأخيرة، أو model.predict(source, embed=[layer]) لاختيار طبقات محددة. يفيد ذلك في المهام اللاحقة مثل التجميع أو البحث عن التشابه. متاح فقط لنماذج Ultralytics المعتمدة على PyTorch.
projectstrNoneاسم مجلد المشروع الذي تُحفظ فيه مخرجات التنبؤ إذا كان save مفعّلًا. يُوضَع المسار النسبي ضمن runs_dir/<task>، بينما يُستخدم المسار المطلق كما هو.
namestrNoneاسم تشغيل التنبؤ. يُستخدم لإنشاء دليل فرعي ضمن مجلد المشروع، حيث تُخزّن مخرجات التنبؤ عند تفعيل save.
streamboolFalseيتيح معالجة طويلة الفيديوهات أو أعداد كبيرة من الصور بكفاءة في استخدام الذاكرة، وذلك بإرجاع مولّد لكائنات Results بدلًا من تحميل جميع الإطارات إلى الذاكرة دفعة واحدة.
verboseboolTrueيتحكم في عرض سجلات الاستدلال المفصلة في الطرفية، لتوفير ملاحظات آنية عن عملية التنبؤ.
compilebool أو strFalseيتيح تجميع رسوم torch.compile في PyTorch 2.x باستخدام backend='inductor'. يقبل True → "default"، أو False لتعطيله، أو وضعًا نصيًا مثل "default"، "reduce-overhead"، "max-autotune-no-cudagraphs". ويعود إلى التنفيذ الفوري مع تحذير إذا لم يكن مدعومًا.
channels_lastboolNoneيستخدم تنسيق الذاكرة channels_last (NHWC) للاستدلال الأصلي باستخدام PyTorch. يفعّله None تلقائيًا على وحدات CPU بمعمارية x86 في Linux وWindows التي تدعم oneDNN، مع PyTorch 1.13 أو أحدث؛ ويعطّله False، بينما يطلبه True على أجهزة CPU بمعمارية x86 أو أجهزة CUDA المدعومة. لا تتغير الإعدادات على ARM64 وMPS وإصدارات PyTorch الأقدم ووحدات CPU التي لا تدعم oneDNN والتنسيقات المصدّرة مثل TensorRT وONNX.
nmsbool، اختياريNoneيجري افتراضيًا استدلالًا من واحد إلى متعدد باستخدام NMS (None أو True). اضبط False لاستخدام الرأس أحادي إلى واحد الخالي من NMS عند توفره. راجع دليل الاكتشاف الشامل لمزيد من التفاصيل.

وسائط التصور:

المعاملالنوعالافتراضيالوصف
showboolFalseإذا كان True، يعرض الصور أو مقاطع الفيديو المشروحة في نافذة. يفيد ذلك في الحصول على ملاحظات مرئية فورية أثناء التطوير أو الاختبار.
saveboolFalse or Trueيفعّل حفظ الصور أو مقاطع الفيديو المشروحة في ملفات. يفيد ذلك في التوثيق أو التحليل الإضافي أو مشاركة النتائج. تكون القيمة الافتراضية True عند استخدام CLI وFalse عند الاستخدام في Python.
save_framesboolFalseعند معالجة مقاطع الفيديو، يحفظ الإطارات الفردية كصور. يفيد ذلك في استخراج إطارات محددة أو إجراء تحليل تفصيلي إطارًا بإطار.
save_txtboolFalseيحفظ نتائج الاكتشاف في ملف نصي بالتنسيق [class] [x_center] [y_center] [width] [height] [confidence]. يفيد ذلك في التكامل مع أدوات التحليل الأخرى.
save_confboolFalseيضمّن درجات الثقة في الملفات النصية المحفوظة. ويزيد ذلك من تفاصيل البيانات المتاحة للمعالجة اللاحقة والتحليل.
save_cropboolFalseيحفظ صورًا مقتطعة للاكتشافات. يفيد ذلك في زيادة بيانات مجموعة البيانات أو تحليلها أو إنشاء مجموعات بيانات مركزة على كائنات محددة.
show_labelsboolTrueيعرض تسميات كل اكتشاف في المخرجات المرئية، ما يتيح فهم الكائنات المكتشفة فورًا.
show_confboolTrueيعرض درجة الثقة لكل اكتشاف بجوار التسمية، ما يوضح مدى يقين النموذج بشأن كل اكتشاف.
show_boxesboolTrueيرسم صناديق إحاطة حول الكائنات المكتشفة. ويُعد ذلك ضروريًا للتعرف بصريًا على الكائنات وتحديد مواقعها في الصور أو إطارات الفيديو.
line_widthint or NoneNoneيحدد عرض خط صناديق الإحاطة. إذا كان None، يُضبط عرض الخط تلقائيًا وفقًا لحجم الصورة. ويوفر ذلك تخصيصًا مرئيًا لتحسين الوضوح.

أجهزة الاستدلال#

تقبل device أسماء أجهزة PyTorch لجميع تنسيقات النماذج، لذا تحدد القيمة نفسها العتاد نفسه سواء شغّلت نقطة تحقق .pt أو نموذجًا مُصدّرًا. اتركه دون تعيين لاستخدام أفضل جهاز متاح. يربط كل وقت تشغيل الاسم بعتاده الخاص، وتقبل عمليات التحقق وقياس الأداء القيم نفسها:

التنسيقغير معيّنcpu0 أو cuda:0mpsxpunpu
PyTorch .pt، TorchScriptCUDA GPU، وإلا فـCPUCPUGPU من NVIDIAApple GPUGPU من IntelNPU من Huawei Ascend
ONNXCUDA GPU، وإلا فـCPUCPUNVIDIA GPU (CUDA)، AMD GPU (MIGraphX)Core ML--
TensorRTGPU من NVIDIAGPU من NVIDIAGPU من NVIDIA---
OpenVINOOpenVINO AUTOCPU من Intel--Intel GPU (xpu:1 هو GPU.1 في OpenVINO)NPU من Intel
LiteRTCPUCPU--Intel GPU عبر إضافة OpenVINOIntel NPU عبر إضافة OpenVINO
PaddlePaddleCUDA GPU، وإلا فـCPUCPUGPU من NVIDIA---

تعني - أن وقت التشغيل لا يوفّر خلفية لهذا الجهاز. تتحقق ONNX وTensorRT وPaddlePaddle من الاسم أولًا باستخدام PyTorch، لذا ترفض جهازًا لا يستطيع PyTorch رؤيته، وإلا فإنها تعمل على العتاد الافتراضي لديها. يصدر OpenVINO تحذيرًا وينتقل إلى AUTO عند غياب جهاز Intel مطلوب، بينما تنتقل إضافة LiteRT Intel إلى CPU. تختار التنسيقات الأخرى عتادها الخاص: تعمل CoreML على Apple Neural Engine وCPU، ويقبل Edge TPU القيمة tpu:0، وتقبل NCNN القيمة vulkan:0 لمسار Vulkan GPU، بينما تعمل التنسيقات المتبقية على CPU الهدف أو مسرّعه. تظل الأسماء الأقدم intel:cpu وintel:gpu وintel:npu صالحة كأسماء بديلة مهملة للقيم cpu وxpu وnpu.

مثال
from ultralytics import YOLO

model = YOLO("yolo26n_openvino_model/")
results = model("https://ultralytics.com/images/bus.jpg", device="npu")  # Intel NPU

تنسيقات الصور والفيديو#

يدعم YOLO26 تنسيقات متنوعة للصور والفيديو، وفقًا لما هو محدد في ultralytics/data/utils.py. راجع الجداول أدناه للاطلاع على اللواحق الصالحة وأمثلة على أوامر predict.

الصور#

يحتوي الجدول أدناه على تنسيقات الصور الصالحة في Ultralytics.

ملاحظة

تتطلب تنسيقات HEIC/HEIF الحزمة pi-heif، التي تُثبّت تلقائيًا عند أول استخدام. ويدعم Pillow تنسيق AVIF أصليًا.

لواحق الصورمثال على أمر predictمرجع
.avifyolo predict source=image.avifتنسيق ملفات الصور AV1
.bmpyolo predict source=image.bmpتنسيق ملفات BMP من Microsoft
.dngyolo predict source=image.dngتنسيق Adobe DNG
.heicyolo predict source=image.heicتنسيق الصور عالي الكفاءة
.heifyolo predict source=image.heifتنسيق الصور عالي الكفاءة
.jp2yolo predict source=image.jp2JPEG 2000
.jpegyolo predict source=image.jpegJPEG
.jpgyolo predict source=image.jpgJPEG
.mpoyolo predict source=image.mpoكائن صور متعددة
.pngyolo predict source=image.pngرسومات الشبكة المحمولة
.tifyolo predict source=image.tifتنسيق ملفات الصور ذات الوسوم
.tiffyolo predict source=image.tiffتنسيق ملفات الصور ذات الوسوم
.webpyolo predict source=image.webpWebP

مقاطع الفيديو#

يحتوي الجدول أدناه على تنسيقات الفيديو الصالحة في Ultralytics.

لواحق الفيديومثال على أمر predictمرجع
.asfyolo predict source=video.asfتنسيق الأنظمة المتقدمة
.aviyolo predict source=video.aviتداخل الصوت والفيديو
.gifyolo predict source=video.gifتنسيق تبادل الرسوم
.m4vyolo predict source=video.m4vMPEG-4 الجزء 14
.mkvyolo predict source=video.mkvMatroska
.movyolo predict source=video.movتنسيق ملفات QuickTime
.mp4yolo predict source=video.mp4MPEG-4 الجزء 14 - ويكيبيديا
.mpegyolo predict source=video.mpegMPEG-1 الجزء 2
.mpgyolo predict source=video.mpgMPEG-1 الجزء 2
.tsyolo predict source=video.tsتدفق نقل MPEG
.wmvyolo predict source=video.wmvWindows Media Video
.webmyolo predict source=video.webmمشروع WebM

التعامل مع النتائج#

تعيد جميع استدعاءات predict() في Ultralytics قائمة من كائنات Results:

النتائج
from ultralytics import YOLO

# ⁨تحميل نموذج YOLO26n مُدرّب مسبقًا⁩
model = YOLO("yolo26n.pt")

# ⁨تشغيل الاستدلال على صورة⁩
results = model("https://ultralytics.com/images/bus.jpg")
results = model(
    [
        "https://ultralytics.com/images/bus.jpg",
        "https://ultralytics.com/images/zidane.jpg",
    ]
)  # ⁨استدلال على دفعات⁩

تتضمن كائنات Results السمات التالية:

السمةالنوعالوصف
orig_imgnp.ndarrayالصورة الأصلية كمصفوفة NumPy.
orig_shapetupleأبعاد الصورة الأصلية بتنسيق (الارتفاع، العرض).
boxesBoxes, optionalكائن Boxes يحتوي على مربعات الإحاطة للكائنات المكتشفة.
masksMasks, optionalكائن Masks يحتوي على أقنعة الكائنات المكتشفة.
probsProbs, optionalكائن Probs يحتوي على احتمالات كل فئة لمهمة التصنيف.
keypointsKeypoints, optionalكائن Keypoints يحتوي على النقاط المفتاحية المكتشفة لكل كائن.
obbOBB, optionalكائن OBB يحتوي على مربعات إحاطة موجّهة.
semantic_maskSemanticMask, optionalكائن SemanticMask يحتوي على خريطة فئات كثيفة لكل بكسل.
depthDepthMap, optionalكائن DepthMap يحتوي على خريطة عمق كثيفة لكل بكسل.
speeddictقاموس لسرعات المعالجة المسبقة والاستدلال والمعالجة اللاحقة، بالمللي ثانية لكل صورة.
namesdictقاموس يربط فهارس الفئات بأسمائها.
pathstrمسار ملف الصورة.
save_dirstr, optionalالدليل الذي تُحفظ فيه النتائج.

النتائج حسب المهمة#

تعتمد الحقول التي تُملأ أدناه على مهمة النموذج — قارن بين الكشف والتجزئة والتجزئة الدلالية وتقدير العمق والتصنيف والوضعية وOBB إذا لم تختر مهمة بعد. يُرجع كل تنبؤ كائن Results واحدًا لكل صورة أو إطار. تكون الحقول العامة أعلاه متاحة دائمًا، بينما تُخزَّن بيانات التنبؤ الخاصة بالمهمة في الحقول أدناه. تكون موترات إحداثيات YOLO والثقة torch.float32؛ وتكون موترات الاحتمالات torch.float32، إلا إذا كان النموذج يعمل بدقة FP16 (quantize=16 مع نموذج PyTorch أو TorchScript خارج CPU، أو نموذج ONNX بمدخلات FP16)، فعندئذ تكون torch.float16. بعد result.numpy()، تصبح الموترات مصفوفات NumPy بأنواع بيانات NumPy المطابقة. أقنعة المثيلات موترات ثنائية من النوع torch.uint8، بينما تستخدم الأقنعة الدلالية أصغر نوع بيانات صحيح عمليًا لمعرّفات الفئات: torch.uint8 أو torch.int16 أو torch.int32، حسب عدد الفئات.

السمةالنوعالشكلالوصف
result.boxesBoxes(N)مربعات الكشف.
result.boxes.datatorch.float32(N,6/7)[x1,y1,x2,y2,conf,cls] الخام، مع معرّف التتبّع اختياريًا.
result.boxes.xyxytorch.float32(N,4)مربعات البكسل xyxy.
result.boxes.conftorch.float32(N,)درجات الثقة.
result.boxes.clstorch.float32(N,)معرّفات الفئات؛ حوّلها إلى int للحصول على الأسماء.

تتضمن الكائنات Results الطرق التالية:

الطريقةنوع القيمة المُعادةالوصف
update()Noneيحدّث كائن Results ببيانات جديدة مثل الصناديق والأقنعة والاحتمالات وobb والنقاط المفتاحية والأقنعة الدلالية أو العمق.
cpu()Resultsيعيد نسخة من كائن Results مع نقل جميع الموترات إلى ذاكرة CPU.
numpy()Resultsيعيد نسخة من كائن Results مع تحويل جميع الموترات إلى مصفوفات NumPy.
cuda()Resultsيعيد نسخة من كائن Results مع نقل جميع الموترات إلى ذاكرة GPU.
to()Resultsيعيد نسخة من كائن Results مع نقل الموترات إلى الجهاز ونوع البيانات المحددين.
new()Resultsينشئ كائن Results جديدًا له سمات الصورة والمسار والأسماء والسرعة نفسها.
plot()np.ndarrayيرسم نتائج الكشف على صورة BGR مُدخلة ويعيد الصورة المشروحة.
show()Noneيعرض الصورة مع نتائج الاستدلال المشروحة.
save()strيحفظ صورة نتائج الاستدلال المشروحة في ملف ويعيد اسم الملف.
verbose()strيعيد سلسلة سجل لكل مهمة، توضح نتائج الكشف والتصنيف.
save_txt()strيحفظ نتائج الكشف في ملف نصي ويعيد مسار الملف المحفوظ.
save_crop()Noneيحفظ صور الكشف المقتطعة في الدليل المحدد.
summary()List[Dict[str, Any]]يحوّل نتائج الاستدلال إلى قاموس مُلخّص مع إمكانية التطبيع.
to_df()DataFrameيحوّل نتائج الكشف إلى إطار بيانات Polars.
to_csv()strيحوّل نتائج الكشف إلى تنسيق CSV.
to_json()strيحوّل نتائج الكشف إلى تنسيق JSON.

لمزيد من التفاصيل، راجع وثائق الفئة Results.

الصناديق#

يمكن استخدام كائن Boxes لفهرسة صناديق الإحاطة ومعالجتها وتحويلها إلى تنسيقات مختلفة.

الصناديق
from ultralytics import YOLO

# ⁨تحميل نموذج YOLO26n مُدرّب مسبقًا⁩
model = YOLO("yolo26n.pt")

# ⁨تشغيل الاستدلال على صورة⁩
results = model("https://ultralytics.com/images/bus.jpg")  # ⁨قائمة results⁩

# ⁨عرض النتائج⁩
for r in results:
    print(r.boxes)  # ⁨اطبع كائن Boxes الذي يحتوي على صناديق الإحاطة المكتشفة⁩

إليك جدولًا لطرق وخصائص الفئة Boxes، يتضمن الاسم والنوع والوصف:

الاسمالنوعالوصف
cpu()الطريقةانقل الكائن إلى ذاكرة CPU.
numpy()الطريقةحوّل الكائن إلى مصفوفة NumPy.
cuda()الطريقةانقل الكائن إلى ذاكرة CUDA.
to()الطريقةانقل الكائن إلى الجهاز المحدد.
xyxyالخاصية (torch.Tensor)أعِد الصناديق بتنسيق xyxy.
confالخاصية (torch.Tensor)أعِد قيم الثقة للصناديق.
clsالخاصية (torch.Tensor)أعِد قيم الفئات للصناديق.
idالخاصية (torch.Tensor)أعِد معرّفات التتبّع للصناديق (إن توفرت).
xywhالخاصية (torch.Tensor)أعِد الصناديق بتنسيق xywh.
xyxynالخاصية (torch.Tensor)أعِد الصناديق بتنسيق xyxy بعد تطبيعها حسب حجم الصورة الأصلية.
xywhnالخاصية (torch.Tensor)أعِد الصناديق بتنسيق xywh بعد تطبيعها حسب حجم الصورة الأصلية.

لمزيد من التفاصيل، راجع وثائق الفئة Boxes.

الأقنعة#

يمكن استخدام كائن Masks لفهرسة الأقنعة ومعالجتها وتحويلها إلى مقاطع.

الأقنعة
from ultralytics import YOLO

# ⁨حمّل نموذج تقسيم YOLO26n-seg مُدرّبًا مسبقًا⁩
model = YOLO("yolo26n-seg.pt")

# ⁨تشغيل الاستدلال على صورة⁩
results = model("https://ultralytics.com/images/bus.jpg")  # ⁨قائمة results⁩

# ⁨عرض النتائج⁩
for r in results:
    print(r.masks)  # ⁨اطبع كائن Masks الذي يحتوي على أقنعة المثيلات المكتشفة⁩

إليك جدولًا لطرق وخصائص الفئة Masks، يتضمن الاسم والنوع والوصف:

الاسمالنوعالوصف
dataالخاصية (torch.Tensor)موتر قناع ثنائي torch.uint8 ذو شكل (N,H,W) وقيم 0 أو 1.
cpu()الطريقةيعيد موتر الأقنعة في ذاكرة CPU.
numpy()الطريقةيعيد موتر الأقنعة كمصفوفة NumPy.
cuda()الطريقةيعيد موتر الأقنعة في ذاكرة GPU.
to()الطريقةيعيد موتر الأقنعة بالجهاز ونوع البيانات المحددين.
xynالخاصية (list[np.ndarray])قائمة بمضلعات الأقنعة المُطبَّعة.
xyالخاصية (list[np.ndarray])قائمة بمضلعات الأقنعة بإحداثيات البكسل.

لمزيد من التفاصيل، راجع وثائق الفئة Masks.

القناع الدلالي#

يخزّن SemanticMask خريطة فئات كثيفة واحدة لنتائج التجزئة الدلالية. وعلى خلاف Masks، لا يحتوي على قناع ثنائي لكل كائن، ولا يوفر أدوات مساعدة للمضلعات.

القناع الدلالي
from ultralytics import YOLO

# ⁨حمّل نموذج دلالي YOLO26n-sem مُدرّبًا مسبقًا⁩
model = YOLO("yolo26n-sem.pt")

# ⁨تشغيل الاستدلال على صورة⁩
results = model("https://ultralytics.com/images/bus.jpg")  # ⁨قائمة results⁩

# ⁨عرض النتائج⁩
for r in results:
    print(r.semantic_mask.data)  # ⁨اطبع خريطة معرّفات الفئات H × W⁩
الاسمالنوعالوصف
dataالخاصية (torch.Tensor)خريطة معرّفات الفئات ذات الشكل (H,W). نوع البيانات هو torch.uint8 أو torch.int16 أو torch.int32، ويُحدَّد بحسب عدد الفئات.
shapeالخاصية (tuple)شكل خريطة الفئات، والذي يطابق عادةً result.orig_shape.
cpu()الطريقةيعيد موتر القناع الدلالي في ذاكرة CPU.
numpy()الطريقةيعيد موتر القناع الدلالي كمصفوفة NumPy.
cuda()الطريقةيعيد موتر القناع الدلالي في ذاكرة GPU.
to()الطريقةيعيد موتر القناع الدلالي بالجهاز ونوع البيانات المحددين.

النقاط المفتاحية#

يمكن استخدام كائن Keypoints لفهرسة الإحداثيات ومعالجتها وتطبيعها.

النقاط المفتاحية
from ultralytics import YOLO

# ⁨حمّل نموذج وضعية YOLO26n-pose مُدرّبًا مسبقًا⁩
model = YOLO("yolo26n-pose.pt")

# ⁨تشغيل الاستدلال على صورة⁩
results = model("https://ultralytics.com/images/bus.jpg")  # ⁨قائمة results⁩

# ⁨عرض النتائج⁩
for r in results:
    print(r.keypoints)  # ⁨اطبع كائن Keypoints الذي يحتوي على النقاط المفتاحية المكتشفة⁩

إليك جدولًا لطرق وخصائص الفئة Keypoints، يتضمن الاسم والنوع والوصف:

الاسمالنوعالوصف
cpu()الطريقةيعيد موتر النقاط المفتاحية في ذاكرة CPU.
numpy()الطريقةيعيد موتر النقاط المفتاحية كمصفوفة NumPy.
cuda()الطريقةيعيد موتر النقاط المفتاحية في ذاكرة GPU.
to()الطريقةيعيد موتر النقاط المفتاحية بالجهاز ونوع البيانات المحددين.
xynالخاصية (torch.Tensor)إحداثيات النقاط المفتاحية المُطبَّعة ذات الشكل (N,K,2).
xyالخاصية (torch.Tensor)إحداثيات النقاط المفتاحية بالبكسل ذات الشكل (N,K,2).
confالخاصية (torch.Tensor)يعيد قيم الثقة للنقاط المفتاحية إن توفرت، وإلا يعيد None.

لمزيد من التفاصيل، راجع وثائق الفئة Keypoints.

الاحتمالات#

يمكن استخدام كائن Probs للحصول على فهارس التصنيف ودرجاته top1 وtop5.

الاحتمالات
from ultralytics import YOLO

# ⁨حمّل نموذج تصنيف YOLO26n-cls مُدرّبًا مسبقًا⁩
model = YOLO("yolo26n-cls.pt")

# ⁨تشغيل الاستدلال على صورة⁩
results = model("https://ultralytics.com/images/bus.jpg")  # ⁨قائمة results⁩

# ⁨عرض النتائج⁩
for r in results:
    print(r.probs)  # ⁨اطبع كائن Probs الذي يحتوي على احتمالات الفئات المكتشفة⁩

إليك جدولًا يلخّص طرق وخصائص الفئة Probs:

الاسمالنوعالوصف
cpu()الطريقةيعيد نسخة من موتر probs في ذاكرة CPU.
numpy()الطريقةيعيد نسخة من موتر probs على هيئة مصفوفة NumPy.
cuda()الطريقةيعيد نسخة من موتر probs في ذاكرة GPU.
to()الطريقةيعيد نسخة من موتر probs باستخدام الجهاز ونوع البيانات المحددين.
top1الخاصية (int)فهرس الفئة الأولى الأعلى ترتيبًا.
top5الخاصية (list[int])فهارس الفئات الخمس الأعلى ترتيبًا.
top1confالخاصية (torch.Tensor)درجة الثقة للفئة الأولى الأعلى ترتيبًا.
top5confالخاصية (torch.Tensor)درجات الثقة للفئات الخمس الأعلى ترتيبًا.

لمزيد من التفاصيل، راجع وثائق الفئة Probs.

OBB#

يمكن استخدام الكائن OBB لفهرسة مربعات الإحاطة الموجّهة ومعالجتها وتحويلها إلى تنسيقات مختلفة.

OBB
from ultralytics import YOLO

# ⁨تحميل نموذج YOLO26n مُدرّب مسبقًا⁩
model = YOLO("yolo26n-obb.pt")

# ⁨تشغيل الاستدلال على صورة⁩
results = model("https://ultralytics.com/images/boats.jpg")  # ⁨قائمة results⁩

# ⁨عرض النتائج⁩
for r in results:
    print(r.obb)  # ⁨اطبع كائن OBB الذي يحتوي على مربعات الإحاطة الموجّهة للكائنات المكتشفة⁩

إليك جدولًا لطرق وخصائص الفئة OBB، يتضمن الاسم والنوع والوصف:

الاسمالنوعالوصف
cpu()الطريقةانقل الكائن إلى ذاكرة CPU.
numpy()الطريقةحوّل الكائن إلى مصفوفة NumPy.
cuda()الطريقةانقل الكائن إلى ذاكرة CUDA.
to()الطريقةانقل الكائن إلى الجهاز المحدد.
confالخاصية (torch.Tensor)أعِد قيم الثقة للصناديق.
clsالخاصية (torch.Tensor)أعِد قيم الفئات للصناديق.
idالخاصية (torch.Tensor)أعِد معرّفات التتبّع للصناديق (إن توفرت).
xyxyالخاصية (torch.Tensor)أعِد المربعات الأفقية بتنسيق xyxy.
xywhrالخاصية (torch.Tensor)أعِد المربعات المُدارة بتنسيق xywhr.
xyxyxyxyالخاصية (torch.Tensor)أعِد المربعات المُدارة بتنسيق xyxyxyxy.
xyxyxyxynالخاصية (torch.Tensor)أعِد المربعات المُدارة بتنسيق xyxyxyxy بعد تطبيعها حسب حجم الصورة.

لمزيد من التفاصيل، راجع وثائق الفئة OBB.

رسم النتائج#

تتيح الطريقة plot() في كائنات Results تصور التنبؤات من خلال تراكب الكائنات المكتشفة (مثل مربعات الإحاطة والأقنعة والنقاط المفتاحية والاحتمالات) على الصورة الأصلية. وتعيد هذه الطريقة الصورة المشروحة على هيئة مصفوفة NumPy، ما يسهّل عرضها أو حفظها.

الرسم
from PIL import Image

from ultralytics import YOLO

# Load a pretrained YOLO26n model
model = YOLO("yolo26n.pt")

# Run inference on 'bus.jpg'
results = model(["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/zidane.jpg"])  # results list

# Visualize the results
for i, r in enumerate(results):
    # Plot results image
    im_bgr = r.plot()  # BGR-order numpy array
    im_rgb = Image.fromarray(im_bgr[..., ::-1])  # RGB-order PIL image

    # Show results to screen (in supported environments)
    r.show()

    # Save results to disk
    r.save(filename=f"results{i}.jpg")

معلمات الطريقة plot()#

تدعم الطريقة plot() وسائط متنوعة لتخصيص المخرجات:

المعاملالنوعالوصفالافتراضي
confboolتضمين درجات ثقة الكشف.True
line_widthfloatعرض خطوط مربعات الإحاطة. يتغير حسب حجم الصورة إذا كان None.None
font_sizefloatحجم خط النص. يتغير حسب حجم الصورة إذا كان None.None
fontstrاسم الخط المستخدم في التعليقات النصية.'Arial.ttf'
pilboolإرجاع الصورة ككائن PIL Image.False
imgnp.ndarray | torch.Tensorصورة بديلة. يجب أن تكون الموترات متصلة الذاكرة بتنسيق HWC BGR uint8.None
kpt_radiusintنصف قطر النقاط المفتاحية المرسومة.5
kpt_lineboolوصل النقاط المفتاحية بخطوط.True
labelsboolتضمين تسميات الفئات في التعليقات التوضيحية.True
boxesboolتراكب مربعات الإحاطة على الصورة.True
masksboolتراكب الأقنعة على الصورة.True
probsboolتضمين احتمالات التصنيف.True
showboolعرض الصورة المشروحة مباشرةً باستخدام عارض الصور الافتراضي.False
saveboolحفظ الصورة المشروحة في الملف المحدد بواسطة filename.False
filenamestrمسار الملف واسم الملف المراد حفظ الصورة المشروحة فيه إذا كانت قيمة save هي True.None
color_modestrحدّد وضع الألوان، مثل 'instance' أو 'class'.'class'
txt_colortuple[int, int, int]لون النص بتنسيق BGR لتسميات التصنيف.(255, 255, 255)

الاستدلال الآمن للخيوط#

يُعد ضمان سلامة الخيوط أثناء الاستدلال أمرًا بالغ الأهمية عند تشغيل عدة نماذج YOLO بالتوازي عبر خيوط مختلفة. يضمن الاستدلال الآمن للخيوط عزل تنبؤات كل خيط وعدم تداخلها، مما يجنب حالات التنافس ويضمن مخرجات متسقة وموثوقة.

عند استخدام نماذج YOLO في تطبيق متعدد الخيوط، من المهم إنشاء كائنات نموذج منفصلة لكل خيط أو استخدام تخزين محلي للخيط لتجنب التعارضات:

الاستدلال الآمن للخيوط

أنشئ نموذجًا واحدًا داخل كل خيط لضمان استدلال آمن للخيوط:

from threading import Thread

from ultralytics import YOLO

def thread_safe_predict(model, image_path):
    """Performs thread-safe prediction on an image using a locally instantiated YOLO model."""
    model = YOLO(model)
    results = model.predict(image_path)
    # ⁨معالجة النتائج⁩

# ⁨بدء خيوط يمتلك كل منها مثيل نموذج خاصًا به⁩
Thread(target=thread_safe_predict, args=("yolo26n.pt", "image1.jpg")).start()
Thread(target=thread_safe_predict, args=("yolo26n.pt", "image2.jpg")).start()

حلقة for لمصدر البث#

فيما يلي برنامج Python النصي يستخدم OpenCV (cv2) وYOLO لإجراء الاستدلال على إطارات الفيديو. يفترض هذا البرنامج أنك ثبّت الحزم اللازمة مسبقًا (opencv-python وultralytics).

حلقة for للبث
import cv2

from ultralytics import YOLO

# ⁨تحميل نموذج YOLO⁩
model = YOLO("yolo26n.pt")

# ⁨افتح ملف الفيديو⁩
video_path = "path/to/your/video/file.mp4"
cap = cv2.VideoCapture(video_path)

# ⁨تكرار إطارات الفيديو⁩
while cap.isOpened():
    # ⁨قراءة إطار من الفيديو⁩
    success, frame = cap.read()

    if success:
        # ⁨إجراء استدلال YOLO على الإطار⁩
        results = model(frame)

        # ⁨تصور النتائج على الإطار⁩
        annotated_frame = results[0].plot()

        # ⁨عرض الإطار المشروح⁩
        cv2.imshow("YOLO Inference", annotated_frame)

        # ⁨إنهاء الحلقة إذا ضُغط على 'q'⁩
        if cv2.waitKey(1) & 0xFF == ord("q"):
            break
    else:
        # ⁨إنهاء الحلقة عند الوصول إلى نهاية الفيديو⁩
        break

# ⁨تحرير كائن التقاط الفيديو وإغلاق نافذة العرض⁩
cap.release()
cv2.destroyAllWindows()

ينفّذ هذا البرنامج تنبؤات على كل إطار من الفيديو، ويصور النتائج، ويعرضها في نافذة. يمكن الخروج من الحلقة بالضغط على 'q'.

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

هل أنت مستعد لتجاوز استخدام نموذج مدرّب مسبقًا؟ تأكد من أن مهمتك تلائم مشكلتك، وهيّئ بياناتك باستخدام دليل مجموعات البيانات، ثم درّب النموذج عليها.

الأسئلة الشائعة#

  • تُعد Ultralytics YOLO عائلة من أحدث النماذج لاكتشاف الكائنات في الزمن الفعلي، وتجزئة المثيلات، والتجزئة الدلالية، وتقدير العمق، والتصنيف، وتقدير الوضعية، واكتشاف مربعات الإحاطة الموجّهة (OBB). ويُجري وضع التنبؤ فيها الاستدلال بسرعة عالية على مصادر بيانات مثل الصور ومقاطع الفيديو والبث المباشر، مع دعم المعالجة الدفعية والبث.

  • يمكن لـ Ultralytics YOLO معالجة مجموعة واسعة من مصادر البيانات، بما فيها الصور الفردية ومقاطع الفيديو والمجلدات وعناوين URL وعمليات البث. يمكنك تحديد مصدر البيانات في استدعاء model.predict(). على سبيل المثال، استخدم 'image.jpg' لصورة محلية أو 'https://ultralytics.com/images/bus.jpg' لعنوان URL. راجع الأمثلة التفصيلية لمختلف مصادر الاستدلال في الوثائق.

  • لتحسين سرعة الاستدلال وإدارة الذاكرة بكفاءة، يمكنك استخدام وضع البث عن طريق ضبط stream=True في طريقة استدعاء المتنبئ. ينشئ وضع البث مولّدًا موفرًا للذاكرة من كائنات Results بدلًا من تحميل جميع الإطارات إلى الذاكرة. ويُعد وضع البث مفيدًا بوجه خاص لمعالجة مقاطع الفيديو الطويلة أو مجموعات البيانات الكبيرة. تعرّف على المزيد حول وضع البث.

  • تدعم الطريقة model.predict() في YOLO وسائط متنوعة، مثل conf وiou وimgsz وdevice وغيرها. تتيح لك هذه الوسائط تخصيص عملية الاستدلال وضبط معلمات مثل عتبات الثقة وحجم الصورة والجهاز المستخدم للحوسبة. يمكن العثور على أوصاف تفصيلية لهذه الوسائط في قسم وسائط الاستدلال.

  • استخدم model.embed(source) لاستخراج تضمينات الميزات من الطبقة قبل الأخيرة، أو مرّر embed=[layer_index] إلى model.predict() لاختيار طبقات محددة.

    from ultralytics import YOLO
    
    model = YOLO("yolo26n.pt")
    source = "https://ultralytics.com/images/bus.jpg"
    
    results = model.predict(source)  # ⁨كائنات النتائج⁩
    embeddings = model.embed(source)  # ⁨قائمة تضمينات torch.Tensor⁩
  • بعد إجراء الاستدلال باستخدام YOLO، تحتوي كائنات Results على طرق لعرض الصور المشروحة وحفظها. يمكنك استخدام طرق مثل result.show() وresult.save(filename="result.jpg") لتصور النتائج وحفظها. تُنشأ تلقائيًا أي مجلدات رئيسية غير موجودة في مسار اسم الملف (مثل result.save("path/to/result.jpg")). للاطلاع على قائمة شاملة بهذه الطرق، راجع قسم العمل مع النتائج.

التعليقات629

اطرح سؤالًا، وشارك نتائجك، أو ساعد شخصًا آخر.

  1. TigoresGitHub

    你好,我想问一下为什么我在推理相同的图像时,设置不同的imgsz参数,会有不同的结果。在一张图像上,有大船、小船、人。imgsz设置的值有640(默认)、1280、1980。640只能检测到大船;1280会检测到大船和小船,并且大船的置信度更高;1980还能检测到人。我很疑惑,模型的输入尺寸不是在训练的时候就已经固定了吗,这是否意味着推理的图像预处理阶段,不管我如何调整imgsz参数,模型都会将输入图像采样到640。但是现在出现的不同的结果,是为什么呢?下面是我的代码: from ultralytics import YOLO model = YOLO("/data/dxh/ultralytics/weight/yolov8s.pt")
    results = model("/data/dxh/ultralytics/datasets/test/invade_ship_cls/invade_result", imgsz=1280, save=True)

    1
    1. Glenn JocherUltralytics

      @Tigores 您好!YOLO模型在推理时会自动将输入图像缩放到您指定的imgsz参数值(而非固定为训练尺寸),更大的分辨率能保留更多细节从而提升小目标检测能力。具体原理可参考Predict模式文档中的图像尺寸与精度关系说明,这是预期行为而非异常现象。

  2. LwpZoeGitHub

    Hello, I would like to ask, my task is instance segmentation. At present, I get the predicted result is the original image superimposed label image, but the result I want is just the RGB label image, no need to superimpose the original image. Where do I need to make changes to make the result a segmented label image?

    1
    1. Glenn JocherUltralytics(تم التعديل)

      @LwpZoe to obtain only the RGB label image without the original image overlay, you can disable the overlay during visualization. Use the plot() method with boxes=False and masks=True to only display the segmentation masks. Alternatively, you can directly access result.masks.data for raw mask data and process it as needed. Refer to the Results section for more details.

    2. LwpZoeGitHub

      Found plot () in yolo-segment-main/ultralytics/engine/results.py, modified content: Def plot ( Self, Conf = True, line_width = None, font_size = None, Font = "Arial.ttf", Pil = False, Img = None, im_gpu = None, kpt_radius = 5, kpt_line = False, Labels = False, Boxes = False, Masks = True, Probs = True, Show = True, Save = True, Filename = 'result', color_mode = "class", ): Make predictions using the command line: Yolo segment predict model = runs/segment/train/weights/best.pt source=yolo-seg-main/datasets/test The result is still the original image overlay mask and box, why? Does changing plot () require retraining to get best.pt in order to predict?

    3. Glenn JocherUltralytics

      To display only the segmentation mask without overlays, modify the plot() function parameters by setting boxes=False, labels=False, and ensuring masks=True. You don't need retraining to adjust visualization settings, as the weights remain unaffected. For further details, refer to the Results.plot() documentation.

  3. User

    Hello, when I run the predict script, I predict a large amount of image data (about more than 20,000 test images). At this time, the model's predict will get stuck, and I don't generate the image of the prediction box. How can I solve this bug?

    1
    1. Paula DerrengerUltralytics

      @Stephen-Hao it sounds like you might be running into memory issues when processing a large number of images. To handle large datasets more efficiently, consider using the stream=True argument in your model.predict() call. This will create a memory-efficient generator of results, reducing the likelihood of your system getting stuck. Additionally, ensure you are using the latest version of the Ultralytics package to benefit from any recent optimizations and bug fixes. If the issue persists, please provide more details about your environment and any error messages you encounter.

    2. Paula DerrengerUltralytics

      @Stephen-Hao you're welcome! If you're experiencing issues with the model getting stuck while predicting a large number of images, try using the stream=True argument in your model.predict() call. This will help manage memory more efficiently by processing images one at a time instead of loading all at once. Also, ensure you're using the latest version of the Ultralytics package. If the problem persists, please provide more details about your setup and any error messages you encounter.

  4. Johanna-JonesGitHub

    Hey, Is there a way to get the MAP precision, IOU and other metrics for the test images you might give the model?

    I have images and the ground truth for the test images but not sure how to get the same metrics for the PREDICT mode

    Thank you!

    1
    1. Johanna-JonesGitHub

      For clarification my pipeline is currently train> valid with val parameter set to false. I then pass one image at a time to the Yolov8 model in the PREDICT mode

    2. Paula DerrengerUltralytics

      Hey there!

      For evaluating your model with metrics like mAP, precision, and IOU on your test images, you should use the Val mode rather than the Predict mode. The Val mode allows you to validate your model on a dataset and provides comprehensive metrics, including the ones you're interested in. Here's an example on how to do it:

      from ultralytics import YOLO
      
      # Assuming 'coco128.yaml' is your dataset configuration file that includes your test data path
      # and that 'your_model.pt' is the trained model you want to evaluate
      model = YOLO('path/to/your_model.pt')
      
      # Validate the model, this will automatically calculate mAP, IOU, and other metrics
      results = model.val(data='path/to/your_dataset_config.yaml')

      Remember to adjust 'path/to/your_model.pt' and 'path/to/your_dataset_config.yaml' to the actual paths of your model and dataset configuration file.

      In your YAML dataset configuration file, make sure to correctly specify the path to your test images and annotations. This way, YOLOv8 will know how to find your test data and corresponding ground truth for evaluation.

      If you have any more questions, feel free to ask. Good luck with your model evaluation! 🚀

  5. GUPABE10GitHub

    how to ignore printing results after inference: 0: 384x640 10 persons, 1 sports ball, 4080.4ms Speed: 12.3ms preprocess, 4080.4ms inference, 1.7ms postprocess per image at shape (1, 3, 384, 640)

    1
    1. Glenn JocherUltralytics

      To disable printing inference results after running predictions, you can use the verbose=False argument in your predict() function. This will prevent the printout of inference times and detected objects. Here's a quick example on how to do it:

      from ultralytics import YOLO
      
      # Load your YOLOv8 model
      model = YOLO('yolov8n.pt')  
      
      # Run inference with verbose=False
      results = model.predict('path/to/your/image.jpg', verbose=False)

      This should keep your console output clean while still performing inference. 😊

    2. GUPABE10GitHub

      Is it the same if I use:

      results = model('path/to/your/image.jpg')

      just as mentioned in the example in this tutorial.

    3. Glenn JocherUltralytics

      @GUPABE10 hi there!

      Yes, using results = model('path/to/your/image.jpg') is perfectly fine and aligns with the examples provided in the tutorial. This command will run inference on the specified image and return the results as a list of Results objects.

      If you want to avoid printing the detailed inference results (like the number of detected objects and processing times), you can use the verbose=False argument:

      from ultralytics import YOLO
      
      # Load a pretrained YOLOv8n model
      model = YOLO("yolov8n.pt")
      
      # Run inference on an image without printing detailed results
      results = model.predict('path/to/your/image.jpg', verbose=False)

      This will keep your console output clean while still performing the inference. If you have any more questions or need further assistance, feel free to ask! 😊

    4. Glenn JocherUltralytics

      Hi there!

      Great question! The difference between model.predict() and model() lies in their usage and flexibility:

      1. model.predict():

        • This method is explicitly designed for running predictions and allows you to pass various arguments to customize the inference process.
        • You can specify parameters like save, imgsz, conf, device, and more to control the behavior of the prediction.
        • Example:
          from ultralytics import YOLO
          
          # Load a pretrained YOLOv8n model
          model = YOLO("yolov8n.pt")
          
          # Run inference with custom arguments
          results = model.predict("path/to/image.jpg", save=True, imgsz=320, conf=0.5)
      2. model():

        • This is a shorthand method that calls the predict() function internally with default settings.
        • It is useful for quick predictions without needing to specify additional parameters.
        • Example:
          from ultralytics import YOLO
          
          # Load a pretrained YOLOv8n model
          model = YOLO("yolov8n.pt")
          
          # Run inference with default settings
          results = model("path/to/image.jpg")

      Both methods will return a list of Results objects, which you can then process as needed. If you need more control over the prediction process, model.predict() is the way to go. For quick and straightforward predictions, model() is convenient.

      Feel free to check out the Ultralytics documentation on prediction for more details and examples.

      Happy coding! 😊

    1. Glenn JocherUltralytics

      Yes—vid_stride (frame skipping) and imgsz (inference resize) are independent, so you can use them together on video sources; imgsz will be applied to the frames that are actually processed (see the Predict mode inference arguments).

      yolo predict model=yolo26n.pt source=video.mp4 vid_stride=2 imgsz=640
      from ultralytics import YOLO
      
      model = YOLO("yolo26n.pt")
      for r in model.predict("video.mp4", vid_stride=2, imgsz=640, stream=True):
          pass
      1
    2. amani784GitHub

      Thank you for your help. I have another question: if I don’t define imgsz in predict, will it resize the image to 640 by default? I have multiple inputs with different resolutions, so I can’t specify a single value for imgsz in .predict or even during ONNX export, because sometimes the input resolution is larger than imgsz.

    3. Glenn JocherUltralytics

      Yes—if you don’t pass imgsz to predict(), it uses the default imgsz=640 and will letterbox/resize each frame/image to that inference size (so larger inputs are downscaled, smaller are upscaled); for mixed-resolution sources you can either leave the default or set a larger imgsz for more detail (GPU memory permitting) as described in the predict settings defaults.

      If you need an ONNX that can accept varying input shapes at runtime, export with dynamic shapes enabled (then your runtime can feed different H×W sizes):

      yolo export model=yolo26n.pt format=onnx dynamic=True
      from ultralytics import YOLO
      
      model = YOLO("yolo26n.pt")
      model.export(format="onnx", dynamic=True)

      Feel free to drop the exact input resolutions (and whether this is video-only) here in the discussion and we can suggest a good imgsz strategy for your case.

      1
    4. amani784GitHub

      Thank you so much ,but for tensorRT export , the model can't accept varying input shapes and i was obliged to put imgsz or my videos have different resolutions and i can't put one imgsz value that can fit all the resolutions. Is there any other solution?

    5. Glenn JocherUltralytics

      Yes—TensorRT doesn’t have to be fixed-shape: export your .engine with dynamic=True so the runtime can accept varying input shapes (you can then choose imgsz per run/video), see the Export mode docs and the TensorRT integration guide.

      yolo export model=yolo26n.pt format=engine dynamic=True

      If you need peak throughput and your resolutions vary a lot, the usual workaround is exporting 2–3 fixed engines at common imgsz values and selecting the closest one at runtime.

      1
  6. Asshok1GitHub

    Hey @glenn-jocher, I’m trying to integrate a TensorRT-optimized YOLO model (.engine) with SAHI (Slicing Aided Hyper Inference) for efficient large-image inference, but I’m facing difficulties making them work together correctly as .engine is not accepted in sahi, can you help in providing the complete code for integrating tensorRT with sahi.

    1. Glenn JocherUltralytics

      SAHI’s built-in Ultralytics integration (model_type="ultralytics") currently expects PyTorch weights like *.pt, so a TensorRT *.engine file won’t load through SAHI as-is; the supported path is to use SAHI with *.pt per the SAHI tiled inference guide, or run the TensorRT engine directly with Ultralytics per the TensorRT export/inference guide. If you specifically need SAHI slicing + a *.engine, you’ll need a custom SAHI DetectionModel adapter around Ultralytics’ TensorRT predictor (best tracked upstream in the SAHI repository); please paste your Ultralytics/SAHI versions and a minimal repro here in the discussion so we can advise on the cleanest adapter approach.

      # SAHI (supported): Ultralytics *.pt + slicing
      from sahi import AutoDetectionModel
      from sahi.predict import get_sliced_prediction
      
      detection_model = AutoDetectionModel.from_pretrained(
          model_type="ultralytics",
          model_path="best.pt",
          confidence_threshold=0.25,
          device="cuda:0",
      )
      
      result = get_sliced_prediction(
          "large.jpg",
          detection_model,
          slice_height=640,
          slice_width=640,
          overlap_height_ratio=0.2,
          overlap_width_ratio=0.2,
      )
      # TensorRT (supported): Ultralytics *.engine inference (no SAHI wrapper)
      from ultralytics import YOLO
      
      model = YOLO("best.engine")
      results = model.predict("large.jpg", device=0, imgsz=640)
  7. hanchaoyuanGitHub

    hello! I used the YOLO11-pose model to estimate the key points of people in the automotive production workshop. However, the model often identified vehicles, hoists and other equipment as humans and calculated the key points, resulting in a relatively high false alarm rate. My question is: How can we prevent the model from identifying other objects and reduce the false alarm rate?

    1. Glenn JocherUltralytics

      For workshop false positives with pose models, the quickest lever is raising the prediction threshold (and optionally increasing imgsz for better person discrimination), but the most reliable fix is fine-tuning on your own workshop data with “hard negative” images (frames with vehicles/hoists but no people) so the model learns your background; see the inference args in the predict mode docs.

      yolo pose predict model=yolo11n-pose.pt source=path/to/video.mp4 conf=0.6 imgsz=960

      If you paste your exact command, plus a couple representative frames (people + false positives) here in the discussion, we can suggest tighter settings or a training setup (and for new work, try a YOLO26 pose checkpoint as it’s generally stronger out of the box).

  8. d5423197GitHub

    Hi there,

    If no boxes/masks detected by the model, what will be the output of model inference. (results = model(["image1.jpg", "image2.jpg"]) #)

    I want to deal with the edge case.