为 Ultralytics YOLO 模型导出 ST Edge AI
使用 format="stedgeai" 导出 Ultralytics YOLO 模型,生成适用于 ST Edge AI Core 的 ONNX 模型。ST Edge AI Core 是 STMicroelectronics 的工具链,可为 STM32 微控制器(包括配备 Neural-ART 加速器的 STM32N6)编译神经网络。默认情况下,导出会生成浮点模型;使用 quantize=8 还会生成完全量化的 INT8 模型。Ultralytics 会在计算机上使用 yolo predict 和 yolo val 运行这两个文件,因此你可以在为设备编译前测量精度。
Ultralytics 使用计算机上的 ONNX Runtime 验证这些模型;STMicroelectronics 则使用 ST Edge AI Core 为 STM32N6 编译了全部七项任务的 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 分辨率下的类别 logits [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] 为单位的边界框。
导出参数#
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
format | str | 'stedgeai' | 导出模型的目标格式。 |
imgsz | int 或 tuple | 640 | 模型输入尺寸:正方形图像使用整数,或者使用 (height, width) 元组。模型的批量大小固定为 1,且形状是静态的。OBB 模型要求 imgsz 为正方形。 |
quantize | int 或 str | None | 精度。未设置或设为 32 时会生成浮点模型;设为 8 时会生成 INT8 模型。 |
data | str | None | 用于 INT8 校准的数据集:数据集 YAML 文件,或用于分类任务的数据集目录或内置数据集名称。如果不提供,quantize=8 会使用任务的默认数据集,例如检测任务使用 coco8.yaml。 |
fraction | float | 1.0 | 要使用的校准数据集比例。 |
opset | int | None | ONNX opset。默认使用你的 PyTorch 版本能够可靠导出的最新 opset。 |
simplify | bool | True | 使用 onnxslim 简化 ONNX 计算图。 |
device | str | None | 导出时使用的设备: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 激活值。
- 对
data张图像进行 MinMax 校准,预处理方式与 Ultralytics 验证时完全相同。
与标准 ONNX quantize=8 导出不同,后者会让检测头保留浮点格式;此处每个算子都会量化。如果要改用 ST 工具进行量化,请导出浮点模型,并将其传递给 STM32 AI Model Zoo Services。
INT8 精度取决于校准图像与部署场景的匹配程度。向 data= 提供至少包含 300 张代表性图像的数据集;默认校准数据集只包含少量公开样本。
下表比较了 YOLO26n 在各模型默认 imgsz(640、语义分割 1024、深度 768)下的表现。模型在较小的默认验证数据集上评估,并使用相同图像进行校准。这些数据集各包含 4 到 8 张图像,因此这些数值仅能说明哪些任务对 INT8 比较敏感;请使用 yolo val 测量你自己的模型。
| 任务 | 指标 | ONNX 浮点 | ST Edge AI 浮点 | ST Edge AI INT8 |
|---|---|---|---|---|
| 检测 | mAP50-95 | 0.686 | 0.686 | 0.639 |
| 分割 | 边界框 / 掩码 mAP50-95 | 0.638 / 0.540 | 0.638 / 0.540 | 0.356 / 0.401 |
| 语义 | mIoU | 0.610 | 0.610 | 0.609 |
| 深度 | delta1 | 0.852 | 0.852 | 0.840 |
| 姿态 | 边界框 / 姿态 mAP50-95 | 0.697 / 0.459 | 0.697 / 0.459 | 0.650 / 0.267 |
| OBB | mAP50-95 | 0.894 | 0.894 | 0.806 |
浮点导出在所有任务上的表现都与标准 ONNX 导出一致。整图 INT8 量化对实例分割和姿态任务的精度影响最大,因为掩码系数和关键点与边界框共用一个输出缩放比例;部署前,请务必使用你自己的数据仔细验证这两项任务。
部署到 STM32#
-
使用
format="stedgeai"导出模型,并将imgsz设为你将在设备上运行的尺寸。 -
使用
yolo val验证数据集上的浮点和 INT8 模型。 -
使用 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 -
在 STM32 应用程序中部署生成的模型。STM32 AI Model Zoo Services 提供了在 STM32N6 上运行 Ultralytics YOLO 模型的应用程序代码和教程。
在 Ultralytics 之外读取导出模型的代码(例如设备上的 C 后处理代码)必须将边界框和关键点的 x 和 w 值乘以输入宽度,将 y 和 h 值乘以输入高度;还必须运行 NMS、在计算 argmax 前上采样语义 logits,并在上采样深度输出前应用 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 导出返回归一化坐标、低分辨率语义 logits 和对数深度,批量大小固定为 1,且绝不嵌入 NMS;使用quantize=8时,会量化整个计算图。可以。
yolo val model=yolo26n_int8_stedgeai.onnx data=coco8.yaml会在你的计算机上使用 ONNX Runtime 运行量化模型,并报告与其他任何 Ultralytics 模型相同的指标。设备上的精度仍可能略有差异,因此编译后请使用 ST 工具进行确认。
评论
提出问题、分享结果,或帮助其他人。