ONNX Model Zoo 全指南:从模型分类、下载验证到量化部署与贡献

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

ONNX Model Zoo 全指南:从模型分类、下载验证到量化部署与贡献

ONNX(Open Neural Network Exchange)是业界开放的标准模型交换格式,而本仓库 ONNX Model Zoo 正是围绕该格式精心整理的预训练模型集合:模型覆盖计算机视觉、自然语言处理、生成式 AI 与图机器学习四大领域,每个模型均以 .onnx 文件提供并附带构建元数据。读完本文,你将掌握该仓库的目录组织方式、如何通过 Git LFS 按需下载模型、如何用官方测试数据(TensorProto .pb 或 NumPy .npz)验证任意 ONNX 后端推理的正确性,以及如何基于 Intel® Neural Compressor 对模型做 INT8 量化并理解 turnkey_stats.yaml 背后的构建信息。

仓库定位与背景

根据 README.md 的说明,ONNX 定义了一组通用的算子集与统一的文件格式,使 AI 开发者可以在各种框架、工具、运行时和编译器之间自由使用模型。本仓库是一个精选的、以 ONNX 格式存储的预训练 SOTA 模型集合,模型来源于社区贡献,目标是把机器学习模型传播给更广泛的开发者、研究者和爱好者。

需要特别留意 README 顶部的 Deprecation Notice:随着机器学习生态演进,模型分享已经迁移到 Hugging Face 平台。该仓库仅作为历史存档保留,自 2025 年 7 月 1 日起不再提供 LFS 下载,原仓库中的模型可通过 Hugging Face 的 onnxmodelzoo 组织获取。因此,本文所述内容以当前镜像仓库内实际存在的文件为准,主要用于查阅、研究与验证历史模型资产。

由于 ONNX 模型文件体积较大,仓库使用 Git LFS(Large File Storage) 管理模型文件。

仓库结构全景

从镜像仓库根目录可以看到与 README 四大模型分类一一对应的目录,以及历史验证模型的归档目录:

Computer_Vision/               # 计算机视觉(1464 个模型子目录,如 resnet50_Opset16_timm)
Natural_Language_Processing/   # 自然语言处理(75 个模型子目录,如 bert_Opset17_transformers)
Generative_AI/                 # 生成式 AI(如 gptneox_Opset16_transformers)
Graph_Machine_Learning/        # 图机器学习(如 sageconv_Opset16_graph_convolutions)
validated/                     # 已通过精度验证的历史模型及配套脚本
ONNX_HUB_MANIFEST.json         # 模型清单(含 SHA、字节数、输入输出端口等元数据)
README.md / contribute.md / LICENSE

每个模型子目录的组成高度规整,以 Computer_Vision/resnet50_Opset16_timm 为例,包含两个文件:

  • resnet50_Opset16.onnx:序列化后的 ONNX 模型(protobuf 格式);
  • turnkey_stats.yaml:该模型的构建与统计元数据(详见下文"构建元数据解读")。

目录命名遵循 <模型名>_Opset<编号>_<来源框架> 的规律,其中来源包括 timm(pytorch-image-models)、torchvision、torch_hub(PyTorch Hub)、transformers(Hugging Face transformers)以及 graph_convolutions 等,模型统一由开源工具链 TurnkeyML 导出为 ONNX 格式。例如 Natural_Language_Processing/auto_Opset16_transformers 的元数据中 author: transformers、class: RobertaModel,Generative_AI/gptneox_Opset16_transformers 中 class: GPTNeoXModel,可据此快速判断模型出处与结构。

模型分类与代表模型

README 将仓库模型划分为四大类:Computer Vision、Natural Language Processing (NLP)、Generative AI、Graph Machine Learning。其中经过精度验证的模型(Validated Models)被进一步细分为 Vision、Language、Other 三组。

图像分类(Image Classification)

该集合的模型以图像为输入,把图像中的主要物体分类到 1000 个 ImageNet 类别(如键盘、鼠标、铅笔及各类动物)。以下是 README 记载的经典分类模型:

