ReCamera AI模型转换与量化全流程指南

ReCamera AI模型转换与量化全流程指南

原文链接
https://wiki.seeedstudio.com/recamera_model_conversion/#jump2
Github源码库
https://github.com/Seeed-Studio/OSHW-reCamera-Series
内含超多reCamera相关资料，欢迎关注和讨论！

一、核心功能概述

reCamera平台支持PyTorch/ONNX/TFLite/Caffe/Paddle等主流框架的AI模型转换，其他框架的模型需要转换为 ONNX 格式。如需了解如何将其他深度学习架构的模型转换为 ONNX，请参阅官方 ONNX 网站：
https://github.com/onnx/tutorials

下面显示了在 reCamera 上部署 AI 模型的流程图。

最终输出适配其边缘计算芯片的cvimodel格式。本文通过YOLO系列模型实例，详解从环境配置到混合精度量化的完整流程。

二、环境配置（两种方案）

方案1：Docker容器（推荐）

# 安装Docker（首次使用）
sudo apt install docker.io
sudo systemctl start docker
sudo systemctl enable docker
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

# 拉取镜像并启动容器
docker pull sophgo/tpuc_dev:v3.1
docker run --privileged --name reCamera_dev -v $PWD:/workspace -it sophgo/tpuc_dev:v3.1

# Replace "MyName" with the desired name for your container


#容器内安装工具包 tpu_mlir
pip install tpu_mlir[all]==1.7

方案2：本地安装

系统环境检查
首先确认当前系统环境满足以下要求：

• Ubuntu 22.04
• Python 3.10

若环境不满足或安装失败，请选择方案2进行工具安装。

# 基础安装
pip install tpu_mlir==1.7

# 按需安装依赖（示例：ONNX+PyTorch支持）
# tpu_mlir 所需的依赖项在处理来自不同框架的模型时会有所不同。对于由 ONNX 或 Torch 生成的模型文件，请使用以下命令安装额外的依赖项：
pip install tpu_mlir[onnx]==1.7 tpu_mlir[torch]==1.7

# 目前，支持五种配置：onnx、torch、tensorflow、caffe 和 paddle。或者你可以使用以下命令来安装所有依赖项：
pip install tpu_mlir[all]==1.7

当 tpu_mlir-{version}.whl 文件已存在于本地时，可使用以下命令进行安装：

pip install path/to/tpu_mlir-{version}.whl[all]

三、将AI模型转换并量化为cvimodel格式

1. 准备ONNX模型

reCamera已针对YOLO系列模型完成本地推理适配。本节将以yolo11n.onnx为例，演示如何将ONNX模型转换为reCamera专用的cvimodel格式。该格式是reCamera本地推理使用的标准AI模型格式。

重要说明：
PyTorch/TFLite/Caffe模型的转换方法与本节流程完全相同。

1.1 下载预训练模型

• 官方下载链接：下载 yolo11n.onnx
  此 ONNX 文件可直接用于以下部分中的示例，而无需修改 IR 版本或 Opset 版本。

• 将模型文件复制到工作目录的Workspace文件夹中

1.2 版本兼容性说明

当前Wiki使用的ONNX标准：

• IR版本：8
• Opset版本：17

若您的模型是通过Ultralytics在2024年12月后转换的，可能出现版本不兼容问题。可通过以下步骤检查和降级：

版本检查工具

使用Netron可视化工具查看模型信息

pip install netron
netron yolo11n.onnx

版本降级方法

当模型版本高于IR v8/Opset v17时：

1. 安装依赖：

pip install onnx

2. 下载降级工具：

git clone https://github.com/jjjadand/ONNX_Downgrade.git
cd ONNX_Downgrade/

3. 执行降级（两种方式）：

方式A：使用默认版本(IR v8/Opset v17)

python downgrade_onnx.py model_v12.onnx model_v8.onnx

方式B：自定义版本参数

python downgrade_onnx.py model_v12.onnx model_v9.onnx \
--target_ir_version 9 \
--target_opset_version 11

参数说明：

• <input_model_path>: 原始模型路径
• <output_model_path>: 降级后模型保存路径
• --target_ir_version: 目标IR版本（默认8）
• --target_opset_version: 目标Opset版本（默认17）

强烈建议：为避免兼容性问题，推荐统一使用IR v8/Opset v17标准。

