戰(zhàn)：從模型轉(zhuǎn)換到C++推理全流程指南)
在驍龍平臺(tái)做AI推理最忌諱的是把模型拿來直接在CPU上跑一遍就宣布完事硬件加速能力一點(diǎn)都沒用上。Qualcomm QNN SDK本來就提供了一整套從模型轉(zhuǎn)換、量化到C/C運(yùn)行時(shí)調(diào)用的工具鏈大多數(shù)人卡住的地方其實(shí)就兩個(gè)模型不知道怎么轉(zhuǎn)成QNN格式C代碼不知道從哪個(gè)接口下手。這篇文章把這條路完整走一遍從環(huán)境準(zhǔn)備到代碼解析最后再到排坑你可以把它當(dāng)成一份能照著跑的作業(yè)。1. 項(xiàng)目全景與方案設(shè)計(jì)先從QNN的整體架構(gòu)說起動(dòng)手寫代碼之前先把QNN這套東西的地圖畫出來。很多人被QNN勸退不是因?yàn)榇a難寫而是因?yàn)楦拍畈皇臁Ｒ活^扎進(jìn)去看到一堆Handle、Descriptor、Profile直接就懵了。其實(shí)QNN的架構(gòu)分得非常清晰理解了那幾條主線后面所有代碼都只是在跟這幾條主線打交道。1.1 QNN SDK到底是什么為什么選它QNN SDK是高通提供的神經(jīng)網(wǎng)絡(luò)推理SDK跑在驍龍平臺(tái)上時(shí)它能把模型調(diào)度到Hexagon DSP或者HTPHexagon Tensor Processor上執(zhí)行。HTP是高通專門為AI推理設(shè)計(jì)的硬件加速單元比CPU省電吞吐能力高出好幾個(gè)量級(jí)。常見的分類、檢測(cè)、分割模型經(jīng)過合理量化之后在HTP上都能跑得飛快。從架構(gòu)上看QNN分兩層一層是Host側(cè)也就是你的C應(yīng)用跑在CPU上的部分另一層是Device側(cè)也就是跑在DSP/HTP上的部分。Host側(cè)通過QNN提供的Backend接口跟Device側(cè)打交道。像libQnnHtp.so就是HTP的Backend實(shí)現(xiàn)庫(kù)你的程序通過dlopen或者運(yùn)行時(shí)鏈接的方式加載它然后調(diào)用統(tǒng)一的QNN接口剩下的調(diào)度工作全部交給SDK完成。很多人會(huì)問既然有TFLite、ONNX Runtime這些跨平臺(tái)框架為什么還要折騰QNN原因很簡(jiǎn)單模型要跑得夠快夠省電就必須直接調(diào)用硬件能力?？缙脚_(tái)框架為了兼容性往往走的是通用優(yōu)化路徑對(duì)特定硬件的利用程度有限。QNN能直接操作DSP/HTP上的張量緩沖區(qū)和執(zhí)行流水線量化模型跑起來經(jīng)常比CPU快一個(gè)數(shù)量級(jí)。如果你做的是端側(cè)攝像頭、語音助手、手勢(shì)識(shí)別這類對(duì)延遲和功耗極度敏感的場(chǎng)景QNN幾乎繞不開。1.2 完整鏈路拆解從模型轉(zhuǎn)換到C推理一個(gè)模型要跑在QNN上鏈路其實(shí)可以拆成五段準(zhǔn)備模型文件PyTorch導(dǎo)出ONNX或者直接拿TensorFlow/TFLite模型。使用qnn-onnx-converter把ONNX轉(zhuǎn)成QNN的圖描述文件.serialized。使用qnn-context-binary-generator把圖描述文件和HTP Backend綁定生成一個(gè)Context Binary。編寫C程序加載Backend庫(kù)和Context Binary。創(chuàng)建輸入輸出張量執(zhí)行推理讀取結(jié)果。很多人會(huì)直接跳到第4步結(jié)果發(fā)現(xiàn)怎么都跑不通原因就是沒有理解Context Binary的作用。Context Binary可以理解為一份提前構(gòu)建好的執(zhí)行計(jì)劃它把模型的算子調(diào)度、內(nèi)存分配、常量數(shù)據(jù)全部打包在一起。運(yùn)行時(shí)只需要把這個(gè)二進(jìn)制文件加載進(jìn)去SDK就能直接在HTP上創(chuàng)建對(duì)應(yīng)的執(zhí)行上下文不用再一條一條去解析算子、做圖優(yōu)化。這一點(diǎn)非常重要。如果你在運(yùn)行時(shí)才去構(gòu)建圖每次啟動(dòng)都要重新做一遍算子的挑選和內(nèi)存規(guī)劃冷啟動(dòng)時(shí)間可能多出幾百毫秒甚至幾秒。而Context Binary方案把重活全部放在離線階段完成運(yùn)行時(shí)就是純加載速度極快。這也是為什么高通官方在端側(cè)部署時(shí)推薦的生產(chǎn)路徑就是Context Binary。1.3 方案取舍用Graph API還是直接用Context BinaryQNN其實(shí)提供了兩條運(yùn)行路徑一條是直接用Graph API在運(yùn)行時(shí)裝圖另一條就是上面說的加載Context Binary。從我實(shí)際用下來的感受來看除非你在做的是需要?jiǎng)討B(tài)修改網(wǎng)絡(luò)結(jié)構(gòu)的實(shí)驗(yàn)場(chǎng)景否則生產(chǎn)環(huán)境一定要走Context Binary。Graph API在運(yùn)行時(shí)構(gòu)建圖的好處是比較靈活可以在代碼里動(dòng)態(tài)指定張量維度、插入算子適合原型驗(yàn)證。但壞處也很明顯每次初始化都要完成完整的圖構(gòu)建流程而且需要在目標(biāo)設(shè)備上具備完整的算子庫(kù)和轉(zhuǎn)換工具鏈。這會(huì)讓程序的啟動(dòng)時(shí)間變長(zhǎng)還容易因?yàn)檫\(yùn)行環(huán)境和轉(zhuǎn)換環(huán)境不一致導(dǎo)致各種奇奇怪怪的算子兼容問題。Context Binary則是把模型在開發(fā)機(jī)上轉(zhuǎn)換完畢把校驗(yàn)也做掉之后再把二進(jìn)制文件放進(jìn)設(shè)備里。運(yùn)行時(shí)的代碼路徑極大簡(jiǎn)化就變成幾行固定的調(diào)用標(biāo)準(zhǔn)流程。就算產(chǎn)品發(fā)布了多個(gè)模型版本只要替換二進(jìn)制文件就行C代碼基本不用動(dòng)。我建議做產(chǎn)品落地的朋友直接采用這條路徑下面所有的代碼也都是按這個(gè)方案來寫的。2. 環(huán)境準(zhǔn)備與模型轉(zhuǎn)換這一步值80%的調(diào)試時(shí)間說實(shí)話QNN項(xiàng)目里真正耗時(shí)間的往往不是寫代碼而是環(huán)境搭建和模型轉(zhuǎn)換。很多人編譯報(bào)錯(cuò)、運(yùn)行崩潰最后發(fā)現(xiàn)都是SDK版本不匹配、交叉編譯工具鏈不對(duì)、模型轉(zhuǎn)換時(shí)埋了雷。環(huán)境準(zhǔn)備這一章認(rèn)真看能幫你省下大量排坑時(shí)間。2.1 SDK版本與交叉編譯工具鏈準(zhǔn)備我用的是高通發(fā)布的QNN SDK 2.x版本不同版本接口細(xì)節(jié)略有差異但整體思路是一致的。拿到SDK壓縮包之后解壓到某個(gè)目錄然后設(shè)置環(huán)境變量export QNN_SDK_ROOT/path/to/qnn-sdk export LD_LIBRARY_PATH$QNN_SDK_ROOT/lib/aarch64-unknown-linux-gnu:$LD_LIBRARY_PATH export PATH$QNN_SDK_ROOT/bin/aarch64-unknown-linux-gnu:$PATH注意SDK里的lib目錄下通常會(huì)區(qū)分x86_64-linux-clang和aarch64-unknown-linux-gnu等多個(gè)平臺(tái)目錄。你這臺(tái)開發(fā)機(jī)用的轉(zhuǎn)換工具比如qnn-onnx-converter一般是x86的Python腳本但運(yùn)行時(shí)加載的libQnnHtp.so必須選目標(biāo)設(shè)備對(duì)應(yīng)的架構(gòu)版本。如果程序跑在ARM64的Linux板子上就一定要把a(bǔ)arch64-unknown-linux-gnu目錄下的庫(kù)優(yōu)先加進(jìn)LD_LIBRARY_PATH而不是用x86的庫(kù)去跑否則直接報(bào)無法加載動(dòng)態(tài)庫(kù)。交叉編譯時(shí)還是要用aarch64的GCC工具鏈。我這邊用的是aarch64-linux-gnu-g版本建議在10以上太老的編譯器對(duì)C17支持不友好后面代碼里的智能指針、lambda寫起來會(huì)比較別扭。提前在板子上裝好對(duì)應(yīng)的依賴庫(kù)比如libstdc、libc這種基礎(chǔ)運(yùn)行庫(kù)避免把編譯產(chǎn)物拷過去之后才發(fā)現(xiàn)缺符號(hào)。如果你跑的是Windows on Snapdragon平臺(tái)那工具鏈又不太一樣要用MSVC或者Clang配合高通提供的Windows庫(kù)。今天這篇主要講Linux環(huán)境但代碼邏輯在Windows上一樣能套用關(guān)鍵路徑都是那些接口函數(shù)。2.2 從PyTorch導(dǎo)出ONNX的操作要點(diǎn)我們?cè)赒NN里最常見的第一步是把PyTorch模型導(dǎo)出成ONNX。導(dǎo)出命令很簡(jiǎn)單import torch model torch.load(model.pth, map_locationcpu) model.eval() dummy_input torch.randn(1, 3, 224, 224) torch.onnx.export( model, dummy_input, model.onnx, opset_version13, input_names[input_0], output_names[output_0], dynamic_axes{input_0: {0: batch}, output_0: {0: batch}} )這里有幾個(gè)細(xì)節(jié)非常關(guān)鍵。第一opset_version盡量選13或更高QNN轉(zhuǎn)換器對(duì)高版本opset的支持更完善低版本有些算子表達(dá)過于簡(jiǎn)陋轉(zhuǎn)換器反而容易踩坑。第二dynamic_axes一定要設(shè)置成動(dòng)態(tài)batch因?yàn)镼NN轉(zhuǎn)換器在解析ONNX時(shí)會(huì)對(duì)張量維度做靜態(tài)推理如果你把batch固定為1后續(xù)想換不同batch就得重新轉(zhuǎn)換非常麻煩。第三導(dǎo)出的模型里盡量不要包含自定義算子、數(shù)據(jù)依賴的循環(huán)結(jié)構(gòu)這類ONNX算子QNN不一定認(rèn)識(shí)一旦遇到就只能改成標(biāo)準(zhǔn)算子或者提前把邏輯拆到C里做預(yù)處理。我踩過最大的坑是模型里有一個(gè)torch.where的條件分支導(dǎo)出ONNX之后轉(zhuǎn)換器總是報(bào)算子不支持。后來把網(wǎng)絡(luò)結(jié)構(gòu)里的動(dòng)態(tài)條件邏輯挪到前處理步驟中用mask加法代替條件分支才順利轉(zhuǎn)換成功。所以導(dǎo)出模型之前最好先檢查一遍網(wǎng)絡(luò)里有沒有比較冷門的高級(jí)操作。2.3 使用qnn-onnx-converter的完整轉(zhuǎn)換命令環(huán)境變量配置好之后用轉(zhuǎn)換器把ONNX轉(zhuǎn)成QNN模型描述文件python $QNN_SDK_ROOT/bin/qnn-onnx-converter \ --input_network model.onnx \ --output_qnn_path ./qnn_model \ --input_list ./input_list.txt \ --quantize_full_type_uint16input_list.txt是用于校準(zhǔn)的數(shù)據(jù)列表每一行寫一個(gè)數(shù)據(jù)文件的路徑。這些數(shù)據(jù)文件是原始輸入通常是二進(jìn)制格式或者npy格式。如果你要做全整型量化校準(zhǔn)數(shù)據(jù)必須覆蓋真實(shí)場(chǎng)景的分布比如輸入是圖片最好從驗(yàn)證集里隨機(jī)抽200~500張盡量包含各種光照、角度、遮擋情況。校準(zhǔn)數(shù)據(jù)如果太單調(diào)量化后的模型精度會(huì)有明顯崩塌。--quantize_full_type_uint16表示權(quán)重激活都用uint16量化這是HTP上常用的一種方案精度比uint8高一些性能差異也不大。如果你追求極致性能可以試試uint8但精度掉得比較厲害。這塊可以多測(cè)幾組找一個(gè)準(zhǔn)確率和速度的平衡點(diǎn)。轉(zhuǎn)換完會(huì)在qnn_model目錄下生成一個(gè)model.serialized描述文件。接下來用Context Binary生成器把描述文件和HTP Backend綁定qnn-context-binary-generator \ --backend $QNN_SDK_ROOT/lib/aarch64-unknown-linux-gnu/libQnnHtp.so \ --model qnn_model/model.serialized \ --binary_file model_context.bin生成的model_context.bin就是最終要部署到設(shè)備上的文件。注意這里指定的libQnnHtp.so是開發(fā)機(jī)上的x86版本還是目標(biāo)板子的ARM版本命令行里的庫(kù)路徑實(shí)際上會(huì)被運(yùn)行時(shí)路徑替代生成的Context Binary里記錄的是一些后端圖信息最終執(zhí)行還是在設(shè)備的HTP上所以選哪個(gè)版本不是最核心的問題。但為了保險(xiǎn)我一般還是用目標(biāo)架構(gòu)的路徑去生成省得后續(xù)出現(xiàn)莫名其妙的ABI不兼容。2.4 用qnn-model-tool檢查模型信息轉(zhuǎn)換完之后不要急著寫C代碼先用高通自帶的工具檢查一下生成結(jié)果qnn-model-tool --model model_context.bin --print_info這個(gè)命令會(huì)打印模型的輸入輸出張量名稱、維度和類型。我會(huì)把輸入張量的名字記下來后面C代碼里創(chuàng)建張量時(shí)要用這個(gè)名字去匹配。如果名字寫錯(cuò)了graphExecute的時(shí)候通常會(huì)報(bào)張量未綁定或者數(shù)據(jù)填充失敗的錯(cuò)。另外還可以用qnn-model-tool --model model_context.bin --print_buffers查看模型內(nèi)所有緩沖區(qū)的布局方便確認(rèn)輸入數(shù)據(jù)應(yīng)該按什么形狀填充。這一步雖然簡(jiǎn)單但能避免后面代碼里到處猜維度。3. 手寫C推理代碼核心調(diào)用步驟逐段拆解環(huán)境搞定、模型轉(zhuǎn)換完成現(xiàn)在進(jìn)入重頭戲C調(diào)用QNN SDK。我用一個(gè)最簡(jiǎn)單的圖像分類模型做例子把從加載模型到推理輸出的整個(gè)流程寫成代碼。這個(gè)結(jié)構(gòu)也可以直接套用到檢測(cè)、分割等更復(fù)雜的模型上。3.1 核心接口說明QNN SDK的C接口核心其實(shí)就是一組函數(shù)指針表通過QnnInterface_getProviders()拿到接口提供者再?gòu)奈锢碓O(shè)備加載Backend實(shí)現(xiàn)初始化之后就能使用它提供的能力。QNN最大的特點(diǎn)是把Backend和Context分開抽象Backend是物理能力層負(fù)責(zé)管理NPU/GPU/DSP資源Context是邏輯執(zhí)行層負(fù)責(zé)持有模型圖和內(nèi)部狀態(tài)。整個(gè)調(diào)用序列可以分成四步獲取QNN接口初始化Backend。用導(dǎo)入的Context Binary創(chuàng)建Context。從Context中獲取Graph并綁定輸入輸出張量。執(zhí)行推理讀取結(jié)果。代碼寫起來會(huì)有一些宏和版本差異但接口骨架非常穩(wěn)定。下面我會(huì)拆成幾個(gè)代碼塊來解析。3.2 從QNN Backend初始化到加載Context Binary先看接口獲取和初始化的代碼#include QnnInterface.h #include QnnTypes.h #include QnnContext.h #include QnnGraph.h #include QnnTensor.h #include iostream #include vector #include cstring #include fstream #include dlfcn.h using QnnFunctionTable QNN_INTERFACE_VER_TYPE; QnnFunctionTable* g_qnn nullptr; Qnn_BackendHandle_t g_backend nullptr; Qnn_ContextHandle_t g_context nullptr; bool loadQnnInterface(const char* backendLibPath) { void* handle dlopen(backendLibPath, RTLD_NOW | RTLD_GLOBAL); if (!handle) { std::cerr dlopen failed: dlerror() std::endl; return false; } auto getProviders (Qnn_ErrorHandle_t (*)(const QnnInterface_t***, uint32_t*)) dlsym(handle, QnnInterface_getProviders); if (!getProviders) { std::cerr cannot find QnnInterface_getProviders std::endl; return false; } const QnnInterface_t** providers nullptr; uint32_t numProviders 0; if (getProviders(providers, numProviders) ! QNN_SUCCESS || numProviders 0) { std::cerr no QNN providers found std::endl; return false; } g_qnn providers[0]-QNN_INTERFACE_VER_TYPE; return true; }dlopen那一步就相當(dāng)于在運(yùn)行時(shí)加載HTP驅(qū)動(dòng)的前端庫(kù)。為什么要用dlopen而不是直接鏈接因?yàn)槟憧梢酝ㄟ^命令行參數(shù)傳入不同的Backend庫(kù)路徑程序變得更靈活。想切到GPU Backend時(shí)只需要換個(gè)路徑即可不用重新編譯。拿到接口之后開始初始化Backend和Contextbool initBackendAndContext(const std::string modelPath) { if (!g_qnn) return false; // 初始化后端 if (g_qnn-backendInitialize(nullptr) ! QNN_SUCCESS) { std::cerr backend initialize failed std::endl; return false; } // 創(chuàng)建后端句柄 Qnn_Backend_Config_t* backendConfig nullptr; if (g_qnn-backendCreate(nullptr, backendConfig, g_backend) ! QNN_SUCCESS) { std::cerr backend create failed std::endl; return false; } // 讀取Context Binary內(nèi)容 std::ifstream binFile(modelPath, std::ios::binary); std::vectoruint8_t buffer((std::istreambuf_iteratorchar(binFile)), std::istreambuf_iteratorchar()); if (buffer.empty()) { std::cerr model binary is empty std::endl; return false; } // 從二進(jìn)制直接創(chuàng)建Context Qnn_Context_Config_t contextConfig; memset(contextConfig, 0, sizeof(contextConfig)); Qnn_ContextCreateFromBinary_Config_t* ctxCreateConfig nullptr; if (g_qnn-contextCreateFromBinary( g_backend, nullptr, buffer.data(), buffer.size(), g_context, ctxCreateConfig) ! QNN_SUCCESS) { std::cerr context create from binary failed std::endl; return false; } return true; }這里要解釋一下為什么用contextCreateFromBinary而不是contextCreate。contextCreate要求傳入網(wǎng)絡(luò)描述符運(yùn)行時(shí)再?gòu)拿枋龇麡?gòu)建圖。而contextCreateFromBinary接收的是離線生成好的二進(jìn)制執(zhí)行計(jì)劃所有算子的選擇、內(nèi)存分配、依賴關(guān)系都已經(jīng)確定。路徑短、開銷小、穩(wěn)定可靠這就是上一章極力推薦Context Binary的原因。執(zhí)行完以上代碼模型其實(shí)已經(jīng)在HTP上初步建立了執(zhí)行上下文但還缺輸入輸出張量這塊拼圖。3.3 創(chuàng)建輸入輸出Tensor并填充數(shù)據(jù)張量在QNN里是一個(gè)非常重要的抽象它描述了一塊數(shù)據(jù)區(qū)以及它的維度、數(shù)據(jù)類型、量化參數(shù)等信息。創(chuàng)建張量的代碼如下bool createInputTensor(const std::string name, const std::vectoruint32_t dims, Qnn_Tensor_t tensor) { tensor QNN_TENSOR_INIT; tensor.type QNN_TENSOR_TYPE_APP_WRITE; // 輸入張量由應(yīng)用寫入 tensor.dataFormat QNN_TENSOR_DATA_FORMAT_FLOAT_32; Qnn_TensorData_t td tensor.tensorData; td.name name.c_str(); td.rank static_castuint32_t(dims.size()); td.dimensions const_castuint32_t*(dims.data()); td.dataType QNN_DATATYPE_FLOAT_32; td.quantizeParams.encodingDefinition QNN_TENSOR_QUANTIZATION_NONE; if (g_qnn-tensorCreate(g_context, tensor) ! QNN_SUCCESS) { std::cerr tensor create failed: name std::endl; return false; } return true; }QNN_TENSOR_TYPE_APP_WRITE表示這塊內(nèi)存在設(shè)備端由應(yīng)用側(cè)負(fù)責(zé)寫入。還有一種常見類型是QNN_TENSOR_TYPE_APP_READ用于輸出張量表示應(yīng)用需要從設(shè)備端讀取結(jié)果。當(dāng)然也有QNN_TENSOR_TYPE_NATIVE這類直接綁定設(shè)備內(nèi)存的用法但那是性能優(yōu)化階段才需要考慮的事第一次跑通流程時(shí)先用APP_WRITE/APP_READ最省心。創(chuàng)建完輸入張量后要把圖像數(shù)據(jù)填進(jìn)去void fillInputTensor(Qnn_Tensor_t tensor, const std::vectorfloat imageData) { // 先讓QNN獲取一塊可寫入的數(shù)據(jù)指針 void* tensorData nullptr; g_qnn-tensorGetData(tensor, tensorData); if (tensorData nullptr) { std::cerr input tensor data pointer is null std::endl; return; } memcpy(tensorData, imageData.data(), imageData.size() * sizeof(float)); }輸出張量的創(chuàng)建邏輯類似但type要改成QNN_TENSOR_TYPE_APP_READ。這里的核心概念是QNN的輸入輸出張量本質(zhì)上是共享內(nèi)存的通道你往輸入張量綁定的指針里寫數(shù)據(jù)模型執(zhí)行時(shí)直接讀這塊內(nèi)存執(zhí)行結(jié)束后從輸出張量綁定的指針里取數(shù)據(jù)。把數(shù)據(jù)搬進(jìn)去和取出來是整個(gè)流程唯一需要顯式操作內(nèi)存的地方。3.4 執(zhí)行推理和結(jié)果讀取執(zhí)行推理是整個(gè)項(xiàng)目最爽的一步代碼反而是所有環(huán)節(jié)里最簡(jiǎn)短的bool runInference(Qnn_Tensor_t inputTensor, Qnn_Tensor_t outputTensor) { // 獲取模型中的圖句柄 Qnn_GraphHandle_t graphHandle nullptr; Qnn_GraphHandle_t* graphList nullptr; uint32_t numGraphs 0; if (g_qnn-contextGetGraphs(g_context, graphList, numGraphs) ! QNN_SUCCESS) { std::cerr context get graphs failed std::endl; return false; } if (numGraphs 0) { std::cerr no graph in context std::endl; return false; } graphHandle graphList[0]; // 將輸入輸出張量綁定到執(zhí)行 Qnn_Tensor_t tensors[2] { inputTensor, outputTensor }; if (g_qnn-graphExecute(graphHandle, tensors, 2, nullptr, nullptr) ! QNN_SUCCESS) { std::cerr graph execute failed std::endl; return false; } // 讀取輸出數(shù)據(jù) void* outData nullptr; g_qnn-tensorGetData(outputTensor, outData); float* floatOut reinterpret_castfloat*(outData); std::cout Inference done. First 10 outputs: std::endl; for (int i 0; i 10; i) { std::cout floatOut[i] ; } std::cout std::endl; return true; }graphExecute的執(zhí)行是同步的調(diào)用返回時(shí)推理就已經(jīng)完成了。如果你做的是視頻流或者連續(xù)多幀處理建議在創(chuàng)建Context時(shí)打開異步執(zhí)行相關(guān)的配置改成邊采集邊推理的方式提升吞吐。后面章節(jié)會(huì)展開說。一個(gè)容易忽略的細(xì)節(jié)是contextGetGraphs拿到的圖句柄列表是Context內(nèi)部的不需要自行釋放。如果你加載的Context Binary里包含了多個(gè)模型比如一個(gè)檢測(cè)模型加一個(gè)特征模型遍歷這個(gè)數(shù)組就能拿到所有圖句柄分別執(zhí)行。實(shí)際項(xiàng)目中很有用。3.5 資源釋放的正確順序資源釋放順序有講究別小看這最后一步。一個(gè)常見的錯(cuò)誤是先把Backend銷毀了再銷毀Context然后程序崩潰。正確的順序是void cleanup() { if (g_context) { g_qnn-contextFree(g_context); g_context nullptr; } if (g_backend) { g_qnn-backendFree(g_backend); g_backend nullptr; } // 后端terminate放最后 g_qnn-backendTerminate(nullptr); }先釋放Context再釋放Backend最后調(diào)用backendTerminate。原因很簡(jiǎn)單Context還持有Backend內(nèi)部的設(shè)備資源如果先把Backend釋放掉Context在銷毀的時(shí)候會(huì)訪問到一塊已經(jīng)失效的句柄區(qū)域輕則告警重則段錯(cuò)誤。我早期做這塊時(shí)都是直接不釋放進(jìn)程退出讓系統(tǒng)回收后來做長(zhǎng)時(shí)間運(yùn)行的服務(wù)才發(fā)現(xiàn)釋放順序混亂會(huì)導(dǎo)致內(nèi)存持續(xù)上漲最后只能把進(jìn)程重啟。養(yǎng)成正確的釋放習(xí)慣寫出來的服務(wù)才敢跑上幾天幾夜。4. 編譯運(yùn)行與踩坑實(shí)錄從代碼到真正跑起來代碼寫完之后編譯和運(yùn)行階段才是真正開始“打仗”的時(shí)候。這一章我把高頻踩坑點(diǎn)整理出來希望能幫你從報(bào)錯(cuò)大海里快速爬出來。4.1 編譯期錯(cuò)誤怎么排查編譯命令大致是這樣aarch64-linux-gnu-g -stdc17 qnn_runner.cpp -o qnn_runner \ -I$QNN_SDK_ROOT/include \ -L$QNN_SDK_ROOT/lib/aarch64-unknown-linux-gnu \ -Wl,-rpath,$QNN_SDK_ROOT/lib/aarch64-unknown-linux-gnu這里重點(diǎn)說一下-Wl,-rpath的作用。編譯時(shí)鏈接的庫(kù)在運(yùn)行時(shí)也要能被找到如果你不在編譯時(shí)指定rpath運(yùn)行前就必須手動(dòng)設(shè)置LD_LIBRARY_PATH。跑服務(wù)的時(shí)候很容易忘記設(shè)置然后看到一連串error while loading shared libraries排查半天才發(fā)現(xiàn)是動(dòng)態(tài)庫(kù)路徑問題。把它編進(jìn)二進(jìn)制里一勞永逸。編譯期最常遇到的第一類報(bào)錯(cuò)是找不到頭文件比如fatal error: QnnType.h: No such file or directory。這通常是-I路徑寫錯(cuò)了檢查一下SDK里的include目錄結(jié)構(gòu)把路徑對(duì)準(zhǔn)包含QnnInterface.h的那一層。第二類報(bào)錯(cuò)是鏈接時(shí)找不到QnnInterface_getProviders符號(hào)報(bào)undefined reference。多半是因?yàn)槟阌昧薈編譯器但接口頭文件里的函數(shù)沒有用extern C包裹。QNN頭文件有的版本自帶兼容處理有的版本則需要在包含前手動(dòng)加上extern C { #include QnnInterface.h }這個(gè)問題很隱蔽因?yàn)榫幾g器報(bào)錯(cuò)行號(hào)往往指向你的源文件而不是頭文件讓人誤以為是自己代碼寫錯(cuò)了。后來我在項(xiàng)目規(guī)則里固定了一條所有QNN相關(guān)頭文件一律用extern C包含從此再?zèng)]遇到過這類鏈接問題。4.2 運(yùn)行時(shí)錯(cuò)誤速查表運(yùn)行時(shí)錯(cuò)誤五花八門把幾個(gè)高頻場(chǎng)景列成表格方便對(duì)照排查現(xiàn)象常見原因處理建議dlopen失敗libQnnHtp.so: cannot open shared object fileLD_LIBRARY_PATH沒指對(duì)或者庫(kù)架構(gòu)不匹配先確認(rèn)當(dāng)前運(yùn)行的機(jī)器架構(gòu)再設(shè)置對(duì)應(yīng)的庫(kù)路徑backendCreate返回錯(cuò)誤沒有更多日志HTP固件版本和SDK版本不匹配檢查設(shè)備的DSP固件版本升級(jí)Hexagon SDK或更換QNN版本contextCreateFromBinary報(bào)RPC_ERRORHTP驅(qū)動(dòng)沒加載或者權(quán)限不足確認(rèn)設(shè)備端是否已經(jīng)啟動(dòng)QNN的RPC服務(wù)用高通提供的run工具初始化環(huán)境輸入張量數(shù)據(jù)寫不進(jìn)去tensorGetData返回空指針張量類型設(shè)置錯(cuò)誤用了NATIVE類型卻沒有綁定設(shè)備內(nèi)存首次跑通流程用QNN_TENSOR_TYPE_APP_WRITEgraphExecute崩潰提示張量名稱不匹配代碼里創(chuàng)建張量的名字和模型里不一致用qnn-model-tool --print_info查看模型真實(shí)張量名推理結(jié)果全是0輸入數(shù)據(jù)沒寫進(jìn)張量或者量化參數(shù)設(shè)置不對(duì)先用float模型跑通再切量化模型對(duì)比結(jié)果這里補(bǔ)充一個(gè)容易忽略的點(diǎn)如果設(shè)備上跑的是沒有root權(quán)限的用戶態(tài)進(jìn)程訪問HTP可能會(huì)被SELinux或者權(quán)限策略攔下來報(bào)一些看起來完全莫名其妙的錯(cuò)誤。遇到這類問題先檢查日志看有沒有權(quán)限相關(guān)的關(guān)鍵字。沒有權(quán)限就用系統(tǒng)管理員協(xié)助調(diào)整配置不要試圖硬繞權(quán)限限制。4.3 打開日志和調(diào)試技巧QNN內(nèi)部有一套完整的日志機(jī)制調(diào)試的時(shí)候打開日志能幫你少走很多彎路。export QNN_LOG_LEVELVERBOSE ./qnn_runner日志級(jí)別從低到高通常是ERROR、WARN、INFO、VERBOSE。平時(shí)跑服務(wù)用WARN就行檢查問題時(shí)開到VERBOSE。開啟后你會(huì)看到SDK內(nèi)部每一步在做什么比如加載后端、創(chuàng)建Context、綁定張量、執(zhí)行算子。有一次模型執(zhí)行結(jié)果不對(duì)打開日志才發(fā)現(xiàn)是某些算子在HTP上走了低精度分支數(shù)值精度下降導(dǎo)致結(jié)果偏差但整個(gè)流程本身沒有報(bào)錯(cuò)。這種問題不開日志根本無從查起。還有一個(gè)小技巧在代碼里加一個(gè)getElapsedTime的計(jì)時(shí)模塊分別統(tǒng)計(jì)模型加載耗時(shí)和推理耗時(shí)。模型加載耗時(shí)可以用來判斷Context Binary是否真的被完整加載推理耗時(shí)可以判斷模型是否真的跑在了HTP上。如果推理耗時(shí)和純CPU實(shí)現(xiàn)差不多那就要懷疑是不是量化沒生效或者Backend配置里禁用了HTP加速。4.4 如何確認(rèn)推理真的跑在HTP上這里插一個(gè)重要驗(yàn)證步驟怎么確認(rèn)模型不是跑在CPU上最簡(jiǎn)單的方法是看執(zhí)行時(shí)間。一個(gè)MobileNetV2量化的模型在驍龍8系列平臺(tái)上跑推理時(shí)間通常只有幾毫秒如果代碼配置正確肉眼可見地比純CPU快。另一種方式是在QNN日志里搜索HtpGraph之類的關(guān)鍵字VERBOSE日志會(huì)打印出后端執(zhí)行時(shí)的算子調(diào)度信息。更嚴(yán)謹(jǐn)?shù)淖龇ㄊ菍?shí)測(cè)功耗。把設(shè)備插上功率計(jì)跑100次推理對(duì)比CPU版和HTP版的功耗差異。HTP版本通常明顯更低。做功耗對(duì)比的時(shí)候建議把屏幕亮度、無線模塊等因素固定住否則數(shù)據(jù)會(huì)被干擾帶偏。日志確認(rèn)和功耗測(cè)量都做過之后基本可以放心你的模型已經(jīng)真正跑在高通NPU上了。5. 性能優(yōu)化與落地建議到這里整個(gè)流程已經(jīng)跑通了模型能夠在C程序里被加載和推理。但跑通只是第一步要想真正落地到產(chǎn)品里還有幾個(gè)關(guān)于性能和穩(wěn)定性的問題需要處理。這部分不是必選項(xiàng)但對(duì)于做長(zhǎng)期項(xiàng)目的人來說非常值得參考。5.1 Tensor內(nèi)存分配與對(duì)齊前面提到APP_WRITE/APP_READ張量類型最省心但在追求極致性能時(shí)可以考慮使用QNN_TENSOR_TYPE_NATIVE并把輸入輸出緩沖區(qū)直接綁到設(shè)備端。這種做法的好處是省去了Host和Device之間的一次內(nèi)存拷貝。如果決定用原生內(nèi)存綁定的方式就必須注意內(nèi)存對(duì)齊。QNN的HTP后端對(duì)緩沖區(qū)有對(duì)齊要求通常是256字節(jié)或者更高具體值可以在SDK的文檔中查到。用posix_memalign分配內(nèi)存設(shè)置QNN_TENSOR_MEM_TYPE_DMA等類型再通過tensorCreateCustom綁定能明顯降低單次推理的負(fù)載。不過這屬于進(jìn)階優(yōu)化第一次做項(xiàng)目不建議直接上。先用APP_WRITE/APP_READ把功能做對(duì)之后再用性能剖析工具找出真正的瓶頸點(diǎn)再有針對(duì)性地替換成原生內(nèi)存方案。5.2 Context復(fù)用與多模型切換在一個(gè)長(zhǎng)期運(yùn)行的應(yīng)用里不要每推理一幀就創(chuàng)建一個(gè)新Context這是非常浪費(fèi)的。一個(gè)Context可以復(fù)用很多次graphExecute是線程安全還是需要加鎖取決于具體后端實(shí)現(xiàn)但通常建議一個(gè)Context對(duì)應(yīng)一個(gè)推理線程保持穩(wěn)定的調(diào)用頻率。多線程場(chǎng)景下要么給Context加鎖要么創(chuàng)建多個(gè)Context每個(gè)線程持有一個(gè)后者吞吐更好。如果你有多個(gè)模型需要切換推理可以一次性把所有模型的Context Binary都加載進(jìn)來每個(gè)模型對(duì)應(yīng)一個(gè)Context和一組輸入輸出張量。執(zhí)行時(shí)按需調(diào)用對(duì)應(yīng)Context的圖切換開銷很小。這種設(shè)計(jì)比每次切換都創(chuàng)建銷毀Context要穩(wěn)得多內(nèi)存占用也更好預(yù)估。5.3 我的個(gè)人維護(hù)習(xí)慣最后分享一個(gè)我自己的習(xí)慣每跑通一個(gè)新模型就在項(xiàng)目目錄下新建一個(gè)model_config.txt把模型版本、輸入尺寸、量化方案、Backend庫(kù)版本、生成Context Binary的命令全部記錄下來。這東西看機(jī)器折騰久了半年后回來看項(xiàng)目如果沒有一份配置記錄你會(huì)對(duì)著一個(gè)陌生模型文件發(fā)半天呆。我看過太多人拿著別人給的Context Binary直接接進(jìn)業(yè)務(wù)代碼出了問題不知道是后端不兼容還是模型轉(zhuǎn)換有誤只能從頭排查。提前把版本信息記錄好配合上面說的日志分級(jí)機(jī)制排查問題基本能砍掉一半時(shí)間。QNN整套東西上手之后會(huì)發(fā)現(xiàn)它的接口設(shè)計(jì)一旦理順剩下的就是機(jī)械式調(diào)用。真正決定項(xiàng)目上限的反而是在模型轉(zhuǎn)換階段對(duì)算子兼容性的把握以及在C側(cè)對(duì)張量生命周期的管理能力。第一次跑通別著急上性能優(yōu)化先讓整個(gè)鏈路穩(wěn)定轉(zhuǎn)起來再一步步打磨細(xì)節(jié)。 高通QNN SDK實(shí)戰(zhàn)：從模型轉(zhuǎn)換到C++推理全流程指南
在驍龍平臺(tái)做AI推理最忌諱的是把模型拿來直接在CPU上跑一遍就宣布完事硬件加速能力一點(diǎn)都沒用上。Qualcomm QNN SDK本來就提供了一整套從模型轉(zhuǎn)換、量化到C/C運(yùn)行時(shí)調(diào)用的工具鏈大多數(shù)人卡住的地方其實(shí)就兩個(gè)模型不知道怎么轉(zhuǎn)成QNN格式C代碼不知道從哪個(gè)接口下手。這篇文章把這條路完整走一遍從環(huán)境準(zhǔn)備到代碼解析最后再到排坑你可以把它當(dāng)成一份能照著跑的作業(yè)。1. 項(xiàng)目全景與方案設(shè)計(jì)先從QNN的整體架構(gòu)說起動(dòng)手寫代碼之前先把QNN這套東西的地圖畫出來。很多人被QNN勸退不是因?yàn)榇a難寫而是因?yàn)楦拍畈皇臁Ｒ活^扎進(jìn)去看到一堆Handle、Descriptor、Profile直接就懵了。其實(shí)QNN的架構(gòu)分得非常清晰理解了那幾條主線后面所有代碼都只是在跟這幾條主線打交道。1.1 QNN SDK到底是什么為什么選它QNN SDK是高通提供的神經(jīng)網(wǎng)絡(luò)推理SDK跑在驍龍平臺(tái)上時(shí)它能把模型調(diào)度到Hexagon DSP或者HTPHexagon Tensor Processor上執(zhí)行。HTP是高通專門為AI推理設(shè)計(jì)的硬件加速單元比CPU省電吞吐能力高出好幾個(gè)量級(jí)。常見的分類、檢測(cè)、分割模型經(jīng)過合理量化之后在HTP上都能跑得飛快。從架構(gòu)上看QNN分兩層一層是Host側(cè)也就是你的C應(yīng)用跑在CPU上的部分另一層是Device側(cè)也就是跑在DSP/HTP上的部分。Host側(cè)通過QNN提供的Backend接口跟Device側(cè)打交道。像libQnnHtp.so就是HTP的Backend實(shí)現(xiàn)庫(kù)你的程序通過dlopen或者運(yùn)行時(shí)鏈接的方式加載它然后調(diào)用統(tǒng)一的QNN接口剩下的調(diào)度工作全部交給SDK完成。很多人會(huì)問既然有TFLite、ONNX Runtime這些跨平臺(tái)框架為什么還要折騰QNN原因很簡(jiǎn)單模型要跑得夠快夠省電就必須直接調(diào)用硬件能力?？缙脚_(tái)框架為了兼容性往往走的是通用優(yōu)化路徑對(duì)特定硬件的利用程度有限。QNN能直接操作DSP/HTP上的張量緩沖區(qū)和執(zhí)行流水線量化模型跑起來經(jīng)常比CPU快一個(gè)數(shù)量級(jí)。如果你做的是端側(cè)攝像頭、語音助手、手勢(shì)識(shí)別這類對(duì)延遲和功耗極度敏感的場(chǎng)景QNN幾乎繞不開。1.2 完整鏈路拆解從模型轉(zhuǎn)換到C推理一個(gè)模型要跑在QNN上鏈路其實(shí)可以拆成五段準(zhǔn)備模型文件PyTorch導(dǎo)出ONNX或者直接拿TensorFlow/TFLite模型。使用qnn-onnx-converter把ONNX轉(zhuǎn)成QNN的圖描述文件.serialized。使用qnn-context-binary-generator把圖描述文件和HTP Backend綁定生成一個(gè)Context Binary。編寫C程序加載Backend庫(kù)和Context Binary。創(chuàng)建輸入輸出張量執(zhí)行推理讀取結(jié)果。很多人會(huì)直接跳到第4步結(jié)果發(fā)現(xiàn)怎么都跑不通原因就是沒有理解Context Binary的作用。Context Binary可以理解為一份提前構(gòu)建好的執(zhí)行計(jì)劃它把模型的算子調(diào)度、內(nèi)存分配、常量數(shù)據(jù)全部打包在一起。運(yùn)行時(shí)只需要把這個(gè)二進(jìn)制文件加載進(jìn)去SDK就能直接在HTP上創(chuàng)建對(duì)應(yīng)的執(zhí)行上下文不用再一條一條去解析算子、做圖優(yōu)化。這一點(diǎn)非常重要。如果你在運(yùn)行時(shí)才去構(gòu)建圖每次啟動(dòng)都要重新做一遍算子的挑選和內(nèi)存規(guī)劃冷啟動(dòng)時(shí)間可能多出幾百毫秒甚至幾秒。而Context Binary方案把重活全部放在離線階段完成運(yùn)行時(shí)就是純加載速度極快。這也是為什么高通官方在端側(cè)部署時(shí)推薦的生產(chǎn)路徑就是Context Binary。1.3 方案取舍用Graph API還是直接用Context BinaryQNN其實(shí)提供了兩條運(yùn)行路徑一條是直接用Graph API在運(yùn)行時(shí)裝圖另一條就是上面說的加載Context Binary。從我實(shí)際用下來的感受來看除非你在做的是需要?jiǎng)討B(tài)修改網(wǎng)絡(luò)結(jié)構(gòu)的實(shí)驗(yàn)場(chǎng)景否則生產(chǎn)環(huán)境一定要走Context Binary。Graph API在運(yùn)行時(shí)構(gòu)建圖的好處是比較靈活可以在代碼里動(dòng)態(tài)指定張量維度、插入算子適合原型驗(yàn)證。但壞處也很明顯每次初始化都要完成完整的圖構(gòu)建流程而且需要在目標(biāo)設(shè)備上具備完整的算子庫(kù)和轉(zhuǎn)換工具鏈。這會(huì)讓程序的啟動(dòng)時(shí)間變長(zhǎng)還容易因?yàn)檫\(yùn)行環(huán)境和轉(zhuǎn)換環(huán)境不一致導(dǎo)致各種奇奇怪怪的算子兼容問題。Context Binary則是把模型在開發(fā)機(jī)上轉(zhuǎn)換完畢把校驗(yàn)也做掉之后再把二進(jìn)制文件放進(jìn)設(shè)備里。運(yùn)行時(shí)的代碼路徑極大簡(jiǎn)化就變成幾行固定的調(diào)用標(biāo)準(zhǔn)流程。就算產(chǎn)品發(fā)布了多個(gè)模型版本只要替換二進(jìn)制文件就行C代碼基本不用動(dòng)。我建議做產(chǎn)品落地的朋友直接采用這條路徑下面所有的代碼也都是按這個(gè)方案來寫的。2. 環(huán)境準(zhǔn)備與模型轉(zhuǎn)換這一步值80%的調(diào)試時(shí)間說實(shí)話QNN項(xiàng)目里真正耗時(shí)間的往往不是寫代碼而是環(huán)境搭建和模型轉(zhuǎn)換。很多人編譯報(bào)錯(cuò)、運(yùn)行崩潰最后發(fā)現(xiàn)都是SDK版本不匹配、交叉編譯工具鏈不對(duì)、模型轉(zhuǎn)換時(shí)埋了雷。環(huán)境準(zhǔn)備這一章認(rèn)真看能幫你省下大量排坑時(shí)間。2.1 SDK版本與交叉編譯工具鏈準(zhǔn)備我用的是高通發(fā)布的QNN SDK 2.x版本不同版本接口細(xì)節(jié)略有差異但整體思路是一致的。拿到SDK壓縮包之后解壓到某個(gè)目錄然后設(shè)置環(huán)境變量export QNN_SDK_ROOT/path/to/qnn-sdk export LD_LIBRARY_PATH$QNN_SDK_ROOT/lib/aarch64-unknown-linux-gnu:$LD_LIBRARY_PATH export PATH$QNN_SDK_ROOT/bin/aarch64-unknown-linux-gnu:$PATH注意SDK里的lib目錄下通常會(huì)區(qū)分x86_64-linux-clang和aarch64-unknown-linux-gnu等多個(gè)平臺(tái)目錄。你這臺(tái)開發(fā)機(jī)用的轉(zhuǎn)換工具比如qnn-onnx-converter一般是x86的Python腳本但運(yùn)行時(shí)加載的libQnnHtp.so必須選目標(biāo)設(shè)備對(duì)應(yīng)的架構(gòu)版本。如果程序跑在ARM64的Linux板子上就一定要把a(bǔ)arch64-unknown-linux-gnu目錄下的庫(kù)優(yōu)先加進(jìn)LD_LIBRARY_PATH而不是用x86的庫(kù)去跑否則直接報(bào)無法加載動(dòng)態(tài)庫(kù)。交叉編譯時(shí)還是要用aarch64的GCC工具鏈。我這邊用的是aarch64-linux-gnu-g版本建議在10以上太老的編譯器對(duì)C17支持不友好后面代碼里的智能指針、lambda寫起來會(huì)比較別扭。提前在板子上裝好對(duì)應(yīng)的依賴庫(kù)比如libstdc、libc這種基礎(chǔ)運(yùn)行庫(kù)避免把編譯產(chǎn)物拷過去之后才發(fā)現(xiàn)缺符號(hào)。如果你跑的是Windows on Snapdragon平臺(tái)那工具鏈又不太一樣要用MSVC或者Clang配合高通提供的Windows庫(kù)。今天這篇主要講Linux環(huán)境但代碼邏輯在Windows上一樣能套用關(guān)鍵路徑都是那些接口函數(shù)。2.2 從PyTorch導(dǎo)出ONNX的操作要點(diǎn)我們?cè)赒NN里最常見的第一步是把PyTorch模型導(dǎo)出成ONNX。導(dǎo)出命令很簡(jiǎn)單import torch model torch.load(model.pth, map_locationcpu) model.eval() dummy_input torch.randn(1, 3, 224, 224) torch.onnx.export( model, dummy_input, model.onnx, opset_version13, input_names[input_0], output_names[output_0], dynamic_axes{input_0: {0: batch}, output_0: {0: batch}} )這里有幾個(gè)細(xì)節(jié)非常關(guān)鍵。第一opset_version盡量選13或更高QNN轉(zhuǎn)換器對(duì)高版本opset的支持更完善低版本有些算子表達(dá)過于簡(jiǎn)陋轉(zhuǎn)換器反而容易踩坑。第二dynamic_axes一定要設(shè)置成動(dòng)態(tài)batch因?yàn)镼NN轉(zhuǎn)換器在解析ONNX時(shí)會(huì)對(duì)張量維度做靜態(tài)推理如果你把batch固定為1后續(xù)想換不同batch就得重新轉(zhuǎn)換非常麻煩。第三導(dǎo)出的模型里盡量不要包含自定義算子、數(shù)據(jù)依賴的循環(huán)結(jié)構(gòu)這類ONNX算子QNN不一定認(rèn)識(shí)一旦遇到就只能改成標(biāo)準(zhǔn)算子或者提前把邏輯拆到C里做預(yù)處理。我踩過最大的坑是模型里有一個(gè)torch.where的條件分支導(dǎo)出ONNX之后轉(zhuǎn)換器總是報(bào)算子不支持。后來把網(wǎng)絡(luò)結(jié)構(gòu)里的動(dòng)態(tài)條件邏輯挪到前處理步驟中用mask加法代替條件分支才順利轉(zhuǎn)換成功。所以導(dǎo)出模型之前最好先檢查一遍網(wǎng)絡(luò)里有沒有比較冷門的高級(jí)操作。2.3 使用qnn-onnx-converter的完整轉(zhuǎn)換命令環(huán)境變量配置好之后用轉(zhuǎn)換器把ONNX轉(zhuǎn)成QNN模型描述文件python $QNN_SDK_ROOT/bin/qnn-onnx-converter \ --input_network model.onnx \ --output_qnn_path ./qnn_model \ --input_list ./input_list.txt \ --quantize_full_type_uint16input_list.txt是用于校準(zhǔn)的數(shù)據(jù)列表每一行寫一個(gè)數(shù)據(jù)文件的路徑。這些數(shù)據(jù)文件是原始輸入通常是二進(jìn)制格式或者npy格式。如果你要做全整型量化校準(zhǔn)數(shù)據(jù)必須覆蓋真實(shí)場(chǎng)景的分布比如輸入是圖片最好從驗(yàn)證集里隨機(jī)抽200~500張盡量包含各種光照、角度、遮擋情況。校準(zhǔn)數(shù)據(jù)如果太單調(diào)量化后的模型精度會(huì)有明顯崩塌。--quantize_full_type_uint16表示權(quán)重激活都用uint16量化這是HTP上常用的一種方案精度比uint8高一些性能差異也不大。如果你追求極致性能可以試試uint8但精度掉得比較厲害。這塊可以多測(cè)幾組找一個(gè)準(zhǔn)確率和速度的平衡點(diǎn)。轉(zhuǎn)換完會(huì)在qnn_model目錄下生成一個(gè)model.serialized描述文件。接下來用Context Binary生成器把描述文件和HTP Backend綁定qnn-context-binary-generator \ --backend $QNN_SDK_ROOT/lib/aarch64-unknown-linux-gnu/libQnnHtp.so \ --model qnn_model/model.serialized \ --binary_file model_context.bin生成的model_context.bin就是最終要部署到設(shè)備上的文件。注意這里指定的libQnnHtp.so是開發(fā)機(jī)上的x86版本還是目標(biāo)板子的ARM版本命令行里的庫(kù)路徑實(shí)際上會(huì)被運(yùn)行時(shí)路徑替代生成的Context Binary里記錄的是一些后端圖信息最終執(zhí)行還是在設(shè)備的HTP上所以選哪個(gè)版本不是最核心的問題。但為了保險(xiǎn)我一般還是用目標(biāo)架構(gòu)的路徑去生成省得后續(xù)出現(xiàn)莫名其妙的ABI不兼容。2.4 用qnn-model-tool檢查模型信息轉(zhuǎn)換完之后不要急著寫C代碼先用高通自帶的工具檢查一下生成結(jié)果qnn-model-tool --model model_context.bin --print_info這個(gè)命令會(huì)打印模型的輸入輸出張量名稱、維度和類型。我會(huì)把輸入張量的名字記下來后面C代碼里創(chuàng)建張量時(shí)要用這個(gè)名字去匹配。如果名字寫錯(cuò)了graphExecute的時(shí)候通常會(huì)報(bào)張量未綁定或者數(shù)據(jù)填充失敗的錯(cuò)。另外還可以用qnn-model-tool --model model_context.bin --print_buffers查看模型內(nèi)所有緩沖區(qū)的布局方便確認(rèn)輸入數(shù)據(jù)應(yīng)該按什么形狀填充。這一步雖然簡(jiǎn)單但能避免后面代碼里到處猜維度。3. 手寫C推理代碼核心調(diào)用步驟逐段拆解環(huán)境搞定、模型轉(zhuǎn)換完成現(xiàn)在進(jìn)入重頭戲C調(diào)用QNN SDK。我用一個(gè)最簡(jiǎn)單的圖像分類模型做例子把從加載模型到推理輸出的整個(gè)流程寫成代碼。這個(gè)結(jié)構(gòu)也可以直接套用到檢測(cè)、分割等更復(fù)雜的模型上。3.1 核心接口說明QNN SDK的C接口核心其實(shí)就是一組函數(shù)指針表通過QnnInterface_getProviders()拿到接口提供者再?gòu)奈锢碓O(shè)備加載Backend實(shí)現(xiàn)初始化之后就能使用它提供的能力。QNN最大的特點(diǎn)是把Backend和Context分開抽象Backend是物理能力層負(fù)責(zé)管理NPU/GPU/DSP資源Context是邏輯執(zhí)行層負(fù)責(zé)持有模型圖和內(nèi)部狀態(tài)。整個(gè)調(diào)用序列可以分成四步獲取QNN接口初始化Backend。用導(dǎo)入的Context Binary創(chuàng)建Context。從Context中獲取Graph并綁定輸入輸出張量。執(zhí)行推理讀取結(jié)果。代碼寫起來會(huì)有一些宏和版本差異但接口骨架非常穩(wěn)定。下面我會(huì)拆成幾個(gè)代碼塊來解析。3.2 從QNN Backend初始化到加載Context Binary先看接口獲取和初始化的代碼#include QnnInterface.h #include QnnTypes.h #include QnnContext.h #include QnnGraph.h #include QnnTensor.h #include iostream #include vector #include cstring #include fstream #include dlfcn.h using QnnFunctionTable QNN_INTERFACE_VER_TYPE; QnnFunctionTable* g_qnn nullptr; Qnn_BackendHandle_t g_backend nullptr; Qnn_ContextHandle_t g_context nullptr; bool loadQnnInterface(const char* backendLibPath) { void* handle dlopen(backendLibPath, RTLD_NOW | RTLD_GLOBAL); if (!handle) { std::cerr dlopen failed: dlerror() std::endl; return false; } auto getProviders (Qnn_ErrorHandle_t (*)(const QnnInterface_t***, uint32_t*)) dlsym(handle, QnnInterface_getProviders); if (!getProviders) { std::cerr cannot find QnnInterface_getProviders std::endl; return false; } const QnnInterface_t** providers nullptr; uint32_t numProviders 0; if (getProviders(providers, numProviders) ! QNN_SUCCESS || numProviders 0) { std::cerr no QNN providers found std::endl; return false; } g_qnn providers[0]-QNN_INTERFACE_VER_TYPE; return true; }dlopen那一步就相當(dāng)于在運(yùn)行時(shí)加載HTP驅(qū)動(dòng)的前端庫(kù)。為什么要用dlopen而不是直接鏈接因?yàn)槟憧梢酝ㄟ^命令行參數(shù)傳入不同的Backend庫(kù)路徑程序變得更靈活。想切到GPU Backend時(shí)只需要換個(gè)路徑即可不用重新編譯。拿到接口之后開始初始化Backend和Contextbool initBackendAndContext(const std::string modelPath) { if (!g_qnn) return false; // 初始化后端 if (g_qnn-backendInitialize(nullptr) ! QNN_SUCCESS) { std::cerr backend initialize failed std::endl; return false; } // 創(chuàng)建后端句柄 Qnn_Backend_Config_t* backendConfig nullptr; if (g_qnn-backendCreate(nullptr, backendConfig, g_backend) ! QNN_SUCCESS) { std::cerr backend create failed std::endl; return false; } // 讀取Context Binary內(nèi)容 std::ifstream binFile(modelPath, std::ios::binary); std::vectoruint8_t buffer((std::istreambuf_iteratorchar(binFile)), std::istreambuf_iteratorchar()); if (buffer.empty()) { std::cerr model binary is empty std::endl; return false; } // 從二進(jìn)制直接創(chuàng)建Context Qnn_Context_Config_t contextConfig; memset(contextConfig, 0, sizeof(contextConfig)); Qnn_ContextCreateFromBinary_Config_t* ctxCreateConfig nullptr; if (g_qnn-contextCreateFromBinary( g_backend, nullptr, buffer.data(), buffer.size(), g_context, ctxCreateConfig) ! QNN_SUCCESS) { std::cerr context create from binary failed std::endl; return false; } return true; }這里要解釋一下為什么用contextCreateFromBinary而不是contextCreate。contextCreate要求傳入網(wǎng)絡(luò)描述符運(yùn)行時(shí)再?gòu)拿枋龇麡?gòu)建圖。而contextCreateFromBinary接收的是離線生成好的二進(jìn)制執(zhí)行計(jì)劃所有算子的選擇、內(nèi)存分配、依賴關(guān)系都已經(jīng)確定。路徑短、開銷小、穩(wěn)定可靠這就是上一章極力推薦Context Binary的原因。執(zhí)行完以上代碼模型其實(shí)已經(jīng)在HTP上初步建立了執(zhí)行上下文但還缺輸入輸出張量這塊拼圖。3.3 創(chuàng)建輸入輸出Tensor并填充數(shù)據(jù)張量在QNN里是一個(gè)非常重要的抽象它描述了一塊數(shù)據(jù)區(qū)以及它的維度、數(shù)據(jù)類型、量化參數(shù)等信息。創(chuàng)建張量的代碼如下bool createInputTensor(const std::string name, const std::vectoruint32_t dims, Qnn_Tensor_t tensor) { tensor QNN_TENSOR_INIT; tensor.type QNN_TENSOR_TYPE_APP_WRITE; // 輸入張量由應(yīng)用寫入 tensor.dataFormat QNN_TENSOR_DATA_FORMAT_FLOAT_32; Qnn_TensorData_t td tensor.tensorData; td.name name.c_str(); td.rank static_castuint32_t(dims.size()); td.dimensions const_castuint32_t*(dims.data()); td.dataType QNN_DATATYPE_FLOAT_32; td.quantizeParams.encodingDefinition QNN_TENSOR_QUANTIZATION_NONE; if (g_qnn-tensorCreate(g_context, tensor) ! QNN_SUCCESS) { std::cerr tensor create failed: name std::endl; return false; } return true; }QNN_TENSOR_TYPE_APP_WRITE表示這塊內(nèi)存在設(shè)備端由應(yīng)用側(cè)負(fù)責(zé)寫入。還有一種常見類型是QNN_TENSOR_TYPE_APP_READ用于輸出張量表示應(yīng)用需要從設(shè)備端讀取結(jié)果。當(dāng)然也有QNN_TENSOR_TYPE_NATIVE這類直接綁定設(shè)備內(nèi)存的用法但那是性能優(yōu)化階段才需要考慮的事第一次跑通流程時(shí)先用APP_WRITE/APP_READ最省心。創(chuàng)建完輸入張量后要把圖像數(shù)據(jù)填進(jìn)去void fillInputTensor(Qnn_Tensor_t tensor, const std::vectorfloat imageData) { // 先讓QNN獲取一塊可寫入的數(shù)據(jù)指針 void* tensorData nullptr; g_qnn-tensorGetData(tensor, tensorData); if (tensorData nullptr) { std::cerr input tensor data pointer is null std::endl; return; } memcpy(tensorData, imageData.data(), imageData.size() * sizeof(float)); }輸出張量的創(chuàng)建邏輯類似但type要改成QNN_TENSOR_TYPE_APP_READ。這里的核心概念是QNN的輸入輸出張量本質(zhì)上是共享內(nèi)存的通道你往輸入張量綁定的指針里寫數(shù)據(jù)模型執(zhí)行時(shí)直接讀這塊內(nèi)存執(zhí)行結(jié)束后從輸出張量綁定的指針里取數(shù)據(jù)。把數(shù)據(jù)搬進(jìn)去和取出來是整個(gè)流程唯一需要顯式操作內(nèi)存的地方。3.4 執(zhí)行推理和結(jié)果讀取執(zhí)行推理是整個(gè)項(xiàng)目最爽的一步代碼反而是所有環(huán)節(jié)里最簡(jiǎn)短的bool runInference(Qnn_Tensor_t inputTensor, Qnn_Tensor_t outputTensor) { // 獲取模型中的圖句柄 Qnn_GraphHandle_t graphHandle nullptr; Qnn_GraphHandle_t* graphList nullptr; uint32_t numGraphs 0; if (g_qnn-contextGetGraphs(g_context, graphList, numGraphs) ! QNN_SUCCESS) { std::cerr context get graphs failed std::endl; return false; } if (numGraphs 0) { std::cerr no graph in context std::endl; return false; } graphHandle graphList[0]; // 將輸入輸出張量綁定到執(zhí)行 Qnn_Tensor_t tensors[2] { inputTensor, outputTensor }; if (g_qnn-graphExecute(graphHandle, tensors, 2, nullptr, nullptr) ! QNN_SUCCESS) { std::cerr graph execute failed std::endl; return false; } // 讀取輸出數(shù)據(jù) void* outData nullptr; g_qnn-tensorGetData(outputTensor, outData); float* floatOut reinterpret_castfloat*(outData); std::cout Inference done. First 10 outputs: std::endl; for (int i 0; i 10; i) { std::cout floatOut[i] ; } std::cout std::endl; return true; }graphExecute的執(zhí)行是同步的調(diào)用返回時(shí)推理就已經(jīng)完成了。如果你做的是視頻流或者連續(xù)多幀處理建議在創(chuàng)建Context時(shí)打開異步執(zhí)行相關(guān)的配置改成邊采集邊推理的方式提升吞吐。后面章節(jié)會(huì)展開說。一個(gè)容易忽略的細(xì)節(jié)是contextGetGraphs拿到的圖句柄列表是Context內(nèi)部的不需要自行釋放。如果你加載的Context Binary里包含了多個(gè)模型比如一個(gè)檢測(cè)模型加一個(gè)特征模型遍歷這個(gè)數(shù)組就能拿到所有圖句柄分別執(zhí)行。實(shí)際項(xiàng)目中很有用。3.5 資源釋放的正確順序資源釋放順序有講究別小看這最后一步。一個(gè)常見的錯(cuò)誤是先把Backend銷毀了再銷毀Context然后程序崩潰。正確的順序是void cleanup() { if (g_context) { g_qnn-contextFree(g_context); g_context nullptr; } if (g_backend) { g_qnn-backendFree(g_backend); g_backend nullptr; } // 后端terminate放最后 g_qnn-backendTerminate(nullptr); }先釋放Context再釋放Backend最后調(diào)用backendTerminate。原因很簡(jiǎn)單Context還持有Backend內(nèi)部的設(shè)備資源如果先把Backend釋放掉Context在銷毀的時(shí)候會(huì)訪問到一塊已經(jīng)失效的句柄區(qū)域輕則告警重則段錯(cuò)誤。我早期做這塊時(shí)都是直接不釋放進(jìn)程退出讓系統(tǒng)回收后來做長(zhǎng)時(shí)間運(yùn)行的服務(wù)才發(fā)現(xiàn)釋放順序混亂會(huì)導(dǎo)致內(nèi)存持續(xù)上漲最后只能把進(jìn)程重啟。養(yǎng)成正確的釋放習(xí)慣寫出來的服務(wù)才敢跑上幾天幾夜。4. 編譯運(yùn)行與踩坑實(shí)錄從代碼到真正跑起來代碼寫完之后編譯和運(yùn)行階段才是真正開始“打仗”的時(shí)候。這一章我把高頻踩坑點(diǎn)整理出來希望能幫你從報(bào)錯(cuò)大海里快速爬出來。4.1 編譯期錯(cuò)誤怎么排查編譯命令大致是這樣aarch64-linux-gnu-g -stdc17 qnn_runner.cpp -o qnn_runner \ -I$QNN_SDK_ROOT/include \ -L$QNN_SDK_ROOT/lib/aarch64-unknown-linux-gnu \ -Wl,-rpath,$QNN_SDK_ROOT/lib/aarch64-unknown-linux-gnu這里重點(diǎn)說一下-Wl,-rpath的作用。編譯時(shí)鏈接的庫(kù)在運(yùn)行時(shí)也要能被找到如果你不在編譯時(shí)指定rpath運(yùn)行前就必須手動(dòng)設(shè)置LD_LIBRARY_PATH。跑服務(wù)的時(shí)候很容易忘記設(shè)置然后看到一連串error while loading shared libraries排查半天才發(fā)現(xiàn)是動(dòng)態(tài)庫(kù)路徑問題。把它編進(jìn)二進(jìn)制里一勞永逸。編譯期最常遇到的第一類報(bào)錯(cuò)是找不到頭文件比如fatal error: QnnType.h: No such file or directory。這通常是-I路徑寫錯(cuò)了檢查一下SDK里的include目錄結(jié)構(gòu)把路徑對(duì)準(zhǔn)包含QnnInterface.h的那一層。第二類報(bào)錯(cuò)是鏈接時(shí)找不到QnnInterface_getProviders符號(hào)報(bào)undefined reference。多半是因?yàn)槟阌昧薈編譯器但接口頭文件里的函數(shù)沒有用extern C包裹。QNN頭文件有的版本自帶兼容處理有的版本則需要在包含前手動(dòng)加上extern C { #include QnnInterface.h }這個(gè)問題很隱蔽因?yàn)榫幾g器報(bào)錯(cuò)行號(hào)往往指向你的源文件而不是頭文件讓人誤以為是自己代碼寫錯(cuò)了。后來我在項(xiàng)目規(guī)則里固定了一條所有QNN相關(guān)頭文件一律用extern C包含從此再?zèng)]遇到過這類鏈接問題。4.2 運(yùn)行時(shí)錯(cuò)誤速查表運(yùn)行時(shí)錯(cuò)誤五花八門把幾個(gè)高頻場(chǎng)景列成表格方便對(duì)照排查現(xiàn)象常見原因處理建議dlopen失敗libQnnHtp.so: cannot open shared object fileLD_LIBRARY_PATH沒指對(duì)或者庫(kù)架構(gòu)不匹配先確認(rèn)當(dāng)前運(yùn)行的機(jī)器架構(gòu)再設(shè)置對(duì)應(yīng)的庫(kù)路徑backendCreate返回錯(cuò)誤沒有更多日志HTP固件版本和SDK版本不匹配檢查設(shè)備的DSP固件版本升級(jí)Hexagon SDK或更換QNN版本contextCreateFromBinary報(bào)RPC_ERRORHTP驅(qū)動(dòng)沒加載或者權(quán)限不足確認(rèn)設(shè)備端是否已經(jīng)啟動(dòng)QNN的RPC服務(wù)用高通提供的run工具初始化環(huán)境輸入張量數(shù)據(jù)寫不進(jìn)去tensorGetData返回空指針張量類型設(shè)置錯(cuò)誤用了NATIVE類型卻沒有綁定設(shè)備內(nèi)存首次跑通流程用QNN_TENSOR_TYPE_APP_WRITEgraphExecute崩潰提示張量名稱不匹配代碼里創(chuàng)建張量的名字和模型里不一致用qnn-model-tool --print_info查看模型真實(shí)張量名推理結(jié)果全是0輸入數(shù)據(jù)沒寫進(jìn)張量或者量化參數(shù)設(shè)置不對(duì)先用float模型跑通再切量化模型對(duì)比結(jié)果這里補(bǔ)充一個(gè)容易忽略的點(diǎn)如果設(shè)備上跑的是沒有root權(quán)限的用戶態(tài)進(jìn)程訪問HTP可能會(huì)被SELinux或者權(quán)限策略攔下來報(bào)一些看起來完全莫名其妙的錯(cuò)誤。遇到這類問題先檢查日志看有沒有權(quán)限相關(guān)的關(guān)鍵字。沒有權(quán)限就用系統(tǒng)管理員協(xié)助調(diào)整配置不要試圖硬繞權(quán)限限制。4.3 打開日志和調(diào)試技巧QNN內(nèi)部有一套完整的日志機(jī)制調(diào)試的時(shí)候打開日志能幫你少走很多彎路。export QNN_LOG_LEVELVERBOSE ./qnn_runner日志級(jí)別從低到高通常是ERROR、WARN、INFO、VERBOSE。平時(shí)跑服務(wù)用WARN就行檢查問題時(shí)開到VERBOSE。開啟后你會(huì)看到SDK內(nèi)部每一步在做什么比如加載后端、創(chuàng)建Context、綁定張量、執(zhí)行算子。有一次模型執(zhí)行結(jié)果不對(duì)打開日志才發(fā)現(xiàn)是某些算子在HTP上走了低精度分支數(shù)值精度下降導(dǎo)致結(jié)果偏差但整個(gè)流程本身沒有報(bào)錯(cuò)。這種問題不開日志根本無從查起。還有一個(gè)小技巧在代碼里加一個(gè)getElapsedTime的計(jì)時(shí)模塊分別統(tǒng)計(jì)模型加載耗時(shí)和推理耗時(shí)。模型加載耗時(shí)可以用來判斷Context Binary是否真的被完整加載推理耗時(shí)可以判斷模型是否真的跑在了HTP上。如果推理耗時(shí)和純CPU實(shí)現(xiàn)差不多那就要懷疑是不是量化沒生效或者Backend配置里禁用了HTP加速。4.4 如何確認(rèn)推理真的跑在HTP上這里插一個(gè)重要驗(yàn)證步驟怎么確認(rèn)模型不是跑在CPU上最簡(jiǎn)單的方法是看執(zhí)行時(shí)間。一個(gè)MobileNetV2量化的模型在驍龍8系列平臺(tái)上跑推理時(shí)間通常只有幾毫秒如果代碼配置正確肉眼可見地比純CPU快。另一種方式是在QNN日志里搜索HtpGraph之類的關(guān)鍵字VERBOSE日志會(huì)打印出后端執(zhí)行時(shí)的算子調(diào)度信息。更嚴(yán)謹(jǐn)?shù)淖龇ㄊ菍?shí)測(cè)功耗。把設(shè)備插上功率計(jì)跑100次推理對(duì)比CPU版和HTP版的功耗差異。HTP版本通常明顯更低。做功耗對(duì)比的時(shí)候建議把屏幕亮度、無線模塊等因素固定住否則數(shù)據(jù)會(huì)被干擾帶偏。日志確認(rèn)和功耗測(cè)量都做過之后基本可以放心你的模型已經(jīng)真正跑在高通NPU上了。5. 性能優(yōu)化與落地建議到這里整個(gè)流程已經(jīng)跑通了模型能夠在C程序里被加載和推理。但跑通只是第一步要想真正落地到產(chǎn)品里還有幾個(gè)關(guān)于性能和穩(wěn)定性的問題需要處理。這部分不是必選項(xiàng)但對(duì)于做長(zhǎng)期項(xiàng)目的人來說非常值得參考。5.1 Tensor內(nèi)存分配與對(duì)齊前面提到APP_WRITE/APP_READ張量類型最省心但在追求極致性能時(shí)可以考慮使用QNN_TENSOR_TYPE_NATIVE并把輸入輸出緩沖區(qū)直接綁到設(shè)備端。這種做法的好處是省去了Host和Device之間的一次內(nèi)存拷貝。如果決定用原生內(nèi)存綁定的方式就必須注意內(nèi)存對(duì)齊。QNN的HTP后端對(duì)緩沖區(qū)有對(duì)齊要求通常是256字節(jié)或者更高具體值可以在SDK的文檔中查到。用posix_memalign分配內(nèi)存設(shè)置QNN_TENSOR_MEM_TYPE_DMA等類型再通過tensorCreateCustom綁定能明顯降低單次推理的負(fù)載。不過這屬于進(jìn)階優(yōu)化第一次做項(xiàng)目不建議直接上。先用APP_WRITE/APP_READ把功能做對(duì)之后再用性能剖析工具找出真正的瓶頸點(diǎn)再有針對(duì)性地替換成原生內(nèi)存方案。5.2 Context復(fù)用與多模型切換在一個(gè)長(zhǎng)期運(yùn)行的應(yīng)用里不要每推理一幀就創(chuàng)建一個(gè)新Context這是非常浪費(fèi)的。一個(gè)Context可以復(fù)用很多次graphExecute是線程安全還是需要加鎖取決于具體后端實(shí)現(xiàn)但通常建議一個(gè)Context對(duì)應(yīng)一個(gè)推理線程保持穩(wěn)定的調(diào)用頻率。多線程場(chǎng)景下要么給Context加鎖要么創(chuàng)建多個(gè)Context每個(gè)線程持有一個(gè)后者吞吐更好。如果你有多個(gè)模型需要切換推理可以一次性把所有模型的Context Binary都加載進(jìn)來每個(gè)模型對(duì)應(yīng)一個(gè)Context和一組輸入輸出張量。執(zhí)行時(shí)按需調(diào)用對(duì)應(yīng)Context的圖切換開銷很小。這種設(shè)計(jì)比每次切換都創(chuàng)建銷毀Context要穩(wěn)得多內(nèi)存占用也更好預(yù)估。5.3 我的個(gè)人維護(hù)習(xí)慣最后分享一個(gè)我自己的習(xí)慣每跑通一個(gè)新模型就在項(xiàng)目目錄下新建一個(gè)model_config.txt把模型版本、輸入尺寸、量化方案、Backend庫(kù)版本、生成Context Binary的命令全部記錄下來。這東西看機(jī)器折騰久了半年后回來看項(xiàng)目如果沒有一份配置記錄你會(huì)對(duì)著一個(gè)陌生模型文件發(fā)半天呆。我看過太多人拿著別人給的Context Binary直接接進(jìn)業(yè)務(wù)代碼出了問題不知道是后端不兼容還是模型轉(zhuǎn)換有誤只能從頭排查。提前把版本信息記錄好配合上面說的日志分級(jí)機(jī)制排查問題基本能砍掉一半時(shí)間。QNN整套東西上手之后會(huì)發(fā)現(xiàn)它的接口設(shè)計(jì)一旦理順剩下的就是機(jī)械式調(diào)用。真正決定項(xiàng)目上限的反而是在模型轉(zhuǎn)換階段對(duì)算子兼容性的把握以及在C側(cè)對(duì)張量生命周期的管理能力。第一次跑通別著急上性能優(yōu)化先讓整個(gè)鏈路穩(wěn)定轉(zhuǎn)起來再一步步打磨細(xì)節(jié)。