Validasi dan metrik

Jalankan validasi

val() mengambil dataset dan mengembalikan metrik.

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)

Nilai kembaliannya adalah dict datar dari kunci metrik ke angka. Setiap kunci bersifat literal, jadi bacalah berdasarkan nama daripada posisi. Untuk detect, segment, dan classify, nilai ini adalah subclass dict yang juga membawa hasil per kelas sebagai atribut, dijelaskan di bawah.

Argumen utama adalah data, split, batch, imgsz, conf, iou, workers, device, augment, save_json dan verbose. conf secara default adalah 0.001 dan iou ke 0.6, keduanya jauh lebih longgar daripada default prediksi, karena pencarian mAP membutuhkan ekor dengan kepercayaan rendah. imgsz secara default adalah ukuran input model itu sendiri daripada angka tetap. split menerima val, test atau train dan tidak ada lainnya. Tanpa data, checkpoint hasil pelatihan divalidasi pada dataset tempat ia dilatih; bobot rilis tidak membawa dataset dan memerlukan data=.

Setiap bidang lain dari konfigurasi validasi diteruskan sebagai argumen kata kunci, termasuk save_dir, max_det, eval_max_det, half, amp_dtype, cache, save_plots, single_cls, dan agnostic_nms. Dengan half=True di CUDA, validasi berjalan di bawah autocast dalam amp_dtype, dan output bfloat16 dikonversi ke float32 sebelum pascapemrosesan; pelatihan dengan amp_dtype="bfloat16" divalidasi dengan cara yang sama.

agnostic_nms=True hanya mempertahankan box dengan skor tertinggi di antara box yang tumpang tindih di atas iou, apa pun kelasnya. Langkah ini berjalan pada deteksi akhir milik family, setelah classes=, sehingga mAP, confusion matrix, kurva, dan hitungan per gambar semuanya menilai box yang sama. Ini mencakup detect dan segment, dan task lain mana pun memunculkan ValueError. Sisi predict ada di Ambang batas dan pemfilteran.

single_cls=True menilai deteksi sebagai satu kelas. Ground truth diciutkan ke kelas 0, dan deteksi model dipertahankan sesuai classes= dalam ruang label model itu sendiri, lalu dilabeli ulang 0, sehingga checkpoint yang dilatih pada beberapa kelas dinilai sebagai detektor satu kelas.

Kunci metrik per task

Deteksi mengembalikan family COCO dari angka:

metrics/mAP50-95   metrics/mAP50    metrics/mAP75metrics/mAP_small  metrics/mAP_medium  metrics/mAP_largemetrics/AR1  metrics/AR10  metrics/AR100  metrics/AR_max_detmetrics/AR_small  metrics/AR_medium  metrics/AR_largemetrics/precision  metrics/recallmetrics/precision(B)  metrics/recall(B)  metrics/mAP50(B)  metrics/mAP50-95(B)

Dua dari mereka adalah jebakan. metrics/precision dan metrics/recall adalah alias yang dijaga untuk kompatibilitas belakang: mereka membawa nilai mAP 50-95 dan AR@100, bukan pasangan presisi dan recall. Gunakan kunci bernama.

Segmentasi instance mengembalikan angka mAP dan AR di atas sebagai angka mask di bawah kunci tanpa akhiran, dengan versi kotak berada di bawah akhiran (B) dan diulang di bawah (M). Presisi dan recall hanya ada dalam bentuk akhiran untuk task ini, seperti metrics/precision(B)/metrics/recall(B) dan metrics/precision(M)/metrics/recall(M), dan kedua pasangan membawa nilai alias yang sama seperti detect: pasangan (B) adalah bounding box mAP50-95 dan bounding box AR@100, pasangan (M) adalah mask mAP50-95 dan mask AR@100.

OBB metrics/precision dan metrics/recall bukan alias: mereka adalah presisi nyata dan recall pada IoU 0,50, diambil pada titik operasi paling longgar (setiap prediksi yang bertahan conf, default 0.001). Salinan yang berakhiran (OBB) mengulangi keempat nilai yang sama dengan nama spesifik task, konvensi yang sama seperti (B) dan (M) di atas.

