ModelConverter

有关 ModelConverter 工具在线使用指南，请参阅 HubAI 转换。

概述

ModelConverter 是我们用于在本地将神经网络模型转换为 Luxonis 设备部署格式的开源工具。它包含：

ModelConverter Docker 镜像 - 特定目标平台的容器镜像，其中捆绑了所需的转换工具链。
ModelConverter CLI - 用于运行转换、打开交互式 shell 以及访问推理、基准测试和分析实用程序的 modelconverter 命令。

安装

ModelConverter 需要在您的系统上安装 Docker。建议使用 Ubuntu OS 以获得最佳兼容性。在 Windows 或 macOS 上，建议使用 Docker Desktop 进行安装。否则，请按照官方网站上的说明为您的操作系统进行安装。ModelConverter CLI 可以通过 Python 包索引 (PyPI) 安装，命令如下：

Command Line

1pip install modelconv

运行 modelconverter --help 以查看可用命令和选项。高级工作流程可用的可选附加组件：

pip install "modelconv[bench]" 用于 modelconverter benchmark
pip install "modelconv[analysis]" 用于 RVC4 DLC 分析和可视化

当本地镜像尚未提供时，CLI 可以在可能的情况下自动构建它们。有关特定目标平台的镜像可用性和先决条件，请参阅仓库构建说明。

准备

模型来源

您感兴趣的模型应为以下格式之一：

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

模型文件可以是独立的，也可以打包为 NN Archive。

校准数据（可选）

如果您不打算在转换过程中量化模型，则可以跳过此步骤。否则，请准备一个包含图像文件（.jpg、.png 或 .jpeg）的目录，用于指导量化。 ModelConverter 将自动将它们处理为适当的格式。请确保用于校准的图像与用于训练模型的图像不同。通常，验证数据集用于此目的。您还可以选择提供 .npy 或 .raw 格式的校准数据。但是请注意，这些文件不会进行自动处理，因此请确保正确准备它们（例如，对于 RVC4 转换，请使用 NHWC 布局）。

共享文件夹

使用 CLI 时，请在当前工作目录中保留一个 shared_with_container 目录。它将在转换容器内挂载为 /app/shared_with_container/。推荐的目录结构如下：

archives 用于存储 NN Archive，
calibration_data 用于存储校准数据，
configs 用于存储配置文件，
models 用于存储模型文件，
outputs 用于存储转换输出。

运行以下命令创建文件夹：

Command Line

1mkdir shared_with_container
2cd shared_with_container
3mkdir archives calibration_data configs models outputs

只要文件在容器内可见，此结构不是强制性的，但它有助于组织本地和下载的资产。ModelConverter 首先按提供的路径精确检查，然后相对于 /app/shared_with_container/ 解析该路径。output_dir 可以使用 --output-dir 设置；否则，它将根据模型名称、目标平台和时间戳自动生成。

转换

转换使用 ModelConverter CLI 进行。该过程通过转换参数进行指导。您可以在配置文件中定义它们，或者将模型来源提供为 NN Archive，ModelConverter 将自动为您填充转换参数。此外，您可以在 CLI 上传递键值覆盖来更改单次运行的转换参数。要运行转换：

为您感兴趣的模型准备一个配置文件或 NN Archive。
如果使用本地文件，请将相关的模型文件、配置文件、NN Archive 文件和校准数据放在 shared_with_container 的相应子目录中。在转换 NN Archive 时，无需提供模型文件。校准数据是可选的，仅在计划在转换过程中量化模型时才应提供。
使用指向挂载文件夹内配置文件或 NN Archive 的 --path 参数运行转换。或者，也可以提供 s3:// 和 gcs:// URL。

Command Line

1modelconverter convert <platform> --path <url_or_path> [ 转换参数覆盖 ]

通用 CLI 选项

选项	描述
`--tool-version`	选择底层转换工具的版本。
`--image`	使用特定的 Docker 镜像，而不是默认的标签查找。
`--output-dir`	设置 `shared_with_container/outputs` 下的输出目录名称。
`--to`	选择输出打包格式，例如 `native` 或 `nn_archive`。
`--archive-preprocess`	将预处理存储在 NN Archive 中，而不是将其烘焙到模型中。

对于本地构建的镜像，CLI 期望的标签格式为 luxonis/modelconverter-rvc4:<tool-version>-latest。如果使用自定义标签，请通过 --image 显式传递。

对于 RVC4，完整的 SNPE 构建版本（例如 2.32.6.250402）允许 CLI 在首次构建时自动下载存档（如果该版本存在于 Qualcomm 的目录中）。简短版本（例如 2.32.6）则假定存档或镜像已在本地可用。

对于大于 2 GB 的 ONNX 模型，外部数据文件必须与模型一起存在，文件名为 <model>.onnx_data。如果从 NN Archive 进行转换，请将 .onnx 文件和匹配的 .onnx_data 文件都包含在存档中。

