开始使用

为 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] 为单位的边界框。

导出参数#

参数类型默认值说明
formatstr'stedgeai'导出模型的目标格式。
imgszint 或 tuple640模型输入尺寸:正方形图像使用整数,或者使用 (height, width) 元组。模型的批量大小固定为 1,且形状是静态的。OBB 模型要求 imgsz 为正方形。
quantizeint 或 strNone精度。未设置或设为 32 时会生成浮点模型;设为 8 时会生成 INT8 模型。
datastrNone用于 INT8 校准的数据集:数据集 YAML 文件,或用于分类任务的数据集目录或内置数据集名称。如果不提供,quantize=8 会使用任务的默认数据集,例如检测任务使用 coco8.yaml。
fractionfloat1.0要使用的校准数据集比例。
opsetintNoneONNX opset。默认使用你的 PyTorch 版本能够可靠导出的最新 opset。
simplifyboolTrue使用 onnxslim 简化 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 激活值。
  • 对 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-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. 使用 format="stedgeai" 导出模型,并将 imgsz 设为你将在设备上运行的尺寸。

  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 模型的应用程序代码和教程。

输出需要后处理

在 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 工具进行确认。

贡献者

评论

提出问题、分享结果,或帮助其他人。