ModelConverter
最后更新
对于托管在线转换,请使用 HubAI 转换。本页介绍如何在本地运行 ModelConverter。
概述
modelconverterPython 包提供 CLI、配置处理、输入暂存、缓存、推理、基准测试和分析工具。- 特定于平台的 Docker 镜像包含供应商转换工具链。这使得 OpenVINO、SNPE 和 Hailo 依赖项与主机系统隔离。
安装
Command Line
1pip install modelconvCommand Line
1pip install "modelconv[bench]" # modelconverter benchmark
2pip install "modelconv[analysis]" # RVC4 analysis and visualizationsudo。确保该用户有权访问 Docker 守护程序,以便生成的文件仍归用户所有。验证安装:Command Line
1modelconverter --version
2modelconverter --help支持的输入和平台
s3:// 和 gs://)支持的远程 URL。支持的源模型格式有:- ONNX (
.onnx),所有平台都支持。 - OpenVINO IR (
.xml和.bin),支持 RVC2 和 RVC3。 - TensorFlow Lite (
.tflite)。
<model>.onnx_data。使用 NN Archive 时,请包含这两个文件,并采用相同的命名约定。配置转换
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输入和输出
| 字段 | 描述 |
|---|---|
input_model | 模型路径或远程 URL。每个阶段都需要。 |
input_bin | OpenVINO 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: PADdataset_name:split:loader_plugin 选择自定义 LDF 加载器。目前不支持多输入 LDF 校准数据集。图像根据配置进行大小调整和转换。当预处理存储在 NN Archive 元数据中时,ModelConverter 会在量化之前将其应用于图像和生成的随机样本。用户提供的 .npy 和 .raw 文件必须已经包含后端就绪值,具有正确的数据类型、形状和布局。RVC4 图像张量通常使用 NHWC;Hailo 和 RVC3 期望无批次的通道最后样本(图像为 HWC)。Hailo 还接受 .npy 文件中的前导单例批次轴。当校准需要存储在 NN Archive 元数据中的预处理时,不能使用自定义 RVC4 --input_list 参数。当省略校准数据时,ModelConverter 会生成随机样本。这对于测试模型是否转换很有用,但生产量化应使用真实的代表性数据。优先使用反映部署模型将接收的数据的保留验证子集;当有代表性的保留数据可用时,避免重复使用训练样本。NN Archive 校准
NN Archive 存储模型元数据和预处理,但不包含校准数据集。当使用量化的 RVC4 或 Hailo 流转换存档时,请提供
calibration.path。否则,ModelConverter 会回退到随机校准数据。Command Line
1modelconverter convert rvc4 --path ./model.tar.xz \
2 calibration.path ./calibrationFP16_STANDARD)不需要校准数据集。平台特定设置
| 平台 | 常见设置 |
|---|---|
| RVC2 | number_of_shaves、superblob、compress_to_fp16、n_workers、mo_args 和 compile_tool_args。 |
| RVC3 | pot_target_device、compress_to_fp16、mo_args 和 compile_tool_args。 |
| RVC4 | quantization_mode、htp_socs、optimization_level、encodings、strict_quantization_overrides、normalize_io_encodings 和其他 SNPE 参数。 |
| Hailo | hw_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_FOCUSED | W8A8 具有增强的参数和激活量化器。它可以在保留 8 位权重和激活的同时提高精度。 |
INT8_INT16_MIXED | 8 位权重和 16 位激活。它可以在提高数值稳定性的同时,以吞吐量和模型大小为代价。 |
INT8_INT16_MIXED_ACCURACY_FOCUSED | 混合 W8A16 模式,具有增强的参数和激活量化器。它可以在与混合模式相同的吞吐量和大小权衡下进一步提高精度。 |
INT16_STANDARD | 16 位权重和激活。它提供更高精度的整数路径,但性能和大小成本高于 INT8。 |
FP16_STANDARD | 无校准的浮点转换。它有利于数值稳定性,但通常比 INT8 具有更低的吞吐量和更大的模型。 |
CUSTOM | 将量化行为留给自定义 SNPE 参数和可选编码覆盖。当预定义模式与所需的精度策略不匹配时使用。 |
除了
CUSTOM 之外,每个预定义的 RVC4 量化模式都控制相应的 SNPE 参数,并覆盖通过 snpe_onnx_to_dlc_args、snpe_dlc_quant_args 或 snpe_dlc_graph_prepare_args 提供的冲突值。运行转换
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 50Command 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_0stage_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 镜像和工具版本
| 平台 | 可用的官方工具版本 | 默认 |
|---|---|---|
| RVC2 | OpenVINO 2021.4.0、2022.3.0 | 2022.3.0 |
| RVC3 | OpenVINO 2022.3.0 | 2022.3.0 |
| RVC4 | SNPE 2.32.6、2.41.0 | 2.41.0 |
| Hailo | 从 Hailo AI 软件套件本地构建 | 2025.04 |
--tool-version 选择另一个可用版本:Command Line
1modelconverter convert rvc4 --tool-version 2.41.0 --path ./model.onnxluxonis/modelconverter-<platform>:<tool-version>-latest。当自定义镜像不遵循该约定时,请明确传递它:Command Line
1modelconverter convert rvc4 \
2 --image luxonis/modelconverter-rvc4:custom \
3 --path ./model.onnx2.41.0.251128)允许 CLI 从 Qualcomm 的目录下载该版本(如果可用)。短版本(例如 2.41.0)需要匹配的本地镜像或存档。有关部署兼容性指南,请参阅 转换故障排除。Hailo 镜像必须在本地构建。从 Hailo 获取匹配的 Hailo AI 软件套件镜像,并按照上游构建说明进行操作。GPU 加速的 Hailo 转换还需要 NVIDIA 容器工具包。输入、输出和缓存
${XDG_CACHE_HOME:-~/.cache}/modelconverter 处的自动管理缓存中暂存所需的输入。ModelConverter 仅复制配置引用的文件,按内容去重,并重用未更改的输入。默认缓存预算为 50 GiB;必要时,在转换之前删除最近最少使用的条目。活动转换使用的文件不会被删除。使用以下命令检查或清除缓存:Command Line
1modelconverter cache info
2modelconverter cache clean
3modelconverter cache clean -yMODELCONVERTER_CACHE_MAX_SIZE 以更改预算,或将其设置为 0 以表示无限制:Command Line
1MODELCONVERTER_CACHE_MAX_SIZE=20GiB modelconverter convert rvc4 --path ./model.onnxoutput/ 下: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--main-stage。有关完整的配置,请参阅上游 multistage.yaml 示例。打包 NN Archive
archive 命令打包独立模型和推断的元数据,而无需运行平台转换:Command Line
1modelconverter archive ./model.onnx --save-path ./model.tar.xz--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
Command Line
1modelconverter shell rvc4--command 运行单个命令而不是交互式 shell:Command Line
1modelconverter shell rvc4 --command "snpe-net-run --help"