模型类别 论文参考 特点
MobileNet Sandler et al. 轻量级深度网络,适合移动端与嵌入式视觉应用,论文 Top-5 错误率约 10%
ResNet He et al. 最深 152 层的 CNN,通过捷径连接(shortcut)提升分类精度,论文 Top-5 错误率约 3.6%
SqueezeNet Iandola et al. 轻量 CNN,以约 50 倍更少的参数量达到 AlexNet 级精度,论文 Top-5 错误率约 20%
VGG Simonyan et al. 最深 19 层的 CNN,采用多个更小尺寸卷积核,论文 Top-5 错误率约 8%
AlexNet Krizhevsky et al. 8 层深度 CNN,输入图像输出 1000 维向量,论文 Top-5 错误率约 15%
GoogleNet Szegedy et al. 22 层 CNN,比 VGG 更小更快,论文 Top-5 错误率约 6.7%
CaffeNet Krizhevsky et al. AlexNet 的 Caffe 变体,max pooling 位于 LRN 之前以降低计算与内存开销
DenseNet-121 Huang et al. 每层与其余层相连,梯度流强、特征更多样
Inception_V1 / V2 Szegedy et al. GoogLeNet 及加入 BatchNorm 的改进版
ShuffleNet_V1 / V2 Zhang et al. 面向移动设备的高计算效率 CNN
EfficientNet-Lite4 Tan et al. 计算与参数量少一个数量级,仍保持较高精度
ZFNet-512 Zeiler et al. 8 层 CNN,在更细分辨率上提取图像特征

其中 ResNet、SqueezeNet、VGG、AlexNet、GoogleNet、CaffeNet、DenseNet-121、Inception_V1、ZFNet-512、EfficientNet-Lite4 等均提供了对应的 Hugging Face Spaces 在线演示入口(见 README 表格中的徽章链接)。

领域化图像分类还包括 MNIST 手写数字识别模型,对应 validated/vision/classification/mnist 目录,用于特定数据集上的分类。

目标检测与图像分割(Object Detection & Image Segmentation)

目标检测模型检测图像中的多个物体并分割出物体所在区域;语义分割模型则为每个像素打上预定义类别标签。代表模型包括:

模型类别 论文参考 特点
Tiny YOLOv2 Redmon et al. 实时检测 20 个类别的轻量 YOLOv2
SSD Liu et al. 单阶段检测器,检测 80 个类别
SSD-MobileNetV1 Howard et al. SSD 框架 + MobileNet 主干,检测 80 类、定位最多 10 个物体
Faster-RCNN Ren et al. 以 RPN + CNN 构成统一网络,检测 80 类
Mask-RCNN He et al. 实例分割,每个 ROI 并行预测类别、边界框与掩码
RetinaNet Lin et al. 通过 Focal Loss 解决类别不平衡的密集检测器
YOLO v2-coco / YOLO v3 / Tiny YOLOv3 / YOLOv4 Redmon et al. / Bochkovskiy et al. 实时检测系列
DUC Wang et al. 基于 Cityscapes 的逐像素语义分割,适用于自动驾驶
FCN Long et al. 端到端逐像素分割网络

以上验证模型对应仓库中的 validated/vision/object_detection_segmentation 目录(含 tiny-yolov2、ssd、faster-rcnn、mask-rcnn、retinanet、yolov2-coco、yolov3、yolov4、duc、fcn 等子目录)。而新导出的 torchvision 检测模型则位于 Computer_Vision/fasterrcnn_resnet50_fpn_v2_Opset16_torchvision、maskrcnn、retinanet、fcos 等目录中。

人体、人脸与姿态分析(Body, Face & Gesture Analysis)

  • ArcFace:基于 CNN 的人脸识别,为输入人脸图像生成判别性 embedding;
  • UltraFace:面向边缘计算设备的超轻量人脸检测模型;
  • Emotion FerPlus:基于人脸图像的情绪识别 CNN;
  • Age and Gender:年龄与性别分类模型。

对应目录为 validated/vision/body_analysis。

图像处理(Image Manipulation)

  • CycleGAN(Unpaired Image-to-Image Translation):在无配对样本的情况下完成源域到目标域的图像转换;
  • Super Resolution with sub-pixel CNN:使用亚像素卷积层放大输入图像;
  • Fast Neural Style Transfer:以固定损失网络衡量内容与风格差异,实现快速风格迁移。

对应目录为 validated/vision/super_resolution 与 validated/vision/style_transfer。

自然语言处理(NLP)

  • 机器理解(Machine Comprehension):针对给定上下文段落回答问题,代表模型有 BiDAF(Bidirectional Attention Flow)、BERT-Squad、RoBERTa、GPT-2、T5(见 validated/text/machine_comprehension);
  • 机器翻译(Machine Translation):如基于注意力对齐的 NMT、Google 的 NMT 系统;
  • 语言建模(Language Modelling):从大规模语料学习语言表示。

在镜像仓库中,NLP 模型以 *_Opset16/17/18_transformers 目录组织,覆盖 bert、distilbert、roberta、electra、longformer、mpnet、t5encoder、mt5encoder 等数十个 Hugging Face transformers 模型族(见 Natural_Language_Processing),并以 ONNX_HUB_MANIFEST.json 记录每个模型的 SHA、字节数、输入输出端口等详细元数据。

