ONNX 模型中心¶

ONNX 模型中心是一个简单快捷的方式，可以从ONNX 模型库获取最先进的预训练 ONNX 模型。此外，这为研究人员和模型开发者提供了与更广泛社区分享其预训练模型的机会。

安装¶

ONNX 模型中心在 ONNX 1.11.0 之后可用。

基本用法¶

ONNX 模型中心能够从任何 git 仓库下载、列出和查询训练好的模型，并默认使用官方的 ONNX 模型库。在本节中，我们将展示一些基本功能。

首先请使用以下方式导入hub：

from onnx import hub

按名称下载模型：¶

load 函数将默认搜索模型库以查找具有匹配名称的最新模型，将此模型下载到本地缓存中，并将模型加载到 ModelProto 对象中以供 ONNX 运行时使用。

model = hub.load("resnet50")

从自定义仓库下载：¶

任何具有适当结构的存储库都可以成为ONNX模型中心。要从其他中心下载，或在主模型中心指定特定分支或提交，可以提供repo参数：

model = hub.load("resnet50", repo="onnx/models:771185265efbdc049fb223bd68ab1aeb1aecde76")

列出和检查模型：¶

模型中心提供了用于查询模型库以了解更多可用模型的API。这不会下载模型，而是仅返回与给定参数匹配的模型信息。

# List all models in the onnx/models:main repo
all_models = hub.list_models()

# List all versions/opsets of a specific model
mnist_models = hub.list_models(model="mnist")

# List all models matching a given "tag"
vision_models = hub.list_models(tags=["vision"])

在下载之前，还可以使用get_model_info函数检查模型的元数据：

print(hub.get_model_info(model="mnist", opset=8))

这将打印类似的内容：

ModelInfo(
    model=MNIST,
    opset=8,
    path=vision/classification/mnist/model/mnist-8.onnx,
    metadata={
     'model_sha': '2f06e72de813a8635c9bc0397ac447a601bdbfa7df4bebc278723b958831c9bf',
     'model_bytes': 26454,
     'tags': ['vision', 'classification', 'mnist'],
     'io_ports': {
        'inputs': [{'name': 'Input3', 'shape': [1, 1, 28, 28], 'type': 'tensor(float)'}],
        'outputs': [{'name': 'Plus214_Output_0', 'shape': [1, 10], 'type': 'tensor(float)'}]},
     'model_with_data_path': 'vision/classification/mnist/model/mnist-8.tar.gz',
     'model_with_data_sha': '1dd098b0fe8bc750585eefc02013c37be1a1cae2bdba0191ccdb8e8518b3a882',
     'model_with_data_bytes': 25962}
)

本地缓存¶

ONNX 模型中心在可配置的位置本地缓存下载的模型，以便后续调用 hub.load 时不需要网络连接。

默认缓存位置¶

中心客户端按以下顺序查找默认缓存位置：

$ONNX_HOME/hub 如果定义了 ONNX_HOME 环境变量
$XDG_CACHE_HOME/hub 如果定义了 XDG_CACHE_HOME 环境变量
~/.cache/onnx/hub 其中 ~ 是用户主目录

设置缓存位置¶

要手动设置缓存位置，请使用：

hub.set_dir("my/cache/directory")

此外，可以检查缓存位置：

print(hub.get_dir())

额外的缓存详情¶

要清除模型缓存，可以简单地使用像shutil或os这样的Python工具删除缓存目录。此外，可以选择使用force_reload选项覆盖缓存的模型：

model = hub.load("resnet50", force_reload=True)

我们包含这个标志是为了完整性，但请注意，缓存中的模型是通过sha256哈希来消除歧义的，因此force_reload标志在正常使用中不是必需的。最后我们注意到，模型缓存目录结构将反映清单中model_path字段指定的目录结构，但文件名通过模型SHA256哈希来消除歧义。

这样，模型缓存是人类可读的，可以在多个版本的模型之间消除歧义，并且如果它们具有相同的名称和哈希值，可以在不同的中心之间重复使用缓存的模型。

