Ultralytics YOLOのNMS IoUしきい値を調整する方法

IoUしきい値によって、検出器が重なり合う2つのボックスを同じ物体として扱う条件が決まります。Ultralytics YOLOでは、非最大値抑制（NMS）によって最も信頼度の高いボックスを残し、同じクラスでiouを超えて重なるほかのボックスを削除します。しきい値が高すぎると1つの物体に2つのボックスが付き、低すぎると並んでいる2つの物体のうち片方が消えてしまいます。

2026年11月8日にリリースされたUltralytics 8.4.208以降、推論とトラッキングのデフォルトは0.7ではなくiou=0.5になりました。一方、検証では0.7が維持されます。このガイドでは、変更点とその理由、しきい値とconfの関係、使用するカメラに合わせて両方を調整する方法、そしてYOLO26のエンドツーエンドヘッドでNMSを完全に省略するタイミングを説明します。

Ultralytics YOLOの推論とトラッキングのデフォルトIoUは0.5になりました#

iouを指定せず、NMSが適用される場合、predictモードとtrackモードでは0.5が使われるようになりました。明示的に指定した値は引き続き優先されるため、すでにiouを設定しているパイプラインの動作は変わりません。predictの設定リファレンスには、新しいデフォルト値がconf=0.25と並んで記載されています。

次のワークフローでは、iouが未設定の場合に0.5が適用されます。

• PythonとCLIによる推論およびトラッキング。再利用されるPredictorや、明示的なiou=Noneも含みます。
• Solutions。たとえば物体カウント、キュー管理、TrackZoneが該当し、Predictorの値を引き継ぎます。
• NMSを組み込んだ新しいエクスポート（nms=True）。以前にエクスポートしたモデルには、エクスポート時のデフォルト値が維持されます。
• Ultralytics Platform。デプロイ済みエンドポイントのIoUスライダーとiouフィールドのデフォルト値が0.5であることは、推論ドキュメントに記載されています。
• モバイルパッケージ：Ultralytics YOLOのiOSパッケージはリリース8.9.20で0.5をデフォルトとし、Flutterプラグインもリリース0.7.2で同様に変更されました。アプリストアでのデフォルト値は、インストールされているバージョンによって異なります。

意図的に0.7を維持するものが2つあります。公開済みのmAPが変わらないようにするための検証と、重なりの大きいマスクが今回の測定対象ではなかったSAM、SAM 2、SAM 3、FastSAMのPredictorです。

実際に推論を実行しているUltralytics Platformの倉庫安全モデルのPredictタブです。IoUスライダーの初期値は0.5になりました。

以前のデフォルト0.7が推論に適さなかった理由#

このリリース以前は、iouのデフォルト値はpredictとvalで共通でした。PR #27084によると、この値は2022年12月、無関係なデータローダーのプルリクエスト内で行われた1行の設定変更により0.6から0.7へ移行し、その後、モバイルアプリも一貫性を保つために追随しました。

この2つのモードは、それぞれ異なる目的で使われます。

• 検証では、信頼度0.001までのボックス全体を順位付けして評価します。重複ボックスは通常、正しいボックスより低い順位になるため損失は小さい一方、実在する物体を抑制すると、すべてのしきい値で再現率が低下します。許容度の高いしきい値を使うと、重なり合う候補を評価用に残せます。
• 推論では、conf=0.25で最終的なボックスのセットを返します。NMSを通過した重複はすべて、出力、カウント、アラートにおいて目に見える偽陽性になります。しきい値が0.7の場合、同じクラスのボックスは最大70%重なっていても両方残ります。

confには、まさにこの理由からすでに個別のデフォルト値が設定されており、推論では0.25、検証では0.001でした。iouも同じ方式になりました。

測定結果#

PR #27084では、RTX PRO 6000を使ってCOCO val2017で測定した、NMSしきい値ごとの検出F1スコアが報告されています。F1は適合率と再現率をまとめた指標です。以下の値はクラスごとの平均を百分率で示しています。

すべてのモデルで0.45または0.5のスコアが0.7を上回り、0.5でのスコアは表中の各モデルの最高値と同等か、0.1以内の差に収まっています。COCO val2017のクラス別平均における差は1ポイント未満です。使用するカメラでの差の大きさは、同じクラスのボックスがどの程度重なるかによって異なります。

IoUしきい値を下げると、重複ボックスと近接物体にどのような影響があるか#

NMSはIntersection over Unionで重なりを測定します。これは2つのボックスの共通領域を、両方のボックスを合わせた領域で割った値です。ボックスを信頼度順に並べて最良のものを残し、それと同じクラスでIoUがしきい値を超えるほかのボックスをすべて削除します。その後、次に残ったボックスについて同じ処理を繰り返します。

この1つの値は、両方向に影響します。

• iouを下げると、重なり合うボックスがより多く削除されます。1つの物体に対する重複は早く消えますが、バンパー同士が接触した車、ベルトコンベア上の荷物、列に並んだ人のように、実在する2つの物体が大きく重なっていると、片方が1つにまとめられてしまうことがあります。
• iouを上げると、重なり合うボックスがより多く残ります。近接する物体は残りますが、1つの物体に対するほぼ重複したボックスも残ります。