请注意，NN Archive 不包含有关校准数据的信息，因此您必须通过在覆盖参数中设置 calibration 参数来手动提供。

例如，使用量化将模型转换为 RVC4：

Command Line

1modelconverter convert rvc4 --path archives/<nn_archive>.tar.xz \
2    calibration.path calibration_data/<calibration_data_dir>

请注意，如果您正在使用配置文件进行转换，并且修改了默认阶段名称（stages.stage_name），则必须在覆盖参数中提供每个阶段的完整路径。例如，如果阶段名称更改为 stage1，则应使用 stages.stage1.calibration.path 而不是仅使用 calibration.path。

Command Line

1modelconverter convert rvc4 --path configs/<config_file>.yaml \
2    stages.stage1.calibration.path calibration_data/<calibration_data_dir>

或者，您也可以通过使用 docker run 命令在没有 ModelConverter CLI 的情况下运行转换：

Command Line

1docker run --rm -it \
2    -v $(pwd)/shared_with_container:/app/shared_with_container/ \
3    luxonis/modelconverter-<platform>:<tool-version>-latest \
4    convert <platform> \
5    --path <s3_url_or_path> [ 转换参数覆盖 ]

多阶段转换

ModelConverter 还支持多阶段转换，其中一个模型的输出成为另一个模型的输入。这通过配置文件中的 stages 部分进行配置。有关当前示例，请参阅 defaults.yaml 和示例配置文件目录。

交互式 Shell

如果您需要检查工具链或在容器内手动运行供应商工具，请打开一个交互式 Shell：

Command Line

1modelconverter shell rvc4

参数

以下各节总结了最常用的转换参数及其默认值。有关完整的当前选项集，请参阅 defaults.yaml 和当前示例配置文件。

顶层

参数	描述	默认值
`input_model`	模型源文件的路径。可以是本地路径或 s3 或 gcs URL。必需。	-
`inputs`	模型的输入列表。	-
`outputs`	模型的输出列表。	-
`disable_onnx_simplification`	禁用 ONNX 简化。	`False`
`disable_onnx_optimization`	禁用 ONNX 优化。	`False`
`keep_intermediate_outputs`	不删除中间文件。	`True`

输入

inputs 是模型每个输入的参数列表。每个输入可以具有以下参数：

参数	描述	默认值	示例
`name`	输入的名称。	-	`"input_0"`
`shape`	输入的形状。	-	`[1, 3, 224, 224]`
`layout`	输入的布局。	-	`"NCHW"`
`data_type`	输入的数据类型。	-	`"float32"`
`encoding`	输入的编码。可以是以下之一：`RGB`、`BGR`、`GRAY` 或 `NONE`	-	`"RGB"`
`encoding.from`	源模型输入期望的编码。	`"RGB"`	`"RGB"`
`encoding.to`	导出的模型应期望的编码。	`"BGR"`	`"BGR"`
`mean_values`	用于归一化输入的均值，遵循原始模型的通道顺序。可以是单个数字、数字列表或用于 ImageNet 归一化的 `"imagenet"` 字符串。	-	`[ 123.675, 116.28, 103.53 ]`
`scale_values`	用于归一化输入的缩放值，遵循原始模型的通道顺序。可以是单个数字、数字列表或用于 ImageNet 归一化的 `"imagenet"` 字符串。	-	`[ 58.395, 57.12, 57.375 ]`
`calibration`	指定如何校准输入。有关详细信息，请参阅校准参数	-	-

inputs 列表的参数也可以在顶层全局配置，省略 name 参数，这样它们将应用于所有模型输入。如果这些参数也在 inputs 列表中定义，它们将覆盖 name 参数标识的特定输入的全局配置。如果根本不指定输入，它们将从模型中推断。

当 encoding 设置为单个值时，该值会自动应用于 encoding.from 和 encoding.to。要使用不同的值，可以单独显式设置 encoding.from 和 encoding.to。

Outputs

Parameter	Description	Default	Example
`name`	输出的名称。	-	`"output_0"`
`shape`	输出的形状。	-	`[1, 1000]`
`layout`	输出的布局。	-	`"NC"`
`data_type`	输出的数据类型。	-	`"float32"`

如果未指定输出，它们将从模型中推断。

Calibration

校准数据可以通过两种方式指定：

Random

如果未提供校准数据，工具将生成随机数据进行校准。不建议使用随机校准数据，因为它可能导致次优的量化结果。此选项提供了一种快速测试转换过程的方法。

Parameter	Description	Default
`max_images`	用于校准的图像数量。	`20`
`min_value`	输入数据的最小值。	`0.0`
`max_value`	输入数据的最大值。	`255.0`
`mean`	输入数据的平均值。	`127.5`
`std`	输入数据的标准差。	`35.0`
`data_type`	输入数据的数据类型。	`"float32"`

Guided

此校准方法使用真实图像来校准模型。

