Оновлення до 1.5.0

Ця сторінка описує оновлення самої LibreYOLO. Якщо ви шукаєте спосіб завантажити контрольну точку з upstream-проєкту, дивіться імпорт наявних ваг, це інша тема.

Повний запис про реліз містить журнал змін. Нижче наведено лише те, що потребує дій із вашого боку.

Обов'язкові зміни коду

allow_experimental=True більше не існує

Механізм підтвердження вилучено разом із базовим механізмом ddp_aware(experimental_key=...). Раніше для навчання та експорту EC, RTMDet, PicoDet і FOMO був потрібний цей аргумент, тому зміна стосується кожного скрипту, що навчає одне з цих сімейств.

# 1.4.0
model.train(data="data.yaml", epochs=100, allow_experimental=True)

# 1.5.0: видаліть аргумент
model.train(data="data.yaml", epochs=100)

Проміжного шару для застарілого виклику немає. Виклик, який досі передає цей аргумент, спричиняє TypeError. Разом із ним вилучено BaseModel.EXPERIMENTAL_WEIGHT_FILENAMES. Перехоплювач get_download_notice() збережено, і його досі перевизначають MiDaS, SegFormer та YOLO9-P2.

Рівні підтримки досі публікуються, але більше не є аргументом: дивіться рівні стабільності.

Рівня експорту "experimental" більше не існує

from libreyolo.export.support import Tier

# 1.4.0: Literal["validated", "experimental", "blocked"]
# 1.5.0: Literal["validated", "available", "blocked"]

Код, що розгалужується за рядком рівня, має читати "available" там, де раніше читав "experimental". BaseExporter більше не виводить RuntimeWarning для цих форматів. Стан для кожного формату наведено в матриці експорту.

pretrained=False разом із resume тепер відхиляється

Раніше ця комбінація продовжувала роботу непослідовно. Тепер вона спричиняє:

ValueError: pretrained=False cannot be combined with resume.

Виберіть щось одне. pretrained=False починає з нової ініціалізації з фіксованим початковим значенням генератора; у 1.5.0 це працює для кожного придатного до навчання сімейства, а не лише для трьох. resume продовжує перерваний запуск із його контрольної точки. Обидва варіанти описано в розділі навчання.

Параметр CLI --imgsz є рядком, а не цілим числом

Зміна вужча, ніж здається. Обидва наведені нижче варіанти не змінюються:

libreyolo predict --model yolo9-t --source img.jpg --imgsz 640   # усе ще працює

model.predict("img.jpg", imgsz=640)   # усе ще працює

Змінити потрібно лише код, який безпосередньо викликає командні функції CLI з Python, оскільки predict, train і val розширили тип --imgsz з int до str, щоб приймати прямокутні розміри:

from libreyolo.cli.commands.predict import predict_cmd

predict_cmd(..., imgsz=640)      # 1.4.0
predict_cmd(..., imgsz="640")    # 1.5.0, тепер також працює "480x640"

Типовим значенням train тепер є рядок "640". Параметр export --imgsz уже був рядком, а profile не змінився.

Числа, що змінюються

Три зміни впливають на метрики з типовими налаштуваннями. Якщо ви відстежуєте результати між версіями, прочитайте це перед порівнянням запуску 1.5.0 із запуском 1.4.0.

faster-coco-eval є типовим бекендом метрик COCO

val() і валідація навчання після кожної епохи тепер обчислюють метрики COCO за допомогою бекенда faster-coco-eval на C++ замість pycocotools.

Рішення про перехід ухвалено за виміряним паритетом на всіх 100 тестових розбиттях RF100-VL: 1381 із 1400 значень метрик побітово ідентичні, максимальне відхилення 2.22e-16, зміни основних показників дорівнюють рівно 0, загальна швидкість вища у 15.6 раза, а на датасетах із великою кількістю виявлень у 56 разів. Ваші числа не повинні змінитися. Однак їх створює інша реалізація, тому ця зміна є в списку.

pycocotools залишається автоматичним резервним варіантом, якщо faster-coco-eval не встановлено. Щоб примусово використати його:

libreyolo val --model yolo9-t --data coco.yaml --no-faster-coco-eval

model.val(data="coco.yaml", faster_coco_eval=False)

LIBREYOLO_FASTER_COCO_EVAL=0 робить те саме глобально. Фактично використаний бекенд записується до журналу на рівні INFO, доступний як model.last_eval_backend після val() і включений як eval_backend до даних JSON CLI. Швидкий шлях можна встановити командою pip install libreyolo[fast-eval].

Контрольним точкам YOLOX, навченим до 1.5.0, потрібне перевизначення eps

Це пастка цього релізу. Прочитайте цей розділ, якщо ви донавчали YOLOX.

YOLOX задає для BatchNorm eps=1e-3 і momentum=0.03. До 1.5.0 ці значення застосовувалися як виправлення після створення, яке не переживало перебудову кількості класів, що виконується в train(), коли nc вашого датасету відрізняється від контрольної точки. Таке донавчання й валідація під час нього використовували типове значення torch eps=1e-5, а після повторного завантаження для інференсу застосовувалося 1e-3: ті самі тензори з іншою нормалізацією.

Розміри зі звичайними згортками майже не змінюються. Розмір n із роздільними за глибиною згортками змінюється значно, оскільки його поканальна running_var досить мала, щоб eps домінувало. На розбитті ball датасету RF100-VL та сама контрольна точка nano має 0.566 mAP50-95 під час оцінювання з eps, на якому її навчено, і 0.151 після стандартного повторного завантаження.

