Ultralytics YOLO 모델용 ST Edge AI 내보내기

Ultralytics YOLO 모델을 format="stedgeai"로 내보내면, STM32 마이크로컨트롤러와 Neural-ART 가속기를 탑재한 STM32N6을 포함한 STM32용 신경망을 컴파일하는 STMicroelectronics 툴체인인 ST Edge AI Core에 맞게 구성된 ONNX 모델을 얻을 수 있습니다. 내보내기는 기본적으로 부동 소수점 모델과 quantize=8를 사용하는 완전 양자화 INT8 모델을 생성합니다. Ultralytics는 yolo predict 및 yolo val을 사용해 컴퓨터에서 두 파일 중 하나를 실행하므로, 디바이스용으로 컴파일하기 전에 정확도를 측정할 수 있습니다.

호스트에서 검증됨

Ultralytics는 컴퓨터에서 ONNX Runtime으로 이러한 모델을 검증하며, STMicroelectronics는 ST Edge AI Core를 사용해 STM32N6용 7개 작업 모두의 INT8 내보내기 모델을 컴파일했습니다. STM32 보드에서 정확도, 지연 시간 및 메모리를 측정하는 작업은 ST 도구를 사용해 수행합니다. 자세한 내용은 STM32에 배포를 참조하세요.

전용 ST Edge AI 형식을 사용하는 이유#

마이크로컨트롤러는 INT8 모델을 실행하며, 표준 ONNX 내보내기만으로는 처음부터 끝까지 양자화가 제대로 이루어지지 않습니다:

  • 하나의 출력에 혼합된 범위. YOLO 감지 헤드는 픽셀 단위의 박스 좌표(0~640)와 클래스 점수(0~1)를 하나의 텐서로 결합합니다. INT8 양자화는 해당 텐서에 하나의 스케일을 적용하므로 점수의 해상도가 거의 모두 손실됩니다. ST Edge AI 내보내기는 박스와 키포인트 좌표를 입력 크기 기준으로 [0, 1]에 정규화합니다. 이는 Ultralytics가 Edge TPU에 사용하는 것과 동일한 정규화 방식이므로 전체 그래프를 양자화할 수 있습니다.
  • 크기가 큰 고밀도 출력. 시맨틱 세그멘테이션 및 깊이 모델은 일반적으로 그래프 내부에서 입력 해상도로 업샘플링합니다. ST Edge AI 내보내기는 업샘플링 전에 처리를 멈춥니다. 따라서 시맨틱 세그멘테이션의 출력 버퍼는 64배, 깊이 출력 버퍼는 16배 작아지며, 깊이 값은 INT8 레벨이 균등하게 분포되는 로그 도메인에 유지됩니다.
  • 그래프 내부의 후처리. 임베디드 NMS와 YOLO26의 NMS 없는 헤드는 헤드 뒤에 TopK 및 gather 연산자를 추가합니다. 내보내기에서는 해당 연산자를 제외하고 항상 원시 예측값을 반환하므로, 애플리케이션에서 NMS를 실행합니다.

대신 표준 레이아웃(픽셀 좌표, 전체 해상도 맵, 선택적 임베디드 NMS)을 원한다면 ONNX 내보내기를 사용하세요.

지원 작업#

모든 Ultralytics YOLO 작업은 내보내기 후 호스트에서 실행됩니다. 출력 형태는 imgsz=640 기준입니다:

작업출력
감지[1, 4 + nc, 8400]: [0, 1]로 정규화된 박스, 클래스 점수
인스턴스 분할[1, 4 + nc + 32, 8400] 및 [0, 1]로 정규화된 박스, 마스크 프로토타입 [1, 32, 160, 160]
시맨틱 분할1/8 해상도의 클래스 로짓 [1, nc, 80, 80]. 업샘플링한 다음 픽셀별 argmax를 계산합니다.
깊이 추정1/4 해상도의 로그 깊이 [1, 1, 160, 160]. 미터 단위 깊이로 변환하려면 exp(x)을 적용한 다음 업샘플링합니다.
분류클래스 확률 [1, nc]
자세 추정[1, 4 + nc + nk, 8400]: [0, 1]로 정규화된 박스 및 키포인트
방향성 객체 감지[1, 4 + nc + 1, 8400]: [0, 1]로 정규화된 박스, 라디안 단위 각도. 정사각형 imgsz가 필요합니다.

RT-DETR 및 YOLO-NAS 모델은 지원되지 않습니다.

사용법#

내보내기
from ultralytics import YOLO

# YOLO26 모델 로드
model = YOLO("yolo26n.pt")

# 부동 소수점 모델 내보내기
model.export(format="stedgeai")  # 'yolo26n_stedgeai.onnx' 생성

