Гіперпараметри

Задання аргументів

Метод train() приймає іменовані аргументи, а CLI приймає ті самі назви у формі key=value.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt")results = model.train(    data="my-dataset.yaml",    epochs=100,    batch=16,    imgsz=640,    lr0=0.01,) print(results["best_mAP50_95"])

libreyolo train model=LibreYOLO9s.pt data=my-dataset.yaml \  epochs=100 batch=16 imgsz=640 lr0=0.01

Обидва шляхи ведуть до того самого місця. Kwargs передаються до TrainConfig.from_kwargs(), який створює dataclass конфігурації сімейства.

Друкарська помилка не породжує винятку

Метод from_kwargs() відкидає кожен ключ, який не є полем конфігурації, та породжує UserWarning із його назвою. Після цього навчання починається з типовим значенням:

# UserWarning: Unknown training config keys (ignored): ['learning_rate']
model.train(data="my-dataset.yaml", learning_rate=0.001)

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

Типові значення залежать від сімейства

TrainConfig визначає поле й базове типове значення. Кожне сімейство успадковує його та перевизначає значення, змінені в опублікованому рецепті, тому немає єдиної правильної відповіді на запитання «яка типова швидкість навчання».

Базовими типовими значеннями є optimizer="sgd", lr0=0.01, momentum=0.937, weight_decay=5e-4, scheduler="yoloxwarmcos", epochs=300, batch=16, imgsz=640 і amp=True. Три приклади того, наскільки сімейство відхиляється від них:

D-FINE і DEIM постачаються з amp=False, оскільки декодер D-FINE обмежує активації значенням 65504, найбільшим скінченним значенням float16. Для YOLO-NAS і FOMO воно також типово вимкнене. Прапорець CLI --amp типово має значення True для кожного сімейства, тому вважається наданим користувачем і перевизначає типове значення сімейства; не змінюйте його без відповідного наміру.

Щоб переглянути справжні типові значення сімейства без здогадок:

from dataclasses import fields from libreyolo import LibreYOLO9from libreyolo.training.config import TrainConfig family_cfg = LibreYOLO9.TRAIN_CONFIG()base_cfg = TrainConfig() for f in fields(family_cfg):    family_value = getattr(family_cfg, f.name)    base_value = getattr(base_cfg, f.name, None)    if not hasattr(base_cfg, f.name) or family_value != base_value:        print(f"{f.name}: {family_value}")

# Виводить типові значення train, val і predict, зокрема перевизначення сімейства.libreyolo cfg

Розмір батча

batch є глобальним батчем. Під час навчання на кількох GPU кожен ранг завантажує batch // world_size, тому передане число є кількістю зображень на крок оптимізатора незалежно від кількості GPU. Див. розділ Навчання на кількох GPU.

batch=-1 вмикає autobatch. Засіб навчання перевіряє модель у режимі навчання зі справжнім зворотним проходом для степенів двійки, апроксимує криву використання пам'яті прямою й вибирає найбільший степінь двійки, строго менший за екстрапольоване значення, що вміщується в 60 відсотків усієї VRAM.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # batch=-1 перевіряє пам'ять GPU й визначає конкретний степінь двійки.model.train(data="my-dataset.yaml", batch=-1, imgsz=640)

libreyolo train model=LibreYOLO9s.pt data=my-dataset.yaml batch=-1

Ключове тут саме тестування в режимі навчання зі зворотним проходом: тест у режимі інференсу не враховує збережені активації та тензори градієнтів, які для глибокої CNN у кілька разів перевищують обсяг інференсу. RF-DETR зменшує цільову частку до 45 відсотків, бо синтетичний зворотний прохід усе одно недооцінює витрати її критерію та допоміжних шарів декодера.

Autobatch є функцією CUDA. На CPU або MPS він записує один рядок у лог і зберігає типовий батч.

Накопичення градієнтів

nbs задає номінальний, або ефективний, розмір батча. Засіб навчання накопичує round(nbs / batch) мікробатчів на крок оптимізатора.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # 4 мікробатчі по 16 на крок оптимізатора, ефективний батч 64.model.train(data="my-dataset.yaml", batch=16, nbs=64)

За типового значення None накопичення вимкнене, а навчання не змінюється.

Швидкість навчання й розклад

lr0 є початковою швидкістю навчання, а optimizer приймає sgd, adam і adamw. momentum є моментом SGD або beta1 Adam, weight_decay є доданком L2, а nesterov застосовується до SGD.

Форму розкладу визначають scheduler, warmup_epochs, warmup_lr_start і min_lr_ratio. no_aug_epochs задає кількість останніх епох без сильної аугментації, і кілька розкладів також використовують його для формування завершальної частини, тому це не лише параметр аугментації. Дію кожного сімейства на аугментаційну частину описано в розділі Аугментації.

