Como ajustar o limiar de IoU do NMS no Ultralytics YOLO

O limiar de IoU determina quando um detector considera que duas caixas sobrepostas representam o mesmo objeto. No Ultralytics YOLO, a supressão não máxima (NMS) mantém a caixa com a maior confiança e elimina qualquer outra caixa da mesma classe que se sobreponha a ela em mais de iou. Se definires um valor demasiado alto, um objeto terá duas caixas; se o definires demasiado baixo, o segundo de dois objetos lado a lado desaparecerá.

A partir do Ultralytics 8.4.208, lançado em 8 de novembro de 2026, a predição e o rastreamento usam 0.5 por padrão em vez de iou=0.5, enquanto a validação continua a usar 0.7. Este guia explica o que mudou e porquê, como o limiar interage com conf, como ajustar ambos para a tua câmara e quando eliminar completamente o NMS com a cabeça end-to-end do YOLO26.

O Ultralytics YOLO agora faz predições e rastreamento com IoU 0.5 por padrão#

Quando não especificas iou e o NMS é aplicado, os modos predict e track usam agora 0.5. Qualquer valor que especifiques explicitamente continua a prevalecer, por isso os pipelines que já definem iou comportam-se exatamente como antes. A referência das definições de predição apresenta o novo valor predefinido junto a conf=0.25.

Estes fluxos de trabalho passam a usar 0.5 quando iou não está definido:

• Predição e rastreamento com Python e CLI, incluindo preditores reutilizados e um iou=None explícito.
• Solutions como a contagem de objetos, a gestão de filas e o TrackZone, que herdam o valor do preditor.
• Novas exportações com NMS integrado (nms=True). Um modelo que exportaste anteriormente mantém o valor predefinido usado no momento da exportação.
• Ultralytics Platform, onde a documentação de inferência apresenta o seletor de IoU e o campo iou nos endpoints implementados, ambos com valor 0.5.
• Pacotes para dispositivos móveis: o pacote Ultralytics YOLO para iOS usa 0.5 por padrão na versão 8.9.20, tal como o plugin Flutter na versão 0.7.2; os valores predefinidos nas lojas de aplicações dependem da versão instalada.

Duas coisas permanecem intencionalmente em 0.7: a validação, para que o mAP publicado não mude, e os preditores SAM, SAM 2, SAM 3 e FastSAM, cujas máscaras muito sobrepostas não fizeram parte da medição.

O separador Predict de um modelo de segurança de armazém no Ultralytics Platform, a executar uma predição real. O seletor de IoU começa agora em 0.5.

Por que o antigo valor predefinido de 0.7 não era adequado para predições#

Antes desta versão, iou tinha um único valor predefinido partilhado entre predict e val. De acordo com a PR #27084, esse valor passou de 0.6 para 0.7 numa alteração de configuração de uma linha, em dezembro de 2022, no âmbito de um pull request não relacionado sobre o dataloader; mais tarde, as aplicações móveis adotaram o mesmo valor apenas por consistência.

Os dois modos têm funções diferentes:

• A validação avalia a lista completa de caixas ordenadas, até uma confiança de 0.001. Uma duplicata costuma ficar abaixo da caixa verdadeira na classificação e tem pouco custo, enquanto suprimir um objeto real reduz o recall em todos os limiares. Um limiar permissivo mantém os candidatos sobrepostos disponíveis para avaliação.
• A predição devolve um conjunto final de caixas em conf=0.25. Cada duplicata que o NMS deixa passar é um falso positivo visível no resultado, na contagem ou no alerta. Com 0.7, duas caixas da mesma classe que se sobreponham até 70% sobrevivem.

conf já tinha valores predefinidos separados exatamente por este motivo: 0.25 para predição e 0.001 para validação. iou segue agora o mesmo padrão.

O que a medição revelou#

A PR #27084 apresenta as seguintes pontuações F1 de deteção para diferentes limiares de NMS no COCO val2017, usando uma RTX PRO 6000. O F1 resume a precisão e o recall; os valores abaixo são médias por classe, expressas em percentagem:

Todos os modelos obtêm uma pontuação superior com 0.45 ou 0.5 do que com 0.7, e 0.5 fica no melhor resultado de cada modelo na tabela ou a uma distância máxima de 0.1. As diferenças são inferiores a um ponto na média por classe do COCO val2017; na tua própria câmara, a dimensão da diferença depende da frequência com que caixas da mesma classe se sobrepõem.

O que um limiar de IoU mais baixo faz às duplicatas e aos objetos próximos#

O NMS mede a sobreposição pela interseção sobre união: a área partilhada dividida pela área combinada de duas caixas. Ordena as caixas por confiança, mantém a melhor e elimina todas as outras caixas da mesma classe cuja IoU com a melhor exceda o limiar. Depois, repete o processo com a próxima caixa que sobreviver.

Esse único valor tem efeitos nos dois sentidos:

• Um iou mais baixo elimina mais caixas sobrepostas. As duplicatas de um objeto desaparecem mais cedo, mas dois objetos reais que se sobreponham muito — como carros encostados para-choques com para-choques, encomendas num tapete transportador ou pessoas numa fila — podem ser reduzidos a um só.
• Um iou mais alto mantém mais caixas sobrepostas. Os objetos próximos sobrevivem, mas as caixas quase duplicadas de um único objeto também.

A lição de deteção de objetos da Academy mostra o efeito na imagem de teste padrão bus.jpg com YOLO26n:

Nesta imagem, passar de 0.5 para 0.3 não altera a contagem, enquanto aumentar para 0.95 deixa passar mais três caixas. O efeito será diferente nas tuas imagens, por isso testa vários limiares nos teus próprios fotogramas.

Duas definições relacionadas influenciam o mesmo resultado. agnostic_nms=True também suprime caixas sobrepostas de classes diferentes, o que ajuda quando um objeto recebe dois rótulos, como carro e camião. max_det limita por predefinição as deteções a 300 por imagem, por isso pode ser necessário aumentar o valor em cenas muito densas.

Confiança vs. limiar de IoU no YOLO: quando alterar cada um#

conf e iou respondem a perguntas diferentes. conf determina se uma caixa tem confiança suficiente para ser mantida; iou determina se duas caixas mantidas correspondem, na realidade, ao mesmo objeto. Altera primeiro conf quando o problema forem caixas fracas ou espúrias, e altera iou apenas quando o problema for a sobreposição. A pontuação de confiança no YOLO26 é uma pontuação de classificação, não uma probabilidade calibrada; por isso, escolhe ambos os valores com base em dados de validação, não na intuição.

Usa o sintoma no resultado para escolher o parâmetro:

• O mesmo objeto tem duas caixas. Reduz iou, por exemplo, de 0.5 para 0.4.
• Um de dois objetos próximos desaparece em zonas com multidões. Aumenta iou, por exemplo, de 0.5 para 0.7, o antigo valor predefinido.
• Aparecem caixas no fundo. Aumenta primeiro conf; alterar iou só afeta caixas que se sobrepõem.
• Os objetos reais não são detetados. Reduz conf e consulta o guia de problemas comuns se o modelo nunca detetar nada.
• Apresentas contagens. Testa várias combinações nos fotogramas da câmara de contagem e mantém a combinação com o menor erro de contagem.

A geometria da câmara é tão importante quanto a cena. Uma vista elevada, de cima para baixo, tende a separar pessoas e veículos, pelo que as caixas se sobrepõem menos e um limiar mais baixo é mais prático. Uma câmara baixa e oblíqua ao longo de uma fila, faixa ou corredor coloca os objetos uns atrás dos outros, e as caixas de objetos diferentes podem sobrepor-se muito mais de 50%. Nesse caso, aumentar iou para perto de 0.7 pode preservar deteções reais.

Ilustrativo. Vistas oblíquas de objetos em fila produzem caixas muito sobrepostas para objetos diferentes; neste caso, um iou mais alto mantém os objetos próximos reais.

Ajusta o limiar de IoU para a tua própria câmara#

