RK3588边缘端Facenet人脸识别模型转换与RKNN部署实践

人脸特征向量提取这件事在服务器上跑不算特别难真正让人头疼的是把它塞进RK3588这种边缘SoC里和NPU打交道。Facenet作为经典的老牌人脸识别模型结构不算复杂但网上资料特别容易把人带沟里——大部分帖子还在将PC上怎么训练、怎么建人脸库到了“PyTorch模型怎么一步步变成RKNN、怎么在板端跑起来”这一步资料一下少了一大半而且每一步都可能踩坑。我这次从零走通了一遍完整链路包括环境搭建、PyTorch导出ONNX、ONNX转RKNN、量化、板端推理和性能调优把遇到的坑和解决办法全部整理出来希望能省下你几天的时间。这篇内容适合手里已经有一块RK3588开发板、准备做边缘侧人脸识别或类似特征提取任务的开发者。你不需要对RKNN有多深的理解只要熟悉PyTorch基础、会敲命令行就行。我会把关键代码、版本组合和排障思路都写清楚照着做基本能复现。1. 项目背景与技术选型思路先说清楚为什么这个组合在2024年了还有人折腾。RK3588这颗芯片在边缘AI里出镜率很高内置的NPU算力标称6 TOPS支持int8、int16、fp16混合精度关键是可以跑一些不大不小的CNN模型而且整板功耗比GPU友好太多。和树莓派、Jetson系列比起来RK3588的优势是接口丰富、价格适中缺点是NPU工具链没那么成熟相关问题一大半出在转换和量化环节。Facenet这边我选的是经典的Inception ResNet v1结构输入160x160输出512维的embedding向量。虽然现在有更新的ArcFace、CosFace这些方案但Facenet模型轻、结构直观、开源权重多非常适合作为RKNN部署的练手模型。识别流程也不复杂先用一个人脸检测器把脸框出来然后裁剪对齐成160x160输入给Facenet最后拿输出的512维向量去和库里的人脸向量算余弦相似度或欧氏距离超过阈值就算匹配。整条部署链路可以拆成三个阶段PyTorch导出ONNX、ONNX转RKNN、板端推理。第一个阶段考验你对模型结构和ONNX导出的理解第二个阶段考验你对RKNN工具链和量化原理的掌握第三个阶段考验的是板端环境调试能力。三个阶段的坑完全不一样我一个个说。1.1 为什么选RKNN而不是直接跑ONNX Runtime有人可能会问都2024年了RK3588能不能直接装个ONNX Runtime跑模型答案是能跑但基本发挥不出NPU性能。ONNX Runtime在ARM上默认走CPU推理一小撮算子能走一下GPU但NPU是完完全全用不上的。我实测下来在RK3588 CPU上跑160x160输入的Facenet单次推理大概需要200到300毫秒而转成RKNN后走NPU耗时直接降到十毫秒级别差距在二十倍以上。所以做边缘端推理RKNN几乎是绕不开的。RKNN是瑞芯微自己的神经网络模型格式通过rknn-toolkit2工具链把ONNX、PyTorch、TensorFlow等模型转换成RKNN然后再用RKNN Runtime在板上加载执行。转换过程中还可以对模型做int8量化进一步压推理延迟和内存占用。代价就是工具链的坑比较密集版本匹配、算子支持、量化精度全是地雷。1.2 整条链路的全貌和主要风险点我这次走的链路是这样的PyTorch预训练权重 - torch.onnx.export导出ONNX - onnx-simplifier精简 - onnxruntime验证输出一致性 - rknn-toolkit2加载ONNX - 配置平台和量化参数 - build生成RKNN - RK3588板端用RKNNLite加载推理。每个环节的核心风险点分别是导出环节的opset版本和动态维度问题、精简环节的算子融合问题、转换环节的量化精度问题、板端环节的驱动和运行时版本匹配问题。记住这张路线图后面所有内容都是围绕它展开的。2. 环境准备版本匹配是第一优先级先泼一盆冷水RKNN工具链的老版本兼容性真的一般和PyTorch、ONNX这些开源生态的版本耦合也比较紧前期装环境如果版本对不上后面一步一个错。我建议在动手之前先把PC端和板端的版本列一个清单照着装不要盲目升级。我的环境是这样的PC端Ubuntu 20.04 x86_64、Python 3.8、rknn-toolkit2 1.6.0板端RK3588开发板、Ubuntu 22.04ARM版、RKNPU2运行时驱动 1.6.0模型链路PyTorch 1.13.1、onnx 1.13.1、onnxruntime 1.14.1这个组合在我这边跑通没有问题。如果你用更新版本的rknn-toolkit2比如2.x接口会有变化配置参数也可能不一样。别看到新版就往上冲除非你非常清楚新版改了哪些东西。工具链的文档里有一张版本对应表建议先翻一翻。2.1 安装rknn-toolkit2的几个坑rknn-toolkit2的安装推荐用conda单独建一个虚拟环境千万不要直接装进系统Python。原因很简单它依赖的包很多跟其他项目冲突的概率非常大。我踩的第一个坑就是它强依赖特定版本的numpy和protobuf装完直接把我另一个项目的numpy版本顶掉了。官方建议是用Python 3.6到3.10之间我自己用3.8最稳。安装方式可以选择从pip源安装也可以拉官方Docker镜像。如果你不想折腾依赖关系官方Docker镜像是省事的路子但我个人更喜欢conda环境因为改起来灵活。安装完第一件事跑一下官方自带的demo确认环境是好的再碰自己的模型。很多人在这个环节就卡住了报错大多是numpy版本不对、缺少libpython或者RKNN模块找不到。这不丢人工具链就这个脾气一个一个装回来就好。2.2 板端运行时和PC端工具链的版本对应板端要装的是RKNN Runtime的Python包叫rknnlite和对应的NPU驱动固件。注意rknnlite的版本要和PC端rknn-toolkit2的版本匹配。我用的是1.6.0对上1.6.0。如果你PC端转出来的RKNN模型在板端加载时报版本不兼容优先检查这一对版本。另外板端系统里可能已经有瑞芯微自带的NPU驱动了如果你是拿公版Ubuntu镜像装的要确认一下/dev/rknpu设备节点是否存在。没有这个节点模型根本加载不起来。查一下ls /dev/rknpu有输出基本就说明驱动正常。3. Facenet模型关键点与预处理分析动手转换之前花点时间把模型和预处理搞清楚比什么都重要。这个环节偷懒后面识别率崩了都不知道去哪找原因。Facenet的原始实现里主干网络是Inception ResNet v1最后接一个Embedding层输出512维向量。整个模型很大参数量在20M以上但实际部署时因为输入只有160x160计算量还在可接受范围内。模型在输出端有个细节有的实现会在最后做L2归一化有的不会这个直接影响后面相似度计算最好在PyTorch里先确认清楚。3.1 输入尺寸与预处理是第一个精度杀手Facenet的官方预处理不是常用的mean/std归一化而是把像素值从0到255先减去127.5再除以128直接映射到[-1, 1]区间。这个细节相当关键。很多从ImageNet训练来的模型惯用mean[0.485, 0.456, 0.406]、std[0.229, 0.224, 0.225]那套归一化如果你套用给Facenet特征分布直接歪掉人脸识别率会惨不忍睹。这也解释了为什么有些人明明模型转换成功了在板端跑出来的人脸特征跟训练时完全对不上。别问我是怎么知道的我在这上面浪费了两个晚上。所以第一步先用PyTorch在PC上加载官方权重用一张标准人脸图跑一遍记录输出向量作为后面所有环节的基准。3.2 相似度计算和阈值选择Facenet输出的512维向量在实际使用中通常要做L2归一化然后算两个向量的余弦相似度。余弦相似度的取值范围是-1到1数值越接近1表示越像同一个人的脸。阈值一般设置在0.6到0.8之间具体要根据自己的数据集调。我实测下来在自然场景下0.7左右是比较靠谱的起点如果光线稳定、证件照场景可以调到0.75以上反之如果场景复杂可能得降到0.6以下。注意有些Facenet实现输出的是未归一化的embedding直接在推理结果上做L2归一化是安全的归一化后再算相似度也符合原论文的做法。4. PyTorch转ONNX实操模型转换的第一大步是把PyTorch模型导出成ONNX。这一步看起来简单实际上坑很多。最典型的问题包括导出后的模型在onnxruntime里跑的结果和PyTorch对不上、动态维度设置导致NPU转换失败、opset版本问题导致某些算子不支持等。4.1 导出脚本怎么写我用的导出脚本大概长这样import torch import torch.onnx model load_facenet_model() # 你自己的模型加载逻辑 model.eval() dummy_input torch.randn(1, 3, 160, 160) torch.onnx.export( model, dummy_input, facenet.onnx, input_names[input], output_names[embedding], dynamic_axes{input: {0: batch}, embedding: {0: batch}}, opset_version12, do_constant_foldingTrue, )这里有个细节opset_version我用的是12不是越高越好。RKNN工具链对新版opset的支持有滞后选太高可能导致后面转换时遇到“不支持的算子”报错。如果转换时报了算子问题优先试试把opset降到11或12。4.2 dynamic_axes的取舍dynamic_axes设置成只动态batch维度是个比较稳的折中方案。如果你把宽高也设成动态ONNX模型会更通用但RKNN转换时对动态shape的支持比较有限后面可能会遇到麻烦。我建议转换最终部署模型时干脆把完整shape都固定死比如1x3x160x160这样RKNN转换最顺利NPU上跑的效率也最高。导出后用onnxruntime验证一下import onnxruntime as ort import numpy as np sess ort.InferenceSession(facenet.onnx) inputs np.random.randn(1, 3, 160, 160).astype(np.float32) onnx_out sess.run(None, {input: inputs})[0] # 和PyTorch模型的输出对比误差一般小于1e-4就算正常这一步非常重要如果ONNX的输出和PyTorch输出误差过大说明导出环节出了问题千万不要带着问题往下走。4.3 用onnx-simplifier清洗模型导出后的ONNX模型常常包含一些冗余结构和格式转换算子比如Identity、Cast、Transpose这些对NPU不友好。推荐用onnx-simplifier做一次精简pip install onnx-simplifier python -m onnxsim facenet.onnx facenet_sim.onnx简化之后记得再次用onnxruntime验证输出一致性。简化器偶尔会有一点点数值扰动但误差应该非常小。如果简化后误差变大用原始的ONNX也行不一定非得简化我见过某些模型简化后反而出错的情况。5. ONNX转RKNN量化与平台配置接下来是整条链路里最核心也最容易出问题的一步把清洗好的ONNX转成RKNN。这一步和硬件强相关需要明确指定目标平台是RK3588因为不同平台的NPU指令集和算子支持有差异。同时量化策略直接决定了转出来的模型精度和性能。5.1 转换脚本核心代码我的转换脚本基本框架如下from rknn.api import RKNN rknn RKNN() rknn.config(target_platformrk3588) ret rknn.load_onnx(modelfacenet_sim.onnx) assert ret 0 ret rknn.build(do_quantizationTrue, datasetdataset.txt) assert ret 0 ret rknn.export_rknn(facenet.rknn) assert ret 0这不是完整代码只是为了让你看到核心流程。实际开发时还要加上release_memory等资源释放操作。config里还可以配置mean_values和std_values。如果你想让NPU在输入端帮你完成预处理可以在config里指定rknn.config(target_platformrk3588, mean_values[[127.5, 127.5, 127.5]], std_values[[128, 128, 128]])这样设置之后板端输入原始RGB图像0到255范围给RKNN推理接口内部会自动帮你完成减均值除标准差的操作。这个正好对应Facenet官方的预处理非常方便也省去在板端再做一遍numpy运算的时间。5.2 量化数据集怎么准备do_quantizationTrue时RKNN需要一份数据集来统计每层激活值的分布范围从而计算int8的scale和zero point。dataset.txt文件里的每一行是量化图片的路径支持npy或者图片格式。我用的是一张张裁剪好的160x160人脸图存成npy格式。量化数据集的选取直接关系到量化质量。你最好从实际部署场景中挑选有代表性的人脸图片光线、角度、肤色尽量多样化。数量不需要太多几十张到两百张就够关键是质量和覆盖面。我试过用300张公开人脸数据集外的图片做量化效果反而不如精心挑选的50张实测场景图。关于量化还有一个常见误区不要在部署前的调试阶段就急着做int8量化。第一次转模型建议先跑一遍fp16或fp32确认为模型输出正常再做int8量化。如果上来就量化出了问题你不知道是转换问题还是量化问题排查起来非常痛苦。5.3 int8量化精度下降的应对策略RK3588的NPU对int8支持最好理论算力6 TOPS也是基于int8计算的。但int8量化在Facenet这种特征提取模型上极其容易掉点原因是embedding向量对数值精度敏感量化噪声会直接污染最后的特征。我试过直接全量int8量化识别率掉到没法用两个人脸的区分度变得很模糊。解决思路有三个第一个认真准备量化数据集用场景相关数据的量化效果会明显改善第二个对敏感层做混合量化让某些关键层保持fp16第三个如果条件允许用QAT量化感知训练微调模型但成本较高一般部署阶段不建议。rknn-toolkit2支持混合量化配置在rknn.config里可以针对特定算子或层设置量化精度。具体API在1.6.0版本里是rknn.config(quantized_dtypefp16)这种全局设置也有更细粒度的方式但不同版本接口有差异建议直接查对应版本的手册。我自己的经验是先全局int8看精度如果不行再把模型最后的Embedding层和全连接层设为fp16往往能找回大部分精度损失。5.4 转换后的验证RKNN模型转出来之后别急着上板。先在PC端用模拟器验证一遍rknn.init_runtime(targetNone) # 模拟器模式 outputs rknn.inference(inputs[preprocessed_img])拿这个输出和之前onnxruntime的输出做对比。如果模拟器输出和ONNX输出差别很大先排查配置和量化数据集的问题。没问题了再上板测。6. 板端推理与性能优化模型转换完毕就进入板端部署环节。RK3588板端的推理接口和PC端不一样用的是RKNNLite一个专门为端侧设计的轻量级运行时。6.1 RKNNLite推理示例板端Python代码核心就这几行from rknnlite.api import RKNNLite rknn_lite RKNNLite() rknn_lite.load_rknn(facenet.rknn) rknn_lite.init_runtime() img load_and_preprocess(face.jpg) # 注意这里的预处理要与RKNN config匹配 emb rknn_lite.inference(inputs[img])[0]如果你在config里配置了mean_values和std_values这个img就要是原始0到255范围的RGB数组。如果你没配置那img必须是你自己处理成[-1,1]或模型期望分布的数据。推理结果出来之后记得和PC端模拟器输出再对比一次。这一步能确认板端NPU实际执行结果和模拟器一致。如果差别过大多半是驱动版本不匹配或者输入数据格式不一致。6.2 性能实测与优化手段我实测下来Facenet在RK3588 NPU上int8量化后单次推理大概在12到18毫秒左右加上人脸检测和前后处理整个识别流程跑到30到40毫秒一帧是没问题的。fp16模式下延迟会高一截大约20多毫秒但精度更稳。如果发现推理速度上不去先确认推理是否真的跑在了NPU上。RKNNLite默认会优先用NPU但如果模型里有不支持的算子它会回退到CPU速度瞬间掉一个量级。排查方式是看NPU的利用率用瑞芯微提供的性能分析工具或者简化模型确保算子全部被NPU接管。另一个被很多人忽略的性能因素是散热。RK3588满载跑NPU时发热相当可观如果散热片不够好芯片会主动降频推理延迟随之飙升。我调试的时候用了一个带PWM控制的散热风扇通过/dev/thermal-zone温度和PWM占空比联动把核心温度压到60摄氏度以下性能稳定很多。6.3 完整的人脸识别流程怎么搭建Facenet特征提取只是识别流程的一部分完整的流程还需要人脸检测和对齐。我建议板端用OpenCV读取视频帧人脸检测可以用一个轻量的检测模型比如RetinaFace的轻量版或者SCRFD转成RKNN后在NPU上跑检测检测出人脸bbox后裁剪出来缩放到160x160再送进Facenet提取特征。人脸比对的时候将库里的每个人脸向量放在内存里实时提取出向量后对全库做一次余弦相似度计算。如果人脸库不大比如几百人以内这种暴力搜索完全够用不需要引入向量数据库。线上性能好、代码简单是我推荐的起步方案。7. 常见问题与排查技巧实录这部分我把实际调试中遇到的高频问题整理成了表格每个问题都附上了解决办法。你如果遇到类似现象可以直接对照处理。现象可能原因解决办法RKNN模型在板端加载失败rknnlite版本与PC端rknn-toolkit2不匹配将两端版本对齐到同一版本号int8量化后识别率大幅下降量化数据集不具代表性或模型对量化敏感用实际场景图重新量化对敏感层做混合量化推理输出全为0或NaN输入预处理与模型训练时不一致检查是否设置了mean_values、std_values输入范围是否匹配推理速度很慢上百毫秒算子回退到CPU执行用工具分析算子执行情况排布不支持算子的层转换时提示算子不支持ONNX opset版本过高用opset 11或12重新导出或用onnx-simplifier简化板端推理结果与PC模拟器不一致驱动异常或输入数据格式不一致确认板端NPU驱动版本检查输入维度、数据类型7.1 量化精度下降怎么排查如果你遇到的正是这个最头疼的问题我建议按这个顺序查先拿一张图分别在PyTorch、ONNX Runtime、RKNN模拟器、板端推理四次跑拿到四个512维向量。两两算余弦相似度。如果PyTorch和ONNX Runtime已经对不上说明导出环节有问题。如果ONNX Runtime和RKNN模拟器对不上说明量化参数有问题。如果模拟器和板端对不上说明运行时环境有问题。这样一步定位不用瞎猜。7.2 模型没跑到NPU上怎么办RKNN执行时有一条规则只要模型里有一个算子CPU不支持整个图就不能完整跑在NPU上性能会断崖式下降。排查方法是先看模型里的算子列表再对照RKNN手册中支持的算子清单。对Facenet来说常见的坑集中在自定义的PReLU、某些版本的Flatten、以及在导出ONNX时自动生成的Reshape和Transpose。前面的onnx-simplifier步骤就能解决很大一部分。7.3 一个小技巧先用非量化模式跑通全流程我在整个项目里最大的心得就是分两步走。第一次转换不做量化用fp16或者fp32先跑通整个流程确定模型输出数值稳定、识别逻辑正确然后再回到量化环节做优化。很多人一上来就int8量化遇到精度问题就会同时面临“模型本身没转好”和“量化损伤了精度”两个问题非常难排查。先不量化把问题范围缩小一半后面的路会顺很多。再分享一个工具链使用习惯每次修改模型或转换参数后记得清理之前的中间文件和缓存。rknn-toolkit2有时候会因为旧的临时文件导致转换结果异常你以为是参数问题其实就是缓存脏了。8. 最后再说点实际体会整套流程走下来最大的感受是工具链的报错提示有时候很不友好但绝大多数问题本质上都出在“信息不对称”上——模型输入输出的shape、数值范围、归一化方式、算子和版本支持情况只要把这些信息理清楚大部分坑都能提前避掉。RK3588的NPU性能是够用的真正限制你的往往是工具链的这些细节。我自己习惯在项目里把模型转换和推理验证写成脚本每次改完模型一键跑通不做重复劳动。另外如果只是做原型验证可以先在PC端模拟器上调通再上板能省不少烧录和调试时间。希望这篇内容能让你在人脸识别部署路上少走几个弯有其他问题可以留言交流。