板子到手那天，我没有急着跑 YOLOv8。先把屏幕点亮，是多年踩坑换来的肌肉记忆：RK3588 这类 SoC 上，显示链路一旦有问题，后面所有推理画面的可视化都会变成盲调——模型跑通了、日志说检测到人了，屏幕却是黑的，你根本无法判断是推理错了还是显示没通。这套“LCD 显示 + OpenCV + YOLOv8 的 NPU 部署”链条，本质上不是三个独立任务，而是一条从头到尾的数据流水线：摄像头或图像进、像素格式转换、模型推理、坐标还原、再到屏幕上画框。链条上任何一环用了软解软转，整条流水线的帧率就会被那一环拖死。
这篇内容面向的是手里已经有 RK3588 板子、想正经做视觉项目的人：可能是刚接触嵌入式 AI 的学生，也可能是从 PC 端 PyTorch 转过来、第一次碰交叉编译和量化部署的工程师。我会按真实的推进顺序展开——先讲整体方案怎么选、为什么这么选，再一步步说 LCD 点屏、OpenCV 带硬件加速的编译、YOLOv8 转 RKNN 的量化细节、板端零拷贝流水线的写法，最后给出性能实测和问题速查。所有代码片段都可以直接改改就用，参数我给的是我自己验证过的范围，不是文档抄来的默认值。
1. 整体方案设计与选型拆解
在动手敲命令之前，先把整条链路拆成四段看清楚：显示输出段、图像采集与预处理段、推理段、后处理与回显段。每一段在 RK3588 上都有硬件加速通道和软件兜底通道两条路，选错的代价是 3 到 10 倍的性能差。很多人最后的帧率只有 8 FPS，问题往往不在 NPU，而在于预处理用 CPU 做了 resize 和颜色空间转换。
1.1 整条流水线的数据流与硬件对应关系
RK3588 的硬件模块和软件接口大致是这样对应的：摄像头走 MIPI CSI 进 ISP，ISP 由 rkaiq 这套 3A 库驱动；图像缩放、格式转换、旋转、裁剪交给 RGA（2D 图形加速器）；推理交给 NPU，官方运行时是 librknnrt，量化转换工具是 rknn-toolkit2；显示走 VOP 再到 MIPI-DSI 或 HDMI，用户态接口是 DRM。CPU 那 4 个 A76 加 4 个 A55，在理想设计里只负责调度、后处理和画框。
所以一条“正确的”流水线应该是：VI 采集 → RGA 缩放到 640×640 并转 RGB → NPU 推理 → CPU 做解码和非极大值抑制 → RGA 把原始帧缩放到屏幕分辨率 → DRM 上屏并叠加检测框。注意 RGA 出现了两次，这不浪费，因为它是独立硬件，和 NPU、CPU 并行工作，反而是把三者的时间重叠起来的关键。
我在第一版里偷懒，用cv::resize做预处理，1080p 转 640×640 单帧就要 6 到 8 毫秒，加上cvtColor又是 3 毫秒，一秒钟三十帧的话 CPU 光预处理就吃掉 300 毫秒的预算。换成 RGA 之后这部分降到 1 毫秒以内，而且不占 CPU。这个差距在 30 FPS 目标下是决定性的。
1.2 为什么绕开“模型直接吃原始分辨率”的思路
有人会想，既然要 resize 有开销，那干脆训练和导出都用 1080p 输入，让模型自己处理。这条路在 RK3588 上不划算，原因有两个。第一是 NPU 的算力账：6 TOPS 是 INT8 的理论峰值，卷积计算量随输入面积线性增长，640 到 1080 是接近 3 倍面积，YOLOv8n 从 20 多毫秒直接变成 60 毫秒以上，帧率掉到 15 以下。第二是内存带宽账，特征图占用翻三倍，在 LPDDR 上很容易触发带宽瓶颈，实际表现比算力估算还差。
所以业界通用做法是：模型输入固定小分辨率，把“看得清”这件事交给采集端的光学变焦或者ROI 裁剪。如果你确实需要检测远处小目标，正确姿势是用高分辨率原图做滑窗切片推理，或者用两个模型分工，而不是把主干网络的输入撑大。我在一个需要检测 20 米外目标的场景里试过 960×960 输入，单帧 45 毫秒，最后还是退回了 640 加切片，因为 640 切片的总吞吐更高。
1.3 软件栈版本的“对齐”比“最新”重要
这套生态里最容易翻车的地方不是技术难点，而是版本。rknn-toolkit2 的转换端和板端的 librknnrt.so 必须版本匹配，模型文件里会写入 toolkit 版本号，运行时版本低于它就直接报invalid model或者初始化失败。我吃过一次亏：PC 上装了 2.x 版本转换，板子镜像里的运行库还是 1.5.x，排查了两个小时以为是量化参数问题。
我的做法是在项目根目录放一个versions.txt，把四个东西钉死：kernel 与镜像日期、librknnrt.so 版本（strings /usr/lib/librknnrt.so | grep -i rknn可见）、rknn-toolkit2 版本、OpenCV 版本。每次换环境先对一遍这张表，比任何调试技巧都省时间。另外，Python 端的 toolkit 建议用虚拟环境隔离，它依赖的 numpy、onnx 版本比较挑剔，装在全局环境里迟早会跟别的项目打架。
2. LCD 点亮：从设备树到上屏的第一帧
显示这一段的价值不只是“能看到画面”。它是你验证整块板子系统是否正常的探针：时钟树、电源域、设备树、驱动加载，任何一个环节错，屏幕就是黑的或者花屏。而且显示调通之后，你就有了一个可靠的可视化调试窗口，后面推理出问题能一眼看出是坐标错了还是根本没检测到。
2.1 先确认屏幕的物理参数和时序
拿到一块 MIPI-DSI 屏，你需要四个信息才能配置：分辨率、像素时钟、lane 数、初始化序列。前三个通常能从屏厂给的规格书里找到，初始化序列是一串寄存器写命令，屏厂一般会给一个.h或者.txt，格式类似0x39, 0x05, 0x2C这样的命令加参数。
像素时钟自己算一遍比较保险，公式是pixel_clock = h_total × v_total × 刷新率。以 1920×1080@60 为例，h_total 约 2200，v_total 约 1125，得到 148.5 MHz。DSI 是差分串行，每条 lane 的速率是pixel_clock × bpp / lane 数，RGB888 是 24 bpp，4 lane 情况下每条 lane 891 Mbps，换算成 DDR 时钟就是 445.5 MHz。如果你按 2 lane 接，速率要翻倍到 1782 Mbps，这时候要检查 SoC 的 DSI 控制器和屏本身能不能跑到这个速率，很多小屏上限只有 1 Gbps/lane。
注意：MIPI-DSI 的时序参数里 h_front_porch、h_back_porch、h_sync_len 三个值加起来才是 h_total 减去有效宽度，写设备树时不要漏掉 sync_len，漏了会出现画面整体右移、右边一条黑边。
2.2 设备树里改哪几个节点
在厂商提供的 BSP 里，显示相关的设备树一般分三层：SoC 级的dsi@fed...控制器节点、板级的panel子节点、还有route或者ports里的连接关系。你需要改的是板级那部分：
&dsi0 { status = "okay"; panel@0 { compatible = "panel-init-seq-generic"; reg = <0>; width-mm = <68>; height-mm = <121>; display-timings { timing0 { clock-frequency = <148500000>; hactive = <1920>; vactive = <1080>; hfront-porch = <40>; hback-porch = <40>; hsync-len = <10>; vfront-porch = <10>; vback-porch = <10>; vsync-len = <2>; hsync-active = <0>; vsync-active = <0>; de-active = <1>; pixelclk-active = <0>; }; }; }; };这里的hsync-active和pixelclk-active是极性，不同屏不一样，写反了的表现是画面横向撕裂或者整体偏色。经验上，先按屏厂 demo 里的值抄，能亮再优化，别一上来就自己推导极性。
改完设备树重新编译 dtb，make ARCH=arm64 rockchip_defconfig之后单独编 dtbs 就行，不用整个镜像重刷。烧进去重启，看内核日志：
dmesg | grep -Ei "dsi|panel|vop"正常的话能看到 panel 探测成功、dsi 时钟设置、vop 绑定这几条。如果只有 dsi 控制器初始化而没有 panel probe，八成是compatible字符串和驱动里的匹配表对不上，或者是复位脚、电源脚没配。
2.3 用 modetest 验证，别急着写应用
点亮阶段最有效的工具是modetest，它是 libdrm 自带的测试程序，能直接列 connector、切模式、显示测试图案，不依赖任何上层框架。
modetest -M rockchip -c # 列出所有 connector 和当前状态 modetest -M rockchip -s 92@85:1920x1080 -P 79@85:1920x1080@XR24第一列是 connector id，后面是 crtc id 和 plane id，具体数字每块板子不同，从-c的输出里找connected的那个。这一步能出图，说明 kernel 层的显示链路完全通了，剩下就是用户态怎么用。
我在这一步踩过一个坑：屏幕能显示彩条但颜色是反的，查了半天发现是 RGB 顺序配置成了 BGR，设备树里那个bus-format属性没写对。这种问题在应用层是无论如何都调不出来的，必须在 DRM 层用测试图案先确认。
2.4 应用层选 DRM 还是 framebuffer
两条路都能上屏，差别很大。framebuffer（/dev/fb0）简单，mmap之后直接写内存，适合新手和小分辨率；但它没有页翻转，写的时候容易撕裂，而且不支持多层叠加、不支持硬件缩放。DRM 是现在的正路，双缓冲加 page flip 垂直同步，画框可以放在 overlay plane 上，主画面用 RGA 缩放后直接送主 plane。
如果你只是想快速看到图像，用 OpenCV 的imshow配 GTK 或 Qt 后端也行，但那个方案在嵌入式上的开销很大：一次imshow要走软件渲染、窗口合成、再拷贝到 framebuffer，1080p 下单帧就要 10 毫秒以上。我现在的标准做法是写一个约两百行的 DRM 封装：初始化时选 connector、创建 dumb buffer、配好 plane；每帧先drmModeAddFB2建帧缓冲，画完调drmModePageFlip，用poll等 flip 完成事件再画下一帧。这套东西跑 1080p@60 稳稳的，CPU 占用只有个位数。
3. OpenCV 交叉编译：把 NEON 和 RGA 都用起来
板子上自带的 OpenCV 往往是发行版预编译的，WITH_OPENCL=OFF、没有 NEON 优化、更没有 RGA 支持，跑个cv::resize和 PC 上没什么区别，纯靠 CPU 硬扛。自己编一次能带来两个收益：一是开启 NEON 和-O3让基础算子快一截，二是接上 RGA 后端，让 resize、cvtColor、warpAffine 这些常用操作直接下沉到硬件。
3.1 编译前先明确“我要用哪些模块”
OpenCV 全量编译出来接近 200 MB，加上opencv_contrib更大，而嵌入式上你 90% 的时间只用到 core、imgproc、imgcodecs、videoio、highgui 这五个。裁剪模块不只是省空间，还直接影响编译成功率和运行时的内存占用。
我的配置是：关掉BUILD_TESTS、BUILD_PERF_TESTS、BUILD_EXAMPLES、BUILD_DOCS，关掉WITH_GTK、WITH_QT（嵌入式上不需要本地窗口），关掉WITH_OPENCL（RK3588 的 GPU 走 OpenCL 意义不大，还会引入依赖），保留WITH_V4L（摄像头采集要用）、WITH_FFMPEG（读视频文件或 RTSP 要用）、WITH_JPEG/WITH_PNG（存图要用）。
cmake -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_TOOLCHAIN_FILE=../platforms/linux/aarch64-gnu.toolchain.cmake \ -DCMAKE_INSTALL_PREFIX=/opt/opencv-rk3588 \ -DBUILD_LIST=core,imgproc,imgcodecs,videoio,highgui,calib3d \ -DBUILD_TESTS=OFF -DBUILD_PERF_TESTS=OFF -DBUILD_EXAMPLES=OFF \ -DWITH_GTK=OFF -DWITH_QT=OFF -DWITH_OPENCL=OFF \ -DWITH_V4L=ON -DWITH_FFMPEG=ON \ -DENABLE_NEON=ON -DENABLE_VFPV3=ON \ -DCV_ENABLE_INTRINSICS=ON \ -DCMAKE_C_FLAGS="-O3 -ffast-math" \ -DCMAKE_CXX_FLAGS="-O3 -ffast-math" \ ..-ffast-math这个选项要慎用，它会让编译器放宽浮点语义，图像处理里一般没问题，但如果你在 OpenCV 之外还调用同一份代码做数值敏感的计算，可能出现微小偏差。我在纯视觉项目里一直开着，没遇到问题。
工具链文件里的路径要指向你自己的交叉编译器，重点是-march=armv8-a这一项，aarch64 默认就带 NEON，不需要像 32 位那样手动指定-mfpu=neon。
3.2 opencv_contrib 里的 RGA 后端
OpenCV 官方主仓里没有 RK3588 的 RGA 后端，需要额外打补丁或者使用厂商维护的 fork。补丁做的事情是在modules/imgproc/src/resize.cpp之类的位置加一个分支，当检测到 RGA 可用且参数满足条件时，走im2d的imresize接口，而不是 CPU 版。
打上之后的效果很明显：1920×1080 到 640×640 的 resize，CPU 版 6 到 8 毫秒，RGA 版 0.8 到 1.2 毫秒；cvtColor从 BGR 到 RGB 也从 3 毫秒降到 0.5 毫秒左右。两项加起来，单帧省出 8 毫秒，30 FPS 的预算刚好够。
注意：RGA 对 stride 有对齐要求，宽度一般要求 4 或 16 像素对齐。用
cv::Mat直接传的话，如果不是连续内存或者 stride 不满足，后端会静默回退到 CPU，你以为走了硬件其实没走。判断方法是看 CPU 占用，或者打开 RGA 的日志开关。
如果你不想打补丁，另一种做法是自己封装一层预处理函数，用 librga 的im2dAPI 直接操作 dma_buf，然后把结果交给 OpenCV 或者直接喂给 NPU。这条路上手更陡但控制力最强，我在最终版本里用的就是这个方案，因为它能实现真正的零拷贝。
3.3 编译产物怎么验证没白干
编完装到/opt/opencv-rk3588，板端设好LD_LIBRARY_PATH和PKG_CONFIG_PATH，然后跑一段自检代码：
#include <opencv2/core.hpp> #include <opencv2/imgproc.hpp> #include <iostream> #include <chrono> int main() { std::cout << cv::getBuildInformation().substr(0, 1200) << std::endl; cv::Mat src(1080, 1920, CV_8UC3, cv::Scalar(10, 20, 30)); cv::Mat dst; auto t0 = std::chrono::steady_clock::now(); for (int i = 0; i < 100; ++i) cv::resize(src, dst, cv::Size(640, 640)); auto t1 = std::chrono::steady_clock::now(); double ms = std::chrono::duration<double, std::milli>(t1 - t0).count() / 100; std::cout << "resize avg: " << ms << " ms" << std::endl; std::cout << "NEON: " << cv::checkHardwareSupport(CV_CPU_NEON) << std::endl; return 0; }关键就看两个数字：NEON是否为 1，以及 resize 平均耗时。如果 resize 超过 3 毫秒，说明要么 NEON 没生效，要么 RGA 后端没编进去。我第一次编译时忘了加-DCV_ENABLE_INTRINSICS=ON，NEON 检测返回 0，白折腾一轮。
4. YOLOv8 转 RKNN：量化的成败都在细节里
这一段是整个项目里返工率最高的部分。模型转不过去、转过去了精度掉了、精度没掉但速度不对，三种情况的排查路径完全不同。我的建议是分三步走：先转成不量化的浮点模型验证结构正确，再转量化模型验证精度，最后才调性能参数。跳过前两步直接压性能，出问题你根本不知道是哪一层。
4.1 导出 ONNX 时的三个固定动作
从 ultralytics 的仓库导出 ONNX，命令一行就够，但有几个参数必须显式指定，否则后面必踩坑：
yolo export model=yolov8n.pt format=onnx imgsz=640,640 \ opset=12 simplify=True dynamic=Falseopset=12是稳妥选择。太低的话某些算子不支持，太高的话 rknn-toolkit2 的算子映射表可能还没覆盖。simplify=True会跑一遍 onnx-simplifier，把冗余的 Reshape、Transpose 干掉，对后续转换帮助很大。dynamic=False尤其重要，RKNN 需要静态 shape，带动态维度的模型转过去会报输入维度不匹配。
还有一个容易被忽略的点：不要导出带 NMS 的端到端版本。ultralytics 现在支持导出含后处理的模型，但 RKNN 对这类带复杂控制流或自定义算子的图支持有限，转过去要么失败，要么被拆得七零八落。正路是导出原始的三个尺度输出（80×80、40×40、20×20，每个尺度 64 通道的 DFL 输出加类别分数），后处理在 CPU 上用 C++ 手写。这部分代码不难，但必须自己写，因为它是性能关键路径。
导出之后在 PC 上用 onnxruntime 跑一遍，确认输出 shape 是[1, 64, 80, 80]、[1, 64, 40, 40]、[1, 64, 20, 20]加上对应的分数张量，总共六个输出（有些版本合并成三个）。shape 对不上就先别往下走。
4.2 rknn-toolkit2 的配置项逐条解释
转换脚本的核心就三个函数：rknn.config、rknn.load_onnx、rknn.build。配置项看着多，真正影响结果的就那么几个：
from rknn.api import RKNN rknn = RKNN(verbose=True) rknn.config( mean_values=[[0, 0, 0]], std_values=[[255, 255, 255]], target_platform='rk3588', quantized_dtype='asymmetric_quantized-8', quantized_algorithm='normal', optimization_level=3, compress_weight=True, single_core_mode=False, ) rknn.load_onnx(model='yolov8n.onnx') rknn.build(do_quantization=True, dataset='./dataset.txt') rknn.export_rknn('yolov8n.rknn')mean_values和std_values这里要特别小心。YOLOv8 训练时输入是 0 到 1 的浮点（除以 255），如果你在 RKNN 里配std_values=[[255,255,255]]，它就帮你在硬件上做这个归一化，你的应用代码传入的就可以是 0 到 255 的 uint8。如果配错了，模型输出会全乱，表现是置信度普遍极低或者框全堆在中心。我的习惯是归一化放在模型里做，因为 RGA 只负责缩放和格式转换，浮点除法交给 NPU 前置处理更省事。
quantized_algorithm有三个选项：normal、mmse、kl_divergence。normal最快，mmse精度最好但转换时间长三到五倍。我的经验是 YOLOv8 系列用normal就够了，mAP 掉点在 1 个点以内；如果做的是小目标或者密集场景，可以试mmse对比。
optimization_level=3会做一些图层面的融合优化，一般都能开到 3，遇到转换失败再往下调。
4.3 量化数据集：两百张图比两万张有用
量化校准的原理是用一批真实图片跑前向，统计每层激活值的分布，然后确定量化 scale。关键不在于图片多，而在于分布对。如果你的实际场景是室内暗光，校准集里全是室外白天的高清图，量化后的精度必然掉。
我的标准做法是：从实际部署场景的录像里抽 200 到 300 帧，覆盖不同光照、不同目标密度、有无目标的都要有。全是有目标的图会让背景区域的分布统计偏掉，建议至少留 20% 的空场景帧。
dataset.txt就是一个纯文本，每行一张图的路径：
./calib/img_0001.jpg ./calib/img_0002.jpg ./calib/img_0003.jpg路径用绝对路径最保险，相对路径在build时的工作目录可能和你想的不一样。另外图片不必预先 resize 到 640，toolkit 会自己按配置处理，但必须是 RGB 三通道，灰度图或者四通道 PNG 会导致报错。
量化完成之后，toolkit 会打印每一层的量化误差信息（开verbose=True才看得到）。重点关注误差超过 0.05 的层，如果这些层集中在检测头附近，精度掉点就比较严重。
4.4 精度掉了怎么救：混合量化和逐层分析
实测下来，YOLOv8n 在 COCO 上量化前后 mAP 差距一般在 0.5 到 1.5 个点，属于可接受范围。但如果你自己的数据集类别少、目标特殊，掉点可能到 3 个点以上。这时候有几个手段可以依次试：
第一招是调校准集，这是性价比最高的。换一批更贴近部署场景的图，重跑一次量化，经常能救回一两个点。
第二招是混合量化。rknn-toolkit2 支持把某些层保持浮点，其余层量化：
rknn.config(..., quantized_dtype='asymmetric_quantized-8') rknn.load_onnx(model='yolov8n.onnx') rknn.hybrid_quantization_step1(dataset='./dataset.txt') # 编辑生成的 yolov8n.quantization.cfg，把关键层加入 custom_quantize_layers rknn.hybrid_quantization_step2( model_input='yolov8n.model', data_input='yolov8n.data', model_quantization_cfg='yolov8n.quantization.cfg')具体哪些层该保浮点，看 step1 输出的误差表，一般把误差最大的连续几层标出来。注意保浮点的层越多，速度越慢，因为 NPU 和 CPU 之间会有数据搬运，所以别超过总层数的 5%。
第三招是换量化算法到 mmse，或者干脆用quantized_dtype='w8a16'之类的混合精度（部分版本支持），代价是速度下降 20% 到 30%。
注意：每次改量化配置，务必在验证集上跑一遍完整评估，别只看几张图“感觉还行”。我见过量化后单张图看着正常，一跑批量评估 mAP 掉了 6 个点的情况，原因是某个尺度的输出被量化成了常数。
5. 板端部署：零拷贝流水线怎么写
模型文件拷到板子上只是开始。真正决定帧率的是你怎么组织内存和线程。RKNN 的运行时提供了rknn_create_mem和rknn_set_io_mem，让你把 DMA 缓冲直接绑到输入输出，这样 RGA 处理完的数据不需要 memcpy 就能进 NPU，NPU 输出也不需要拷贝就能被后处理读到。一次 memcpy 1080p 的 RGB 图像大约 1 到 2 毫秒，看起来不多，但一秒钟三十帧就是 60 毫秒的 CPU 时间，在四核 A76 上相当于一个核被吃掉了四分之一。
5.1 内存布局：一次性分配，循环复用
我的做法是启动时按最大尺寸分配三块 dma_buf：采集缓冲、模型输入缓冲（640×640×3）、显示缓冲。三块都拿到文件描述符和虚拟地址，之后每帧只在描述符之间传递，不再 malloc。
// 伪代码，展示结构 int in_fd; void* in_virt = rknn_create_mem(ctx, 640 * 640 * 3, &in_fd); rknn_tensor_mem* in_mem = /* 包装成 rknn_tensor_mem */; rknn_set_io_mem(ctx, in_mem, &input_attrs[0]);关键在于输入张量的属性要设对：fmt = RKNN_TENSOR_NHWC、type = RKNN_TENSOR_UINT8、size = 640*640*3、pass_through = 0。pass_through=0表示让运行时按 config 里的 mean/std 做归一化，pass_through=1表示原样传入，后者要求你自己在外部做好归一化，一般用不到。
输出张量建议用want_float=0，拿定点结果自己反量化，比让运行时转浮点快。YOLOv8 的输出是 int8，带上每层的 scale 和 zp，反量化就是(val - zp) * scale，一次乘加的事。
5.2 三线程流水线：采集、推理、显示各管一段
单线程串行执行的帧率上限，是采集、预处理、推理、后处理、显示五段耗时的倒数。假设各段是 3、2、15、5、3 毫秒，串行就是 28 毫秒一帧，35 FPS。做成流水线之后，瓶颈在推理的 15 毫秒，理论上能到 66 FPS。实际因为同步开销能到 50 左右，提升接近一倍。
线程划分我的习惯是三个：采集与预处理线程（负责取图、RGA 缩放、把数据写进输入缓冲）、推理线程（阻塞在rknn_run）、后处理与显示线程（取输出、解码、画框、page flip）。三者用一个容量为 2 的环形队列连接，队列满时采集线程丢最旧的帧而不是阻塞——这条在实时系统里非常重要，宁丢帧不堆积，否则延迟会越滚越大，画面和现实差出半秒。
同步用条件变量加互斥锁就够了，别上无锁队列，那玩意儿的正确性验证成本远大于收益。每帧带上时间戳和帧号，方便事后分析哪一段耗时超标。
5.3 后处理的 C++ 实现要点
YOLOv8 的后处理分两步：DFL 解码和 NMS。DFL 部分对每个 anchor 的 64 个通道做 softmax 加权求和得到距离，再结合 anchor 位置还原成框。这部分计算量不小，640 输入下总共 8400 个 anchor，每个 4 条边各 16 个通道，全展开是五万多次乘加，在 A76 上大约 1 到 2 毫秒。
优化点在于：先按类别分数过滤，再做 DFL。分数低于阈值的 anchor 直接跳过，实测能把 DFL 的调用次数降到原来的 5% 到 10%，耗时降到 0.2 毫秒。NMS 用简单的按分数排序加 IoU 剔除，类别多的话按类别分组做，避免不同类别之间误抑制。
还有一个容易忽略的细节：输出张量的 scale 是逐层的，三个尺度的量化参数不同，反量化时不能共用一个 scale。我第一次写的时候图省事用了第一个通道的 scale，结果大目标的框整体偏大 20%，调了半天以为是训练问题。
6. 性能实测与调优：把每一毫秒找出来
性能这事不能靠感觉。我习惯在代码里埋一个轻量的计时器，用clock_gettime(CLOCK_MONOTONIC)打点，每 100 帧统计一次各段的平均值和 P99。平均值看整体，P99 看卡顿，很多时候平均 20 毫秒但 P99 到 80 毫秒，画面就是一顿一顿的。
6.1 各阶段耗时的实测数据
在 1080p 采集、640 输入的配置下，我的实测数据大致如下（不同板卡散热和内存频率会有浮动）：
| 阶段 | 实现方式 | 耗时（ms） | 备注 |
|---|---|---|---|
| 采集取帧 | V4L2 dma_buf | 1.5 | 队列取帧，不含 ISP 延迟 |
| 预处理 | RGA 缩放+转 RGB | 1.0 | 1080p 到 640 |
| 推理 YOLOv8n | NPU 三核并行 | 11.0 | INT8 量化 |
| 后处理 | CPU DFL+NMS | 2.0 | 分类别过滤后 |
| 显示准备 | RGA 缩放到屏 | 1.2 | 1080p 输出 |
| 上屏 | DRM page flip | 0.3 | 异步，不等垂直同步 |
| 合计（流水线） | 约 16 | 瓶颈在推理 |
单看推理 11 毫秒，YOLOv8s 大约 22 到 25 毫秒，YOLOv8m 就上到 45 毫秒以上了。所以如果目标是 30 FPS 以上，n 和 s 是合理选择，m 只能做到 20 FPS 左右，还得看场景能不能接受。
6.2 NPU 核心调度与频率这两件事
RK3588 的 NPU 有三个核心，默认调度策略是自动分配。对于 YOLOv8 这种单模型场景，single_core_mode=False让运行时自己拆图并行，比单核快接近三倍。但如果你要同时跑两个模型（比如检测加分类），就要考虑用rknn_set_core_mask手动绑核，一个模型绑 core 0，另一个绑 core 1，避免互相抢。
频率方面，NPU 的 devfreq 默认是简单按负载调，但它对突发负载的响应有延迟，流水线刚启动那几帧会跑在低频上。我的做法是在应用启动时把 governor 设成userspace并锁到较高频点：
cat /sys/class/devfreq/*npu*/available_frequencies echo userspace > /sys/class/devfreq/*npu*/governor echo 1000000000 > /sys/class/devfreq/*npu*/userspace/set_freq具体可用频率每块板子不同，先cat出来再选。锁频的代价是功耗和发热，如果是电池供电的产品，建议只在检测到连续高负载时临时锁，空闲时放回自动。
散热这件事必须提一句。RK3588 满载时 SoC 功耗能到 5 瓦以上，没有散热片的板子跑十分钟就会降频，帧率从 55 掉到 35。我现在的标准配置是铝散热片加一个小风扇，或者至少贴一块 20×20 的铜块加导热硅胶，成本很低但效果立竿见影。
7. 常见问题速查与避坑实录
下面这张表是我和身边人踩过的坑汇总，按出现频率排序。每个问题我都写了判断依据，因为嵌入式调试最难的不是解决，而是定位。
| 现象 | 最可能原因 | 判断方法 | 处理方式 |
|---|---|---|---|
| RKNN 初始化失败，报版本错误 | toolkit 与运行库版本不匹配 | strings librknnrt.so | grep -i version | 统一到同一版本，重转模型 |
| 推理结果全是同一个框 | mean/std 配置与实际输入不符 | 用同一张图对比 PC 端 ONNX 输出 | 检查归一化配置，必要时 pass_through |
| 量化后精度暴跌 | 校准集与场景分布差异大 | 分层误差表，看误差集中位置 | 换校准集，或对关键层混合量化 |
| 屏幕黑屏但 dmesg 正常 | 背光没开或 PWM 没配 | 万用表量背光供电 | 检查 backlight 节点和 enable 脚 |
| 画面撕裂 | 没用 page flip 或没等 vsync | 观察水平方向错位 | 改 DRM 双缓冲，等 flip 事件 |
| 帧率随运行时间下降 | 内存泄漏或未释放 dma_buf | cat /proc/meminfo看 CmaFree | 每帧检查释放，用 RAII 封装 |
RGA 报错invalid param | 宽高或 stride 未对齐 | 打印实际参数 | 宽度对齐到 16，检查格式枚举 |
| 检测框整体偏移 | 后处理反量化 scale 用错 | 对比单张图的原始输出 | 逐输出张量取各自 scale |
| 多线程下偶发崩溃 | 共享 cv::Mat 引用计数竞争 | 复现时看 core dump 栈 | 深拷贝或改用裸缓冲区加锁 |
| 摄像头出图偏绿 | ISP 的 3A 未启动或白平衡未收敛 | 前几帧对比后续帧 | 等待 rkaiq 初始化完成再取流 |
说几个表里没写但值得单独拎出来的经验。
关于 dma_buf 泄漏。这类问题最阴险，因为程序跑起来完全正常，跑半小时后开始卡，一小时直接 OOM。原因是每次rknn_create_mem或者 RGA 的importbuffer都会占一块 CMA，忘了release就一直累积。我的做法是给每个硬件缓冲写一个小的 RAII 包装类，构造时申请、析构时释放，禁止裸指针在业务代码里传递。同时开一个后台线程每十秒打印一次CmaFree，一旦单调下降就说明漏了。
关于 V4L2 的 buffer 数量。默认给 4 个 buffer，1080p 的 NV12 每块约 3 MB，四块就是 12 MB。如果同时开了多路摄像头，很容易把 CMA 吃光导致后面的分配失败。我一般设 3 个，够用且省内存，取帧延迟也没明显增加。
关于模型热加载。做产品时经常需要在运行时切换模型，这时候要注意rknn_destroy之后必须等所有正在跑的rknn_run返回，否则会段错误。我吃过这个亏，后来在推理线程里加了一个原子标志位，切换前先置位、等推理线程自己退出循环，再销毁上下文。
关于日志。嵌入式上 printf 到串口的开销不小，一秒钟几十条日志能占掉几个毫秒。调试期开，出产品必须关，或者改成写环形缓冲、只在异常时落盘。我现在的做法是用一个编译期开关控制的轻量日志宏，Release 版本里直接编译成空语句。
最后一个关于选型的心得：这套方案里最容易被低估的其实是 RGA。很多人在 NPU 上调了半天参数，帧率提升不到 10%，却不知道预处理还在用 CPU 做双线性插值。花半天时间把 resize 和 cvtColor 换到 RGA 上，收益比调一个月量化参数都大。判断方法很简单：推理时用top看一眼，如果某个核的 CPU 占用长期在 60% 以上而 NPU 负载不高，那瓶颈一定在 CPU 侧的数据搬运上，顺着这条线查基本一查一个准。
系统架构与优化实践)