Parameter	Description	Default
`path`	校准数据的路径。可以是本地路径或 s3 或 gcs URL。	-
`max_images`	用于校准的图像数量。默认情况下，将使用整个数据集。	`-1`
`resize_method`	如何调整图像大小以适应模型输入形状。可以是以下之一：“resize”、“pad”或“crop”。	`"resize"`

Platform-Specific

以下参数特定于各个目标平台：

RVC2

Parameter	Description	Default	Example
`superblob`	将模型编译为 superblob 格式。	`True`	-
`compress_to_fp16`	将模型权重压缩为 FP16 精度。	`True`	-
`number_of_shaves`	要使用的 SHAVE 的数量。仅在禁用 superblob 转换时使用。	`8`	-
`number_of_cmx_slices`	要使用的 CMX 切片数量。仅在禁用 superblob 转换时使用。	`8`	-
`mo_args`	Model Optimizer 的其他参数列表。此处提供的参数将始终优先于 ModelConverter 内部逻辑将要指定的参数。	`[]`	`["--use_legacy_frontend"]`
`compile_tool_args`	Compile Tool 的其他参数列表。此处提供的参数将始终优先于 ModelConverter 内部逻辑将要指定的参数。	`[]`	`["-ov_api_1_0"]`

RVC4

Parameter	Description	Default	Example
`snpe_onnx_to_dlc_args`	SNPE ONNX 到 DLC 工具的其他参数列表。	-	`["--batch", "6"]`
`snpe_dlc_quant_args`	SNPE DLC 量化工具的其他参数列表。	-	`["--weights_bitwidth=16"]`
`snpe_dlc_graph_prepare_args`	SNPE DLC 图准备工具的其他参数列表。	-	`["--htp_archs=v73"]`
`keep_raw_images`	在中间数据中保留用于校准的原始图像。	`False`	-
`use_per_channel_quantization`	为卷积、反卷积和全连接运算中的权重和偏置启用每通道量化。	`True`	-
`use_per_row_quantization`	为 Matmul 和全连接运算启用行量化。	`False`	-
`htp_socs`	要定位的 HTP SoC 列表。	`["sm8550"]`	`["sm8550", "sm8650", "qcs6490"]`
`optimization_level`	DLC 图准备的优化级别。可用选项为 `1`、`2` 和 `3`。	`2`	-
`quantization_mode`	预定义的量化模式。	`INT8_STANDARD`	-

Quantization Modes从 CLI 覆盖时，使用 rvc4.quantization_mode 在 RVC4 转换的各种预定义量化模式之间进行选择。可用模式为：

INT8_STANDARD: 标准 INT8 量化带校准（默认），以获得最佳性能（FPS）和模型大小。
INT8_ACCURACY_FOCUSED: INT8 量化带校准。此模式利用更高级的量化技术，在不降低性能或增加模型大小的情况下可能提高精度，具体取决于模型。
INT8_INT16_MIXED: 混合 INT8 和 INT16 量化带校准。此模式在所有层中使用 8 位权重和 16 位激活，以提高数值稳定性和精度，但会降低性能（FPS）并增加模型大小。
INT8_INT16_MIXED_ACCURACY_FOCUSED: 混合 INT8 和 INT16 量化带校准，使用更高级的量化技术，可能在降低性能（FPS）和增加模型大小的情况下提高精度。
FP16_STANDARD: FP16 量化不带校准，适用于需要更高精度和数值稳定性的模型，但会降低性能（FPS）并增加模型大小。
CUSTOM: 自定义量化模式，用户可以在配置文件或通过命令行参数指定更高级的选项。

当 quantization_mode 设置为 CUSTOM 以外的任何值时，该模式的默认设置将覆盖在配置文件或通过命令行参数（通过 rvc4.snpe_onnx_to_dlc_args、rvc4.snpe_dlc_quant_args 或 rvc4.snpe_dlc_graph_prepare_args 覆盖选项）提供的任何自定义设置。

配置文件

转换参数可以在 .yaml 配置文件中定义。请参阅下图或查阅其他示例以获取更多信息。

Yaml

1# 相对于 `shared_with_container` 目录的本地路径
2input_model: models/model.onnx
3
4mean_values: imagenet
5scale_values: imagenet
6data_type: float32
7shape: [ 1, 3, 256, 256 ]
8
9# ONNX 模型期望 RGB 输入，
10# 导出的模型将期望 BGR 输入
11encoding:
12  from: RGB
13  to: BGR
14
15calibration:
16  # 校准路径可以是 s3 url
17  path: s3://url/to/calibration_data.zip
18  max_images: 20

本页目录

ModelConverterView as Markdown

概述

安装

准备

模型来源

校准数据（可选）

共享文件夹

转换

通用 CLI 选项

多阶段转换

交互式 Shell

参数

顶层

输入

Outputs

Calibration

Random

Guided

Platform-Specific

RVC2

RVC4

配置文件

ModelConverter