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