RK3568鸿蒙开发板部署RKNN推理框架：从环境搭建到Demo运行全流程

1. 项目概述：从零部署RKNN推理框架到鸿蒙开发板

最近在折腾一块DAYU200开发板，它搭载的是瑞芯微的RK3568芯片，跑的是OpenHarmony系统。我的目标很明确：在这块板上把瑞芯微官方的轻量级AI推理工具链rknn_toolkit_lite2给跑起来，并且成功运行一个官方的Demo。听起来像是个标准的“开箱即用”流程，对吧？但实际操作下来，你会发现从环境适配、依赖解决到最终模型推理，每一步都可能藏着“坑”。这不仅仅是把Python包装上去那么简单，它涉及到芯片架构、系统环境、模型转换和运行时库的完整对齐。如果你也有一块RK3568的开发板，无论是DAYU200还是其他型号，想在鸿蒙或者Linux系统上部署自己的AI模型，那这篇从踩坑到填坑的实录，应该能帮你省下不少折腾的时间。

2. 核心需求与方案选型解析

2.1 为什么是rknn_toolkit_lite2？

首先得搞清楚我们为什么要用这个工具。瑞芯微为自家的NPU（神经网络处理单元）提供了两套主要的开发工具：rknn-toolkit2和rknn-toolkit-lite2。前者功能强大，运行在x86_64的PC上，主要负责模型的转换、量化和仿真；后者则是前者的“运行时”精简版，专门为ARM架构的嵌入式设备设计，体积小、依赖少，只负责加载转换好的RKNN模型文件并进行推理。

对于DAYU200这样的边缘设备，我们显然需要rknn_toolkit_lite2。它的核心价值在于：

1. 轻量级：剥离了图形界面和复杂的转换工具，核心就是一个Python包加C++库，对设备资源占用小。
2. 针对性优化：直接调用RK3568芯片的NPU驱动，实现硬件加速推理，效率远高于在CPU上运行。
3. 无缝衔接：在PC上用rknn-toolkit2转换好的模型（.rknn文件），可以直接拿到开发板上用lite2版本加载运行，形成标准的“PC端转换-设备端部署”工作流。

所以，我们的任务链条很清晰：在DAYU200上搭建一个能正确运行rknn_toolkit_lite2的Python环境，然后验证它能否正常驱动NPU并执行推理计算。

2.2 DAYU200开发板环境特点与挑战

DAYU200的默认系统是OpenHarmony 3.2 Release。它与我们更常见的Ubuntu、Debian等Linux发行版有显著区别，这直接带来了几个挑战：

1. 包管理差异：OpenHarmony使用hpm作为包管理器，而非apt或yum。很多常见的Linux软件包可能没有现成的ohos版本。
2. Python环境：系统可能预装了Python，但版本和路径需要确认。更关键的是，pip可能没有，或者源不可用。
3. 系统库依赖：rknn_toolkit_lite2底层依赖一些C库（如libstdc++, glibc等），这些库在OpenHarmony上的版本和符号链接需要与工具链兼容。
4. NPU驱动：RK3568的NPU驱动是否已集成到内核中？用户态是否有访问权限？这是硬件加速能否生效的前提。

面对这些挑战，一种比较稳妥的方案是：在OpenHarmony上通过Linux兼容层（如通过Docker容器）来构建一个标准的Linux（如Ubuntu）环境。这样，我们可以使用熟悉的apt和pip来安装依赖，大大降低环境配置的复杂度。另一种方案是直接使用瑞芯微为RK3568提供的Debian/Ubuntu固件，但这可能偏离了鸿蒙生态的初衷。本文将以在OpenHarmony上创建Ubuntu容器环境为主线进行阐述，这也是目前社区里验证过比较可行的方法。

3. 基础环境搭建与依赖部署

3.1 准备Linux兼容运行环境

由于直接在OpenHarmony上配置复杂的Python依赖比较困难，我们首先在DAYU200上部署一个Docker容器，运行一个轻量级的Ubuntu系统。

