本文档记录了在 Windows/WSL 环境下，将训练好的 YOLO 模型（.pt）转换为 ONNX，再转换为 RK3588 NPU 上可执行的 RKNN 模型，并在 RK3588 开发板上完成推理的全流程，以及过程中遇到的各种问题及解决方案。

1、总体目标

• 输入：在 Windows 或阿里云服务器上训练得到的 best.pt 模型（YOLOv8/v11/v12 等）。

• 输出：在 RK3588 开发板 NPU 上运行的 best.rknn 模型，并实现目标检测推理。

• 核心步骤：1、.pt → ONNX（使用 ultralytics）

   			2、ONNX → RKNN（使用 rknn-toolkit2）
  
   			3、RKNN → RK3588 部署推理（使用 rknn-toolkit-lite2）
  

2、环境准备（PC端，模型转换）

2.1、使用 WSL（Windows Subsystem for Linux）

• 确认 WSL 版本：在 Windows PowerShell 中运行 wsl --version，版本 2.x 为最佳。
• 启动 WSL：在 Windows 终端中输入 wsl。
• 重要：转换工作不要在 /mnt/c/… 下进行，应切换到 Linux 原生文件系统（如 cd ~），以避免权限和 IO 性能问题。

2.2、安装 Miniconda

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
# 按提示安装，之后重启终端或 source ~/.bashrc

2.3、创建独立虚拟环境
RKNN-Toolkit2 官方推荐 Python 3.8。我们创建一个名为 rknn2 的环境。

conda create -n rknn2 python=3.8 -y
conda activate rknn2

3、导出 ONNX 模型```

如果你的 best.pt 已存在，在 rknn2 环境中安装必要的库并导出。

pip install ultralytics torch onnx onnxsim
yolo export model=best.pt format=onnx imgsz=640 simplify=True opset=13

• 成功后会生成 best.onnx。
• 注意：若导出时遇到 libgomp: Invalid value for environment variable OMP_NUM_THREADS，可忽略或执行 unset OMP_NUM_THREADS。

4、安装 RKNN-Toolkit2（PC端转换工具）```

4.1、获取最新版 RKNN-Toolkit2
下载链接链接https://gitcode.com/gh_mirrors/rk/rknn-toolkit2?source_module=search_result_repo

cd ~
git clone https://github.com/airockchip/rknn-toolkit2.git --depth 1
cd rknn-toolkit2/rknn-toolkit2/packages/x86_64

4.2、安装依赖与 whl 包
注意：不要使用旧版 requirements_cp38-1.6.0.txt，它会强制安装 TensorFlow 2.8.0 导致 tf-estimator-nightly 找不到。直接安装新版 whl 即可，新版已移除对 TF 的强制依赖。

pip install -r requirements.txt   # 如果存在则安装，新版目录下可能没有这个文件
# 更简单的方式：直接安装 whl，让 pip 自动处理依赖
pip install rknn_toolkit2-2.3.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl -i https://pypi.tuna.tsinghua.edu.cn/simple

4.3验证安装

python -c 'from rknn.api import RKNN; print("RKNN imported successfully!")'

5、ONNX 转 RKNN

创建转换脚本 onnx2rknn.py，内容如下：

from rknn.api import RKNN

ONNX_MODEL = 'best.onnx'
RKNN_MODEL = 'best.rknn'

rknn = RKNN(verbose=True)
rknn.config(mean_values=[[0,0,0]], std_values=[[255,255,255]], target_platform='rk3588')
ret = rknn.load_onnx(model=ONNX_MODEL)
if ret != 0:
    print("Load onnx failed")
    exit(ret)

# 先不进行量化，快速验证
ret = rknn.build(do_quantization=False)
if ret != 0:
    print("Build failed")
    exit(ret)

ret = rknn.export_rknn(RKNN_MODEL)
if ret != 0:
    print("Export failed")
    exit(ret)

rknn.release()
print("RKNN model exported successfully")

python onnx2rknn.py

Build RKNN model done
Export RKNN model success, saved as best.rknn

7、在 RK3588 上部署推理环境

7.1、安装 RKNN-Lite（板端推理库）
在 RK3588 终端（建议 Ubuntu 20.04/22.04）中：

# 创建 Python 3.8 虚拟环境
conda create -n rknn_deploy python=3.8 -y
conda activate rknn_deploy

# 安装必要依赖
pip install opencv-python-headless numpy psutil

# 安装 rknn-toolkit-lite2 (ARM 版本)
# 从官方仓库下载对应 whl 或直接使用 pip
pip install rknn-toolkit-lite2 -i https://pypi.tuna.tsinghua.edu.cn/simple

7.2、编写推理脚本
创建 infer.py，内容示例（简化后处理）：

import cv2
import numpy as np
from rknnlite.api import RKNNLite

def letterbox(img, new_shape=(640,640), color=(114,114,114)):
    # ... 实现 letterbox 预处理
    pass

def main():
    rknn = RKNNLite()
    rknn.load_rknn('./best.rknn')
    rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0)

    img = cv2.imread('test.jpg')
    img, ratio, pad = letterbox(img, (640,640))
    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    img_norm = img_rgb.astype(np.float32) / 255.0
    img_input = np.expand_dims(img_norm, axis=0)

    outputs = rknn.inference(inputs=[img_input])
    # 后处理（根据模型输出格式，YOLO 需要解码）
    # ...

    rknn.release()

if __name__ == '__main__':
    main()

python infer.py