从零到一：在Ubuntu 20.04上构建完整的RKNN-Toolkit 1.6开发环境

最近有不少朋友在尝试将AI模型部署到瑞芯微（Rockchip）的NPU硬件上，比如RK1808、RK3399Pro这些开发板。这确实是个不错的思路，毕竟专用硬件能带来显著的推理加速。但第一步的环境搭建，往往就劝退了不少人。我自己在Ubuntu 20.04上折腾RKNN-Toolkit 1.6时，也踩了不少坑，尤其是那个有点“年迈”的TensorFlow 1.14.0依赖。这篇文章，我就把自己从系统准备、依赖安装、到最终验证成功的完整流程，以及中间遇到的各种“坑”和解决方案，详细地梳理一遍。无论你是刚接触边缘AI部署的新手，还是从其他平台迁移过来的开发者，希望这份手把手的记录能帮你少走弯路，快速把环境跑起来。

1. 环境准备与系统基础配置

在开始安装RKNN-Toolkit之前，确保你的Ubuntu 20.04系统处于一个干净、稳定的状态至关重要。我强烈建议在一个新安装的系统或者一个独立的虚拟环境（如Docker容器或虚拟机）中进行操作，这样可以避免与现有Python环境发生难以排查的冲突。

首先，更新系统包管理器并安装一些基础编译工具和库。这些是后续编译某些Python包或系统库所必需的。

sudo apt update
sudo apt upgrade -y
sudo apt install -y build-essential cmake git wget curl

接下来，我们需要处理Python环境。Ubuntu 20.04默认安装了Python 3.8，这对于RKNN-Toolkit 1.6来说是兼容的。但系统自带的pip版本可能较旧，我们需要先升级它。

sudo apt install -y python3-pip python3-dev
python3 -m pip install --upgrade pip

注意：这里我使用了 python3 -m pip 而不是直接调用 pip3，这可以确保我们调用的是与当前 python3 解释器关联的pip，避免因系统存在多个Python版本而导致混淆。

RKNN-Toolkit的图形化组件或某些底层库依赖于一些系统图形库。即使你打算在无图形界面的服务器上使用，安装它们也能避免一些潜在的导入错误。

sudo apt install -y libglib2.0-0 libsm6 libxrender1 libxext6 libgl1-mesa-glx

2. 安装RKNN-Toolkit 1.6：两种路径的深度解析

官方提供了手动安装和通过配置特定源自动安装两种方式。我两种都尝试过，各有优劣。手动安装可控性强，适合网络环境特殊或需要离线部署的场景；自动安装更便捷，但需要对pip源有完全的信任。

2.1 手动安装：步步为营的可靠之选

手动安装的核心在于获取正确的.whl安装包和对应的依赖清单文件。由于网络原因，从GitHub或官方分享的网盘下载可能速度不一，请提前准备好安装文件。

第一步：下载RKNN-Toolkit 1.6安装包 你需要找到名为 rknn_toolkit-1.6.0-cp3x-cp3x-linux_x86_64.whl 的文件（其中cp3x对应你的Python版本，如cp38）。同时下载同版本发布包中的 requirements-cpu.txt（或requirements-gpu.txt，如果你有NVIDIA GPU并配置了CUDA）。

第二步：安装Python依赖 进入存放上述文件的目录，首先安装需求文件中列出的所有依赖。这一步会安装numpy、opencv-python、protobuf等一系列包。

pip3 install --user -r requirements-cpu.txt

如果安装过程中有某个包版本冲突或安装失败，可以尝试单独安装并指定一个兼容的版本。例如，onnx的版本可能需要控制在1.x。

第三步：安装RKNN-Toolkit本体 依赖安装无误后，使用pip安装下载好的wheel文件。

pip3 install --user rknn_toolkit-1.6.0-cp38-cp38-linux_x86_64.whl

--user 参数会将包安装到当前用户的目录下（通常是 ~/.local/lib/python3.8/site-packages），避免了需要sudo权限，也更安全。

2.2 自动安装：配置官方源的快速通道

如果你能顺畅访问Rockchip的官方PyPI镜像，自动安装会简单很多。这需要你修改pip的配置，信任并添加该镜像源。

首先，创建或修改pip的配置文件。对于当前用户，可以在家目录下操作：

mkdir -p ~/.pip
vim ~/.pip/pip.conf

在 pip.conf 文件中输入以下内容：

[global]
index-url = http://repo.rock-chips.com/pypi/simple
trusted-host = repo.rock-chips.com
timeout = 120

保存退出后，你就可以直接通过pip命令安装RKNN-Toolkit了。安装时会自动解析并安装所有依赖。

pip3 install --user rknn-toolkit==1.6.0