Контрольна точка, навчена до 1.5.0, має семантику eps=1e-5. Щоб отримати для неї достовірні числа, виконайте оцінювання з перевизначенням BN eps на 1e-5:

import torch
from libreyolo import LibreYOLOX

model = LibreYOLOX("my-yolox-finetune.pt")
for module in model.model.modules():
    if isinstance(module, torch.nn.BatchNorm2d):
        module.eps = 1e-5

model.val(data="data.yaml")

Або один раз включіть sqrt((var + 1e-3) / (var + 1e-5)) у ваги BN і збережіть результат. Контрольним точкам, навченим у 1.5.0 або новішій версії, не потрібне жодне з цих рішень.

Багатомасштабне навчання D-FINE використовує upstream-рецепт для кожного розміру

Значення base_size_repeat було жорстко задано як 3 для кожного розміру. Тепер воно визначається окремо для кожного розміру згідно з upstream-рецептом: n навчається з фіксованим розміром і вимкненим багатомасштабним режимом, s використовує 20, m 6, l 4, x 3. Раніше збігався лише x, тому n, s, m і l бачать інший розподіл масштабів та збігаються до інших значень метрик.

Щоб відновити попередню поведінку, задайте значення явно:

from libreyolo.training.config import DFINEConfig

config = DFINEConfig(base_size_repeat=3)

DEIM і далі використовує жорстко задане значення 3. Подробиці про сімейство наведено на сторінці D-FINE.

Варто знати, дії не потрібні

• Результати з прямокутним imgsz змінилися, оскільки раніше були неправильними. Координати рамок, зміна розміру масок RTMDet, перемасштабування YOLO-NAS і масштабування еталонних даних валідатором тепер використовують окремі висоту й ширину замість одного скалярного значення. Квадратний imgsz побітово не змінився. Прямокутний інференс або валідація у 1.4.0 мали неправильний масштаб. YOLO-NAS тепер повністю відхиляє прямокутний imgsz замість непомітного створення неправильних вихідних даних.
• Словники метрик отримали нові ключі. max_det, ar_max_det і AR_max_det від засобу оцінювання COCO, а також metrics/loss і metrics/loss/ce від FOMO. Значення з типовими налаштуваннями не змінилися, але все, що перебирає ключі метрик, зокрема користувацькі засоби журналювання і заголовки CSV, бачить нові стовпці.
• Запуски YOLO9 із фіксованим початковим значенням, що спричиняють перебудову голови, починають з іншої ініціалізації, оскільки початкове значення тепер застосовується до перебудови, а не після неї. Донавчання 1.4.0 з фіксованим початковим значенням для іншої кількості класів не відтворюється побітово у 1.5.0.
• libreyolo[hub-kernels] на CUDA тепер справді залучає нативне ядро MS-deform-attn. У 1.4.0 його було обмежено умовою, яку RF-DETR ніколи не виконував, тому ядро не запускалося. Передбачення RF-DETR та інших сімейств із деформованою увагою можуть змінитися в межах похибки float. Стандартних установлень це не стосується, а LIBREYOLO_HUB_KERNELS=0 вимикає ядро.
• libreyolo predict відкидає непідтримувані параметри замість помилки. CLI фільтрує kwargs за сигнатурою __call__ моделі, тому параметр, якого сімейство не приймає, ігнорується замість спричинення TypeError. Друкарська помилка в назві прапорця тепер непомітно ігнорується.
• Живі джерела змінюють форму вихідних даних JSON. Вебкамери, потоки RTSP і захоплення екрана неявно вмикають потоковий режим, що виводить один запис для кожного кадру замість одного запису для виклику. Ці джерела з'явилися у 1.5.0, тому зміна не стосується скриптів 1.4.0.
• Повторний експорт rfdetr-pose або yolonas-pose до ONNX створює інші назви виходів. У 1.4.0 їхні багатотензорні голови пози помилково визначалися як сегментація за евристикою кількості виходів. Наявні файли .onnx на диску не змінюються.
• У встановленні без torch результати містять масиви numpy замість torch.Tensor, тому .boxes.data повертає інший тип, а розв'язання рівних значень у NMS може відрізнятися від torchvision. За встановленого torch поведінка побітово не змінилася. Дивіться полегшене встановлення.
• Об'єкти конфігурації перевіряють більше під час створення. TrainConfig отримав __post_init__ там, де його не було, тому вже некоректна конфігурація тепер спричиняє помилку негайно, а не в глибині виконання. Серіалізація ValidationConfig отримала ключ edge_thresholds, що порушує строгий круговий перехід ValidationConfig(**dump) із дампа 1.4.0.
• Назви файлів ваг для сімейств із суфіксом задачі визначаються інакше. segformer-b0 тепер перетворюється на LibreSegformerb0-sem.pt. Це виправляє помилки 404 автоматичного завантаження й порушує скрипти з жорстко заданою старою назвою без суфікса.
• Маркер pytest experimental_backend тепер має назву extended_backend. Це стосується лише запуску набору тестів із -m.

Контрольні точки та датасети

Контрольні точки, записані версією 1.4.0, завантажуються без змін. Схема отримала imgsz_h і imgsz_w для прямокутних моделей і досі записує скалярне значення imgsz = max(h, w) для старіших читачів. Для експорту ExecuTorch і MNN тепер потрібний супровідний файл, відповідно <program>.pte.json і <model>.mnn.json, а експорт HRNet містить pose_input: "person_crop". Формати датасетів не змінилися.