accuracy_top5 sebenarnya top-min(5, num_classes), jadi pada dataset tiga kelas itu adalah top-3, yang dipenuhi setiap sampel dan akibatnya terbaca 1,0. Hasil klasifikasi juga menyediakan kedua nilai itu sebagai atribut top1 dan top5, di samping confusion_matrix.

Kunci sweep titik task dibangun dari ambang jarak, jadi dengan secara default terbaca metrics/mAP@[0.01:0.10] dan tombol ambang tunggal terbaca metrics/mAP@0.01. Melewati dist_thresholds mengubah kedua string.

Sebagian besar tugas juga mengembalikan kunci fitness, angka tunggal terbaik-checkpoint seleksi digunakan secara default. Deteksi, segmentasi, dan OBB tidak membawa satu; keluarga mereka dipilih pada metrics/mAP50-95, yang dilakukan oleh kamus mereka kembali. Pose tidak mengembalikan fitness maupun metrics/mAP50-95; pelatihnya atur best_metric_key ke metrics/keypoints_mAP50-95 sebagai gantinya.

Klasifikasi ImageFolder menambahkan makro metrics/precision, metrics/recall, dan metrics/f1, dirata-ratakan atas kelas yang ada dalam target validasi. Top-1 tetap menjadi fitness default. Deteksi juga mengembalikan metrics/best_conf dan metrics/best_conf_f1, memilih ambang optimal micro-F1 pada IoU 0.50, dan menaruh ambang dengan nama kelas sebagai kunci di metrics.box.best_conf_per_class. Deteksi dengan skor sama tetap dikelompokkan; hasil seri memilih ambang yang lebih tinggi. Jika tidak ada F1 positif, hasilnya 0.0. Segmentasi tidak menyediakan kunci ambang ini.

Confusion matrix

Hasil detect, segment, dan classify membawa results.confusion_matrix. Matriks ini dihitung pada setiap validasi, baik plot ditulis maupun tidak, dan matrix-nya adalah array integer yang diindeks matrix[predicted, true].

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt")metrics = model.val(data="coco8.yaml") cm = metrics.confusion_matrixprint(cm.matrix.shape)      # (81, 81): 80 kelas ditambah backgroundprint(cm.class_accuracy())  # nama kelas: proporsi objek yang ditemukan dan diberi kelas itutp, fp = cm.tp_fp()

Untuk detect dan segment, prediksi pada confidence 0.25, atau conf bila lebih tinggi, dipasangkan satu lawan satu dengan box ground truth dari kelas apa pun pada IoU 0.5, dimulai dari IoU tertinggi. Sepasang dihitung pada kelas prediksi dan kelas sebenarnya, sehingga box yang posisinya tepat tetapi kelasnya salah jatuh di luar diagonal. Matriks memiliki baris dan kolom tambahan background: ground truth yang tidak berpasangan dihitung di baris background, prediksi yang tidak berpasangan di kolom background. Segmentasi memasangkan box, bukan mask. Dengan classes=, ground truth dari kelas lain dikeluarkan.

Wilayah crowd COCO (iscrowd=1) mengikuti aturan yang diterapkan mAP. Prediksi yang tidak dicocokkan dengan ground truth mana pun dari kelasnya, yang berada setidaknya setengah di dalam wilayah crowd dengan kelas yang sama (irisan terhadap luas prediksi itu sendiri), diabaikan, bukan dihitung. box.image_metrics dan gambar visualize=True memakai ambang dan aturan crowd yang sama. Label berformat YOLO tidak punya wilayah crowd.

Untuk classify, setiap gambar dihitung sekali, pada kelas top-1-nya terhadap labelnya, dan tidak ada background.

Di atas 2.000 kelas, matriks klasifikasi padat tidak dibangun: matrix, summary(), ekspor to_*(), dan plot() memunculkan error, sedangkan tp_fp(), nonzero(), dan class_accuracy() tetap berfungsi.

Kelasnya adalah libreyolo.validation.ConfusionMatrix, dibangun sebagai ConfusionMatrix(nc, iou_thres=0.5, conf_thres=0.25, *, names=None, task="detect"), dengan task berupa "detect" atau "classify".

