搞边缘AI的朋友应该都有同感：模型在GPU上精度再高，要挪到板子上跑起来，中间总要脱一层皮。我这次在RK3588上部署RTMPose，从拿到一个官方发布的.pth权重文件开始，到最后在NPU上把姿态估计跑通，整个过程涉及PyTorch权重导出ONNX、RKNN-Toolkit2转换量化、板端加载推理三段流程。中间踩的坑不少，尤其是RKNN转换和SimCC后处理这两块，网上资料零散，很多细节要自己试错才能摸清。这篇就把完整的转换流程和关键避坑点写出来，给准备在RK3588（或者同系列RKNN平台）上跑RTMPose的朋友一个参照。
先说结论：RTMPose模型从PTH转到RKNN，本身不算复杂，但想做到精度不掉、性能稳定，有几个关键环节必须卡死——ONNX导出时对head的处理、量化数据集的构造、板端NPU驱动与工具链的版本匹配，以及SimCC坐标解码的具体实现。下文按实际操作顺序逐段讲。
1. 为什么选RTMPose和RK3588这对组合
RTMPose是OpenMMLab旗下MMPose库推出的实时姿态估计模型，核心思路是把关键点坐标预测转化为SimCC（Simplified Coordinate Classification）形式的1D分类问题，而不是像传统方法那样直接回归坐标。这个设计带来的好处很明显：精度高，尤其在COCO数据集上的AP表现，t/s/m/l四个规格分别对应不同的算力预算，从几M到几十M参数量，灵活性很强。这对边缘设备来说非常友好，因为你可以按板子实际能承受的算力选一个规格，而不必硬上一个用不起的大模型。
RK3588这边，NPU算力6 TOPS，具备3个NPU核心，支持INT4/INT8/INT16混合量化。光看数字可能没概念，我实际测试下来，RTMPose-T在256x192输入下，经过INT8量化后单帧推理耗时能到10ms左右，RTMPose-M在相同输入下大概20ms上下，这个性能已经足够支撑实时的单人/多人姿态估计应用。相比之下，如果用CPU直接跑同样的模型，RTMPose-T也要上百毫秒，完全不是一个量级。NPU的算力冗余还允许你适当提高输入分辨率来换精度，这是实践中很有用的余地。
这对组合的落地场景也很明确：边缘盒子、健身镜、智能安防摄像头、康复训练设备。这些场景要求模型实时推理、功耗可控、成本敏感，正好是RK3588这类SoC的主场。如果你正在做上述任何一类产品，RTMPose+RK3588基本可以算是一个默认选项。
选型的时候有个点容易忽略：RTMPose的官方权重是跟着OpenMMLab那套训练代码走的，模型定义和权重文件是配套的。如果你想用MMPose之外的代码库重建模型再加载官方权重，等于是要自己保证网络结构完全对齐。实操中我建议直接用MMPose来加载和导出，省去大量对齐的麻烦。
2. 动手之前的准备：工具链选型和版本匹配
这一节先不急着写代码，把环境理清楚。RKNN转换这条链路涉及的工具和版本非常多，任何一个环节对不上，后面就能冒出奇奇怪怪的报错。
2.1 宿主机和板子的角色分配
我的方案是一台x86的Ubuntu机器或者Linux服务器作为转换环境，RK3588板子作为推理环境。转换环境负责PTH到ONNX、ONNX到RKNN的两步转换，板子只负责加载RKNN模型做推理。板子本身也可以装rknn-toolkit2做转换，但RK3588的CPU转模型速度太慢，一个模型在x86上30秒完成，板子上可能要几分钟到十几分钟，Debug效率极低。
板子系统方面，我用的是RK3588的Ubuntu固件（官方或者第三方适配的都可以），关键是要确认系统里NPU驱动是正常的。连接方式上，adb是最常用的手段，RK3588开发板的Type-C口连接电脑后，执行adb devices应该能看到设备。如果你拿到的是已经跑起来的Ubuntu板子，ssh进去也行，但adb在后期传文件、刷机、查日志时更方便，建议两个都准备好。
2.2 rknn-toolkit2官方仓库、版本选择
rknn-toolkit2是瑞芯微官方的模型转换工具，在GitHub有仓库，里面按release版本提供wheel包。安装方式就是pip install，但版本必须和板端运行的librknnrt（NPU运行时库）对应上。举例来说，如果转换环境装的是rknn-toolkit2 1.6.0，那么板端rknn-toolkit-lite2也应该装同源版本，否则可能出现模型加载失败或者算子执行错误。
这里有个特别容易踩的版本暗坑：板子的NPU驱动版本和librknnrt、rknn-toolkit2三者之间，有一个兼容矩阵。比如板子的固件里NPU驱动是较新的版本，但rknn-toolkit2是旧的，转换出来的模型可能在板端直接报错。遇到这种情况，最快的方式是去瑞芯微的官方文档（wiki）查一下当前工具链对应的固件和驱动要求，板子能升级就升级，不能升级就切换工具链版本。
2.3 关于pth和pt的澄清
转换流程的第一步是拿到PyTorch权重文件。网上讨论里常看到.pth和.pt两种后缀，甚至有说法是“pth是根据pt导出的”。这里顺带澄清一下：两者本质上没有区别，都只是PyTorch保存权重的文件后缀名，就像.jpg和.jpeg。MMPose官方输出的权重通常是.pth，而huggingface上有些仓库的出口文件是.pt，加载方式完全一致，不用额外纠结。
不过要留意的是，PyTorch权重有两种形态：一种是纯粹的状态字典（state_dict），另一种是整个模型序列化文件。RTMPose官方权重大多是state_dict形态，加载时需要有对应的模型定义代码。这也是为什么我反复强调用MMPose库加载——它会自动处理模型结构和权重的配对。
2.4 依赖安装清单
转换环境建议安装：
- Python 3.8/3.10（取决于rknn-toolkit2的wheel要求）
- torch，版本建议1.10~1.13
- mmpose、mmengine、mmcv（用于加载RTMPose权重）
- onnx、onnxruntime（用于检查和验证ONNX模型）
- rknn-toolkit2
板端推理环境建议安装：
- rknn-toolkit-lite2
- numpy、opencv-python
- 匹配的librknnrt（通常随固件或工具链附带的先安装）
3. PTH转ONNX：最容易翻车的一环
PTH到ONNX是整条链路的第一个分水岭。很多人以为torch.onnx.export三行代码就完事，但RTMPose这种带复杂head的模型，在这一步如果处理不细致，后面ONNX转RKNN会带着结构缺陷一路错下去。
3.1 使用MMPose官方接口导出
我的做法是直接利用MMPose自带的部署工具脚本。MMPose仓库里提供了deploy相关的导出配置，核心流程是：
- 下载rtmpose的config文件和预训练权重；
- 用mmpose API加载模型（包括backbone、neck、head）；
- 设置模型为eval模式；
- 构造一个dummy输入（图片张量），调用torch.onnx.export导出。
伪代码大致如下：
import torch from mmpose.apis import init_model config_file = 'rtmpose-t_8xb256-420e_coco-256x192.py' checkpoint_file = 'rtmpose-t_simcc-coco_pt-aic-coco_420e-256x192-2691dd5a_20230223.pth' model = init_model(config_file, checkpoint_file, device='cpu') model.eval() dummy_input = torch.randn(1, 3, 256, 192) torch.onnx.export( model, dummy_input, 'rtmpose_t.onnx', input_names=['input'], output_names=['simcc_x', 'simcc_y'], opset_version=11, do_constant_folding=True, )这里有几个关键点需要说明。
3.2 opset版本的选择
opset_version建议从11开始试。RTMPose的head里用到了softmax和矩阵乘法等算子，opset 11基本都能覆盖。如果你用更新的torch版本（比如2.0+），默认的opset可能已经是17，导出的ONNX会有一些较新算子，RKNN-Toolkit2不一定吃得消。所以稳妥起见，我建议在11到13之间选择，遇到算子不支持再往上调。
3.3 head输出如何处理
RTMPose的head是SimCCHead，最终输出两个分支：simcc_x和simcc_y。它们的形状分别是(B, K, W)和(B, K, H)，其中K是关键点数量（COCO是17），W和H是在1D分类的格子数。这个输出不是直接的坐标值，而是每个关键点在x方向和y方向上的类别分布（logits）。
导出时有两个选择：
- 方案A：完整导出整个模型，包括head，输出simcc_x和simcc_y，后处理（softmax求期望）放板端做。
- 方案B：只导出到backbone+neck，输出特征图，板端自己再接SimCC head。
我强烈建议方案A。原因很简单：板端用Python或者C++写SimCCHead非常容易出错，而且head计算量很小，放在NPU上跑反而省心。导出后你在板端只需要拿到simcc_x和simcc_y，再做softmax和期望解码，工作量小很多。
3.4 验证ONNX输出是否正确
导出完之后，千万别急着转RKNN。先用onnxruntime跑一遍ONNX模型，把输出和PyTorch模型的输出做数值对比。
import onnxruntime as ort import numpy as np ort_session = ort.InferenceSession('rtmpose_t.onnx') dummy_input = np.random.randn(1, 3, 256, 192).astype(np.float32) ort_outputs = ort_session.run(None, {'input': dummy_input}) # 和PyTorch输出对比，检查每个输出的shape和数值范围这一步能帮你提前发现head导出错位、算子丢失等问题。数值对比时不用要求完全一致，误差在1e-4量级内通常没问题。如果误差很大，优先检查dummy_input的归一化方式是否和模型训练时一致——RTMPose用的是ImageNet均值和方差归一化，这一点在后面的量化阶段还会再次出现。
3.5 dynamic_axes该不该设
很多人会在导出时把batch维度设成动态，方便以后一次推理多张图。但RKNN转换时，动态shape支持很有限，而且动态shape转换出来的模型在NPU上性能会打折扣。我的建议是固定batch=1，input_shape写成(1, 3, 256, 192)，以固定shape去导出。后面如果真要多路视频流，可以用多个线程跑多个rknn实例，而不是加大batch。
4. ONNX转RKNN：量化与算子兼容性的实战记录
ONNX文件到手，接下来就是重头戏：用rknn-toolkit2把它转成RKNN格式。这一步主要做三件事：加载ONNX、构建模型、量化并导出。量化是精度损失的主要来源，也是坑最多的地方。
4.1 基础转换代码
from rknn.api import RKNN rknn = RKNN() # 配置推理平台、输入输出预处理参数 rknn.config( mean_values=[[123.675, 116.28, 103.53]], std_values=[[58.395, 57.12, 57.375]], target_platform='rk3588' ) # 加载ONNX模型 ret = rknn.load_onnx(model='rtmpose_t.onnx') if ret != 0: print('load onnx failed') exit(-1) # 构建RKNN模型，do_quantization决定是否做INT8量化 ret = rknn.build(do_quantization=True, dataset='dataset.txt') if ret != 0: print('build failed') exit(-1) # 导出RKNN文件 ret = rknn.export_rknn('rtmpose_t.rknn') if ret != 0: print('export failed') exit(-1)这段代码看着简单，但每个参数背后都有讲究。
4.2 预处理参数的准确性
mean_values和std_values必须和训练时一致。RTMPose在COCO数据集上的标准预处理是BGR格式，mean=(123.675, 116.28, 103.53)，std=(58.395, 57.12, 57.375)。这里有个经典错误：在config里写mean/std时，顺序是按RGB还是BGR？RKNN-Toolkit2默认认为输入是RGB还是BGR，和你load进模型的数据格式有关。我建议在config里就统一设定，然后在代码注释里写清楚，避免两个环节各想各的。
还有一个细节点：如果你在板端用opencv读图（默认BGR），rknn.inference的输入图像就不用再转RGB，因为config里按BGR处理。如果你是自己用PIL读图（默认RGB），那入参前要把格式统一，否则颜色通道错乱，姿态估计结果会混乱。
4.3 量化数据集dataset.txt的正确构造
do_quantization=True时，需要提供一个dataset.txt文件，每一行是用于校准的图片绝对路径。这些图片不要求有标注，但内容的分布要能代表真实使用场景。
我的经验是：
- 图片数量至少20张，推荐50到200张；
- 图片内容和实际推理场景越接近越好，比如你是做健身场景，就多找些人做运动姿态的图片；
- 图片分辨率不需要和模型输入一致，rknn会内部resize，但尽量用比较正常的图像。
如果你随便拿几张噪声图或者风格完全不一致的图去量化，模型的激活值统计会偏移，导致量化后精度崩掉。量化校准的本质是用一组图片摸清每层激活值的分布范围，然后在这个范围内做INT8映射，所以校准数据越有代表性，量化误差越小。
4.4 量化后精度下降的排查
INT8量化多少会掉点，RTMPose这样的大模型一般掉1-2个AP点或坐标平均误差加大，属于正常。但如果掉得离谱，比如关键点乱跳，就要排查：
第一步，对比ONNX在onnxruntime下（FP32）的输出和RKNN在模拟器下的输出（不开量化、仅验证推理）。分别跑同一张图片，观察输出差异。如果FP32 RKNN输出也和ONNX不一致，那是模型转换或者预处理的问题，和量化无关。
第二步，确认量化配置。rknn.config里的quantized_dtype默认是'asymmetric_quantized-8'，如果你用的是某些特殊算子，可以尝试设置quantized_algorithm='normal'或'min_max'，不同算法对某些网络效果有别。
第三步，如果还不行，考虑混合量化。rknn.config里可以设置指定某些层不做量化，保留FP16或INT16精度。RTMPose的head输出层对坐标精度比较敏感，我实际测试中，把head层（输出simcc_x、simcc_y之前的卷积层）设置为不量化，能够明显改善关键点抖动的问题。
rknn.config( mean_values=[[123.675, 116.28, 103.53]], std_values=[[58.395, 57.12, 57.375]], target_platform='rk3588', quantized_dtype='asymmetric_quantized-8', quantized_algorithm='normal', custom_quantize_layers=[ # 按你的模型层名填写，或者使用default pattern ] )注意，mixed precision的设置在老版本rknn-toolkit2里的写法可能不一样，建议先查官方文档对应版本。
4.5 常见的算子不兼容报错
RKNN-Toolkit2对ONNX算子的支持已经比较全面，但仍有几个坑：
- 某些版本的PyTorch导出的Resize算子（比如upsample）格式和RKNN预期不一致，报错时会提示“Resize mode not supported”之类。解决办法是检查ONNX里的Resize节点，必要时在PyTorch里把upsample方式改成nearest或bilinear的特定配置，或者用onnx-simplifier处理一下。
- 某些版本的PyTorch导出的LayerNorm或者softmax维度处理，在RKNN里可能报错。RTMPose整体上算子种类比较常规，遇到这种问题概率不大，但如果真的遇到，优先检查onnx版本和算子集。
建议在转换前先用onnx-simplifier整理一下ONNX图，去掉冗余节点、合并算子，能显著降低后续RKNN解析出问题的概率。
5. 板端部署：从adb连板到拿到可视化结果
RKNN模型文件生成之后，任务就变成板端部署了。这里涉及板子连接、运行环境配置、推理代码编写、SimCC后处理解码，以及最终可视化。
5.1 板子状态确认
先把板子连上。Type-C连USB到电脑，两侧都通电后执行：
adb devices如果设备列表里能看到rk3588设备，说明adb正常。接着通过adb shell进板子，检查NPU状态：
adb shell cat /sys/kernel/debug/rknpu/version能读到NPU驱动版本号，说明NPU驱动工作正常。如果没有这个文件，可能是debugfs没有挂载，尝试：
mount -t debugfs none /sys/kernel/debug另外也建议用这个命令看一下板子剩余内存和CPU占用，后面跑推理时对比性能会用到。
5.2 安装rknn-toolkit-lite2
板端推理用的是rknn-toolkit-lite2，它只负责模型加载和推理，不能做模型转换，但体积小、官网提供适配ARM平台的wheel。安装命令：
pip install rknn-toolkit-lite2安装完后可以验证一下版本：
from rknnlite.api import RKNNLite如果你拿到的是源码包，也可以直接从源码导入路径，效果一样。但要注意librknnrt的版本，rknn-toolkit-lite2会自带一个runtime库，和系统里的驱动是否匹配要测试才知道，报错就去看库版本和驱动版本的兼容性。
5.3 推理代码
板端推理Python代码大致如下：
from rknnlite.api import RKNNLite import cv2 import numpy as np rknn_lite = RKNNLite() ret = rknn_lite.load_rknn('rtmpose_t.rknn') if ret != 0: print('load rknn failed') exit(-1) ret = rknn_lite.init_runtime() if ret != 0: print('init runtime failed') exit(-1) # 读取图片，resize到256x192 img = cv2.imread('test.jpg') img = cv2.resize(img, (192, 256)) # 输入图像格式和转换时的预处理配置保持一致 img = img.astype(np.float32) # inference输入要求(batch, height, width, channel)，注意RKNN是NHWC布局 img_input = np.expand_dims(img, axis=0) outputs = rknn_lite.inference(inputs=[img_input]) # outputs包含simcc_x和simcc_y两个分支 simcc_x, simcc_y = outputs这里有两个重要的细节。
第一，RKNN的输入布局是NHWC，不是PyTorch常用的NCHW。虽然rknn-toolkit2在config里有参数可以适配NCHW，但默认情况和硬件底层更贴近的是NHWC，提前统一比较好。如果你在转换时用的是NCHW，板端输入也保持一致，不会报错，但可能存在性能损耗，建议直接按NHWC来。
第二，预处理。如果你在rknn.config里设置了mean/std，那么rknn_lite.inference内部会自动做减均值除方差的归一化，你只需要把图像数据转成float32。如果你没有设置mean/std，就需要自己在代码里手动归一化。
5.4 SimCC后处理——真正的核心逻辑
拿到simcc_x和simcc_y，还远不是关键点坐标。RTMPose的head输出的是每个关键点在x和y方向上的分布（logits），要解码成坐标才能用。
SimCC的解码流程：
- 对simcc_x和simcc_y分别做softmax；
- 计算每个分布的概率加权期望位置（也可以先取最大响应再加权，但期望值更稳）；
- 将期望位置乘以缩放因子，得到原始图像坐标；
以RTMPose的256x192输入为例，head输出的simcc_x形状是(B, 17, 192)（宽度方向网格数等于输入宽度除以下采样倍数，RTMPose的head下采样通常是1倍，这里网格数直接就是宽高尺寸的一半相关，具体看config），simcc_y形状是(B, 17, 256)。解码后每个关键点的坐标需要乘以下采样倍数，再除以模型输入尺寸，映射到原图比例。
实操代码参考：
def simcc_decoding(simcc_x, simcc_y, input_size=(256, 192)): B, K, W = simcc_x.shape _, _, H = simcc_y.shape # softmax simcc_x = np.exp(simcc_x - np.max(simcc_x, axis=-1, keepdims=True)) simcc_x /= np.sum(simcc_x, axis=-1, keepdims=True) simcc_y = np.exp(simcc_y - np.max(simcc_y, axis=-1, keepdims=True)) simcc_y /= np.sum(simcc_y, axis=-1, keepdims=True) # 期望位置 x_coords = np.sum(simcc_x * np.arange(W), axis=-1) y_coords = np.sum(simcc_y * np.arange(H), axis=-1) # 映射到输入尺寸比例 x_coords = x_coords / W * input_size[1] y_coords = y_coords / H * input_size[0] return np.stack([x_coords, y_coords], axis=-1) # (B, K, 2)注意，实际的缩放因子和网络结构有关。RTMPose的simcc_x的W通常是192（等于输入宽度），simcc_y的H是256（等于输入高度），也就是说head的输出网格直接对齐输入分辨率。如果你的config里有下采样倍数参数，你需要把坐标乘以下采样倍数。这一点务必在导出ONNX之前从config里确认清楚，否则后处理出来的坐标会整体偏离。
解码完成的关键点坐标，是基于模型输入尺寸的（256x192），如果你要画到原图上，还需要把坐标按原图尺寸和输入尺寸的比例再做一次缩放。画图时用cv2.circle逐点画就行，这里就不赘述了。
5.5 板端常见运行错误
部署阶段最常见的两个报错：
一是RuntimeError: load rknn failed。大概率是模型文件和rknn-toolkit-lite2版本不兼容，或者模型被损坏。先检查rknn文件是否在转换机上可以正常load（用rknn-toolkit2的load_rknn测试），再把文件重新push到板子。
二是推理返回全零或KeyError。这个一般是后处理时outputs的索引顺序弄错。rtmpose_t.rknn的输出列表顺序是[simcc_x, simcc_y]，但如果你改过模型导出配置，顺序可能变。建议在板端先打印outputs里每个数组的shape，确认哪个是x方向的分布，哪个是y方向的。
6. 踩坑复盘与性能优化建议
最后这部分是实际操作中积累的经验总结，也是我认为这篇最有价值的部分。
6.1 坐标抖动问题
第一次在板子上跑通RTMPose，我遇到最明显的现象是：单人姿态大体正常，但手腕、脚踝这些相对小区域的关键点在连续帧里抖得很厉害。一开始以为是因为量化导致精度下降，后来排查发现主要还是和三个因素有关：
- 输入图像质量：摄像头画面如果过暗或过噪，RTMPose本身检出的关键点就不稳，量化只是放大了误差；
- 量化设置：把head层保留为更高精度后，抖动明显减弱；
- 输入尺寸固定：用256x192，对小人（远处的人）本身就不够，关键点定位自然差一些。如果需要检测的量小目标，建议适当提高输入分辨率，比如384x288。
6.2 不要盲目上混合量化
混合量化虽然能提升精度，但并非全部层都保留高精度就一定更好。RK3588的NPU对INT8算力是最强的，如果大量层用FP16，推理速度会明显下降。我的实践经验是：先测默认INT8量化后的精度和性能，如果精度可接受，就不要加混合量化；如果精度崩了，优先怀疑预处理和量化数据集，而不是一上来就混合量化。RTMPose的head输出层是精度敏感层，单独把最后几层调成INT16或FP16，性价比最高。
6.3 多路或多线程推理的方法
RK3588的NPU支持多实例推理。如果你要跑两路视频流做姿态估计，不需要在一个rknn实例里做batch，而是可以创建两个RKNNLite实例，分别加载同一个rknn模型文件，绑定到不同的核上运行。实测在RTMPose-T模型下，两个实例并行推理，单帧耗时略有增加但吞吐量几乎翻倍。代码上就是：
rknn1 = RKNNLite() rknn1.load_rknn('rtmpose_t.rknn') rknn1.init_runtime(core_mask=RKNNLite.NPU_CORE_0) rknn2 = RKNNLite() rknn2.load_rknn('rtmpose_t.rknn') rknn2.init_runtime(core_mask=RKNNLite.NPU_CORE_1)RKNNLite支持NPU_CORE_0、NPU_CORE_1、NPU_CORE_2和全核共用的core_mask配置，多路场景按需分配即可。
6.4 图像硬件加速
如果你做的是视频流实时推理，输入图像缩放、格式转换这些操作如果都在CPU上做，会浪费不少算力。RK3588硬件上带RGA（2D图形加速单元），可以零拷贝做resize和格式转换。比如用rga把1920x1080的原图缩放到256x192，耗时几乎可以忽略。具体可以用Rockchip的rga库或者librga，虽然API文档有点简陋，但功能确实强大，值得花时间接入。摄像头采集方面，RK3588的MPP模块负责视频硬解码，接入USB摄像头或者mipi摄像头后，可以直接用硬件编码模块把输入帧转为模型需要的格式，全程CPU占用很低。
6.5 热词里提到的几个话题
搜索热词里还有几个相关的点，比如“rk3588部署yolov8”“yolo26转rknn”“dinov3转rknn”，其实转换流程和本文描述的基本一致：PTH导出ONNX，RKNN-Toolkit2加载并量化，板端用RKNNLite推理。唯一的区别是模型的head和后处理完全不同——yolo系列需要anchor解码和NMS，RTMPose需要SimCC解码。但工具链的使用方法、版本匹配规则、量化数据集的构造思路，是完全通用的。你只要把本文学到的这套方法迁移过去，yolo的RKNN转换也能很快跑通。
最后再说两个小技巧。第一，在转换机上对比RKNN模拟器的输出和板端输出，如果两者不一致，优先怀疑librknnrt和rknn-toolkit-lite2的版本匹配。第二，板端部署的Python代码里，建议把rknn的推理循环写成一个独立线程，用队列传送图像帧，避免摄像头帧率波动导致推理线程被阻塞，实测这个架构调整对整体流畅度提升非常明显。
RK3588 + RTMPose这套组合，从工具链角度已经相当成熟了，只要版本对齐、预处理一致、后处理按SimCC的路子走，基本不会遇到颠覆性的难题。希望这篇实战记录能帮你在转换流程上少走弯路，把精力花在真正影响产品的算法调优和业务逻辑上。
