Come regolare la soglia IoU di NMS in Ultralytics YOLO

La soglia IoU determina quando un rilevatore considera due riquadri sovrapposti come lo stesso oggetto. In Ultralytics YOLO, la soppressione non massimale (NMS) mantiene il riquadro con la confidenza più alta ed elimina ogni altro riquadro della stessa classe che si sovrappone a esso più di iou. Se la imposti troppo in alto, un oggetto avrà due riquadri; se la imposti troppo in basso, il secondo di due oggetti affiancati scomparirà.

A partire da Ultralytics 8.4.208, rilasciato l'8 novembre 2026, la predizione e il tracking usano 0.5 come valore predefinito invece di iou=0.5, mentre la validazione mantiene 0.7. Questa guida spiega che cosa è cambiato e perché, come la soglia interagisce con conf, come regolare entrambi i valori per la tua telecamera e quando eliminare del tutto NMS con la testa end-to-end di YOLO26.

Ultralytics YOLO ora esegue predizioni e tracking con IoU 0.5 come valore predefinito#

Se non passi iou e si applica NMS, ora la modalità predict e la modalità track usano 0.5. Qualsiasi valore passato in modo esplicito ha comunque la precedenza, quindi le pipeline che già impostano iou si comportano esattamente come prima. Il riferimento alle impostazioni di predict mostra il nuovo valore predefinito accanto a conf=0.25.

Questi flussi di lavoro adottano 0.5 quando iou non è impostato:

• Predizione e tracking con Python e CLI, inclusi i predittori riutilizzati e un iou=None esplicito.
• Soluzioni come il conteggio degli oggetti, la gestione delle code e TrackZone, che ereditano il valore del predittore.
• Nuove esportazioni con NMS incorporata (nms=True). Un modello esportato in precedenza mantiene il valore predefinito impostato al momento dell'esportazione.
• Ultralytics Platform, dove la documentazione sull'inferenza indica il cursore IoU e il campo iou impostati a 0.5 sugli endpoint distribuiti.
• Pacchetti per dispositivi mobili: il pacchetto Ultralytics YOLO per iOS usa 0.5 come valore predefinito nella versione 8.9.20, così come il plugin Flutter nella versione 0.7.2; i valori predefiniti negli app store dipendono dalla versione installata.

Due impostazioni restano intenzionalmente a 0.7: la validazione, così i valori mAP pubblicati non cambiano, e i predittori SAM, SAM 2, SAM 3 e FastSAM, le cui maschere fortemente sovrapposte non rientravano nella misurazione.

La scheda Predict di un modello per la sicurezza in magazzino in Ultralytics Platform, durante una predizione reale. Il cursore IoU ora parte da 0.5.

Perché il vecchio valore predefinito 0.7 non era adatto alla predizione#

Prima di questa versione, iou aveva un unico valore predefinito condiviso da predict e val. Secondo PR #27084, quel valore è passato da 0.6 a 0.7 con una modifica di una sola riga nella configurazione, nel dicembre 2022, all'interno di una richiesta pull non correlata sul dataloader; in seguito le app per dispositivi mobili lo hanno adottato solo per coerenza.

Le due modalità hanno funzioni diverse:

• La validazione valuta l'intero elenco ordinato di riquadri, fino a una confidenza di 0.001. Di solito un duplicato ha una posizione più bassa rispetto al riquadro corretto e incide poco, mentre la soppressione di un oggetto reale riduce il richiamo a ogni soglia. Una soglia permissiva conserva i candidati sovrapposti per la valutazione.
• La predizione restituisce un insieme finale di riquadri con conf=0.25. Ogni duplicato lasciato passare da NMS è un falso positivo visibile nell'output, nel conteggio o nell'avviso. Con 0.7, sopravvivono entrambi i riquadri della stessa classe che si sovrappongono fino al 70%.

conf aveva già valori predefiniti separati proprio per questo motivo: 0.25 per la predizione e 0.001 per la validazione. Ora iou segue lo stesso schema.

Che cosa ha mostrato la misurazione#

PR #27084 riporta i seguenti punteggi F1 di rilevamento con diverse soglie NMS su COCO val2017, usando una RTX PRO 6000. F1 riassume la precisione e il richiamo; i valori qui sotto sono medie per classe, espresse in percentuale:

