NN Archive

概述

NN Archive 是我们自己的格式，它将模型可执行文件和配置文件打包到一个 .tar.xz 存档中。配置文件编码了模型的架构、预处理和后处理以及其他相关信息，这些信息对于在我们生态系统中无缝实现模型至关重要。例如，这简化了使用 Modelconverter 工具转换模型时的转换参数的指定，或者在 DepthAI 管道中部署模型时处理预处理和后处理。

模型可执行文件

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

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

如果存档旨在我们的设备上进行推理，则文件需要是 RVC 编译格式，并且与要运行它的RVC Platform 的要求相匹配：

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

配置

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

输入

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

name (str) - 输入层的名称。
dtype (str) - 输入数据类型（例如，'float32'）。
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 读取此类型以自动设置管道。

输出

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

name (str) - 输出层的名称。
dtype (str) - 输出数据的类型（例如，'float32'）。

头部

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

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

Heads 部分是可选的。如果未定义，我们假定为原始输出（无需后处理）。

元数据

此部分表示模型的元数据。它定义为 Metadata 字典。它包含以下字段：

name (str) - 模型的名称。
path (str) - 模型可执行文件的路径（例如，'model.onnx'）。路径相对于存档根目录。对于 OpenVINO IR 模型，此处仅提供 .xml 文件的路径，并确保 .bin 文件位于同一路径下。
precision (str) - 模型权重的精度（例如，'float32'）。

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

生成

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

通过从头开始训练模型或从现有来源获取模型来准备模型可执行文件（注意模型格式）。
准备一个 config.json。一个简单的单输入/输出模型示例配置，没有任何预处理（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_layer_name",
40                "dtype": "float32"
41            }
42        ],
43        "heads": []
44    }
45}

我们可以通过扩展 heads 部分来添加后处理步骤。一个包含三个分类类别的模型的示例 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 参数来简单定义。它应该指向第二阶段模型的可执行文件（路径必须相对于存档根目录）。可以使用 ArchiveGenerator 构建 NN Archive。确保在 executables_paths 参数中提供了第一阶段和第二阶段模型可执行文件的路径。

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

如果需要，我们建议构建两个单独的 NN Archive。

本页目录

NN ArchiveView as Markdown

概述

模型可执行文件

配置

输入

输出

头部

元数据

生成

多阶段模型

NN Archive