步骤一：检查并安装Docker通过串口或SSH登录DAYU200开发板。首先检查Docker是否已安装：

docker --version

如果未安装，需要根据OpenHarmony的版本安装Docker。OpenHarmony 3.2通常可以通过hpm安装，但过程可能较复杂。一个更直接的方法是，许多DAYU200的社区镜像已经集成了Docker。如果确实没有，你可能需要先刷写一个包含了Docker的社区固件，这是后续步骤的基础。

步骤二：拉取并运行Ubuntu容器我们选择一个轻量的Ubuntu镜像，例如ubuntu:20.04。

docker pull ubuntu:20.04 docker run -itd --name rknn_env --privileged -v /dev/bus/usb:/dev/bus/usb -v /data:/data ubuntu:20.04 /bin/bash

这里有几个关键参数：

• --privileged：赋予容器最高权限，这对于访问NPU设备节点通常是必要的。
• -v /dev/bus/usb:/dev/bus/usb：将USB设备挂载到容器内，如果你需要通过USB连接板子进行调试，这个映射有用。
• -v /data:/data：创建一个共享数据卷，方便在宿主机（OpenHarmony）和容器之间传递文件，比如模型文件。

步骤三：进入容器并更新系统

docker exec -it rknn_env bash

进入容器后，首先更新软件源并安装基础工具：

apt update apt upgrade -y apt install -y python3 python3-pip vim wget

注意：在容器内操作，意味着你的工作环境是标准的Ubuntu。所有后续的rknn_toolkit_lite2安装和Demo运行都在这个容器内进行。当你退出容器后，再次进入需要运行docker exec -it rknn_env bash。

3.2 安装rknn_toolkit_lite2Python包

瑞芯微官方提供了针对不同Python版本和芯片架构的rknn_toolkit_lite2轮子（whl文件）。我们需要选择与容器内环境匹配的版本。

步骤一：确定Python版本和架构在容器内执行：

python3 --version # 例如输出 Python 3.8.10 dpkg --print-architecture # 输出 arm64

RK3568是ARMv8架构，所以是aarch64（即arm64）。Python版本假设是3.8。

步骤二：下载对应的whl文件你需要从瑞芯微的官方资源站或GitHub仓库找到rknn_toolkit_lite2的发布包。通常文件名格式为rknn_toolkit_lite2-{version}-cp38-cp38-linux_aarch64.whl。 我们可以使用wget直接下载到容器内，或者先在宿主机下载，然后通过之前挂载的/data卷复制进去。 假设文件已放在容器的/data目录下。

步骤三：安装whl包

cd /data pip3 install rknn_toolkit_lite2-2.0.0-cp38-cp38-linux_aarch64.whl -i https://pypi.tuna.tsinghua.edu.cn/simple

使用国内镜像源可以加速下载。安装成功后，可以验证：

python3 -c "from rknnlite.api import RKNNLite; print('RKNN Lite2 import success')"

如果没有报错，说明Python包安装成功。

3.3 部署NPU运行时库与驱动

仅仅安装Python包是不够的，它只是一个上层接口。底层还需要NPU的驱动和运行时库（.so文件）才能实际调用硬件。

步骤一：获取NPU运行时库这些库文件通常包含在瑞芯微提供的“RKNN SDK”中，或者随rknn-toolkit2的安装包一起提供。你需要找到名为librknnrt.so的核心库文件，以及可能存在的其他依赖库（如libgomp.so.1,libm.so.6等，这些系统通常已有）。

关键是要找到与你的芯片型号（RK3568）和系统架构（aarch64）匹配的版本。一个常见的做法是，从瑞芯微为RK3568提供的Linux SDK中提取这些库。

步骤二：将库文件放置到系统路径将librknnrt.so等必要的库文件复制到容器内的系统库目录，例如/usr/lib/。

cp /data/librknnrt.so /usr/lib/

然后，可能需要更新动态链接库缓存：

