Comment régler le seuil IoU du NMS dans Ultralytics YOLO

Le seuil IoU détermine à partir de quel degré de chevauchement un détecteur considère deux boîtes comme désignant le même objet. Dans Ultralytics YOLO, la suppression non maximale (NMS) conserve la boîte ayant le score de confiance le plus élevé et supprime toute autre boîte de la même classe dont le chevauchement avec elle dépasse iou. Si tu règles le seuil trop haut, un objet aura deux boîtes ; si tu le règles trop bas, le deuxième de deux objets côte à côte disparaîtra.

Depuis Ultralytics 8.4.208, publié le 8 novembre 2026, la prédiction et le suivi utilisent désormais iou=0.5 au lieu de 0.7 par défaut, tandis que la validation reste à 0.7. Ce guide explique ce qui a changé et pourquoi, comment le seuil interagit avec conf, comment régler les deux seuils pour ta caméra et quand supprimer complètement le NMS avec la tête de bout en bout de YOLO26.

Ultralytics YOLO utilise désormais IoU 0,5 par défaut pour la prédiction et le suivi#

Quand tu ne spécifies pas iou et que le NMS s'applique, le mode predict et le mode track utilisent désormais 0,5. Toute valeur que tu spécifies explicitement reste prioritaire : les pipelines qui définissent déjà iou fonctionnent donc exactement comme avant. La référence des paramètres de prédiction indique la nouvelle valeur par défaut à côté de conf=0.25.

Ces flux de travail adoptent la valeur 0,5 lorsque iou n'est pas défini :

• Prédiction et suivi avec Python et la CLI, y compris les prédicteurs réutilisés et un iou=None explicite.
• Solutions telles que le comptage d'objets, la gestion des files d'attente et TrackZone, qui héritent de la valeur du prédicteur.
• Nouveaux exports avec NMS intégré (nms=True). Un modèle exporté auparavant conserve la valeur par défaut de son export.
• Ultralytics Platform, dont la documentation sur l'inférence indique le curseur IoU et le champ iou à 0,5 sur les points de terminaison déployés.
• Packages mobiles : le package Ultralytics YOLO pour iOS utilise 0,5 par défaut depuis la version 8.9.20, tout comme le plugin Flutter depuis la version 0.7.2 ; les valeurs par défaut des boutiques d'applications dépendent de la version installée.

Deux éléments restent volontairement à 0,7 : la validation, afin que les mAP publiés ne changent pas, et les prédicteurs SAM, SAM 2, SAM 3 et FastSAM, dont les masques très chevauchants n'ont pas été pris en compte dans les mesures.

Onglet Predict d'un modèle de sécurité d'entrepôt dans Ultralytics Platform, exécutant une véritable prédiction. Son curseur IoU démarre désormais à 0,5.

Pourquoi l'ancienne valeur par défaut de 0,7 ne convenait pas à la prédiction#

Avant cette version, iou avait une valeur par défaut unique, partagée entre predict et val. Selon la PR #27084, cette valeur est passée de 0,6 à 0,7 à la suite d'une modification d'une ligne de configuration en décembre 2022, dans une pull request sans rapport sur le chargeur de données ; les applications mobiles l'ont ensuite adoptée par souci de cohérence.

Les deux modes ont des fonctions différentes :

• La validation évalue toute la liste de boîtes classées, jusqu'à un score de confiance de 0,001. Une boîte en double est généralement moins bien classée que la vraie boîte et a peu d'impact, tandis qu'un objet réel supprimé réduit le rappel à chaque seuil. Un seuil permissif conserve les candidats qui se chevauchent pour l'évaluation.
• La prédiction renvoie un ensemble final de boîtes avec conf=0.25. Chaque doublon que le NMS laisse passer devient un faux positif visible dans ta sortie, ton décompte ou ton alerte. À 0,7, deux boîtes de la même classe qui se chevauchent jusqu'à 70 % sont toutes deux conservées.

conf avait déjà des valeurs par défaut distinctes pour cette raison précise : 0,25 pour la prédiction et 0,001 pour la validation. iou suit désormais le même principe.

Ce que les mesures ont montré#

La PR #27084 présente les scores F1 de détection suivants pour différents seuils NMS sur COCO val2017, avec une RTX PRO 6000. Le F1 synthétise la précision et le rappel ; les valeurs ci-dessous sont des moyennes par classe, exprimées en pourcentage :

