كيفية ضبط عتبة IoU في NMS ضمن Ultralytics YOLO

تحدد عتبة IoU متى يتعامل الكاشف مع صندوقين متداخلين على أنهما للجسم نفسه. في Ultralytics YOLO، يحتفظ الكبت غير الأقصى (NMS) بالصندوق ذي أعلى ثقة ويحذف أي صندوق آخر من الفئة نفسها يتداخل معه بأكثر من iou. إذا جعلت العتبة مرتفعة جدًا، فسيظهر للجسم الواحد صندوقان؛ وإذا جعلتها منخفضة جدًا، فسيختفي الجسم الثاني من جسمين متجاورين.

اعتبارًا من Ultralytics 8.4.208، الذي صدر في 8 نوفمبر 2026، أصبح الإعداد الافتراضي للتنبؤ والتتبع iou=0.5 بدلًا من 0.7، بينما يظل الإعداد الافتراضي للتحقق 0.7. يشرح هذا الدليل ما الذي تغير ولماذا، وكيف تتفاعل العتبة مع conf، وكيف تضبط كليهما لكاميرتك، ومتى تتخلى عن NMS تمامًا باستخدام الرأس الشامل من طرف إلى طرف في YOLO26.

أصبح Ultralytics YOLO يتنبأ ويتتبع الآن باستخدام IoU بقيمة 0.5 افتراضيًا#

عندما لا تمرر iou وتُطبَّق NMS، يستخدم كل من وضع التنبؤ ووضع التتبع الآن القيمة 0.5. وتظل أي قيمة تمررها صراحةً هي المعتمدة، لذا تستمر مسارات العمل التي تضبط iou بالفعل كما كانت تمامًا. ويسرد مرجع إعدادات التنبؤ القيمة الافتراضية الجديدة إلى جانب conf=0.25.

تعتمد مسارات العمل هذه القيمة 0.5 عندما يكون iou غير مضبوط:

• التنبؤ والتتبع باستخدام Python وCLI، بما في ذلك المُتنبئات المعاد استخدامها وتحديد iou=None صراحةً.
• الحلول مثل عدّ الأجسام وإدارة الطوابير وTrackZone، التي ترث قيمة المُتنبئ.
• عمليات التصدير الجديدة المضمّن فيها NMS (nms=True). ويحتفظ النموذج الذي صدّرته سابقًا بالقيمة الافتراضية وقت تصديره.
• منصة Ultralytics، حيث تسرد وثائق الاستدلال منزلق IoU وحقل iou، وتكون قيمتهما 0.5 في نقاط النهاية المنشورة.
• حزم الأجهزة المحمولة: تضبط حزمة Ultralytics YOLO لنظام iOS القيمة الافتراضية على 0.5 في الإصدار 8.9.20، وكذلك إضافة Flutter في الإصدار 0.7.2؛ وتعتمد القيم الافتراضية في متاجر التطبيقات على الإصدار المثبّت.

يظل أمران مضبوطين عمدًا على 0.7: التحقق، كي لا تتغير قيم mAP المنشورة، ومُتنبئات SAM وSAM 2 وSAM 3 وFastSAM، إذ لم تكن الأقنعة ذات التداخل الشديد ضمن القياس.

علامة تبويب Predict لنموذج سلامة المستودعات في منصة Ultralytics، أثناء تنفيذ تنبؤ فعلي. يبدأ منزلق IoU الآن عند 0.5.

لماذا لم تكن القيمة الافتراضية القديمة 0.7 مناسبة للتنبؤ#

قبل هذا الإصدار، كان لـiou إعداد افتراضي واحد مشترك بين predict وval. ووفقًا لـPR #27084، انتقلت هذه القيمة من 0.6 إلى 0.7 بتغيير من سطر واحد في الإعدادات في ديسمبر 2022، ضمن طلب سحب غير ذي صلة بتحميل البيانات، ثم اتبعت تطبيقات الأجهزة المحمولة هذه القيمة لاحقًا لمجرد الاتساق.

للوضعين مهمتان مختلفتان:

