チェックポイントスキーマ

スキーマv1.0

公式のLibreYOLO .ptチェックポイントには、次の項目がすべて含まれます。

{
    "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はdetect、segment、semantic、panoptic、pose、classify、gaze、obb、point、depth、edge、normal、restore、matte、ocr、embed、meshのいずれかです。

公式チェックポイントはすべてのnamesキーを書き込みます。リーダーはレガシーの疎なマッピングに対し、欠けたキーをclass_iラベルで埋めることがありますが、範囲外のキーは無効です。

長方形チェックポイントは、レガシーリーダー向けにmax(imgsz_h, imgsz_w)を設定したスカラーimgszを維持し、実際の寸法を持つimgsz_hとimgsz_wも書き込みます。長方形フィールドを認識するリーダーは、スカラーよりこれらを優先する必要があります。HRNet姿勢推定のように固定長方形規約を持つファミリーは、互換性のない実行時サイズを拒否します。

スキーマは意図的にフラットで、modelも意図的にstate dictです。

from libreyolo import LibreYOLOfrom libreyolo.utils.serialization import unwrap_libreyolo_checkpointimport torch # チェックポイントをダウンロードしてローカルパスができるように再保存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")

姿勢推定の追加項目

姿勢推定は通常、personを持つ単一クラスのnc: 1です。ただし、YOLO-NASの姿勢推定ヘッドは1つの共有キーポイントスケルトンを使うマルチクラス姿勢推定にも対応します。その場合、ncとnamesは検出と同様にクラスを記述します。姿勢推定のランタイムエクスポートは、形状[batch, anchors, nc]のscoresを出力します。

メッシュの追加項目

メッシュチェックポイントはtask: "mesh"、nc: 1、names: {0: "person"}を使います。パラメータの配置は人体モデル間で異なるため、寸法を仮定せず記録します。

密なタスクのプレースホルダー

複数のタスクはクラスではなく密なマップを予測するため、クラス相当のスロットはスキーマ互換性のためだけに存在します。

エッジ予測は[0, 1]内の密なfloat32確率マップです。

復元チェックポイントは、deblur、denoise、super-resolutionなどの短い破損ラベルdegradation、GoProやSIDDなど出所を示すラベルdataset、出力と入力の正の整数アップスケール係数scaleを追加できます。たとえば、x4超解像モデルでは4です。省略時または1では、復元画像が入力解像度を維持します。ランタイムはファミリーとサイズからもスケールを導出するため、scaleは読み込み時の要件ではなく出所メタデータです。

OCRの追加項目

ppocrファミリーはtierごとに1つの複合チェックポイントを提供し、そのmodel state dictはdet.*とrec.*のキーネームスペースに2つのサブモデルを保持します。

エクスポートランタイムのメタデータ

エクスポートした成果物は同じ長方形の二重書き込み規則を使います。レガシースカラーimgszの横にimgsz_hとimgsz_wを書き込み、長方形フィールドを認識しないリーダーはスカラーを正方形規約として暗黙に扱ってはなりません。

長方形ランタイム対応はファミリーと形式の範囲に限定されます。YOLO9ファミリー、HRNet、NAFNet、Real-ESRGANのエクスポートは、対応形式で正方形でないimgsz_hとimgsz_wを使用できます。長方形に明示対応しないファミリーや形式は、成果物を正方形として前処理せずメタデータを拒否します。HRNetのエクスポートは固定、バッチ1、FP32の人物cropヘッドで、W32は256x192、W48は384x288を受け付け、人物検出器はグラフに組み込まれません。

NMSを組み込んだエクスポートは、次のフラットなキーを追加できます。

nms=trueを指定したONNX YOLO9検出エクスポートでは、出力0（名前はoutput）がエクスポート時のしきい値による単独のNMS後テンソルです。nms_raw_output=trueの場合、出力1（名前はraw）はLibreYOLOバックエンド用に予約され、ネイティブの元キャンバスへのクリップと実行時のpredict(conf=..., iou=..., max_det=...)セマンティクスを適用できます。第三者の利用者は最初の出力を使用してください。

姿勢推定エクスポートはnum_keypointsを追加できます。keypoint_dimでは、テンソルにprecisionまたはclass-logitフィールドを含むGroupPose形式の未加工エクスポートが8などの大きな値を使うことがあります。num_keypoints_per_classはJSONエンコードされたリストで、キーポイントが0個のクラススロットもスキーマを定義するため維持する必要があります。pose_inputでは、"person_crop"がグラフはすでに切り出された1つのcropを消費し、検出器を含まないことを意味します。HRNetランタイムエクスポートにはこの値が必要です。

分類エクスポートはcrop_pctを追加できます。中心crop比率を示す浮動小数点数で、crop前のリサイズ先はround(imgsz / crop_pct)となり、省略時のデフォルトは0.875です。interpolationは"bilinear"または"bicubic"で、デフォルトは"bilinear"です。

ExecuTorchエクスポートは、必須の<program>.pte.jsonサイドカーにフラットなメタデータを書き込みます。v1規約はCPU、FP32、バッチ1、固定入力キャンバスで、さらにexecutorch_version、"xnnpack"と等しいexecutorch_delegate、正のexecutorch_delegate_partitionsを必要とします。別のdelegate、動的形状、FP32以外の精度を主張するサイドカーはローダーが拒否します。

MNNエクスポートは、必須の<model>.mnn.jsonサイドカーにフラットなメタデータを書き込みます。v1規約はCPU、FP32、検出専用、固定NCHW入力形状で、さらにmnn_version、"cpu"と等しいmnn_backend、順序付きで空でないmnn_input_namesとmnn_output_names、[batch, channels, height, width]順の4つの正の整数としてのmnn_input_shape、mnn_input_shape[0]と等しいmnn_batchを必要とします。動的、FP32以外、検出以外、非対応ファミリー、または一貫しない形状のメタデータはローダーが拒否します。

.pteと.mnnはバックエンド固有の成果物であり、PyTorchチェックポイントではありません。

量子化チェックポイント

量子化モデルは、任意のフラットキーquantを1つ追加します。値はschema、recipe、keep_high_precision、execution、較正の出所、module_count、stateを持つマニフェスト辞書です。FP8マニフェストはfp8_tensorwise_weightsも持つことがあり、重みのスケールが出力チャンネルごとではなくテンソル単位であるQuantLinearモジュール名の正確な一覧です。quantを見つけたローダーは、load_state_dictの前に量子化モジュールの構造とスケーリングポリシーを再構築します。

stateは2つの成果物形式を区別します。

デフォルトの"prepared"はFP32のマスター重みと_q_*スケールバッファを保持し、学習可能です。量子化に対応しないリーダーはquantキーを無視し、マスターを浮動小数点モデルとして読み込めます。

"finalized"はexport(format="pt")が書き込むデプロイ形式です。マスターは削除され、代わりに各量子化モジュールがパック済み重みを保持します。

int8では活性化範囲バッファ_q_act_lo、_q_act_hi、_q_calibratedが維持されます。マニフェストは量子化されないテンソルについてremainderを記録し、"fp16"または"fp32"です。展開はシミュレーションをビット単位で再現するため、finalizedの推論はfinalizeを行ったデバイス上でpreparedの推論と完全に一致します。この配置が外部エクスポーターとランタイム向けの安定した規約です。

学習チェックポイント

トレーナーのチェックポイントは同じ必須メタデータの核を使い、フラットな学習フィールドと再開フィールドを追加できます。

{
    "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は最上位のmodelがEMAで平滑化されているかを宣言します。EMAが有効な場合、train_model、ema、ema_updatesが再開状態を維持します。公開する推論用重みは簡潔にし、学習チェックポイントとして意図的に配布する場合を除き、optimizer、epoch、config、loss、EMA再開状態を含めるべきではありません。

リリース互換性のため、リーダーはレガシーの最良メトリクス別名best_mAP50_95、best_mAP50、best_metric、best_metric_nameを受け付けます。

外部スナップショット

このスキーマはLibreYOLOが作成した.ptファイルを管理します。別のモデルtierが使う複数ファイル構成のアップストリームスナップショットを改名またはラップするものではありません。

LibreMODUSサイズ14b-a7bは明示的な例外です。別名はLibreVLM(...)を通じて固定済みアップストリームファイルのディレクトリへ解決され、LibreYOLOはv1.0メタデータを追加せず、.ptとして再公開もしません。

レガシーおよび外部の重み

新しい書き込み処理は厳密に検証し、v1.0メタデータを出力する必要があります。メタデータがない、または不完全な場合、LibreYOLO形式に見えるレガシーチェックポイントは警告と変換手順を伴う互換経路で読み込まれ、外部のアップストリームチェックポイントは自動変換へ振り分けられます。アップストリームチェックポイントを参照してください。

ヘルパー

スキーマヘルパーは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は値を変更せず、エラーの一覧を返します。strict=Trueでは代わりにCheckpointMetadataErrorを発生させます。規約に準拠したチェックポイントを書き込むためにサポートされる方法はmodel.save(path)です。