# COCO8으로 보정한 INT8 모델 내보내기
model.export(format="stedgeai", quantize=8, data="coco8.yaml")  # 'yolo26n_int8_stedgeai.onnx' 생성
호스트에서 예측 및 검증
from ultralytics import YOLO

# 내보낸 ST Edge AI 모델 로드
model = YOLO("yolo26n_int8_stedgeai.onnx")

# 추론 실행
results = model("https://ultralytics.com/images/bus.jpg")

# COCO8 데이터셋에서 INT8 정확도 측정
metrics = model.val(data="coco8.yaml")

내보내기마다 파일 하나가 생성됩니다. Ultralytics는 파일 이름이 _stedgeai.onnx으로 끝나는지 확인해 ST Edge AI 모델을 인식한 다음, 좌표를 픽셀 단위로 다시 변환하고 시맨틱 및 깊이 맵을 업샘플링하며 로그 깊이를 미터 단위 깊이로 변환합니다. 파일 이름을 바꿀 때도 해당 끝부분을 유지하세요. 일반적인 .onnx 이름을 사용하면 표준 ONNX 모델로 로드되어 박스를 [0, 1] 단위로 반환합니다.

내보내기 인수#

인수유형기본값설명
formatstr'stedgeai'내보낸 모델의 대상 형식입니다.
imgszint 또는 tuple640모델 입력 크기입니다. 정사각형 이미지에는 정수를, 그 외에는 (height, width) 튜플을 사용합니다. 모델의 배치 크기는 1로 고정되며 형태는 정적입니다. OBB 모델에는 정사각형 imgsz이 필요합니다.
quantizeint 또는 strNone정밀도입니다. 설정하지 않거나 32을 지정하면 부동 소수점 모델을 생성하고, 8을 지정하면 INT8 모델을 생성합니다.
datastrNoneINT8 보정에 사용하는 데이터셋입니다. 데이터셋 YAML 또는 분류 작업용 데이터셋 디렉터리나 기본 제공 데이터셋 이름을 지정합니다. 지정하지 않으면 quantize=8은 해당 작업의 기본 데이터셋을 사용합니다. 예를 들어 감지 작업에서는 coco8.yaml을 사용합니다.
fractionfloat1.0사용할 보정 데이터셋의 비율입니다.
opsetintNoneONNX opset입니다. 기본값은 PyTorch 버전에서 안정적으로 내보낼 수 있는 최신 opset입니다.
simplifyboolTrueonnxslim을 사용해 ONNX 그래프를 간소화합니다.
devicestrNone내보내기에 사용하는 디바이스입니다. GPU(device=0) 또는 CPU(device=cpu)를 지정합니다.

batch 및 dynamic=True은 거부되며, nms=True는 경고와 함께 원시 출력으로 대체됩니다.

INT8 양자화#

quantize=8을 사용하면 Ultralytics는 ONNX Runtime의 정적 양자화를 사용해 모델을 양자화합니다. 이때 ST Edge AI Core가 권장하고 STM32 AI Model Zoo Services가 적용하는 방식을 따릅니다:

  • 부동 소수점 모델 입력 및 출력을 사용하는 QDQ(QuantizeLinear/DequantizeLinear) 형식입니다.
  • 부호가 있는 대칭 채널별 INT8 가중치와 부호가 있는 비대칭 INT8 활성화입니다.
  • Ultralytics 검증 중과 정확히 동일하게 전처리한 data 이미지에 대해 MinMax 보정을 수행합니다.

헤드를 부동 소수점으로 유지하는 표준 ONNX quantize=8 내보내기와 달리 모든 연산자가 양자화됩니다. 대신 ST 도구로 양자화하려면 부동 소수점 모델을 내보낸 뒤 STM32 AI Model Zoo Services에 전달하세요.

자체 데이터로 보정

INT8 정확도는 보정 이미지가 배포 환경과 얼마나 유사한지에 따라 달라집니다. data=에 대표 이미지가 300장 이상 포함된 데이터셋을 전달하세요. 기본 보정 데이터셋에는 공개 샘플이 몇 개만 들어 있습니다.

아래 표는 각 모델의 기본 imgsz(640, 시맨틱 세그멘테이션 1024, 깊이 768)에서 YOLO26n을 비교한 결과입니다. 기본 검증 데이터셋은 크기가 작으며, 동일한 이미지로 보정했습니다. 각 데이터셋에는 이미지가 4~8장뿐이므로, 이 수치는 어떤 작업이 INT8에 민감한지 보여주는 참고 자료로 보시고 yolo val로 자체 모델을 측정하세요.