Academyの物体検出レッスンでは、標準のbus.jpgテスト画像にYOLO26nを適用した場合の影響を示しています。

この画像では、しきい値を0.5から0.3に下げてもカウントは変わりませんが、0.95に上げるとボックスがさらに3つ残ります。実際の映像では影響が異なるため、使用する映像のフレームで複数のしきい値を試してください。

関連する2つの設定も同じ出力に影響します。agnostic_nms=Trueはクラスをまたいで重なり合うボックスも抑制します。これは、1つの物体に「車」と「トラック」など2つのラベルが付く場合に役立ちます。max_detは画像ごとの検出数をデフォルトで300に制限するため、非常に密集したシーンでは値を引き上げる必要がある場合があります。

YOLOの信頼度とIoUしきい値：それぞれを変更するタイミング#

confとiouは、それぞれ異なる問いに答える値です。confはボックスを残すのに十分な信頼度があるかを判定し、iouは残った2つのボックスが実際には同じ物体かを判定します。問題が信頼度の低いボックスや誤検出であれば、まずconfを変更し、重なりが問題の場合に限ってiouを変更してください。YOLO26の信頼度スコアは順位付け用のスコアであり、校正済みの確率ではありません。そのため、両方の値は直感ではなく検証データに基づいて選んでください。

出力に現れている症状をもとに、調整する値を選びます。

• 同じ物体に2つのボックスが付く。iouを下げます。たとえば、0.5から0.4にします。
• 混雑した場所で、隣り合う2つの物体の片方が消える。iouを上げます。たとえば、0.5から以前のデフォルト値である0.7にします。
• 背景にボックスが表示される。まずconfを上げます。iouを変更しても、重なり合うボックスにしか影響しません。
• 実在する物体が完全に見逃される。confを下げます。モデルがまったく検出しない場合は、よくある問題のガイドも確認してください。
• 物体数を報告する。カウント用カメラのフレームで両方の値を試し、カウント誤差が最小になる組み合わせを選びます。

カメラの幾何学的な配置も、シーンと同じくらい重要です。高い位置から真下を見下ろす映像では、人や車両が分離して映る傾向があり、ボックスの重なりが少なくなるため、低いしきい値が実用的です。列、車線、通路に沿った低い斜め位置のカメラでは、物体が前後に重なって映り、異なる物体のボックス同士が50%を大きく超えて重なることがあります。この場合は、iouを0.7に近づけると、実在する物体の検出を維持できる可能性があります。

説明用の画像です。斜めから見た車列では、異なる物体のボックスが大きく重なるため、IoUを高くすると実在する隣接物体を残せます。

使用するカメラに合わせてIoUしきい値を調整する#

1枚の画像で適切に見えるしきい値でも、ライブカメラではうまくいかないことがあります。実際に運用するカメラから数十フレームを用意し、運用時と同じ解像度と角度で調整して、人が目視で数えた結果と比較してください。

コードを使わずに最初の確認を行うには、対象フレームを数枚、Ultralytics PlatformのYOLO26nモデルページにあるPredictタブにアップロードし、信頼度とIoUのスライダーを動かして重複や見逃された隣接物体を確認します。その後、以下のスイープを実行し、根拠を示せる値を選びます。

1. フレームを収集します。実際のカメラから、最も混雑する時間帯と最も空いている時間帯のフレームを保存します。すでにUltralytics Platformでラベル付けしている場合は、データセットのバージョンを参照用セットとして使います。
2. 手作業で数えます。各フレーム内の対象物体の実数を記録します。トレーニングを行う予定がある場合は、物体にすべてラベルを付けます。
3. confとiouを組み合わせてスイープします。各フレームのカウントを手作業で数えた値と比較する以下のスクリプトを実行します。
4. 平均誤差が最小になる組み合わせを選びます。次に、まだ失敗するフレームを開いて確認します。重複がある場合はiouを下げ、隣接物体が1つにまとめられている場合は上げます。同じフレームで重複と見逃しが相殺されると、カウントが正しく見えることがあります。そのため、描画されたボックスも確認し、調整に使っていないフレームでも選んだ組み合わせを検証してください。
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]引数は、カウント対象を1つのクラス（COCOではperson）に限定します。使用するクラスのインデックスを指定してください。調整した値は、トラッキングとエクスポートに設定します。

# トラッキングでは、検出器の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)

トラッキングでは、安定したしきい値が2つの点で重要です。NMSを通過した重複ボックスは、同じ物体に2つ目のトラックIDを割り当てる可能性があります。また、抑制された隣接物体は、そのフレームでの関連付けから外れることがあります。検出とOBBでは、デフォルトのTrackTrackトラッカーが、独自のより許容度の高い処理によって候補の一部を復元できます。ByteTrackとBoT-SORTに関するトラッキングレッスンでは、iouとは別に設定される、トラッカー独自のマッチングしきい値を解説しています。

Ultralytics Platformの専用エンドポイントからモデルを提供していますか？各リクエストで調整済みのconfとiouを明示的に渡してください。

