ONNX Model Zoo 全指南:从模型分类、下载验证到量化部署与贡献
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 不会自动下载模型文件。正确流程是:
- 安装 Git LFS:
pip install git-lfs
- 按需下载单个模型:
git lfs pull --include="[path to model].onnx" --exclude=""
- 或一次性下载全部模型:
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 给出了结构化流程:
- 检查现有 Issue/PR:避免重复工作;
- 开启 Issue:新增功能或模型前先与社区讨论,Bug 则说明复现方式;
- Fork 仓库并完成修改,提交信息需清晰描述改动目的;
- 提交 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。