ONNX Model Zoo 中的 YOLOv3:模型文件、推理管线与 INT8 量化实战指南

原创2026-09-23 21:04:541,989 阅读
文章标签:人工智能深度学习计算机视觉NLP机器学习

ONNX Model Zoo 中的 YOLOv3:模型文件、推理管线与 INT8 量化实战指南

YOLOv3 是经典的单阶段实时目标检测网络,可在单张图像中同时检测 80 个不同类别的目标(基于 COCO 类别体系)。本指南以 validated/vision/object_detection_segmentation/yolov3/README.md 为核心,完整讲解 ONNX Model Zoo 中 YOLOv3 系列模型(YOLOv3、YOLOv3-12、YOLOv3-12-int8)的规格、输入输出格式、图像预处理与后处理完整管线,并结合仓库清单文件与相关模型目录,深入介绍基于 Intel® Neural Compressor 的 INT8 量化流程。读完本文,你将能够下载并运行这些 ONNX 模型,编写端到端的检测推理代码,并复现文档中的量化调优实验。

模型概述

YOLOv3 由 Joseph Redmon 与 Ali Farhadi 提出(论文 YOLOv3: An Incremental Improvement),是一个面向实时目标检测的神经网络。与两阶段检测器(如 Faster R-CNN)不同,YOLO 系列将检测视为回归问题,一次前向即可输出所有目标框与类别概率,因此在保证较高精度的同时具备非常快的推理速度。本仓库中该模型被验证为可检测 80 个不同类别,对应的类别清单源自 keras-yolo3 项目中基于 COCO 数据集的类别文件。

该模型由 keras 模型转换而来:原仓库基于 qqwweee/keras-yolo3,并使用 keras2onnx 转换器导出为 ONNX 格式。转换后的模型经过本仓库的精度验证流程,属于 README 中"Validated Models"列表下的目标检测与图像分割(Object Detection & Image Segmentation)类别。

模型文件与版本规格

在 model 目录 下存放了三个版本的 ONNX 模型及其携带示例测试数据的压缩包,规格对比如下:

Model 下载(纯模型) 下载(含示例测试数据) ONNX 版本 Opset 版本 精度
YOLOv3 237 MB 222 MB 1.5 10 mAP of 0.553
YOLOv3-12 237 MB 222 MB 1.9 12 mAP of 0.2874
YOLOv3-12-int8 60 MB 53 MB 1.9 12 mAP of 0.2693

对比 YOLOv3-12,YOLOv3-12-int8 的 mAP 下降了 0.0181,性能提升为 2.19x。

注意:性能数据依赖于测试硬件。

上述性能数据采集环境为 Intel® Xeon® Platinum 8280 处理器、每实例 1s 4c、CentOS Linux 8.3,数据 batch size 为 1。

从量化收益看,int8 模型体积从约 237 MB 压缩到约 60 MB(约 25%),同时推理加速约 2.19 倍,仅损失约 0.018 的 mAP——这对在 CPU 上部署实时检测服务的场景极具吸引力。

从清单文件确认模型元信息

仓库根目录的 ONNX_HUB_MANIFEST.json 中登记了这三个模型的完整元数据(第 8448–8650 行左右),包括 SHA 校验值、字节数、输入输出端口(io_ports)等,可用于核对下载文件的完整性。例如:

  • yolov3-10.onnx:model_sha 为 1f4613c3d0...,model_bytes 为 247908721;
  • yolov3-12-int8.onnx:model_sha 为 9230c02f...,model_bytes 为 62912863;
  • yolov3-12.onnx:model_sha 为 d97d7d5c...,model_bytes 为 247942267。

三个模型均带有 vision、object detection segmentation、yolov3 标签,输入输出端口结构一致(详见下文"输入与输出"小节)。

推理管线

输入到模型

YOLOv3 系列模型接受两个输入:

  1. Resized image:形状为 (1x3x416x416) 的 NCHW 浮点张量,即一张经过缩放并填充到 416×416 的 RGB 图像;
  2. Original image size:形状为 (1x2),内容为 [image.size[1], image.size[0]],即原始图像的 (高, 宽),用于将模型输出的缩放坐标还原到原图坐标系。

清单文件中登记的两个输入名分别为 input_1(tensor(float))与 image_shape(tensor(float)),后者维度固定为 (unk, 2)。

预处理步骤

图像需要先被归一化到 [0, 1] 区间,该变换最好在预处理阶段完成(而非依赖模型内部的归一化层)。同时,为了不破坏原始宽高比,采用 YOLO 系列经典的 letterbox 策略:按比例缩放图像后,用灰色(128,128,128)填充四周至目标尺寸 416×416。