ldconfig

步骤三：验证NPU设备节点NPU驱动会在系统中创建设备节点。检查是否存在：

ls -l /dev/bus/usb # 如果通过USB连接模式，可能需要检查 ls -l /dev/dri/ # 对于PCIe或集成NPU，设备节点可能在这里或 /dev/rknpu

具体的设备节点路径需要参考RK3568的驱动文档。有时驱动会以内核模块形式加载，你可以检查：

lsmod | grep npu

或者

dmesg | grep -i npu

查看内核日志中是否有NPU初始化的成功信息。

实操心得：这一步是最容易出问题的地方。不同版本的固件、不同的内核配置，可能导致NPU的设备节点名称和路径完全不同。如果后续Demo运行失败，并提示“打开设备失败”或“初始化NPU失败”，十有八九是这一步的库版本不对或设备节点权限有问题。务必确保你使用的librknnrt.so版本与你的系统内核驱动版本匹配。一个笨办法但有效：直接使用开发板原厂提供的完整系统镜像（如果它是Linux发行版），里面的库和驱动肯定是匹配的，可以从中拷贝。

4. 运行官方Demo全流程拆解

环境准备好之后，我们来实际运行一个Demo。瑞芯微通常会在SDK中提供一些示例程序，比如基于MobileNet或YOLO的图片分类、目标检测Demo。

4.1 获取Demo代码与模型文件

假设我们从瑞芯微的示例包中拿到了一个“图片分类”Demo。它通常包含以下文件：

• test.py：主推理脚本。
• mobilenet_v1.rknn：已经转换好的RKNN模型文件。
• dog_224x224.jpg：一张测试图片。
• labels.txt：分类标签文件。

我们将这些文件通过数据卷（/data）放到容器内的工作目录，例如/workspace。

4.2 剖析Demo脚本的核心逻辑

打开test.py，其核心代码结构一般如下，理解它有助于我们调试和编写自己的应用：

from rknnlite.api import RKNNLite import numpy as np from PIL import Image # 1. 初始化RKNN对象 rknn_lite = RKNNLite() # 2. 加载RKNN模型 ret = rknn_lite.load_rknn('./mobilenet_v1.rknn') if ret != 0: print('Load RKNN model failed') exit(ret) # 3. 初始化运行时环境 # 参数‘target’可以指定为‘rk3568’，‘core_mask’可以设置使用的核心 ret = rknn_lite.init_runtime(target='rk3568', core_mask=RKNNLite.NPU_CORE_0) if ret != 0: print('Init runtime environment failed') exit(ret) # 4. 数据预处理 img = Image.open('./dog_224x224.jpg').resize((224, 224)) img = np.array(img).astype('float32') img = np.expand_dims(img, axis=0) # 添加batch维度 # 可能需要归一化、通道转换（RGB->BGR）等，具体看模型要求 # img = (img - mean) / std # img = img[..., ::-1] # RGB to BGR # 5. 执行推理 outputs = rknn_lite.inference(inputs=[img]) print('Inference done.') # 6. 后处理与结果解析 # 假设输出是分类概率 probabilities = np.array(outputs[0][0]) top5_idx = np.argsort(probabilities)[-5:][::-1] with open('labels.txt', 'r') as f: labels = f.readlines() for i in top5_idx: print(f'{labels[i].strip()}: {probabilities[i]}') # 7. 释放资源 rknn_lite.release()

关键点解析：

• init_runtime：这一步是关键，它负责与底层NPU驱动建立连接。target参数必须指定正确的芯片型号。core_mask可以指定使用NPU的哪个核心（如果NPU是多核的），对于轻量任务，使用单个核心可能更节能。
• 数据预处理：这是最容易出错的地方。PC上训练和转换模型时，有一套固定的预处理流程（缩放、裁剪、归一化、通道顺序）。在部署端，必须严格复现完全相同的预处理逻辑，否则输入数据分布不对，输出结果就会毫无意义。务必仔细核对原始模型（如TensorFlow、PyTorch）的预处理代码。
• inference：输入数据需要包装成列表。即使只有一个输入节点，也需要是inputs=[data]的形式。

