ONNX Model Zoo 中的 ResNet 图像分类模型:从架构原理到推理、量化与源码实践

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

ONNX Model Zoo 中的 ResNet 图像分类模型:从架构原理到推理、量化与源码实践

导读

ResNet 是深度学习中影响最为深远的卷积网络架构之一,它以"残差学习"框架解决了深层网络难以训练的问题,并在 ImageNet 上以最多 152 层的深度(约为 VGG 的 8 倍深、而计算复杂度更低)取得了当时顶尖的分类精度。本文以 ONNX Model Zoo 仓库中 validated/vision/classification/resnet/README.md 为主线,系统讲解仓库内 ResNet v1/v2 系列 ONNX 模型的文件布局、推理输入输出约定、ImageNet 预处理/后处理细节、可复制的 ONNX 预处理子图代码,以及基于 Intel® Neural Compressor 的 INT8/QDQ 量化实践,并结合仓库源码与辅助脚本给出可直接运行的实战方案。

一、ResNet 在 ONNX Model Zoo 中的定位与使用场景

ResNet 系列模型承担的是**图像分类(Image Classification)**任务:输入一张图像,输出图像中主体对象在预定义类别集合上的分类得分。仓库 README.md 中将其列为 Image Classification 模型类别之一,参考论文为 He et al. 的《Deep Residual Learning for Image Recognition》,论文中 ResNet 在 ImageNet 上的 Top-5 误差约为 3.6%。

它的典型适用场景是对分类精度要求较高的任务:ResNet 系列在保证模型体积可接受的前提下提供了非常高的精度,且由于推理时只做一次前向传播(而非两阶段检测),非常适合作为通用视觉特征的骨干网络,也常被用作目标检测、分割模型的 Backbone。在本文仓库中,你也可以看到大量以 ResNet 为骨干的衍生模型,例如:

它们均以 ResNet-50-FPN 为骨干,足以说明 ResNet 在视觉任务生态中的基础地位。

二、ResNet 架构原理:残差学习与两种残差块变体

2.1 残差学习框架

更深的神经网络通常更难训练。ResNet 的核心思想是:不再让每一层直接学习"无参照的映射函数",而是显式地把层重构为"相对于层输入的残差函数"。即在网络中引入恒等快捷连接(identity shortcut),使得深层网络在训练时更容易优化,并且精度可以随深度增加而持续提升。

在 ImageNet 数据集上,残差网络被验证到 152 层深度(相比 VGG 深约 8 倍,但复杂度更低)。

2.2 ResNet v1 与 v2 的区别

变体 残差块中的激活位置 说明
ResNet v1 后激活(post-activation) 经典的原始残差块设计(论文 v1)
ResNet v2 预激活(pre-activation) BN 与 ReLU 放在卷积之前,来自《Identity Mappings in Deep Residual Networks》

在本文关联的 README 中,仓库同时提供了 v1、v2 两个系列的 18/34/50/101/152 层模型,便于对比两种残差块设计在同一深度下的精度差异。

三、模型文件一览:ResNet v1 / v2 / Caffe2 / 量化版

本小节完整对应 README 中的模型清单。所有文件均位于 validated/vision/classification/resnet/model 目录下,每个模型同时提供两种下载形式:

  • .onnx:序列化后的 ONNX 模型文件(protobuf);
  • .tar.gz:包含模型及示例测试数据(serialized protobuf TensorProto 或 NumPy 归档)的压缩包,可用于验证模型正确性。

3.1 ResNet V1 系列(Opset 7,ONNX 1.2.1)

模型 onnx 文件 含测试数据包 ONNX 版本 Opset Top-1 (%) Top-5 (%)
ResNet18 resnet18-v1-7.onnx (44.7 MB) resnet18-v1-7.tar.gz (42.9 MB) 1.2.1 7 69.93 89.29
ResNet34 resnet34-v1-7.onnx (83.3 MB) resnet34-v1-7.tar.gz (78.6 MB) 1.2.1 7 73.73 91.40
ResNet50 resnet50-v1-7.onnx (97.8 MB) resnet50-v1-7.tar.gz (92.2 MB) 1.2.1 7 74.93 92.38
ResNet101 resnet101-v1-7.onnx (170.6 MB) resnet101-v1-7.tar.gz (159.8 MB) 1.2.1 7 76.48 93.20
ResNet152 resnet152-v1-7.onnx (230.6 MB) resnet152-v1-7.tar.gz (217.2 MB) 1.2.1 7 77.11 93.61
ResNet50-fp32 resnet50-v1-12.onnx (97.8 MB) resnet50-v1-12.tar.gz (92.0 MB) 1.7.0 12 74.97 92.33
ResNet50-int8 resnet50-v1-12-int8.onnx (24.6 MB) resnet50-v1-12-int8.tar.gz (22.3 MB) 1.7.0 12 74.77 92.32
ResNet50-qdq resnet50-v1-12-qdq.onnx (24.6 MB) resnet50-v1-12-qdq.tar.gz (16.8 MB) 1.10.0 12 74.43 —