Chaque modèle obtient un meilleur score à 0,45 ou 0,5 qu'à 0,7, et le score à 0,5 est au maximum à 0,1 point du meilleur résultat de chaque modèle dans le tableau. Les écarts sont inférieurs à un point sur la moyenne par classe de COCO val2017 ; avec ta propre caméra, l'ampleur de l'écart dépend de la fréquence à laquelle les boîtes de même classe se chevauchent.

Effet d'un seuil IoU plus bas sur les doublons et les objets proches#

Le NMS mesure le chevauchement avec l'intersection sur union : la surface commune divisée par la surface combinée de deux boîtes. Il classe les boîtes par score de confiance, conserve la meilleure et supprime toute autre boîte de la même classe dont l'IoU avec celle-ci dépasse le seuil. Il recommence ensuite avec la boîte suivante parmi celles qui restent.

Cette seule valeur a deux effets opposés :

• Un iou plus bas supprime davantage de boîtes qui se chevauchent. Les doublons sur un même objet disparaissent plus vite, mais deux objets réels qui se chevauchent fortement — comme des voitures pare-chocs contre pare-chocs, des colis sur un convoyeur ou des personnes dans une file — peuvent être réduits à un seul.
• Un iou plus élevé conserve davantage de boîtes qui se chevauchent. Les objets proches sont conservés, mais les boîtes presque identiques d'un même objet le sont aussi.

La leçon de l'Academy sur la détection d'objets montre l'effet sur l'image de test standard bus.jpg avec YOLO26n :

Sur cette image, passer de 0,5 à 0,3 ne change pas le décompte, tandis que passer à 0,95 laisse passer trois boîtes supplémentaires. L'effet sera différent sur tes séquences vidéo : teste donc plusieurs seuils sur tes propres images.

Deux paramètres connexes façonnent la même sortie. agnostic_nms=True supprime également les boîtes qui se chevauchent entre classes, ce qui est utile lorsqu'un objet reçoit deux étiquettes, comme voiture et camion. max_det limite par défaut les détections à 300 par image ; il peut donc être nécessaire d'augmenter cette valeur pour les scènes très denses.

Confiance et seuil IoU dans YOLO : quand modifier chacun#

conf et iou répondent à des questions différentes. conf détermine si une boîte est assez fiable pour être conservée ; iou détermine si deux boîtes conservées représentent en réalité un seul objet. Modifie d'abord conf si ton problème concerne des boîtes peu fiables ou parasites, et ne modifie iou que si le problème est le chevauchement. Le score de confiance dans YOLO26 est un score de classement, pas une probabilité calibrée : choisis donc les deux valeurs à partir de données de validation plutôt que de ton intuition.

Choisis le paramètre à modifier en fonction du symptôme dans ta sortie :

• Le même objet reçoit deux boîtes. Réduis iou, par exemple de 0,5 à 0,4.
• L'un de deux objets proches disparaît dans une foule. Augmente iou, par exemple de 0,5 à 0,7, l'ancienne valeur par défaut.
• Des boîtes apparaissent sur l'arrière-plan. Augmente d'abord conf ; modifier iou ne concerne que les boîtes qui se chevauchent.
• Des objets réels ne sont pas détectés du tout. Réduis conf et consulte le guide des problèmes courants si le modèle ne déclenche jamais de détection.
• Tu comptes des objets. Fais varier les deux paramètres sur des images de la caméra utilisée pour le comptage et conserve la paire qui minimise l'erreur de décompte.

La géométrie de la caméra compte autant que la scène. Une vue plongeante, prise de haut, tend à séparer les personnes et les véhicules : leurs boîtes se chevauchent moins, et un seuil plus bas est donc plus pratique. Une caméra basse et oblique dirigée le long d'une file, d'une voie ou d'une allée empile les objets les uns derrière les autres ; les boîtes d'objets différents peuvent alors se chevaucher bien au-delà de 50 %. Dans ce cas, augmenter iou vers 0,7 peut préserver de vraies détections.

Illustration. Les vues obliques d'objets en file produisent des boîtes très chevauchantes pour des objets différents : c'est le cas où un IoU plus élevé conserve les objets voisins réels.

