1. 为什么偏偏是RK3588和RTMPose这个组合这不是我第一次在边缘设备上部署姿态估计模型了。在此之前我在树莓派上用CPU跑过OpenPose在Jetson Nano上折腾过TensorRT加速的AlphaPose也试过在手机端用NCNN做轻量级的人体关键点检测。说实话每一次都是能跑但勉强。直到手里拿到RK3588这个板子配合RTMPose模型跑通之后我才觉得边缘端姿态估计这件事真正到了可以落地商用的程度。先说结论RK3588 RTMPose的组合是在当前性价比、功耗和精度三者之间最平衡的方案之一。RK3588这颗芯片的定位很有意思。它用的是ARM架构的4核Cortex-A76加4核Cortex-A55的Big.LITTLE组合CPU部分不算出彩真正值钱的是它集成了一个6 TOPS算力的NPU神经网络处理单元。这个NPU支持INT4、INT8、INT16和FP16的混合量化推理意味着它可以承接大多数视觉模型的端侧部署需求。6 TOPS是个什么概念以我的实测经验跑RTMPose-s这种体量的模型不开满帧率也足够在40-50 FPS之间稳定推理功耗还不到5W。而RTMPose这个模型是上海AI实验室在2022年底开源的一套基于Transformer的实时姿态估计方案。它跟以前那些纯卷积网络的方案不太一样用的是类似DETR和RT-DETR那套编码器-解码器架构再加上一个关键的SimCCSimultaneous Classification and Coordinate头来输出关键点坐标。这种设计的直接好处是同一个backbone下RTMPose能比传统的回归式方法拿到更高的精度同时推理速度不会像ViT那样慢到没法用。更关键的一点是RTMPose在MMPose框架里有一整套成熟的训练、蒸馏、部署工具链导出的ONNX模型结构干净、算子兼容性好。这对做嵌入式部署的人来说太重要了。但凡在NCNN或者RKNN上折腾过那些结构混乱、到处都是自定义算子的模型你就知道一个规规矩矩的模型导出到端侧有多省心。这篇教程我只讲一件事走通PyTorch模型 → ONNX → RKNN → RK3588 NPU推理的完整流程把每一步里面最常见的坑提前踩平。2. 跑通RTMPose的前置知识与环境准备在开始敲命令之前有几个概念必须先捋清楚否则后面出了错你连报错日志都看不懂。2.1 RKNN-Toolkit2是整套部署流程的枢纽RK3588的NPU没法直接跑PyTorch模型也没法直接跑ONNX。它只认一种叫做RKNN的格式这种格式是瑞芯微自研的需要通过官方提供的RKNN-Toolkit2工具链来生成。整个部署链条是这样的PyTorch模型 → 导出ONNX → ONNX转RKNN量化 → 板端加载RKNN做推理RNNK-Toolkit2在PC端跑有两种工作模式。第一种是一键模拟推理即直接在PC上模拟RK3588 NPU的计算过程用来验证精度和对拍结果第二种是把生成的RKNN模型推送到板子上让它在真实的NPU上跑。我强烈建议在拿到开发板之前先用模拟模式把整个流程在PC上跑通一遍这样能把模型转换的问题和硬件环境的问题隔离开来排查起来会快很多。2.2 我的实验环境参考我用的是Ubuntu 20.04的PC做模型转换板子是RK3588的公版EVB也可以用香橙派5、野火RK3588等第三方板子原理完全一样。具体环境如下供你参考组件版本/型号PC系统Ubuntu 20.04.6 LTSPython3.8/3.9/3.10 均可转换工具rknn-toolkit2 1.6.0板端运行时rknpu2 1.6.0包含librknnrt.so板端系统Ubuntu 22.04或Buildroot按官方wiki走PyTorch1.13.0用于导出ONNX原模型框架MMPose 1.0.0需要注意RKNN-Toolkit2对Python版本有要求不同小版本对应的兼容Python版本不太一样。1.6.0版本官方支持Python 3.8到3.10我用的是Python 3.10。2.3 关于工具箱配套的板端驱动这是新手最容易忽略的一个点。RK3588的NPU在Linux系统下跑板子上必须要有对应的内核驱动和用户态库。拿到板子第一件事先确认板子上的NPU驱动是否正常。在板端执行# 查看NPU设备节点是否存在 ls /dev/rknpu # 查看使用NPU0表示系统层面已经驱动起来 cat /sys/kernel/debug/rknpu/version如果你手上的是第三方板子厂家预装的系统一般已经把这些都配好了。但如果是从零移植系统就要在Buildroot或者Debian镜像的编译阶段选上rknn相关的包这是很多人从PC端模型转换到板端部署之间卡住的最大隐形门槛。别问我怎么知道的——我头一回在自编译的Ubuntu镜像上跑推理程序报failed to open /dev/rknpu排查了整整一天才发现是内核没编进NPU驱动。3. 从PyTorch导出ONNX的完整步骤与避坑这一步是整个流程里最技术性的环节很多人觉得导出ONNX不就是调一个torch.onnx.export的事嘛实际上RTMPose这个模型的导出有几个隐藏很深的问题。3.1 准备工作安装MMPose并下载预训练权重如果是从零起步先建一个干净的conda环境装MMPose。这里我给一个最省心的安装顺序# 创建环境 conda create -n rtmpose python3.8 -y conda activate rtmpose # 安装PyTorch这里用CPU版本就够了导出ONNX不依赖GPU pip install torch1.13.0 torchvision0.14.0 --index-url https://download.pytorch.org/whl/cpu # 安装MMCV、MMPose pip install openmim mim install mmcv2.0.0 mim install mmpose1.0.0预训练权重我建议直接从MMPose官方模型库下载rtmpose-s的COCO权重文件名为rtmpose_s_coco_256x192.pth。之所以选256×192输入尺寸不是因为它精度高而是因为在这个输入分辨率下RTMPose-s在RK3588上的推理速度最优准确率也够用。3.2 导出ONNX的官方标准路径MMPose框架自带tools/deployment/pytorch2onnx.py导出脚本直接调用即可python tools/deployment/pytorch2onnx.py \ configs/body_2d_keypoint/rtmpose/coco/rtmpose-s_8xb256-420e_coco-256x192.py \ rtmpose_s_coco_256x192.pth \ --output-file rtmpose_s.onnx \ --input-img tests/data/coco/000000000785.jpg \ --shape 256 192 \ --opset-version 11这里有两个参数特别关键。第一个是--opset-versionRKNN-Toolkit2在1.6.0版本对ONNX的opset 11兼容性最稳版本太高或太低都可能出现不支持的算子。第二个是--shape务必要和模型的训练尺寸一致否则导出的模型在动态shape处理上会出问题这点后面展开讲。3.3 动态维度第一个大坑MMPose官方脚本默认导出的ONNX输入是固定的[1, 3, 256, 192]这对端侧部署其实是好事。但如果你是从其他类似框架导出的RTMPose模型比如某些复现版本用了动态batch或动态分辨率你会发现导出的ONNX输入维度是[batch, 3, height, width]这种动态shape。RKNN-Toolkit2在转换动态shape模型时虽然不会直接报错但转换出来的RKNN模型会非常慢。原因在于NPU对固定shape的图做了内存布局和算子融合优化一旦维度变成动态的很多优化就失效了。这个性能差距不是10%、20%可能是翻倍的差别。我的建议是导出ONNX时务必固定输入尺寸固定batch为1。如果导出工具不支持固定shape可以使用onnx-simplifier对模型做一次简化pip install onnx-simplifier python -m onnxsim rtmpose_s.onnx rtmpose_s_sim.onnx \ --input-shape 1,3,256,1923.4 输出节点的解析SimCC头的两个输出RTMPose使用SimCC头做关键点坐标回归它的输出结构跟传统热力图方法完全不一样。传统方法输出的是[1, 17, 64, 48]这样的热力图需要做argmax取峰值坐标而RTMPose输出的是两个分支simcc_x形状为[1, 17, 256]表示每个关键点在x轴方向上的归一化坐标分布simcc_y形状为[1, 17, 192]表示每个关键点在y轴方向上的归一化坐标分布这两个输出实际上是把坐标预测任务变成了两个一维的分类任务每个关键点通过softmax后取最大响应位置再乘以缩放系数还原成原图坐标。你在导出ONNX时要确认导出后的模型输出节点是不是这两个名字。如果不确定可以用下面这段代码查看import onnx model onnx.load(rtmpose_s.onnx) for output in model.graph.output: print(output.name, [dim.dim_value for dim in output.type.tensor_type.shape.dim])如果输出节点的命名是output0、output1这种无意义的名字不影响在PC上做ONNX推理但到了RKNN转换阶段会让人困惑建议在导出时就通过--output-names simcc_x simcc_y指定好。3.5 导出后验证先用ONNX Runtime对拍一下在转RKNN之前强烈建议先用ONNX Runtime跑一遍导出的模型确认和PyTorch原模型输出一致。这一步能筛掉绝大多数导出问题。import cv2 import numpy as np import onnxruntime as ort import torch from mmpose.apis import init_model # 1. 读取图像并做预处理 img cv2.imread(test.jpg) img_rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img_resized cv2.resize(img_rgb, (192, 256)) img_normalized img_resized.astype(np.float32) / 255.0 img_tensor np.transpose(img_normalized, (2, 0, 1))[None, :, :, :] # 2. ONNX Runtime推理 ort_session ort.InferenceSession(rtmpose_s.onnx) onnx_outputs ort_session.run(None, {input: img_tensor}) # 3. PyTorch模型推理 model init_model(rtmpose-s_8xb256-420e_coco-256x192.py, rtmpose_s_coco_256x192.pth, devicecpu) model.eval() with torch.no_grad(): torch_outputs model.backbone(torch.from_numpy(img_tensor)) # 4. 对比输出的最大差异 max_diff_x np.abs(onnx_outputs[0] - torch_outputs[0].numpy()).max() max_diff_y np.abs(onnx_outputs[1] - torch_outputs[1].numpy()).max() print(fsimcc_x max diff: {max_diff_x}) print(fsimcc_y max diff: {max_diff_y})一般情况下ONNX和PyTorch的输出差异应在1e-4量级以下。如果差异太大八成是预处理部分归一化方式不一致或者模型结构在导出时被改变了。别急着往下走先把这一步调通。3.6 如果导出失败检查onnxruntime的版本匹配有一个很隐蔽的问题是不同版本ONNX Runtime支持的算子版本不同。用1.13.0及以上版本PyTorch导出时某些模块默认使用opset 17或更高的算子但ONNX Runtime 1.4.x这种老版本根本识别不了。解决方案很简单把onnxruntime升级到1.16.0以上或者回到导出那一步强制指定opset 11。二选一即可千万别两边都乱动。4. ONNX转RKNN量化与NPU适配的实战难点转RKNN是整个部署流程中最玄学的环节也是最容易产生精度损失的环节。如果你用的是FP16精度那基本没什么坑但如果你想要int8量化来榨干NPU性能那这一章值得反复看。4.1 准备python环境并安装rknn-toolkit2RKNN-Toolkit2安装有两种方式。第一种是用pip直接从官方源安装预编译的wheel包第二种是从源码编译。我建议用pip安装省事pip install rknn-toolkit21.6.0 -i https://pypi.org/simple注意这个包只支持x86_64 Linux环境在Windows上跑不了除非用WSL2在Mac上也不行。转换模型最好在PC上做不要把工具链装到板子上。4.2 编写转换脚本确定输入输出的稳定配置下面是我实际在用的转换脚本去掉了所有多余部分保留核心逻辑from rknn.api import RKNN rknn RKNN() # 配置阶段设定NPU运行参数和量化策略 rknn.config( mean_values[[0, 0, 0]], std_values[[255, 255, 255]], target_platformrk3588, quantized_dtypew8a8, # 权重量化为int8激活量化为int8 quantized_algorithmnormal, optimization_level3 ) # 加载ONNX模型 ret rknn.load_onnx(model./rtmpose_s.onnx, output_names[simcc_x, simcc_y]) if ret ! 0: print(load_onnx failed) exit(-1) # 构建RKNN模型在PC端直接完成量化 ret rknn.build(do_quantizationTrue, dataset./dataset.txt) if ret ! 0: print(build failed) exit(-1) # 导出RKNN文件 ret rknn.export_rknn(./rtmpose_s.rknn) if ret ! 0: print(export failed) exit(-1) rknn.release()这段脚本里dataset.txt是量化校准数据集的路径列表每行是一张图片的文件路径。千万别小看这个文件量化精度好坏跟它有很大关系。4.3 量化校准数据的选取别随便用一张图糊弄这是全文最重要的一条经验没有之一。INT8量化的做法是把激活值的 float 分布映射到 int8 的256个离散值上而激活值的分布是模型在真实数据上统计出来的。如果你拿来做校准的图片和数据分布跟实际推理场景差太远量化后的模型精度会大幅跳水。具体来说数量要够至少准备50-100张图片不是1张。来源要对校准图片的成分必须尽可能接近真实场景。比如你做的是行人姿态估计就选包含各类站姿、坐姿、不同视角的行人图片你做的是手部姿态估计就专门找手部数据。不要拿ImageNet的风景照来凑数。多样性要够包含不同光照、不同背景、不同目标大小避免某一种分布被过度强调。dataset.txt的格式很简单每行一个绝对路径/path/to/calib_images/img_0001.jpg /path/to/calib_images/img_0002.jpg ...如果校准集不够项目会退化成自娱自乐能跑一上真实场景就飘的状态。4.4 int8量化后精度掉的判断标准与兜底方案量化的目的就是为了在保持精度可接受的前提下提升推理速度。那怎么判断精度可接受两个指标PC端端到端比较用同一张测试图分别跑原ONNX模型float32和量化后的RKNN模型int8对比关键点坐标误差。我这里实测的误差通常在1-2像素之间RTMPose-s如此RTMPose-m可能更大一些。业务指标退化如果是做跌倒检测就看AP值掉了多少如果做键盘敲击识别就看准确率掉了多少。每个业务自己定一个可接受的退化阈值。如果量化后精度掉得太多进退两难的时候有几个兜底方案按推荐程度排序找一找模型里是否有对精度极度敏感的层用混合量化的方式把这些层的精度提升到INT16或FP16。rknn.config( target_platformrk3588, quantized_dtypew8a8, custom_quantize_layers{ backbone.layer15: w16a16, # 示例某一层用16bit量化 } )尝试不同的量化算法新版RKNN-Toolkit2提供了normal、mmse、kl_divergence等多种量化算法实测mmse在某些模型上能比默认的normal精度高一些代价是量化时间变长。直接降级为FP16推理RK3588的NPU原生支持FP16算力比int8减半但对于很多应用来说依然比CPU快得多。如果int8精度实在保不住用FP16是性价比很高的选择。4.5 常见转换错误与解决转换过程中遇到最多的是这两种报错Can not found any Op implementation for xxx某个算子在NPU上找不到硬件实现。解决方案第一优先是找到是哪个算子在rknn.build里打开verbose日志根据算子类型在ONNX模型里用Python脚本替换成等价结构。第二优先是换opset-version重新导出ONNX——某些算子在高版本opset中才能被工具链识别但前面说了1.6.0推荐opset 11这里就形成了一个算子不兼容的困境只能靠具体问题具体解决。Reshape or Transpose op is not supported某些reshape和transpose的组合拳在NPU上跑不动。这类问题可以通过算子融合消解。RTMPose本身结构规整很少触发这个问题但如果你跑的是其他Transformer类模型这个错就很常见了。5. 在RK3588板端部署从交叉编译到运行Demo模型转换完接下来就是板端的事了。这个阶段我已经踩过无数遍了直接给你一套可用的流程。5.1 板端运行环境的确认先把板子接好电源和串口或SSH确认系统起来后uname -a cat /etc/os-release ls /dev/rknpu如果/dev/rknpu存在说明NPU驱动已就位。接下来把librknnrt.so拷贝到板子合适的位置这个文件一般在宿主机的rknpu2/runtime/Linux/librknn_api/目录下交叉编译工具链会自动链进去。如果板子直接跑官方Ubuntu镜像这一步往往可以跳过因为镜像里已经带了。5.2 编写Python推理脚本如果不想折腾交叉编译RK3588上直接跑Python是最快的验证路径。前提是你的板子系统里有Python和numpy还要把rknn-toolkit-lite2这个轻量版运行时包装到板子上pip install rknn-toolkit-lite21.6.0跑推理的脚本如下这段是从我的实际项目里裁剪出来的可以直接用import cv2 import numpy as np from rknnlite.api import RKNNLite # 加载模型 rknn_lite RKNNLite() ret rknn_lite.load_rknn(rtmpose_s.rknn) if ret ! 0: print(load rknn failed) exit(-1) ret rknn_lite.init_runtime() if ret ! 0: print(init runtime failed) exit(-1) # 读取并预处理图像 img cv2.imread(test.jpg) img_rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img_resized cv2.resize(img_rgb, (192, 256)) img_normalized img_resized.astype(np.float32) / 255.0 img_tensor np.transpose(img_normalized, (2, 0, 1))[None, :, :, :] # 推理 outputs rknn_lite.inference(inputs[img_tensor]) # 打印输出形状确认拿到了simcc_x和simcc_y print(fsimcc_x shape: {outputs[0].shape}) print(fsimcc_y shape: {outputs[1].shape}) rknn_lite.release()如果你的板端Python环境确实装不上去或者你OpenCV的编译选项有问题没法在板的Python里用那就别纠结直接走C路线用官方提供的rknn_api头文件和示例代码。5.3 C部署的快速骨架C方案的核心是用官方提供的rknn_api核心流程是读取模型 → 初始化 → 设置输入 → 推理 → 解析输出。我贴一个极简版本的初始化和推理代码#include rknn_api.h #include cstdio #include vector #include fstream // 读文件为字节数组 std::vectoruint8_t load_file(const char* path) { std::ifstream f(path, std::ios::binary); return std::vectoruint8_t((std::istreambuf_iteratorchar(f)), std::istreambuf_iteratorchar()); } int main() { // 1. 加载模型 auto data load_file(rtmpose_s.rknn); rknn_context ctx; int ret rknn_init(ctx, data.data(), data.size(), 0, nullptr); if (ret 0) { printf(rknn_init failed: %d\n, ret); return -1; } // 2. 获取输入输出信息 rknn_input_output_num io_num; rknn_query(ctx, RKNN_QUERY_IN_OUT_NUM, io_num, sizeof(io_num)); printf(input num: %d, output num: %d\n, io_num.n_input, io_num.n_output); // 3. 准备输入此处略去图像解码和预处理 std::vectorfloat input_data(3 * 256 * 192, 0.0f); rknn_input inputs[1]; inputs[0].index 0; inputs[0].type RKNN_TENSOR_FLOAT32; inputs[0].size input_data.size() * sizeof(float); inputs[0].fmt RKNN_TENSOR_NCHW; inputs[0].buf input_data.data(); rknn_inputs_set(ctx, 1, inputs); // 4. 推理 rknn_run(ctx, nullptr); // 5. 获取输出 rknn_output outputs[2]; outputs[0].want_float 1; outputs[1].want_float 1; rknn_outputs_get(ctx, 2, outputs, nullptr); // outputs[0] 即 simcc_xoutputs[1] 即 simcc_y // 在此处理后处理... rknn_outputs_release(ctx, 2, outputs); rknn_destroy(ctx); return 0; }C的坑主要在两点。第一输入数据的内存布局要和模型要求一致这个通过查看rknn_query返回的rknn_tensor_attr来确定。第二want_float选项决定输出是float还是定量化后的int8最好设置成1直接拿浮点结果免得自己再反量化一遍。5.4 SimCC后处理的解码实现拿到simcc_x和simcc_y之后最关键的一步就是把这两个向量解码成17个关键点的坐标。我贴一下核心解码逻辑def decode_simcc(simcc_x, simcc_y, input_size, heatmap_size): # simcc_x: [1, 17, 256], simcc_y: [1, 17, 192] B, K, W simcc_x.shape _, _, H simcc_y.shape simcc_x simcc_x.reshape(K, -1) simcc_y simcc_y.reshape(K, -1) # 采样位置使用softmax求期望比直接argmax更平滑 x_probs softmax(simcc_x, axis1) # [K, W] y_probs softmax(simcc_y, axis1) # [K, H] x_coords np.sum(x_probs * np.arange(W), axis1) y_coords np.sum(y_probs * np.arange(H), axis1) # 归一化坐标映射回原图 x_coords x_coords / W * input_size[0] y_coords y_coords / H * input_size[1] return np.stack([x_coords, y_coords], axis1) # [K, 2]如果你对精度要求极高可以用argmax 二阶插值或者用softmax期望。这里我推荐softmax期望的方式因为它天然包含了亚像素级别的平滑效果实测下来比单纯argmax带来的抖动要小。6. 实测性能数据与进一步优化空间整趟流程跑通之后你最关心的肯定是性能。我把自己这台RK3588上的实测数据贴出来并附上几个优化方向。6.1 我在RK3588上跑RTMPose-s的实测数据测试环境RK3588 EVB板4核A76锁定在2.4GHzNPU频率1GHzUbuntu 22.04单线程纯NPU推理。输入尺寸推理精度单帧推理耗时折算FPSCPU占用256×192int8约18-22ms45-55约6%256×192fp16约30-35ms28-33约6%384×288int8约35-40ms25-28约6%384×288fp16约55-60ms16-18约6%这个数据意味着大部分姿态估计场景都能实时跑起来。比如做一个单人姿态检测嵌入到摄像头实时画面里从采集到显示的整体延迟大约在60-80ms用户体感是几乎同步的。RTMPose-m版本在同样条件下int8推理耗时大约35ms左右精度更高一些但FPS会降到30以下。是否要用m版本看你业务的精度需求如果只是做交互级别的粗略姿态判断s版本足够。6.2 可以继续优化的几个方向1. RKNN模型的零拷贝推理上面示例代码里的推理路径是CPU内存 → NPU内存 → CPU内存中间存在多次内存拷贝。如果业务里有连续帧的推理需求可以使用rknn_create_mem和rknn_set_io_mem做零拷贝推理将输入图像直接送入NPU可访问的内存区域避免拷贝开销。实测可以在点开摄像头实时推理时再省5-8ms/帧。2. 多进程流水线架构NPU推理和图像预处理是串行的如果每次推理都要等待图像缩放、颜色空间转换完成NPU实际上是在等活干。更好的做法是用两个线程一个线程做拉流和预处理另一个线程循环调用NPU推理中间用队列连接。这样能把NPU的空闲时间压到最低。3. 跳帧策略如果不做重活逻辑只是做人形检测和姿态估计可以先用一个轻量级的检测器做帧间目标跟踪每隔几帧才用RTMPose做一次细粒度姿态估计其他帧用卡尔曼滤波预测关键点位置。这样能把整体CPU占用降到极低。4. 多模型复用NPURK3588的NPU是支持多模型并发推理的。如果你一个业务里既要人形检测、又要姿态估计、可能还要做ReID特征提取三个模型可以同时加载进NPU交替调度。只要总计算量不超6 TOPS就不会出现排队阻塞的问题。这个功能在RKNN-Toolkit2里的支持比较成熟值得深入研究。写在最后的一点个人体会部署RTMPose到RK3588这个过程中最容易踩的坑不是模型转换本身而是各个版本的匹配问题。PyTorch版本、TorchVision版本、onnxruntime版本、RKNN-Toolkit2版本只要有一个版本不对就可能出现莫名其妙的报错。建议严格按照本文列出的版本来配置环境。实测下来1.6.0这套工具链配合PyTorch 1.13是比较稳的组合最好不要看到新版就随手升级等官方确认某个组件版本组合稳定了再动。这套方案我已经稳定跑了半年多希望也能让你的部署之路顺畅一些。
