Skema checkpoint

Skema v1.0

Setiap checkpoint .pt resmi LibreYOLO memuat:

{
    "model": state_dict,
    "schema_version": "1.0",
    "libreyolo_version": "0.x.y",
    "model_family": "yolo9",
    "size": "t",
    "task": "detect",
    "nc": 80,
    "names": {0: "cat", 1: "dog"},
    "imgsz": 640,
}

task adalah salah satu dari detect, segment, semantic, panoptic, pose, classify, gaze, obb, point, depth, edge, normal, restore, matte, ocr, embed, atau mesh.

Checkpoint resmi menulis setiap kunci names. Reader dapat menambahkan label class_i untuk kunci yang hilang pada mapping sparse lama, tetapi kunci di luar rentang tidak valid.

Checkpoint rectangle mempertahankan imgsz skalar bagi reader lama, dengan nilai max(imgsz_h, imgsz_w), dan juga menulis imgsz_h serta imgsz_w dengan dimensi sebenarnya. Reader yang memahami kolom rectangle harus memprioritaskannya daripada skalar. Family dengan kontrak rectangle tetap, seperti pose HRNet, menolak ukuran runtime yang tidak kompatibel.

Skema sengaja dibuat flat, dan model sengaja berupa state dict.

from libreyolo import LibreYOLOfrom libreyolo.utils.serialization import unwrap_libreyolo_checkpointimport torch # Unduh checkpoint, lalu simpan ulang agar tersedia path lokal.LibreYOLO("LibreYOLO9t.pt").save("roundtrip.pt") loaded = torch.load("roundtrip.pt", map_location="cpu", weights_only=False)state_dict, metadata = unwrap_libreyolo_checkpoint(loaded) print(metadata["schema_version"], metadata["model_family"])print(metadata["size"], metadata["task"], metadata["nc"], metadata["imgsz"])print(len(state_dict), "tensors")

Tambahan pose

Pose biasanya satu kelas, nc: 1 dengan person, tetapi head pose YOLO-NAS juga mendukung pose multi-kelas dengan satu skeleton keypoint bersama. Dalam kasus itu, nc dan names menjelaskan kelas seperti dalam deteksi. Ekspor pose runtime menghasilkan scores berbentuk [batch, anchors, nc].

Tambahan mesh

Checkpoint mesh menggunakan task: "mesh", nc: 1, dan names: {0: "person"}. Tata letak parameter berbeda antar body model, sehingga dimensinya dicatat, bukan diasumsikan.

Placeholder task padat

Beberapa task memprediksi map padat, bukan kelas, sehingga slot mirip kelas hanya ada untuk kompatibilitas skema.

Prediksi edge adalah map probabilitas float32 padat dalam [0, 1].

Checkpoint restore dapat menambahkan degradation, label kerusakan pendek seperti deblur, denoise, atau super-resolution; dataset, label asal seperti GoPro atau SIDD; serta scale, faktor upscale output terhadap input bilangan bulat positif, misalnya 4 untuk model super-resolution x4. Nilai yang tidak ada atau 1 berarti gambar hasil restorasi mempertahankan resolusi input. Runtime juga menurunkan skala dari family dan ukuran, sehingga scale merupakan metadata asal, bukan persyaratan saat pemuatan.

Tambahan OCR

Family ppocr menyediakan satu checkpoint komposit per tier, dengan state dict model yang menyimpan dua submodel di bawah namespace kunci det.* dan rec.*.

Metadata runtime ekspor

Artefak hasil ekspor menggunakan konvensi dual-write rectangle yang sama: imgsz_h dan imgsz_w ditulis di samping imgsz skalar lama, dan reader yang tidak memahami kolom rectangle tidak boleh diam-diam memperlakukan skalar sebagai kontrak persegi.

Dukungan runtime rectangle dibatasi family dan format. Ekspor family YOLO9, HRNet, NAFNet, dan Real-ESRGAN dapat menggunakan imgsz_h dan imgsz_w nonpersegi dalam format yang didukung; family atau format tanpa dukungan rectangle eksplisit menolak metadata, bukan melakukan preprocessing artefak sebagai persegi. Ekspor HRNet adalah head person-crop tetap, batch satu, FP32, dengan W32 menerima 256x192 dan W48 menerima 384x288, serta detektor orang tidak disematkan dalam graph.

Ekspor dengan NMS tertanam dapat menambahkan kunci flat berikut:

Untuk ekspor deteksi ONNX YOLO9 dengan nms=true, output 0 (bernama output) adalah tensor pasca-NMS mandiri pada ambang batas waktu ekspor. Ketika nms_raw_output=true, output 1 (bernama raw) dicadangkan bagi backend LibreYOLO agar dapat menerapkan clipping canvas asli native dan semantik runtime predict(conf=..., iou=..., max_det=...). Konsumen pihak ketiga sebaiknya menggunakan output pertama.

Ekspor pose dapat menambahkan num_keypoints; keypoint_dim, dengan ekspor mentah bergaya GroupPose mungkin menggunakan nilai lebih besar seperti 8 ketika tensor memuat kolom presisi atau logit kelas; num_keypoints_per_class sebagai list berformat JSON, dengan slot kelas tanpa keypoint harus dipertahankan karena mendefinisikan skema; dan pose_input, dengan "person_crop" berarti graph menerima satu crop yang sudah diekstrak dan tidak memuat detektor. Ekspor runtime HRNet mewajibkan nilai tersebut.