Règle le seuil IoU pour ta propre caméra#

Un seuil qui semble convenir sur une image peut échouer avec une caméra en direct. Règle-le à partir de quelques dizaines d'images prises avec la caméra de déploiement, à la résolution et sous l'angle prévus, puis compare les résultats à ce qu'une personne compte à l'œil.

Pour un premier essai sans code, téléverse quelques-unes de ces images dans l'onglet Predict de la page du modèle YOLO26n dans Ultralytics Platform et déplace les curseurs de confiance et d'IoU pour repérer les doublons et les objets voisins manquants. Exécute ensuite le balayage ci-dessous pour choisir des valeurs que tu peux justifier.

1. Rassemble des images. Enregistre des images provenant de la vraie caméra, couvrant les moments les plus chargés et les plus calmes. Si tu les étiquettes déjà dans Ultralytics Platform, utilise une version du jeu de données comme référence.
2. Compte à la main. Note le nombre réel d'objets cibles dans chaque image, ou annote-les entièrement si tu prévois d'entraîner un modèle.
3. Fais varier conf et iou ensemble. Exécute le script ci-dessous, qui compare le décompte de chaque image au tien.
4. Choisis la paire qui minimise l'erreur moyenne, puis examine les images où elle échoue encore : en cas de doublons, réduis iou ; si des objets voisins sont fusionnés, augmente-le. Un décompte peut sembler correct alors qu'un doublon et une détection manquée s'annulent dans la même image : vérifie aussi les boîtes dessinées et confirme la paire choisie sur quelques images qui n'ont pas servi au réglage.
5. Définis explicitement les deux paramètres partout où le modèle est exécuté, y compris dans les exports avec NMS intégré, afin qu'un changement futur de valeur par défaut ne modifie jamais tes résultats.

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}")

L'erreur absolue moyenne empêche les surestimations d'une image de compenser les sous-estimations d'une autre. L'argument classes=[0] limite le décompte à une seule classe (person dans COCO) ; utilise l'indice de ta propre classe. Utilise ensuite les valeurs réglées pour le suivi et l'export :

# Le suivi applique le seuil NMS du détecteur avant l'association
results = model.track("path/to/video.mp4", conf=0.35, iou=0.6, persist=True)

# Intégrer le NMS dans un nouvel export avec les deux seuils réglés
model.export(format="onnx", nms=True, conf=0.35, iou=0.6)

Pour le suivi, un seuil stable compte à deux égards. Une boîte en double qui survit au NMS peut créer un deuxième ID de suivi pour le même objet, tandis qu'un objet voisin supprimé peut ne pas être associé pendant cette image ; pour la détection et OBB, le suiveur TrackTrack par défaut peut récupérer certains de ces candidats grâce à sa propre passe plus permissive. Notre leçon sur ByteTrack et BoT-SORT pour le suivi présente les seuils d'association propres au suiveur, qui sont distincts de iou.

Tu sers le modèle depuis un point de terminaison dédié dans Ultralytics Platform ? Spécifie explicitement conf et iou réglés dans chaque requête.

Pourquoi la validation reste à IoU 0,7#

Si tu valides avec model.val(), rien n'a changé : le validateur renseigne toujours iou=0.7. La validation s'appuie sur toute la liste classée des boîtes avec un score de confiance très faible, où un seuil permissif préserve les candidats qui se chevauchent pour les comparer aux étiquettes. Conserver 0,7 signifie aussi que les valeurs mAP déjà publiées, ainsi que celles de nos tableaux de modèles, restent comparables aux nouveaux résultats.

Un détail connexe de la validation a changé. La matrice de confusion associe désormais les prédictions aux étiquettes à IoU 0,5 au lieu de 0,45, soit le même seuil IoU que celui utilisé pour mAP₅₀. Il s'agit d'un seuil d'association, pas du NMS : il détermine quelles boîtes sont considérées comme correctes, et non quelles boîtes sont conservées. Le guide des métriques de performance explique le calcul de chaque métrique.

Le paramètre de validation optimise une métrique de classement sur des milliers de boîtes à faible confiance, et non sur les quelques boîtes auxquelles ton application réagit. Si tu veux essayer 0,7 en production, inclus cette valeur dans le balayage des images de caméra ci-dessus et laisse l'erreur de décompte décider.