Um limiar que parece adequado numa imagem pode falhar numa câmara em direto. Ajusta-o com algumas dezenas de fotogramas da câmara de implementação, à resolução e no ângulo que vais usar, e compara os resultados com a contagem feita a olho por uma pessoa.

Para uma primeira tentativa sem código, carrega alguns desses fotogramas no separador Predict da página do modelo YOLO26n no Ultralytics Platform e ajusta os seletores de confiança e IoU para identificar duplicatas e objetos próximos em falta. Depois, executa o teste abaixo para escolher valores que possas justificar.

1. Recolhe fotogramas. Guarda fotogramas da câmara real que abranjam os momentos de maior e menor atividade. Se já os anotas no Ultralytics Platform, usa uma versão do conjunto de dados como referência.
2. Faz a contagem manualmente. Regista o número real de objetos-alvo em cada fotograma, ou anota-os por completo se planeias treinar o modelo.
3. Testa em conjunto conf e iou. Executa o script abaixo, que compara a contagem de cada fotograma com a tua.
4. Escolhe a combinação com o menor erro médio e, em seguida, abre os fotogramas em que ainda falha: as duplicatas indicam que deves reduzir iou; os objetos próximos fundidos indicam que deves aumentá-lo. Uma contagem pode parecer correta quando uma duplicata e uma deteção em falta se anulam no mesmo fotograma, por isso verifica também as caixas desenhadas e confirma a combinação escolhida em alguns fotogramas que não usaste no ajuste.
5. Define ambos explicitamente em todos os locais onde o modelo é executado, incluindo exportações com NMS integrado, para que uma alteração futura do valor predefinido nunca altere os teus resultados.

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

O erro absoluto médio impede que as contagens excessivas de um fotograma anulem as contagens insuficientes de outro. O argumento classes=[0] limita a contagem a uma classe (person no COCO); usa o índice da tua própria classe. Depois, passa os valores ajustados para o rastreamento e a exportação:

# O rastreamento aplica o limiar de NMS do detetor antes da associação
results = model.track("path/to/video.mp4", conf=0.35, iou=0.6, persist=True)

# Integra o NMS numa nova exportação com os dois limiares ajustados
model.export(format="onnx", nms=True, conf=0.35, iou=0.6)

No rastreamento, é importante ter um limiar estável por dois motivos. Uma caixa duplicada que sobreviva ao NMS pode iniciar um segundo ID de rastreamento no mesmo objeto, e um objeto próximo suprimido pode deixar de ser associado nesse fotograma; para deteção e OBB, o rastreador TrackTrack predefinido pode recuperar alguns desses candidatos com a sua própria passagem mais permissiva. A nossa lição sobre rastreamento com ByteTrack e BoT-SORT aborda os próprios limiares de correspondência do rastreador, que são independentes de iou.

A servir o modelo a partir de um endpoint dedicado no Ultralytics Platform? Especifica explicitamente conf e iou ajustados em cada pedido.

Por que a validação continua a usar IoU 0.7#

Se validares com model.val(), nada mudou: o validador continua a preencher iou=0.7. A validação utiliza a lista completa de caixas ordenadas com um valor de confiança muito baixo, onde um limiar permissivo mantém os candidatos sobrepostos disponíveis para correspondência com as anotações. Manter 0.7 também garante que os valores de mAP já publicados, bem como os das tabelas dos nossos modelos, continuem comparáveis com os de novas execuções.

Um detalhe relacionado com a validação mudou. A matriz de confusão passa agora a fazer a correspondência entre predições e anotações com IoU 0.5 em vez de 0.45, o mesmo limiar de IoU usado para mAP₅₀. Este é um limiar de correspondência, não de NMS: determina quais caixas são consideradas corretas, não quais sobrevivem. O guia de métricas de desempenho explica como cada métrica é calculada.

A definição de validação otimiza uma métrica baseada em classificações sobre milhares de caixas com baixa confiança, não sobre as poucas caixas com que a tua aplicação atua. Se quiseres experimentar 0.7 em produção, inclui esse valor nos testes com a câmara descritos acima e deixa que o erro de contagem determine o resultado.