提示：自动安装虽然方便，但在某些网络环境下，从非官方PyPI源下载包可能会遇到SSL证书问题或速度极慢的情况。如果安装失败，请检查网络连接，或回退到手动安装方式。

为了验证安装是否成功，可以打开Python解释器，尝试导入RKNN模块：

python3 -c "from rknn.api import RKNN; print('RKNN-Toolkit import successful')"

如果没有报错，恭喜你，RKNN-Toolkit的核心部分已经就位。

3. 攻克TensorFlow 1.14.0依赖的兼容性难题

这是整个安装过程中最容易出错的一环。RKNN-Toolkit 1.6内部的一些模型转换组件依赖于TensorFlow 1.14.0的特定API。在Python 3.8和Ubuntu 20.04的较新系统环境下，直接安装这个老版本的TensorFlow会遇到一系列问题。

核心矛盾点：

• TensorFlow 1.14.0官方预编译的wheel最高仅支持到Python 3.7。
• 一些底层依赖库（如numpy, protobuf）的新版本与TF 1.14.0不兼容。

我的解决方案是，在安装TF 1.14.0之前，主动降级其关键依赖的版本，并利用pip的灵活性寻找兼容的构建版本。

首先，安装一些必要的系统库，这些是TensorFlow编译或运行时可能用到的：

sudo apt install -y libhdf5-dev libc-ares-dev libeigen3-dev libatlas-base-dev

然后，在安装TensorFlow之前，先确保以下Python包的版本被锁定在兼容的范围内：

pip3 install --user 'numpy<1.19.0' 'protobuf<=3.20.3' 'h5py<3.0.0' 'keras-applications==1.0.8' 'keras-preprocessing==1.1.2'

关键就在这里：我们需要找到一个能为Python 3.8构建的TensorFlow 1.14.0版本。经过测试，可以从社区维护的源中安装一个兼容版本。使用以下命令：

pip3 install --user https://github.com/KumaTea/tensorflow-aarch64/releases/download/v1.14.0/tensorflow-1.14.0-cp38-cp38-linux_x86_64.whl

这个wheel文件并非官方发布，而是由社区为特定平台编译的。在安装前，请务必在测试环境中验证其稳定性和安全性。安装完成后，强烈建议进行功能验证：

import tensorflow as tf
print(tf.__version__)  # 应该输出 1.14.0
hello = tf.constant('Hello, TensorFlow!')
sess = tf.Session()
print(sess.run(hello))

如果上述代码能正常运行并输出字符串，说明TensorFlow 1.14.0已正确安装且基本功能正常。

4. 完整环境验证与实战踩坑记录

环境组件都装好了，但不代表就能顺利工作。我们需要一个端到端的测试来验证RKNN-Toolkit的模型转换和推理功能是否正常。这里我使用一个最简单的ONNX格式的MNIST分类模型作为例子。

第一步：准备测试模型和脚本 首先，下载一个预训练好的MNIST ONNX模型（例如 mnist-8.onnx，可从ONNX Model Zoo获取）。然后，创建一个名为 test_rknn.py 的Python脚本：

from rknn.api import RKNN

def main():
    # 初始化RKNN对象
    rknn = RKNN(verbose=True)

    # 配置模型预处理参数
    print('--> Config model')
    rknn.config(mean_values=[[0]], std_values=[[255]], target_platform='rk1808')
    
    # 加载ONNX模型
    print('--> Loading model')
    ret = rknn.load_onnx(model='./mnist-8.onnx')
    if ret != 0:
        print('Load model failed!')
        exit(ret)
    
    # 构建RKNN模型
    print('--> Building model')
    ret = rknn.build(do_quantization=False)  # 首次测试先关闭量化
    if ret != 0:
        print('Build model failed!')
        exit(ret)
    
    # 导出RKNN模型文件
    print('--> Export rknn model')
    ret = rknn.export_rknn('./mnist.rknn')
    if ret != 0:
        print('Export rknn model failed!')
        exit(ret)
    
    # 在PC上进行模拟推理测试
    print('--> Init runtime environment')
    ret = rknn.init_runtime()
    if ret != 0:
        print('Init runtime environment failed!')
        exit(ret)
    
    # 准备模拟输入数据（一个随机的28x28灰度图像）
    import numpy as np
    inputs = np.random.rand(1, 1, 28, 28).astype(np.float32)
    
    print('--> Running model')
    outputs = rknn.inference(inputs=[inputs])
    print('Simulation inference output:', outputs)
    
    # 释放资源
    rknn.release()
    print('Test done.')

if __name__ == '__main__':
    main()

第二步：运行测试并解读可能出现的错误 运行脚本：python3 test_rknn.py。如果一切顺利，你会看到模型加载、构建、导出、模拟推理的一系列成功日志，并最终输出一个推理结果。