其他类别

  • Visual Question Answering & Dialog:基于图像回答自然语言问题(VQA 系列、Visual Dialog);
  • 语音与音频处理(Speech & Audio Processing):语音识别 RNN、端到端神经语音合成(Deep Voice)、原始音频波形生成(WaveNet);
  • 其他有趣模型:文本生成图像(GAN)、时间序列预测、推荐系统(DropoutNet)、协同过滤(Neural Collaborative Filtering)、段落自动编码器等。README 鼓励用户与研究者通过 contribute.md 贡献模型。

使用方式一:下载模型

通过 Git LFS 下载(官方不推荐整仓克隆)

由于 ONNX 模型体积较大,直接 git clone 不会自动下载模型文件。正确流程是:

  1. 安装 Git LFS:
pip install git-lfs
  1. 按需下载单个模型:
git lfs pull --include="[path to model].onnx" --exclude=""
  1. 或一次性下载全部模型:
git lfs pull --include="*" --exclude=""

注意:正如前文所述,由于原仓库已进入存档状态(2025 年 7 月 1 日起不再提供 LFS 下载),上述命令仅适用于仍保留 LFS 指针可解析的历史镜像环境,实际部署时应优先从 Hugging Face onnxmodelzoo 获取模型文件。

通过 GitHub UI 下载

也可以直接进入每个模型的页面,点击右上角 "Download" 按钮下载单个模型文件(该方式同样受存档策略影响)。

使用方式二:用测试数据验证模型

README 强调:任何 ONNX 后端都应能开箱即用地运行这些模型。解压每个模型对应的 tarball 后,你会得到:

  • model.onnx:序列化的 ONNX 模型(protobuf 文件);
  • 测试数据:以序列化 protobuf TensorProto 文件或序列化 NumPy 归档两种形式提供。

测试数据可用于验证 Model Zoo 中模型的正确性。官方 starter code 如下(使用时请将 onnx_backend 替换为你所选的支持 ONNX 推理的框架,将 backend.run_model 替换为该框架的模型评估逻辑)。

格式一:序列化 protobuf TensorProto(.pb)

测试数据存放于 test_data_set_* 命名规范的文件夹中:

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)

该脚本的关键点在于:利用 onnx.numpy_helper.to_array 将 TensorProto 反序列化为 NumPy 数组,再通过 np.testing.assert_almost_equal 对后端输出与参考输出做近似比较。

格式二:序列化 NumPy 归档(.npz)

测试数据存放于 test_data_*.npz 命名规范的文件中,每个文件包含一组测试输入与输出:

import numpy as np
import onnx
import onnx_backend as backend

# Load the model and sample inputs and outputs
model = onnx.load(model_pb_path)
sample = np.load(npz_path, encoding='bytes')
inputs = list(sample['inputs'])
outputs = list(sample['outputs'])

# Run the model with an onnx backend and verify the results
np.testing.assert_almost_equal(outputs, backend.run_model(model, inputs))

仓库中 validated 目录还提供了大量可直接对照的实操资源:例如 validated/vision/classification/imagenet_inference.ipynb、validated/vision/classification/onnxrt_inference.ipynb、imagenet_preprocess.py、imagenet_postprocess.py 以及 imagenet_val_maps.pklz、synset.txt 等,完整覆盖了从数据准备、预处理、推理到后处理与精度验证的整条链路。

使用方式三:模型可视化

如需查看模型架构的图形化表示,README 推荐使用 Netron。将 model.onnx 拖入 Netron 即可查看算子级计算图、各节点输入输出张量形状与数据类型,适合在做推理前快速核对模型结构与输入端口(如 resnet50_Opset16.onnx 的输入应为 [1, 3, 224, 224] 的 x 张量)。

模型量化:基于 Intel® Neural Compressor

README 指出,INT8 模型由 Intel® Neural Compressor 生成。这是一个开源 Python 库,支持自动精度驱动(accuracy-driven)的调优策略,帮助用户快速找到最优量化模型;它实现 ONNX 模型的动态与静态量化,并支持算子导向(operator oriented)与张量导向(QDQ)两种量化表示方式,用户既可以使用 Web UI 服务,也可以使用 Python 代码完成量化。

仓库中 validated/vision/classification/resnet 的模型页面给出了可复现的量化实测流程与数据(该页明确记载,注意性能数据与测试硬件相关):

  • 提供 ResNet50-fp32(opset 12)、ResNet50-int8、ResNet50-qdq 三种文件;
  • 与 fp32 相比,int8 版 Top-1 精度下降率 0.27%、Top-5 精度下降率 0.01%,性能提升 1.82 倍(测试环境为 Intel® Xeon® Platinum 8280 处理器,1s 4c 每实例,CentOS Linux 8.3,batch size 1);
  • 量化环境要求 onnx 1.7.0、onnxruntime 1.6.0+。

