Схема контрольної точки

Схема 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 для застарілих розріджених відповідностей, але ключі поза діапазоном недійсні.

Прямокутні контрольні точки зберігають скаляр imgsz для застарілих засобів читання, установлений як max(imgsz_h, imgsz_w), і додатково записують imgsz_h та imgsz_w зі справжніми розмірами. Засіб читання, що розуміє прямокутні поля, має надавати їм перевагу над скаляром. Сімейства з фіксованим прямокутним контрактом, як-от HRNet pose, відхиляють несумісні розміри середовища виконання.

Схема навмисно плоска, а model навмисно є словником стану.

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")

Доповнення для пози

Поза зазвичай однокласова, nc: 1 із person, але голова пози YOLO-NAS також підтримує багатокласову позу з одним спільним скелетом ключових точок. У такому разі nc і names описують класи як у виявленні. Експортовані моделі пози для середовища виконання повертають scores із формою [batch, anchors, nc].

Доповнення для сітки

Контрольні точки сітки використовують task: "mesh", nc: 1 і names: {0: "person"}. Структури параметрів відрізняються між моделями тіла, тому розміри записуються, а не припускаються.

Заповнювачі для щільних завдань

Кілька завдань передбачають щільні карти, а не класи, тому поля, подібні до класів, існують лише для сумісності зі схемою.

Передбачення країв є щільними картами ймовірностей float32 у [0, 1].

Контрольні точки відновлення можуть додавати degradation, коротку мітку спотворення на кшталт deblur, denoise або super-resolution; dataset, мітку походження на кшталт GoPro або SIDD; і scale, додатний цілий коефіцієнт масштабування виходу відносно входу, наприклад 4 для моделі підвищення роздільної здатності x4. Відсутнє значення або 1 означає, що відновлене зображення зберігає роздільну здатність вхідного. Середовище виконання також визначає масштаб із сімейства й розміру, тому scale є метаданими походження, а не вимогою під час завантаження.

Доповнення для OCR

Сімейство ppocr постачає одну складену контрольну точку на рівень, де словник стану model містить дві підмоделі в просторах ключів det.* і rec.*.

Метадані середовища виконання експорту

Експортовані артефакти використовують ту саму домовленість подвійного запису для прямокутників: imgsz_h і imgsz_w записуються поруч із застарілим скаляром imgsz, а засіб читання, що не розуміє прямокутних полів, не повинен непомітно трактувати скаляр як квадратний контракт.

Підтримка прямокутників у середовищі виконання залежить від сімейства та формату. Експортовані моделі сімейства YOLO9, HRNet, NAFNet і Real-ESRGAN можуть використовувати неквадратні imgsz_h та imgsz_w у підтримуваних форматах; сімейства чи формати без явної підтримки прямокутників відхиляють метадані, а не обробляють такі артефакти як квадратні. Експортовані моделі HRNet є фіксованими головами кадрування людини з батчем один і FP32, де W32 приймає 256x192, а W48 приймає 384x288; детектор людей у граф не вбудовано.

Експортовані моделі з убудованим NMS можуть додавати такі плоскі ключі:

Для експортованих моделей виявлення ONNX YOLO9 з nms=true вихід 0 (названий output) є самостійним тензором після NMS із порогами часу експорту. Коли nms_raw_output=true, вихід 1 (названий raw) зарезервовано для бекендів LibreYOLO, щоб вони могли застосовувати власне обрізання за початковим полотном і семантику середовища виконання predict(conf=..., iou=..., max_det=...). Стороннім споживачам слід використовувати перший вихід.

Експортовані моделі пози можуть додавати num_keypoints; keypoint_dim, де необроблений експорт у стилі GroupPose може використовувати більші значення, наприклад 8, коли тензор містить поля точності чи логітів класу; num_keypoints_per_class як список у кодуванні JSON, де потрібно зберігати позиції класів із нульовою кількістю ключових точок, бо вони визначають схему; і pose_input, де "person_crop" означає, що граф приймає один уже виділений фрагмент і не містить детектора. Експорт HRNet для середовища виконання потребує цього значення.