Деякі сімейства додають власні параметри швидкості навчання. backbone_lr_mult масштабує групу бекбона відносно голови, clip_max_norm задає обрізання градієнтів, а SegFormer використовує head_lr_mult, щоб швидкість голови декодування була вдесятеро вищою за швидкість бекбона. Ці параметри належать підкласу конфігурації сімейства, а не базовому класу.

EMA

За ema=True експоненційне ковзне середнє ваг зберігається разом із навченими вагами. Воно типово ввімкнене скрізь, крім FOMO.

ema_decay є цільовим коефіцієнтом згасання. Згасання наростає, а не відразу починається із цільового значення: ефективне значення на оновленні n дорівнює ema_decay * (1 - exp(-n / tau)), де типове tau дорівнює 2000, тому ранні оновлення точніше відстежують модель, а пізні сильніше згладжують її. Типові значення сімейств змінюються від 0.997 для пози YOLO-NAS через 0.9998 для YOLOX до 0.9999 для YOLOv9 і лінійки DETR.

Саме ваги EMA проходять валідацію й записуються до best.pt і last.pt. Необроблені навчені ваги також зберігаються під ключем train_model, тому відновлення продовжує навчену траєкторію, а не середнє.

Точність

amp=True виконує прямий прохід у контексті CUDA autocast. amp_dtype вибирає float16 (типово) або bfloat16; також приймаються назви fp16 і bf16.

Float16 потребує динамічного масштабування функції втрат і отримує активний GradScaler. Ширший діапазон експоненти Bfloat16 не потребує цього, тому його масштабувальник створюється, але вимикається, що зберігає однаковий шлях оптимізатора. Запит bfloat16 на пристрої CUDA без підтримки bfloat16 породжує помилку під час налаштування, а не непомітно переходить до іншого режиму.

Результати, контрольні точки й зупинка

Запуски записуються до project/name. project типово дорівнює runs/train для всіх сімейств, але name є одним із перевизначених для сімейства параметрів: базове типове значення дорівнює exp, YOLOv9 використовує yolo9_exp, а D-FINE використовує dfine_exp. За типового exist_ok=False до наявного каталогу додається збільшений суфікс, а не перезаписується його вміст.

save_period записує додатковий файл weights/epoch_<N>.pt кожні N епох на додачу до weights/last.pt після кожної епохи та weights/best.pt після кожного покращення відстежуваної метрики. eval_interval задає частоту валідації, а patience зупиняє запуск після вказаної кількості епох без покращення; значення 0 вимикає ранню зупинку.

cache прискорює повторні епохи, зберігаючи декодовані зображення в RAM (True або "ram") чи як файли .npy поруч із джерелами ("disk"). Кешовані прочитання побайтово ідентичні новим. За наявності робочих процесів завантажувача даних варіант "disk" безпечніший.

Відновлення

resume=True продовжує перерваний запуск. Спочатку потрібно завантажити контрольну точку, оскільки відновлення читає її з моделі, а не з окремого аргументу.

from libreyolo import LibreYOLO # Завантажте контрольну точку перерваного запуску, а потім запитайте продовження.model = LibreYOLO("runs/train/exp/weights/last.pt")model.train(data="my-dataset.yaml", epochs=100, resume=True)

libreyolo train model=runs/train/exp/weights/last.pt \  data=my-dataset.yaml epochs=100 resume=true

Відновлення повертає навчені ваги, стан оптимізатора, ваги EMA та кількість оновлень, відстеження найкращої метрики, масштаб GradScaler, а також випадкові стани PyTorch, CUDA й NumPy. Воно починається з епохи після епохи контрольної точки та перемотує розклад уперед до цієї позиції.

Дві дії не підтримуються. resume=True не можна поєднувати з pretrained, бо це породжує помилку. Крім того, якщо ключ найкращої метрики в контрольній точці відрізняється від ключа поточного запуску, відстеження скидається до нуля з попередженням замість порівняння значень, які мають різний зміст.

Рецепти у файлі

cfg= завантажує відображення YAML із назвами полів TrainConfig і об'єднує його під явно вказаними іменованими аргументами, тому kwarg завжди має пріоритет над файлом.

from libreyolo import LibreYOLO # Ключі yaml є назвами полів TrainConfig. Явні kwargs мають пріоритет.model = LibreYOLO("LibreYOLO9s.pt")model.train(data="my-dataset.yaml", cfg="my-recipe.yaml", epochs=50)

Ключі size і num_classes видаляються з файлу, оскільки вони вже належать екземпляру моделі. У CLI немає прапорця --cfg; шлях до файлу є аргументом Python.

Пов'язані матеріали

• Датасети описують значення, які приймає data=.
• Аугментації описують параметри аугментації та сімейства, які їх підтримують.
• Заморожування шарів і LoRA описують навчання частини ваг.
• Валідація та метрики описує результати запуску.