量化命令示例(需在配置文件中指定数据集路径):

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

量化后的推理同样基于 onnxruntime,可参考 onnxrt_inference.ipynb 了解 fp32 与 int8 模型的预处理、推理与后处理差异。

深入:构建元数据(turnkey_stats.yaml)与模型清单

每个模型目录下的 turnkey_stats.yaml 由 TurnkeyML 工具链生成,记录了模型从 PyTorch 导出到 ONNX 的全过程信息。以 Computer_Vision/resnet50_Opset16_timm/turnkey_stats.yaml 为例,可以解读出:

  • 模型标识:model_name: resnet50、class: ResNet、hash: 25cce11f、author: timm,对应内置脚本 builtin_model_script 指向 TurnkeyML 仓库中的 models/timm/resnet50.py;
  • 导出信息:ir_version: 8、opset: 16,磁盘大小约 99752 KiB,参数量 parameters: 25557032(约 2556 万);
  • 输入维度:onnx_input_dimensions.x: [1, 3, 224, 224],即单张 224×224 的 RGB 图像;
  • 算子统计:onnx_ops_counter 列出 Conv 53、Relu 49、Add 16、Gemm 1、GlobalAveragePool 1、MaxPool 1、Flatten 1——与 ResNet-50 的标准结构吻合;
  • 基准信息:x86_ort 构建在 ONNX Runtime 上成功 benchmark,iterations: 100,导出阶段耗时约 1.8 秒;
  • 系统环境:完整列出 Python 包版本(onnx 1.15.0、onnxruntime 1.15.1、torch 2.1.0、timm 0.9.8、transformers 4.35.0、turnkeyml 0.2.0 等)与硬件信息(Intel Xeon Platinum 8272CL),便于复现构建条件。

类似的元数据同样存在于 NLP 模型,如 Natural_Language_Processing/auto_Opset16_transformers/turnkey_stats.yaml 记录 class: RobertaModel、输入 input_ids: [1, 128]、attention_mask: [1, 128],磁盘大小约 487937 KiB。

根目录的 ONNX_HUB_MANIFEST.json 则是模型的机器可读索引,每条记录包含 model 名称、model_path、onnx_version、opset_version 以及嵌套的 metadata(模型 SHA-256、字节数、tags、输入输出端口 io_ports 的名称/形状/类型、含测试数据的 tar.gz 路径及 SHA)。例如 BERT-Squad 记录中可见 4 个 int64 输入(input_ids、input_mask、segment_ids、unique_ids_raw_output___9:0,序列长度 256)与 3 个输出(两个 float 的 unstack:0/1 与 int64 的 unique_ids:0)。该清单非常适合用脚本批量扫描仓库中全部模型的输入输出契约。

贡献指南

若希望向 Model Zoo 贡献新模型,contribute.md 给出了结构化流程:

  1. 检查现有 Issue/PR:避免重复工作;
  2. 开启 Issue:新增功能或模型前先与社区讨论,Bug 则说明复现方式;
  3. Fork 仓库并完成修改,提交信息需清晰描述改动目的;
  4. 提交 PR 并在描述中引用对应 Issue 编号,随后响应维护者的代码评审。

模型贡献还需要遵循 Model Contribution Guidelines,核心要求包括:

  • 模型唯一性:先搜索 Model Zoo 确认不存在等价模型;
  • 模型源码:提供 .py 源文件(放在 TurnkeyML 的 models 目录),并在文件顶部标注 Author、Task(如 Computer Vision、NLP、Generative AI、Graph Machine Learning)、License(Apache-2.0、BSD-3 或 MIT 之一);
  • 依赖管理:将额外依赖添加到 TurnkeyML 的模型 requirements 文件中;
  • 大文件:权重文件需用 Git LFS 管理;
  • ONNX 生成:使用 TurnkeyML 的 --build-only 选项生成符合 Model Zoo 基础设施标准的 ONNX 模型。

总结

ONNX Model Zoo 为 AI 开发者提供了一套完整、规范的预训练模型资产:既包含经过精度验证的历史模型(validated 目录)与丰富的推理/验证脚本,也包含由 TurnkeyML 统一导出、附有 turnkey_stats.yaml 元数据的新版模型集合(Computer_Vision / Natural_Language_Processing / Generative_AI / Graph_Machine_Learning 四大目录)。配合 ONNX_HUB_MANIFEST.json 的机器可读索引,你可以实现模型的批量检索、按需下载、后端推理验证与 INT8 量化。在使用时请留意仓库的存档状态:模型文件已不再通过 LFS 分发,历史模型可从 Hugging Face onnxmodelzoo 获取。

License

本仓库代码与文档遵循 Apache License v2.0。

登录后查看全文
models