Quand utiliser YOLO26 sans NMS#

Ultralytics YOLO26 entraîne deux têtes simultanément. La tête one-to-many propose plusieurs candidats par objet et dépend du NMS ; c'est celle qu'utilisent par défaut la prédiction et la validation. La tête one-to-one apprend à produire une seule prédiction par objet et n'a donc pas besoin de suppression IoU. Passe nms=False pour l'utiliser, comme l'explique le guide de détection de bout en bout :

results = model.predict("image.jpg", nms=False)  # Tête one-to-one sans NMS
model.export(format="onnx", nms=False)  # Sortie (N, 300, 6) : xyxy, confiance, classe

Avec nms=False, le détecteur n'applique aucune suppression IoU : iou n'a donc aucun effet. Seuls conf, classes et max_det filtrent la sortie. Avec agnostic_nms=True, chaque candidat ne conserve que sa classe ayant le score le plus élevé ; les boîtes distinctes ne font toujours l'objet d'aucune suppression IoU. Un suiveur tel que TrackTrack peut tout de même empêcher lui-même les démarrages de suivi en double.

Le compromis est une légère baisse de précision. Sur COCO val2017 à 640 pixels, avec un seul modèle et une seule échelle, YOLO26n obtient un mAP_50-95 de 40,9 avec NMS et de 40,1 de bout en bout ; YOLO26x obtient respectivement 57,5 et 56,9, selon la documentation des modèles YOLO26. En contrepartie, un export compatible produit les détections finales : tu n'as donc pas à implémenter ni à régler la suppression sur l'appareil cible.

Illustration. Vue plongeante de voitures garées, chacune avec sa propre boîte.

Choisis la tête sans NMS si :

• Tu déploies sur un environnement d'exécution en périphérie où l'implémentation du NMS est difficile ou lente. Tous les formats ne le prennent pas en charge : certains reviennent aux sorties one-to-many ou exigent le NMS ; lis donc les avertissements d'export et compare les résultats sur l'environnement d'exécution cible. Pour le déploiement, consulte l'effet de la tête sans NMS de YOLO26 sur le déploiement.
• Tes scènes sont encombrées et aucun iou ne permet à la fois de supprimer les doublons et de conserver les objets voisins sur les images de ta caméra.
• Tu veux réduire le nombre d'éléments intermédiaires entre le modèle et le code, sans NMS propre à l'environnement d'exécution à configurer.

Conserve le chemin NMS par défaut si chaque dernière fraction de mAP compte davantage que la simplicité du déploiement, ou si tu utilises YOLO11 ou YOLOv8, qui n'ont pas de tête one-to-one.

Quelle que soit la tête que tu déploies, vérifie la licence avant d'intégrer le modèle à un produit. Les modèles Ultralytics YOLO sont disponibles sous AGPL-3.0 et sous licence Ultralytics Enterprise ; les déploiements propriétaires qui ne peuvent pas respecter les obligations de l'AGPL-3.0 nécessitent la licence Enterprise.

Qui devrait modifier son réglage iou#

Si tu utilises la valeur par défaut et que tes résultats te semblaient corrects à 0,7, revérifie-les après la mise à niveau : tu devrais constater moins de boîtes en double et, dans les scènes obliques encombrées, la perte occasionnelle d'un objet voisin. Si tu comptes des objets, compare les décomptes avant et après sur quelques images connues.

Si tu spécifies déjà explicitement iou, rien ne change pour toi. Si tu n'as jamais choisi de valeur délibérément, la nouvelle valeur par défaut constitue un point de départ basé sur des mesures ; un bref balayage sur tes propres images te dira s'il faut la conserver. Les équipes qui créent de nouveaux pipelines en périphérie avec YOLO26 devraient d'abord tester nms=False sur leur environnement d'exécution cible. Pour tester les seuils sur des images de ta propre caméra, ouvre la page du modèle YOLO26n dans Ultralytics Platform et sélectionne Predict ; si tes scènes nécessitent un modèle entraîné avec tes propres données, tu peux l'entraîner dans Ultralytics Platform et le tester dans l'onglet Predict de la page de ton modèle entraîné. Tous les arguments d'inférence sont répertoriés dans la référence des paramètres de prédiction.