RK3588 端侧 AI 部署（五）：Lite2、C API 与零拷贝工程化#

模型通过 Toolkit2 验证后，下一步是让程序真正独立运行在 RK3588 上。可以先用 Lite2 快速复现 Python 结果，再用 RKNPU2 C/C++ API 构建正式应用。

一、三种运行方式如何选择#

方式	运行位置	适合阶段	主要限制
Toolkit2 连板	x86 主机控制 RK3588	转换后快速验证和评估	依赖主机、ADB 和 server
Toolkit-Lite2	RK3588 板端 Python	原型、算法验证、小工具	Python 开销和工程能力有限
RKNPU2 C/C++	RK3588 板端原生程序	产品、视频流、并发和性能优化	开发复杂度更高

推荐顺序：

1
Toolkit2 连板结果正确
2
→ Lite2 在板端复现
3
→ 通用 C API 复现
4
→ 零拷贝、多 Context、RGA 和线程池优化

二、RKNN-Toolkit-Lite2 快速验证#

从 RKNN-Toolkit2 仓库中选择与下面三项匹配的 Lite2 wheel：

RKNN SDK release；
板端 Python cpXX；
aarch64 架构。

1
conda create -n rknnlite python=3.10 -y
2
conda activate rknnlite
3
pip install ./rknn_toolkit_lite2-*-cp310-*-linux_aarch64.whl

最小推理结构：

1
from rknnlite.api import RKNNLite
2

3
runtime = RKNNLite(verbose=True)
4

5
ret = runtime.load_rknn("model.rknn")
6
if ret != 0:
7
    raise RuntimeError(f"load_rknn failed: {ret}")
8

9
ret = runtime.init_runtime(core_mask=RKNNLite.NPU_CORE_AUTO)
10
if ret != 0:
11
    raise RuntimeError(f"init_runtime failed: {ret}")
12

13
try:
14
    outputs = runtime.inference(
15
        inputs=[input_tensor],
16
        data_format=["nhwc"],
17
    )
18
finally:
19
    runtime.release()

这里的 input_tensor 必须与 Toolkit2 验证脚本完全一致。Lite2 只运行 .rknn，不能加载 ONNX 后执行 build()。

三、RKNPU2 通用 C API 的生命周期#

完整流程可以记成：

1
rknn_init
2
→ rknn_query
3
→ 准备输入
4
→ rknn_inputs_set
5
→ rknn_run
6
→ rknn_outputs_get
7
→ 后处理
8
→ rknn_outputs_release
9
→ rknn_destroy

rknn_context 是贯穿整个流程的句柄。所有返回值都要检查，所有成功申请的资源都要在错误路径中释放。

四、读取模型并创建 Context#

模型可以先读入内存，再传给 rknn_init()：

1
#include <fstream>
2
#include <stdexcept>
3
#include <string>
4
#include <vector>
5
#include "rknn_api.h"
6

7
std::vector<unsigned char> LoadFile(const std::string& path) {
8
    std::ifstream file(path, std::ios::binary | std::ios::ate);
9
    if (!file) {
10
        throw std::runtime_error("cannot open model: " + path);
11
    }
12

13
    const auto size = file.tellg();
14
    if (size <= 0) {
15
        throw std::runtime_error("empty model: " + path);
16
    }
17

18
    std::vector<unsigned char> data(static_cast<size_t>(size));
19
    file.seekg(0, std::ios::beg);
20
    file.read(reinterpret_cast<char*>(data.data()), size);
21
    if (!file) {
22
        throw std::runtime_error("read model failed: " + path);
23
    }
24
    return data;
25
}
26

27
int main(int argc, char** argv) {
28
    if (argc < 2) return 1;
29

30
    auto model = LoadFile(argv[1]);
31
    rknn_context ctx = 0;
32

33
    int ret = rknn_init(&ctx, model.data(), model.size(), 0, nullptr);
34
    if (ret != RKNN_SUCC) {
35
        throw std::runtime_error("rknn_init failed: " + std::to_string(ret));
36
    }
37

38
    // query / inference / postprocess ...
39

40
    rknn_destroy(ctx);
41
    return 0;
42
}