Ogni modello ottiene un punteggio più alto con 0.45 o 0.5 che con 0.7, e 0.5 è pari o dista al massimo 0.1 dal risultato migliore di ciascun modello nella tabella. Le differenze sono inferiori a un punto nella media per classe di COCO val2017; con la tua telecamera, l'entità della differenza dipende dalla frequenza con cui si sovrappongono riquadri della stessa classe.

Effetti di una soglia IoU più bassa sui duplicati e sugli oggetti vicini#

NMS misura la sovrapposizione con l'intersezione sull'unione: l'area condivisa divisa per l'area complessiva di due riquadri. Ordina i riquadri per confidenza, mantiene il migliore ed elimina ogni altro riquadro della stessa classe la cui IoU con esso supera la soglia. Poi ripete l'operazione con il riquadro successivo tra quelli rimasti.

Questo singolo valore agisce in entrambe le direzioni:

• Un valore più basso di iou elimina più riquadri sovrapposti. I duplicati dello stesso oggetto scompaiono più facilmente, ma due oggetti reali molto sovrapposti, come auto paraurti contro paraurti, pacchi su un nastro trasportatore o persone in coda, possono essere ridotti a uno.
• Un valore più alto di iou mantiene più riquadri sovrapposti. Gli oggetti vicini sopravvivono, ma anche i riquadri quasi duplicati dello stesso oggetto.

La lezione di object detection dell'Academy mostra l'effetto sull'immagine di test standard bus.jpg con YOLO26n:

In questa immagine, passare da 0.5 a 0.3 non cambia il conteggio, mentre salire a 0.95 lascia passare altri tre riquadri. L'effetto varierà nelle tue riprese, quindi prova diverse soglie sui tuoi fotogrammi.

Due impostazioni correlate influenzano lo stesso output. agnostic_nms=True sopprime anche i riquadri sovrapposti tra classi diverse, utile quando un oggetto riceve due etichette, come auto e camion. max_det limita a 300 il numero di rilevamenti per immagine come valore predefinito, quindi potrebbe essere necessario aumentarlo nelle scene molto dense.

Confidenza e soglia IoU in YOLO: quando modificare ciascuna#

conf e iou rispondono a domande diverse. conf chiede se la confidenza di un riquadro è sufficiente per mantenerlo; iou chiede se due riquadri mantenuti rappresentano davvero un solo oggetto. Modifica prima conf se il problema sono riquadri deboli o spurii, e modifica iou solo se il problema è la sovrapposizione. Il punteggio di confidenza in YOLO26 è un punteggio di ordinamento, non una probabilità calibrata, quindi scegli entrambi i valori in base ai dati di validazione, non all'intuizione.

Scegli il parametro in base al sintomo nell'output:

• Lo stesso oggetto ha due riquadri. Abbassa iou, per esempio da 0.5 a 0.4.
• Uno dei due oggetti vicini scompare tra la folla. Alza iou, per esempio da 0.5 a 0.7, il vecchio valore predefinito.
• Compaiono riquadri sullo sfondo. Alza prima conf; modificare iou influisce solo sui riquadri sovrapposti.
• Gli oggetti reali non vengono rilevati. Abbassa conf e consulta la guida ai problemi comuni se il modello non rileva mai nulla.
• Devi riportare i conteggi. Prova diverse combinazioni sui fotogrammi della telecamera usata per il conteggio e mantieni la coppia con l'errore di conteggio minore.

La geometria della telecamera conta quanto la scena. Una visuale dall'alto tende a separare persone e veicoli, quindi i loro riquadri si sovrappongono meno e una soglia più bassa è più pratica. Una telecamera bassa e obliqua, lungo una coda, una corsia o un corridoio, sovrappone gli oggetti l'uno dietro l'altro; i riquadri di oggetti diversi possono sovrapporsi ben oltre il 50%. In questo caso, alzare iou verso 0.7 può preservare i rilevamenti reali.

A scopo illustrativo. Le visuali oblique di oggetti in coda producono riquadri molto sovrapposti per oggetti diversi: è il caso in cui una iou più alta mantiene gli oggetti vicini reali.

Regola la soglia IoU sulla tua telecamera#