INT8 精度与性能说明(源自 README 记录):与 fp32 ResNet50 相比,int8 ResNet50 的 Top-1 精度下降比率为 0.27%,Top-5 精度下降比率为 0.01%,性能提升为 1.82×。

注意:性能数据依赖测试硬件。上述数据采集于 Intel® Xeon® Platinum 8280 Processor,每实例 1s 4c,CentOS Linux 8.3,batch size 为 1。

3.2 Caffe2 移植的 ResNet50(多 Opset 版本)

模型 onnx 文件 含测试数据包 ONNX 版本 Opset
ResNet50-caffe2 resnet50-caffe2-v1-3.onnx (32 MB) resnet50-caffe2-v1-3.tar.gz (95 MB) 1.1 3
ResNet50-caffe2 resnet50-caffe2-v1-6.onnx (32 MB) resnet50-caffe2-v1-6.tar.gz (96 MB) 1.1.2 6
ResNet50-caffe2 resnet50-caffe2-v1-7.onnx (32 MB) resnet50-caffe2-v1-7.tar.gz (100 MB) 1.2 7
ResNet50-caffe2 resnet50-caffe2-v1-8.onnx (32 MB) resnet50-caffe2-v1-8.tar.gz (100 MB) 1.3 8
ResNet50-caffe2 resnet50-caffe2-v1-9.onnx (32 MB) resnet50-caffe2-v1-9.tar.gz (100 MB) 1.4 9

这一组模型覆盖了 Opset 3/6/7/8/9 多个算子集版本,方便在只支持低版本 Opset 的旧运行时上部署。

3.3 ResNet V2 系列(Opset 7,ONNX 1.2.1)

模型 onnx 文件 含测试数据包 ONNX 版本 Opset Top-1 (%) Top-5 (%)
ResNet18-v2 resnet18-v2-7.onnx (44.6 MB) resnet18-v2-7.tar.gz (42.9 MB) 1.2.1 7 69.70 89.49
ResNet34-v2 resnet34-v2-7.onnx (83.2 MB) resnet34-v2-7.tar.gz (78.6 MB) 1.2.1 7 73.36 91.43
ResNet50-v2 resnet50-v2-7.onnx (97.7 MB) resnet50-v2-7.tar.gz (92.0 MB) 1.2.1 7 75.81 92.82
ResNet101-v2 resnet101-v2-7.onnx (170.4 MB) resnet101-v2-7.tar.gz (159.4 MB) 1.2.1 7 77.42 93.61
ResNet152-v2 resnet152-v2-7.onnx (230.3 MB) resnet152-v2-7.tar.gz (216.0 MB) 1.2.1 7 78.20 94.21

从表中可以观察到:在相同深度下,ResNet v2 的 Top-1/Top-5 精度整体略高于 v1,这与论文中"预激活更利于深层网络训练"的结论一致。

验证方式说明:READM 中明确说明,上表精度采用**中心裁剪(center cropping)**在验证集上测得,而论文使用的是十裁剪(ten-cropping)。可以预期采用十裁剪时精度会提升 1~2%,从而与论文结果接近。这一点在 Validation accuracy 一节有更详细说明。

四、推理:输入、输出与预处理/后处理全流程

4.1 输入约定

所有预训练模型期望的输入是按同一方式归一化的 3 通道 RGB 图像 mini-batch,形状为 (N x 3 x H x W):

  • N:batch size;
  • H、W:高度与宽度,至少为 224。

推理使用的原始图像为 JPEG 格式(README 中记录的测试方式)。

4.2 预处理步骤(标准 ImageNet 流程)

在将图像送入网络前,需要执行以下预处理(README 原文流程):

  1. 缩放:将图像最短边缩放到 256,另一条边按原始宽高比等比缩放(即最小尺寸为 256×256,保持宽高比);
  2. 中心裁剪:从图像中心裁剪出 224×224 的窗口;
  3. 归一化:使用 mean = 255*[0.485, 0.456, 0.406],std = 255*[0.229, 0.224, 0.225] 进行标准化;
  4. 通道重排:将布局从 HWC 转置为 CHW。