正式工程应使用 RAII 封装 Context，确保异常或提前返回时也能执行 rknn_destroy()。

五、不要写死张量属性#

先查询输入输出数量：

1
rknn_input_output_num io_num{};
2
int ret = rknn_query(
3
    ctx,
4
    RKNN_QUERY_IN_OUT_NUM,
5
    &io_num,
6
    sizeof(io_num)
7
);

再逐个查询 Tensor：

1
std::vector<rknn_tensor_attr> input_attrs(io_num.n_input);
2
for (uint32_t i = 0; i < io_num.n_input; ++i) {
3
    input_attrs[i] = {};
4
    input_attrs[i].index = i;
5
    ret = rknn_query(
6
        ctx,
7
        RKNN_QUERY_INPUT_ATTR,
8
        &input_attrs[i],
9
        sizeof(rknn_tensor_attr)
10
    );
11
    if (ret != RKNN_SUCC) {
12
        throw std::runtime_error("query input attr failed");
13
    }
14
}

每个 Tensor 至少打印：

index 和 name；
n_dims、dims、元素数；
NHWC/NCHW；
UINT8/INT8/FLOAT16/FLOAT32；
量化类型、zero point 和 scale；
size、size_with_stride 和 w_stride。

后处理应依据查询结果验证模型契约，而不是看到“YOLO”就默认三个输出。

六、通用 API 输入、运行和输出#

1. 设置输入#

1
rknn_input input{};
2
input.index = 0;
3
input.buf = image_data;
4
input.size = image_bytes;
5
input.type = RKNN_TENSOR_UINT8;
6
input.fmt = RKNN_TENSOR_NHWC;
7
input.pass_through = 0;
8

9
ret = rknn_inputs_set(ctx, 1, &input);
10
if (ret != RKNN_SUCC) {
11
    throw std::runtime_error("rknn_inputs_set failed");
12
}

image_data 的实际 shape、通道、dtype 和预处理必须匹配模型。如果 RKNN 已内置均值和标准差，输入通常可以是预处理后的 UINT8 图像；不能再次手工标准化。

2. 执行推理#

1
ret = rknn_run(ctx, nullptr);
2
if (ret != RKNN_SUCC) {
3
    throw std::runtime_error("rknn_run failed");
4
}

3. 获取和释放输出#

1
std::vector<rknn_output> outputs(io_num.n_output);
2
for (uint32_t i = 0; i < io_num.n_output; ++i) {
3
    outputs[i] = {};
4
    outputs[i].index = i;
5
    outputs[i].want_float = 1;
6
}
7

8
ret = rknn_outputs_get(ctx, io_num.n_output, outputs.data(), nullptr);
9
if (ret != RKNN_SUCC) {
10
    throw std::runtime_error("rknn_outputs_get failed");
11
}
12

13
// 使用 outputs[i].buf 完成 Softmax、Top-K、解码或 NMS
14

15
rknn_outputs_release(ctx, io_num.n_output, outputs.data());

want_float=1 使用方便，但 Runtime 需要反量化/转换。高性能检测后处理可以保持 INT8 输出，并用查询到的 scale、zero point 自行计算：

1
float_value = (quant_value - zero_point) × scale

七、通用 API 的数据路径#

1
CPU buffer
2
→ rknn_inputs_set 复制/转换
3
→ NPU 推理
4
→ rknn_outputs_get 复制/转换
5
→ CPU 后处理

它的优点是简单可靠，适合作为正确性基线；缺点是高清、多路或高帧率时，输入输出搬运可能占据明显时间。

计时应至少拆成：

1
读取/解码 | 预处理 | 输入提交 | rknn_run | 输出获取 | 后处理 | 绘制/编码

八、零拷贝 C API#

零拷贝使用绑定到 Context 的 Tensor Memory：

1
rknn_tensor_mem* input_mem =
2
    rknn_create_mem(ctx, input_attr.size_with_stride);
3

4
rknn_tensor_mem* output_mem =
5
    rknn_create_mem(ctx, output_attr.size_with_stride);
6

7
if (!input_mem || !output_mem) {
8
    throw std::runtime_error("rknn_create_mem failed");
9
}
10

