1. RK3588 上 ONNX 轉(zhuǎn) RKNN 到底卡在哪如果你手里有一塊 RK3588 開發(fā)板想把訓(xùn)練好的 ONNX 模型跑起來大概率會經(jīng)歷這么一條鏈路PC 上導(dǎo)出 ONNX裝 rknn-toolkit2寫轉(zhuǎn)換腳本量化校準(zhǔn)導(dǎo)出 rknn拷到板子上用 rknn-toolkit-lite2 或 C API 推理。聽起來線性實際每一步都有坑。我見過最多的三類問題一是 Ubuntu 環(huán)境里 rknn-toolkit2 和 numpy、torch 版本打架import 就報錯二是 INT8 量化時 dataset.txt 路徑寫錯或者圖片數(shù)量太少build 階段直接失敗三是模型轉(zhuǎn)出來了板端推理結(jié)果和 PC 上對不上精度掉得離譜。這篇就按 0 到 1 的節(jié)奏走一遍從 ONNX 準(zhǔn)備、Ubuntu 22.04 環(huán)境、rknn-toolkit2 安裝、config.toml 骨架、INT8 校準(zhǔn)、轉(zhuǎn)換腳本到板端驗證。同時把 TaoToken 的統(tǒng)一 Key/API 通道配置嵌進(jìn)來方便你在調(diào)試階段用模型對話快速核對輸出語義或者用 Coding Plan 讓 Agent 幫你改轉(zhuǎn)換腳本里的參數(shù)。目標(biāo)很明確你跟著做能拿到一個能在 RK3588 上跑通的 rknn 文件并且知道精度怎么對比。2. 前置準(zhǔn)備ONNX 模型、Ubuntu 環(huán)境與 TaoToken 統(tǒng)一 Key2.1 ONNX 模型從哪來以 YOLO11 為例官方倉庫里一般會提供導(dǎo)出腳本。你在訓(xùn)練環(huán)境里執(zhí)行導(dǎo)出得到y(tǒng)olo11.onnx。注意導(dǎo)出時的 opset 建議 12 或 13RKNN 對高版本 opset 支持有限。導(dǎo)出后可以用onnxsim簡化一下減少轉(zhuǎn)換時的算子兼容問題pip install onnx onnxsim python -m onnxsim yolo11.onnx yolo11_sim.onnx簡化完把yolo11_sim.onnx拷到 Ubuntu 22.04 的轉(zhuǎn)換機(jī)上。轉(zhuǎn)換機(jī)可以是 x86 的 Ubuntu不一定要在 RK3588 板子上做轉(zhuǎn)換板子算力做轉(zhuǎn)換會很慢。2.2 Ubuntu 22.04 環(huán)境要點rknn-toolkit2 對 Python 版本敏感官方推薦 3.8 到 3.10。Ubuntu 22.04 默認(rèn) Python 3.10基本可用。建議用 conda 或 venv 隔離conda create -n rknn python3.10 -y conda activate rknn pip install numpy1.26.4 pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cpunumpy 不要裝 2.xrknn-toolkit2 目前對 numpy 2.x 兼容性差import 時會報_ARRAY_API not found之類的錯。這是踩過的坑里最常見的一個。2.3 TaoToken 統(tǒng)一 Key 在這里的作用轉(zhuǎn)換腳本調(diào)試階段你經(jīng)常需要確認(rèn)模型輸入輸出語義、量化前后輸出差異。這時候可以用 TaoToken 的統(tǒng)一 Key 走模型對話通道把 ONNX 的輸入輸出 shape、量化參數(shù)貼進(jìn)去讓模型幫你判斷配置是否合理。TaoToken 的 API 地址是https://taotoken.net/apiKey 在控制臺生成。你只需要一個 Key就能同時用模型對話、Coding Plan 和 API 通道不用在多個平臺之間切換。具體操作登錄 TaoToken 控制臺在 API Keys 頁面創(chuàng)建一個 Key復(fù)制保存。然后在你的調(diào)試腳本或終端里配置環(huán)境變量export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你要用 Coding Plan 讓 Agent 幫你改convert_int8.py里的量化參數(shù)可以在 Coding Plan 頁面綁定這個 KeyAgent 會直接讀取你的腳本上下文。模型對話入口在模型對話頁面適合快速驗證「asymmetric_quantized-8 和 quantized_dtype 的區(qū)別」這類問題。3. 可復(fù)制配置config.toml 骨架與轉(zhuǎn)換腳本3.1 config.toml 骨架把轉(zhuǎn)換相關(guān)的路徑、平臺、量化參數(shù)集中到一個 config.toml 里腳本讀配置改參數(shù)不用動代碼[model] onnx_path ./yolo11_sim.onnx rknn_path ./yolo11_int8.rknn platform rk3588 [quant] do_quantization true quantized_dtype asymmetric_quantized-8 optimization_level 3 dataset_file ./dataset.txt num_samples 50 [preprocess] mean_values [[0, 0, 0]] std_values [[255, 255, 255]] [taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY這個骨架覆蓋了 RK3588 上 INT8 量化的核心參數(shù)。quantized_dtype選asymmetric_quantized-8是 RK3588 上精度和速度比較平衡的模式optimization_level3讓 RKNN 做更多圖優(yōu)化。3.2 生成校準(zhǔn)數(shù)據(jù)集 dataset.txtINT8 量化需要一批圖片做校準(zhǔn)20 到 100 張即可。寫個腳本從訓(xùn)練集里隨機(jī)抽import os import random IMAGE_DIR ./dataset OUTPUT_FILE dataset.txt NUM_SAMPLES 50 VALID_EXTS (.jpg, .jpeg, .png, .bmp) if __name__ __main__: if not os.path.exists(IMAGE_DIR): print(f錯誤: 找不到文件夾 {IMAGE_DIR}) exit(1) image_list [] for root, dirs, files in os.walk(IMAGE_DIR): for file in files: if file.lower().endswith(VALID_EXTS): file_path os.path.join(root, file).replace(\\, /) image_list.append(file_path) total len(image_list) print(f共找到 {total} 張圖片) if total 0: print(錯誤: 文件夾里沒有圖片) exit(1) selected random.sample(image_list, NUM_SAMPLES) if total NUM_SAMPLES else image_list with open(OUTPUT_FILE, w, encodingutf-8) as f: for p in selected: f.write(p \n) print(f成功生成 {OUTPUT_FILE}包含 {len(selected)} 張圖片)跑完得到dataset.txt每行一個圖片路徑。路徑建議用相對路徑避免換機(jī)器后失效。3.3 轉(zhuǎn)換腳本 convert_int8.py讀 config.toml調(diào) RKNN APIimport sys import os import toml from rknn.api import RKNN def load_config(pathconfig.toml): with open(path, r, encodingutf-8) as f: return toml.load(f) if __name__ __main__: cfg load_config() onnx_model cfg[model][onnx_path] rknn_model cfg[model][rknn_path] platform cfg[model][platform] dataset_file cfg[quant][dataset_file] if not os.path.exists(dataset_file): print(f錯誤: 找不到 {dataset_file}) sys.exit(1) rknn RKNN(verboseTrue) print(-- Config model) rknn.config( mean_valuescfg[preprocess][mean_values], std_valuescfg[preprocess][std_values], target_platformplatform, quantized_dtypecfg[quant][quantized_dtype], optimization_levelcfg[quant][optimization_level] ) print(done) print(-- Loading model) ret rknn.load_onnx(modelonnx_model) if ret ! 0: print(Load model failed!) sys.exit(ret) print(done) print(-- Building model) ret rknn.build( do_quantizationcfg[quant][do_quantization], datasetdataset_file ) if ret ! 0: print(Build model failed!) sys.exit(ret) print(done) print(-- Export rknn model) ret rknn.export_rknn(rknn_model) if ret ! 0: print(Export rknn model failed!) sys.exit(ret) print(f成功! 模型已導(dǎo)出為: {rknn_model}) rknn.release()執(zhí)行python convert_int8.py如果 build 階段報dataset相關(guān)錯誤先檢查 dataset.txt 里的路徑是否都能訪問圖片格式是否被 RKNN 支持。RKNN 對 jpg、png 支持較好bmp 偶爾有兼容問題。4. 驗證請求與成功結(jié)果PC 模擬 板端推理4.1 PC 端模擬推理rknn-toolkit2 支持在 PC 上模擬推理不用板子就能先驗證模型是否正常from rknn.api import RKNN rknn RKNN() ret rknn.load_rknn(./yolo11_int8.rknn) if ret ! 0: print(Load rknn failed!) exit(ret) ret rknn.init_runtime() if ret ! 0: print(Init runtime failed!) exit(ret) import cv2 import numpy as np img cv2.imread(./test.jpg) img cv2.resize(img, (640, 640)) img cv2.cvtColor(img, cv2.COLOR_BGR2RGB) outputs rknn.inference(inputs[img]) print(推理輸出 shape:, [o.shape for o in outputs]) rknn.release()PC 模擬能跑通說明模型結(jié)構(gòu)和量化沒大問題。如果這里就報錯先別急著上板。4.2 板端推理驗證把yolo11_int8.rknn拷到 RK3588 開發(fā)板用 rknn-toolkit-lite2 跑pip install rknn-toolkit-lite2from rknnlite.api import RKNNLite rknn_lite RKNNLite() ret rknn_lite.load_rknn(./yolo11_int8.rknn) if ret ! 0: print(Load rknn failed!) exit(ret) ret rknn_lite.init_runtime(core_maskRKNNLite.NPU_CORE_0) if ret ! 0: print(Init runtime failed!) exit(ret) import cv2 import numpy as np img cv2.imread(./test.jpg) img cv2.resize(img, (640, 640)) img cv2.cvtColor(img, cv2.COLOR_BGR2RGB) outputs rknn_lite.inference(inputs[img]) print(板端推理輸出 shape:, [o.shape for o in outputs]) rknn_lite.release()成功的話你會看到輸出 shape 和 PC 模擬一致。RK3588 有三個 NPU corecore_mask可以指定用哪個單核跑不通時試試RKNNLite.NPU_CORE_0_1_2。4.3 精度對比動作INT8 量化后精度會掉一點關(guān)鍵看掉多少。對比方法同一張圖分別用 ONNX 模型和 rknn 模型推理算輸出余弦相似度或最大絕對誤差。如果余弦相似度低于 0.95說明量化損失偏大可以增加校準(zhǔn)圖片數(shù)量、調(diào)整optimization_level或者對敏感層保留 FP16。5. 本篇常見錯排查5.1 import rknn 報 numpy 版本錯報錯類似AttributeError: module numpy has no attribute float。原因是 numpy 2.x 移除了np.float。降級到 1.26.4pip install numpy1.26.45.2 build 階段 dataset 報錯報錯The dataset file is not exist或Invalid dataset。檢查三點dataset.txt 路徑是否正確、每行路徑是否可訪問、圖片是否能被 cv2 正常讀取?？梢韵扔媚_本遍歷 dataset.txt 逐張cv2.imread驗證。5.3 板端 init_runtime 失敗報錯Init runtime environment failed。常見原因是板子 NPU 驅(qū)動版本和 rknn-toolkit-lite2 版本不匹配。用cat /sys/kernel/debug/rknpu/version看驅(qū)動版本然后裝對應(yīng)版本的 lite2。另外確認(rèn)板子有權(quán)限訪問/dev/rknpu。5.4 推理結(jié)果全零或異常先確認(rèn)預(yù)處理是否一致PC 模擬和板端用的 mean/std 必須和轉(zhuǎn)換時 config 里一致。YOLO 系列常見的是 BGR 轉(zhuǎn) RGB 漏了或者歸一化系數(shù)寫錯。用同一張圖在 PC 模擬和板端分別跑逐層對比輸出定位是哪一層開始偏的。5.5 TaoToken 通道配置報 401如果你在調(diào)試腳本里調(diào) TaoToken API 做語義核對報 401 說明 Key 沒讀到。檢查環(huán)境變量TAOTOKEN_API_KEY是否 export 成功或者直接在腳本里讀 config.toml 的api_key_env字段。TaoToken 的 API 地址是https://taotoken.net/api不要漏掉/api路徑。6. 繼續(xù)跑通全鏈路的下一步模型轉(zhuǎn)出來只是第一步。接下來你可以做幾件事用 TaoToken 的模型對話通道把板端推理的原始輸出貼進(jìn)去讓模型幫你寫后處理代碼比如 YOLO 的 NMS 和框解碼或者用 Coding Plan 讓 Agent 基于你的convert_int8.py生成一個批量轉(zhuǎn)換腳本一次跑多個模型。API Keys 頁面生成的 Key 在模型對話、Coding Plan、API 通道之間通用不用重復(fù)申請。板端性能調(diào)優(yōu)方面RK3588 支持多核 NPU 并行你可以把core_mask設(shè)成RKNNLite.NPU_CORE_0_1_2看吞吐提升。如果模型有動態(tài) shape 需求RKNN 對動態(tài) shape 支持有限建議在 ONNX 導(dǎo)出時就固定輸入尺寸。精度不夠時優(yōu)先增加校準(zhǔn)集多樣性而不是盲目調(diào)optimization_level。轉(zhuǎn)換腳本里的config.toml骨架可以直接復(fù)用到其他模型改路徑和平臺就行。