Quando usar o YOLO26 sem NMS#

O Ultralytics YOLO26 treina duas cabeças em simultâneo. A cabeça one-to-many propõe vários candidatos por objeto e depende do NMS; é a usada por predefinição na predição e na validação. A cabeça one-to-one aprende a produzir uma única predição por objeto, por isso não precisa de supressão por IoU. Especifica nms=False para a usar, como mostra o guia de deteção end-to-end:

results = model.predict("image.jpg", nms=False)  # Cabeça one-to-one sem NMS
model.export(format="onnx", nms=False)  # saídas (N, 300, 6): xyxy, confiança, classe

Com nms=False, o detetor não aplica supressão por IoU, pelo que iou não tem qualquer efeito. Apenas conf, classes e max_det filtram o resultado. Com agnostic_nms=True, cada candidato mantém apenas a classe com a pontuação mais alta; as caixas distintas continuam sem supressão por IoU. Um rastreador como o TrackTrack ainda pode, por si só, suprimir o início de rastreamentos duplicados.

A contrapartida é uma pequena perda de precisão. No COCO val2017, a 640 píxeis, com um único modelo e numa única escala, o YOLO26n obtém 40.9 mAP_50-95 com NMS e 40.1 end-to-end; o YOLO26x obtém 57.5 e 56.9, respetivamente, de acordo com a documentação dos modelos YOLO26. Em contrapartida, uma exportação compatível produz deteções finais, pelo que não tens de implementar nem ajustar a supressão no dispositivo de destino.

Ilustrativo. Vista de cima de carros estacionados, cada um com uma caixa separada.

Escolhe a cabeça sem NMS quando:

• Implementas o modelo num ambiente de execução de edge em que implementar o NMS é complicado ou lento. Nem todos os formatos o suportam: alguns recorrem às saídas one-to-many ou exigem NMS, por isso lê os avisos de exportação e compara os resultados no ambiente de execução de destino. Para saber mais sobre a implementação, consulta como a cabeça sem NMS do YOLO26 altera a implementação.
• As tuas cenas são muito movimentadas e nenhum iou consegue eliminar duplicatas e manter objetos próximos nos fotogramas da tua câmara.
• Queres reduzir o número de componentes entre o modelo e o código, sem NMS específico do ambiente de execução para configurar.

Mantém o fluxo predefinido com NMS quando a última fração de mAP for mais importante do que a simplicidade de implementação, ou quando usares YOLO11 ou YOLOv8, que não têm uma cabeça one-to-one.

Qualquer que seja a cabeça que disponibilizes, verifica a licença antes de integrar o modelo num produto. Os modelos Ultralytics YOLO estão disponíveis ao abrigo da AGPL-3.0 e de uma Licença Ultralytics Enterprise; as implementações proprietárias que não conseguem cumprir as obrigações da AGPL-3.0 precisam da Enterprise License.

Quem deve alterar a definição de IoU#

Se usas o valor predefinido e os resultados pareciam corretos com 0.7, volta a verificá-los depois de atualizar: espera menos caixas duplicadas e, em cenas oblíquas muito movimentadas, a perda ocasional de um objeto próximo. Se contas objetos, compara as contagens antes e depois em alguns fotogramas conhecidos.

Se já especificas iou explicitamente, nada muda para ti. Se nunca escolheste um valor intencionalmente, o novo valor predefinido é um ponto de partida baseado em medições, e um breve teste com os teus próprios fotogramas dirá se deves mantê-lo. As equipas que criam novos pipelines de edge com YOLO26 devem testar primeiro nms=False no ambiente de execução de destino. Para testar limiares com fotogramas da tua própria câmara, abre a página do modelo YOLO26n no Ultralytics Platform e seleciona Predict; se as tuas cenas exigirem um modelo treinado com os teus próprios dados, podes treiná-lo no Ultralytics Platform e testá-lo no separador Predict da página do modelo treinado. Todos os argumentos de inferência estão listados na referência das definições de predição.