• يقيّم التحقق قائمة الصناديق المرتبة بأكملها، حتى مستوى ثقة قدره 0.001. وعادةً ما يأتي الصندوق المكرر بترتيب أدنى من الصندوق الصحيح، فلا يسبب خسارة كبيرة، بينما يؤدي كبت جسم حقيقي إلى خفض الاستدعاء عند كل عتبة. وتحافظ العتبة المتساهلة على المرشحين المتداخلين لأغراض التقييم.
• يعيد التنبؤ مجموعة نهائية واحدة من الصناديق عند conf=0.25. وكل صندوق مكرر تسمح NMS بمروره يمثل نتيجة إيجابية كاذبة ظاهرة في المخرجات أو العدد أو التنبيه. وعند 0.7، ينجو صندوقان من الفئة نفسها إذا لم يتجاوز تداخلهما 70%.

كان لـconf إعدادان افتراضيان منفصلان لهذا السبب تحديدًا: 0.25 للتنبؤ و0.001 للتحقق. ويتبع iou الآن النهج نفسه.

ما الذي أظهره القياس#

يعرض PR #27084 درجات F1 للكشف عند عتبات NMS التالية على COCO val2017 باستخدام RTX PRO 6000. وتلخص F1 كلاً من الدقة والاستدعاء؛ والقيم أدناه متوسطات الفئات، معبّرًا عنها بالنسب المئوية:

تحقق كل النماذج درجة أعلى عند 0.45 أو 0.5 مقارنةً بـ0.7، وتقع نتيجة 0.5 عند أفضل نتيجة لكل نموذج في الجدول أو على بُعد 0.1 منها. تقل الفروق عن نقطة واحدة في متوسط الفئات على COCO val2017؛ أما على كاميرتك، فيعتمد حجم الفرق على مدى تكرار تداخل الصناديق من الفئة نفسها.

تأثير خفض عتبة IoU على التكرارات والأجسام المتجاورة#

تقيس NMS التداخل باستخدام التقاطع على الاتحاد: مساحة الجزء المشترك مقسومة على المساحة المجمّعة للصندوقين. وترتب الصناديق حسب الثقة، وتحتفظ بالأفضل، وتحذف كل صندوق آخر من الفئة نفسها تتجاوز قيمة IoU بينه وبينه العتبة. ثم تكرر العملية مع الصندوق التالي الذي لم يُحذف.

ولهذا الرقم الواحد تأثيران متعاكسان:

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

يوضح درس كشف الأجسام في Academy التأثير على صورة الاختبار القياسية bus.jpg باستخدام YOLO26n:

في هذه الصورة، لا يتغير العدد عند الانتقال من 0.5 إلى 0.3، بينما يؤدي رفع القيمة إلى 0.95 إلى تمرير ثلاثة صناديق إضافية. ويختلف التأثير باختلاف لقطاتك، لذا اختبر عدة عتبات على إطاراتك.

يؤثر إعدادان مرتبطان في المخرجات نفسها. يكبت agnostic_nms=True الصناديق المتداخلة بين الفئات أيضًا، ما يفيد عندما يحصل جسم واحد على تسميتين مثل سيارة وشاحنة. ويحدد max_det الحد الأقصى لعدد الاكتشافات في الصورة عند 300 افتراضيًا، لذا قد يلزم رفعه في المشاهد شديدة الكثافة.

الثقة مقابل عتبة IoU في YOLO: متى تغيّر كلًا منهما#

يجيب conf وiou عن سؤالين مختلفين. يسأل conf عما إذا كانت الثقة في الصندوق كافية للاحتفاظ به؛ بينما يسأل iou عما إذا كان صندوقان محتفظ بهما يعودان في الحقيقة إلى جسم واحد. غيّر conf أولًا عندما تكون المشكلة في الصناديق الضعيفة أو غير الصحيحة، ولا تغيّر iou إلا عندما تكون المشكلة في التداخل. درجة الثقة في YOLO26 هي درجة ترتيب وليست احتمالًا معايرًا، لذا اختر القيمتين بالاستناد إلى بيانات التحقق بدلًا من الحدس.

اختر الإعداد المناسب استنادًا إلى العَرَض الظاهر في المخرجات:

