Schema del checkpoint

Schema v1.0

Ogni checkpoint .pt ufficiale di LibreYOLO contiene:

{
    "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 è uno tra detect, segment, semantic, panoptic, pose, classify, gaze, obb, point, depth, edge, normal, restore, matte, ocr, embed o mesh.

I checkpoint ufficiali scrivono tutte le chiavi di names. I lettori possono riempire le chiavi mancanti con etichette class_i per le vecchie mappature sparse, ma le chiavi fuori intervallo non sono valide.

I checkpoint rettangolari mantengono un imgsz scalare per i lettori legacy, impostato a max(imgsz_h, imgsz_w), e scrivono in aggiunta imgsz_h e imgsz_w con le dimensioni reali. Un lettore che comprende i campi rettangolari deve preferirli allo scalare. Le famiglie con un contratto rettangolare fisso, come HRNet pose, rifiutano le dimensioni di runtime incompatibili.

Lo schema è volutamente piatto, e model è volutamente uno state dict.

from libreyolo import LibreYOLOfrom libreyolo.utils.serialization import unwrap_libreyolo_checkpointimport torch # Scarica un checkpoint, poi risalvalo così esiste un percorso locale.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")

Aggiunte per la stima della posa

La posa di solito è a classe singola, nc: 1 con person, ma la testa pose di YOLO-NAS supporta anche la posa multiclasse con un unico scheletro di keypoint condiviso, nel qual caso nc e names descrivono le classi come nel rilevamento. Le esportazioni pose di runtime emettono scores con forma [batch, anchors, nc].

Aggiunte per le mesh

I checkpoint mesh usano task: "mesh", nc: 1 e names: {0: "person"}. La disposizione dei parametri cambia tra i modelli del corpo, quindi le dimensioni vengono registrate anziché date per scontate.

Segnaposto per i task densi

Diversi task predicono mappe dense anziché classi, quindi gli slot legati alle classi esistono solo per compatibilità con lo schema.

Le predizioni edge sono mappe di probabilità dense float32 in [0, 1].

I checkpoint restore possono aggiungere degradation, una breve etichetta di corruzione come deblur, denoise o super-resolution; dataset, un'etichetta di provenienza come GoPro o SIDD; e scale, un fattore intero positivo di ingrandimento da input a output, per esempio 4 per un modello di super-risoluzione x4. Assente o 1 significa che l'immagine ripristinata mantiene la risoluzione dell'input. Il runtime deriva la scala anche dalla famiglia e dalla size, quindi scale è un metadato di provenienza più che un requisito al caricamento.

Aggiunte per l'OCR

La famiglia ppocr distribuisce un checkpoint composito per ogni tier, il cui state dict model contiene due sottomodelli sotto gli spazi di nomi di chiave det.* e rec.*.

Metadati di runtime dell'esportazione

Gli artefatti esportati usano la stessa convenzione di doppia scrittura per il caso rettangolare: imgsz_h e imgsz_w sono scritti accanto allo scalare legacy imgsz, e un lettore che non comprende i campi rettangolari non deve trattare silenziosamente lo scalare come un contratto quadrato.

Il supporto rettangolare a runtime dipende dalla famiglia e dal formato. Le esportazioni della famiglia YOLO9, di HRNet, NAFNet e Real-ESRGAN possono usare imgsz_h e imgsz_w non quadrati nei formati supportati; le famiglie o i formati senza supporto rettangolare esplicito rifiutano i metadati anziché preelaborare quegli artefatti come quadrati. Le esportazioni HRNet sono teste fisse, batch uno, FP32 su ritagli di persona, dove W32 accetta 256x192 e W48 accetta 384x288, e il rilevatore di persone non è incorporato nel grafo.

Le esportazioni con NMS incorporato possono aggiungere queste chiavi piatte:

Per le esportazioni ONNX di rilevamento YOLO9 con nms=true, l'output 0 (chiamato output) è il tensore post-NMS autonomo alle soglie fissate in fase di esportazione. Quando nms_raw_output=true, l'output 1 (chiamato raw) è riservato ai backend LibreYOLO, così da poter applicare il ritaglio nativo sul canvas originale e la semantica di runtime di predict(conf=..., iou=..., max_det=...). I consumatori di terze parti dovrebbero usare il primo output.

Le esportazioni pose possono aggiungere num_keypoints; keypoint_dim, dove le esportazioni grezze in stile GroupPose possono usare valori più grandi come 8 quando il tensore include campi di precisione o logit di classe; num_keypoints_per_class come lista codificata in JSON, dove gli slot di classe con zero keypoint vanno preservati perché definiscono lo schema; e pose_input, dove "person_crop" significa che il grafo consuma un ritaglio già estratto e non contiene alcun rilevatore. Le esportazioni HRNet di runtime richiedono quel valore.

Le esportazioni di classificazione possono aggiungere crop_pct, un rapporto float di ritaglio centrale il cui obiettivo di ridimensionamento prima del ritaglio è round(imgsz / crop_pct) e che vale 0.875 quando è assente, e interpolation, "bilinear" o "bicubic", con valore predefinito "bilinear".

Le esportazioni ExecuTorch scrivono i metadati piatti in un file affiancato <program>.pte.json obbligatorio. Il contratto v1 è CPU, FP32, batch 1 e canvas di input fisso, e richiede in aggiunta executorch_version, executorch_delegate uguale a "xnnpack" e un executorch_delegate_partitions positivo. Il loader rifiuta un file affiancato che dichiari un altro delegate, forme dinamiche o precisione diversa da FP32.

Le esportazioni MNN scrivono i metadati piatti in un file affiancato <model>.mnn.json obbligatorio. Il contratto v1 è CPU, FP32, solo rilevamento e forma di input NCHW fissa, e richiede in aggiunta mnn_version, mnn_backend uguale a "cpu", mnn_input_names e mnn_output_names ordinati e non vuoti, mnn_input_shape come quattro interi positivi nell'ordine [batch, channels, height, width], e mnn_batch uguale a mnn_input_shape[0]. Il loader rifiuta metadati di forma dinamici, non FP32, non di rilevamento, di famiglie non supportate o incoerenti.

Un .pte e un .mnn sono artefatti specifici del backend, non checkpoint PyTorch.

Checkpoint quantizzati

Un modello quantizzato aggiunge una chiave piatta opzionale, quant, che contiene un manifest dict con schema, recipe, keep_high_precision, execution, la provenienza della calibrazione, module_count e state. I manifest FP8 possono portare anche fp8_tensorwise_weights, l'elenco esatto dei nomi dei moduli QuantLinear la cui scala dei pesi è per tensore anziché per canale di output. Un loader che vede quant ricostruisce la struttura dei moduli quantizzati e la politica di scaling prima di load_state_dict.

state distingue le due forme di artefatto.

"prepared", il valore predefinito, contiene i pesi master FP32 più i buffer di scala _q_* ed è addestrabile. Un lettore senza supporto alla quantizzazione può ignorare la chiave quant e caricare i master come modello float.

"finalized" è la forma di deployment scritta da export(format="pt"). I master vengono rimossi e ogni modulo quantizzato porta invece pesi impacchettati:

I buffer di intervallo delle attivazioni _q_act_lo, _q_act_hi e _q_calibrated sono conservati per int8. Il manifest registra remainder, "fp16" o "fp32", per i tensori non quantizzati. Lo spacchettamento riproduce la simulazione bit per bit, quindi l'inferenza finalized coincide esattamente con quella prepared sul dispositivo che esegue la finalizzazione. Questa disposizione è il contratto stabile per esportatori e runtime esterni.

Checkpoint di addestramento

I checkpoint del trainer usano lo stesso nucleo di metadati obbligatori e possono aggiungere campi piatti di addestramento e di ripresa:

{
    "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 dichiara se il model di primo livello è stato smussato con EMA. Quando l'EMA è attiva, train_model, ema e ema_updates preservano lo stato di ripresa. I pesi di inferenza pubblicati dovrebbero essere snelli e non dovrebbero includere optimizer, epoca, config, loss o stato di ripresa EMA, a meno che non vengano distribuiti intenzionalmente come checkpoint di addestramento.

Per compatibilità tra release, i lettori accettano i vecchi alias della metrica migliore best_mAP50_95, best_mAP50, best_metric e best_metric_name.

Snapshot esterni

Lo schema governa i file .pt prodotti da LibreYOLO. Non rinomina né incapsula gli snapshot upstream multi-file usati dai tier di modelli separati.

La size 14b-a7b di LibreMODUS è un'eccezione esplicita: l'alias si risolve attraverso LibreVLM(...) in una directory di file upstream fissati, e LibreYOLO non le aggiunge i metadati v1.0 né la ripubblica come .pt.

Pesi legacy e di terze parti

I nuovi writer validano in modo rigoroso e devono emettere i metadati v1.0. Quando i metadati mancano o sono incompleti, i checkpoint legacy che sembrano LibreYOLO si caricano attraverso il percorso di compatibilità con un avviso e le istruzioni di conversione, mentre i checkpoint upstream di terze parti vengono instradati alla conversione automatica. Vedi checkpoint upstream.

Helper

Gli helper dello schema vivono in 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 non muta nulla e restituisce l'elenco degli errori; con strict=True solleva invece CheckpointMetadataError. model.save(path) è il modo supportato per scrivere un checkpoint conforme.