從YOLOv5到RKNN：零沖突轉換YOLOv5模型至RK3588 NPU全指南
在嵌入式AI領域，將訓練好的深度學習模型高效部署到邊緣設備的NPU（神經網絡處理器）上是提升性能的關鍵。本文將詳細介紹如何在Ubuntu 20.04環境下，將YOLOv5l模型（.pt文件）通過ONNX中間格式，最終轉換為適用于RK3588 NPU的RKNN模型（.rknn文件），并全程采用環境隔離技術確保無依賴沖突。
一、準備工作：構建干凈的工作環境
環境污染是模型轉換過程中最常見的問題之一，因此我們首先創建一個全新的工作區，確保所有操作在干凈的環境中進行。
1. 清理與創建工作區
打開終端，執行以下命令清理可能存在的舊工作區并創建新的工作目錄：
# 回到主目錄
cd ~
# 刪除舊的工作區（如果存在）
rm -rf rknn_workspace
# 創建新工作區并進入
mkdir rknn_workspace
cd rknn_workspace
2. 準備核心文件
在新工作區內，我們需要準備四個關鍵組成部分：YOLOv5源代碼、預訓練模型、校準圖片集和圖片列表文件。
# 1. 克隆YOLOv5官方倉庫
git clone https://github.com/ultralytics/yolov5.git# 2. 下載yolov5l預訓練模型
wget https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5l.pt# 3. 創建圖片文件夾（用于模型量化校準）
mkdir images# 4. 生成圖片列表文件（后續量化會用到）
find "$(pwd)/images" -name "*.jpg" > dataset.txt
find "$(pwd)/images" -name "*.png" >> dataset.txt
完成后，執行ls命令檢查，確保工作區內包含以下內容：
- yolov5（文件夾）
- yolov5l.pt（模型文件）
- images（文件夾）
- dataset.txt（文件）
二、任務一：導出ONNX模型（隔離環境操作）
ONNX（Open Neural Network Exchange）是一種通用的模型中間格式，我們首先將PyTorch模型轉換為ONNX格式。為避免依賴沖突，這一步將在獨立的虛擬環境中進行。
1. 創建并激活虛擬環境
# 進入YOLOv5目錄
cd yolov5
# 創建虛擬環境
python3 -m venv onnx_export_venv
# 激活虛擬環境
source onnx_export_venv/bin/activate
激活成功后，終端提示符前會顯示(onnx_export_venv)，表示當前處于隔離環境中。
2. 安裝依賴庫
為加快下載速度并確保版本兼容，我們使用清華源并鎖定特定版本的ONNX庫：
# 配置清華源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 升級pip
pip install --upgrade pip
# 安裝YOLOv5依賴
pip install -r requirements.txt
# 安裝特定版本的ONNX（與RKNN工具兼容）
pip install onnx==1.12.0
3. 導出ONNX模型
將預訓練模型復制到當前目錄并執行導出命令：
# 復制模型文件到當前目錄
cp ../yolov5l.pt .# 導出ONNX模型（指定opset 11以確保兼容性）
python export.py --weights yolov5l.pt --include onnx --opset 11
4. 整理結果并清理環境
導出成功后，會生成yolov5l.onnx文件。我們將其移至工作區根目錄，然后銷毀當前虛擬環境（使命已完成）：
# 將ONNX模型移至工作區根目錄
mv yolov5l.onnx ../
# 退出虛擬環境
deactivate
# 返回工作區根目錄
cd ..
# 刪除虛擬環境（釋放空間）
rm -rf ./yolov5/onnx_export_venv
此時，工作區根目錄應已出現yolov5l.onnx文件，第一步轉換完成。
三、任務二：轉換為RKNN模型（獨立隔離環境）
接下來，我們在全新的虛擬環境中使用RKNN-Toolkit2將ONNX模型轉換為RK3588可識別的RKNN模型。
1. 創建并激活新虛擬環境
# 確保在rknn_workspace目錄下
python3 -m venv rknn_convert_venv
# 激活環境
source rknn_convert_venv/bin/activate
終端提示符前會顯示(rknn_convert_venv)，表示進入新的隔離環境。
2. 安裝RKNN-Toolkit2
# 配置清華源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 升級pip
pip install --upgrade pip
# 安裝指定版本的RKNN-Toolkit2（與RK3588兼容）
pip install rknn-toolkit2==2.3.2
該命令會自動安裝所有依賴的兼容版本庫，無需手動干預。
3. 準備轉換腳本
創建convert_rknn.py腳本，用于執行模型轉換：
nano convert_rknn.py
復制以下代碼到文件中：
from rknn.api import RKNNif __name__ == '__main__':rknn = RKNN(verbose=True)print('--> Config model')rknn.config(mean_values=[[0, 0, 0]],std_values=[[255, 255, 255]],target_platform='rk3588' # 指定目標平臺為RK3588)print('done')print('--> Loading model')ret = rknn.load_onnx(model='./yolov5l.onnx')if ret != 0:print('!!! Load yolov5l.onnx failed!')exit(ret)print('done')print('--> Building model')# 啟用量化，并指定校準數據集ret = rknn.build(do_quantization=True, dataset='./dataset.txt')if ret != 0:print('!!! Build yolov5l.rknn failed!')exit(ret)print('done')print('--> Export rknn model')ret = rknn.export_rknn('./yolov5l.rknn')if ret != 0:print('!!! Export yolov5l.rknn failed!')exit(ret)print('done')rknn.release()
保存并退出（按Ctrl+O，回車，再按Ctrl+X）。
4. 準備量化校準圖片
模型量化是提升NPU運行效率的關鍵步驟，需要20-30張代表性圖片作為校準數據。如果沒有現成圖片，可以從視頻中提取：
（1）安裝OpenCV用于視頻幀提取
pip install opencv-python
（2）創建視頻幀提取腳本
nano extract_frames.py
復制以下代碼：
import cv2
import os
import sys# 配置區 - 修改為你的視頻路徑
VIDEO_PATH = "/path/to/your/video.mp4" # 替換為實際視頻路徑
OUTPUT_DIR = "images"
NUM_FRAMES_TO_EXTRACT = 30 # 提取30幀def extract_frames():if not os.path.exists(VIDEO_PATH):print(f"錯誤: 視頻文件未找到! 路徑: {VIDEO_PATH}")sys.exit(1)if not os.path.exists(OUTPUT_DIR):os.makedirs(OUTPUT_DIR)cap = cv2.VideoCapture(VIDEO_PATH)total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))if total_frames == 0:print("錯誤: 無法讀取視頻或視頻為空。")cap.release()sys.exit(1)# 計算采樣間隔，確保均勻取幀interval = total_frames // NUM_FRAMES_TO_EXTRACTif interval == 0:interval = 1print(f"視頻總幀數: {total_frames}")print(f"計劃提取 {NUM_FRAMES_TO_EXTRACT} 幀, 間隔 {interval} 幀。")frame_count = 0extracted_count = 0while cap.isOpened() and extracted_count < NUM_FRAMES_TO_EXTRACT:ret, frame = cap.read()if not ret:breakif frame_count % interval == 0:output_filename = os.path.join(OUTPUT_DIR, f"frame_{extracted_count:04d}.jpg")cv2.imwrite(output_filename, frame)print(f"已保存: {output_filename}")extracted_count += 1frame_count += 1cap.release()print(f"\n提取完成! 共保存 {extracted_count} 張圖片到 '{OUTPUT_DIR}'。")if __name__ == "__main__":extract_frames()
（3）執行幀提取并更新數據集列表
# 修改腳本中的VIDEO_PATH為實際視頻路徑后執行
python3 extract_frames.py# 更新dataset.txt文件
find "$(pwd)/images" -name "*.jpg" > dataset.txt
find "$(pwd)/images" -name "*.png" >> dataset.txt
5. 執行RKNN轉換
一切準備就緒后，運行轉換腳本：
python3 convert_rknn.py
轉換過程會持續幾分鐘，成功完成后會顯示類似以下的日志：
I rknn-toolkit2 version: 2.3.2
...
I rknn building done.
done
--> Export rknn model
done
此時，工作區根目錄會生成yolov5l.rknn文件，這就是RK3588 NPU可直接使用的模型文件。
四、常見問題與解決方案
-
錯誤：Dataset file ./dataset.txt not found!
- 原因：未生成數據集列表文件或文件路徑錯誤
- 解決：確保images文件夾中有圖片，并重新執行dataset.txt生成命令
-
ONNX導出失敗
- 原因：YOLOv5版本與依賴庫不兼容
- 解決：使用本文指定的YOLOv5倉庫和onnx==1.12.0版本
-
RKNN轉換時量化失敗
- 原因：校準圖片數量不足或與模型場景不匹配
- 解決：確保提供20-30張與模型應用場景相符的圖片（如檢測交通場景則提供交通圖片）
五、總結與后續步驟
通過本文介紹的兩步隔離環境轉換法，我們成功將YOLOv5l模型轉換為RK3588 NPU適用的RKNN模型，全程避免了依賴沖突問題。轉換后的yolov5l.rknn文件可直接部署到RK3588設備。
后續步驟建議：
- 將
yolov5l.rknn傳輸到已安裝Ubuntu系統的RK3588開發板 - 使用RKNN-Toolkit2或RKNN Runtime API編寫推理腳本
- 在RK3588上測試模型性能與精度，必要時進行優化調整
這種隔離環境的轉換方法不僅適用于YOLOv5，也可推廣到其他深度學習模型的RKNN轉換過程，為嵌入式AI部署提供了可靠的技術參考。
)