Presisi, recall, dan F1 per kelas

Hasil detect dan segment membawa presisi, recall, dan F1 tiap kelas di berbagai ambang confidence, dicocokkan pada IoU 0.5.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt")metrics = model.val(data="coco8.yaml") box = metrics.boxprint(box.px.shape, box.f1_curve.shape)  # (1000,) dan (classes, 1000)for index, f1 in zip(box.ap_class_index, box.f1):    print(model.names[int(index)], round(float(f1), 3))

box.px menyimpan 1000 nilai confidence, berjarak sama di atas [0, 1]. box.p_curve, box.r_curve, dan box.f1_curve adalah array (classes, 1000), satu baris per entri box.ap_class_index, yaitu indeks kelas yang punya ground truth di split tersebut, dalam urutan menaik. box.p, box.r, dan box.f1 adalah nilai per kelas pada confidence yang memaksimalkan rata-rata F1 atas kelas-kelas itu. Segmentasi menghitung semuanya dari box. Semuanya berupa array kosong bila run tidak menghasilkan kurva.

Metrik kotak per gambar

Hasil deteksi dan segmentasi tetap kompatibel dengan dictionary dan juga menyediakan results.box.image_metrics. Setiap nama berkas dipetakan ke precision, recall, f1, tp, fp, dan fn dengan aturan pencocokan visualisasi, bahkan saat visualisasi mati. Segmentasi menghitung kotak di sini. Nama dasar yang duplikat memakai path lengkap setelah kemunculan pertama. Penyebut nol menghasilkan 0.0. Catatan ini tidak dikumpulkan antar rank terdistribusi.

Tombol pintas

Setiap validator menambahkan waktu:

speed/preprocess_ms   speed/inference_ms   speed/postprocess_msspeed/total_ms        speed/total_s        speed/images_seen

Ini adalah milidetik per gambar yang dirata-ratakan selama seluruh proses. Mereka menggambarkan mesin dan pengaturan yang Anda jalankan, sehingga angka yang diambil dari mereka hanya berarti jika dilaporkan dengan perangkat kerasnya, batch ukuran dan presisi.

Backend Evaluasi

Metrik deteksi dan segmentasi dihitung melalui evaluator COCO, dan faster_coco_eval=True, default-nya, memilih backend C++ ketika paket faster-coco-eval terinstal. Ketika tidak, proses berjalan kembali ke pycocotools dengan satu peringatan per proses:

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

Backend yang sebenarnya dijalankan dicatat pada model sebagai last_eval_backend, dan CLI melaporkannya dalam output untuk tugas gaya deteksi. Atur LIBREYOLO_FASTER_COCO_EVAL untuk mengganti nilai konfigurasi dari lingkungan.

iou_thresholds hanya dihormati pada jalur OBB. Jalur COCO dievaluasi melalui sweep 0,50 hingga 0,95 yang tetap sendiri dan mengabaikan nilainya.

Validasi loss

Secara default, validasi hanya melaporkan akurasi. val_loss=True juga menghitung tujuan pelatihan family pada batch validasi.

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

Ini mengeluarkan metrics/loss ditambah satu metrics/loss/<component> per istilah, diberi bobot persis seperti bobot pelatihan, sehingga komponen-komponennya berjumlah total. Melalui logger, mereka muncul sebagai val/loss dan val/loss/<component>, dan libreyolo monitor overlays metrics/loss with train/loss.

Komponen-komponen ini adalah milik family sendiri:

Ini dimatikan secara default karena penugasan target menambahkan waktu dan memori ke validasi. Validator menggunakan kembali output model yang sudah dihasilkan untuk metrik akurasi daripada menjalankan lintasan maju kedua, ia dijalankan di bawah no_grad pada model evaluasi atau EMA, dan di bawah pelatihan multi-GPU itu dihitung secara lokal pada peringkat 0 tanpa kolektif. Pemilihan Best-checkpoint tetap pada metrik akurasi.