但更常见的情况是遇到错误。下面我列举几个我遇到过的典型问题及解决思路：

• 错误：ImportError: libxxx.so.x: cannot open shared object file

  原因：缺少系统动态库。通常是图形库或数学库。 解决：根据缺失的库文件名（如libGL.so.1），使用 apt-file search 命令查找对应的包并安装。例如：sudo apt install libgl1-mesa-glx。

• 错误：在rknn.build()阶段卡住或报错

  原因：模型结构可能包含RKNN-Toolkit 1.6不支持的算子；或者TensorFlow环境不纯，存在版本冲突。 解决：首先确保TensorFlow是唯一的1.14.0版本（检查pip list | grep tensor）。其次，尝试一个更简单的模型，或者查阅Rockchip官方Wiki，确认该版本工具链支持的算子列表。

• 错误：模拟推理结果明显异常（如全零或NaN）

  原因：模型预处理配置（mean_values, std_values）与模型训练时的设置不符；或者输入数据格式不正确（RKNN默认期望CHW格式，即[通道，高，宽]）。 解决：仔细核对原始模型的预处理要求。使用 netron 工具打开ONNX模型，查看输入节点的名称和预期形状。调整rknn.config()中的参数和输入数据的reshape。

环境变量小技巧： 有时候，为了调试更深层次的问题，你可能需要设置一些环境变量来获取更多日志信息：

export RKNN_LOG_LEVEL=3  # 设置RKNN内部日志级别为DEBUG
export GLOG_minloglevel=0  # 启用所有Google Log (glog)输出

再次运行你的脚本，终端会打印出海量的调试信息，这对于定位模型转换流程中具体在哪一步失败非常有帮助。

5. 进阶配置与生产环境考量

当你完成了基础环境的搭建和验证后，如果计划投入到实际项目开发中，还需要考虑一些更深入的问题。

虚拟环境管理： 强烈建议使用 venv 或 conda 为每个项目创建独立的Python虚拟环境。这样可以完美隔离不同项目对RKNN-Toolkit甚至TensorFlow版本的依赖。例如：

python3 -m venv rknn_env
source rknn_env/bin/activate
# 在此虚拟环境中重复上述所有安装步骤
# 工作完成后，使用 `deactivate` 退出

Docker化部署： 对于团队协作或需要持续集成/持续部署（CI/CD）的场景，将整个环境Docker化是最佳实践。这能确保所有开发者和服务器运行的环境完全一致。下面是一个Dockerfile的简要示例：

FROM ubuntu:20.04

# 设置非交互式安装以避免tzdata等包卡住
ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y \
    python3.8 python3-pip python3.8-dev \
    libglib2.0-0 libsm6 libxrender1 libxext6 libgl1-mesa-glx \
    git wget \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /workspace

# 复制本地已下载的安装包，避免在容器内下载
COPY rknn_toolkit-1.6.0-cp38-cp38-linux_x86_64.whl .
COPY requirements-cpu.txt .

RUN pip3 install --upgrade pip && \
    pip3 install -r requirements-cpu.txt && \
    pip3 install rknn_toolkit-1.6.0-cp38-cp38-linux_x86_64.whl && \
    pip3 install 'numpy<1.19.0' 'protobuf<=3.20.3' && \
    pip3 install https://github.com/KumaTea/tensorflow-aarch64/releases/download/v1.14.0/tensorflow-1.14.0-cp38-cp38-linux_x86_64.whl

# 验证安装
RUN python3 -c "from rknn.api import RKNN; import tensorflow as tf; print('RKNN and TF import OK')"

使用 docker build 构建这个镜像，你就拥有了一个可移植、可复现的RKNN开发环境。

性能调优初探： RKNN-Toolkit的build函数中的do_quantization参数至关重要。量化能将FP32模型转换为INT8等低精度格式，在NPU上获得数倍的推理速度提升，但可能会带来轻微的精度损失。进行量化时，你需要准备一个代表性的校准数据集（通常是从训练集中抽取的几百张图片），并正确配置量化参数。

ret = rknn.build(do_quantization=True,
                  dataset='./calib_dataset.txt') # 数据集文件列表

calib_dataset.txt 文件内容每行是一张图片的路径。量化是一个专门的课题，涉及到精度、速度和模型结构的平衡，建议在基础环境稳定后，再深入研究和尝试。

环境搭建本身不是目的，而是一个起点。当你的Ubuntu 20.04系统上成功运行起第一个RKNN模型转换脚本时，真正的旅程——将AI模型高效部署到边缘设备——才刚刚开始。记住，这个过程中遇到的每一个错误提示，都是通往更深层次理解的线索。多查阅Rockchip的官方Wiki和GitHub Issues，那里的社区讨论常常隐藏着关键解决方案。