做端侧人脸识别落地的同学迟早都会撞上模型转换这堵墙。手里拿着跑得挺好的 Insightface 人脸识别模型训练和评估都在 MxNet 环境下完成一到移动端部署就发现 MxNet 的运行时压根不是给手机准备的。这时候把 MxNet 模型转成 TNN 模型就成了最现实的一条路。这篇文章就围绕这条转换链路展开从 MxNet 模型导出、ONNX 中转、TNN 转换、INT8 量化到端侧精度对齐把每一步的实操细节和踩过的坑都摊开讲。适合手里已经有 Insightface 模型、正准备往端侧推理框架迁移的开发者也适合那些已经在转模型但精度老是对不上的朋友对照排查。1. 为什么非要把MxNet模型搬到TNN上1.1 端侧推理的现实约束先说背景。Insightface 是学术界和工业界都很常用的人脸识别方案训练得到的模型包括 MobileFaceNet、ResNet50 这类骨干网络输出通常是 512 维的人脸特征向量。MxNet 本身是个很成熟的训练框架Symbol 和 Param 的组合在 GPU 服务器上做推理毫无问题但放到手机、嵌入式设备上就非常尴尬MxNet 的推理引擎在移动端的支持很弱安装包体积大对 ARM 架构的优化也不够更不用谈 NPU、GPU 加速这类端侧刚需。实际项目里人脸识别最常见的落地场景就是门禁、考勤、刷脸支付、人流通行这些场景的设备配置普遍不高对延迟和功耗都很敏感。第一原则是推理引擎必须轻量、可裁剪、能在端侧高效跑。TNN 这个开源推理框架在端侧的支持比较完善包括 ARM CPU、GPU、NPU 多种后端模型格式统一配套了模型转换工具和量化工具社区里积累也比较厚。把 Insightface 模型转成 TNN 模型本质上解决的是两件事一是让模型能在真实手机设备上跑起来二是让模型跑得够快、够小。第二点尤其关键因为原版 MxNet 模型动辄几十 MB一个 MobileFaceNet 也有十几 MB这对端侧来说是不小的负担。转换后通常还要做量化来压缩体积和加速量化到 INT8 之后体积能压到原来的四分之一左右加载速度和推理速度都有可感知的提升。1.2 转换链路选型为什么中间走ONNX转换路径最直接的想法是 MxNet 直接转 TNN但 TNN 官方工具对 ONNX 的支持最成熟直接解析 MxNet 的 Symbol 图很容易踩到算子映射不全的问题。所以业界最常见的做法也是我强烈建议你采用的做法是走一条“MxNet → ONNX → TNN”的中间转换链路。ONNX 在这里起的是中间表示的作用它就像通用语言先把 MxNet 的图结构翻译成 ONNX 描述的图再由 TNN 的转换工具把 ONNX 翻译成 TNN 自己的模型格式。这样做的好处是每一段的转换工具都经过大量项目验证遇到问题时你只需要判断问题出在前半段还是后半段排查面会窄很多。这条链路另一个好处是对齐算子。Insightface 模型里常见的算子比如 PRelu、DepthwiseConv、BatchNorm在 MxNet 里有一套名字和参数定义在 ONNX 里又有一套到了 TNN 里还有一套。如果直接做两段式映射兼容性表会非常大而且一旦遇到 TNN 不支持的算子你根本不知道是 MxNet 的算子定义有问题还是中间翻译出了问题。走了 ONNX 之后每一段转换都有明确的报错信息可以用 netron 这类可视化工具直接检查 ONNX 图调试起来非常直观。2. 转换前的准备工作2.1 环境与工具链装配转换不是上来就跑命令先把环境准备好能省掉后面一大半的折腾。我当时用的 Python 环境是 3.8安装了 MxNet 1.7.0ONNX 1.7.0以及配套的 onnxruntime 1.6.0 用来做转换过程的中间验证。TNN 的转换工具核心是一套 Python 脚本从官方仓库 clone 下来之后就能运行另外还需要 protobuf 编译器用于序列化 TNN 模型文件。版本匹配的坑值得提前说。MxNet 官方对 ONNX 导出的支持在不同版本上差异很大如果你用的 MxNet 版本太老比如 1.4 以下导出的 ONNX 会缺少很多新算子支持后面在 TNN 转换阶段会出现一堆不友好的报错。反过来MxNet 版本太新、ONNX 版本不对齐也会出现 protobuf 解析失败。我习惯的搭配是 MxNet 1.7.0 ONNX 1.7.0 onnxruntime 1.6.0这个组合导出 Insightface 模型基本没有遇到图结构层面的问题。如果你的项目里已经有固定版本完全可以沿用前提是确保 onnxruntime 能正确加载导出的 ONNX 文件——这是验证导出成功与否最直接的标准。另外TNN 转换工具本身对 Python 版本有要求3.6 到 3.8 之间的版本比较稳太新的 Python 版本偶尔会有依赖库不兼容的问题。建议单独建一个虚拟环境来跑转换工具不要和训练环境混在一起否则依赖冲突能把人逼疯。2.2 看清Insightface模型的输入输出转换之前一定要先把你手里的模型结构吃透。Insightface 训练出来的模型通常包括两部分一部分是特征提取骨干网络另一部分是最后的全连接层和特征归一化处理。实际部署到端侧时全连接层往往会被去掉因为需要的只是骨干网络输出的特征向量。所以在导出 ONNX 时你要决定是导出整个模型还是只导出骨干部分。建议只导出骨干部分模型更小也避免把训练阶段的层带进部署阶段。再一个关键点是输入尺寸。Insightface 的标准输入一般是 112x112 的 RGB 人脸图像但有些辅助模型或者其他变体可能是 128x128 或其他尺寸必须提前确认。TNN 转换时输入尺寸需要显式固定除非你后面要做动态 shape 的支持。MxNet 导出 ONNX 时同样要显式指定输入形状通常写成 (1, 3, 112, 112)前面的 1 是 batch size3 是通道数后面的 112 是宽高。这里要特别强调ONNX 导出时尽量用固定尺寸不要用动态维度的写法。动态维度在后面 TNN 转换时大概率会碰到不支持或者需要额外处理的麻烦固定尺寸能省掉很多不必要的坑。2.3 预处理协议必须提前锁死很多人在转换上花了一堆时间最后测试精度对不上回头才发现是预处理不一致这个坑非常隐蔽。Insightface 模型训练时的预处理协议通常是读取图像后先做仿射变换把五个人脸关键点对齐到标准位置然后裁剪到 112x112接着把像素值转到 float 并缩放到 0 到 1 的范围再做标准化。mean 和 std 的具体数值必须和训练时的配置完全一致不同版本可能有细微差别务必从训练好的 config 里找到原始的 mean 和 std不要凭记忆去猜。另外一个容易忽略的点是通道顺序。MxNet 默认是 RGB 格式但很多端侧框架内部习惯用 BGR比如 OpenCV 读出来的图像默认就是 BGR。如果你的端侧推理代码直接拿 OpenCV 读图然后喂给模型却忘了做 RGB/BGR 的通道转换精度会惨不忍睹。而且这种问题不容易被直觉发现因为特征向量依旧有模只是相似度全部偏低。我的建议是把通道转换、缩放、标准化全部封装成一个函数并且在验证阶段用同一个预处理函数在 MxNet 侧和 TNN 侧分别跑确保两边完全一致。这个动作看起来简单但能帮你避免后面最耗时的一类问题。3. MxNet到ONNX的导出实操3.1 导出脚本与固定输入尺寸导出这一步用 MxNet 的 ONNX 导出接口就能完成。核心逻辑是加载 Symbol 和 Params然后调用导出函数传入输入名字和输入 shape。一个常见问题是 MxNet 模型的输入名不一定是 data有些模型是 data0 或者其他名字需要先从 Symbol 里取到实际输入名再传入不然导出时会报错或者导出的图输入名字和预期不一致。以下是核心导出逻辑import mxnet as mx from mxnet.contrib import onnx as mx_onnx sym, arg_params, aux_params mx.model.load_checkpoint(model, 0) input_name sym.list_inputs()[0] print(input name:, input_name) onnx_model_path insightface_mobilefacenet.onnx mx_onnx.export_model( sym, [input_name], [(1, 3, 112, 112)], arg_params, aux_params, onnx_model_path, verboseFalse )这里有几个细节。model 是 checkpoint 前缀名0 是 epoch 序号如果你的模型有多个 epoch 保存要注意加载的是最终训练好的那个。导出的 ONNX 文件用 onnxruntime 加载并跑一次确认能正常输出结果import onnxruntime as ort import numpy as np sess ort.InferenceSession(insightface_mobilefacenet.onnx) input_name sess.get_inputs()[0].name fake_input np.random.randn(1, 3, 112, 112).astype(np.float32) outputs sess.run(None, {input_name: fake_input}) print(output shape:, outputs[0].shape) # 保存参考输出后续TNN对比要用 np.save(reference_output.npy, outputs[0])如果 onnxruntime 报错说明导出的图有问题一定要解决之后再继续往下走。不要心存侥幸跳过这一步。3.2 导出后的ONNX结构体检导出成功只是第一步必须检查 ONNX 图的结构。用 netron 打开生成的 ONNX 文件重点看这么几处输入是不是 (1, 3, 112, 112)输出节点的名字和 shape 是否符合预期关键算子比如 PRelu、Conv、BatchNorm 是否都在有没有出现莫名其妙的冗余节点。另外一个值得养成的习惯是把 ONNX 图在 onnxruntime 里跑一份生成参考输出存成 npy 文件。这个 npy 文件在后面的 TNN 转换验证阶段非常有用相当于一个“标准答案”。我当时就是拿这个输出作为基准和 TNN 模型的输出做逐点对比误差控制在千分之一以内才算通过。如果这一步没有保存参考输出后面精度对不上时你根本分不清是转换引入的问题还是预处理的问题。检查输出节点时需要留意如果你心里预期的输出是 512 维特征但 ONNX 的输出 shape 是 (1, 512)那就对了。如果多出一些训练阶段的输出节点比如 loss、softmax 之类的建议裁剪掉只保留特征输出。3.3 常见的导出报错与绕坑导出阶段最常见的报错是算子不支持或者图里有训练专属节点。比如模型里带着 BatchNorm 的 running mean 和 running variance 时如果 MxNet 版本处理不够好可能会把这些辅助输入也当成模型输入导致 ONNX 图里有奇怪的输入。这种情况可以把这些辅助参数固化到前面的卷积层里也就是常说的 fold BatchNorm让 MxNet 在导出前把 BatchNorm 直接合并进卷积层权重导出后的 ONNX 图更干净TNN 转换时也能少掉一类算子的麻烦。Insightface 的模型基本都有 BatchNorm 层这一步几乎必做。还有一个报错是关于全连接层的。Insightface 的全连接层在训练阶段经常被改造成并行的多个子空间全连接如果你的模型里有这类结构导出时会遇到不支持的操作。我的建议是导出前把后处理相关的层全部裁剪掉只保留到最后的特征输出层。这样既省后端计算也避免导出报错。裁剪的时候要小心先确认输出节点的名字是你想要的特征输出然后再动手。实际操作里我还遇到过 ONNX 导出后权重数值对不上的情况原因是 load_checkpoint 加载的 epoch 不对加载了中间保存的 checkpoint 而不是最终模型。建议加载前打印一下 epoch 文件列表确认是最优的那一个。4. ONNX到TNN的转换与量化4.1 用TNN转换工具做基础转换拿到干净的 ONNX 文件之后接下来就是用 TNN 的转换工具把它转成 TNN 模型。TNN 的转换工具是一个 Python 脚本运行方式是指定 ONNX 文件路径、输出目录和模型版本。转换完之后会生成两个文件.tnnproto 是模型结构文件.tnnmodel 是权重文件。这两个文件在端侧部署时要一起拷到设备上。基础转换大致是这样python3 converter.py -onnx insightface_mobilefacenet.onnx -o ./output -v v2.0转换成功会有对应日志如果遇到不支持的算子会直接报错并给出算子名字。这里我建议第一次转换先用 FP32不做量化先把转换链路走通。因为如果一开始就把量化和转换混在一起出了问题你很难定位是图转换失败还是量化导致的偏差。先跑通 FP32 模型再考虑量化这个顺序能让你少走很多弯路。转换成功后在输出目录里会看到两个文件一个以 .tnnproto 结尾一个以 .tnnmodel 结尾。用 TNN 自带的模型检查工具或者直接写一个简单的加载脚本确认这两个文件能被正确加载再进入下一步。4.2 算子兼容性处理TNN 对 ONNX 的支持已经比较完善但 Insightface 模型里总有几个算子需要额外处理。最典型的两个是 PRelu 和某些特殊形式的 Reshape/Transpose。PRelu 是带参数的 ReLUMxNet 里叫 PReluONNX 里表示方式也一样。TNN 的不同版本对 PRelu 的支持情况不同老版本可能不支持新版本已支持。如果你手里的 TNN 版本遇到 PRelu 报错有几个绕的办法。一种是把 PRelu 转成带权重参数的表达式在 ONNX 图上直接改算子类型另一种是在导出前把 PRelu 的 alpha 参数固定改写成等价的组合算子比如 alpha 大于 0 的部分就是一个带权重的 Elementwise 操作。我当时的做法是用 ONNX 的图编辑接口把 PRelu 节点改写成 Conv Slice Add 的组合工作量不大但可以彻底绕开版本兼容性问题。Reshape 和 Transpose 的问题则往往是维度推导出错。TNN 转换时对动态 shape 支持有限如果 ONNX 图里有依赖输入 shape 计算的 Reshape比如把某个维度写成了 -1转换工具可能无法推导出具体的维度数值导致失败。解决办法是在 ONNX 导出时就固定所有 shape或者用图编辑工具把动态维度改成静态值。判断哪些节点是动态维度的方式很简单用 netron 看 Reshape 的输入里是否有一个 shape 张量是计算出来的如果是就把它改成常量。业内还有个思路就是在导出 ONNX 之后用工具跑一遍图精简像 Identity 这种冗余节点直接消除掉减少后续转换环节的负担。我第一次走转换链路就发现 ONNX 图里有一堆 Identity 和 Cast 节点虽然不报错但转换后的 TNN 模型明显偏大精简之后再转体积和加载速度都有改善。4.3 INT8量化的校准集准备FP32 模型跑通之后如果对延迟和体积有要求下一步就是量化。TNN 的量化工具支持 INT8 量化原理是用一组真实输入数据去校准每一层的数值范围然后把浮点权重和激活值映射到 INT8 表示。量化的关键是校准集的选择这一点直接决定量化后的精度损失。校准集应该从你的真实业务数据里采样最好是 100 到 200 张已经对齐好的人脸图像覆盖不同的人、不同的光照、不同的角度。千万不要用空白图像或者训练集图像直接凑数因为校准数据的分布如果和真实分布差异太大量化范围就校准不准精度损失会非常明显。我当时用了一个 128 张对齐人脸的校准集量化后的 MobileFaceNet 在验证集上的精度损失大约在 1% 到 2% 以内属于可以接受的范围。校准集的图像尺寸必须是 112x112预处理方式和正常推理完全一致包括缩放、标准化这些步骤缺一步都会影响量化效果。量化命令一般是python3 quantizer.py -m insightface_mobilefacenet.tnnproto -n insightface_mobilefacenet.tnnmodel -o quantized_model -d calibration_data -t int8量化后的模型体积大约是 FP32 的四分之一比如原来 13MB 的模型量化后大概 3.5MB在端侧加载和推理速度都有明显提升。但要注意如果模型里某些层对精度特别敏感比如最后的特征输出层可以考虑保留为 FP32 混合精度。TNN 支持指定某些层不做量化这个能力在精度敏感的场景下非常有用。5. 端侧验证与精度对齐5.1 输出比对与特征余弦相似度转换完成不是终点验证才是真正的考验。验证的第一步是把 TNN 模型的输出和之前保存的参考输出做逐点对比。理想情况下FP32 模型误差应该在 1e-3 量级如果误差太大就要回到转换环节去查问题。但逐点对比只适用于 FP32 模型量化后的模型因为数值表示精度下降误差会大一些不能直接套用这个标准。对于人脸识别模型更应该关注特征层面的指标余弦相似度。具体做法是准备一组测试图像对包括同一人的不同照片和不同人的照片分别用 MxNet 模型和 TNN 模型提取特征计算两组特征之间的余弦相似度。如果同一人的相似度保持在比较高的水平比如 0.8 以上不同人的相似度保持在比较低的水平比如 0.3 以下而且 MxNet 和 TNN 两个版本的结果差距不大说明转换在业务指标层面是可接受的。这里有个比较实用的经验用 TNN 的 Python 接口或者写一个简单的端侧 Demo在真实设备上跑一遍完整的人脸特征提取流程而不是只在服务器上用 Python 模拟。因为在服务器上跑的数值结果和设备上可能存在细微差别包括算子实现差异和线程调度引起的浮点误差这些在特征比对层面可能被放大所以最终必须以设备上的实测结果为准。5.2 整链路测试预处理-推理-后处理很多人转换模型的时候只关注推理部分却忽略了整条链路的一致性结果是在设备上跑出来的特征向量乱七八糟。完整的端侧链路应该是这样的摄像头或者图像输入 → 人脸检测和对齐 → 仿射变换裁剪到 112x112 → 通道转换和标准化 → TNN 推理 → 得到 512 维特征向量 → 特征归一化L2 Norm→ 与底库特征计算相似度。这里面最容易出错的是仿射变换的实现细节。Insightface 训练时的对齐方式是先检测五个关键点左眼、右眼、鼻尖、左嘴角、右嘴角然后用固定的目标点坐标做仿射变换。目标点坐标的具体数值必须和训练时保持一致不同项目可能不同。如果你在端侧用的是不同的人脸关键点检测器输出的关键点顺序可能不同比如有些检测器输出的顺序是右眼、左眼、鼻尖、右嘴角、左嘴角如果不做顺序调整对齐结果就会错乱。这是我见过最多的问题没有之一。所以整链路测试的时候一定要用一个已知的测试图像在服务器上用 Python 完整跑一遍把每个阶段的中间结果对齐图、预处理后的张量保存下来然后在端侧逐个对比。哪一个阶段对不上就修哪一个阶段。我当时就是用这个方法定位到一个 BGR/RGB 通道顺序的问题把中间张量打印出来对比才发现差异。5.3 精度不符时的排查顺序如果在端侧测出来的精度和 PC 端差异很大不要一头扎进代码里乱猜按顺序排查大概率能快速定位。我的排查顺序是这样第一步查预处理。确认端侧和 PC 端用的预处理代码是否逐行一致包括通道顺序、像素缩放、mean 和 std。如果有任何一行不一致直接改掉再测试。这一条能解决至少一半的“精度不对”问题。第二步查输入张量的排布。确认送入 TNN 的 buffer 是 NCHW 排布还是 CHW 排布TNN 对输入排布有明确要求填错的话数据就串位了。还有一个常见坑是 stride 问题如果图像宽度 112 但 buffer 的 stride 是 128每一行的数据会错位特征会完全不对。第三步回到模型本身。用 TNN 的可视化工具或者日志输出检查模型每一层的关键中间结果和 ONNX 参考输出做对比。TNN 支持逐层输出调试打开 debug 模式之后可以看到每一层的输出数值对比差值比较小的就是正常的差值突然放大的那层就是要重点关注的算子。第四步如果以上都排查过没问题就看是不是量化导致的精度退化。把量化模型换回 FP32 模型试一次如果 FP32 精度正常而量化模型不正常问题就锁定在量化校准环节需要重新准备校准集或者考虑混合精度方案。为了方便对照把常见问题整理成下面这个速查表现象优先排查项解决方向输出误差大预处理不一致统一 RGB/BGR、mean/std、缩放特征相似度整体偏低输入排布或 stride 错误检查 NCHW 排布和 buffer stride某一层误差突然放大算子兼容性问题替换 PRelu、固定 Reshape 维度量化模型精度差校准集分布不符重新采样对齐人脸图像做校准转换直接报错工具版本不匹配更新 TNN、ONNX、MxNet 版本6. 踩坑记录与项目心得最后分享几个我在实践中的具体体会。第一个是关于工具版本的。我早期用过一个比较老的 TNN 版本转换工具对 ONNX 中某些新算子支持不到位整整折腾了两天才发现是版本问题。换了新版本之后同样的命令一次就过。所以遇到转换报错第一个动作应该是查 TNN 版本和 ONNX 版本是否符合官方推荐的搭配而不是急着去改模型结构。第二个是关于“图干净”这件事。一个看起来能正常导出的 ONNX 图内部可能有很多冗余节点比如 Identity、Cast、Squeeze 这些。这些节点单个看无害但累积起来会影响转换效率和端侧推理性能。有条件的话在导出后做一次简单的图精简把冗余节点消除掉再用精简后的图去做转换。我试过精简后的图在 TNN 转换和端侧推理上都比之前更快更稳。第三个是关于团队协作。如果方案是多人协作一定要在项目一开始就把预处理函数和测试数据的路径统一约定好并且把转换好的模型连同参考输出、预处理代码、测试图像一起放进统一的目录管理。这样任何一个环节改造之后大家都能用同一套标准去做回归测试。我在一个项目里因为没有统一预处理结果两个人在各自机器上跑出的特征相似度差了 0.2最后才发现是一个用 RGB 一个用 BGR浪费了整整一天。第四个是关于备份。每一次有效的转换配置、校准集、量化参数都应该记录到项目的说明文档里。这些配置看起来简单但重新调整的时候往往要花不少时间重新尝试。真正的经验密度其实就在这些配置和踩坑记录的积累里。Insightface MxNet 转 TNN 这条路走通一次之后后面的模型再转就很快了。核心无非就是固定输入、导干净图、走 ONNX 中转、用真实数据校准、按顺序排查精度。把这五件事做扎实你手里的模型就能顺利在端侧跑起来。