架构¶

ONNX Hub 架构

ONNX Hub 由两个主要组件组成，客户端和服务器。客户端代码目前包含在 onnx 包中，可以指向一个服务器，该服务器以托管在 GitHub 仓库中的 ONNX_HUB_MANIFEST.json 文件形式存在，例如 ONNX 模型库中的这个文件。这个清单文件是一个 JSON 文档，列出了所有模型及其元数据，并且设计为与编程语言无关。一个格式良好的模型清单条目示例如下：

{
 "model": "BERT-Squad",
 "model_path": "text/machine_comprehension/bert-squad/model/bertsquad-8.onnx",
 "onnx_version": "1.3",
 "opset_version": 8,
 "metadata": {
     "model_sha": "cad65b9807a5e0393e4f84331f9a0c5c844d9cc736e39781a80f9c48ca39447c",
     "model_bytes": 435882893,
     "tags": ["text", "machine comprehension", "bert-squad"],
     "io_ports": {
         "inputs": [
             {
                 "name": "unique_ids_raw_output___9:0",
                 "shape": ["unk__475"],
                 "type": "tensor(int64)"
             },
             {
                 "name": "segment_ids:0",
                 "shape": ["unk__476", 256],
                 "type": "tensor(int64)"
             },
             {
                 "name": "input_mask:0",
                 "shape": ["unk__477", 256],
                 "type": "tensor(int64)"
             },
             {
                 "name": "input_ids:0",
                 "shape": ["unk__478", 256],
                 "type": "tensor(int64)"
             }
         ],
         "outputs": [
             {
                 "name": "unstack:1",
                 "shape": ["unk__479", 256],
                 "type": "tensor(float)"
             },
             {
                 "name": "unstack:0",
                 "shape": ["unk__480", 256],
                 "type": "tensor(float)"
             },
             {
                 "name": "unique_ids:0",
                 "shape": ["unk__481"],
                 "type": "tensor(int64)"
             }
         ]
     },
     "model_with_data_path": "text/machine_comprehension/bert-squad/model/bertsquad-8.tar.gz",
     "model_with_data_sha": "c8c6c7e0ab9e1333b86e8415a9d990b2570f9374f80be1c1cb72f182d266f666",
     "model_with_data_bytes": 403400046
 }
}

这些重要的字段是：

model: 用于查询的模型名称
model_path: 存储在 Git LFS 中的模型的相对路径。
onnx_version: 模型的ONNX版本
opset_version: 操作集的版本。如果未指定，客户端将下载最新的操作集。
metadata/model_sha: 可选的模型sha规范，用于增强下载安全性
metadata/tags: 可选的顶级标签，帮助用户通过给定类型找到模型

在metadata字段中的所有其他字段对客户端是可选的，但为用户提供了重要的详细信息。

添加到ONNX模型中心¶

贡献一个官方模型¶

将模型添加到官方onnx/models版本模型中心的最简单方法是遵循这些指南来贡献您的模型。一旦贡献，确保您的模型在其README.md中有一个Markdown表格 (示例)。模型中心清单生成器将从这些Markdown表格中提取信息。要运行生成器：

git clone https://github.com/onnx/models.git
git lfs pull --include="*" --exclude=""
cd models/workflow_scripts
python generate_onnx_hub_manifest.py

一旦生成了新的清单，请将其添加到拉取请求中并提交到onnx/models

托管您自己的ONNX模型中心¶

要托管您自己的模型中心，请在您的 GitHub 仓库的顶层添加一个 ONNX_HUB_MANIFEST.json 文件 (示例)。至少您的清单条目应包括本文档架构部分中提到的字段。提交后，请检查您是否可以使用本文档的“从自定义仓库下载”部分下载模型。

如果有任何问题请提出¶

对于ONNX模型问题或SHA不匹配问题，请在[Model Zoo]/(https://github.com/onnx/models/issues)中提出问题。
关于ONNX模型中心使用的其他问题/问题，请在此仓库中提出问题。