Una soglia che sembra corretta su una singola immagine può non funzionare con una telecamera in diretta. Regolala su alcune decine di fotogrammi della telecamera di distribuzione, alla risoluzione e all'angolazione che userai, e confronta i risultati con il conteggio effettuato a occhio da una persona.

Per una prima prova senza codice, carica alcuni di questi fotogrammi nella scheda Predict della pagina del modello YOLO26n in Ultralytics Platform e sposta i cursori di confidenza e IoU per individuare i duplicati e gli oggetti vicini mancanti. Poi esegui la prova descritta sotto per scegliere valori che puoi motivare.

1. Raccogli i fotogrammi. Salva fotogrammi dalla telecamera reale che coprano i momenti più affollati e quelli più tranquilli. Se li annoti già in Ultralytics Platform, usa una versione del dataset come insieme di riferimento.
2. Conta a mano. Annota il numero reale di oggetti di interesse in ogni fotogramma, oppure etichettali tutti se prevedi di addestrare il modello.
3. Prova insieme conf e iou. Esegui lo script qui sotto, che confronta il conteggio di ogni fotogramma con il tuo.
4. Scegli la coppia con l'errore medio minore, poi apri i fotogrammi in cui il modello continua a sbagliare: se ci sono duplicati, abbassa iou; se gli oggetti vicini vengono uniti, alzalo. Un conteggio può sembrare corretto anche quando un duplicato e un mancato rilevamento si compensano nello stesso fotogramma; controlla anche i riquadri disegnati e verifica la coppia scelta su alcuni fotogrammi che non hai usato per la regolazione.
5. Imposta esplicitamente entrambi i valori ovunque venga eseguito il modello, comprese le esportazioni con NMS incorporata, così eventuali modifiche future ai valori predefiniti non altereranno i risultati.

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'errore assoluto medio impedisce che i conteggi eccessivi di un fotogramma compensino quelli insufficienti di un altro. L'argomento classes=[0] limita il conteggio a una sola classe (person in COCO); usa l'indice della tua classe. Poi imposta i valori regolati per il tracking e l'esportazione:

# La soglia NMS del rilevatore viene applicata prima dell'associazione nel tracking
results = model.track("path/to/video.mp4", conf=0.35, iou=0.6, persist=True)

# Incorpora NMS in una nuova esportazione con entrambe le soglie regolate
model.export(format="onnx", nms=True, conf=0.35, iou=0.6)

Per il tracking, una soglia stabile è importante per due motivi. Un riquadro duplicato che supera NMS può avviare un secondo ID di traccia sullo stesso oggetto; un oggetto vicino soppresso può invece essere escluso dall'associazione per quel fotogramma. Per il rilevamento e l'OBB, il tracker TrackTrack predefinito può recuperare alcuni di questi candidati con un proprio passaggio più permissivo. La nostra lezione sul tracking con ByteTrack e BoT-SORT illustra le soglie di corrispondenza del tracker, che sono separate da iou.

Distribuisci il modello da un endpoint dedicato in Ultralytics Platform? Passa esplicitamente conf e iou regolati in ogni richiesta.

Perché la validazione mantiene IoU 0.7#

Se esegui la validazione con model.val(), non cambia nulla: il validatore imposta ancora iou=0.7. La validazione usa l'intero elenco ordinato di riquadri con una confidenza molto bassa, dove una soglia permissiva mantiene disponibili i candidati sovrapposti per il confronto con le etichette. Mantenere 0.7 significa anche che i valori mAP che hai già pubblicato, e quelli nelle nostre tabelle dei modelli, restano confrontabili con i nuovi risultati.

È cambiato un dettaglio correlato della validazione. Ora la matrice di confusione abbina le predizioni alle etichette con IoU 0.5 invece di 0.45, la stessa soglia IoU usata per mAP₅₀. È una soglia di corrispondenza, non di NMS: determina quali riquadri contano come corretti, non quali riquadri sopravvivono. La guida alle metriche di prestazione spiega come viene calcolata ogni metrica.

L'impostazione di validazione ottimizza una metrica basata su un ordinamento che comprende migliaia di riquadri a bassa confidenza, non i pochi riquadri su cui agisce la tua applicazione. Se vuoi provare 0.7 in produzione, includilo nella prova con la telecamera descritta sopra e lascia che decida l'errore di conteggio.