仓库中的 imagenet_preprocess.py 给出了两种参考实现:

  • preprocess(image):纯 NumPy/PIL 实现。先将短边缩放到 256(Image.BILINEAR),再中心裁剪 224×224,然后转置为 CHW、转 float32,并按 mean=[0.485,0.456,0.406]、std=[0.229,0.224,0.225] 做 (x/255 - mean)/std 归一化,最后 reshape 为 (1, 3, 224, 224);
  • preprocess_mxnet(img):使用 MXNet Gluon 的 transforms.Compose,依次执行 Resize(224)、CenterCrop(224)、ToTensor()、Normalize([0.485,0.456,0.406], [0.229,0.224,0.225]),最后 expand_dims(axis=0) 增加 batch 维。

注意两种实现存在细微差异:前者按"短边缩放到 256 再裁剪 224",后者直接 Resize(224);这与 README 描述的标准流程(缩放到 256 后裁剪 224)对应的是前者。实际使用时请以 README 描述为准,或统一采用 preprocess() 的实现。

4.3 用 ONNX 子图表达预处理(可复制代码)

README 给出了一个很有价值的实践:把预处理步骤本身建模成一个 ONNX 模型(Opset 18),从而让预处理与网络前向推理统一到同一张计算图上。核心要点:

  • 主图 resnet_preproc_g 的输入是 seq(uint8[?, ?, 3]) 的图像序列,输出是 float[B, 3, 224, 224];
  • 通过 metadata_props 声明 "preprocessing_fn": "local.preprocess";
  • local domain 中实现 preprocess:对每张图做 Resize(mode="linear"、antialias=1、keep_aspect_ratio_policy="not_smaller" 缩放到 256)、CenterCropPad 到 224×224、按 kMean=[123.675, 116.28, 103.53](即 255*0.485 等)与 kStddev=[58.395, 57.12, 57.375] 归一化,最后 Transpose(perm=[2,0,1]) 得到 CHW 布局;
  • 用 SequenceMap + ConcatFromSequence(axis=0, new_axis=1) 将 batch 内各样本拼接。

该 ONNX 模型已预先导出,见 preproc/resnet-preproc-v1-18.onnx(4.0 KB),含测试数据版本 preproc/resnet-preproc-v1-18.tar.gz(864 KB),ONNX 版本 1.13.1、Opset 18。

使用 onnx.parser 从文本直接构建并校验模型的完整代码(README 原文):

import onnx
from onnx import parser
from onnx import checker

resnet_preproc = parser.parse_model('''
<
  ir_version: 8,
  opset_import: [ "" : 18, "local" : 1 ],
  metadata_props: [ "preprocessing_fn" : "local.preprocess"]
>
resnet_preproc_g (seq(uint8[?, ?, 3]) images) => (float[B, 3, 224, 224] preproc_data)
{
    preproc_data = local.preprocess(images)
}

<
  opset_import: [ "" : 18 ],
  domain: "local",
  doc_string: "Preprocessing function."
>
preprocess (input_batch) => (output_tensor) {
    tmp_seq = SequenceMap <
        body = sample_preprocessing(uint8[?, ?, 3] sample_in) => (float[3, 224, 224] sample_out) {
            target_size = Constant <value = int64[2] {256, 256}> ()
            image_resized = Resize <mode = "linear",
                                    antialias = 1,
                                    axes = [0, 1],
                                    keep_aspect_ratio_policy = "not_smaller"> (sample_in, , , target_size)

            target_crop = Constant <value = int64[2] {224, 224}> ()
            image_sliced = CenterCropPad <axes = [0, 1]> (image_resized, target_crop)

            kMean = Constant <value = float[3] {123.675, 116.28, 103.53}> ()
            kStddev = Constant <value = float[3] {58.395, 57.12, 57.375}> ()
            im_norm_tmp1 = Cast <to = 1> (image_sliced)
            im_norm_tmp2 = Sub (im_norm_tmp1, kMean)
            im_norm = Div (im_norm_tmp2, kStddev)

            sample_out = Transpose <perm = [2, 0, 1]> (im_norm)
        }
    > (input_batch)
    output_tensor = ConcatFromSequence < axis = 0, new_axis = 1 >(tmp_seq)
}

''')
checker.check_model(resnet_preproc)

将预处理子图"拼接"到网络模型前端,则使用 ONNX compose 工具(README 原文)。注意需要先把网络模型转换到 Opset 18 并设置 ir_version = 8:

import onnx
from onnx import version_converter
from onnx import checker

network_model = onnx.version_converter.convert_version(network_model, 18)
network_model.ir_version = 8
checker.check_model(network_model)