検証でIoU 0.7を維持する理由#

model.val()を使って検証する場合、変更はありません。検証器は引き続きiou=0.7を設定します。検証では、非常に低い信頼度まで含むボックスの全順位リストを使います。許容度の高いしきい値により、ラベルとのマッチングに使える重なり合う候補を残します。また、0.7を維持することで、すでに公開したmAPの数値やモデル表に記載されている数値を、新しい実行結果と比較できるようにしています。

関連する検証の詳細が1点変更されました。混同行列では、予測とラベルのマッチングに0.45ではなく0.5のIoUが使われるようになりました。これはmAP₅₀で使われるIoUしきい値と同じです。これはマッチングしきい値であり、NMSではありません。どのボックスが残るかではなく、どのボックスが正解として数えられるかを決めます。性能指標のガイドでは、各指標の計算方法を説明しています。

検証設定は、アプリケーションが実際に処理する少数のボックスではなく、何千もの低信頼度ボックスを対象とした順位付け指標を最適化します。本番環境で0.7を試す場合は、上記のカメラスイープに含め、カウント誤差に基づいて判断してください。

YOLO26でNMSを使わないタイミング#

Ultralytics YOLO26は、2つのヘッドを同時にトレーニングします。One-to-Manyヘッドは物体ごとに複数の候補を提案し、NMSに依存します。推論と検証では、デフォルトでこのヘッドが使われます。One-to-Oneヘッドは物体ごとに1つの予測を出力するよう学習するため、IoUによる抑制は不要です。エンドツーエンド検出ガイドにあるように、使用するにはnms=Falseを渡します。

results = model.predict("image.jpg", nms=False)  # NMSを使わないOne-to-Oneヘッド
model.export(format="onnx", nms=False)  # 出力（N, 300, 6）：xyxy、信頼度、クラス

nms=Falseを指定すると、検出器はIoUによる抑制を適用しないため、iouは作用しません。出力をフィルタリングするのはconf、classes、max_detのみです。agnostic_nms=Trueを指定すると、各候補ではスコアが最も高いクラスだけが残りますが、異なるボックスに対するIoU抑制は行われません。TrackTrackなどのトラッカーは、重複したトラックの開始を独自に抑制できます。

トレードオフとして、精度がわずかに低下します。COCO val2017で640ピクセル、単一モデル、単一スケールの場合、YOLO26nはNMSありで40.9 mAP_50-95、エンドツーエンドで40.1を記録します。YOLO26xはそれぞれ57.5と56.9です。これはYOLO26のモデルドキュメントに基づく値です。その代わり、対応するエクスポート形式では最終的な検出結果が出力されるため、ターゲットデバイス上で抑制処理を実装したり調整したりする必要がありません。

説明用の画像です。駐車車両を真上から見た画像で、それぞれの車に個別のボックスが付いています。

NMSを使わないヘッドを選ぶのは、次のような場合です。

• NMSの実装が難しい、または遅いエッジランタイムにデプロイする場合。すべての形式が対応しているわけではありません。一部の形式ではOne-to-Manyの出力にフォールバックするか、NMSが必要になるため、エクスポート時の警告を確認し、ターゲットランタイムで結果を比較してください。デプロイについては、YOLO26のNMSを使わないヘッドがデプロイに与える影響を参照してください。
• シーンが混雑しており、カメラ映像の重複を除去しながら隣接物体も残せるiouが1つもない場合。
• モデルとコードの間の構成要素を減らし、ランタイムごとにNMSを設定せずに済ませたい場合。

デプロイのシンプルさよりmAPのわずかな向上を重視する場合や、One-to-Oneヘッドを持たないYOLO11またはYOLOv8を使う場合は、デフォルトのNMS経路を使用してください。

どちらのヘッドをデプロイする場合も、モデルを製品に組み込む前にライセンスを確認してください。Ultralytics YOLOモデルはAGPL-3.0とUltralytics Enterprise Licenseで利用できます。AGPL-3.0の義務を満たせない独自製品へのデプロイには、Enterprise Licenseが必要です。

iou設定を変更するべき人#

デフォルト値を使っていて、0.7で結果に問題がなかった場合は、アップグレード後に再確認してください。重複ボックスは減ると予想されますが、混雑した斜め視点のシーンでは、隣接物体がまれに見失われることがあります。物体数をカウントしている場合は、既知のフレーム数枚で変更前後のカウントを比較してください。

すでにiouを明示的に渡している場合、変更はありません。意図的に値を選んだことがない場合、新しいデフォルト値は測定に基づく出発点となり、使用するフレームで短時間のスイープを行えば、そのまま使うべきかどうかを判断できます。YOLO26を使った新しいエッジパイプラインを構築するチームは、まずターゲットランタイムでnms=Falseをテストしてください。使用するカメラのフレームでしきい値を試すには、Ultralytics PlatformのYOLO26nモデルページを開いてPredictを選択します。独自データでトレーニングしたモデルが必要なシーンでは、Ultralytics Platformでモデルをトレーニングし、トレーニング済みモデルのページにあるPredictタブでテストできます。すべての推論引数はpredictの設定リファレンスに記載されています。