検証と指標

検証の実行

val()はデータセットを受け取り、指標を返します。

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt")metrics = model.val(data="coco8.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"])print(metrics["speed/total_ms"])

libreyolo val model=LibreYOLO9s.pt data=coco8.yaml

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt")metrics = model.val(data="coco8.yaml", split="train", batch=4) print(metrics)

戻り値は通常のdict[str, float]です。すべてのキーはリテラルなので、位置ではなく名前で読み取ってください。

主な引数はdata、split、batch、imgsz、conf、iou、workers、device、augment、save_json、verboseです。confのデフォルトは0.001、iouは0.6で、どちらも予測時のデフォルトより大幅に緩くなっています。mAPのsweepには信頼度の低い末尾まで必要なためです。imgszは固定値ではなくモデル自身の入力サイズがデフォルトです。splitはval、test、trainだけを受け付けます。

検証構成のその他のフィールドはキーワード引数として渡せます。save_dir、max_det、eval_max_det、half、amp_dtype、cache、save_plotsも含まれます。

タスク別の指標キー

物体検出はCOCO系の数値を返します。

metrics/mAP50-95   metrics/mAP50    metrics/mAP75
metrics/mAP_small  metrics/mAP_medium  metrics/mAP_large
metrics/AR1  metrics/AR10  metrics/AR100  metrics/AR_max_det
metrics/AR_small  metrics/AR_medium  metrics/AR_large
metrics/precision  metrics/recall
metrics/precision(B)  metrics/recall(B)  metrics/mAP50(B)  metrics/mAP50-95(B)

このうち2つは注意が必要です。metrics/precisionとmetrics/recallは後方互換性のため維持されるエイリアスで、precisionとrecallの組ではなく、mAP 50-95とAR@100の値を保持します。名前が明確なキーを使用してください。

インスタンスセグメンテーションでは、上記のmAPとARをサフィックスなしのキーでマスク指標として返し、ボックス版を(B)サフィックス、マスク版のコピーを(M)サフィックスで返します。このタスクのprecisionとrecallはサフィックス付きだけで、metrics/precision(B)とmetrics/recall(B)、metrics/precision(M)とmetrics/recall(M)になります。どちらの組も物体検出と同じエイリアス値を保持します。(B)の組はボックスのmAP50-95とAR@100、(M)の組はマスクのmAP50-95とAR@100です。

OBBのmetrics/precisionとmetrics/recallはエイリアスではありません。IoU 0.50における実際のprecisionとrecallで、最も緩い動作点、つまりconf（デフォルト0.001）を通過したすべての予測から取得します。(OBB)サフィックス付きのコピーは、上記の(B)や(M)と同じ規則で、同じ4つの値をタスク固有名の下に繰り返します。

accuracy_top5は実際にはtop-min(5, num_classes)です。3クラスのデータセットではtop-3となり、すべてのサンプルが条件を満たすため1.0になります。

pointタスクのsweepキーは距離しきい値から構築されます。デフォルトではmetrics/mAP@[0.01:0.10]となり、単一しきい値のキーはmetrics/mAP@0.01です。dist_thresholdsを渡すと両方の文字列が変わります。

ほとんどのタスクは、最良チェックポイント選択でデフォルト使用する単一値のfitnessキーも返します。物体検出、セグメンテーション、OBBはこのキーを持ちません。それらのファミリーでは辞書が返すmetrics/mAP50-95を使って選択します。姿勢推定はfitnessもmetrics/mAP50-95も返さず、代わりにトレーナーがbest_metric_keyをmetrics/keypoints_mAP50-95へ設定します。

速度キー

すべてのバリデーターが処理時間を追加します。

speed/preprocess_ms   speed/inference_ms   speed/postprocess_ms
speed/total_ms        speed/total_s        speed/images_seen

これらは実行全体で平均した画像あたりのミリ秒です。実行したマシンと設定を表すため、この値を報告するときはハードウェア、バッチサイズ、精度も併記しなければ意味がありません。

評価バックエンド

