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

本页目录

  • 概述
  • 安装
  • 支持的输入和平台
  • 配置转换
  • 输入和输出
  • 校准数据
  • 平台特定设置
  • 运行转换
  • 转换选项
  • Docker 镜像和工具版本
  • 输入、输出和缓存
  • 多阶段转换
  • 打包 NN Archive
  • 推理
  • 基准测试
  • RVC4 分析
  • 交互式 Shell
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

ModelConverter

最后更新

概述

ModelConverter 是一个开源工具,用于将神经网络模型转换为 Luxonis 设备的部署格式。它支持 RVC2、RVC3、RVC4 和 Hailo 平台。本地转换分为两部分:
  • modelconverter Python 包提供 CLI、配置处理、输入暂存、缓存、推理、基准测试和分析工具。
  • 特定于平台的 Docker 镜像包含供应商转换工具链。这使得 OpenVINO、SNPE 和 Hailo 依赖项与主机系统隔离。

安装

ModelConverter 需要 Python 3.10 或更高版本。从 PyPI 安装 CLI:
Command Line
1pip install modelconv
仅在需要相应工具时安装可选依赖项:
Command Line
1pip install "modelconv[bench]"     # modelconverter benchmark
2pip install "modelconv[analysis]"  # RVC4 analysis and visualization
本地转换和推理需要 Docker。建议在 Windows 和 macOS 上使用 Docker Desktop;建议在原生 Linux 安装上使用 Ubuntu。以普通用户身份运行 CLI,无需 sudo。确保该用户有权访问 Docker 守护程序,以便生成的文件仍归用户所有。验证安装:
Command Line
1modelconverter --version
2modelconverter --help

支持的输入和平台

