神经网络模型存档

概述

神经网络模型存档是我们自己的格式，它将模型可执行文件和配置文件打包成一个.tar.xz档案。配置文件编码了模型所需的架构、预处理和后处理以及其他相关信息，以便在我们的生态系统中无缝实现。例如，当使用ModelConverter工具或通过Hub中的详细转换转换模型时，简化了转换参数的指定，或在DepthAI流水线中部署模型时处理预处理和后处理。

神经网络模型存档始终描述存储在其中的模型可执行文件。

如果存档包含ONNX模型，则config.json中的值应与该ONNX模型匹配。

如果存档包含编译后的RVC模型，则config.json中的值应描述该编译模型。

模型可执行文件

模型可执行文件构成用于推理的实际模型。如果存档用于转换，则文件需采用ModelConverter支持的一种格式：

ONNX (.onnx),
OpenVINO IR (.xml 和 .bin), 或
TensorFlow Lite (.tflite)。

如果存档旨在在我们的设备上进行推理，则文件需要采用与目标运行的RVC平台要求相匹配的RVC编译格式：

二进制大对象 (.blob 或 .superblob) 用于RVC2和RVC3平台，或
深度学习容器 (.dlc) 用于RVC4平台。

配置

config.json文件编码了配置模式版本以及一个表示模型的字典，包含输入、输出、头部和元数据部分。

获取值的途径

当手动构建ONNX神经网络模型存档时，最常见的数据来源包括：

原始训练或推理代码，用于预处理和输出语义，
Netron，用于张量名称、形状和布局，
以及onnxruntime，用于输入输出名称、形状和数据类型。

输入

此部分配置模型的输入流。定义为Input字典列表。每个包含以下字段：

name (str) - 输入层的名称。从存档中的模型复制。
dtype (str) - 输入张量数据类型（例如float32或uint8）。应与模型输入张量期望的数据类型匹配。
input_type (str) - 输入数据类型（'raw'或'image'）。
shape (list of ints) - 输入数据的形状，以整数列表表示（例如[H,W]、[H,W,C]、[N,H,W,C]等）。应与模型输入张量形状完全匹配。
layout (str) - 输入数据维度的字符码解释（例如NCHW）。应与模型张量形状使用的顺序匹配。
preprocessing (dict) - 应用于输入数据的预处理。
- mean (list of floats) - 按通道顺序的均值。顺序取决于模型训练时的通道顺序。
- scale (list of floats) - 按通道顺序的标准化值。顺序取决于模型训练时的通道顺序。
- reverse_channels (bool) - 如果为True，模型输入为RGB；否则为BGR。已弃用，将在未来版本中被dai_type标志取代。
- interleaved_to_planar (bool)：如果为True，模型输入为交错格式(NHWC)；否则为平面格式(NCHW)。已弃用，将在未来版本中被dai_type标志取代。
- dai_type (str)：DepthAI输入类型，由DepthAI读取以自动设置流水线。

mean和scale应描述NN Archive中存储的模型所期望的预处理。如果原始预处理是input = (input / 255.0 - mean) / std，则将255 * mean存储为mean，255 * std存储为scale。在RGB和BGR之间切换时不要交换mean和scale的值；只需重新排列通道以匹配模型期望的编码。

输出

此部分配置模型的输出流。定义为Output字典列表。每个包含以下字段：

name (str) - 输出层的名称。
dtype (str) - 输出数据的数据类型（例如float32）。
shape (list of ints) - 输出张量的形状。
layout (str) - 输出张量维度的字符码解释（例如NC或NCHW）。

头部

此部分配置应用于模型输出的后处理步骤。定义为Head字典列表。每个包含以下字段：

parser (str) - 负责对模型输出进行后处理的depthai-nodes解析器名称。
outputs (list of str) - 应输入到解析器的输出名称列表。如果为None，则输入所有输出。
metadata (dict)：头部特定的元数据。有关更多信息，请参阅此源代码。

Heads 部分是可选的。如果未定义，则默认输出为原始数据（无需后处理）。当模型输出需要语义解释时（例如分类的类别名称，或检测/分割的解析器专用元数据），应使用 heads。

元数据

本部分表示模型的元数据。定义为一个 Metadata 字典，包含以下字段：