4.3 执行Demo并验证结果

在容器内的/workspace目录下，直接运行脚本：

cd /workspace python3 test.py

成功运行的标志：

1. 脚本没有报错退出。
2. 打印出“Inference done”或类似信息。
3. 输出了TOP-5的类别及其概率，并且概率值看起来合理（例如，识别一张狗图片，golden retriever的概率最高）。

如果一切顺利，恭喜你，DAYU200的NPU已经被成功调用，并完成了第一次AI推理！

性能观察： 你可以稍加修改脚本，在推理前后加入时间戳，计算推理耗时：

import time start = time.time() outputs = rknn_lite.inference(inputs=[img]) print(f'Inference time: {(time.time()-start)*1000:.2f} ms')

对比在RK3568的CPU上运行相同模型的时间，你会直观感受到NPU加速的效果（通常是数量级的提升）。

5. 深度踩坑实录与问题排查指南

在实际操作中，几乎不可能一帆风顺。下面是我遇到的一些典型问题及解决方案，整理成排查清单。

5.1 环境与依赖类问题

问题1：ImportError: librknnrt.so: cannot open shared object file

• 现象：导入rknnlite.api或运行init_runtime时出现此类动态链接库错误。
• 排查：
  1. 确认库文件存在：find / -name librknnrt.so 2>/dev/null，看是否能找到。
  2. 确认库路径在搜索范围内：echo $LD_LIBRARY_PATH。如果库不在标准路径（/usr/lib,/lib），需要将其加入环境变量：export LD_LIBRARY_PATH=/path/to/your/lib:$LD_LIBRARY_PATH。
  3. 检查库的架构：file /path/to/librknnrt.so，确认是ELF 64-bit LSB shared object, ARM aarch64。
  4. 检查库的依赖：ldd /path/to/librknnrt.so，查看是否有其他not found的依赖。在Ubuntu容器内，可以用apt安装缺失的系统库。

问题2：安装rknn_toolkit_lite2的whl包时，提示“平台不支持”或“版本不匹配”

• 现象：pip install失败，报错包含platform或cpXX不兼容。
• 解决：
  1. 严格核对Python版本（cp38对应 Python 3.8）和系统架构（linux_aarch64对应 ARM64）。
  2. 尝试使用--force-reinstall和--no-deps选项强制安装：pip3 install xxx.whl --force-reinstall --no-deps，然后手动安装其依赖（如numpy,opencv-python-headless等）。

5.2 NPU运行时与驱动类问题

问题3：RKNNLite.init_runtime() 失败，返回错误码 -1 或 -2

• 现象：模型加载成功，但初始化运行时环境失败。
• 排查：
  1. 检查target参数：确保target='rk3568'。不同芯片的代号不同。
  2. 检查NPU驱动状态：在容器内执行dmesg | tail -50，查看最近的内核日志，寻找关于npu或rknpu的错误信息。可能需要检查内核是否加载了NPU驱动模块。
  3. 检查设备权限：如果驱动创建了/dev/rknpu或类似的设备文件，检查当前用户（在容器内通常是root）是否有读写权限：ls -l /dev/rknpu。如果没有权限，需要在docker run时通过--privileged提权，或在宿主机上修改设备文件的权限。
  4. 库版本冲突：这是最棘手的问题。确保你使用的librknnrt.so与当前系统内核的NPU驱动版本完全匹配。最可靠的方法是使用开发板厂商提供的完整BSP SDK中的库。

问题4：推理结果完全错误或全是零