• يظهر للجسم نفسه صندوقان. اخفض iou، مثلًا من 0.5 إلى 0.4.
• يختفي أحد جسمين متجاورين وسط الحشود. ارفع iou، مثلًا من 0.5 إلى 0.7، وهي القيمة الافتراضية القديمة.
• تظهر صناديق على الخلفية. ارفع conf أولًا؛ فتغيير iou لا يؤثر إلا في الصناديق المتداخلة.
• لا تُكتشف أجسام حقيقية على الإطلاق. اخفض conf، وراجع دليل المشكلات الشائعة إذا لم يُصدر النموذج أي اكتشاف.
• تُبلغ عن الأعداد. اختبر نطاقًا من القيمتين على إطارات كاميرا العد، واحتفظ بالزوج الذي يحقق أقل خطأ في العد.

لا تقل أهمية هندسة الكاميرا عن المشهد نفسه. فعادةً ما يفصل المنظور المرتفع من الأعلى الأشخاص والمركبات، فيقل تداخل صناديقهم وتصبح العتبة الأقل أكثر ملاءمة. أما الكاميرا المنخفضة والمائلة على امتداد طابور أو مسار أو ممر، فتجعل الأجسام متراصة بعضها خلف بعض، وقد تتداخل صناديق الأجسام المختلفة بأكثر من 50%. في هذه الحالة، قد يحافظ رفع iou مجددًا باتجاه 0.7 على الاكتشافات الحقيقية.

للتوضيح. تؤدي المناظير المائلة للأجسام المصطفة إلى تداخل شديد بين صناديق الأجسام المختلفة، وهي الحالة التي تحافظ فيها قيمة iou الأعلى على الأجسام المتجاورة الحقيقية.

اضبط عتبة IoU على كاميرتك#

قد تفشل عتبة تبدو مناسبة في صورة واحدة عند استخدامها مع كاميرا مباشرة. اضبطها على بضع عشرات من الإطارات الملتقطة بكاميرا النشر، وبدقة العرض والزاوية اللتين ستستخدمهما، ثم قارن النتائج بما يعدّه شخص بعينه.

لإجراء تجربة أولية بلا كتابة شيفرة، حمّل بعض هذه الإطارات إلى علامة تبويب Predict في صفحة نموذج YOLO26n على منصة Ultralytics، وحرّك منزلقَي الثقة وIoU لرصد التكرارات والأجسام المتجاورة التي لم تُكتشف. ثم نفّذ الاختبار الوارد أدناه لاختيار قيم يمكنك تبريرها.

1. اجمع الإطارات. احفظ إطارات من الكاميرا الفعلية تغطي أكثر الأوقات ازدحامًا وأهدأها. وإذا كنت تضع تسميات عليها بالفعل في منصة Ultralytics، فاستخدم إصدارًا من مجموعة البيانات بوصفه مجموعة مرجعية.
2. أحصِ يدويًا. دوّن العدد الحقيقي للأجسام المستهدفة في كل إطار، أو ضع تسميات كاملة عليها إذا كنت تخطط للتدريب.
3. اختبر conf وiou معًا. شغّل النص البرمجي أدناه، الذي يقارن عدد الأجسام في كل إطار بالعدد الذي سجلته.
4. اختر الزوج الذي يحقق أقل متوسط للخطأ، ثم افتح الإطارات التي لا يزال أداؤه فيها ضعيفًا: تعني التكرارات خفض iou، ويعني دمج الأجسام المتجاورة رفعه. قد يبدو العدد صحيحًا إذا عادل جسم مكرر جسمًا فائتًا في الإطار نفسه، لذا تحقق أيضًا من الصناديق المرسومة، وأكّد الزوج المختار على بضعة إطارات لم تستخدمها في الضبط.
5. اضبط القيمتين صراحةً في كل موضع يعمل فيه النموذج، بما في ذلك عمليات التصدير المضمّن فيها NMS، حتى لا يؤدي أي تغيير مستقبلي في القيم الافتراضية إلى تغيير نتائجك.

from pathlib import Path

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # or your trained weights
hand_counts = {"frame_001.jpg": 12, "frame_002.jpg": 7}  # your count per frame
frames = [str(Path("path/to/camera_frames") / name) for name in hand_counts]