model_w_preproc = onnx.compose.merge_models(
    preprocessing_model, network_model,
    io_map=[('preproc_data', 'data')]
)
checker.check_model(model_w_preproc)

io_map 将预处理子图的输出 preproc_data 与网络模型的输入名 data 对接。合并后,输入一张原始 JPEG 图像即可端到端得到分类结果,预处理逻辑完全固化在 ONNX 图中,便于跨框架复现同一套预处理。README 同时指出,imagenet_preprocess.py 中提供了对应的 Python 与 MXNet 参考实现,可用于交叉验证。

4.4 输出与后处理

  • 输出:模型输出图像在 ImageNet 1000 个类别上的得分(类别列表见 synset.txt)。
  • 后处理:对各类别得分计算 softmax 概率,并按概率从高到低排序,得到最可能的类别排名。仓库提供的 imagenet_postprocess.py 中 postprocess(scores) 的实现为:
import mxnet as mx
import numpy as np

def postprocess(scores):
    prob = mx.ndarray.softmax(scores).asnumpy()
    prob = np.squeeze(prob)
    a = np.argsort(prob)[::-1]
    return a

argsort(...)[::-1] 返回按概率降序排列的类别 ID 数组,a[0] 即最可能的预测类别。

4.5 快速推理入口

README 提供了两条快速上手路径:

  1. 浏览器端体验:ResNet50(Caffe2 版本,release 1.2)可通过 ONNX.js 在浏览器中直接运行推理(对应 README 中提到的 demo)。
  2. Notebook 实践:查看 imagenet_inference.ipynb 了解如何使用上述模型完成一次完整推理(MXNet + Gluon API),使用时需要在 Notebook 中指定正确的模型名称。

五、训练、验证与数据集准备

5.1 训练

仓库使用 MXNet + Gluon API 完成 ResNet 各变体的训练。训练超参数、网络结构等细节记录在 train_resnet.ipynb 中,覆盖 v1/v2 的 18/34/50/101/152 各深度变体。

5.2 验证

验证同样基于 MXNet + Gluon,参考 Notebook imagenet_validation.ipynb。使用时需在 Notebook 中指定对应的模型名称,以在验证集上复现精度指标。

5.3 数据集

训练与验证使用 ImageNet(ILSVRC2012) 数据集。数据集准备指南见 imagenet_prep.md,要点如下:

  1. 在 ImageNet 官网注册账号后下载两个文件:
文件名 大小
ILSVRC2012_img_train.tar 138 GB
ILSVRC2012_img_val.tar 6.3 GB
  1. 下载仓库内的辅助脚本 extract_imagenet.py 与验证标签文件 imagenet_val_maps.pklz,放到同一目录;
  2. 执行解压脚本:
python extract_imagenet.py --download-dir *path to download folder* --target-dir *path to extract folder*

注意:ImageNet 数据集按许可要求仅限非商业用途。

此外,Caffe2 版本的 ResNet50 使用的是 2015 年的 ImageNet 数据(ILSVRC2015)。

5.4 验证精度说明

前文表格中的精度在验证集上采用中心裁剪测得,而论文使用的是十裁剪(ten-cropping)。README 说明,若采用十裁剪,预期精度可提升 1~2%,从而接近论文报告的结果。这是复现精度时需要注意的重要差异点。

六、量化:从 ResNet50-fp32 到 INT8 / QDQ

6.1 量化模型来源

ResNet50-int8 与 ResNet50-qdq 均由 ResNet50-fp32 模型(resnet50-v1-12.onnx)量化而来,使用的是 Intel® Neural Compressor 工具链(onnxruntime 后端)。

6.2 环境要求

  • onnx:1.7.0
  • onnxruntime:1.6.0+

6.3 准备模型

wget https://github.com/onnx/models/raw/main/vision/classification/resnet/model/resnet50-v1-12.onnx

(本文仓库中该模型已直接提供,无需单独下载,路径见 resnet50-v1-12.onnx。)

6.4 执行量化

使用 run_tuning.sh 脚本触发基于精度的自动调优量化,务必先在配置文件中指定正确的数据集路径:

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

参数说明:

  • --input_model:待量化的 fp32 模型路径(.onnx 文件);
  • --config:量化调优配置文件(如 resnet50_v1_5.yaml),用于控制量化精度/性能目标、校准数据与调优策略;
  • --output_model:量化后模型的保存路径。

6.5 量化后推理

量化完成后,使用 onnxruntime 对 ResNet50_fp32 与 ResNet50_int8 分别推理并对比结果,参考 Notebook onnxrt_inference.ipynb。该 Notebook 同时说明了量化模型对应的预处理与后处理方式。