以下代码展示了如何将一张 PIL 图像预处理为 NCHW 张量:

import numpy as np
from PIL import Image

# this function is from yolo3.utils.letterbox_image
def letterbox_image(image, size):
    '''resize image with unchanged aspect ratio using padding'''
    iw, ih = image.size
    w, h = size
    scale = min(w/iw, h/ih)
    nw = int(iw*scale)
    nh = int(ih*scale)

    image = image.resize((nw,nh), Image.BICUBIC)
    new_image = Image.new('RGB', size, (128,128,128))
    new_image.paste(image, ((w-nw)//2, (h-nh)//2))
    return new_image

def preprocess(img):
    model_image_size = (416, 416)
    boxed_image = letterbox_image(img, tuple(reversed(model_image_size)))
    image_data = np.array(boxed_image, dtype='float32')
    image_data /= 255.
    image_data = np.transpose(image_data, [2, 0, 1])
    image_data = np.expand_dims(image_data, 0)
    return image_data

image = Image.open(img_path)
# input
image_data = preprocess(image)
image_size = np.array([image.size[1], image.size[0]], dtype=np.int32).reshape(1, 2)

要点拆解:

  • letterbox_image:以 min(w/iw, h/ih) 作为缩放系数,保证缩放后图像完整落在目标画布内;不足部分用灰色填充并居中,最终返回 416×416 的 RGB 图像;
  • image_data /= 255.:将像素值归一化到 [0,1];
  • np.transpose(image_data, [2, 0, 1]):将 HWC 布局转换为 CHW(NCHW 的前三维);
  • np.expand_dims(image_data, 0):增加 batch 维度,得到 (1,3,416,416);
  • image_size:以 (高, 宽) 顺序构造 (1,2) 张量,与模型的第二个输入对齐。

补充说明:在 Tiny YOLOv3 的文档 tiny-yolov3/README.md 中,image_size 使用 dtype=np.float32 构造;而 YOLOv3 本模型使用 dtype=np.int32。两者均以 [image.size[1], image.size[0]] 的顺序传入原始尺寸,实际使用时应以所加载模型对第二输入的类型要求为准(清单中 image_shape 的类型为 tensor(float),若遇到类型不匹配,可统一转成 float32)。

输出到模型

模型共有 3 个输出:

  1. boxes:形状 (1x'n_candidates'x4),所有候选锚框的坐标;
  2. scores:形状 (1x80x'n_candidates'),每个锚框在 80 个类别上的得分;
  3. indices:形状 ('nbox'x3),从 boxes 张量中筛选出的索引,索引格式为 (batch_index, class_index, box_index)。

清单文件中对应的三个输出名分别为 yolonms_layer_1/ExpandDims_1:0(tensor(float))、yolonms_layer_1/ExpandDims_3:0(tensor(float))与 yolonms_layer_1/concat_2:0(tensor(int32)),可见模型内部已集成了 NMS(Non-Maximum Suppression)与解码逻辑——这正是它与早期 YOLO 导出格式(如 tiny-yolov2 中直接输出 (1x125x13x13) 原始张量)的最大区别:后处理中的大量繁琐步骤已内建到 ONNX 图中,推理代码因此非常简洁。

后处理步骤

indices 输出直接给出了最终保留的目标索引,因此后处理只需按索引从 boxes 与 scores 中取回对应元素即可:

out_boxes, out_scores, out_classes = [], [], []
for idx_ in indices:
    out_classes.append(idx_[1])
    out_scores.append(scores[tuple(idx_)])
    idx_1 = (idx_[0], idx_[2])
    out_boxes.append(boxes[idx_1])
  • out_classes:每个目标的类别索引(idx_[1]),可进一步映射到 80 类 COCO 类别名;
  • out_scores:每个目标在对应类别上的置信度得分,通过 scores[tuple(idx_)] 按 (batch, class, box) 下标取出;
  • out_boxes:每个目标的边界框坐标,通过 boxes[(batch, box)] 取出。

最终 out_boxes、out_scores、out_classes 即为检测结果:边界框列表、置信度列表与类别列表。Tiny YOLOv3 的文档中使用 for idx_ in indices[0] 遍历(其索引张量多一维 batch),而 YOLOv3 直接遍历 indices,二者遍历方式略有差异,但取回逻辑一致。

数据集与验证精度

模型的预训练权重来自 pjreddie.com 提供的 yolov3.weights(Darknet 官方权重),本仓库只负责将其转换并验证,不包含训练流程。

验证指标与数据如下:

  • YOLOv3:指标为 COCO box mAP(对 IoU 0.5:0.95 取平均),在 2017 COCO val 数据上计算,mAP 为 0.553(对应 Darknet 官方 YOLOv3 的原始精度);
  • YOLOv3-12 与 YOLOv3-12-int8:指标为 COCO box mAP@[IoU=0.50:0.95 | area=all | maxDets=100],同样在 2017 COCO val 数据上计算,mAP 分别为 0.2874 与 0.2693。

从源码结构看,YOLOv3(Opset 10)与 YOLOv3-12(Opset 12)在输出端口与模型结构上保持一致,mAP 数值差异主要源于验证口径与实现版本的细微差别;而 int8 版本与 fp32 版本相比仅损失 0.0181 的 mAP,精度保持良好。

INT8 量化实战

量化方案

YOLOv3-12-int8 是通过对 YOLOv3-12 模型进行量化得到的。量化使用 Intel® Neural Compressor,以 onnxruntime 作为后端执行。Intel® Neural Compressor 是一款开源的精度驱动调优库:它自动尝试多种量化策略,帮助用户快速找到最优的量化模型;支持 ONNX 模型的动态与静态量化,并可以 operator-oriented 与 tensor-oriented(QDQ)两种方式表示量化后的 ONNX 模型(详见仓库根目录 README.md 中关于 INT8 模型的说明)。

环境要求

  • onnx:1.9.0
  • onnxruntime:1.10.0

准备模型

先下载待量化的 fp32 模型:

wget https://github.com/onnx/models/raw/main/vision/object_detection_segmentation/yolov3/model/yolov3-12.onnx

如果你已经从本仓库获取了模型,也可以直接使用 validated/vision/object_detection_segmentation/yolov3/model/yolov3-12.onnx 作为 --input_model。

模型量化

使用 Neural Compressor 提供的 run_tuning.sh 脚本进行精度驱动量化调优:

bash run_tuning.sh --input_model=path/to/model \  # model path as *.onnx
                   --config=yolov3.yaml \
                   --data_path=path/to/COCO2017 \
                   --output_model=path/to/save

参数说明:

  • --input_model:输入的 ONNX 模型路径,必须是 *.onnx 文件(此处即 yolov3-12.onnx);
  • --config:量化配置文件 yolov3.yaml,用于声明量化精度目标、量化策略与评估配置;
  • --data_path:COCO 2017 数据集路径,用于精度评估与校准数据采集;
  • --output_model:量化后模型的保存路径。

这一流程对应了 Neural Compressor 的典型工作方式:以 COCO 2017 作为校准与验证数据,在给定精度损失预算(由 yolov3.yaml 配置)内自动搜索最优量化参数,最终输出满足精度要求的 int8 模型,即本文模型表格中的 YOLOv3-12-int8。

使用 ONNX 模型的一般方法

本仓库所有模型均遵循统一的 ONNX Model Zoo 使用约定:解压每个模型的 tar.gz 后,会得到一个 model.onnx(protobuf 序列化文件)与示例测试数据(序列化 TensorProto 或 NumPy 归档)。仓库根目录 README.md 提供了两种加载测试数据并验证模型的入门代码:

  • TensorProto 格式(.pb):存放在 test_data_set_* 目录中,使用 onnx.TensorProto 解析 input_*.pb 与 output_*.pb,再用 numpy_helper.to_array 转为 NumPy 数组后喂给 ONNX 后端,最后通过 np.testing.assert_almost_equal 与参考输出比对;
  • NumPy 归档格式(.npz):每个 .npz 文件包含一组输入与输出,直接 np.load 后即可用于校验。

以 onnxruntime 为例(替换代码中的 onnx_backend 为 onnxruntime、backend.run_model 为 session.run),即可对 YOLOv3 模型执行真实推理:将上一节 preprocess 得到的 image_data 与 image_size 作为两个输入,运行后获得 boxes、scores、indices 三个输出,再套用后处理代码即可得到最终检测框。若希望可视化模型结构,官方推荐使用 Netron 打开 .onnx 文件查看各节点与张量形状。

总结

本文围绕 ONNX Model Zoo 中的 YOLOv3 系列模型,梳理了三个版本的规格与精度对比,完整还原了从图像读取、letterbox 预处理、模型推理到索引后处理的端到端流程,并给出了基于 Intel® Neural Compressor + onnxruntime 的 INT8 量化实操命令。读者可以直接复用文中的 Python 代码与 shell 命令,在本仓库 yolov3/model 目录下的模型文件上完成部署与量化实验。

该模型使用 MIT License 许可,论文出处为 Joseph Redmon、Ali Farhadi 的 YOLOv3: An Incremental Improvement(2018)。

登录后查看全文
models