SSD-MobileNetV1 ONNX 目标检测模型实战指南：ONNX Runtime 推理、图像预处理/后处理与 INT8 量化

SSD-MobileNetV1 ONNX 目标检测模型实战指南ONNX Runtime 推理、图像预处理/后处理与 INT8 量化【免费下载链接】modelsA collection of pre-trained, state-of-the-art models in the ONNX format项目地址: https://gitcode.com/gh_mirrors/model/models本文是围绕本仓库validated/vision/object_detection_segmentation/ssd-mobilenetv1/目录下 SSD-MobileNetV1 模型系列撰写的技术指南。SSD-MobileNetV1 是经典的单阶段目标检测模型兼顾检测精度与计算效率非常适合移动端与嵌入式视觉场景。通过本文你将掌握该系列 4 个 ONNX 模型变体含 INT8 量化版的差异与选型、基于 ONNX Runtime 的完整推理流程、NHWC/uint8图像输入的预处理方法、4 个输出张量的语义解析与后处理画框实现以及使用 Intel® Neural Compressor 对模型进行后训练量化的实操步骤。SSD-MobileNetV1 模型概述SSD-MobileNetV1 是一个单阶段目标检测模型其核心思想是将SSDSingle Shot MultiBox Detector单次多框检测器与MobileNet骨干网络相结合SSD是一类 CNN 检测框架只需对图像做一次前向推理single shot即可同时预测出图像中的多个目标及其边界框无需像 Faster R-CNN 那样分两阶段先提候选框、再分类回归进行MobileNet作为特征提取骨干网络为检测提供高层语义特征同时凭借深度可分离卷积大幅降低计算量。两者组合得到的 SSD-MobileNetV1 是一个高效、高精度、低计算成本的检测模型官方文档明确指出其适用于移动端与嵌入式视觉应用suitable for mobile and embedded vision applications。事实依据本节描述来源于 ssd-mobilenetv1/README.md 的 Description 部分。模型文件与版本选型本仓库为该模型提供了4 个 ONNX 变体全部位于 model 目录 下同时每个模型都附带了包含样本测试数据test_data_set的.tar.gz压缩包便于直接校验与跑通推理Model下载ONNX下载含样本测试数据ONNX 版本Opset 版本mAPSSD-MobilenetV129.3 MB27.9 MB1.7.010—SSD-MobilenetV1-1228.1 MB24.3 MB1.9.0120.2303SSD-MobilenetV1-12-int89.2 MB5.6 MB1.9.0120.2297SSD-MobilenetV1-12-qdq9.6 MB5.7 MB1.9.0130.2297注意上述.tar.gz包中的样本测试数据由验证工作流生成详见后文仓库验证机制一节可用于在不准备测试图片的情况下直接校验模型输出。量化收益对比官方数据与 fp32 版 SSD-MobilenetV1-12 相比int8 版 SSD-MobilenetV1-12 的mAP 下降幅度仅 0.26%而性能提升约 1.23 倍。性能数据采集环境为Intel® Xeon® Platinum 8280 处理器单实例 1s 4cCentOS Linux 8.3batch size 为 1。需要说明的是性能数据高度依赖具体测试硬件在不同平台上复测结果可能存在差异。通过 ONNX_HUB_MANIFEST.json 核验模型元信息仓库根目录的 ONNX_HUB_MANIFEST.json 是模型的统一索引清单其中完整记录了上述 4 个变体的 SHA 摘要、字节大小、tags 以及输入输出端口定义。例如ssd_mobilenet_v1_10.onnxmodel_sha为1fbcf476...模型字节数29275103约 27.9 MiB输入名为image_tensor:0ssd_mobilenet_v1_12-int8.onnx模型字节数9540809约 9.1 MiB输入名为inputsssd_mobilenet_v1_13-qdq.onnx虽然文件名带 12但opset 版本为 13输入名为inputs。从清单可以看出一个细节opset 10 版本保留的是原始 TensorFlow 风格的输入名image_tensor:0而 opset 12/13 的重导出版本统一使用inputs作为输入名编写推理代码时需要按实际模型版本匹配输入名。模型来源TensorFlow SSD-MobileNetV1 ⟹tf2onnx 转换⟹ ONNX SSD-MobileNetV1ONNX SSD-MobileNetV1 ⟹Intel® Neural Compressor 量化⟹ 量化版 ONNX SSD-MobileNetV1环境准备运行本模型推理的核心依赖为onnxruntime官方文档在 Quantization 章节给出环境为 onnx 1.9.0 / onnxruntime 1.8.0推理时建议使用相近或更新的版本numpy图像数据转换Pillow图像读取与画框matplotlib可视化展示可选安装命令示例pip install onnxruntime numpy pillow matplotlib基于 ONNX Runtime 的推理加载模型并执行推理以下代码展示了使用 ONNX Runtime 加载 SSD-MobileNetV1 ONNX 模型并执行推理的完整流程代码整理自官方 README 并补充了必要的导入与环境变量定义import os import onnxruntime as rt WORK validated/vision/object_detection_segmentation/ssd-mobilenetv1/model MODEL ssd_mobilenet_v1_12 outputs [num_detections:0, detection_boxes:0, detection_scores:0, detection_classes:0] # 加载模型并运行推理 # 自 ORT 1.10 起若要使用默认 CPU 执行提供程序ExecutionProvider以外的后端 # 必须在实例化 InferenceSession 时显式设置 providers 参数 # 例如 NVIDIA GPU 可用且 ORT Python 包以 CUDA 构建时 # rt.InferenceSession(path/to/model, providers[CUDAExecutionProvider]) sess rt.InferenceSession(os.path.join(WORK, MODEL .onnx)) result sess.run(outputs, {image_tensor:0: img_data}) num_detections, detection_boxes, detection_scores, detection_classes result # 打印检测数量 print(num_detections) print(detection_classes)提示上述代码中的输入名image_tensor:0对应 opset 10 版本的原始导出若使用 opset 12/13 的ssd_mobilenet_v1_12.onnx、_12-int8.onnx或_13-qdq.onnx需将输入字典的 key 改为inputs可通过sess.get_inputs()[0].name动态获取。输入约定该模型不要求固定图像尺寸no fixed image dimensions输入约束为batch size 1通道数为 3RGB数据排布为NHWC即(batch_size, height, width, channels)输入数据类型为uint80~255 的原始像素值不需要归一化到 [0,1]这正是 MobileNet SSD 这类检测模型的常见约定。ONNX_HUB_MANIFEST.json 中记录的输入端口image_tensor:0类型为tensor(uint8)形状为[unk__8520, unk__8521, unk__8522, 3]其中前三维为动态维度与不固定尺寸的约定一致。图像预处理预处理的核心目标是把任意尺寸的 RGB 图像转换为(1, H, W, 3)的uint8张量。官方给出的预处理代码如下import numpy as np from PIL import Image, ImageDraw, ImageColor import math import matplotlib.pyplot as plt # 打开并展示图像文件 img Image.open(image file) plt.axis(off) plt.imshow(img) plt.show() # 将 img.getdata() 返回的一维数组 reshape 为 HWC # 再增加一个维度变成 NHWC即一个只含 1 张图像的 batch img_data np.array(img.getdata()).reshape(img.size[1], img.size[0], 3) img_data np.expand_dims(img_data.astype(np.uint8), axis0)要点拆解img.getdata()返回的是一维像素数组按行优先排列因此先reshape为(H, W, 3)的 HWC 布局astype(np.uint8)显式将数据转换为uint8与模型输入类型tensor(uint8)对齐np.expand_dims(..., axis0)在首位插入 batch 维度得到(1, H, W, 3)。输出解析模型的类别标签基于COCO 数据集的 80 类目标person、car、dog 等。对每个 batch 的输入图像模型返回4 个张量数组输出名含义num_detections检测到的目标数量detection_boxes边界框列表每个框由(top, left, bottom, right)组成坐标值是相对图像尺寸的归一化比例0~1detection_scores每个检测框的置信度分数取值 0~1表示该类别被检测到的概率detection_classes长度为 10 的整数数组float 类型存储表示 COCO 类别标签的索引其中detection_classes的10是模型的最大检测数量上限模型会固定输出最多 10 个检测结果实际有效结果数以num_detections为准。Manifest 中记录的输出形状也印证了这一点detection_boxes形状为[batch, N, 4]N 为动态维度即最多 10detection_classes/detection_scores形状为[batch, N]。后处理绘制检测框与标签由于边界框坐标是相对图像尺寸的归一化值绘制时必须先乘以图像的宽高还原为像素坐标。官方后处理代码如下# 为每个检测绘制边界框和标签 def draw_detection(draw, d, c): width, height draw.im.size # 框坐标相对于图像尺寸因此乘以高和宽得到像素坐标 top d[0] * height left d[1] * width bottom d[2] * height right d[3] * width top max(0, np.floor(top 0.5).astype(int32)) left max(0, np.floor(left 0.5).astype(int32)) bottom min(height, np.floor(bottom 0.5).astype(int32)) right min(width, np.floor(right 0.5).astype(int32)) label coco_classes[c] label_size draw.textsize(label) if top - label_size[1] 0: text_origin tuple(np.array([left, top - label_size[1]])) else: text_origin tuple(np.array([left, top 1])) color ImageColor.getrgb(red) thickness 0 draw.rectangle([left thickness, top thickness, right - thickness, bottom - thickness], outlinecolor) draw.text(text_origin, label, fillcolor, fontfont) # 遍历结果——返回的每个张量都是一个 batch batch_size num_detections.shape[0] draw ImageDraw.Draw(img) for batch in range(0, batch_size): for detection in range(0, int(num_detections[batch])): c detection_classes[batch][detection] d detection_boxes[batch][detection] draw_detection(draw, d, c) # 展示带检测框和标签的图像 plt.figure(figsize(80, 40)) plt.axis(off) plt.imshow(img) plt.show()后处理流程的关键点坐标还原top d[0] * height、left d[1] * width等将归一化坐标映射回像素坐标边界裁剪通过max(0, ...)与min(height/width, ...)将越界坐标裁剪到图像范围内数量控制外层循环以int(num_detections[batch])为上限只绘制模型实际检测到的目标忽略多余的填充结果coco_classes是需要自行维护的 COCO 80 类标签列表c即detection_classes输出的类别索引。模型训练与转换背景训练数据集SSD-MobileNetV1 使用MS COCO 2017数据集进行训练包括 Train Images、Val Images 以及 Train/Val annotations。COCO 数据集同时提供目标检测标注与 80 类语义类别定义本模型的输出类别即来源于此。训练与转换模型的训练预处理细节以及 TensorFlow 模型到 ONNX 的转换过程可以参考官方配套的 tf2onnx 转换与推理 Notebook即 ConvertingSSDMobilenetToONNX.ipynb位于 tensorflow-onnx 项目的 tutorials 目录。该 Notebook 完整覆盖了在 SSD-MobileNetV1 上运行评估、导出为 TensorFlow SavedModel、转换为 ONNX以及输入/输出预处理和后处理代码的编写。INT8 量化使用 Intel® Neural CompressorSSD-MobilenetV1-12-int8opset 12与SSD-MobilenetV1-12-qdqopset 13均由 fp32 版SSD-MobilenetV1-12量化得到量化工具为Intel® Neural Compressor后端为 onnxruntime。量化方式为后训练量化PTQ。量化环境onnx: 1.9.0onnxruntime: 1.8.0准备模型先获取待量化的 fp32 模型此处以官方下载方式为例wget https://github.com/onnx/models/raw/main/vision/object_detection_segmentation/ssd-mobilenetv1/model/ssd_mobilenet_v1_12.onnx执行量化Intel® Neural Compressor 的量化入口为run_tuning.sh脚本需要在配置文件中指定正确的数据集路径配置内容包含校准数据集位置、量化策略、op 类型白名单等bash run_tuning.sh --input_modelpath/to/model \ # 模型路径格式为 *.onnx --configssd_mobilenet_v1.yaml \ --output_modelpath/to/save参数说明--input_model待量化的 fp32 ONNX 模型路径--configIntel® Neural Compressor 的 YAML 配置文件如ssd_mobilenet_v1.yaml其中需配置数据集路径、校准calibration方式与量化精度目标--output_model量化后模型的保存路径。量化效果从模型表格可以直观看到量化的收益模型体积ssd_mobilenet_v1_12.onnx约 28.1 MB ⟹ssd_mobilenet_v1_12-int8.onnx约 9.2 MB约为原来的 1/3精度mAP 从 0.2303 降至 0.2297降幅约 0.26%速度官方在同硬件环境下测得约 1.23x 性能提升。因此在带宽受限、存储受限或对延迟敏感的移动/嵌入式场景下优先推荐选用 INT8 量化版本对精度极其敏感的场景则可保留 fp32 版本。补充说明INT8 模型在部分平台上的推理加速依赖 CPU 的avx512vnni指令集支持这一点也在仓库验证脚本中有所体现见下节部署时建议确认目标硬件的指令集能力。仓库验证机制模型是如何被校验的本仓库对 ONNX 模型有一套完整的自动验证工作流位于 validated/workflow_scripts 目录SSD-MobileNetV1 目录下的.tar.gz样本测试数据即由该流程产出check_model.py核心校验逻辑。run_onnx_checker使用onnx.checker.check_model做结构合规检查run_backend_ort使用 ONNX Runtime 创建test_data_set_N测试目录并执行推理最后打包为.tar.gz。其中ort_skip_reason明确处理了-int8.onnx/-qdq.onnx模型依赖avx512vnni指令集的情况若当前机器不支持该指令集则只运行InferenceSession做形状推断跳过完整 ORT 数值比对test_models.pyCI 入口脚本。支持--target onnx|onnxruntime|all选择校验器、--all_models全量校验、--create用 ORT 重建损坏的测试数据等参数遍历text/与vision/目录下所有.onnx与.tar.gz模型。对读者而言这份工作流意味着每个.tar.gz内自带一组由 ONNX Runtime 官方生成的test_data_set_0无需准备测试图片即可验证模型的输入输出行为你也可以参照test_models.py的流程在自己的推理链路中对模型做同样的结构校验与数值比对。总结SSD-MobileNetV1 在本仓库中提供了一套完整的原始 fp32 ⟹ 重导出 fp32 ⟹ INT8 量化模型家族配套官方 README 与仓库级验证脚本使其成为一个理想的单阶段目标检测参考实现。实际落地时建议按如下路径决策选型快速验证用ssd_mobilenet_v1_10.onnx保留image_tensor:0原始输入名生产部署选 opset 12 的ssd_mobilenet_v1_12.onnx移动/嵌入式/低延迟场景优先ssd_mobilenet_v1_12-int8.onnx或ssd_mobilenet_v1_13-qdq.onnx推理牢记输入为(1, H, W, 3)的uint8张量NHWC不做归一化输出固定为num_detections / detection_boxes / detection_scores / detection_classes四个张量后处理检测框坐标为相对值绘制前需乘以图像宽高并做边界裁剪量化参照run_tuning.sh --input_model... --configssd_mobilenet_v1.yaml --output_model...的流程用 Intel® Neural Compressor 对 fp32 模型做 PTQ并留意目标硬件对avx512vnni的支持情况。【免费下载链接】modelsA collection of pre-trained, state-of-the-art models in the ONNX format项目地址: https://gitcode.com/gh_mirrors/model/models创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考