name（字符串）- 模型名称。
path（字符串）- 模型可执行文件的路径（例如 'model.onnx'）。该路径相对于存档根目录。如果是 OpenVINO IR 模型，请仅提供 .xml 文件的路径，并确保 .bin 文件位于同一路径下。
precision（字符串）- 模型权重的精度（例如 float32 或 float16）。这是存储的模型文件本身的精度，而非单个输入或输出张量的数据类型。

此外，可在此部分添加任意字段以帮助理解模型。

生成

要生成 NN Archive，请遵循以下步骤：

通过从头训练或从现有来源获取（注意模型格式）来准备模型可执行文件。
准备 config.json。以下是一个简单的单输入/输出 ONNX 模型配置示例，无需任何预处理（mean=0, scale=1, reverse_channels=False）或后处理要求：

JSON

1{
2    "config_version": null,
3    "model": {
4        "metadata": {
5            "name": "ModelName",
6            "path": "model_name.onnx",
7            "precision": "float32"
8        },
9        "inputs": [
10            {
11                "name": "input_layer_name",
12                "dtype": "float32",
13                "input_type": "image",
14                "shape": [
15                    1,
16                    3,
17                    256,
18                    256
19                ],
20                "layout": "NCHW",
21                "preprocessing": {
22                    "mean": [
23                        0.0,
24                        0.0,
25                        0.0
26                    ],
27                    "scale": [
28                        1.0,
29                        1.0,
30                        1.0
31                    ],
32                    "reverse_channels": false,
33                    "interleaved_to_planar": null
34                }
35            }
36        ],
37        "outputs": [
38            {
39                "name": "output",
40                "dtype": "float32",
41                "shape": [
42                    1,
43                    3
44                ],
45                "layout": "NC"
46            }
47        ],
48        "heads": []
49    }
50}

我们可以通过扩展 heads 部分来添加后处理步骤。以下是一个具有三个分类类别的模型头部示例：

JSON

1{
2    ...
3    "model": {
4        ...
5        "heads": [
6            {
7                "parser": "ClassificationParser",
8                "metadata": {
9                    "postprocessor_path": null,
10                    "classes": [
11                        "Class1",
12                        "Class2",
13                        "Class3"
14                    ],
15                    "n_classes": 3,
16                    "is_softmax": true
17                },
18                "outputs": [
19                    "output"
20                ]
21            }
22        ]
23    }
24}

安装 luxonis-ml 并运行 Archive Generator：

Python

1from luxonis_ml.nn_archive.archive_generator import ArchiveGenerator
2from luxonis_ml.nn_archive.config import CONFIG_VERSION
3import json
4
5cfg_path = ... # 配置数据 JSON 的字符串路径。
6with open(cfg_path, "r") as file:
7    cfg_dict = json.load(file)
8cfg_dict["config_version"] = CONFIG_VERSION # 从 luxonis-ml 设置配置版本
9
10generator = ArchiveGenerator(
11    archive_name=..., # 生成的存档的字符串名称。
12    save_path=..., # 要保存存档文件的字符串路径。
13    cfg_dict=cfg_dict,
14    executables_paths=... # 相关模型可执行文件的字符串路径列表。
15    )
16
17generator.make_archive() # 存档文件保存到指定的 save_path

多阶段模型

模型有时由多个阶段组成。一个常见的例子是两阶段模型，包含主模型（第一阶段）和后处理器（第二阶段），每个都有自己的可执行文件。我们也支持将此类模型打包到 NN Archive 中。首先按照上述步骤定义第一阶段的配置文件。第二阶段模型只需在 Heads.Metadata 部分设置 postprocessor_path 参数即可定义。它应指向第二阶段模型的可执行文件（路径必须相对于存档根目录）。 NN Archive 可以使用 ArchiveGenerator 构建。请确保第一阶段和第二阶段模型的可执行文件路径都提供在 executables_paths 参数中。

请注意，配置文件仅与第一阶段模型相关，无法为第二阶段模型定义任何信息。

如有必要，建议构建两个独立的NN Archive。

本页目录

神经网络模型存档

概述

模型可执行文件

配置

获取值的途径

输入

输出

头部

元数据

生成

多阶段模型