Tiga hal yang dengan sengaja tidak dilakukannya. Ia tidak pernah termasuk denoising-kontrastas persyaratan, karena itu memerlukan ground truth pada waktu maju dan validasi maju tanpa itu. Ini melaporkan model dalam mode evaluasi, jadi di mana family's train dan eval benar-benar berbeda di depan, dalam statistik BatchNorm atau stokastik kedalaman, angka tersebut mencerminkan mode evaluasi; itu adalah perbandingan yang dimaksud. Dan sebuah task family belum menerapkannya sehingga menyebabkan kesalahan konfigurasi saat pengaturan daripada diam-diam melewatkan:

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

FOMO adalah pengecualian yang tidak mengubah apa pun: validatornya selalu menghitung ini loss, dan val_loss=True hanya memengaruhi tombol mana yang diterbitkan dengannya.

Validasi yang ditingkatkan dan validasi loss tidak dapat dikombinasikan, dan meminta keduanya meningkatkan.

Berkas menulis validasi

val() selalu menulis config.yaml ke direktori simpanannya, secara default ke runs/val/<model>_<size>_<timestamp> ketika save_dir tidak diberikan. project, name dan exist_ok menentukannya dengan cara yang sama seperti pelatihan: project/name, dengan sufiks bernomor kecuali exist_ok=True.

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

save_json=True menulis predictions.json untuk deteksi, dan predictions_bbox.json ditambah predictions_masks.json untuk segmentasi. OBB tidak mendukungnya dan menyatakannya.

save_plots=True, atau aliasnya plots=True, menulis ke dalam subdirektori plots/ dan memerlukan matplotlib, yang dipasang oleh pip install "libreyolo[plots]". Deteksi mendapatkan box_metrics.png, AP per kelas dan grafik recall, kurva presisi-recall dan kepercayaan, kurva F1 per kelas di f1_conf_box.png, confusion matrix sebagai hitungan di confusion_matrix.png dan sebagai proporsi tiap kelas sebenarnya di confusion_matrix_normalized.png, dan contoh gambar beranotasi ketika OpenCV terpasang. Segmentasi menambahkan salinan sisi mask dari grafik metrik, grafik per kelas, serta kurva presisi-recall dan kepercayaan; kurva F1 dan confusion matrix tetap di tingkat box. Pose mendapatkan set metrik dan kurva miliknya sendiri. Klasifikasi menulis kedua berkas confusion matrix, kecuali di atas 2.000 kelas. Validator lain tidak mengimplementasikan plot; semantik, panoptik, kedalaman, normal, tepi, pemulihan, matte, OCR, OBB, dan poin semuanya tidak menulis apa pun di sana. Kegagalan plot akan memberi peringatan dan tidak pernah menghentikan jalannya.

visualize=True menulis gambar kotak TP/FP/FN dengan memperhitungkan kelas untuk deteksi dan segmentasi, atau gambar label-versus-top-1 untuk klasifikasi ImageFolder, ke visualize/errors/ dan visualize/correct/. Pencocokan memakai IoU 0.5 dan skor keyakinan max(0.25, conf). Nilai default adalah visualize=False, show_labels=True, dan show_conf=True. Task yang tidak didukung dan validasi klip V-JEPA 2 menolak visualisasi.

plot_samples=8 membatasi plot sampel terpisah; 0 menonaktifkannya dan -1 mempertahankan semua gambar. Ini tidak mengubah metrik atau keluaran visualisasi.

Validasi selama pelatihan

Pelatihan memvalidasi setiap eval_interval epoch, dan selalu setelah epoch terakhir, terhadap dataset's val split, dan metrik yang dihasilkannya adalah yang menjadi penggerak pemilihan best.pt, patience early stop, dan val/ kunci di setiap logger. Validasi dijalankan pada bobot EMA ketika EMA aktif. Berkasnya masuk ke direktori val/ di dalam run. val=False mematikan validasi selama pelatihan, termasuk pada epoch terakhir.

Lihat Hyperparameters untuk eval_interval, patience dan save_plots, serta Experiment loggers untuk di mana angkanya pergi.

Terkait

• Dataset untuk kunci split dan validator format dibaca.