작업지표ONNX 부동 소수점ST Edge AI 부동 소수점ST Edge AI INT8
감지mAP50-950.6860.6860.639
분할박스 / 마스크 mAP50-950.638 / 0.5400.638 / 0.5400.356 / 0.401
의미론적mIoU0.6100.6100.609
깊이delta10.8520.8520.840
포즈박스 / 포즈 mAP50-950.697 / 0.4590.697 / 0.4590.650 / 0.267
OBBmAP50-950.8940.8940.806

부동 소수점 내보내기는 모든 작업에서 표준 ONNX 내보내기와 동일한 결과를 냅니다. 인스턴스 세그멘테이션과 포즈는 전체 그래프 INT8에서 정확도 손실이 가장 큽니다. 마스크 계수와 키포인트가 박스와 하나의 출력 스케일을 공유하기 때문입니다. 배포 전에 자체 데이터로 이 두 작업을 신중하게 검증하세요.

STM32에 배포#

  1. 디바이스에서 실행할 imgsz에 맞춰 format="stedgeai"으로 모델을 내보내기합니다.

  2. yolo val을 사용해 데이터셋에서 부동 소수점 및 INT8 모델을 검증합니다.

  3. ST Edge AI Core로 모델을 컴파일합니다. 아래 명령은 ST Edge AI Core 명령줄 문서 및 Neural-ART 시작 가이드를 따릅니다. 메모리 프로파일과 입력 옵션은 해당 문서를 참조하세요.

    # Report the model's memory and operator usage for an STM32 target
    stedgeai analyze -m yolo26n_int8_stedgeai.onnx --target stm32
    
    # Generate the C model for an STM32N6 with the Neural-ART accelerator
    stedgeai generate -m yolo26n_int8_stedgeai.onnx --target stm32n6 --st-neural-art
  4. 생성된 모델을 STM32 애플리케이션에 배포합니다. STM32 AI Model Zoo Services는 STM32N6에서 Ultralytics YOLO 모델을 사용하는 애플리케이션 코드와 튜토리얼을 제공합니다.

출력에는 후처리가 필요합니다

디바이스의 C 후처리처럼 Ultralytics 외부에서 내보낸 모델을 읽는 코드는 박스 및 키포인트의 x 및 w 값에 입력 너비를 곱하고, y 및 h 값에 입력 높이를 곱해야 합니다. 또한 NMS를 실행하고, argmax 전에 시맨틱 로짓을 업샘플링하며, 깊이 출력을 업샘플링하기 전에 exp를 적용해야 합니다. 학습, 내보내기 및 배포 전반에서 imgsz를 동일하게 유지하세요.

자주 묻는 질문#

  • yolo export model=yolo26n.pt format=stedgeai quantize=8 data=coco8.yaml을 실행해 INT8 모델 yolo26n_int8_stedgeai.onnx을 생성하거나, quantize=8를 생략해 부동 소수점 모델 yolo26n_stedgeai.onnx을 생성합니다. 그런 다음 STM32에 배포에 나온 것처럼 ST Edge AI Core로 파일을 컴파일합니다.

  • ST Edge AI 내보내기는 박스 및 키포인트 좌표를 입력 크기 기준으로 정규화하여 클래스 점수와 동일한 [0, 1] 범위로 맞춥니다. 이를 통해 전체 그래프를 INT8로 양자화할 수 있습니다. 픽셀 좌표를 복원하려면 x 및 w에 입력 너비를 곱하고, y 및 h에 입력 높이를 곱하세요. Ultralytics는 _stedgeai.onnx 모델을 로드할 때 이 작업을 자동으로 수행합니다.

  • 아니요. 내보내기는 항상 원시 예측값을 반환하므로 애플리케이션에서 NMS를 실행하거나 STM32 AI Model Zoo Services의 후처리를 사용하세요.

  • 표준 ONNX 내보내기는 픽셀 좌표와 전체 해상도의 시맨틱 및 깊이 맵을 반환하고, NMS를 포함할 수 있으며, quantize=8을 사용하면 컨볼루션 및 행렬 곱셈 레이어만 양자화합니다. ST Edge AI 내보내기는 정규화된 좌표와 저해상도 시맨틱 로짓 및 로그 깊이를 반환하고, 배치 크기는 1로 고정되며, NMS를 포함하지 않습니다. 또한 quantize=8를 사용하면 전체 그래프를 양자화합니다.

  • 예. yolo val model=yolo26n_int8_stedgeai.onnx data=coco8.yaml은 컴퓨터에서 ONNX Runtime으로 양자화된 모델을 실행하고 다른 Ultralytics 모델과 동일한 지표를 보고합니다. 디바이스에서의 정확도는 조금 다를 수 있으므로, 컴파일한 후 ST 도구로 확인하세요.

기여자

댓글

질문을 하거나 결과를 공유하거나 다른 사람을 도와주세요.