Ekspor classification dapat menambahkan crop_pct, rasio center-crop float dengan target resize pracrop round(imgsz / crop_pct) dan default 0.875 jika tidak ada, serta interpolation, "bilinear" atau "bicubic", dengan default "bilinear".

Ekspor ExecuTorch menulis metadata flat ke sidecar wajib <program>.pte.json. Kontrak v1 adalah CPU, FP32, batch 1, dan canvas input tetap, serta mewajibkan executorch_version, executorch_delegate bernilai "xnnpack", dan executorch_delegate_partitions positif. Loader menolak sidecar yang menyatakan delegate lain, bentuk dinamis, atau presisi selain FP32.

Ekspor MNN menulis metadata flat ke sidecar wajib <model>.mnn.json. Kontrak v1 adalah CPU, FP32, khusus deteksi, dan bentuk input NCHW tetap, serta mewajibkan mnn_version, mnn_backend bernilai "cpu", mnn_input_names dan mnn_output_names terurut serta tidak kosong, mnn_input_shape berupa empat bilangan bulat positif dalam urutan [batch, channels, height, width], dan mnn_batch sama dengan mnn_input_shape[0]. Loader menolak metadata dinamis, selain FP32, selain deteksi, family tidak didukung, atau bentuk tidak konsisten.

Berkas .pte dan .mnn merupakan artefak khusus backend, bukan checkpoint PyTorch.

Checkpoint terkuantisasi

Model terkuantisasi menambahkan satu kunci flat opsional, quant, yang menyimpan dict manifest dengan schema, recipe, keep_high_precision, execution, asal kalibrasi, module_count, dan state. Manifest FP8 juga dapat memuat fp8_tensorwise_weights, list tepat nama modul QuantLinear yang skala bobotnya bersifat tensorwise, bukan per output channel. Loader yang melihat quant membangun ulang struktur modul terkuantisasi dan kebijakan scaling sebelum load_state_dict.

state membedakan dua bentuk artefak.

"prepared", yang merupakan default, menyimpan master weight FP32 ditambah buffer skala _q_* dan dapat dilatih. Reader tanpa dukungan kuantisasi dapat mengabaikan kunci quant dan memuat master sebagai model float.

"finalized" adalah bentuk deployment yang ditulis oleh export(format="pt"). Master dihapus dan setiap modul terkuantisasi menyimpan bobot terkemas:

Buffer rentang aktivasi _q_act_lo, _q_act_hi, dan _q_calibrated dipertahankan untuk int8. Manifest mencatat remainder, "fp16" atau "fp32", bagi tensor yang tidak dikuantisasi. Unpacking mereproduksi simulasi bit demi bit, sehingga inferensi finalized sama persis dengan inferensi prepared pada device finalisasi. Tata letak ini adalah kontrak stabil bagi exporter dan runtime eksternal.

Checkpoint pelatihan

Checkpoint trainer menggunakan inti metadata wajib yang sama dan dapat menambahkan kolom flat pelatihan serta resume:

{
    "model": state_dict,
    "epoch": 42,
    "optimizer": optimizer_state_dict,
    "config": {},
    "loss": 1.23,
    "best_metric_key": "metrics/mAP50-95",
    "best_metric_value": 0.51,
    "best_epoch": 39,
    "is_ema_weights": True,
    "train_model": raw_state_dict,
    "ema": ema_state_dict,
    "ema_updates": 12345,
}

is_ema_weights menyatakan apakah model top-level telah dihaluskan EMA. Ketika EMA diaktifkan, train_model, ema, dan ema_updates mempertahankan status resume. Bobot inferensi yang dipublikasikan sebaiknya ramping dan tidak menyertakan optimizer, epoch, konfigurasi, loss, atau status resume EMA kecuali sengaja didistribusikan sebagai checkpoint pelatihan.

Untuk kompatibilitas rilis, reader menerima alias metrik terbaik lama best_mAP50_95, best_mAP50, best_metric, dan best_metric_name.

Snapshot eksternal

Skema mengatur berkas .pt yang dibuat LibreYOLO. Skema tidak mengganti nama atau membungkus snapshot upstream multi-berkas yang digunakan oleh tier model terpisah.

LibreMODUS ukuran 14b-a7b adalah pengecualian eksplisit: alias diselesaikan melalui LibreVLM(...) ke direktori berkas upstream yang dikunci versinya, dan LibreYOLO tidak menambahkan metadata v1.0 maupun memublikasikannya kembali sebagai .pt.

Bobot lama dan asing

Writer baru melakukan validasi ketat dan wajib menghasilkan metadata v1.0. Jika metadata tidak ada atau tidak lengkap, checkpoint yang tampak seperti LibreYOLO lama dimuat melalui jalur kompatibilitas dengan peringatan dan petunjuk konversi, sedangkan checkpoint upstream asing diarahkan ke konversi otomatis. Lihat checkpoint upstream.

Helper

Helper skema berada dalam libreyolo.utils.serialization:

wrap_libreyolo_checkpoint(
    state_dict,
    *,
    model_family,
    size,
    task,
    nc,
    names=None,
    imgsz=None,
    libreyolo_version=None,
    schema_version="1.0",
    **extra_metadata,
) -> dict

validate_checkpoint_metadata(checkpoint, *, strict=False) -> list[str]

unwrap_libreyolo_checkpoint(loaded, *, strict=False) -> tuple[dict, dict]

validate_checkpoint_metadata tidak melakukan mutasi dan mengembalikan list error; dengan strict=True, metode ini memunculkan CheckpointMetadataError. model.save(path) adalah cara yang didukung untuk menulis checkpoint yang sesuai.