2. 准备工作目录

在与 相同的级别创建目录。图像文件通常是模型训练数据集的一部分，用于后续量化过程中的校准。 在终端中输入以下命令：

git clone -b v1.7 --depth 1 https://github.com/sophgo/tpu-mlir.git
cd tpu-mlir
source ./envsetup.sh && ./build.sh
mkdir model_yolo11n && cd model_yolo11n
cp -rf ${REGRESSION_PATH}/dataset/COCO2017 .
cp -rf ${REGRESSION_PATH}/image .
mkdir Workspace && cd Workspace

获取可用的ONNX模型文件后，请按照以下目录结构放置文件：

model_yolo11n/          # 模型工作目录（与tpu-mlir同级）
├── COCO2017/           # COCO2017数据集（用于量化校准）
├── image/              # 测试图像目录
└── Workspace/          # 实际工作子目录
    └── yolo11n.onnx    # 待转换的ONNX模型文件

3. ONNX→MLIR转换

转换概述

ONNX 到 MLIR 的转换是模型转换过程中的关键中间步骤。在获得适用于 reCamera 推理的最终模型之前，需要先将 ONNX 模型转换为 MLIR 格式。这个 MLIR 文件作为桥梁，用于生成最终针对 reCamera 推理引擎优化的模型。

输入预处理说明

对于图像输入模型，需要了解模型的预处理流程。如果模型使用预处理过的 npz 文件作为输入，则无需额外考虑预处理。否则，预处理过程遵循以下公式：

$$y=(x-\text{mean})\times \text{scale}$$

其中：

• $x$ 表示原始输入
• $y$ 表示预处理后的输入
• $\text{mean}$ 和 $\text{scale}$ 是模型特定的归一化参数

YOLO11 预处理参数

对于官方 YOLO11 模型：

• 归一化范围：[0, 1]
• 图像格式：RGB
• 具体参数计算：
  • 每个通道值乘以 $\frac{1}{255}$
  • 最终参数：
    • $\text{mean}=[0.0,0.0,0.0]$
    • $\text{scale}=[0.0039216,0.0039216,0.0039216]$

注意：不同模型的 $\text{mean}$ 和 $\text{scale}$ 参数可能不同，需根据具体模型的归一化方法确定。

在 Workspace 目录下执行以下命令：

model_transform \
--model_name yolo11n \
--model_def yolo11n.onnx \
--input_shapes "[[1,3,640,640]]" \
--mean "0.0,0.0,0.0" \
--scale "0.0039216,0.0039216,0.0039216" \
--keep_aspect_ratio \
--pixel_format rgb \
--output_names "/model.23/cv2.0/cv2.0.2/Conv_output_0,/model.23/cv3.0/cv3.0.2/Conv_output_0,/model.23/cv2.1/cv2.1.2/Conv_output_0,/model.23/cv3.1/cv3.1.2/Conv_output_0,/model.23/cv2.2/cv2.2.2/Conv_output_0,/model.23/cv3.2/cv3.2.2/Conv_output_0" \
--test_input ../image/dog.jpg \
--test_result yolo11n_top_outputs.npz \
--mlir yolo11n.mlir

参数说明：

参数	是否必选	说明
--model_name	是	模型名称
--model_def	是	ONNX模型文件路径
--input_shapes	否	输入形状，默认为[[1,3,640,640]]
--mean	否	各通道均值，默认0,0,0
--scale	否	各通道缩放系数，默认1.0,1.0,1.0
--keep_aspect_ratio	否	是否保持宽高比，默认false
--pixel_format	否	图像格式，默认bgr
--output_names	是	输出节点名称
--test_input	否	测试输入文件
--test_result	否	测试结果输出文件
--mlir	是	输出的MLIR文件路径

重要提示：

1. YOLO11模型转换时选择的output_names是模型头部的6个输出节点，而非最终输出output0
2. 可通过Netron工具查看模型结构确定输出节点位置

转换完成后会生成两个关键文件：

1. yolo11n.mlir - 核心MLIR格式模型文件
2. ${model_name}_in_f32.npz - 后续量化校准的输入测试文件

• 未选择最终输出节点output0
• 选择了模型头部前的6个中间输出节点
• 原因：YOLO系列模型的检测头(HEAD)在INT8量化后精度损失严重

