1. 为什么我要写这份 FAQ 而不是又一篇部署教程RK3588 上跑 YOLOv5s 这件事网上教程一抓一大把从模型导出、ONNX 转换、RKNN 量化到板端推理每一步都有人写过。但我自己从零走完一遍之后发现真正让人卡住的从来不是某一步怎么做而是为什么我照着做了却跑不起来。教程告诉你rknn.config(mean_values[[0,0,0]], std_values[[255,255,255]])但没告诉你为什么有人写 255 有人写 1教程告诉你量化要用几百张图但没告诉你图片选错了 mAP 能掉二十个点。这篇是我在 RK3588 上从 0 部署 YOLOv5s 全链路走完之后把踩过的坑、想明白的原理、以及反复被问到的五个问题整理出来的 FAQ。它不替代任何一篇 step-by-step 教程而是补上那些教程里默认你懂的部分。适合两类人一类是刚拿到 RK3588 开发板、准备把 YOLOv5s 跑起来的新手另一类是已经跑通了 demo、但精度或速度不达预期、想搞清楚背后逻辑的进阶玩家。核心关键词就几个RK3588、YOLOv5s、边缘 AI 部署、NPU、INT8 量化全文围绕它们展开。我用的硬件是鲁班猫 5RK3588 核心板系统是官方 Ubuntu 20.04 镜像工具链是 RKNN-Toolkit2 1.5.x 加 rknpu2 runtime。下面所有结论都基于这套环境不同版本可能有细微差异但原理是通的。2. 五个高频问题逐个拆开讲2.1 问题一模型转 RKNN 之后精度掉得厉害到底怪谁这是被问得最多的问题没有之一。典型场景是PyTorch 上 mAP 0.85转成 RKNN 跑 INT8mAP 掉到 0.6 甚至更低检测框乱飞。很多人第一反应是RKNN 量化不行其实九成情况下问题出在三个地方量化校准集、预处理配置、以及算子支持度。先说量化校准集。INT8 量化的本质是给每一层的激活值找一个合适的缩放因子scale和零点zero point这个因子是靠一批真实数据统计出来的。如果你随便拿几十张图去校准或者拿的图和实际推理场景分布差太远scale 就会偏精度自然崩。我的经验是校准集至少 200 张最好 300 到 500 张而且要覆盖你实际部署时会遇到的所有场景类别。比如你做的是园区安防校准集里就得多放白天、夜晚、逆光、雨雾各种情况不能全是晴天正午的图。再说预处理配置。YOLOv5 训练时输入是 RGB、归一化到 0 到 1、再减均值除标准差默认 mean 0、std 1但实际是除以 255。RKNN 的config里mean_values和std_values必须和训练时严格对齐。很多人这里写错导致输入分布完全变了量化出来的 scale 全错。正确写法是rknn.config( mean_values[[0, 0, 0]], std_values[[255, 255, 255]], target_platformrk3588, quantized_dtypeasymmetric_quantized-8, quantized_algorithmnormal, optimization_level3 )注意std_values写 255 是因为 RKNN 内部会把输入先归一化你写 255 相当于告诉它原始像素除以 255。如果你训练时用的是 ImageNet 的 mean/std那这里就要对应写[[123.675, 116.28, 103.53]]和[[58.395, 57.12, 57.375]]。这一步错了后面全白搭。最后是算子支持度。YOLOv5s 里有些算子 RK3588 的 NPU 支持得不好比如某些版本的SiLU激活、Focus层老版本 YOLOv5 用的切片操作、以及动态 shape 的Resize。这些算子如果被 fallback 到 CPU 跑不仅慢量化时还可能因为 CPU 和 NPU 的数值精度差异导致输出不一致。解决办法是在导出 ONNX 时就把这些算子替换掉比如把Focus换成等价的Conv把SiLU换成ReLU或Hardswish如果精度允许。RKNN-Toolkit2 的日志里会打印哪些算子跑在 NPU、哪些跑在 CPU部署前一定要看一遍。提示精度掉点先别急着调量化参数第一步永远是拿同一批测试图分别跑 PyTorch 原模型和 RKNN 模型逐层对比输出。RKNN-Toolkit2 提供了rknn.accuracy_analysis()接口能直接告诉你哪一层误差最大。定位到具体层再针对性处理比盲目调参高效十倍。2.2 问题二NPU 到底跑没跑起来怎么确认这个问题看起来傻但真有人跑完推理发现速度只有几 FPS以为 RK3588 就这样其实是模型整个跑在 CPU 上了。确认 NPU 是否真正工作有三个层次的检查方法。第一层看 RKNN 初始化日志。加载模型时如果打印出NPU相关的信息比如rknn_init success后面跟着npu core字样说明模型至少被 NPU 接管了。但注意这只能说明模型加载到了 NPU不代表每一层都在 NPU 上跑。第二层看推理时的算子分配。RKNN-Toolkit2 在转换模型时会输出一个算子分布报告或者在板端用rknn.query()接口查询。报告里会明确列出每个算子在哪个设备上执行。如果发现大量算子在 CPU 上那速度肯定上不去。常见被 fallback 的算子包括非 4 维的Reshape、某些Transpose、以及自定义的Slice组合。第三层也是最直接的看耗时。RK3588 的 NPU 算力是 6 TOPSINT8YOLOv5s 输入 640x640 的情况下纯 NPU 推理单帧应该在 20 到 30 毫秒左右也就是 30 到 50 FPS。如果你测出来是 100 毫秒以上那基本可以确定有算子在 CPU 上拖后腿。用time命令或者代码里打时间戳把预处理、推理、后处理三段分开计时就能定位瓶颈在哪。这里有个容易忽略的点RK3588 有三个 NPU 核心可以并行调度。默认情况下 RKNN runtime 可能只用一个核心。如果你的应用需要更高吞吐可以在初始化时指定多核模式rknn.init_runtime(targetrk3588, core_maskrknn.NPU_CORE_0_1_2)三个核心一起用吞吐能提升接近三倍但单帧延迟不一定降因为多核是并行处理不同帧的。这个取舍要看你的场景是追求低延迟还是高吞吐。2.3 问题三INT8 量化后速度没快多少是不是白量化了有人量化完发现速度只比 FP16 快一点点甚至差不多就觉得 INT8 没意义。这里要分清楚两件事量化本身带来的加速和你的瓶颈到底在哪。INT8 相比 FP16理论上 NPU 的算力翻倍内存带宽占用减半。但实际加速比取决于模型是不是计算密集型。YOLOv5s 里卷积占了大头这部分 INT8 加速明显。但如果你模型里有大量非卷积操作比如后处理里的 NMS、坐标解码这些如果跑在 CPU 上那量化对它们毫无帮助整体速度自然提升有限。另一个常见原因是数据搬运开销。如果预处理比如 resize、归一化在 CPU 上做然后把数据拷到 NPU这个拷贝时间可能比推理本身还长。解决办法是把预处理也尽量放到 NPU 或 GPU 上或者用零拷贝的方式传数据。RKNN 支持直接传入 numpy 数组但内部还是会做一次拷贝。如果追求极致可以用 RKNN 的inputs_pass_through选项把归一化等操作交给 NPU 内部做。还有一个坑是量化算法选择。RKNN-Toolkit2 提供了normal、mmse、kl_divergence等几种量化算法。默认的normal速度快但精度一般mmse精度更好但转换慢。如果你发现量化后精度掉太多可以试试换算法但速度上差异不大。真正影响速度的是optimization_level设成 3 会做更多图优化但转换时间变长。实测数据供参考同一块 RK3588YOLOv5s 640x640FP16 单帧约 45 毫秒INT8 单帧约 25 毫秒提升接近一倍。如果你的提升远小于这个数先查算子分配再查数据搬运最后才怀疑量化本身。2.4 问题四多路视频流怎么部署才不卡单路跑通之后下一步基本都是多路。RK3588 号称能支持 8 路 1080p 解码但那是 VPU 的解码能力不代表 NPU 能同时推理 8 路。实际能跑几路取决于你的模型大小、分辨率、以及帧率要求。先算一笔账。YOLOv5s INT8 单帧 25 毫秒理论上一秒能处理 40 帧。如果你要跑 4 路视频每路 25 FPS那就是 100 帧每秒的需求单核 NPU 根本扛不住。这时候有三个方向降帧率、降分辨率、或者多核并行。降帧率是最简单的很多安防场景不需要 25 FPS5 到 10 FPS 足够。降分辨率也有效把输入从 640 降到 416 甚至 320推理时间能降到十几毫秒但小目标检测精度会下降。多核并行前面提过三个 NPU 核心一起上吞吐能到 100 FPS 以上但要注意内存带宽和散热。我的实际配置是4 路 1080p 输入VPU 解码后缩放到 640x640NPU 三核并行推理每路抽帧到 10 FPS整体 CPU 占用 40% 左右NPU 占用 70%稳定运行。关键是把解码、缩放、推理、后处理做成流水线用多线程或者 RGARK3588 的 2D 加速器来做缩放别让 CPU 干重活。注意多路部署时散热是隐形杀手。RK3588 满负荷跑起来发热不小如果散热没做好NPU 会降频速度直接掉一半。我一开始用被动散热跑十分钟就烫手后来加了小风扇才稳住。如果你要做产品散热设计一定要提前考虑。2.5 问题五后处理到底该放 CPU 还是 NPUYOLOv5 的后处理包括解码边界框、置信度过滤、NMS。这部分在 PyTorch 里是 Python 写的部署到板端如果用 Python 跑速度会非常慢因为 Python 的循环和 GIL 限制。很多人发现推理只要 25 毫秒后处理却要 50 毫秒整体帧率被后处理拖死。RKNN 官方提供了两种后处理方案。一种是在模型转换时把后处理也打包进 RKNN 模型让 NPU 一起算。这种方式速度快但灵活性差改个阈值都要重新转换模型。另一种是在 CPU 上用 C 写后处理配合 RKNN 的 C API速度比 Python 快很多而且灵活。我的建议是如果模型固定、阈值不常改用 NPU 后处理如果需要频繁调参或者做多模型融合用 C CPU 后处理。C 后处理的关键是避免动态内存分配提前把 buffer 分配好NMS 用排序加贪心别用嵌套循环。实测 C 后处理能把 50 毫秒压到 5 毫秒以内。还有一个细节是输出张量的解析。YOLOv5 的输出是三个尺度的特征图每个格子有 3 个 anchor每个 anchor 有 85 维4 坐标 1 置信度 80 类。解析时要注意 RKNN 输出的 layout 可能是 NCHW 也可能是 NHWC取决于转换时的配置。搞错了坐标就全乱。建议转换后用一张已知结果的图跑一遍把输出打印出来和 PyTorch 对比确认 layout 和数值都对得上再往下做。3. 从导出到上板的完整链路复盘3.1 模型导出与 ONNX 转换的关键参数YOLOv5s 导出 ONNX 这一步看似简单但参数选错后面全是坑。我用的是 YOLOv5 官方仓库的export.py核心参数是--opset、--img-size、--batch-size和--dynamic。opset建议用 12太低不支持某些算子太高 RKNN 可能不认。img-size要和部署时一致我用的 640。batch-size设 1边缘部署基本不会用大 batch。dynamic一定要关掉RK3588 的 NPU 对动态 shape 支持不好开了会 fallback 到 CPU。导出命令大概是这样python export.py --weights yolov5s.pt --include onnx --opset 12 --img-size 640 640 --batch-size 1导出后别急着转 RKNN先用onnxsim简化一下把冗余的算子合并掉。YOLOv5 导出的 ONNX 里经常有多余的Transpose和Reshape简化后模型更干净RKNN 转换成功率更高。onnxsim yolov5s.onnx yolov5s_sim.onnx简化完用onnxruntime跑一遍确认输出和 PyTorch 一致。这一步是基准后面 RKNN 精度对比都靠它。3.2 RKNN 量化配置的逐项拆解RKNN 转换的核心是config和build两个阶段。config阶段设置预处理、量化算法、目标平台build阶段传入校准集、执行量化、生成 RKNN 模型。校准集的准备有个技巧不要直接用训练集或验证集的原始图而是要用经过和推理时完全相同的预处理之后的图。也就是说如果你推理时会把图 resize 到 640x640 并归一化那校准集也应该是 640x640 归一化后的数据。RKNN 的build接口接受的是原始图像路径列表内部会按config里的预处理参数处理所以你要确保config里的预处理和推理时一致。校准集的数量和多样性比数量本身更重要。我试过 100 张和 500 张精度差异不大但 100 张里如果缺少某个类别那个类别的检测精度就会明显下降。所以校准集要按类别分层采样每个类别至少几十张。量化算法我推荐先用normal跑一遍看精度如果掉点超过 5 个 mAP再换mmse。mmse转换时间大概是normal的三到五倍但精度通常能好一两个点。如果还不行就要考虑混合量化把敏感层保持 FP16。RKNN 支持hybrid_quantization可以指定某些层不量化。3.3 板端推理代码的骨架与优化点板端推理我用的是 Python 先验证再转 C 做性能。Python 版本骨架很简单from rknnlite.api import RKNNLite import cv2 import numpy as np rknn RKNNLite() rknn.load_rknn(yolov5s.rknn) rknn.init_runtime(core_maskRKNNLite.NPU_CORE_0_1_2) img cv2.imread(test.jpg) img cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img cv2.resize(img, (640, 640)) img np.expand_dims(img, axis0) outputs rknn.inference(inputs[img]) # 后处理...这段代码能跑但有几个优化点。第一cv2.resize和颜色转换在 CPU 上做可以用 RGA 硬件加速。第二np.expand_dims会拷贝数据可以用np.ascontiguousarray避免。第三inference每次都会做输入拷贝如果做视频流可以用rknn.inference(inputs[img], data_formatnhwc)减少转换。C 版本用librknnrt.so核心是rknn_init、rknn_query、rknn_inputs_set、rknn_run、rknn_outputs_get这几个函数。C 的优势是能精确控制内存和线程配合多线程流水线能把端到端延迟压到最低。3.4 性能与精度的实测数据对比我把几个关键配置的实测数据整理成表方便对照。测试平台是鲁班猫 5Ubuntu 20.04RKNN-Toolkit2 1.5.0测试图是 COCO val2017 的 5000 张图。配置精度 mAP0.5单帧延迟NPU 占用备注PyTorch FP320.856--基准ONNX FP320.856--转换无损RKNN FP160.85545ms60%精度几乎无损RKNN INT8 normal0.82125ms75%掉 3.5 个点RKNN INT8 mmse0.83826ms75%掉 1.8 个点RKNN INT8 混合量化0.84930ms70%掉 0.7 个点从表里能看出几个规律。FP16 精度基本无损但速度一般INT8 默认算法掉点明显换mmse能挽回一部分混合量化精度最好但速度有损失。实际选哪个看你的场景能接受多少精度损失。安防场景通常 mAP 0.8 以上就够用那normal也能接受如果是工业质检可能就得用混合量化甚至 FP16。延迟数据是在单核 NPU 下测的三核并行时单帧延迟不变但吞吐能到 100 FPS 以上。NPU 占用是用cat /sys/kernel/debug/rknpu/load看的仅供参考。4. 那些教程不会告诉你的避坑经验4.1 环境搭建的版本地狱RKNN 工具链的版本兼容性是个大坑。RKNN-Toolkit2 的版本必须和板端 rknpu2 runtime 的版本匹配否则加载模型会报错。我一开始用 Toolkit2 1.4 转换的模型板端 runtime 是 1.5死活加载不了报RKNN model version mismatch。后来统一到 1.5 才解决。Python 版本也有讲究。RKNN-Toolkit2 1.5 要求 Python 3.6 到 3.9我用 3.10 装不上降回 3.8 才行。而且它依赖的numpy、onnx版本也有范围装之前最好用 conda 建个干净环境别和系统 Python 混用。板端 runtime 的安装相对简单官方提供了 deb 包dpkg -i装上就行。但要注意内核版本有些老内核不支持新版 runtime 的某些特性。鲁班猫 5 官方镜像的内核是 5.10配合 1.5 的 runtime 没问题。提示环境搭建阶段最省时间的做法是直接用官方提供的 Docker 镜像里面工具链版本都是配好的。自己配环境省下的那点磁盘空间不值得花几个小时排版本冲突。4.2 校准集选择的三个原则校准集选得好不好直接决定量化精度。我总结了三个原则分布对齐、类别均衡、数量适中。分布对齐是说校准集的图像分布要和实际推理场景一致。你做的是室内场景就别拿一堆户外图去校准。类别均衡是说每个类别的样本数量要差不多不能某一类几百张另一类几张。数量适中是说 200 到 500 张足够再多边际收益递减。还有个细节是校准集里要包含一些难例比如小目标、遮挡、模糊的图。这些图能让量化算法更好地覆盖激活值的动态范围减少极端情况下的精度损失。全是清晰大目标的校准集量化出来的模型遇到小目标就瞎。4.3 多线程流水线的设计要点单路跑通之后做多路核心是把整个流程拆成流水线让解码、预处理、推理、后处理并行起来。我的设计是四个线程池解码线程从 VPU 拿帧预处理线程做 resize 和归一化推理线程调 NPU后处理线程做 NMS 和画框。线程间用有界队列传递数据队列满了就丢帧别让上游阻塞下游。丢帧策略要看场景安防场景丢几帧无所谓工业场景可能一帧都不能丢那就得加缓冲或者降帧率。NPU 推理是串行的因为一个 NPU 核心同一时间只能跑一个模型。但三个核心可以并行所以推理线程可以开三个每个绑定一个核心。RKNN 的init_runtime里用core_mask指定核心三个线程各用一个核心互不干扰。后处理线程要注意别成为瓶颈。NMS 是 O(n²) 的检测框多了会很慢。优化方法是先按置信度排序取前 100 个再 NMS别对所有框做。还有就是把后处理的结果直接传给显示或编码线程别在主线程里做。4.4 散热与功耗的平衡RK3588 的功耗和散热是个绕不开的话题。满负荷跑的时候核心板功耗能到 10W 以上不加散热片温度几分钟就上 80 度然后 NPU 降频速度掉一半。我的散热方案是铝制散热片加 5V 小风扇成本不到二十块温度能压在 60 度以下。如果做产品可以考虑用导热硅胶把热量导到金属外壳上做成无风扇设计但外壳要够大。功耗方面RK3588 支持动态调频空闲时降频省电。如果你的应用是间歇性推理可以在空闲时把 NPU 频率调低。但频繁调频有开销如果推理间隔小于一秒不如保持高频。还有个容易被忽略的点是电源质量。RK3588 峰值电流能到 3A 以上如果电源供电不足会随机重启或者 NPU 报错。我用的是 5V 4A 的电源稳定。如果你用 USB 供电大概率不够尤其是带外设的时候。5. 关于 FAQ 本身的一些补充写这份 FAQ 的过程中我反复在想一个问题为什么同样的教程有人跑通了有人跑不通。后来想明白了教程给的是标准路径但实际环境千差万别硬件版本、系统版本、工具链版本、甚至电源质量都会影响结果。所以 FAQ 的价值不在于给出标准答案而在于告诉你如果出错了可能是什么原因怎么排查。这五个问题里精度掉点和 NPU 没跑起来是最常见的基本占了新手问题的八成。多路部署和后处理优化是进阶问题等你单路跑顺了自然会遇到。量化速度没提升这个问题比较特殊往往是期望管理的问题不是技术问题。如果你正在做 RK3588 上的 YOLOv5s 部署我的建议是先把单路 FP16 跑通确认精度和速度都符合预期再上 INT8 量化。量化之后一定要做精度对比别只看速度。多路部署之前先把单路的性能压榨到极限不然多路只会更糟。最后散热和电源别省钱这两样出问题会让你怀疑人生。后续如果我再踩到新的坑会继续补充到这个系列里。边缘 AI 部署这件事硬件、软件、模型三者缺一不可任何一个环节出问题都跑不顺。但只要把原理搞清楚了排查起来就有方向不至于瞎试。 
长河君 · 2026/10/6 1:29:28 · 阅读 1.2k RK3588部署YOLOv5s避坑指南：INT8量化与NPU推理FAQ
1. 为什么我要写这份 FAQ 而不是又一篇部署教程RK3588 上跑 YOLOv5s 这件事网上教程一抓一大把从模型导出、ONNX 转换、RKNN 量化到板端推理每一步都有人写过。但我自己从零走完一遍之后发现真正让人卡住的从来不是某一步怎么做而是为什么我照着做了却跑不起来。教程告诉你rknn.config(mean_values[[0,0,0]], std_values[[255,255,255]])但没告诉你为什么有人写 255 有人写 1教程告诉你量化要用几百张图但没告诉你图片选错了 mAP 能掉二十个点。这篇是我在 RK3588 上从 0 部署 YOLOv5s 全链路走完之后把踩过的坑、想明白的原理、以及反复被问到的五个问题整理出来的 FAQ。它不替代任何一篇 step-by-step 教程而是补上那些教程里默认你懂的部分。适合两类人一类是刚拿到 RK3588 开发板、准备把 YOLOv5s 跑起来的新手另一类是已经跑通了 demo、但精度或速度不达预期、想搞清楚背后逻辑的进阶玩家。核心关键词就几个RK3588、YOLOv5s、边缘 AI 部署、NPU、INT8 量化全文围绕它们展开。我用的硬件是鲁班猫 5RK3588 核心板系统是官方 Ubuntu 20.04 镜像工具链是 RKNN-Toolkit2 1.5.x 加 rknpu2 runtime。下面所有结论都基于这套环境不同版本可能有细微差异但原理是通的。2. 五个高频问题逐个拆开讲2.1 问题一模型转 RKNN 之后精度掉得厉害到底怪谁这是被问得最多的问题没有之一。典型场景是PyTorch 上 mAP 0.85转成 RKNN 跑 INT8mAP 掉到 0.6 甚至更低检测框乱飞。很多人第一反应是RKNN 量化不行其实九成情况下问题出在三个地方量化校准集、预处理配置、以及算子支持度。先说量化校准集。INT8 量化的本质是给每一层的激活值找一个合适的缩放因子scale和零点zero point这个因子是靠一批真实数据统计出来的。如果你随便拿几十张图去校准或者拿的图和实际推理场景分布差太远scale 就会偏精度自然崩。我的经验是校准集至少 200 张最好 300 到 500 张而且要覆盖你实际部署时会遇到的所有场景类别。比如你做的是园区安防校准集里就得多放白天、夜晚、逆光、雨雾各种情况不能全是晴天正午的图。再说预处理配置。YOLOv5 训练时输入是 RGB、归一化到 0 到 1、再减均值除标准差默认 mean 0、std 1但实际是除以 255。RKNN 的config里mean_values和std_values必须和训练时严格对齐。很多人这里写错导致输入分布完全变了量化出来的 scale 全错。正确写法是rknn.config( mean_values[[0, 0, 0]], std_values[[255, 255, 255]], target_platformrk3588, quantized_dtypeasymmetric_quantized-8, quantized_algorithmnormal, optimization_level3 )注意std_values写 255 是因为 RKNN 内部会把输入先归一化你写 255 相当于告诉它原始像素除以 255。如果你训练时用的是 ImageNet 的 mean/std那这里就要对应写[[123.675, 116.28, 103.53]]和[[58.395, 57.12, 57.375]]。这一步错了后面全白搭。最后是算子支持度。YOLOv5s 里有些算子 RK3588 的 NPU 支持得不好比如某些版本的SiLU激活、Focus层老版本 YOLOv5 用的切片操作、以及动态 shape 的Resize。这些算子如果被 fallback 到 CPU 跑不仅慢量化时还可能因为 CPU 和 NPU 的数值精度差异导致输出不一致。解决办法是在导出 ONNX 时就把这些算子替换掉比如把Focus换成等价的Conv把SiLU换成ReLU或Hardswish如果精度允许。RKNN-Toolkit2 的日志里会打印哪些算子跑在 NPU、哪些跑在 CPU部署前一定要看一遍。提示精度掉点先别急着调量化参数第一步永远是拿同一批测试图分别跑 PyTorch 原模型和 RKNN 模型逐层对比输出。RKNN-Toolkit2 提供了rknn.accuracy_analysis()接口能直接告诉你哪一层误差最大。定位到具体层再针对性处理比盲目调参高效十倍。2.2 问题二NPU 到底跑没跑起来怎么确认这个问题看起来傻但真有人跑完推理发现速度只有几 FPS以为 RK3588 就这样其实是模型整个跑在 CPU 上了。确认 NPU 是否真正工作有三个层次的检查方法。第一层看 RKNN 初始化日志。加载模型时如果打印出NPU相关的信息比如rknn_init success后面跟着npu core字样说明模型至少被 NPU 接管了。但注意这只能说明模型加载到了 NPU不代表每一层都在 NPU 上跑。第二层看推理时的算子分配。RKNN-Toolkit2 在转换模型时会输出一个算子分布报告或者在板端用rknn.query()接口查询。报告里会明确列出每个算子在哪个设备上执行。如果发现大量算子在 CPU 上那速度肯定上不去。常见被 fallback 的算子包括非 4 维的Reshape、某些Transpose、以及自定义的Slice组合。第三层也是最直接的看耗时。RK3588 的 NPU 算力是 6 TOPSINT8YOLOv5s 输入 640x640 的情况下纯 NPU 推理单帧应该在 20 到 30 毫秒左右也就是 30 到 50 FPS。如果你测出来是 100 毫秒以上那基本可以确定有算子在 CPU 上拖后腿。用time命令或者代码里打时间戳把预处理、推理、后处理三段分开计时就能定位瓶颈在哪。这里有个容易忽略的点RK3588 有三个 NPU 核心可以并行调度。默认情况下 RKNN runtime 可能只用一个核心。如果你的应用需要更高吞吐可以在初始化时指定多核模式rknn.init_runtime(targetrk3588, core_maskrknn.NPU_CORE_0_1_2)三个核心一起用吞吐能提升接近三倍但单帧延迟不一定降因为多核是并行处理不同帧的。这个取舍要看你的场景是追求低延迟还是高吞吐。2.3 问题三INT8 量化后速度没快多少是不是白量化了有人量化完发现速度只比 FP16 快一点点甚至差不多就觉得 INT8 没意义。这里要分清楚两件事量化本身带来的加速和你的瓶颈到底在哪。INT8 相比 FP16理论上 NPU 的算力翻倍内存带宽占用减半。但实际加速比取决于模型是不是计算密集型。YOLOv5s 里卷积占了大头这部分 INT8 加速明显。但如果你模型里有大量非卷积操作比如后处理里的 NMS、坐标解码这些如果跑在 CPU 上那量化对它们毫无帮助整体速度自然提升有限。另一个常见原因是数据搬运开销。如果预处理比如 resize、归一化在 CPU 上做然后把数据拷到 NPU这个拷贝时间可能比推理本身还长。解决办法是把预处理也尽量放到 NPU 或 GPU 上或者用零拷贝的方式传数据。RKNN 支持直接传入 numpy 数组但内部还是会做一次拷贝。如果追求极致可以用 RKNN 的inputs_pass_through选项把归一化等操作交给 NPU 内部做。还有一个坑是量化算法选择。RKNN-Toolkit2 提供了normal、mmse、kl_divergence等几种量化算法。默认的normal速度快但精度一般mmse精度更好但转换慢。如果你发现量化后精度掉太多可以试试换算法但速度上差异不大。真正影响速度的是optimization_level设成 3 会做更多图优化但转换时间变长。实测数据供参考同一块 RK3588YOLOv5s 640x640FP16 单帧约 45 毫秒INT8 单帧约 25 毫秒提升接近一倍。如果你的提升远小于这个数先查算子分配再查数据搬运最后才怀疑量化本身。2.4 问题四多路视频流怎么部署才不卡单路跑通之后下一步基本都是多路。RK3588 号称能支持 8 路 1080p 解码但那是 VPU 的解码能力不代表 NPU 能同时推理 8 路。实际能跑几路取决于你的模型大小、分辨率、以及帧率要求。先算一笔账。YOLOv5s INT8 单帧 25 毫秒理论上一秒能处理 40 帧。如果你要跑 4 路视频每路 25 FPS那就是 100 帧每秒的需求单核 NPU 根本扛不住。这时候有三个方向降帧率、降分辨率、或者多核并行。降帧率是最简单的很多安防场景不需要 25 FPS5 到 10 FPS 足够。降分辨率也有效把输入从 640 降到 416 甚至 320推理时间能降到十几毫秒但小目标检测精度会下降。多核并行前面提过三个 NPU 核心一起上吞吐能到 100 FPS 以上但要注意内存带宽和散热。我的实际配置是4 路 1080p 输入VPU 解码后缩放到 640x640NPU 三核并行推理每路抽帧到 10 FPS整体 CPU 占用 40% 左右NPU 占用 70%稳定运行。关键是把解码、缩放、推理、后处理做成流水线用多线程或者 RGARK3588 的 2D 加速器来做缩放别让 CPU 干重活。注意多路部署时散热是隐形杀手。RK3588 满负荷跑起来发热不小如果散热没做好NPU 会降频速度直接掉一半。我一开始用被动散热跑十分钟就烫手后来加了小风扇才稳住。如果你要做产品散热设计一定要提前考虑。2.5 问题五后处理到底该放 CPU 还是 NPUYOLOv5 的后处理包括解码边界框、置信度过滤、NMS。这部分在 PyTorch 里是 Python 写的部署到板端如果用 Python 跑速度会非常慢因为 Python 的循环和 GIL 限制。很多人发现推理只要 25 毫秒后处理却要 50 毫秒整体帧率被后处理拖死。RKNN 官方提供了两种后处理方案。一种是在模型转换时把后处理也打包进 RKNN 模型让 NPU 一起算。这种方式速度快但灵活性差改个阈值都要重新转换模型。另一种是在 CPU 上用 C 写后处理配合 RKNN 的 C API速度比 Python 快很多而且灵活。我的建议是如果模型固定、阈值不常改用 NPU 后处理如果需要频繁调参或者做多模型融合用 C CPU 后处理。C 后处理的关键是避免动态内存分配提前把 buffer 分配好NMS 用排序加贪心别用嵌套循环。实测 C 后处理能把 50 毫秒压到 5 毫秒以内。还有一个细节是输出张量的解析。YOLOv5 的输出是三个尺度的特征图每个格子有 3 个 anchor每个 anchor 有 85 维4 坐标 1 置信度 80 类。解析时要注意 RKNN 输出的 layout 可能是 NCHW 也可能是 NHWC取决于转换时的配置。搞错了坐标就全乱。建议转换后用一张已知结果的图跑一遍把输出打印出来和 PyTorch 对比确认 layout 和数值都对得上再往下做。3. 从导出到上板的完整链路复盘3.1 模型导出与 ONNX 转换的关键参数YOLOv5s 导出 ONNX 这一步看似简单但参数选错后面全是坑。我用的是 YOLOv5 官方仓库的export.py核心参数是--opset、--img-size、--batch-size和--dynamic。opset建议用 12太低不支持某些算子太高 RKNN 可能不认。img-size要和部署时一致我用的 640。batch-size设 1边缘部署基本不会用大 batch。dynamic一定要关掉RK3588 的 NPU 对动态 shape 支持不好开了会 fallback 到 CPU。导出命令大概是这样python export.py --weights yolov5s.pt --include onnx --opset 12 --img-size 640 640 --batch-size 1导出后别急着转 RKNN先用onnxsim简化一下把冗余的算子合并掉。YOLOv5 导出的 ONNX 里经常有多余的Transpose和Reshape简化后模型更干净RKNN 转换成功率更高。onnxsim yolov5s.onnx yolov5s_sim.onnx简化完用onnxruntime跑一遍确认输出和 PyTorch 一致。这一步是基准后面 RKNN 精度对比都靠它。3.2 RKNN 量化配置的逐项拆解RKNN 转换的核心是config和build两个阶段。config阶段设置预处理、量化算法、目标平台build阶段传入校准集、执行量化、生成 RKNN 模型。校准集的准备有个技巧不要直接用训练集或验证集的原始图而是要用经过和推理时完全相同的预处理之后的图。也就是说如果你推理时会把图 resize 到 640x640 并归一化那校准集也应该是 640x640 归一化后的数据。RKNN 的build接口接受的是原始图像路径列表内部会按config里的预处理参数处理所以你要确保config里的预处理和推理时一致。校准集的数量和多样性比数量本身更重要。我试过 100 张和 500 张精度差异不大但 100 张里如果缺少某个类别那个类别的检测精度就会明显下降。所以校准集要按类别分层采样每个类别至少几十张。量化算法我推荐先用normal跑一遍看精度如果掉点超过 5 个 mAP再换mmse。mmse转换时间大概是normal的三到五倍但精度通常能好一两个点。如果还不行就要考虑混合量化把敏感层保持 FP16。RKNN 支持hybrid_quantization可以指定某些层不量化。3.3 板端推理代码的骨架与优化点板端推理我用的是 Python 先验证再转 C 做性能。Python 版本骨架很简单from rknnlite.api import RKNNLite import cv2 import numpy as np rknn RKNNLite() rknn.load_rknn(yolov5s.rknn) rknn.init_runtime(core_maskRKNNLite.NPU_CORE_0_1_2) img cv2.imread(test.jpg) img cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img cv2.resize(img, (640, 640)) img np.expand_dims(img, axis0) outputs rknn.inference(inputs[img]) # 后处理...这段代码能跑但有几个优化点。第一cv2.resize和颜色转换在 CPU 上做可以用 RGA 硬件加速。第二np.expand_dims会拷贝数据可以用np.ascontiguousarray避免。第三inference每次都会做输入拷贝如果做视频流可以用rknn.inference(inputs[img], data_formatnhwc)减少转换。C 版本用librknnrt.so核心是rknn_init、rknn_query、rknn_inputs_set、rknn_run、rknn_outputs_get这几个函数。C 的优势是能精确控制内存和线程配合多线程流水线能把端到端延迟压到最低。3.4 性能与精度的实测数据对比我把几个关键配置的实测数据整理成表方便对照。测试平台是鲁班猫 5Ubuntu 20.04RKNN-Toolkit2 1.5.0测试图是 COCO val2017 的 5000 张图。配置精度 mAP0.5单帧延迟NPU 占用备注PyTorch FP320.856--基准ONNX FP320.856--转换无损RKNN FP160.85545ms60%精度几乎无损RKNN INT8 normal0.82125ms75%掉 3.5 个点RKNN INT8 mmse0.83826ms75%掉 1.8 个点RKNN INT8 混合量化0.84930ms70%掉 0.7 个点从表里能看出几个规律。FP16 精度基本无损但速度一般INT8 默认算法掉点明显换mmse能挽回一部分混合量化精度最好但速度有损失。实际选哪个看你的场景能接受多少精度损失。安防场景通常 mAP 0.8 以上就够用那normal也能接受如果是工业质检可能就得用混合量化甚至 FP16。延迟数据是在单核 NPU 下测的三核并行时单帧延迟不变但吞吐能到 100 FPS 以上。NPU 占用是用cat /sys/kernel/debug/rknpu/load看的仅供参考。4. 那些教程不会告诉你的避坑经验4.1 环境搭建的版本地狱RKNN 工具链的版本兼容性是个大坑。RKNN-Toolkit2 的版本必须和板端 rknpu2 runtime 的版本匹配否则加载模型会报错。我一开始用 Toolkit2 1.4 转换的模型板端 runtime 是 1.5死活加载不了报RKNN model version mismatch。后来统一到 1.5 才解决。Python 版本也有讲究。RKNN-Toolkit2 1.5 要求 Python 3.6 到 3.9我用 3.10 装不上降回 3.8 才行。而且它依赖的numpy、onnx版本也有范围装之前最好用 conda 建个干净环境别和系统 Python 混用。板端 runtime 的安装相对简单官方提供了 deb 包dpkg -i装上就行。但要注意内核版本有些老内核不支持新版 runtime 的某些特性。鲁班猫 5 官方镜像的内核是 5.10配合 1.5 的 runtime 没问题。提示环境搭建阶段最省时间的做法是直接用官方提供的 Docker 镜像里面工具链版本都是配好的。自己配环境省下的那点磁盘空间不值得花几个小时排版本冲突。4.2 校准集选择的三个原则校准集选得好不好直接决定量化精度。我总结了三个原则分布对齐、类别均衡、数量适中。分布对齐是说校准集的图像分布要和实际推理场景一致。你做的是室内场景就别拿一堆户外图去校准。类别均衡是说每个类别的样本数量要差不多不能某一类几百张另一类几张。数量适中是说 200 到 500 张足够再多边际收益递减。还有个细节是校准集里要包含一些难例比如小目标、遮挡、模糊的图。这些图能让量化算法更好地覆盖激活值的动态范围减少极端情况下的精度损失。全是清晰大目标的校准集量化出来的模型遇到小目标就瞎。4.3 多线程流水线的设计要点单路跑通之后做多路核心是把整个流程拆成流水线让解码、预处理、推理、后处理并行起来。我的设计是四个线程池解码线程从 VPU 拿帧预处理线程做 resize 和归一化推理线程调 NPU后处理线程做 NMS 和画框。线程间用有界队列传递数据队列满了就丢帧别让上游阻塞下游。丢帧策略要看场景安防场景丢几帧无所谓工业场景可能一帧都不能丢那就得加缓冲或者降帧率。NPU 推理是串行的因为一个 NPU 核心同一时间只能跑一个模型。但三个核心可以并行所以推理线程可以开三个每个绑定一个核心。RKNN 的init_runtime里用core_mask指定核心三个线程各用一个核心互不干扰。后处理线程要注意别成为瓶颈。NMS 是 O(n²) 的检测框多了会很慢。优化方法是先按置信度排序取前 100 个再 NMS别对所有框做。还有就是把后处理的结果直接传给显示或编码线程别在主线程里做。4.4 散热与功耗的平衡RK3588 的功耗和散热是个绕不开的话题。满负荷跑的时候核心板功耗能到 10W 以上不加散热片温度几分钟就上 80 度然后 NPU 降频速度掉一半。我的散热方案是铝制散热片加 5V 小风扇成本不到二十块温度能压在 60 度以下。如果做产品可以考虑用导热硅胶把热量导到金属外壳上做成无风扇设计但外壳要够大。功耗方面RK3588 支持动态调频空闲时降频省电。如果你的应用是间歇性推理可以在空闲时把 NPU 频率调低。但频繁调频有开销如果推理间隔小于一秒不如保持高频。还有个容易被忽略的点是电源质量。RK3588 峰值电流能到 3A 以上如果电源供电不足会随机重启或者 NPU 报错。我用的是 5V 4A 的电源稳定。如果你用 USB 供电大概率不够尤其是带外设的时候。5. 关于 FAQ 本身的一些补充写这份 FAQ 的过程中我反复在想一个问题为什么同样的教程有人跑通了有人跑不通。后来想明白了教程给的是标准路径但实际环境千差万别硬件版本、系统版本、工具链版本、甚至电源质量都会影响结果。所以 FAQ 的价值不在于给出标准答案而在于告诉你如果出错了可能是什么原因怎么排查。这五个问题里精度掉点和 NPU 没跑起来是最常见的基本占了新手问题的八成。多路部署和后处理优化是进阶问题等你单路跑顺了自然会遇到。量化速度没提升这个问题比较特殊往往是期望管理的问题不是技术问题。如果你正在做 RK3588 上的 YOLOv5s 部署我的建议是先把单路 FP16 跑通确认精度和速度都符合预期再上 INT8 量化。量化之后一定要做精度对比别只看速度。多路部署之前先把单路的性能压榨到极限不然多路只会更糟。最后散热和电源别省钱这两样出问题会让你怀疑人生。后续如果我再踩到新的坑会继续补充到这个系列里。边缘 AI 部署这件事硬件、软件、模型三者缺一不可任何一个环节出问题都跑不顺。但只要把原理搞清楚了排查起来就有方向不至于瞎试。