Bắt đầu

Xuất model Ultralytics YOLO sang ST Edge AI

Xuất model Ultralytics YOLO với format="stedgeai" để tạo model ONNX có cấu trúc phù hợp với ST Edge AI Core, bộ công cụ của STMicroelectronics dùng để biên dịch mạng neural cho vi điều khiển STM32, bao gồm STM32N6 với bộ tăng tốc Neural-ART. Theo mặc định, quá trình xuất tạo model float và một model INT8 được lượng tử hóa hoàn toàn bằng quantize=8. Ultralytics chạy cả hai tệp trên máy tính bằng yolo predict và yolo val, giúp bạn đo độ chính xác trước khi biên dịch cho thiết bị.

Đã xác thực trên máy chủ

Ultralytics xác thực các model này bằng ONNX Runtime trên máy tính, còn STMicroelectronics đã biên dịch các bản xuất INT8 của cả bảy tác vụ cho STM32N6 bằng ST Edge AI Core. Bạn cần dùng công cụ ST để đo độ chính xác, độ trễ và bộ nhớ trên bo mạch STM32; xem Triển khai lên STM32.

Vì sao cần định dạng ST Edge AI chuyên dụng?#

Vi điều khiển chạy model INT8, nhưng quá trình xuất ONNX tiêu chuẩn không lượng tử hóa hiệu quả toàn bộ quy trình:

  • Các khoảng giá trị khác nhau trong một đầu ra. Detection head của YOLO kết hợp tọa độ box tính bằng pixel (khoảng từ 0 đến 640) và điểm số lớp (từ 0 đến 1) trong một tensor duy nhất. Lượng tử hóa INT8 gán cho tensor đó một scale duy nhất, khiến độ phân giải của điểm số gần như mất hoàn toàn. ST Edge AI chuẩn hóa tọa độ box và keypoint về [0, 1] theo kích thước đầu vào, tương tự cách Ultralytics chuẩn hóa cho Edge TPU, nhờ đó có thể lượng tử hóa toàn bộ graph.
  • Đầu ra dày đặc, kích thước lớn. Các model phân đoạn ngữ nghĩa và độ sâu thường tăng kích thước lên bằng độ phân giải đầu vào bên trong graph. ST Edge AI dừng trước bước tăng kích thước này, nhờ đó buffer đầu ra nhỏ hơn 64 lần đối với phân đoạn ngữ nghĩa và 16 lần đối với độ sâu; đồng thời, giá trị độ sâu được giữ ở miền log, nơi các mức INT8 được phân bố đồng đều.
  • Hậu xử lý bên trong graph. NMS nhúng và head không cần NMS của YOLO26 bổ sung các toán tử TopK và gather sau head. Quá trình xuất loại bỏ chúng và luôn trả về dự đoán thô, vì vậy NMS được chạy trong ứng dụng của bạn.

Nếu bạn cần bố cục tiêu chuẩn (tọa độ pixel, bản đồ độ phân giải đầy đủ, NMS nhúng tùy chọn), hãy dùng xuất ONNX.

Các tác vụ được hỗ trợ#

Tất cả tác vụ Ultralytics YOLO đều được xuất và chạy trên máy chủ. Các hình dạng đầu ra dành cho imgsz=640:

Tác vụĐầu ra
Phát hiện[1, 4 + nc, 8400]: box được chuẩn hóa về [0, 1], điểm số lớp
Phân đoạn đối tượng[1, 4 + nc + 32, 8400] với box được chuẩn hóa về [0, 1], cùng các prototype mask [1, 32, 160, 160]
Phân đoạn ngữ nghĩaLogit lớp [1, nc, 80, 80] ở độ phân giải 1/8; tăng kích thước, sau đó lấy argmax theo từng pixel
Ước lượng độ sâuĐộ sâu log [1, 1, 160, 160] ở độ phân giải 1/4; áp dụng exp(x) để tính độ sâu theo đơn vị thực, sau đó tăng kích thước
Phân loạiXác suất lớp [1, nc]
Ước lượng tư thế[1, 4 + nc + nk, 8400]: box và keypoint được chuẩn hóa về [0, 1]
Phát hiện hộp định hướng[1, 4 + nc + 1, 8400]: box được chuẩn hóa về [0, 1], góc tính bằng radian; yêu cầu imgsz hình vuông

Không hỗ trợ model RT-DETR và YOLO-NAS.

Cách sử dụng#

Export
from ultralytics import YOLO

# Nạp model YOLO26
model = YOLO("yolo26n.pt")