解决方案：

1. 使用Netron可视化工具查看模型结构
2. 选择量化友好型中间层作为输出节点
3. 后续章节会演示如何通过混合精度量化解决此问题

Netron可视化操作指南

1. 安装Netron：

pip install netron

2. 启动可视化：

netron yolo11n.onnx

也可以选择在线启动Netron

在界面中定位6个关键输出节点位置

model_transform 参数详解

参数	必选	说明
--model_name	是	模型标识名称
--model_def	是	输入ONNX模型路径
--input_shapes	否	输入张量形状，默认[[1,3,640,640]]
--mean	否	归一化均值，默认0,0,0
--scale	否	归一化缩放系数，默认1.0,1.0,1.0
--output_names	是	关键参数指定输出节点名称
--test_input	否	测试输入文件路径
--test_result	否	验证结果输出路径
--mlir	是	输出MLIR文件路径

4. MLIR→cvimodel量化

如果要从 转换为 F16 精度 ，可以在终端中输入以下 reference 命令：

方案A：FP16精度（平衡模式）

model_deploy \
  --mlir yolo11n.mlir \
  --quant_input \
  --quantize F16 \
  --customization_format RGB_PACKED \
  --processor cv181x \
  --test_input ../image/dog.jpg \
  --test_reference yolo11n_top_outputs.npz \
  --fuse_preprocess \
  --tolerance 0.99,0.9 \
  --model yolo11n_1684x_f16.cvimodel

转换成功后，您将获得一个 FP16 精度的文件，可以直接用于推理。如果您需要 INT8 精度或混合精度文件，请参阅以下文章后面部分的内容。

model_deploy 核心参数详解

参数名称	必填	类型	默认值	说明
--mlir	是	字符串	-	输入的MLIR模型文件路径
--quantize	是	枚举值	-	量化类型： • F32 (全精度) • F16 (半精度) • BF16 (脑浮点) • INT8 (8位整型)
--processor	是	字符串	-	目标处理器型号 reCamera 2024版固定使用cv181x
--calibration_table	否	字符串	-	INT8量化必需的校准表路径
--tolerance	否	浮点数	-	FP32与量化结果的相似度容忍度(0-1)
--test_input	否	字符串	-	验证输入文件(npz/npy/image)
--test_reference	否	字符串	-	参考结果文件(npz格式)
--compare_all	否	布尔	false	是否比较所有张量
--excepts	否	字符串	-	需排除验证的网络层(逗号分隔)
--op_divide	否	布尔	false	启用运算内存优化(特定模型)
--model	是	字符串	-	输出模型路径(含文件名)
--skip_validation	否	布尔	false	跳过正确性验证(提升速度)

方案B：INT8精度（极致性能）

生成校准表
在转换为 INT8 模型之前，您需要运行 calibration 以获得校准表。根据情况，输入数据的数量约为 100 到 1000 个。 然后使用校准表生成对称或不对称 。如果对称模型已经满足要求，一般不建议使用不对称模型，因为不对称模型的性能稍逊于对称模型。这是一个现有的100幅图像进行校准的例子：cvimodel COCO2017

# 生成校准表
run_calibration yolo11n.mlir --dataset ../COCO2017 --input_num 100 -o yolo11n_calib_table

运行上述命令后，将生成一个名为 用作 INT8 模型后续编译的输入文件。yolo11n_calib_table

run_calibration参数说明表

参数名称	必填	类型	默认值	说明
--mlir	是	字符串	-	输入的MLIR模型文件路径
--dataset	否	字符串	-	包含校准图像/npz/npy的输入目录
--data_list	否	字符串	-	样本列表文件路径 注意：需与--dataset二选一
--input_num	否	整数	0	校准样本数量 0表示使用全部样本
--tune_num	否	整数	10	优化样本数量(默认10)
--histogram_bin_num	否	整数	2048	直方图分箱数量(默认2048)
--o	是	字符串	-	输出校准表文件路径

编译INT8模型：
获取文件后，执行以下命令将其转换为 INT8 对称量化模型yolo11n_cali_table