ModelConverter 接受独立模型、YAML 配置文件或 NN Archive。模型输入可以是本地相对或绝对路径,也可以是配置的文件系统插件(例如 s3:// 和 gs://)支持的远程 URL。支持的源模型格式有:
  • ONNX (.onnx),所有平台都支持。
  • OpenVINO IR (.xml 和 .bin),支持 RVC2 和 RVC3。
  • TensorFlow Lite (.tflite)。
对于大于 2 GB 的 ONNX 模型,请将外部数据文件放在模型旁边,并将其命名为 <model>.onnx_data。使用 NN Archive 时,请包含这两个文件,并采用相同的命名约定。

配置转换

推荐的输入是 NN Archive,因为它将模型及其元数据保存在一起。YAML 配置仍然可用于独立和高级工作流。完整的模式和示例保存在 defaults.yaml 和上游 configs 目录中。紧凑的单阶段配置可能如下所示:
Yaml
1name: resnet18
2input_model: ./models/resnet18.onnx
3
4shape: [1, 3, 224, 224]
5layout: NCHW
6data_type: float32
7
8encoding:
9  from: RGB
10  to: BGR
11
12mean_values: imagenet
13scale_values: imagenet
14
15calibration:
16  path: ./calibration
17  max_images: 100
18  resize_method: RESIZE
YAML 文件中的路径是相对于该文件解析的,而不是 ModelConverter 调用的目录。因此,您可以将配置与其模型和校准数据放在一起,并从任何地方运行它。

输入和输出

常见的输入和输出字段是:
字段描述
input_model模型路径或远程 URL。每个阶段都需要。
input_binOpenVINO IR 权重文件。通常从匹配的 .xml 文件推断。
inputs每个输入的名称、形状、布局、数据类型、编码、归一化和可选的冻结值。
outputs输出张量名称。当源格式提供它们时,它们会被推断出来。
shape / layout / data_type当它们未针对特定输入覆盖时使用的全局输入设置。
encoding.from源模型期望的颜色顺序。
encoding.to运行时期望的颜色顺序。
mean_values / scale_values标量或每通道归一化值,或 imagenet 预设。
keep_intermediate_outputs保留转换中间件。默认为 true。
onnx_simplification使用 onnxsim、实验性 onnxslim 或 false。默认为 onnxsim。
onnx_optimizations启用、禁用或配置 ModelConverter 的 ONNX 图优化。
全局输入字段适用于每个输入。单个 inputs 条目下的值优先于该输入。当省略编码时,已知的 NCHW 或 NHWC 图像输入默认为三通道的 RGB → BGR 或单通道的 GRAY。已知的非图像输入和无批次的 CHW/HWC 输入默认为 NONE;缺少形状或布局元数据默认为 RGB → BGR。对于无批次图像,请明确设置编码,对于非图像张量,请使用 encoding: NONE。当 encoding 是单个值时,ModelConverter 将其用于 encoding.from 和 encoding.to。将均值和比例值保留在训练期间使用的原始通道顺序中;ModelConverter 处理任何所需的通道置换。标量或单元素归一化列表广播到所有通道;否则,为每个通道提供一个值。比例值必须非零。ONNX 预处理嵌入支持 NCHW 和 NHWC 输入。

校准数据

校准数据可以是包含图像(.jpg、.jpeg 或 .png)、NumPy 数组(.npy)、原始缓冲区(.raw)的目录,或 LDF 数据集标识符:
Yaml
1calibration:
2  path: dataset_name:split
3  max_images: 100
4  resize_method: PAD
使用 dataset_name:split:loader_plugin 选择自定义 LDF 加载器。目前不支持多输入 LDF 校准数据集。图像根据配置进行大小调整和转换。当预处理存储在 NN Archive 元数据中时,ModelConverter 会在量化之前将其应用于图像和生成的随机样本。用户提供的 .npy 和 .raw 文件必须已经包含后端就绪值,具有正确的数据类型、形状和布局。RVC4 图像张量通常使用 NHWC;Hailo 和 RVC3 期望无批次的通道最后样本(图像为 HWC)。Hailo 还接受 .npy 文件中的前导单例批次轴。当校准需要存储在 NN Archive 元数据中的预处理时,不能使用自定义 RVC4 --input_list 参数。当省略校准数据时,ModelConverter 会生成随机样本。这对于测试模型是否转换很有用,但生产量化应使用真实的代表性数据。优先使用反映部署模型将接收的数据的保留验证子集;当有代表性的保留数据可用时,避免重复使用训练样本。校准由默认的 RVC4 和 Hailo 量化流使用,RVC3 可选,RVC2 忽略。禁用校准的模式(例如 RVC4 FP16_STANDARD)不需要校准数据集。

平台特定设置

平台常见设置
RVC2number_of_shaves、superblob、compress_to_fp16、n_workers、mo_args 和 compile_tool_args。
RVC3pot_target_device、compress_to_fp16、mo_args 和 compile_tool_args。
RVC4quantization_mode、htp_socs、optimization_level、encodings、strict_quantization_overrides、normalize_io_encodings 和其他 SNPE 参数。
Hailohw_arch、optimization_level、compression_level、batch_size、alls 和校准控制。
rvc4.encodings 提供原始 SNPE 量化覆盖。rvc4.normalize_io_encodings 默认为 true,将暴露的输入/输出编码标准化为 DepthAI 兼容的默认 INT8 值。将其设置为 false 以保留配置的 I/O 编码。RVC4 提供以下预定义的 quantization_mode 值:
模式精度和权衡
INT8_STANDARD默认 W8A8 量化。它通常提供最佳吞吐量和最小模型大小,并且需要代表性校准数据。
INT8_ACCURACY_FOCUSEDW8A8 具有增强的参数和激活量化器。它可以在保留 8 位权重和激活的同时提高精度。
INT8_INT16_MIXED8 位权重和 16 位激活。它可以在提高数值稳定性的同时,以吞吐量和模型大小为代价。
INT8_INT16_MIXED_ACCURACY_FOCUSED混合 W8A16 模式,具有增强的参数和激活量化器。它可以在与混合模式相同的吞吐量和大小权衡下进一步提高精度。
INT16_STANDARD16 位权重和激活。它提供更高精度的整数路径,但性能和大小成本高于 INT8。
FP16_STANDARD无校准的浮点转换。它有利于数值稳定性,但通常比 INT8 具有更低的吞吐量和更大的模型。
CUSTOM将量化行为留给自定义 SNPE 参数和可选编码覆盖。当预定义模式与所需的精度策略不匹配时使用。

运行转换

从配置文件、NN Archive 或独立模型运行转换:
Command Line
1modelconverter convert <platform> --path <config_archive_or_model> [configuration overrides]
例如:
Command Line
1modelconverter convert rvc4 \
2  --path ./resnet18.yaml \
3  --output-dir resnet18-rvc4 \
4  calibration.max_images 50
配置覆盖是 CLI 选项之后的键值对。对于列表条目,按索引寻址项目:
Command Line
1modelconverter convert rvc4 \
2  --path ./resnet18.yaml \
3  inputs.0.name input_1 \
4  inputs.0.shape "[1,3,256,256]" \
5  outputs.0.name output_0
如果重命名默认的 stage_name,请使用新的阶段路径作为前缀覆盖,例如 stages.encoder.inputs.0.shape。

转换选项

选项描述
--path配置文件、NN Archive、独立模型或远程 URL。
--output-dir在 output/ 下创建的目录名称。
--to输出打包:nn_archive(默认)或 native。
--main-stage将多阶段转换打包为 NN Archive 时使用的主阶段。
--tool-version平台镜像使用的供应商工具链版本。
--image / --docker-image显式 Docker 镜像。完整的镜像标签优先于 --tool-version。
--archive-preprocess将预处理存储在 NN Archive 元数据中,用于单阶段转换。需要 --to nn_archive。
--memory限制容器内存,例如 4GiB 或 512M。
--cpus限制容器 CPU 内核;支持 0.5 等小数。
--gpu / --no-gpu为 Hailo 容器启用或禁用 NVIDIA 运行时。
--dev构建并运行挂载本地源的开发镜像。
运行 modelconverter convert --help 以获取所有选项。默认情况下,ModelConverter 将预处理嵌入到模型中。对于单阶段 NN Archive 输出,无法嵌入的有效预处理将移动到存档元数据,并重试转换并发出警告。原生输出和多阶段转换不支持此回退。

Docker 镜像和工具版本

CLI 在可用时拉取匹配的官方镜像。当前的官方镜像托管在 Luxonis GitHub 容器注册表中:
平台可用的官方工具版本默认
RVC2OpenVINO 2021.4.0、2022.3.02022.3.0
RVC3OpenVINO 2022.3.02022.3.0
RVC4SNPE 2.32.6、2.41.02.41.0
Hailo从 Hailo AI 软件套件本地构建2025.04
使用 --tool-version 选择另一个可用版本:
Command Line
1modelconverter convert rvc4 --tool-version 2.41.0 --path ./model.onnx
当官方镜像不可用时,如果其供应商依赖项可用,CLI 可以从存储库 Dockerfile 构建镜像。本地构建的镜像使用 luxonis/modelconverter-<platform>:<tool-version>-latest。当自定义镜像不遵循该约定时,请明确传递它:
Command Line
1modelconverter convert rvc4 \
2  --image luxonis/modelconverter-rvc4:custom \
3  --path ./model.onnx
对于 RVC4 本地构建,提供完整的 SNPE 构建版本(例如 2.41.0.251128)允许 CLI 从 Qualcomm 的目录下载该版本(如果可用)。短版本(例如 2.41.0)需要匹配的本地镜像或存档。有关部署兼容性指南,请参阅 转换故障排除。Hailo 镜像必须在本地构建。从 Hailo 获取匹配的 Hailo AI 软件套件镜像,并按照上游构建说明进行操作。GPU 加速的 Hailo 转换还需要 NVIDIA 容器工具包。

输入、输出和缓存

CLI 接受普通主机路径,并在 ${XDG_CACHE_HOME:-~/.cache}/modelconverter 处的自动管理缓存中暂存所需的输入。ModelConverter 仅复制配置引用的文件,按内容去重,并重用未更改的输入。默认缓存预算为 50 GiB;必要时,在转换之前删除最近最少使用的条目。活动转换使用的文件不会被删除。使用以下命令检查或清除缓存:
Command Line
1modelconverter cache info
2modelconverter cache clean
3modelconverter cache clean -y
设置 MODELCONVERTER_CACHE_MAX_SIZE 以更改预算,或将其设置为 0 以表示无限制:
Command Line
1MODELCONVERTER_CACHE_MAX_SIZE=20GiB modelconverter convert rvc4 --path ./model.onnx
结果写入当前工作目录中的 output/ 下:
Text
1output/
2└── resnet18-rvc4/
3    ├── resnet18.onnx
4    ├── resnet18.dlc
5    ├── modelconverter.log
6    ├── config.yaml
7    ├── buildinfo.json
8    └── intermediate_outputs/
如果省略 --output-dir,ModelConverter 会根据模型、平台、日期和时间生成一个名称。它仅在目录为空或被标记为早期 ModelConverter 操作的结果时替换现有目录。它拒绝覆盖不相关的内容。

多阶段转换

当一个阶段的输出为另一个阶段提供校准数据时,将多个模型放在 stages 下。链接的校准条目标识了前一个 stage 及其 output 或自定义后处理 script。
Yaml
1stages:
2  detector:
3    input_model: ./detector.onnx
4
5  recognizer:
6    input_model: ./recognizer.onnx
7    calibration:
8      stage: detector
9      output: features
从多阶段配置生成 NN Archive 时,请指定 --main-stage。有关完整的配置,请参阅上游 multistage.yaml 示例。

打包 NN Archive

使用 archive 命令打包独立模型和推断的元数据,而无需运行平台转换:
Command Line
1modelconverter archive ./model.onnx --save-path ./model.tar.xz
目标也可以是 LuxonisML 支持的远程 URL。当目标需要特定的注册上传插件时,请使用 --put-file-plugin。

推理

使用以下命令对转换后的模型运行推理:
Command Line
1modelconverter infer <platform> \
2  --model-path <converted_model> \
3  --input-path <input_directory> \
4  --output-dir <output_name> \
5  --config <config_or_archive>
输入目录必须包含每个模型输入的一个子目录,并以该输入命名。每个目录可以包含图像、.npy 数组或 .raw 缓冲区。图像根据配置进行预处理;数组和原始缓冲区不变地传递。推理结果写入 output/<output_name>/,日志位于 output/<output_name>.log。ModelConverter 标记其推理输出目录,以便重复运行可以安全地替换早期结果,而不会删除不相关的文件。

基准测试

有关安装、支持的平台和工件、设备连接要求和使用示例,请参阅专门的 基准测试指南。

RVC4 分析

analysis 额外功能提供了用于比较 ONNX 和 DLC 层输出、测量 RVC4 设备上每层循环使用情况以及可视化结果 CSV 文件的工具。
Command Line
1modelconverter analyze \
2  --dlc-model-path output/<conversion>/model.dlc \
3  --onnx-model-path output/<conversion>/intermediate_outputs/model-modified.onnx \
4  --image-dirs ./input_images
5
6modelconverter visualize output/analysis/<model_name>
使用 intermediate_outputs 中的修改后的 ONNX 模型作为参考,因为它包含在 DLC 转换之前应用的预处理和图转换。使用最终的顶级 DLC 作为默认比较目标。分析需要可通过 ADB 访问的 RVC4 设备,并提供 snpe-net-run 和 snpe-diagview。

交互式 Shell

在选定的平台镜像中打开 shell:
Command Line
1modelconverter shell rvc4
使用 --command 运行单个命令而不是交互式 shell:
Command Line
1modelconverter shell rvc4 --command "snpe-net-run --help"