YOLO-NAS

Install

YOLO-NAS needs no extra beyond the base package.

pip install libreyolo

Predict

A checkpoint name that is not already on disk is fetched from Deci's public CDN, not from the LibreYOLO org, which hosts none of these weights. Before the transfer starts the library prints Deci's license terms once per process, and before the downloaded file is opened its SHA-256 is checked against a pinned value. What those terms allow is in licensing.

from libreyolo import LibreYOLO, SAMPLE_IMAGE # A name not already on disk is fetched from Deci's CDN. The download# prints Deci's license terms first; taking the file accepts them.model = LibreYOLO("LibreYOLONASs.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(box.cls, box.conf, box.xyxy)

libreyolo predict model=LibreYOLONASs.pt save=True \  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg

from libreyolo import LibreYOLO, SAMPLE_IMAGE # The -pose suffix picks the pose head and its own set of weights.model = LibreYOLO("LibreYOLONASs-pose.pt")result = model(SAMPLE_IMAGE) print(result.keypoints.xy)

The returned Results object is the one every family returns, so swapping in a different detector is a one line change. conf sets the confidence threshold and iou the NMS threshold. See prediction for sources, streaming and result handling.

The oriented-box task returns result.obb. The published OBB graph uses a 1024-pixel canvas and its recorded 18-class label set.

Variants

Detection and pose are the same architecture under different heads, and they take the same arguments. The sizes in the table below are the detection ones; pose is published at those and at one smaller size. The pose head predicts the COCO keypoint set.

Train

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLONASs.pt")model.train(data="my-dataset.yaml", epochs=100, imgsz=640, batch=16)

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

from libreyolo import LibreYOLONAS # No Deci checkpoint is touched: the model starts from random weights,# so what comes out of the run derives only from your data.model = LibreYOLONAS(None, size="s")model.train(data="my-dataset.yaml", imgsz=640, batch=16)

epochs, lr0 and amp are resolved per task when you leave them out, so a pose run starts from different defaults than a detection run. The optimizer defaults to AdamW. The class count comes from the dataset YAML and the head is rebuilt for it before the first epoch; on the pose head the keypoint count is handled the same way, so a COCO pose checkpoint can be fine-tuned onto a skeleton of a different size.

Fine-tuning starts from Deci's weights, which is what Deci's license covers. Training from a randomly initialized model involves no Deci checkpoint at all, and that is the third snippet above.

See training for datasets, augmentation, multi-GPU and loggers.

Detection defaults to amp=True with amp_dtype="float16"; oriented-box training retains amp=False. The OBB head supports training, prediction and validation, uses flipped/HSV augmentation and selects checkpoints with metrics/mAP50-95(OBB). load_detect_weights_for_obb() initializes it from detection weights.

Validate

val() returns a dictionary of metrics/ keys covering precision, recall, mAP 50 and mAP 50-95, measured against any dataset in the format you trained on.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLONASs.pt")metrics = model.val(data="my-dataset.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"])

libreyolo val model=LibreYOLONASs.pt data=my-dataset.yaml

# The bundled COCO yaml carries an embedded download script, so it# needs explicit permission unless the dataset is already local.libreyolo val model=LibreYOLONASl.pt data=coco.yaml imgsz=640 \  allow_download_scripts=True

Export

An exported artifact loads back through LibreYOLO() on its file suffix, so a .onnx or .engine file behaves like a checkpoint and returns the same Results. Running the graph in a bare runtime, with no LibreYOLO installed, is also supported, but then preprocessing and postprocessing are yours to write. Each format installs a different extra and takes a few arguments of its own. Both are on that format's page.

An export is another copy of the same weights in a different container. Exporting a Deci checkpoint changes neither where the weights came from nor the license that covers them.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLONASs.pt")model.export(format="onnx", imgsz=640)

libreyolo export model=LibreYOLONASs.pt format=onnx imgsz=640

from libreyolo import LibreYOLO, SAMPLE_IMAGE # The factory routes on the file suffix, so an exported artifact loads# like any checkpoint and returns the same Results object.model = LibreYOLO("LibreYOLONASs.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

ONNX inputs and outputs

Checkpoints

There are none to list. Deci's license forbids redistribution, so the LibreYOLO org publishes no YOLO-NAS weights and the download resolves elsewhere: a name of the form LibreYOLONAS<size>.pt, LibreYOLONAS<size>-pose.pt for pose, or LibreYOLONAS<size>-obb.pt (s, m, l) for oriented boxes, maps to the matching object on Deci's public CDN.

Only the checkpoints whose SHA-256 the library pins can be fetched that way. Anything else fails closed rather than opening an unverified third-party pickle, and has to be downloaded by hand and passed as a path. A file already on disk loads from its path, with no download and no checksum gate. That includes a Deci .pth under its original name, which the loader recognizes.

Licensing

Citation

YOLO-NAS was released without a paper. The entry below is the one its authors ask for, covering SuperGradients, the library it shipped in.

@misc{supergradients,
  doi = {10.5281/ZENODO.7789328},
  url = {https://zenodo.org/record/7789328},
  author = {Aharon,  Shay and {Louis-Dupont} and {Ofri Masad} and Yurkova,  Kate and {Lotem Fridman} and {Lkdci} and Khvedchenya,  Eugene and Rubin,  Ran and Bagrov,  Natan and Tymchenko,  Borys and Keren,  Tomer and Zhilko,  Alexander and {Eran-Deci}},
  title = {Super-Gradients},
  publisher = {GitHub},
  journal = {GitHub repository},
  year = {2021},
}