model_deploy \
  --mlir yolo11n.mlir \
  --quantize INT8 \
  --quant_input \
  --processor cv181x \
  --calibration_table yolo11n_calib_table \
  --test_input ../image/dog.jpg \
  --test_reference yolo11n_top_outputs.npz \
  --customization_format RGB_PACKED \
  --fuse_preprocess \
  --aligned_input \
  --model yolo11n_1684x_int8_sym.cvimodel

编译后，会生成一个名为与量化为 F16/BF16 的模型相比，量化为 INT8 的模型更轻量级，推理速度更快。yolo11n_1684x_int8_sym.cvimodel

关键参数说明

• 校准阶段：

  • --input_num 100：从COCO2017中随机选取100张图片进行校准
  • --tune_num 10：使用10张图片进行量化参数微调

• 部署阶段：

  • --quant_input：启用输入量化
  • --customization_format RGB_PACKED：指定RGB打包格式
  • --fuse_preprocess：融合预处理操作
  • --aligned_input：启用对齐输入

输出文件说明

文件	描述
yolo11n_calib_table	校准表文件(二进制格式)
yolo11n_1684x_int8_sym.cvimodel	INT8对称量化模型

快速验证方法

1. 将生成的cvimodel文件复制到reCamera的模型目录
2. 使用Node-RED进行可视化测试：
   • 添加"Model"节点并上传模型文件
   • 连接"Image"输入节点和"Preview"输出节点
   • 部署后输入测试图片dog.jpg

注意：INT8量化模型在边缘设备上可实现3-4倍加速，适合实时推理场景。

5. 模型验证与部署

Node-RED快速测试

1. 导入模型节点
2. 上传yolo11n_1684x_int8_sym.cvimodel
3. 部署后通过预览节点查看实时推理结果

示例视频如下：

测试验证视频

您需要在节点中选择 以进行快速验证。双击 model 节点，单击 导入量化模型，然后单击 ，最后单击 yolo11n_1684x_int8_sym.cvimodelmodel

我们可以在节点中查看 INT8 量化模型的推理结果。通过正确的转换和量化方法得到的仍然是可靠的：previewcvimodel

目前，reCamera 的 Node-RED 仅支持对有限数量的模型进行预览测试。将来，我们将适配更多型号。如果您将自定义模型导入 Node-RED 或未设置指定的输出张量（如我们的示例所示），则 Node-RED 的后端不支持预览测试，即使您的后端是正确的。

我们将发布有关各种模型的预处理和后处理的教程，以便您可以编写自己的代码来推断您的自定义。

以下是转换后的Markdown文档，包含清晰的格式和结构：

混合精度量化实战指南 (YOLOv5s示例)

1. 准备工作

当模型中某些层的精度容易受到量化的影响，但我们仍然需要更快的推理速度时，单一精度的量化可能不再适用。在这种情况下，混合精度量化可以更好地解决这种情况。对于对量化更敏感的层，我们可以选择 F16/BF16 量化，而对于精度损失最小的层，我们可以使用 INT8。

接下来，我们将以 为例，演示如何快速将模型转换和量化为 mixed-precision 模型。在阅读本节之前，请确保您已经阅读了本文的前几节，因为本节中的作建立在前面介绍的内容之上。

这是 的下载链接。您可以单击该链接下载模型并将其复制到您的工作区以供进一步使用。yolov5s.onnx

1.1 下载模型文件

• Yolov5s官方下载链接
• 将模型文件放入工作目录：

mkdir model_yolov5s && cd model_yolov5s
cp -rf ${REGRESSION_PATH}/dataset/COCO2017 .
cp -rf ${REGRESSION_PATH}/image .
mkdir workspace && cd workspace

第一步仍然是将模型转换为文件。因为在使用混合精度量化时 YOLO 中的精度损失很小，所以与之前的方法不同，我们将在最后选择最终的输出名称，而不是参数中 the 之前的输出。在 Netron 中可视化：

2. 模型转换流程

2.1 ONNX转MLIR

由于 yolov5 的归一化参数与 yolo11 相同，我们可以获取以下命令进行 model_transform：

model_transform \
  --model_name yolov5s \
  --model_def yolov5s.onnx \
  --input_shapes [[1,3,640,640]] \
  --mean 0.0,0.0,0.0 \
  --scale "0.0039216,0.0039216,0.0039216" \
  --keep_aspect_ratio \
  --pixel_format rgb \
  --output_names output \  # 关键区别：使用最终输出节点
  --test_input ../image/dog.jpg \
  --test_result yolov5s_top_outputs.npz \
  --mlir yolov5s.mlir

