libreyolo quantize

Замінює float-модулі моделі квантованими, калібрує їх на зображеннях без міток, коли рецепт потребує статистики, і зберігає результат як контрольну точку PyTorch.

Команда: libreyolo quantize
Обов'язково: model
Результат: Шлях джерела з -<recipe> перед суфіксом, напр. LibreYOLO9s-int8.pt

Синтаксис

bash

libreyolo quantize model=<name|path> [recipe=<recipe>] [key=value ...]

Аргументи задаються парами key=value, працює також POSIX-форма, тому recipe=int8 і --recipe int8 є тим самим аргументом.

Аргументи

Аргумент	Типово	Призначення
`model`		Ваги моделі `.pt`. Обов'язковий
`recipe`	`int8`	Рецепт квантування: `fp16`, `bf16`, `fp8`, `int8`, `w4a16`, `w4a8`, `nvfp4`, `mxfp4`, `int2`
`calib`	`coco128.yaml`	Зображення для калібрування: YAML з даними або назва вбудованого датасету. Без міток, лише прямий прохід. `none` пропускає калібрування
`samples`	`128`	Максимальна кількість зображень для калібрування
`batch`	`8`	Розмір батча під час калібрування
`algorithm`	`auto`	Оцінювання діапазону активацій: `auto`, що обирає minmax, або `minmax`, або `percentile`
`out`		Шлях до вихідної контрольної точки. Типово це шлях джерела з `-<recipe>` перед суфіксом
`device`	`auto`	Пристрій
`allow_download_scripts`	`false`	Дозволити вбудований код Python у блоках завантаження в YAML датасету
`json`	`false`	Вивід JSON у stdout
`quiet`	`false`	Придушити stderr
`help_json`	`false`	Вивести схему команди у форматі JSON і завершити роботу

Приклади

Базовий приклад

# Калібрує на coco128 і записує LibreYOLO9s-int8.ptlibreyolo quantize model=LibreYOLO9s.pt recipe=int8

Лише приведення типу, без калібрування

libreyolo quantize model=LibreYOLO9s.pt recipe=fp16 calib=none \  out=weights/LibreYOLO9s-fp16.pt

Ширше калібрування, потім відновлення

libreyolo quantize model=LibreYOLO9s.pt recipe=int8 \  calib=coco128.yaml samples=256 batch=16 algorithm=minmax # Навчання з урахуванням квантування на квантованій контрольній точці відновлює правильність.libreyolo train model=LibreYOLO9s-int8.pt data=coco8.yaml epochs=10 lr0=0.001

Примітки

Які сімейства його приймають

Квантування охоплює чотири сімейства: yolo9, rfdetr, birefnet і feynobg. Будь-яке інше сімейство завершується помилкою quantize_failed, яка містить цей список.

Чого торкається кожен рецепт

fp16 і bf16 виконують приведення типу. Вони змінюють лише dtype, не потребують калібрування, і правильним налаштуванням для них є calib=none.

int8 і fp8 квантують модулі Conv2d та Linear, тому вони підходять для згорткових сімейств.

w4a16, w4a8, nvfp4, mxfp4 та int2 квантують лише nn.Linear, тому призначені для трансформерних сімейств. Запит на будь-який із них для yolo9 відхиляється з поясненням, а не дає мовчки неквантовану модель, оскільки прискорення нижче 8 біт там працює лише для GEMM, а згортки лишалися б у вищій точності.

int8, fp8, w4a8 та int2 потребують статистики калібрування для своїх активацій. int2 до того ж потребує подальшого навчання для відновлення, тому його відхилено для birefnet і feynobg, які не мають модуля навчання.

Кожне сімейство незалежно від рецепта лишає частину модулів у float: перші шари, голови передбачення, а в моделі YOLOv9 ще й згортку DFL, тобто фіксований оператор інтегрального математичного сподівання, який не можна квантувати.

Дані для калібрування не є навчальними даними

calib вказує на невеликий набір зображень без міток, який використовується лише у прямому проході, щоб визначити діапазони активацій. За ним не рахують метрик, а його мітки ніколи не читаються. Типовий coco128.yaml завантажується за URL під час першого використання, тому не потребує додаткових дозволів; YAML із вбудованим скриптом завантаження на Python потребує allow_download_scripts=true.

algorithm=percentile доступний і може знижувати правильність (accuracy) для трансформерних сімейств, тому auto обирає minmax.

Відновлення правильності

Результатом є звичайна контрольна точка PyTorch, тому libreyolo train приймає її напряму. Навчання квантованої контрольної точки є навчанням з урахуванням квантування (quantization-aware training); додавання distill_model=<teacher> перетворює його на дистиляцію з урахуванням квантування.

Вивід і коди виходу

У результаті виводяться шлях збереження, рецепт, режим виконання, ознака того, чи виконувалося калібрування, та кількість замінених модулів за видами. Код виходу: 0 в разі успіху, 4, якщо модель не вдається завантажити, 5, якщо не вдається квантування або збереження, і 1 для інших помилок виконання.

Пов'язане: libreyolo export, команда, яка натомість виходить за межі PyTorch і записує артефакт для розгортання.