# Xuất model float
model.export(format="stedgeai")  # tạo 'yolo26n_stedgeai.onnx'

# Xuất model INT8 được hiệu chuẩn trên COCO8
model.export(format="stedgeai", quantize=8, data="coco8.yaml")  # tạo 'yolo26n_int8_stedgeai.onnx'
Dự đoán và xác thực trên máy chủ
from ultralytics import YOLO

# Tải model ST Edge AI đã xuất
model = YOLO("yolo26n_int8_stedgeai.onnx")

# Chạy suy luận
results = model("https://ultralytics.com/images/bus.jpg")

# Đo độ chính xác INT8 trên tập dữ liệu COCO8
metrics = model.val(data="coco8.yaml")

Mỗi lần xuất tạo một tệp. Ultralytics nhận diện model ST Edge AI dựa trên hậu tố _stedgeai.onnx, rồi chuyển tọa độ về pixel, tăng kích thước bản đồ ngữ nghĩa và độ sâu, đồng thời chuyển độ sâu log sang độ sâu theo đơn vị thực. Hãy giữ nguyên hậu tố này khi đổi tên tệp; tên .onnx thông thường sẽ được tải dưới dạng model ONNX tiêu chuẩn và trả về box theo [0, 1].

Các tham số xuất model#

Đối sốKiểuMặc địnhMô tả
formatstr'stedgeai'Định dạng đích của model được xuất.
imgszint hoặc tuple640Kích thước đầu vào của model: số nguyên đối với ảnh vuông hoặc bộ giá trị (height, width). Model có batch size cố định là 1 và hình dạng tĩnh. Model OBB yêu cầu imgsz hình vuông.
quantizeint hoặc strNoneĐộ chính xác. Nếu không đặt hoặc dùng 32, quá trình xuất tạo model float; 8 tạo model INT8.
datastrNoneTập dữ liệu dùng để hiệu chuẩn INT8: tệp YAML của tập dữ liệu, hoặc thư mục tập dữ liệu hay tên tập dữ liệu tích hợp sẵn đối với phân loại. Nếu không cung cấp, quantize=8 dùng tập dữ liệu mặc định của tác vụ, chẳng hạn coco8.yaml cho detection.
fractionfloat1.0Tỷ lệ dataset hiệu chuẩn sẽ được sử dụng.
opsetintNoneONNX opset. Mặc định là opset mới nhất mà phiên bản PyTorch của bạn có thể xuất một cách ổn định.
simplifyboolTrueĐơn giản hóa graph ONNX bằng onnxslim.
devicestrNoneThiết bị dùng để xuất: GPU (device=0) hoặc CPU (device=cpu).

batch và dynamic=True sẽ bị từ chối; nms=True sẽ chuyển về đầu ra thô kèm cảnh báo.

Lượng tử hóa INT8#

Với quantize=8, Ultralytics lượng tử hóa model bằng phương pháp lượng tử hóa tĩnh của ONNX Runtime, theo phương pháp mà ST Edge AI Core khuyến nghị và STM32 AI Model Zoo Services áp dụng:

  • Định dạng QDQ (QuantizeLinear/DequantizeLinear) với đầu vào và đầu ra của model ở dạng float.
  • Trọng số INT8 có dấu, đối xứng theo từng kênh và activation INT8 có dấu, bất đối xứng.
  • Hiệu chuẩn MinMax trên các ảnh data, được tiền xử lý chính xác như trong quá trình xác thực Ultralytics.

Khác với quá trình xuất ONNX quantize=8 tiêu chuẩn, vốn giữ head ở dạng float, mọi toán tử đều được lượng tử hóa. Để lượng tử hóa bằng công cụ ST, hãy xuất model float rồi chuyển model đó cho STM32 AI Model Zoo Services.

Hiệu chuẩn bằng dữ liệu của bạn

Độ chính xác INT8 phụ thuộc vào mức độ tương đồng giữa ảnh hiệu chuẩn và cảnh triển khai. Hãy cung cấp cho data= một tập dữ liệu có ít nhất 300 ảnh đại diện; các tập dữ liệu hiệu chuẩn mặc định chỉ chứa một vài mẫu công khai.

Bảng dưới đây so sánh YOLO26n ở imgsz mặc định của từng model (640, phân đoạn ngữ nghĩa 1024, độ sâu 768) trên các tập dữ liệu xác thực mặc định nhỏ, được hiệu chuẩn trên cùng các ảnh. Mỗi tập dữ liệu chỉ có 4 đến 8 ảnh, vì vậy hãy xem các con số này như chỉ dấu về mức độ nhạy cảm với INT8 của từng tác vụ và đo model của bạn bằng yolo val.