物体検出とセグメンテーションの指標はCOCO評価器で計算され、デフォルトのfaster_coco_eval=Trueはfaster-coco-evalパッケージがインストールされている場合にC++バックエンドを選択します。ない場合はプロセスごとに1回警告し、pycocotoolsへフォールバックします。

faster_coco_eval requested but not installed; falling back to pycocotools.
Install with: pip install faster-coco-eval

実際に使用したバックエンドはモデルのlast_eval_backendに記録され、物体検出系タスクではCLIも出力に含めます。環境から構成値を上書きするにはLIBREYOLO_FASTER_COCO_EVALを設定します。

iou_thresholdsが使われるのはOBB経路だけです。COCO経路は独自の固定0.50から0.95のsweepで評価し、この値を無視します。

検証loss

デフォルトの検証は精度だけを報告します。val_loss=Trueを指定すると、検証バッチに対してファミリーの学習目的関数も計算します。

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt")model.train(data="coco8.yaml", epochs=10, val_loss=True)

metrics/lossと項ごとのmetrics/loss/<component>を出力します。各成分には学習とまったく同じ重みが付くため、合計するとtotalになります。ロガーではval/lossとval/loss/<component>として表示され、libreyolo monitorはmetrics/lossをtrain/lossへ重ねて表示します。

成分はファミリー固有です。

ターゲット割り当てによって検証の時間とメモリが増えるため、デフォルトでは無効です。精度指標用にすでに生成したモデル出力を再利用し、2回目の順伝播は実行しません。評価モデルまたはEMAモデルに対してno_grad下で実行し、マルチGPU学習ではcollectiveを使わずrank 0上でローカル計算します。最良チェックポイントの選択は引き続き精度指標に基づきます。

意図的に行わないことが3つあります。1つ目は対照的ノイズ除去の項を含めないことです。これには順伝播時の正解データが必要ですが、検証の順伝播では渡さないためです。2つ目は評価モードのモデルを報告することです。BatchNorm統計やStochastic Depthなど、ファミリーの学習時と評価時の順伝播が実際に異なる箇所では、数値は評価モードを反映します。これが意図する比較です。3つ目は、ファミリーで未実装のタスクを通知なくスキップしないことです。セットアップ時に構成エラーを発生させます。

val_loss=True currently supports RF-DETR detection only; segment, pose, OBB,
classify, and semantic tasks are not supported

FOMOは動作が変わらない例外です。バリデーターが常にこのlossを計算しており、val_loss=Trueは公開するキーだけに影響します。

拡張付き検証と検証lossは併用できず、両方を指定すると例外が発生します。

検証が書き込むファイル

val()は必ず保存ディレクトリにconfig.yamlを書き込みます。save_dirを指定しない場合、デフォルトはruns/val/<model>_<size>_<timestamp>です。

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt")model.val(data="coco8.yaml", save_json=True, save_dir="runs/val/exp")

save_json=Trueは、物体検出ではpredictions.json、セグメンテーションではpredictions_bbox.jsonとpredictions_masks.jsonを書き込みます。OBBは対応しておらず、その旨を報告します。

save_plots=Trueはplots/サブディレクトリへ書き込みます。OpenCVがインストールされている場合、物体検出ではbox_metrics.png、クラスごとのAPとrecallのチャート、precision-recallと信頼度の曲線、confusion matrix、アノテーション付きサンプル画像を生成します。セグメンテーションは各項目のマスク版を追加し、姿勢推定には独自の指標と曲線一式があります。その他のバリデーターはプロットを実装していません。画像分類、セマンティック、panoptic、深度、法線、エッジ、復元、matte、OCR、OBB、pointはいずれも何も書き込みません。プロットの失敗は警告され、実行を中止しません。

学習中の検証

学習はeval_intervalエポックごとにデータセットのval分割で検証し、生成された指標がbest.ptの選択、patienceによる早期停止、すべてのロガーのval/キーを駆動します。EMAが有効な場合、検証はEMA重み上で実行されます。

eval_interval、patience、save_plotsについてはハイパーパラメーターを、数値の送信先については実験ロガーを参照してください。

関連項目

• バリデーターが読み取る分割キーと形式についてはデータセットを参照してください。