YOLO-NAS
Deci.AI의 아키텍처 검색에서 나온 백본과 넥을 사용하고 양자화 인식 RepVGG 블록으로 구축된 합성곱 탐지기입니다. 가중치는 Deci.AI 소유이며 비상업적 사용만 허용되고 LibreYOLO는 이를 게시하지 않습니다.
- 작업
- detection, pose, oriented boxes
- 크기
- s, m, l at 640 px
- 설치
pip install libreyolo- 지원 티어
- 코어, v1.1.0부터 지원. 학습 가능한 핵심 탐지기입니다. 기능은 같은 릴리스 주기에서 플래그십을 따릅니다.
- 라이선스
- 코드 Apache-2.0, 가중치 Deci.AI proprietary, non-commercial. 상업적 사용
설치
YOLO-NAS에는 기본 패키지 외의 extra가 필요하지 않습니다.
pip install libreyolo예측
디스크에 아직 없는 체크포인트 이름은 이러한 가중치를 하나도 호스팅하지 않는 LibreYOLO 조직이 아니라 Deci의 공개 CDN에서 가져옵니다. 전송을 시작하기 전에 라이브러리가 프로세스마다 한 번 Deci 라이선스 약관을 출력하며 다운로드 파일을 열기 전에 고정된 값과 SHA-256을 대조합니다. 해당 약관이 허용하는 범위는 라이선스에 나와 있습니다.
from libreyolo import LibreYOLO, SAMPLE_IMAGE # 디스크에 아직 없는 이름은 Deci CDN에서 가져옵니다. 다운로드 전에# Deci 라이선스 약관을 출력하며 파일을 받으면 약관에 동의한 것입니다.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.jpgfrom libreyolo import LibreYOLO, SAMPLE_IMAGE # -pose 접미사가 자세 헤드와 전용 가중치 집합을 선택합니다.model = LibreYOLO("LibreYOLONASs-pose.pt")result = model(SAMPLE_IMAGE) print(result.keypoints.xy)반환되는 Results 객체는 모든 계열이 반환하는 것과 같으므로 탐지기를 바꾸려면 한 줄만 변경하면 됩니다. conf는 신뢰도 임곗값을, iou는 NMS 임곗값을 설정합니다. 소스, 스트리밍, 결과 처리는 예측을 참조합니다.
회전 바운딩 박스 작업은 result.obb를 반환합니다. 공개 OBB 그래프는 1024 픽셀 캔버스와 기록된 18개 클래스 레이블 집합을 사용합니다.
변형
탐지와 자세 추정은 서로 다른 헤드 아래에서 같은 구조를 사용하며 같은 인수를 받습니다. 아래 표의 크기는 탐지용입니다. 자세 모델도 해당 크기들과 더 작은 크기 하나로 공개됩니다. 자세 헤드는 COCO 키포인트 집합을 예측합니다.
| 체크포인트 | 입력(px) | mAP 50-95 | 파라미터(M) |
|---|---|---|---|
| LibreYOLONASl | 640 | 56.3 | 66.98 |
| LibreYOLONASm | 640 | 55.4 | 51.18 |
| LibreYOLONASs | 640 | 51.8 | 19.05 |
COCO val2017, 500 images. LibreYOLO 벤치마크 도구로 측정하고 Vision Analysis에 공개했습니다. 이곳에서 하드웨어와 런타임별 지연 시간을 비교하고 전체 실행 기록을 확인할 수 있습니다.
학습
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=16from libreyolo import LibreYOLONAS # Deci 체크포인트를 전혀 사용하지 않습니다. 모델은 무작위 가중치에서# 시작하므로 실행 결과는 제공한 데이터에서만 파생됩니다.model = LibreYOLONAS(None, size="s")model.train(data="my-dataset.yaml", imgsz=640, batch=16)epochs, lr0, amp를 생략하면 작업별로 결정되므로 자세 실행은 탐지 실행과 다른 기본값에서 시작합니다. 기본 옵티마이저는 AdamW입니다. 클래스 수는 데이터셋 YAML에서 가져오며 첫 epoch 전에 이에 맞춰 헤드를 다시 구축합니다. 자세 헤드도 키포인트 수를 같은 방식으로 처리하므로 COCO 자세 체크포인트를 다른 크기의 스켈레톤에 파인튜닝할 수 있습니다.
파인튜닝은 Deci의 가중치에서 시작하며 여기에 Deci 라이선스가 적용됩니다. 무작위로 초기화한 모델의 학습은 Deci 체크포인트를 전혀 사용하지 않으며 위의 세 번째 스니펫이 이 경로입니다.
데이터셋, 증강, 다중 GPU, 로거는 학습을 참조합니다.
탐지는 amp=True와 amp_dtype="float16"이 기본값이며, 회전 바운딩 박스 학습은 amp=False를 유지합니다. OBB 헤드는 학습, 예측, 검증을 지원하고, 뒤집기/HSV 증강을 사용하며, metrics/mAP50-95(OBB)로 체크포인트를 선택합니다. load_detect_weights_for_obb()는 탐지 가중치로 OBB 헤드를 초기화합니다.
검증
val()은 학습에 사용한 형식의 데이터셋을 대상으로 측정한 정밀도, 재현율, mAP 50, mAP 50-95를 포함하는 metrics/ 키 사전을 반환합니다.
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# 번들 COCO yaml에는 내장 다운로드 스크립트가 있으므로 데이터셋이 이미# 로컬에 있지 않다면 명시적 권한이 필요합니다.libreyolo val model=LibreYOLONASl.pt data=coco.yaml imgsz=640 \ allow_download_scripts=True내보내기
| 작업 | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | ncnn | TFLite | CoreML | Core AI |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Detection | Detection to ONNX: 지원함 | Detection to TorchScript: 지원함 | Detection to ExecuTorch: 지원함 | Detection to TensorRT: 지원함 | Detection to OpenVINO: 지원함 | Detection to Paddle: 지원함 | Detection to MNN: 지원함 | Detection to RKNN: 지원함 | Detection to ncnn: 지원함 | Detection to TFLite: 지원함 | Detection to CoreML: 지원하지 않음 | Detection to Core AI: 지원함 |
| Pose | Pose to ONNX: 지원함 | Pose to TorchScript: 지원함 | Pose to ExecuTorch: 지원함 | Pose to TensorRT: 지원함 | Pose to OpenVINO: 지원함 | Pose to Paddle: 지원함 | Pose to MNN: 지원하지 않음 | Pose to RKNN: 지원하지 않음 | Pose to ncnn: 지원함 | Pose to TFLite: 지원하지 않음 | Pose to CoreML: 지원하지 않음 | Pose to Core AI: 지원하지 않음 |
| Oriented boxes | Oriented boxes to ONNX: 지원함 | Oriented boxes to TorchScript: 지원함 | Oriented boxes to ExecuTorch: 지원함 | Oriented boxes to TensorRT: 지원함 | Oriented boxes to OpenVINO: 지원함 | Oriented boxes to Paddle: 지원하지 않음 | Oriented boxes to MNN: 지원하지 않음 | Oriented boxes to RKNN: 지원하지 않음 | Oriented boxes to ncnn: 지원함 | Oriented boxes to TFLite: 지원하지 않음 | Oriented boxes to CoreML: 지원하지 않음 | Oriented boxes to Core AI: 지원하지 않음 |
내보낸 아티팩트는 파일 접미사에 따라 LibreYOLO()로 다시 불러오므로 .onnx 또는 .engine 파일은 체크포인트처럼 동작하며 동일한 Results를 반환합니다. LibreYOLO가 설치되지 않은 기본 런타임에서 그래프를 실행할 수도 있지만 이 경우 전처리와 후처리를 직접 작성해야 합니다. 각 형식은 서로 다른 extra를 설치하고 고유한 몇 가지 인수를 받습니다. 둘 다 해당 형식 페이지에 나와 있습니다.
내보내기는 같은 가중치를 다른 컨테이너에 복제하는 일입니다. Deci 체크포인트를 내보내도 가중치의 출처나 적용되는 라이선스는 바뀌지 않습니다.
from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLONASs.pt")model.export(format="onnx", imgsz=640)libreyolo export model=LibreYOLONASs.pt format=onnx imgsz=640from libreyolo import LibreYOLO, SAMPLE_IMAGE # 팩토리는 파일 접미사에 따라 라우팅하므로 내보낸 아티팩트도# 다른 체크포인트처럼 불러와 동일한 Results 객체를 반환합니다.model = LibreYOLO("LibreYOLONASs.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)ONNX 입력과 출력
LibreYOLONAS detect
| 텐서 | images float32 [batch, 3, height, width] |
|---|---|
| 색상 | RGB |
| 스케일링 | 픽셀 / 255 |
| 정규화 | 없음 |
| 크기 조정 | custom, Pillow bilinear |
Pillow의 바이리니어 리사이즈를 재현하는 방법
LibreYOLO는 Pillow의 BILINEAR 필터(Image.resize)로 크기를 조정합니다. OpenCV의 INTER_LINEAR나 INTER_AREA가 아닙니다. 축소할 때 Pillow는 축소 배율만큼 필터를 넓히며, OpenCV의 리사이즈는 검출 결과를 바꾸고 상자를 몇 픽셀 옮깁니다. Pillow 없이 재현하려면 한 축을 리사이즈해 8비트로 반올림한 뒤, 다른 축을 리사이즈해 다시 반올림합니다. 축마다 s = in_size / out_size, f = max(s, 1)로 둡니다. 출력 픽셀 i의 중심은 c = (i + 0.5) * s이고, 원본 픽셀 j를 int(c - f + 0.5)부터 int(c + f + 0.5) - 1까지(이미지 범위로 제한) 읽으며, 각 가중치는 max(0, 1 - |j + 0.5 - c| / f)이고 가중치의 합으로 나눕니다. Pillow는 고정소수점으로 계산하고 이미지 모양에 따라 축 순서를 고르므로, 부동소수점 가중치는 일부 픽셀에서 한 단계 다를 수 있습니다. 이는 우리 검증 결과를 바꾸지 않습니다.
Square input only. Export rejects a non-square imgsz, and height equals width, 640 by default.
The image is not scaled to fill the canvas. The longest side goes to R = min(636, height, width), so 636 at 640 x 640.
Scale by r = min(R / h, R / w) and resize to (round(w * r), round(h * r)). The rounding is Python round, so an exact .5 goes to the even neighbor.
Paste the resized image onto a canvas filled with 114 at left = (width - new_w) // 2 and top = (height - new_h) // 2.
On the test image, cv2.resize with INTER_LINEAR loses two of the eight detections, and INTER_AREA moves boxes by up to 1.4 px.
Divide by 255 after the resize. There is no mean or std normalization.
Detection, 기본 내보내기
| 출력 | 형태 | 의미 |
|---|---|---|
pred_logits | [batch, anchors, 4] | Boxes, despite the name. x1, y1, x2, y2 in input-canvas pixels. anchors is the cell count over strides 8, 16 and 32, 8400 at 640 x 640. |
pred_boxes | [batch, anchors, nc] | Class scores, despite the name. Sigmoid already applied. 80 classes for the COCO checkpoints. |
후처리
- The output names are swapped relative to their content. Read boxes from pred_logits and scores from pred_boxes, or tell them apart by the last dimension (4 for boxes).
- Take the best class per anchor: score = max over classes, class = argmax. One anchor yields at most one detection.
- Keep anchors whose score is strictly above the confidence threshold (0.25 by default).
- Keep the 1000 highest scoring candidates.
- Map boxes back to the original image: subtract left from x and top from y, divide by r, clip to the image. Drop boxes left with zero width or height.
- Run NMS per class with IoU 0.45 and keep at most 300 detections.
- nms=True is not available for this family: export raises NotImplementedError.
LibreYOLONAS pose
| 텐서 | images float32 [batch, 3, height, width] |
|---|---|
| 색상 | BGR |
| 스케일링 | 픽셀 / 255 |
| 정규화 | 없음 |
| 크기 조정 | custom, Pillow bilinear |
Pillow의 바이리니어 리사이즈를 재현하는 방법
LibreYOLO는 Pillow의 BILINEAR 필터(Image.resize)로 크기를 조정합니다. OpenCV의 INTER_LINEAR나 INTER_AREA가 아닙니다. 축소할 때 Pillow는 축소 배율만큼 필터를 넓히며, OpenCV의 리사이즈는 검출 결과를 바꾸고 상자를 몇 픽셀 옮깁니다. Pillow 없이 재현하려면 한 축을 리사이즈해 8비트로 반올림한 뒤, 다른 축을 리사이즈해 다시 반올림합니다. 축마다 s = in_size / out_size, f = max(s, 1)로 둡니다. 출력 픽셀 i의 중심은 c = (i + 0.5) * s이고, 원본 픽셀 j를 int(c - f + 0.5)부터 int(c + f + 0.5) - 1까지(이미지 범위로 제한) 읽으며, 각 가중치는 max(0, 1 - |j + 0.5 - c| / f)이고 가중치의 합으로 나눕니다. Pillow는 고정소수점으로 계산하고 이미지 모양에 따라 축 순서를 고르므로, 부동소수점 가중치는 일부 픽셀에서 한 단계 다를 수 있습니다. 이는 우리 검증 결과를 바꾸지 않습니다.
Square input only. Export rejects a non-square imgsz, and height equals width, 640 by default.
Channels are BGR, unlike detection. Pad value and position also differ from detection.
The longest side goes to R = min(640, height, width), so it fills the canvas.
Scale by r = min(R / h, R / w) and resize to (round(w * r), round(h * r)). The rounding is Python round, so an exact .5 goes to the even neighbor.
Paste the resized image in the top-left corner of a canvas filled with 127. All padding is on the bottom and the right.
On the test image, cv2.resize with INTER_LINEAR or INTER_AREA moves boxes by up to 5 px and keypoints by more than 10 px.
Divide by 255 after the resize. There is no mean or std normalization.
Pose, 기본 내보내기
| 출력 | 형태 | 의미 |
|---|---|---|
boxes | [batch, anchors, 4] | Person boxes as x1, y1, x2, y2 in input-canvas pixels. anchors is the cell count over strides 8, 16 and 32, 8400 at 640 x 640. |
scores | [batch, anchors, nc] | Class scores, sigmoid already applied. nc is 1 (person) for the COCO pose checkpoints. |
keypoints_xy | [batch, anchors, num_keypoints, 2] | Keypoint x, y in input-canvas pixels. num_keypoints is 17 (COCO order) for the COCO pose checkpoints. |
keypoints_conf | [batch, anchors, num_keypoints] | Per-keypoint visibility score, sigmoid already applied. |
후처리
- Take the best class per anchor: score = max over classes, class = argmax. With one class this is just the person score.
- Keep anchors whose score is at or above the confidence threshold (0.25 by default). This is >=, not > as in detection.
- Keep the 1000 highest scoring candidates.
- Map boxes and keypoints back to the original image: divide x and y by r. The image sits in the top-left corner, so there is no pad offset to subtract.
- Clip boxes to the image and drop boxes left with zero width or height. Keypoints are not clipped and can fall outside the image.
- Run NMS per class with IoU 0.45 and keep at most 300 detections. Keep each survivor's keypoints as (x, y, keypoints_conf).
- nms=True is not available for this family: export raises NotImplementedError.
LibreYOLONAS obb
| 텐서 | images float32 [batch, 3, height, width] |
|---|---|
| 색상 | BGR |
| 스케일링 | 픽셀 / 255 |
| 정규화 | 없음 |
| 크기 조정 | custom, bilinear |
Square input only. Export rejects a non-square imgsz, and height equals width, 1024 by default.
Channels are BGR, unlike detection. The resize filter and the pad position also differ from detection.
The longest side goes to R = min(1024, height, width), so it fills the canvas.
Scale by r = min(R / h, R / w) and resize to (round(w * r), round(h * r)). The rounding is Python round, so an exact .5 goes to the even neighbor.
The resize is cv2.resize with INTER_LINEAR, not Pillow as in detection and pose. It is skipped when the image already has that size. On the test image, Pillow's filter here changes the detection count.
Paste the resized image in the top-left corner of a canvas filled with 114. All padding is on the bottom and the right.
Divide by 255 after the resize. There is no mean or std normalization.
Oriented boxes, 기본 내보내기
| 출력 | 형태 | 의미 |
|---|---|---|
boxes | [batch, anchors, 5] | Rotated boxes as cx, cy, w, h, angle. cx, cy, w and h are in input-canvas pixels. The angle is in radians. The graph computes it as (sigmoid(logit) - 0.25) x pi, so it lies between -pi/4 and 3pi/4 and is not wrapped yet. The w side points along (cos angle, sin angle) in image coordinates, y down. anchors is the cell count over strides 8, 16 and 32, 21504 at 1024 x 1024. |
scores | [batch, anchors, nc] | Class scores, sigmoid already applied. 18 classes (DOTA 2.0) for the published checkpoints. |
후처리
- Take the best class per anchor: score = max over classes, class = argmax. One anchor yields at most one detection.
- Keep anchors whose score is at or above the confidence threshold (0.25 by default). This is >=, not > as in detection.
- Keep the 1000 highest scoring candidates.
- Map boxes back to the original image: divide cx, cy, w and h by r. The image sits in the top-left corner, so there is no pad offset, and the angle does not change.
- Clip cx to 0 to the image width and cy to 0 to the image height. w and h are not clipped. Drop boxes with w or h at or below 0.
- Put the long side first: if h > w, swap w and h and add pi/2 to the angle. Then wrap the angle to [-pi/2, pi/2) with angle = ((angle + pi/2) mod pi) - pi/2.
- Run greedy NMS per class on exact rotated-box IoU (polygon intersection area over union, for example cv2.rotatedRectangleIntersection) with IoU 0.45, and keep at most 300 detections. LibreYOLO does not use upstream's matrix soft-NMS.
- LibreYOLO also reports an axis-aligned box per detection. With ex = abs(cos angle) * w / 2 + abs(sin angle) * h / 2 and ey = abs(sin angle) * w / 2 + abs(cos angle) * h / 2, it is cx - ex, cy - ey, cx + ex, cy + ey, clipped to the image.
- nms=True is not available for this family: export raises NotImplementedError.
직접 구현한 코드를 확인하려면 같은 파일을 LibreYOLO로 실행하세요. LibreYOLO("model.onnx").predict("image.jpg")가 기준 결과를 반환합니다. LibreYOLO 1.7.0으로 검증함.
체크포인트
나열할 체크포인트가 없습니다. Deci 라이선스는 재배포를 금지하므로 LibreYOLO 조직은 YOLO-NAS 가중치를 게시하지 않으며 다운로드는 다른 위치에서 처리됩니다. LibreYOLONAS<size>.pt 형식의 이름, 자세용 LibreYOLONAS<size>-pose.pt, 또는 회전 박스용 LibreYOLONAS<size>-obb.pt(s, m, l)가 Deci 공개 CDN의 해당 객체에 매핑됩니다.
라이브러리가 SHA-256을 고정한 체크포인트만 이 방식으로 가져올 수 있습니다. 그 외 항목은 검증되지 않은 서드파티 pickle을 열지 않고 실패하며 직접 다운로드해 경로로 전달해야 합니다. 디스크에 이미 있는 파일은 다운로드나 체크섬 게이트 없이 해당 경로에서 불러옵니다. 로더가 인식하는 원래 이름의 Deci .pth도 여기에 포함됩니다.
라이선스
내려받는 특정 가중치의 Hugging Face 저장소에서 라이선스를 확인하십시오. LibreYOLO 조직의 모든 체크포인트에는 라이선스가 있으며 한 계열 안에서도 항상 같지는 않습니다. 해당 저장소가 신뢰할 수 있는 기준입니다. 아래 요약은 이 페이지를 마지막으로 검증했을 때 적용된 내용을 설명합니다.
관련 라이선스에 관한 설명이며 법률 자문이 아닙니다. 상업적으로 중요한 사안이라면 라이선스를 직접 읽고 별도의 법률 자문을 받으십시오.
- 원작
- YOLO-NAS, Deci.AI
- 업스트림 라이선스
- Deci.AI proprietary, non-commercial
- LibreYOLO 코드
- MIT
- 가중치
- Deci.AI proprietary, non-commercial, 저자가 배포합니다. LibreYOLO는 이를 호스팅하거나 미러링하지 않습니다.
- 해석
- Two licenses apply here and they are not the same. The SuperGradients source this port follows is Apache-2.0 and LibreYOLO's own implementation is MIT, so nothing restricts the architecture or the training code. Deci's published checkpoints are a different matter: the YOLO-NAS license grants a revocable, non-transferable right to use them and nothing more. It forbids redistribution and sublicensing, forbids offering them as a managed or remote service, restricts modification and reverse engineering, and rules out commercial use, including any model running in a production environment, unless you hold a separate agreement with Deci. LibreYOLO therefore does not mirror them, and prints those terms once before the download starts. Weights trained from a randomly initialized model on your own data derive from no Deci checkpoint.
LibreYOLO는 이러한 가중치를 호스팅하거나 미러링하지 않습니다. 이 계열은 LibreYOLO Hugging Face 조직에 존재하지 않습니다. 모든 자동 다운로드는 대신 Deci의 공개 CDN으로 향하고 시작 전에 프로세스마다 한 번 Deci 약관을 출력하며 파일을 열기 전에 고정된 SHA-256과 대조합니다.
대안은 무작위로 초기화한 모델을 학습하는 것입니다. 구조는 업스트림에서 Apache-2.0이고 여기서는 MIT이므로 자체 데이터로 이렇게 학습한 모델은 어떤 Deci 체크포인트에서도 파생되지 않습니다.
인용
YOLO-NAS는 논문 없이 공개되었습니다. 아래 항목은 저자들이 배포 라이브러리인 SuperGradients를 대상으로 요청한 인용입니다.
@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},
}github.com/Deci-AI/super-gradients#citing에 있는 저자의 인용 블록에서 복사했습니다.