2.2 生成校准表

run_calibration \
  yolov5s.mlir \
  --dataset ../COCO2017 \
  --input_num 100 \
  -o yolov5s_calib_table

3. 混合精度量化核心步骤

与我们转换 int8 对称量化 yolo11 模型的部分不同，在执行model_deploy之前，我们需要生成一个混合精度的量化表。参考命令如下：

3.1 生成量化决策表

run_qtable \
  yolov5s.mlir \
  --dataset ../COCO2017 \
  --calibration_table yolov5s_calib_table \
  --processor cv181x \
  --min_layer_cos 0.99 \
  --expected_cos 0.999 \
  -o yolov5s_qtable

3.2 run_qtable 参数说明表

参数	必需？	描述
N/A	是	指定MLIR文件
dataset	否	指定输入样本目录，其中包含images、npz或npy文件
data_list	否	指定样本列表；必须选择dataset或data_list其中之一
calibration_table	是	输入校准表
processor	是	取决于所使用的平台。2024版本reCamera选择"cv181x"作为参数
fp_type	否	指定混合精度的浮点精度类型，支持auto、F16、F32、BF16；默认为auto
input_num	否	指定输入样本的数量；默认为10
expected_cos	否	指定最终网络输出层的最小预期余弦相似度；默认为0.99
min_layer_cos	否	指定每个层输出的最小余弦相似度；低于此阈值的值将使用浮点计算；默认为0.99
debug_cmd	否	指定开发使用的调试命令字符串；默认为空
global_compare_layers	否	指定要替换的图层以进行最终输出比较，例如’layer1,layer2’或’layer1:0.3,layer2:0.7’
loss_table	否	指定文件名以保存所有量化为浮点类型的层的损失值；默认为full_loss_table.txt

工作原理说明：

1. 在将每层的后续层根据其cos值转换为相应的浮点模式后，会检查该层计算得到的cos值
2. 如果cos值仍然小于min_layer_cos参数，则当前层及其直接后继层将被设置为使用浮点运算

动态调整机制：
run_qtable会在将每对相邻层设置为使用浮点计算后，重新计算整个网络输出的cos值

• 如果cos值超过指定的expected_cos参数，搜索过程终止
• 因此，设置较大的expected_cos值会导致尝试进行浮点运算的层数更多

3.3 编译混合精度模型

最后，运行以获得混合精度 ：model_deploycvimodel

model_deploy \
  --mlir yolov5s.mlir \
  --quantize INT8 \
  --quantize_table yolov5s_qtable \
  --calibration_table yolov5s_calib_table \
  --customization_format RGB_PACKED \
  --fuse_preprocess \
  --aligned_input \
  --processor cv181x \
  --model yolov5s_mix-precision.cvimodel

4. 模型验证

4.1 查看模型信息

在转换和量化完成后，可以使用以下命令查看模型信息：

model_tool --info yolov5s_mix-precision.cvimodel

输出包含：

• TensorMap（张量映射关系）
• WeightMap（权重分布信息）

4.2 在reCamera上测试

1. 我们可以在 reCamera 中运行一个示例来验证混合精度量化 YOLOv5 模型。拉取编译好的测试示例：

git clone https://github.com/jjjadand/yolov5_Test_reCamera.git

2. 部署测试：
   复制编译后的示例并使用 FileZilla 等软件到 reCamera。（您可以查看 reCamera 入门yolov5s_mix-precision.cvimodel
   复制完成后，在 recamera 终端中运行命令：

cp yolov5s_mix-precision.cvimodel /path/to/yolov5_Test_reCamera/solutions/sscma-model/build/
cd yolov5_Test_reCamera/solutions/sscma-model/build/
sudo ./sscma-model yolov5s_mix-precision.cvimodel Dog.jpg Out.jpg

预览，量化后的 yolov5 模型推理结果如下：Out.jogmixed-precision

四、官方资源

• reCamera OS

• reCamera Series

• reCamera example

提示：reCamera持续更新支持更多模型架构，建议定期查看官方更新日志。
如果对于此教程有任何疑问，请到reCamera讨论区提问，我们会为你提供不同的帮助和支持。