6.6 量化收益(来自 README 记录)

对比项 数值
Top-1 精度下降比率 0.27%
Top-5 精度下降比率 0.01%
性能提升 1.82×

模型体积上,int8 版本从 fp32 的 97.8 MB 降至 24.6 MB(约 1/4)。需要再次强调,性能数据依赖具体测试硬件,上述数据为 Intel® Xeon® Platinum 8280、CentOS Linux 8.3、batch size 1 环境下的记录。

七、仓库中的扩展生态:更多 ResNet 变体的 ONNX 导出

除了 validated 下经精度验证的经典 ResNet 之外,仓库的 Computer_Vision 目录还通过 TurnkeyML 工具链导出了一大批来自 timm / torch_hub / torchvision 的 ResNet 系列与变体模型,每个目录内含 .onnx 模型文件与 turnkey_stats.yaml 统计文件,例如:

这些导出模型与 validated/vision/classification/resnet 下的经典模型共同构成了完整的 ResNet 模型矩阵:既有经过精度验证的经典 v1/v2 权重,也有覆盖现代变体与多 Opset 的导出集合。仓库根目录的 ONNX_HUB_MANIFEST.json 记录了各模型的元信息(模型路径、ONNX 版本、Opset、输入输出端口等),可用于批量检索与集成。

八、在仓库中验证 ONNX 模型的通用方法

由于每个 .tar.gz 测试包内含 test_data_set_*(protobuf TensorProto 格式)或 test_data_*.npz(NumPy 归档格式)的输入输出样例,你可以使用任意支持 ONNX 推理的后端验证模型。以 protobuf 测试数据为例(来自仓库 README.md 的通用用法):

import numpy as np
import onnx
import os
import glob
import onnx_backend as backend

from onnx import numpy_helper

model = onnx.load('model.onnx')
test_data_dir = 'test_data_set_0'

# Load inputs
inputs = []
inputs_num = len(glob.glob(os.path.join(test_data_dir, 'input_*.pb')))
for i in range(inputs_num):
    input_file = os.path.join(test_data_dir, 'input_{}.pb'.format(i))
    tensor = onnx.TensorProto()
    with open(input_file, 'rb') as f:
        tensor.ParseFromString(f.read())
    inputs.append(numpy_helper.to_array(tensor))

# Load reference outputs
ref_outputs = []
ref_outputs_num = len(glob.glob(os.path.join(test_data_dir, 'output_*.pb')))
for i in range(ref_outputs_num):
    output_file = os.path.join(test_data_dir, 'output_{}.pb'.format(i))
    tensor = onnx.TensorProto()
    with open(output_file, 'rb') as f:
        tensor.ParseFromString(f.read())
    ref_outputs.append(numpy_helper.to_array(tensor))

# Run the model on the backend
outputs = list(backend.run_model(model, inputs))

# Compare the results with reference outputs.
for ref_o, o in zip(ref_outputs, outputs):
    np.testing.assert_almost_equal(ref_o, o)

np.testing.assert_almost_equal 会校验推理输出与官方参考输出的一致性,是快速确认模型文件完整性的通用手段。模型结构的可视化推荐使用 Netron。

九、参考资料(论文与实现)

  • ResNet v1:《Deep residual learning for image recognition》,He, Kaiming, Xiangyu Zhang, Shaoqing Ren, and Jian Sun. In Proceedings of the IEEE conference on computer vision and pattern recognition, pp. 770-778. 2016.
  • ResNet v2:《Identity mappings in deep residual networks》,He, Kaiming, Xiangyu Zhang, Shaoqing Ren, and Jian Sun. In European Conference on Computer Vision, pp. 630-645. Springer, Cham, 2016.
  • 实现框架:MXNet(Gluon model zoo / GluonCV)
  • 量化工具:Intel® Neural Compressor(onnxruntime 后端)

本模型目录的许可证为 Apache 2.0(见 LICENSE)。

总结

从架构原理到实际部署,ONNX Model Zoo 的 ResNet 分类模型目录 validated/vision/classification/resnet 提供了完整闭环:v1/v2 全深度系列的 ONNX 权重、可直接校验的测试数据、可复制的 ONNX 预处理子图、Python/MXNet 参考实现,以及 INT8/QDQ 量化流程。对于需要在不同框架、运行时与硬件上获得一致且高精度图像分类能力的开发者而言,这套模型及其配套脚本(imagenet_preprocess.py、imagenet_postprocess.py、imagenet_prep.md)提供了开箱即用、可验证、可量化的完整参考。

登录后查看全文
models