3、模型转换基础：从PyTorch/TensorFlow/ONNX到BM1684模型的转换流程
BM1684作为算能科技推出的高性能边缘计算AI芯片，其原生支持的计算图格式为BMCompiler中间表示（简称F32/F16/BF16格式的bmodel）。实际业务中，算法工程师绝大多数情况下使用PyTorch、TensorFlow或导出ONNX进行模型训练与验证，因此必须通过转换工具链将训练框架模型映射为BM1684可执行的bmodel。本章围绕转换流程、工具链基本用法、常见失败原因与排查手段展开，帮助学员建立从“训练框架模型”到“BM1684可运行模型”的完整认知闭环。
3.1 转换流程的核心原理与工具链组成
BM1684的模型转换并非简单的格式改写，而是将训练框架中的计算图逐层映射为芯片上可执行的指令序列与数据布局。整个转换流程遵循“前端解析—中间优化—后端生成”的三段式设计。前端负责读取PyTorch/TensorFlow/ONNX等格式的模型文件，将其解析为统一的内部计算图表示（称为TOP或F32 umodel）；中间阶段执行算子融合、常量折叠、内存规划等优化；后端则根据BM1684的硬件特性（如TPU内核数量、局部存储器大小、DMA带宽）生成最终的bmodel二进制文件。
工具链的核心组件包括：bmneto（负责ONNX/TensorFlow/Caffe模型的前端转换）、bmnetp（执行INT8量化与校准）、bmneta（精度分析与层间误差对比）、bmcompiler（最终编译生成bmodel）。实际工程中，通常使用bmneto将模型转为fp32 umodel，再通过bmnetp进行量化，最后调用bmcompiler生成可部署文件。对于纯FP32推理场景，也可以跳过量化步骤直接编译。
3.2 转换操作流程与关键参数配置
以最常见的ONNX转换路径为例，标准流程包含以下步骤：
- 环境准备：安装
tpu-mlir或bmneto工具包，确认版本与BM1684 SDK匹配。推荐使用Docker镜像sophgo/tpu-mlir:latest，避免依赖冲突。 - 模型导出：在PyTorch中通过
torch.onnx.export导出ONNX文件，需固定输入Shape并设置opset_version=11或更高。导出后使用onnxsim进行图优化，消除冗余节点。 - 执行转换：运行
bmneto --model=model.onnx --outdir=./out --input_shapes="[1,3,224,224]" --target=BM1684。其中--input_shapes必须与导出时一致，否则会报Shape不匹配错误。 - 量化校准（可选）：若需INT8模型，使用
bmnetp --model=model_fp32.umodel --cali_images=./cali_set --cali_iterations=100。校准集应覆盖真实部署场景的数据分布，通常建议500-1000张代表性图片。 - 编译生成：最终通过
bmcompiler --model=model_int8.umodel --out=model_int8.bmodel生成bmodel。编译时可指定--opt=2（优化等级）和--dyn=false（关闭动态Shape）。
| 工具名称 | 输入格式 | 输出格式 | 核心参数 | 典型用途 |
|---|---|---|---|---|
| bmneto | .onnx/.pb/.prototxt | fp32 umodel | --input_shapes, --target | 前端解析与图优化 |
| bmnetp | fp32 umodel | int8 umodel | --cali_images, --cali_iterations | INT8量化与校准 |
| bmneta | fp32/int8 umodel | 精度报告 | --compare_layer | 逐层精度对比 |
| bmcompiler | umodel | .bmodel | --opt, --dyn, --out | 最终编译生成 |
--target=BM1684，工具链可能默认生成BM1686或BM1688格式，导致部署时加载失败。务必在每次转换命令中显式声明目标芯片型号。
3.3 实战案例：YOLOv5s从PyTorch到INT8 bmodel的完整转换
以YOLOv5s检测模型为例，展示实际转换过程中遇到的典型问题与解决路径。该模型包含C3模块、Focus层、SPP层等结构，在转换时具有代表性。
背景与约束：项目要求将YOLOv5s部署到BM1684边缘盒子，输入分辨率640×640，帧率需达到30FPS以上，因此必须使用INT8量化。训练框架为PyTorch 1.9，模型权重为官方预训练COCO模型。
初始现象：直接使用bmneto转换导出的ONNX文件，报错Unsupported op: Focus。进一步查看日志发现，YOLOv5中的Focus层（通过slice+concat实现）在ONNX中展开为多个Gather和Concat节点，部分节点不被BM1684前端支持。
分析判断过程：通过bmneto --print-stats查看算子统计，发现不支持算子集中在Focus层和SPP中的CBS模块。查阅BM1684算子支持列表，确认Gather算子仅支持axis=0且indices为常量，而Focus展开后的Gather axis=2不满足条件。
实际操作步骤：
- 修改YOLOv5模型代码，将Focus层替换为标准的Conv层（stride=2），重新训练或直接加载原权重并调整结构。
- 导出ONNX时设置
opset_version=12，并使用onnxsim简化模型，消除不必要的Reshape和Transpose。 - 执行转换：
bmneto --model=yolov5s_sim.onnx --input_shapes="[1,3,640,640]" --target=BM1684 --outdir=./fp32，成功生成fp32 umodel。 - 准备1000张COCO验证集子集作为校准数据，运行
bmnetp --model=./fp32/compilation.bmodel --cali_images=./cali --cali_iterations=200，生成int8 umodel。 - 编译生成最终bmodel：
bmcompiler --model=./int8/compilation.bmodel --out=yolov5s_int8.bmodel --opt=2。
结果对比：转换后模型在BM1684上实测推理耗时约12ms/帧（含预处理），满足30FPS要求。INT8模型mAP@0.5为0.562，相比FP32的0.574仅下降2.1%，在可接受范围内。
风险与代价：替换Focus层导致模型结构改变，需重新验证输出张量形状；校准集选择不当可能引起精度下降超过5%。建议在量化后使用bmneta逐层对比激活值分布，定位异常层。
bmneto --print-stats快速扫描模型，提前识别不支持的算子，避免后期反复修改网络结构。
3.4 常见误区与转换日志分析要点
模型转换失败时，日志是定位问题的第一手资料。BM1684工具链的日志通常分为三个级别：INFO（正常流程信息）、WARNING（潜在风险提示）、ERROR（致命错误）。学员应养成查看完整日志的习惯，而非只关注最后几行。
典型的日志分析路径如下：
- 算子不支持：日志中出现
Unsupported op: XXX或Not implemented for XXX。解决策略包括：替换为等价算子组合、使用--op_attr调整参数、或通过--custom_op注册自定义算子实现。 - 输入Shape不匹配：报错
Shape mismatch at input[0]。检查导出ONNX时的动态轴设置，确保--input_shapes与模型实际输入一致。对于动态Batch场景，可固定为1并配合外部批处理。 - 量化精度异常：转换成功但推理结果错误。查看
bmnetp输出的校准日志，关注cosine similarity指标，若低于0.99则需增加校准集多样性或改用逐通道量化。 - 内存不足：日志显示
Out of memory。可通过--opt=0降低优化等级，或使用--split参数将模型分段编译。
总结而言，BM1684模型转换的核心在于“静态化”与“算子适配”。学员需要掌握工具链的基本命令，理解日志中关键字段的含义，并具备根据错误信息反推模型结构问题的能力。建议在项目启动前，先使用官方提供的模型动物园（Model Zoo）中的同类模型进行预转换测试，建立对工具链行为的直觉认知，再处理自有模型。