Esquema de checkpoint

Esquema v1.0

Todo checkpoint .pt oficial do LibreYOLO contém:

{    "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 é um destes: detect, segment, semantic, panoptic, pose, classify, gaze, obb, point, depth, edge, normal, restore, matte, ocr, embed ou mesh.

Os checkpoints oficiais escrevem todas as chaves de names. Os leitores podem preencher chaves ausentes com rótulos class_i para mapeamentos esparsos legados, mas chaves fora do intervalo são inválidas.

Checkpoints retangulares mantêm um imgsz escalar para leitores legados, definido como max(imgsz_h, imgsz_w), e escrevem adicionalmente imgsz_h e imgsz_w com as dimensões reais. Um leitor que entenda os campos retangulares deve preferi-los ao escalar. Famílias com contrato retangular fixo, como o pose da HRNet, rejeitam tamanhos de runtime incompatíveis.

Checkpoints de classificação podem adicionar interpolation, o filtro de resize do modelo: "bilinear", "bicubic", "nearest" ou "bilinear_no_antialias". save(), best.pt e last.pt o escrevem e o carregamento o restaura, então treinamento, val(), predict(), calibração INT8 e exportação mantêm o filtro com o qual o checkpoint foi salvo. Um checkpoint sem a chave mantém o padrão da família, e qualquer outro valor é inválido. Os três primeiros redimensionam com o Pillow, que faz antialiasing ao reduzir; "bilinear_no_antialias" é bilinear puro com centros de meio pixel e sem antialiasing.

O esquema é deliberadamente plano, e model é deliberadamente um state dict.

from libreyolo import LibreYOLOfrom libreyolo.utils.serialization import unwrap_libreyolo_checkpointimport torch # Baixe um checkpoint e salve de novo para que exista um caminho local.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")

Acréscimos de pose

Checkpoints de pose registram seu esquema de classes e keypoints. YOLO-NAS suporta várias classes com um esqueleto compartilhado; RF-DETR também suporta contagens de keypoints por classe. nc e names descrevem as classes. Exportações de pose em runtime emitem scores com dimensões [batch, anchors, nc].

RF-DETR pode registrar num_keypoints_per_class junto de kpt_names. As contagens se alinham às classes do dataset; zero indica uma classe só de caixas, e as predições são preenchidas até a dimensão máxima de keypoints.

Acréscimos de mesh

Checkpoints de mesh usam task: "mesh", nc: 1 e names: {0: "person"}. Os layouts de parâmetros diferem entre modelos de corpo, então as dimensões são registradas em vez de presumidas.

Placeholders de tarefas densas

Várias tarefas predizem mapas densos em vez de classes, então os slots parecidos com classe existem apenas por compatibilidade de esquema.

Predições de bordas são mapas densos de probabilidade float32 em [0, 1].

Checkpoints de restore podem adicionar degradation, um rótulo curto de corrupção como deblur, denoise ou super-resolution; dataset, um rótulo de proveniência como GoPro ou SIDD; e scale, um fator inteiro positivo de aumento de escala da saída em relação à entrada, por exemplo 4 para um modelo de super-resolução x4. Ausente ou 1 significa que a imagem restaurada mantém a resolução de entrada. O runtime também deriva a escala a partir da família e do tamanho, então scale é metadado de proveniência e não um requisito de carregamento.

Acréscimos de OCR

A família ppocr distribui um checkpoint composto por tier, cujo state dict de model guarda dois submodelos sob os namespaces de chave det.* e rec.*.

Metadados de runtime de exportação

Os artefatos exportados usam a mesma convenção de escrita dupla para o caso retangular: imgsz_h e imgsz_w são escritos ao lado do escalar legado imgsz, e um leitor que não entenda os campos retangulares não deve tratar silenciosamente o escalar como um contrato quadrado.

O suporte retangular em runtime tem escopo por família e por formato. Exportações da família YOLO9, HRNet, NAFNet e Real-ESRGAN podem usar imgsz_h e imgsz_w não quadrados nos formatos suportados; famílias ou formatos sem suporte retangular explícito rejeitam os metadados em vez de pré-processar esses artefatos como quadrados. As exportações de HRNet são cabeças fixas, de batch um, FP32 e sobre recorte de pessoa, em que a W32 aceita 256x192 e a W48 aceita 384x288, e o detector de pessoas não está embutido no grafo.

Exportações com NMS embutido podem adicionar estas chaves planas:

Para exportações ONNX de detecção da YOLO9 com nms=true, a saída 0 (chamada output) é o tensor pós-NMS autônomo nos limiares definidos na exportação. Quando nms_raw_output=true, a saída 1 (chamada raw) fica reservada para os backends do LibreYOLO, para que eles possam aplicar o recorte nativo no canvas original e a semântica de runtime de predict(conf=..., iou=..., max_det=...). Consumidores de terceiros devem usar a primeira saída.

Exportações de pose podem adicionar num_keypoints; keypoint_dim, em que exportações brutas no estilo GroupPose podem usar valores maiores, como 8, quando o tensor inclui campos de precisão ou de logits de classe; num_keypoints_per_class como uma lista codificada em JSON, em que os slots de classe com zero keypoints precisam ser preservados porque definem o esquema; e pose_input, em que "person_crop" significa que o grafo consome um recorte já extraído e não contém detector. As exportações de runtime da HRNet exigem esse valor.

Exportações de classificação podem adicionar crop_pct, uma razão float de recorte central cujo alvo de redimensionamento antes do recorte é floor(imgsz / crop_pct) e que assume 0.875 por padrão quando ausente, e interpolation, um dos quatro valores de checkpoint acima, com padrão "bilinear" quando ausente; os leitores rejeitam qualquer outro valor.

Exportações ExecuTorch escrevem os metadados planos em um sidecar <program>.pte.json obrigatório. O contrato da v1 é CPU, FP32, batch 1 e canvas de entrada fixo, e exige adicionalmente executorch_version, executorch_delegate igual a "xnnpack" e um executorch_delegate_partitions positivo. O loader rejeita um sidecar que declare outro delegate, shapes dinâmicos ou precisão diferente de FP32.

Exportações MNN escrevem os metadados planos em um sidecar <model>.mnn.json obrigatório. O contrato da v1 é CPU, FP32, somente detecção e shape de entrada NCHW fixo, e exige adicionalmente mnn_version, mnn_backend igual a "cpu", mnn_input_names e mnn_output_names ordenados e não vazios, mnn_input_shape como quatro inteiros positivos na ordem [batch, channels, height, width], e mnn_batch igual a mnn_input_shape[0]. O loader rejeita metadados de shape dinâmicos, não FP32, que não sejam de detecção, de família não suportada ou inconsistentes.

Um .pte e um .mnn são artefatos específicos de backend, não checkpoints do PyTorch.

Classificadores registram norm_mean, norm_std e resize_mode. Telas retangulares mantêm imgsz_h e imgsz_w. O letterbox_pad do YOLO9 é topleft ou center; metadados ausentes mantêm a geometria legada no canto superior esquerdo.

Checkpoints quantizados

Um modelo quantizado adiciona uma chave plana opcional, quant, que guarda um dict de manifesto com schema, recipe, keep_high_precision, execution, proveniência de calibração, module_count e state. Manifestos FP8 também podem carregar fp8_tensorwise_weights, a lista exata de nomes de módulos QuantLinear cuja escala de peso é por tensor em vez de por canal de saída. Um loader que veja quant reconstrói a estrutura dos módulos quantizados e a política de escalonamento antes do load_state_dict.

state distingue as duas formas de artefato.

"prepared", o padrão, guarda pesos mestres FP32 mais buffers de escala _q_* e é treinável. Um leitor sem suporte a quantização pode ignorar a chave quant e carregar os mestres como um modelo float.

"finalized" é a forma de deploy escrita por export(format="pt"). Os mestres são removidos e cada módulo quantizado carrega, em vez deles, pesos empacotados:

Os buffers de faixa de ativação _q_act_lo, _q_act_hi e _q_calibrated são mantidos para int8. O manifesto registra remainder, "fp16" ou "fp32", para os tensores não quantizados. O desempacotamento reproduz a simulação bit a bit, então a inferência finalizada bate exatamente com a inferência preparada no dispositivo em que a finalização ocorreu. Esse layout é o contrato estável para exportadores e runtimes externos.

Checkpoints de treinamento

Os checkpoints do trainer usam o mesmo núcleo de metadados obrigatórios e podem adicionar campos planos de treinamento e de retomada:

{    "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 declara se o model de primeiro nível é suavizado por EMA. Quando a EMA está habilitada, train_model, ema e ema_updates preservam o estado de retomada. Pesos publicados para inferência devem ser enxutos e não devem incluir optimizer, epoch, config, loss nem estado de retomada de EMA, a menos que sejam distribuídos intencionalmente como checkpoints de treinamento.

Por compatibilidade entre versões, os leitores aceitam os aliases legados de melhor métrica best_mAP50_95, best_mAP50, best_metric e best_metric_name.

A seleção personalizada registra fitness_source="callback" e best_metric_key="fitness/custom". O código e o estado do callback não são salvos; essas execuções não podem ser retomadas. Inicie uma nova execução a partir de seus pesos.

Snapshots externos

O esquema rege os arquivos .pt escritos pelo LibreYOLO. Ele não renomeia nem envolve snapshots upstream de múltiplos arquivos usados pelos tiers de modelo separados.

O LibreMODUS de tamanho 14b-a7b é uma exceção explícita: o alias resolve, via LibreVLM(...), para um diretório de arquivos upstream fixados, e o LibreYOLO não adiciona metadados v1.0 a ele nem o republica como um .pt.

Pesos legados e de terceiros

Novos escritores validam de forma estrita e precisam emitir metadados v1.0. Quando os metadados estão ausentes ou incompletos, checkpoints legados com cara de LibreYOLO carregam pelo caminho de compatibilidade, com um aviso e instruções de conversão, e checkpoints upstream de terceiros são roteados para a conversão automática. Veja checkpoints upstream.

Helpers

Os helpers do esquema ficam em 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 não altera nada e retorna a lista de erros; com strict=True ele levanta CheckpointMetadataError em vez disso. model.save(path) é a forma suportada de escrever um checkpoint conforme.

Perfis de entrada

Checkpoints de histogramas de duas polaridades preservam o input_profile completo, incluindo formato, layout, polaridade, codificação, escala e duração da janela, além de input_initialization. O recarregamento para predição não precisa do YAML do dataset; treinamento/validação rejeitam perfis incompatíveis. Veja histogramas de eventos.