Експортовані моделі класифікації можуть додавати crop_pct, коефіцієнт центрального обрізання з рухомою комою, де цільовим розміром до обрізання є round(imgsz / crop_pct) і типове значення за відсутності дорівнює 0.875, а також interpolation, "bilinear" або "bicubic", типово "bilinear".

Експорт ExecuTorch записує плоскі метадані до обов'язкового супровідного файла <program>.pte.json. Контракт v1 передбачає CPU, FP32, батч 1 і фіксоване полотно вхідних даних, а також вимагає executorch_version, executorch_delegate зі значенням "xnnpack" і додатне executorch_delegate_partitions. Завантажувач відхиляє супровідний файл, що вказує інший делегат, динамічні форми або точність, відмінну від FP32.

Експорт MNN записує плоскі метадані до обов'язкового супровідного файла <model>.mnn.json. Контракт v1 передбачає CPU, FP32, лише виявлення об'єктів і фіксовану форму входу NCHW, а також вимагає mnn_version, mnn_backend зі значенням "cpu", упорядковані непорожні mnn_input_names і mnn_output_names, mnn_input_shape як чотири додатні цілі числа в порядку [batch, channels, height, width] і mnn_batch, що дорівнює mnn_input_shape[0]. Завантажувач відхиляє динамічні метадані, відмінну від FP32 точність, інше завдання, непідтримуване сімейство чи неузгоджену форму.

Файли .pte і .mnn є артефактами окремих бекендів, а не контрольними точками PyTorch.

Квантовані контрольні точки

Квантована модель додає один необов'язковий плоский ключ quant, що містить словник маніфесту зі schema, recipe, keep_high_precision, execution, походженням калібрування, module_count і state. Маніфести FP8 також можуть містити fp8_tensorwise_weights, точний список назв модулів QuantLinear, для яких масштаб ваг застосовується до всього тензора, а не до кожного вихідного каналу. Завантажувач, що бачить quant, відтворює структуру квантованих модулів і політику масштабування перед load_state_dict.

state розрізняє дві форми артефакту.

"prepared", типове значення, містить основні ваги FP32 разом із буферами масштабу _q_* і придатне до навчання. Засіб читання без підтримки квантування може ігнорувати ключ quant і завантажити основні ваги як модель із рухомою комою.

"finalized" є формою для розгортання, яку записує export(format="pt"). Основні ваги вилучаються, і кожен квантований модуль натомість містить упаковані ваги:

Буфери діапазону активацій _q_act_lo, _q_act_hi та _q_calibrated зберігаються для int8. Маніфест записує remainder, "fp16" або "fp32", для неквантованих тензорів. Розпакування побітово відтворює симуляцію, тому інференс фіналізованої моделі точно збігається з інференсом підготовленої на пристрої фіналізації. Ця структура є стабільним контрактом для зовнішніх експортерів і середовищ виконання.

Контрольні точки навчання

Контрольні точки засобу навчання використовують те саме обов'язкове ядро метаданих і можуть додавати плоскі поля навчання та відновлення:

{
    "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 зберігають стан для відновлення. Опубліковані ваги для інференсу мають бути компактними й не повинні містити оптимізатор, епоху, конфігурацію, функцію втрат або стан відновлення EMA, якщо їх навмисно не розповсюджують як контрольні точки навчання.

Для сумісності з випусками засоби читання приймають застарілі псевдоніми найкращої метрики best_mAP50_95, best_mAP50, best_metric і best_metric_name.

Зовнішні знімки стану

Схема регулює файли .pt, створені LibreYOLO. Вона не перейменовує й не обгортає багатофайлові знімки стану оригінальних реалізацій, які використовують окремі рівні моделей.

Розмір 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).