1. RK3566 跑 PaddleOCRv2 到底難在哪從模型轉(zhuǎn)換到板端推理的完整踩坑路徑RK3566 是一顆四核 Cortex-A55 的嵌入式 SoC自帶 0.8T 算力的 NPU很多人拿它做邊緣 OCR 盒子、閘機識別、工業(yè)讀碼器。PaddleOCRv2 是百度飛槳開源的 OCR 套件檢測模型 PP-OCRv2 det 加識別模型 PP-OCRv2 rec中文場景識別率在輕量模型里屬于第一梯隊。把這兩個東西湊到一起就是典型的「端側(cè) OCR 部署」需求板子本地出結(jié)果不依賴網(wǎng)絡(luò)延遲可控隱私數(shù)據(jù)不出設(shè)備。適合讀這篇的人有三類一是手上已經(jīng)有 RK3566 開發(fā)板比如 RK3566 核心板 底板、或者類似 EVB 板想跑通 OCR 的嵌入式工程師二是做過 NX、樹莓派、Jetson 部署第一次碰 RKNN 工具鏈的算法同學(xué)三是項目里既要端側(cè)識別、又想留一條云端兜底通道需要統(tǒng)一管理 Key 和調(diào)用的開發(fā)者。我試過在 NX 上用 TensorRT 部署 PaddleOCRv2整個過程一個下午就搞定了所以一開始以為 RK3566 也差不多結(jié)果前前后后折騰了一周多坑主要集中在三個地方paddle2onnx 轉(zhuǎn)模型時的動態(tài)維度、rknn.config 里 mean/std 參數(shù)的語義、以及板端 C 推理時輸入前處理的歸屬問題。這篇會按真實操作順序走一遍先在 PC 上把 Paddle 模型轉(zhuǎn)成 ONNX再轉(zhuǎn)成 RKNN然后 PC 連板驗證最后板端 C 推理。每一步都給可復(fù)制的命令和配置遇到報錯怎么定位也寫清楚。同時因為項目里還需要一條云端 OCR 通道做效果對比和兜底我會說明怎么用 TaoToken 的統(tǒng)一 Key 和 API 通道來管理云端調(diào)用這樣端側(cè)和云側(cè)可以放在同一套代碼框架里切換。先說結(jié)論性的經(jīng)驗RKNN 對動態(tài) shape 支持很差轉(zhuǎn)模型時必須固定輸入維度mean_values / std_values 不只是前處理參數(shù)它還會影響量化后的模型權(quán)重設(shè)置錯了量化模型直接廢掉板端推理時輸入到底做不做歸一化要和轉(zhuǎn)模型參數(shù)配套不能各做各的。下面逐段展開。2. 環(huán)境準(zhǔn)備與 TaoToken 統(tǒng)一 Key 通道端側(cè)云側(cè)兩條路怎么并行在動手轉(zhuǎn)模型之前先把兩邊的環(huán)境理清楚。端側(cè)這條線是 PCUbuntu 20.04 或 22.04 都行 RK3566 板子PC 上裝 PaddlePaddle、paddle2onnx、rknn-toolkit2板子上跑 rknpu2 的運行時庫。云側(cè)這條線是為了做效果對比和兜底用 TaoToken 的統(tǒng)一 Key 來調(diào)云端 OCR 或多模態(tài)模型避免每個服務(wù)單獨申請一套憑證。先說 PC 端環(huán)境。Paddle 版本建議 2.4 或 2.5和 PaddleOCRv2 的模型匹配。安裝命令python -m pip install paddlepaddle2.4.2 -i https://mirror.baidu.com/pypi/simple python -m pip install paddle2onnx1.0.5paddle2onnx 的版本別裝太新1.0.x 對 PaddleOCRv2 的算子支持最穩(wěn)。rknn-toolkit2 建議用 1.5.0 或 1.6.0對應(yīng)板端 rknpu2 的版本要一致版本錯配是后面很多詭異報錯的根源。安裝 rknn-toolkit2pip install rknn_toolkit2-1.5.0b2f0f9c0-cp38-cp38-linux_x86_64.whl板端這邊rknpu2 從 Rockchip 官方倉庫拉git clone https://github.com/rockchip-linux/rknpu2.git編譯板端推理程序時鏈接librknnrt.so頭文件在rknpu2/runtime/RK356X/Linux/librknn_api/include。交叉編譯工具鏈用板子 SDK 里自帶的aarch64-linux-gnu-gcc別用系統(tǒng) apt 裝的版本glibc 版本對不上會在板子上跑不起來。云側(cè)這條線TaoToken 的作用是把多家模型的調(diào)用收斂到一個入口。你可以在官網(wǎng)注冊后拿到統(tǒng)一 Key然后在控制臺里管理不同模型的權(quán)限。API 地址是https://taotoken.net/api兼容 OpenAI 風(fēng)格的請求格式所以端側(cè)代碼里如果已經(jīng)有一套 HTTP 客戶端改 Base URL 和 Key 就能接上。模型對話入口在https://taotoken.net/models接入文檔在https://taotoken.net/docAPI Key 管理在https://taotoken.net/api-keys。這幾個地址后面 CTA 會再提這里先記住結(jié)構(gòu)。為什么要在這個項目里引入云側(cè)通道因為端側(cè) RKNN 量化后識別率會掉尤其是手寫體、低對比度、傾斜文本這些場景。端側(cè)出結(jié)果后如果置信度低于閾值可以把圖片丟給云端模型復(fù)核這樣既保證實時性又保證準(zhǔn)確率。統(tǒng)一 Key 的好處是端側(cè)和云側(cè)用同一套憑證管理不用在板子上硬編碼多個服務(wù)的 Key換模型也不用改代碼結(jié)構(gòu)。環(huán)境準(zhǔn)備好之后目錄結(jié)構(gòu)建議這樣組織paddleocr_rk3566/ ├── models/ # 原始 Paddle 模型 ├── onnx/ # 轉(zhuǎn)換后的 ONNX ├── rknn/ # 轉(zhuǎn)換后的 RKNN ├── convert/ # 轉(zhuǎn)換腳本 ├── board_infer/ # 板端 C 推理 └── cloud_check/ # 云端對比腳本這樣后面每一步的輸入輸出路徑都清晰出問題好回溯。3. paddle2onnx 轉(zhuǎn)模型與 rknn.config 參數(shù)配置可復(fù)制的轉(zhuǎn)換腳本這一步是整個部署里坑最多的環(huán)節(jié)。先看 Paddle 轉(zhuǎn) ONNX。從 PaddleOCR 官方 release 里下載 PP-OCRv2 的檢測和識別模型檢測模型目錄里是inference.pdmodel和inference.pdiparams。轉(zhuǎn)換命令paddle2onnx --model_dir./det_ch_PP-OCRv2/ \ --model_filenameinference.pdmodel \ --params_filenameinference.pdiparams \ --save_file./det.onnx \ --opset_version11 \ --input_shape_dict{x: [1, 3, 480, 640]} \ --enable_onnx_checkerTrue注意這里input_shape_dict寫的是固定值[1, 3, 480, 640]不是原來的[-1, 3, -1, -1]。這是第一個坑RKNN 不支持動態(tài)輸入轉(zhuǎn) ONNX 時如果保留 -1后面轉(zhuǎn) RKNN 會直接報 shape 相關(guān)的錯或者轉(zhuǎn)出來推理結(jié)果全亂。檢測模型固定成 480x640 影響不大因為檢測本身對分辨率有一定容忍度。識別模型就麻煩了。PaddleOCR 的識別模型輸入是[-1, 3, 32, -1]高度固定 32寬度不定因為不同文本的寬高比差異很大。如果強行固定成[1, 3, 32, 96]長文本會被壓縮變形識別率暴跌。我試過兩種方案方案一是固定一個較大的寬高比比如[1, 3, 32, 320]然后對待識別文本做邊緣填充而不是直接 resize。優(yōu)點是簡單缺點是寬高比小的文本浪費大量計算。方案二是按幾個典型寬高比轉(zhuǎn)多個模型比如 32x96、32x160、32x320、32x480推理時根據(jù)文本實際寬高比選最接近的模型。優(yōu)點是省時缺點是要同時加載多個模型內(nèi)存占用高。這里踩了第二個坑識別模型輸入寬度設(shè)得太小時PC 連板推理會卡在rknn.init_runtime()不動也不報錯。實測寬度大于 96 才能正常轉(zhuǎn)換和推理具體下限沒細(xì)測建議最小設(shè) 96。ONNX 轉(zhuǎn) RKNN 的腳本關(guān)鍵是rknn.config的參數(shù)from rknn.api import RKNN rknn RKNN(verboseTrue) rknn.config( mean_values[[127.5, 127.5, 127.5]], std_values[[127.5, 127.5, 127.5]], target_platformrk3566, quantized_dtypeasymmetric_quantized-8, optimization_level3 ) rknn.load_onnx(model./det.onnx) rknn.build(do_quantizationTrue, dataset./quant_dataset.txt) rknn.export_rknn(./det.rknn) rknn.release()quant_dataset.txt里放幾十張代表性圖片的路徑量化校準(zhǔn)用。這里就是第三個坑也是我卡最久的mean_values和std_values不只是對輸入做前處理它還會影響量化后的模型權(quán)重。我一開始設(shè)成[0,0,0]和[1,1,1]因為我在輸入數(shù)據(jù)里已經(jīng)做了 BGR2RGB、0-255 轉(zhuǎn) 0-1、再減均值除方差。結(jié)果 PC 連板推理的 fp16 模型正常int8 量化模型效果極差板端 C 推理的 fp16 模型也是錯的。同一個模型不同接口結(jié)果不一樣說明問題出在轉(zhuǎn)換參數(shù)而不是推理代碼。后來參考 PaddleOCR 在 RV1106 上的部署配置發(fā)現(xiàn)人家輸入直接喂 uint8 圖像不做額外前處理轉(zhuǎn)模型參數(shù)設(shè)mean_values[127,127,127]、std_values[127,127,127]。我改成這樣之后去掉輸入端的歸一化只保留 resize 和 BGR2RGBfp16 和 int8、PC 連板和板端全部正常。進一步測試發(fā)現(xiàn)規(guī)律輸入不做前處理時mean/std 設(shè)[0,0,0]/[1,1,1]檢測模型什么都檢不到輸入做了前處理時只有 mean/std 接近[0,0,0]/[1,1,1]才有結(jié)果。所以正確理解是mean/std 要按模型訓(xùn)練時的均值方差從 0-1 范圍換算到 0-255 范圍來設(shè)同時輸入端不要再重復(fù)做歸一化。PaddleOCR 訓(xùn)練時用的均值是[0.485, 0.456, 0.406]乘以 255 約等于[123.7, 116.3, 103.5]標(biāo)準(zhǔn)差[0.229, 0.224, 0.225]乘以 255 約等于[58.4, 57.1, 57.4]。實際用[127.5,127.5,127.5]也能跑因為量化校準(zhǔn)會吸收一部分差異。識別模型的轉(zhuǎn)換腳本同理只是輸入 shape 換成對應(yīng)的固定寬度。把檢測和識別都轉(zhuǎn)成 rknn 后PC 連板驗證ret rknn.init_runtime(targetrk3566) outputs rknn.inference(inputs[img])如果init_runtime卡住先檢查識別模型寬度是不是小于 96再檢查板子和 PC 的 adb 連接是否正常。4. 板端 C 推理驗證從 rknpu2 到實際識別結(jié)果PC 連板驗證通過后就要把推理搬到板子上跑 C。從 rknpu2 倉庫里參考examples/ssd的 demo 結(jié)構(gòu)主要流程是加載 rknn 模型、初始化輸入輸出、預(yù)處理圖像、推理、后處理。加載模型rknn_context ctx; int ret rknn_init(ctx, model_path, 0, 0, nullptr);查詢輸入輸出屬性rknn_input_output_num io_num; rknn_query(ctx, RKNN_QUERY_IN_OUT_NUM, io_num, sizeof(io_num));設(shè)置輸入時注意數(shù)據(jù)類型要和轉(zhuǎn)模型時一致。因為我們轉(zhuǎn)模型時輸入是 uint8 圖像mean/std 在模型內(nèi)部處理所以板端喂進去的就是 resize 和 BGR2RGB 之后的 uint8 數(shù)據(jù)不要再做 0-1 歸一化cv::Mat img cv::imread(image_path); cv::cvtColor(img, img, cv::COLOR_BGR2RGB); cv::resize(img, img, cv::Size(640, 480)); rknn_input inputs[1]; inputs[0].index 0; inputs[0].type RKNN_TENSOR_UINT8; inputs[0].size img.total() * img.elemSize(); inputs[0].fmt RKNN_TENSOR_NHWC; inputs[0].buf img.data; rknn_inputs_set(ctx, 1, inputs); rknn_run(ctx, nullptr);輸出后處理按 PaddleOCR 的 DB 檢測和 CTC 識別邏輯寫。檢測輸出是概率圖做二值化和輪廓提取得到文本框識別輸出是序列做 CTC 解碼得到文本。這部分代碼量不小可以直接參考我放在 GitHub 上的實現(xiàn)倉庫地址在文末。編譯命令aarch64-linux-gnu-g main.cpp -o ocr_demo \ -I./rknpu2/runtime/RK356X/Linux/librknn_api/include \ -L./rknpu2/runtime/RK356X/Linux/librknn_api/aarch64 \ -lrknnrt -lopencv_core -lopencv_imgproc -lopencv_imgcodecs把可執(zhí)行文件和 rknn 模型、librknnrt.so一起推到板子上adb push ocr_demo /userdata/ adb push det.rknn /userdata/ adb push rec.rknn /userdata/ adb push librknnrt.so /usr/lib/ adb shell chmod x /userdata/ocr_demo adb shell /userdata/ocr_demo /userdata/test.jpg實測下來一張 640x480 的圖片檢測加識別在 RK3566 上大約 200-400ms具體取決于文本框數(shù)量和識別模型寬度。如果結(jié)果不對先確認(rèn)板端輸入是不是 uint8 且沒做歸一化再確認(rèn)轉(zhuǎn)模型時的 mean/std 設(shè)置這兩個對上了基本就正常。云端對比這條線用 TaoToken 的 API 調(diào)一次多模態(tài)模型把同一張圖傳上去對比端側(cè)和云側(cè)的識別文本。請求示例curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [ {role: user, content: [ {type: text, text: 識別這張圖片里的文字只輸出文字內(nèi)容}, {type: image_url, image_url: {url: data:image/jpeg;base64,$(base64 -w0 test.jpg)}} ]} ] }這樣端側(cè)和云側(cè)的結(jié)果可以放在一起對比端側(cè)置信度低的時候自動走云端復(fù)核。5. 常見報錯排查401、local proxy failed、reading choices、OAuth 對照部署過程中遇到的報錯分兩類端側(cè) RKNN 相關(guān)的和云側(cè) API 調(diào)用相關(guān)的。逐個對照。報錯一rknn_init_runtime卡死無輸出。最常見原因是識別模型輸入寬度太小小于 96 時會出現(xiàn)。解決方法是重新轉(zhuǎn)模型寬度至少設(shè) 96建議 160 或 320。另一個原因是板子和 PC 的 adb 連接不穩(wěn)定adb devices確認(rèn)設(shè)備在線。報錯二量化模型識別結(jié)果亂碼fp16 正常。這是 mean/std 設(shè)置問題。檢查轉(zhuǎn)模型腳本里的mean_values和std_values如果輸入端已經(jīng)做了歸一化轉(zhuǎn)模型參數(shù)要設(shè)成[0,0,0]/[1,1,1]如果輸入端喂 uint8轉(zhuǎn)模型參數(shù)要設(shè)成接近[127.5,127.5,127.5]/[127.5,127.5,127.5]。兩者必須配套不能一邊歸一化一邊又設(shè)大均值。報錯三local proxy failed或連接超時。這是云側(cè) API 調(diào)用時的網(wǎng)絡(luò)問題。先確認(rèn)板子或 PC 能正常訪問外網(wǎng)再檢查請求地址是不是https://taotoken.net/api注意 API 地址不帶 UTM 參數(shù)。如果是在板子上直接調(diào)云端確認(rèn)板子的 DNS 配置正確ping taotoken.net能通。報錯四HTTP 401 Unauthorized。Key 無效或沒帶上。檢查請求頭Authorization: Bearer $TAOTOKEN_API_KEYKey 從https://taotoken.net/api-keys獲取。注意 Key 不要硬編碼在板端代碼里建議通過環(huán)境變量或配置文件注入。如果 Key 泄露在控制臺里吊銷重新生成。報錯五reading choices相關(guān)解析錯誤。這是響應(yīng) JSON 解析問題通常是請求格式不對或者模型名寫錯。確認(rèn)model字段是控制臺里已開通的模型 ID請求體是合法的 JSON。如果返回內(nèi)容為空檢查messages結(jié)構(gòu)是否符合 OpenAI 兼容格式。報錯六OAuth 相關(guān)錯誤。如果用的是需要 OAuth 的客戶端比如某些 IDE 插件或 CLI 工具確認(rèn)回調(diào)地址和客戶端配置正確。TaoToken 的 API Key 方式不需要 OAuth直接用 Bearer Token 即可。如果用 Claude Code 這類工具配置 Base URL 為https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填控制臺里對應(yīng)的模型。排查順序建議先確認(rèn)端側(cè)模型轉(zhuǎn)換參數(shù)對不對再確認(rèn)板端輸入前處理配套最后查云側(cè)網(wǎng)絡(luò)和 Key。端側(cè)問題看日志和推理結(jié)果云側(cè)問題看 HTTP 狀態(tài)碼和響應(yīng)體。6. 端側(cè)云側(cè)協(xié)同的下一步統(tǒng)一 Key 管理與長期編碼方案端側(cè) RK3566 跑 PaddleOCRv2 這條路走通之后實際項目里通常還要考慮幾件事模型更新怎么下發(fā)、端側(cè)識別率不夠時怎么兜底、多個服務(wù)怎么統(tǒng)一管理憑證。模型更新可以通過 OTA 把新的 rknn 文件推到板子上代碼里做版本檢查。端側(cè)兜底就是前面說的置信度低于閾值時把圖片傳給云端模型復(fù)核用 TaoToken 的統(tǒng)一 Key 調(diào)多模態(tài)模型返回文本和端側(cè)結(jié)果做融合。統(tǒng)一 Key 管理的價值在這里體現(xiàn)得比較明顯端側(cè)代碼、云側(cè)對比腳本、后臺管理工具都用同一套 Key 和 Base URL換模型只改 Model ID不用改認(rèn)證邏輯。TaoToken 的控制臺可以看調(diào)用量和余額API Key 可以按項目分多個權(quán)限也能單獨控制。如果你后面要做長期的編碼或 Agent 類項目比如讓模型自動寫板端推理代碼、自動生成轉(zhuǎn)換腳本可以考慮 Coding Plan 這類方案把編碼任務(wù)也收斂到統(tǒng)一通道里。模型對話入口適合做單次驗證和效果對比接入文檔里有各語言的示例代碼。最后把關(guān)鍵地址再列一次方便直接取用官網(wǎng)https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPIhttps://taotoken.net/api模型對話https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文檔https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content板端 C 推理的完整代碼和轉(zhuǎn)換腳本可以參考 GitHub 倉庫zwenyuan1/PaddleOCRv2_rk3566里面有檢測和識別的完整實現(xiàn)。踩過的坑基本都寫在注釋里了遇到類似問題可以先對照排查。