ONNX Model Zoo 中的 ResNet 图像分类模型:从架构原理到推理、量化与源码实践
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 为骨干的衍生模型,例如:
- fasterrcnn_resnet50_fpn_v2_Opset16_torchvision(检测)
- maskrcnn_resnet50_fpn_v2_Opset16_torchvision(实例分割)
- retinanet_resnet50_fpn_v2_Opset16_torchvision(密集检测)
它们均以 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 原文流程):
- 缩放:将图像最短边缩放到 256,另一条边按原始宽高比等比缩放(即最小尺寸为 256×256,保持宽高比);
- 中心裁剪:从图像中心裁剪出 224×224 的窗口;
- 归一化:使用
mean = 255*[0.485, 0.456, 0.406],std = 255*[0.229, 0.224, 0.225]进行标准化; - 通道重排:将布局从 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"; localdomain 中实现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 提供了两条快速上手路径:
- 浏览器端体验:ResNet50(Caffe2 版本,release 1.2)可通过 ONNX.js 在浏览器中直接运行推理(对应 README 中提到的 demo)。
- 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,要点如下:
- 在 ImageNet 官网注册账号后下载两个文件:
| 文件名 | 大小 |
|---|---|
| ILSVRC2012_img_train.tar | 138 GB |
| ILSVRC2012_img_val.tar | 6.3 GB |
- 下载仓库内的辅助脚本 extract_imagenet.py 与验证标签文件 imagenet_val_maps.pklz,放到同一目录;
- 执行解压脚本:
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 统计文件,例如:
- resnet18_Opset16_timm、resnet34_Opset17_torch_hub、resnet50_Opset18_timm、resnet101_Opset17_timm、resnet152_Opset18_timm
- 结构与训练技巧各异的变体:resnet10t_Opset16_timm、resnet50d_Opset16_timm、resnetrs50_Opset17_timm、resnetv2_50_Opset18_timm、resnetblur50_Opset16_timm 等
- 每个模型覆盖 Opset 16/17/18 等多个算子集版本,便于适配不同 ONNX Runtime 版本
这些导出模型与 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)提供了开箱即用、可验证、可量化的完整参考。