for conf in (0.25, 0.35, 0.5):
    for iou in (0.3, 0.4, 0.5, 0.6, 0.7):
        errors = []
        print(f"conf={conf} iou={iou}")
        for r in model.predict(frames, conf=conf, iou=iou, classes=[0], stream=True, verbose=False):
            name = Path(r.path).name
            predicted, expected = len(r.boxes), hand_counts[name]
            errors.append(abs(predicted - expected))
            print(f"  {name}: predicted {predicted}, hand count {expected}")
        print(f"  mean count error {sum(errors) / len(errors):.2f}")

يمنع متوسط الخطأ المطلق التجاوز في العد في إطار من إلغاء النقص في العد في إطار آخر. وتقيّد الوسيطة classes=[0] العد بفئة واحدة (person في COCO)؛ استخدم فهرس الفئة الخاص بك. ثم استخدم القيم المضبوطة في التتبع والتصدير:

# ⁨يطبّق التتبع عتبة NMS الخاصة بالكاشف قبل المطابقة⁩
results = model.track("path/to/video.mp4", conf=0.35, iou=0.6, persist=True)

# ⁨ضمّن NMS في عملية تصدير جديدة باستخدام العتبتين المضبوطتين⁩
model.export(format="onnx", nms=True, conf=0.35, iou=0.6)

في التتبع، تكتسب العتبة المستقرة أهمية مضاعفة. فقد يبدأ صندوق مكرر نجا من NMS معرّف مسار ثانٍ للجسم نفسه، وقد ينقطع ارتباط جسم مجاور حُذف في ذلك الإطار؛ أما في الكشف وOBB، فيمكن لمتعقب TrackTrack الافتراضي استعادة بعض هذه المرشحات عبر تمريرة أقل تشددًا خاصة به. ويتناول درس التتبع حول ByteTrack وBoT-SORT عتبات المطابقة الخاصة بالمتعقب، وهي مستقلة عن iou.

هل تقدّم النموذج من نقطة نهاية مخصصة على منصة Ultralytics؟ مرّر conf وiou المضبوطتين في كل طلب صراحةً.

لماذا تظل عتبة IoU للتحقق عند 0.7#

إذا أجريت التحقق باستخدام model.val()، فلم يتغير شيء: فما زال المدقّق يملأ iou=0.7. يعمل التحقق على قائمة الصناديق المرتبة كاملةً عند قيمة ثقة منخفضة جدًا، حيث تحافظ العتبة المتساهلة على المرشحين المتداخلين ليتاح استخدامها في المطابقة مع التسميات. كما أن الإبقاء على 0.7 يعني أن قيم mAP التي نشرتها بالفعل، وتلك الواردة في جداول النماذج لدينا، تظل قابلة للمقارنة مع عمليات التشغيل الجديدة.

تغيرت أيضًا إحدى التفاصيل المرتبطة بالتحقق. فمصفوفة الالتباس تطابق الآن التنبؤات مع التسميات عند IoU بقيمة 0.5 بدلًا من 0.45، وهي عتبة IoU نفسها المستخدمة في mAP₅₀. هذه عتبة مطابقة وليست NMS: فهي تحدد الصناديق التي تُحسب صحيحة، لا الصناديق التي تبقى. ويشرح دليل مقاييس الأداء كيفية حساب كل مقياس.

يحسّن إعداد التحقق مقياسًا مرتبًا على آلاف الصناديق ذات الثقة المنخفضة، لا على حفنة الصناديق التي يتصرف تطبيقك بناءً عليها. إذا أردت تجربة 0.7 في بيئة الإنتاج، فأدرجها في اختبار الكاميرا أعلاه ودع خطأ العد يحدد النتيجة.

متى تستخدم YOLO26 من دون NMS#

يدرّب Ultralytics YOLO26 رأسين في الوقت نفسه. يقترح الرأس أحادي إلى متعدد عدة مرشحين لكل جسم ويعتمد على NMS، وهو ما يستخدمه التنبؤ والتحقق افتراضيًا. أما الرأس أحادي إلى أحادي فيتعلّم إصدار تنبؤ واحد لكل جسم، لذا لا يحتاج إلى كبت IoU. مرّر nms=False لاستخدامه، كما يوضح دليل الكشف الشامل من طرف إلى طرف:

results = model.predict("image.jpg", nms=False)  # ⁨رأس أحادي إلى أحادي بلا NMS⁩
model.export(format="onnx", nms=False)  # outputs (N, 300, 6): xyxy, confidence, class

باستخدام nms=False، لا يطبّق الكاشف أي كبت لـIoU، لذا لا يكون لـiou ما يؤثر فيه. ولا ترشح المخرجات إلا conf وclasses وmax_det. أما مع agnostic_nms=True، فيحتفظ كل مرشح بالفئة ذات أعلى درجة فقط؛ وتظل الصناديق المختلفة بلا كبت لـIoU. ومع ذلك، يمكن لمتعقب مثل TrackTrack أن يكبت بنفسه بدء مسارات مكررة.

المقابل هو انخفاض طفيف في الدقة. فعلى COCO val2017 بدقة 640 بكسل، وبنموذج واحد ومقياس واحد، يحقق YOLO26n قيمة 40.9 mAP_50-95 مع NMS و40.1 من طرف إلى طرف؛ بينما يحقق YOLO26x قيمتي 57.5 و56.9، وفقًا لوثائق نماذج YOLO26. وفي المقابل، يُصدر التصدير المدعوم الاكتشافات النهائية، فلا تحتاج إلى تنفيذ الكبت أو ضبطه على الجهاز المستهدف.

للتوضيح. منظور علوي لسيارات متوقفة، لكل منها صندوق منفصل.

اختر الرأس الخالي من NMS عندما:

• تنشر على بيئة تشغيل طرفية يكون فيها تنفيذ NMS صعبًا أو بطيئًا. لا تدعمها جميع التنسيقات: فبعضها يعود إلى مخرجات الرأس أحادي إلى متعدد أو يتطلب NMS، لذا اقرأ تحذيرات التصدير وقارن النتائج على بيئة التشغيل المستهدفة. وللاطلاع على جانب النشر، راجع كيف يغيّر الرأس الخالي من NMS في YOLO26 عملية النشر.
• تكون المشاهد لديك مزدحمة ولا توجد قيمة واحدة لـiou تزيل التكرارات وتحافظ على الأجسام المتجاورة معًا في إطارات كاميرتك.
• تريد تقليل المكونات المتغيرة بين النموذج والشيفرة، دون الحاجة إلى ضبط NMS خاص ببيئة التشغيل.

أبقِ مسار NMS الافتراضي عندما تكون كل زيادة طفيفة في mAP أهم من بساطة النشر، أو عندما تستخدم YOLO11 أو YOLOv8، اللذين لا يملكان رأسًا أحاديًا إلى أحادي.

أيًا كان الرأس الذي تنشره، فتحقق من الترخيص قبل إدراج النموذج في منتج. تتوفر نماذج Ultralytics YOLO بموجب AGPL-3.0 وترخيص Ultralytics Enterprise؛ وتتطلب عمليات النشر الاحتكارية التي لا يمكنها الوفاء بالتزامات AGPL-3.0 الحصول على ترخيص Enterprise.

من ينبغي له تغيير إعداد iou#

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

إذا كنت تمرر iou صراحةً بالفعل، فلن يتغير شيء لديك. وإذا لم تختر قيمة عن قصد قط، فالقيمة الافتراضية الجديدة نقطة بداية مبنية على القياس، وسيبين لك اختبار سريع على إطاراتك ما إذا كان عليك الإبقاء عليها. وينبغي للفرق التي تنشئ مسارات عمل جديدة للأجهزة الطرفية باستخدام YOLO26 أن تختبر nms=False أولًا على بيئة التشغيل المستهدفة. لاختبار العتبات على إطارات من كاميرتك، افتح صفحة نموذج YOLO26n على منصة Ultralytics واختر Predict؛ وإذا كانت مشاهدك تتطلب نموذجًا مدرّبًا على بياناتك، فيمكنك تدريبه على منصة Ultralytics واختباره في علامة تبويب Predict ضمن صفحة النموذج المدرّب. وترد جميع وسائط الاستدلال في مرجع إعدادات التنبؤ.