• 现象：推理过程不报错，但输出的概率值全一样、全为零，或者最高概率的类别毫无逻辑。
• 排查：
  1. 首要怀疑：数据预处理。99%的问题出在这里。逐行对比部署端的预处理代码和模型训练/转换时的预处理代码。重点关注：
     • 图像尺寸（width, height）是否完全一致。
     • 像素值归一化：是[0, 1]还是[0, 255]？减去的均值（mean）和除以的标准差（std）是否正确？
     • 通道顺序：模型训练时是RGB还是BGR？OpenCV默认读图是BGR，PIL是RGB。
     • 数据精度：是否转换为模型期望的float32或int8？
  2. 可以写一个简单的脚本，将部署端预处理后的数据（例如，一个numpy数组）保存为文件，然后在PC上用rknn-toolkit2加载同样的模型和图片，对比两者预处理后的输入数据是否完全一致（可以使用np.allclose()函数）。

5.3 性能与稳定性类问题

问题5：推理速度远低于预期

• 现象：NPU推理耗时和CPU推理差不多，没有体现出加速优势。
• 排查：
  1. 确认NPU确实在工作：在推理时，使用htop或cat /sys/kernel/debug/rknpu/load（如果调试接口存在）观察NPU负载。如果负载为0，说明可能还是跑在CPU上。
  2. 检查模型是否量化：浮点模型（FP32）在NPU上的加速比可能不如定点模型（INT8）。确保你加载的.rknn文件是经过量化优化的。可以在PC上用rknn-toolkit2重新转换并量化模型。
  3. 尝试不同的 core_mask：对于小模型，使用单个NPU核心（RKNNLite.NPU_CORE_0）可能效率更高。对于大模型或需要高吞吐的场景，可以尝试使用多个核心（如RKNNLite.NPU_CORE_0_1）。

问题6：内存不足（OOM）错误

• 现象：在加载大模型或处理大图片时，程序崩溃，提示内存不足。
• 解决：
  1. RK3568的NPU有自己独立的内存，但也可能和系统共享部分资源。尝试减小模型输入尺寸。
  2. 检查容器内存限制：docker inspect rknn_env | grep -i memory。如果有限制，可以运行容器时指定更大的内存：docker run -it --memory=2g ...。
  3. 确保在推理完成后，调用rknn_lite.release()释放模型占用的资源。

6. 进阶：集成到OpenHarmony原生应用

在Docker容器中运行成功，只是第一步。最终的目标可能是将AI能力集成到原生的OpenHarmony应用中。这涉及到更复杂的跨进程、跨语言调用。

思路一：C++动态库封装将rknn_toolkit_lite2的推理功能，用C++编写成一个动态库（.so）。这个C++程序直接链接librknnrt.so，并提供几个简单的C接口函数，如init_model,run_inference,release_model。然后，在OpenHarmony的Native层（使用C或C++）调用这个动态库。

思路二：进程间通信（IPC）让一个常驻的Python推理服务运行在容器或后台，OpenHarmony应用通过进程间通信（如Unix Socket、DBus）将图片数据发送给这个服务，并接收推理结果。这种方式隔离性好，Python服务崩溃不会直接影响主应用，但引入了通信开销。

思路三：使用鸿蒙的NAPI机制这是最“原生”但难度也最高的方式。通过OpenHarmony的NAPI（Native API）框架，将C/C++的推理代码封装成JavaScript接口，供ArkTS/JS应用直接调用。这需要对鸿蒙的NDK开发有较深了解。

无论哪种思路，都需要解决一个根本问题：如何让OpenHarmony环境找到并正确加载librknnrt.so及其依赖。你可能需要将这些库文件打包到OpenHarmony应用的libs目录下，并正确配置LD_LIBRARY_PATH。这个过程充满了挑战，需要对鸿蒙的应用打包和动态链接机制有清晰的认识。

从在DAYU200上成功运行第一个RKNN Demo，到最终将其能力无缝融入鸿蒙生态，中间还有很长的路要走。但第一步的成功，已经证明了RK3568 NPU与OpenHarmony结合进行边缘AI计算的可行性。后续的集成工作，更像是软件工程上的挑战，只要耐心拆解，逐步打通各个环节，就能让这块开发板真正“智能”起来。