11
rknn_set_io_mem(ctx, input_mem, &input_attr);
12
rknn_set_io_mem(ctx, output_mem, &output_attr);
13

14
// 把输入写入 input_mem->virt_addr
15
rknn_run(ctx, nullptr);
16
// 从 output_mem->virt_addr 读取结果
17

18
rknn_destroy_mem(ctx, input_mem);
19
rknn_destroy_mem(ctx, output_mem);

完整函数声明和结构体以当前 release 的 RKNNRT C API 文档与头文件为准。

最容易踩坑的 stride#

width 是逻辑宽度，w_stride 是实际每行对齐宽度。二者不同时不能把整张图片直接连续复制：

1
for (int y = 0; y < height; ++y) {
2
    std::memcpy(
3
        dst + y * width_stride * channels,
4
        src + y * width * channels,
5
        width * channels
6
    );
7
}

分配大小应按 size_with_stride 或 API 查询值。使用外部 FD/物理内存时，还要按照 BSP/SDK 要求处理 Cache flush/invalidate。

“零拷贝”表示减少 RKNN 路径上的额外搬运，不代表摄像头、RGA、NPU、显示之间绝对没有任何数据移动。

九、交叉编译和板端运行#

官方 Model Zoo 已提供构建脚本，MobileNet 示例：

1
cd rknn_model_zoo
2
export GCC_COMPILER=<AARCH64_TOOLCHAIN_PREFIX>
3
./build-linux.sh -t rk3588 -a aarch64 -d mobilenet
4

5
adb push install/rk3588_linux_aarch64/rknn_mobilenet_demo/ /userdata/
6
adb shell
7
cd /userdata/rknn_mobilenet_demo
8
export LD_LIBRARY_PATH=./lib
9
./rknn_mobilenet_demo model/mobilenetv2-12.rknn model/bell.jpg

如果在板端原生编译，要确认 OpenCV、CMake 和 RKNN 头文件/库都是 AArch64 版本。交叉编译报 invalid ELF 通常表示链接到了错误架构的库。

十、把 Demo 重构成可维护工程#

推荐目录：

1
src/
2
├─ engine/
3
│  ├─ nn_engine.hpp       # 与硬件无关的引擎接口
4
│  └─ rknn_engine.cpp     # RKNPU2 实现
5
├─ tasks/
6
│  ├─ classification/     # Softmax、Top-K
7
│  └─ detection/          # 解码、阈值、NMS
8
├─ preprocess/            # resize/letterbox、颜色和 layout
9
├─ types/                 # Tensor、Detection、错误码
10
├─ utils/                 # 日志、计时、模型文件读取
11
└─ main.cpp               # 参数和业务流程

分层原则：

引擎层只负责模型和 Tensor，不知道“安全帽”或“公交车”；
任务层实现分类/检测后处理，不直接管理 RKNN Context；
业务层管理摄像头、队列、告警和输出；
使用 RAII、std::vector、智能指针明确资源所有权；
错误码区分模型加载、输入、推理、输出和后处理阶段。

十一、多 Context 和线程#

一个高吞吐视频系统通常是流水线：

1
解码线程
2
→ 有界输入队列
3
→ 多个推理 worker（每个独立 Context）
4
→ 有界结果队列
5
→ 后处理/显示/编码线程

注意：

不要让多个线程无保护地共享同一个 Context；
限制队列长度，避免延迟和内存无限增长；
为帧附带序号和时间戳；
明确实时模式是丢旧帧还是阻塞生产者；
统计吞吐的同时统计单帧端到端延迟；
退出时唤醒等待线程并释放全部 Context。

十二、本篇实践验收#

Lite2 能在板端复现 Toolkit2 的结果；
通用 C API 能正确查询 Tensor、推理和释放资源；
能解释 want_float、scale/zero point 和数据复制；
零拷贝结果与通用 API 在容差内一致；
工程按引擎、任务、预后处理和业务分层；
性能报告能区分预处理、NPU、后处理和端到端时间。

下一篇：RK3588 端侧 AI 部署（六）：MobileNet、YOLO 与 RKLLM 实战

纸翼