Quando usare YOLO26 senza NMS#

Ultralytics YOLO26 addestra due teste contemporaneamente. La testa one-to-many propone diversi candidati per oggetto e usa NMS; è quella impiegata per impostazione predefinita da predizione e validazione. La testa one-to-one impara a produrre una singola predizione per oggetto, quindi non ha bisogno della soppressione IoU. Passa nms=False per usarla, come mostra la guida al rilevamento end-to-end:

results = model.predict("image.jpg", nms=False)  # Testa one-to-one senza NMS
model.export(format="onnx", nms=False)  # output (N, 300, 6): xyxy, confidenza, classe

Con nms=False, il rilevatore non applica alcuna soppressione IoU, quindi iou non ha alcun effetto. Solo conf, classes e max_det filtrano l'output. Con agnostic_nms=True, ogni candidato mantiene solo la classe con il punteggio più alto; i riquadri distinti non vengono comunque soppressi in base alla IoU. Un tracker come TrackTrack può comunque sopprimere autonomamente gli avvii di tracce duplicati.

Il compromesso è una lieve perdita di accuratezza. Su COCO val2017 a 640 pixel, con un singolo modello e una singola scala, YOLO26n ottiene 40.9 mAP_50-95 con NMS e 40.1 end-to-end; YOLO26x ottiene 57.5 e 56.9, secondo la documentazione dei modelli YOLO26. In compenso, un'esportazione supportata restituisce i rilevamenti finali, così non devi implementare né regolare la soppressione sul dispositivo di destinazione.

A scopo illustrativo. Vista dall'alto di auto parcheggiate, ognuna con un riquadro separato.

Scegli la testa senza NMS quando:

• Distribuisci su un runtime edge in cui implementare NMS è complicato o lento. Non tutti i formati la supportano: alcuni usano come alternativa gli output one-to-many o richiedono NMS, quindi leggi gli avvisi di esportazione e confronta i risultati sul runtime di destinazione. Per la distribuzione, consulta come la testa senza NMS di YOLO26 modifica la distribuzione.
• Le tue scene sono affollate e nessun singolo iou riesce sia a rimuovere i duplicati sia a mantenere gli oggetti vicini nei fotogrammi della tua telecamera.
• Vuoi ridurre il numero di componenti tra modello e codice, senza dover configurare NMS specifiche per il runtime.

Mantieni il percorso NMS predefinito quando l'ultimo decimale di mAP conta più della semplicità di distribuzione, oppure quando usi YOLO11 o YOLOv8, che non hanno una testa one-to-one.

Qualunque testa tu distribuisca, controlla la licenza prima di integrare il modello in un prodotto. I modelli Ultralytics YOLO sono disponibili con licenza AGPL-3.0 e con una licenza Ultralytics Enterprise; le distribuzioni proprietarie che non possono rispettare gli obblighi della AGPL-3.0 richiedono la licenza Enterprise.

Chi dovrebbe modificare l'impostazione iou#

Se ti affidi al valore predefinito e i risultati sembravano corretti con 0.7, ricontrollali dopo l'aggiornamento: aspettati meno riquadri duplicati e, nelle scene affollate e oblique, la possibile perdita occasionale di un oggetto vicino. Se conti gli oggetti, confronta i conteggi prima e dopo su alcuni fotogrammi noti.

Se passi già iou in modo esplicito, per te non cambia nulla. Se non hai mai scelto un valore consapevolmente, il nuovo valore predefinito è un punto di partenza misurato e una breve prova sui tuoi fotogrammi ti dirà se mantenerlo. I team che creano nuove pipeline edge con YOLO26 dovrebbero prima testare nms=False sul runtime di destinazione. Per provare le soglie sui fotogrammi della tua telecamera, apri la pagina del modello YOLO26n in Ultralytics Platform e seleziona Predict; se le tue scene richiedono un modello addestrato sui tuoi dati, puoi addestrarlo in Ultralytics Platform e provarlo nella scheda Predict della pagina del modello addestrato. Tutti gli argomenti di inferenza sono elencati nel riferimento alle impostazioni di predict.