Tác vụChỉ sốONNX floatST Edge AI floatST Edge AI INT8
DetectmAP50-950.6860.6860.639
SegmentmAP50-95 của box / mask0.638 / 0.5400.638 / 0.5400.356 / 0.401
Ngữ nghĩamIoU0.6100.6100.609
Độ sâudelta10.8520.8520.840
Tư thếmAP50-95 của box / pose0.697 / 0.4590.697 / 0.4590.650 / 0.267
OBBmAP50-950.8940.8940.806

Bản xuất float khớp với bản xuất ONNX tiêu chuẩn ở mọi tác vụ. Phân đoạn instance và pose mất độ chính xác nhiều nhất khi lượng tử hóa INT8 toàn bộ graph, do hệ số mask và keypoint dùng chung một scale đầu ra với box; hãy xác thực kỹ hai tác vụ này trên dữ liệu của bạn trước khi triển khai.

Triển khai lên STM32#

  1. Xuất model bằng format="stedgeai" ở imgsz mà bạn sẽ chạy trên thiết bị.

  2. Xác thực model float và INT8 trên tập dữ liệu của bạn bằng yolo val.

  3. Biên dịch model bằng ST Edge AI Core. Các lệnh dưới đây tuân theo tài liệu dòng lệnh và hướng dẫn bắt đầu với Neural-ART của ST Edge AI Core; hãy tham khảo các tài liệu này để biết cấu hình bộ nhớ và tùy chọn đầu vào.

    # 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. Triển khai model đã tạo trong ứng dụng STM32 của bạn. STM32 AI Model Zoo Services cung cấp mã ứng dụng và hướng dẫn cho model Ultralytics YOLO trên STM32N6.

Đầu ra cần hậu xử lý

Mã đọc model đã xuất bên ngoài Ultralytics, chẳng hạn mã hậu xử lý C trên thiết bị, phải nhân các giá trị x và w của box và keypoint với chiều rộng đầu vào, đồng thời nhân các giá trị y và h với chiều cao đầu vào; chạy NMS; tăng kích thước logit ngữ nghĩa trước khi lấy argmax; và áp dụng exp cho đầu ra độ sâu trước khi tăng kích thước. Hãy giữ imgsz nhất quán giữa quá trình huấn luyện, xuất và triển khai.

Câu hỏi thường gặp#

  • Chạy yolo export model=yolo26n.pt format=stedgeai quantize=8 data=coco8.yaml để tạo model INT8 yolo26n_int8_stedgeai.onnx, hoặc bỏ quantize=8 để tạo model float yolo26n_stedgeai.onnx. Sau đó biên dịch tệp bằng ST Edge AI Core như hướng dẫn trong Triển khai lên STM32.

  • ST Edge AI chuẩn hóa tọa độ box và keypoint theo kích thước đầu vào để chúng nằm cùng khoảng giá trị [0, 1] với điểm số lớp, nhờ đó có thể lượng tử hóa toàn bộ graph sang INT8. Nhân x và w với chiều rộng đầu vào, đồng thời nhân y và h với chiều cao đầu vào để khôi phục tọa độ pixel. Ultralytics tự động thực hiện việc này khi tải model _stedgeai.onnx.

  • Không. Bản xuất luôn trả về dự đoán thô, vì vậy hãy chạy NMS trong ứng dụng của bạn hoặc dùng bước hậu xử lý trong STM32 AI Model Zoo Services.

  • Bản xuất ONNX tiêu chuẩn trả về tọa độ pixel và bản đồ ngữ nghĩa, độ sâu ở độ phân giải đầy đủ, có thể nhúng NMS và với quantize=8 chỉ lượng tử hóa các lớp tích chập và nhân ma trận. Bản xuất ST Edge AI trả về tọa độ đã chuẩn hóa, logit ngữ nghĩa và độ sâu log ở độ phân giải thấp, có batch size cố định là 1, không bao giờ nhúng NMS và với quantize=8 sẽ lượng tử hóa toàn bộ graph.

  • Có. yolo val model=yolo26n_int8_stedgeai.onnx data=coco8.yaml chạy model đã lượng tử hóa bằng ONNX Runtime trên máy tính và báo cáo các metric tương tự mọi model Ultralytics khác. Độ chính xác trên thiết bị vẫn có thể chênh lệch đôi chút, vì vậy hãy xác nhận bằng công cụ ST sau khi biên dịch.

Người đóng góp

Bình luận

Đặt câu hỏi, chia sẻ kết quả hoặc giúp đỡ người khác.