此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 概述
  • 模型可执行文件
  • 配置
  • 从何处获取值
  • 输入
  • 输出
  • 头
  • 元数据
  • 生成
  • 多阶段模型
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新

概述

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

模型可执行文件

模型可执行文件构成了用于推理的实际模型。 如果归档文件用于转换,则文件需要采用 ModelConverter 支持的格式之一:
  • ONNX (.onnx),
  • OpenVINO IR (.xml 和 .bin),或
  • TensorFlow Lite (.tflite)。
如果归档文件用于在我们的设备上进行推理,则文件需要采用与它所运行的 RVC 平台要求匹配的 RVC 编译格式:
  • 二进制大对象 (.blob 或 .superblob) 用于 RVC2 和 RVC3 平台,或
  • 深度学习容器 (.dlc) 用于 RVC4 平台。

配置

config.json 文件编码了配置方案版本以及一个表示模型的字典,其中包含 inputs、outputs、heads 和 metadata 部分。

从何处获取值

手动构建 ONNX NN Archive 时,最常见的真实来源是:
  • 原始训练或推理代码,用于预处理和输出语义,
  • 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 读取该类型以自动设置管道。
    • resize_mode (str, optional) - 图像如何调整大小以适应模型的输入维度:CROP 中心裁剪,STRETCH 改变宽高比以适应,LETTERBOX 通过填充保留宽高比。

输出

此部分配置模型的输出流。 它被定义为 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 (str) - 模型的名称。
  • path (str) - 模型可执行文件的路径(例如 'model.onnx')。 该路径是相对于归档根目录的。 如果是 OpenVINO IR 模型,请在此处仅提供 .xml 文件的路径,并确保 .bin 文件位于同一路径中。
  • precision (str) - 模型权重的精度(例如 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 中。 首先,按照上述步骤定义第一阶段模型的配置文件。 第二阶段模型通过设置 postprocessor_path 参数在 Heads.Metadata 部分中定义。 它应该指向第二阶段模型的可执行文件(路径必须是相对于归档根目录的)。 NN Archive 可以使用 ArchiveGenerator 构建。确保在 executables_paths 参数中提供了第一阶段和第二阶段模型可执行文件的路径。