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 доступен и может снижать точность на трансформерных семействах, поэтому auto выбирает minmax.

Восстановление точности

Результат — обычный чекпойнт PyTorch, поэтому libreyolo train принимает его напрямую. Обучение квантизованного чекпойнта — это обучение с учётом квантизации; если добавить distill_model=<teacher>, получится дистилляция с учётом квантизации.

Вывод и коды возврата

В результате печатаются путь сохранения, рецепт, режим выполнения, признак того, выполнялась ли калибровка, и число заменённых модулей по видам. Код возврата — 0 при успехе, 4, если модель не удалось загрузить, 5, если не удалась квантизация или сохранение, и 1 для остальных ошибок выполнения.

Смотрите также libreyolo export — эта команда выходит за пределы PyTorch и вместо этого записывает артефакт для развёртывания.