寫這篇東西的起因是我在做一個(gè)Windows桌面端工具的時(shí)候需要在純離線環(huán)境下跑一個(gè)圖像分類模型。Python那邊訓(xùn)練推理都順得很但一放到用戶桌面上就麻煩總不能要求每個(gè)客戶端都裝Python環(huán)境也不能實(shí)時(shí)把圖片傳服務(wù)器。最后選定用Qt做界面把神經(jīng)網(wǎng)絡(luò)推理直接編譯進(jìn)C程序里。整個(gè)集成過(guò)程不算特別復(fù)雜但坑確實(shí)不少尤其是庫(kù)版本、線程模型和圖像預(yù)處理這幾個(gè)環(huán)節(jié)每一個(gè)都值得單獨(dú)拿出來(lái)說(shuō)。這篇文章就把整個(gè)方案從頭到尾梳理清楚給同樣需要在Windows下用Qt調(diào)用神經(jīng)網(wǎng)絡(luò)的人一份可以直接照抄的參考。1. 桌面端為什么需要Qt神經(jīng)網(wǎng)絡(luò)這個(gè)組合1.1 訓(xùn)練只是開(kāi)始部署才是工程的關(guān)鍵很多做算法的人有個(gè)錯(cuò)覺(jué)模型訓(xùn)完、指標(biāo)達(dá)標(biāo)事情就結(jié)束了。真到了工程集成這一步問(wèn)題才會(huì)暴露出來(lái)。你訓(xùn)練時(shí)用的是Python腳本、GPU服務(wù)器、Jupyter Notebook但目標(biāo)產(chǎn)品是一個(gè)需要分發(fā)給普通用戶的Windows桌面程序。那時(shí)候你會(huì)面臨幾個(gè)很現(xiàn)實(shí)的需求用戶機(jī)器上不一定有Python也不應(yīng)該有Python環(huán)境的要求。推理最好在本地完成圖片、文檔這類數(shù)據(jù)不應(yīng)該上傳到任何外部服務(wù)。離線環(huán)境下也要能跑會(huì)議室斷網(wǎng)、客戶內(nèi)網(wǎng)隔離都是常見(jiàn)場(chǎng)景。程序體積、啟動(dòng)速度、內(nèi)存占用要能被普通用戶接受不能一個(gè)模型跑起來(lái)吃掉2GB內(nèi)存。這幾個(gè)需求疊加C桌面程序 本地推理引擎就變成了最優(yōu)解。而Qt作為跨平臺(tái)UI框架在Windows桌面領(lǐng)域積累深、生態(tài)成熟和推理引擎比如ONNX Runtime這種集成起來(lái)也順自然成了首選。1.2 三種常見(jiàn)集成思路的對(duì)比做本地推理市面上其實(shí)有幾條路線可以走我先把它們的利弊擺出來(lái)方便你做選型判斷。方案原理優(yōu)點(diǎn)缺點(diǎn)Python打包PyInstaller等把Python運(yùn)行時(shí)和依賴一起打包進(jìn)去開(kāi)發(fā)速度快算法代碼不用重寫體積大通常200MB啟動(dòng)慢容易被殺軟誤報(bào)Qt C直接集成推理引擎在Qt應(yīng)用內(nèi)加載ONNX等格式模型并做推理性能好體積可控單EXE能跑適合產(chǎn)品化需要寫C橋接代碼調(diào)試鏈路長(zhǎng)本地服務(wù)橋接HTTP/gRPCQt程序啟動(dòng)一個(gè)本地推理服務(wù)通過(guò)本地端口通信前后端解耦Python側(cè)改動(dòng)小進(jìn)程管理復(fù)雜部署目錄更亂異常處理麻煩我的選擇是第二條路Qt直接集成推理引擎。理由是它最像一個(gè)真正的桌面軟件雙擊打開(kāi)就能用不彈黑窗口崩潰問(wèn)題不會(huì)蔓延到界面層。之前我也試過(guò)PyInstaller打包一次誤報(bào)率高得讓人頭疼幾臺(tái)客戶機(jī)器直接隔離了文件光解決白名單問(wèn)題就折騰了兩天所以這回果斷切到C方案。2. 推理引擎選型跨平臺(tái)通用方案優(yōu)先2.1 推理引擎的作用與差異推理引擎干的事通俗講就是把訓(xùn)練好的模型翻譯成當(dāng)前機(jī)器上能高效執(zhí)行的運(yùn)算。同樣的模型在Python里可以靠PyTorch跑但在C環(huán)境里就不能平白無(wú)故地依賴這些重框架了需要一個(gè)輕量級(jí)的專門運(yùn)行時(shí)。我接觸過(guò)幾種主流選擇ONNX Runtime跨平臺(tái)做得最好CPU、GPU都能跑模型生態(tài)極廣幾乎所有訓(xùn)練框架導(dǎo)出的模型都能轉(zhuǎn)成ONNX格式。OpenVINO在Intel CPU和核顯上優(yōu)化得最狠部署包也不大但是離開(kāi)Intel平臺(tái)優(yōu)勢(shì)就沒(méi)那么明顯。TensorRTGPU推理性能天花板但只支持NVIDIA顯卡Windows下部署門檻高顯卡硬件版本還挑。各家自研引擎通常綁定自家硬件通用性差不太適合作為產(chǎn)品化方案的起點(diǎn)?？紤]到目標(biāo)用戶機(jī)器顯卡型號(hào)五花八門甚至不少是核顯辦公本我基本沒(méi)考慮TensorRT。CPU推理才是這個(gè)場(chǎng)景的基準(zhǔn)線ONNX Runtime在這方面表現(xiàn)均衡文檔也全踩坑資料好找。2.2 為什么我最終選定ONNX Runtime從我實(shí)際集成的體驗(yàn)來(lái)說(shuō)選ONNX Runtime有幾個(gè)非?，F(xiàn)實(shí)的原因模型轉(zhuǎn)換鏈短。訓(xùn)練框架PyTorch、Paddle等都能比較輕松地導(dǎo)出ONNX而它又幾乎不需要寫額外代碼導(dǎo)出完成后用Python快速驗(yàn)證一次算子兼容性就行。部署體積可控。ONNX Runtime的Windows動(dòng)態(tài)庫(kù)在20MB上下加上模型和Qt整個(gè)安裝包能做到60MB以內(nèi)。對(duì)比Python打包動(dòng)輒300MB產(chǎn)品體驗(yàn)差距明顯。API生命周期穩(wěn)定。C接口雖然看著有點(diǎn)笨重Ort::Session、Ort::Value這種命名但迭代多年接口變動(dòng)不算激進(jìn)網(wǎng)上資料也夠用。多線程支持成熟。桌面程序里界面線程要響應(yīng)交互推理必須在后臺(tái)線程做ONNX Runtime的C接口可以多線程并發(fā)調(diào)用同一個(gè)Session或在不同線程使用不同Session實(shí)現(xiàn)起來(lái)都不麻煩。2.3 模型轉(zhuǎn)換與算子檢查模型轉(zhuǎn)換這一步看起來(lái)簡(jiǎn)簡(jiǎn)單單一個(gè)torch.onnx.export實(shí)際坑也不少。我習(xí)慣在導(dǎo)出時(shí)就確認(rèn)這幾件事確認(rèn)輸入輸出的名字后面C代碼里要通過(guò)字符串找到輸入輸出張量。確認(rèn)動(dòng)態(tài)軸設(shè)置。如果不想讓圖像寬高固定死就把寬高設(shè)為動(dòng)態(tài)軸如果確定性推理場(chǎng)景固定形狀反而性能更好。確認(rèn)opset版本。導(dǎo)出時(shí)不用刻意追求最新選擇一個(gè)與你的ONNX Runtime版本兼容的即可。導(dǎo)出后用onnxruntime的Python包跑一次輸入真實(shí)數(shù)據(jù)對(duì)比PyTorch結(jié)果誤差在可接受范圍內(nèi)再往下走。這個(gè)小循環(huán)很重要。我見(jiàn)過(guò)太多人導(dǎo)出ONNX之后不驗(yàn)證C那邊折騰半天最后發(fā)現(xiàn)模型本身在導(dǎo)出時(shí)就出了問(wèn)題。導(dǎo)出的模型文件會(huì)放在部署目錄下的models文件夾里加載時(shí)也要注意路徑。3. 環(huán)境搭建Qt工程與推理引擎庫(kù)的正確配置3.1 開(kāi)發(fā)環(huán)境版本組合我用的組合是Qt 6.xMSVC 2019 64位 ONNX Runtime 1.16.xWindows x64版本編譯器和工具鏈保持MSVC統(tǒng)一。這里要特別強(qiáng)調(diào)一個(gè)坑ONNX Runtime官方發(fā)布的預(yù)編譯庫(kù)通常是用MSVC編譯的如果你的Qt套件用的是MinGW兩者能不能直接混用要看運(yùn)氣。MinGW和MSVC的C運(yùn)行庫(kù)、ABI規(guī)范不完全兼容經(jīng)常出現(xiàn)鏈接報(bào)錯(cuò)或者運(yùn)行崩潰。所以我從頭就選了MSVC套件省掉一堆麻煩。安裝時(shí)還要留意CPU架構(gòu)。別在64位程序里鏈接了x86版本的庫(kù)否則加載時(shí)會(huì)直接報(bào)錯(cuò)。如果你需要支持32位系統(tǒng)得單獨(dú)找對(duì)應(yīng)架構(gòu)的庫(kù)。3.2 工程配置關(guān)鍵點(diǎn)ONNX Runtime解壓后的目錄結(jié)構(gòu)一般是onnxruntime-win-x64/ ├── include/ │ └── onnxruntime/ │ ├── core/session/onnxruntime_cxx_api.h │ └── ... └── lib/ ├── onnxruntime.lib └── onnxruntime.dllQt工程里的.pro文件要加這么幾行INCLUDEPATH $$PWD/3rdparty/onnxruntime-win-x64/include LIBS -L$$PWD/3rdparty/onnxruntime-win-x64/lib -lonnxruntime編譯的時(shí)候要鏈接onnxruntime.lib運(yùn)行時(shí)要把onnxruntime.dll放到可執(zhí)行文件旁邊或者放進(jìn)系統(tǒng)PATH能搜到的位置。我習(xí)慣直接在項(xiàng)目的deploy腳本里把DLL拷貝到輸出目錄這樣開(kāi)發(fā)調(diào)試和發(fā)布打包一套流程走完。Debug和Release的運(yùn)行時(shí)DLL理論上都指向同一個(gè)onnxruntime.dll這點(diǎn)比一些純C庫(kù)省心。但如果你遇到崩潰或者鏈接失敗第一個(gè)排查點(diǎn)就是編譯器是否匹配、架構(gòu)是否正確。3.3 第一個(gè)最小推理Demo環(huán)境配置好之后先別急著寫業(yè)務(wù)代碼寫一個(gè)最小程序把模型加載起來(lái)、打印輸出信息確認(rèn)環(huán)境通了再做大功能。大致流程#include iostream #include onnxruntime/core/session/onnxruntime_cxx_api.h int main() { Ort::Env env(ORT_LOGGING_LEVEL_WARNING, test); Ort::SessionOptions sessionOptions; sessionOptions.SetIntraOpNumThreads(4); sessionOptions.SetGraphOptimizationLevel(GraphOptimizationLevel::ORT_ENABLE_ALL); Ort::Session session(env, L./models/model.onnx, sessionOptions); Ort::AllocatorWithDefaultOptions allocator; size_t inputCount session.GetInputCount(); for (size_t i 0; i inputCount; i) { auto name session.GetInputNameAllocated(i, allocator); auto typeInfo session.GetInputTypeInfo(i); auto tensorInfo typeInfo.GetTensorTypeAndShapeInfo(); auto shape tensorInfo.GetShape(); std::cout input: name.get() , shape: ; for (auto dim : shape) std::cout dim ; std::cout std::endl; } return 0; }這里有個(gè)關(guān)鍵點(diǎn)session.GetInputNameAllocated返回的是智能指針管理的內(nèi)存不需要手動(dòng)釋放。如果你看到程序一跑就崩、或者輸出亂碼大概率是模型路徑、DLL路徑或者編譯字符集的問(wèn)題逐個(gè)排查就好。還有一個(gè)常被忽略的細(xì)節(jié)Windows下模型路徑如果包含中文部分版本的ONNX Runtime會(huì)加載失敗。官方給了寬字符接口傳路徑時(shí)建議用L...這樣的寬字符串Qt里則是QString::toStdWString()。我自己遇到過(guò)一次項(xiàng)目目錄恰好放在用戶名中文的路徑下直接卡了半天。4. 橋接層設(shè)計(jì)把推理封裝成Qt能用的C類4.1 接口設(shè)計(jì)原則環(huán)境通了接下來(lái)是核心工程問(wèn)題怎么把推理能力優(yōu)雅地暴露給Qt界面層。我的做法是單獨(dú)建一個(gè)ModelInferencer類對(duì)外只提供兩個(gè)關(guān)鍵方法class ModelInferencer : public QObject { Q_OBJECT public: explicit ModelInferencer(QObject *parent nullptr); ~ModelInferencer(); bool loadModel(const QString modelPath); // 加載模型 bool isLoaded() const; public slots: void infer(const QImage image); // 異步推理入口 signals: void inferenceFinished(const QVariantMap result); void inferenceFailed(const QString message); };設(shè)計(jì)思路上這個(gè)類自己管理一個(gè)后臺(tái)線程和線程安全的任務(wù)隊(duì)列。界面層只需要調(diào)用infer(image)然后等著inferenceFinished信號(hào)拿結(jié)果。界面代碼不碰任何Ort::Value也不感知模型輸出的具體格式。為什么要這樣隔離因?yàn)橥评肀旧砩婕皟?nèi)部狀態(tài)Session、輸入輸出張量如果讓UI線程直接操作這些對(duì)象一方面會(huì)卡界面另一方面多線程并發(fā)時(shí)的數(shù)據(jù)競(jìng)爭(zhēng)會(huì)讓人崩潰。把這個(gè)復(fù)雜性封裝在類內(nèi)部上層怎么調(diào)用都安全。4.2 圖像數(shù)據(jù)從QImage到模型輸入的轉(zhuǎn)換這是最容易翻車、但也是最好理解的一大步。模型輸入通常是一個(gè)四維張量形狀是(batch, channel, height, width)數(shù)值類型是float。而Qt的QImage只是個(gè)二維像素容器這中間隔著一整套轉(zhuǎn)換。我的轉(zhuǎn)換鏈路是用QImage::convertToFormat(QImage::Format_RGB888)統(tǒng)一像素格式?？s放到模型輸入尺寸。把像素?cái)?shù)據(jù)按HWC內(nèi)存布局讀出來(lái)再轉(zhuǎn)換成CHW。做歸一化把[0, 255]映射到模型訓(xùn)練時(shí)用的范圍。第3步是最常錯(cuò)的地方。我見(jiàn)過(guò)不少人直接把QImage::bits()的內(nèi)存塞給模型結(jié)果要么通道順序不對(duì)要么維序不對(duì)推理結(jié)果一片混亂。正確的C寫法大致是這樣// 假設(shè)模型輸入是 1x3x224x224 const int targetWidth 224; const int targetHeight 224; QImage rgbImage image.convertToFormat(QImage::Format_RGB888); QImage scaledImage rgbImage.scaled(targetWidth, targetHeight, Qt::IgnoreAspectRatio, Qt::SmoothTransformation); std::vectorfloat inputTensor(1 * 3 * targetHeight * targetWidth); for (int h 0; h targetHeight; h) { const uchar *line scaledImage.constScanLine(h); for (int w 0; w targetWidth; w) { int index h * targetWidth w; inputTensor[index] (line[w * 3 0] / 255.0f - 0.485f) / 0.229f; inputTensor[targetHeight * targetWidth index] (line[w * 3 1] / 255.0f - 0.456f) / 0.224f; inputTensor[2 * targetHeight * targetWidth index] (line[w * 3 2] / 255.0f - 0.406f) / 0.225f; } }上面的均值和方差是經(jīng)典的ImageNet統(tǒng)計(jì)值。這里要問(wèn)一個(gè)重要問(wèn)題你的模型訓(xùn)練時(shí)的預(yù)處理和這個(gè)一致嗎如果訓(xùn)練代碼里是直接除以255后再歸一化那你推理代碼也要保持一致不能想當(dāng)然地套一套均值方差。很多人最后推理結(jié)果差得離譜問(wèn)題就在這。另外注意QImage::Format_RGB888的像素排列是R、G、B但如果你用了OpenCV的cv::Mat讀圖那默認(rèn)是BGR順序。如果模型訓(xùn)練時(shí)的輸入是RGB直接用OpenCV的Mat塞給模型通道順序就反了。這個(gè)坑幾乎是C推理必踩務(wù)必在自己的工具層里定義好統(tǒng)一輸入格式。4.3 前處理與后處理的封裝前處理可以抽象成一個(gè)函數(shù)輸入QImage輸出std::vectorfloat張量數(shù)據(jù)。后處理也一樣模型輸出的原始張量要先翻譯成業(yè)務(wù)結(jié)果。以分類模型為例輸出通常是一個(gè)(1, numClasses)的浮點(diǎn)數(shù)向量。我后處理會(huì)做兩件事用softmax把分?jǐn)?shù)歸一化成概率。取top-k把類別索引和置信度封裝成QVariantMap返回給UI。QVariantMap ModelInferencer::postprocess(const std::vectorfloat logits, int topK) { // softmax float maxVal *std::max_element(logits.begin(), logits.end()); std::vectorfloat expLogits(logits.size()); float sumExp 0.0f; for (size_t i 0; i logits.size(); i) { expLogits[i] std::exp(logits[i] - maxVal); sumExp expLogits[i]; } // topK std::vectorstd::pairint, float scores; for (size_t i 0; i expLogits.size(); i) { scores.emplace_back(static_castint(i), expLogits[i] / sumExp); } std::partial_sort(scores.begin(), scores.begin() topK, scores.end(), [](const auto a, const auto b) { return a.second b.second; }); QVariantMap result; QVariantList list; for (int i 0; i topK; i) { QVariantMap item; item[index] scores[i].first; item[score] scores[i].second; list.append(item); } result[topK] list; return result; }如果是檢測(cè)模型輸出結(jié)構(gòu)更復(fù)雜通常包含邊界框坐標(biāo)、目標(biāo)置信度、類別概率。解碼邏輯要根據(jù)訓(xùn)練時(shí)的標(biāo)注方式寫這個(gè)就不細(xì)展開(kāi)了但核心思路一樣把張量數(shù)據(jù)轉(zhuǎn)換成UI能直接理解的業(yè)務(wù)結(jié)構(gòu)。5. 多線程與UI推理放線程池界面才不會(huì)卡死5.1 為什么不能直接在UI線程推理一個(gè)分類模型在CPU上跑快的時(shí)候5到15毫秒可能感覺(jué)不出來(lái)卡。但遇到檢測(cè)模型、分割模型或者較大輸入圖單次推理可能到80到150毫秒。任何超過(guò)100毫秒的同步操作放在UI線程用戶就能明顯感到界面卡頓拖動(dòng)窗口像拖泥帶水點(diǎn)擊按鈕半天沒(méi)反應(yīng)。更麻煩的是Qt的事件循環(huán)如果被阻塞窗口系統(tǒng)消息也沒(méi)法及時(shí)處理極端情況下Windows會(huì)彈出程序未響應(yīng)的提示。所以不管推理多快只要不是毫秒級(jí)就絕不能在UI線程里同步調(diào)Session。5.2 信號(hào)槽驅(qū)動(dòng)下的推理流程我采用的模式是界面線程發(fā)出推理請(qǐng)求后臺(tái)工作線程執(zhí)行推理完成后通過(guò)信號(hào)把結(jié)果傳回界面線程。這樣UI線程永遠(yuǎn)不被阻塞用戶操作始終流暢。具體實(shí)現(xiàn)上我在ModelInferencer類內(nèi)部維護(hù)一個(gè)QThreadPool用QtConcurrent::run啟動(dòng)異步任務(wù)void ModelInferencer::infer(const QImage image) { if (!m_session) { emit inferenceFailed(QStringLiteral(模型尚未加載)); return; } // 深拷貝圖像避免在后臺(tái)線程里訪問(wèn)可能被修改的QImage QImage copy image.copy(); QtConcurrent::run([this, copy]() { try { QVariantMap result doInference(copy); // 真正耗時(shí)的工作 emit inferenceFinished(result); } catch (const std::exception e) { emit inferenceFailed(QString::fromUtf8(e.what())); } }); }這里有個(gè)細(xì)節(jié)值得注意image.copy()不是可選操作。如果直接把外界的QImage引用傳進(jìn)后臺(tái)線程萬(wàn)一用戶在這個(gè)圖像被讀的過(guò)程中做了二次修改比如在界面上裁剪、繪制標(biāo)注后臺(tái)線程讀到的像素?cái)?shù)據(jù)就可能不一致甚至崩潰。深拷貝一張圖像的成本通常不高幾百KB到幾MB的像素拷貝換來(lái)的是確定性的線程安全?；卣{(diào)結(jié)果走信號(hào)槽跨線程傳遞時(shí)Qt會(huì)自動(dòng)使用隊(duì)列連接信號(hào)發(fā)出去后在接收方的線程里執(zhí)行槽函數(shù)天然避開(kāi)了數(shù)據(jù)競(jìng)爭(zhēng)。那Ort::Session線程安全嗎ONNX Runtime的C接口是允許同一個(gè)Session被多個(gè)線程并發(fā)調(diào)用的官方文檔也說(shuō)session線程安全。但實(shí)踐中我更傾向于每個(gè)推理線程共享一個(gè)Session因?yàn)椴l(fā)調(diào)用時(shí)會(huì)內(nèi)部加鎖性能不會(huì)因?yàn)槎嗑€程調(diào)用而惡化太多如果對(duì)性能要求極端苛刻可以每個(gè)工作線程單獨(dú)創(chuàng)建Session代價(jià)是內(nèi)存占用翻倍。我一般用共享Session配合SetIntraOpNumThreads控制單次推理的線程數(shù)。5.3 批量推理與請(qǐng)求排隊(duì)如果你的場(chǎng)景是一次性提交一堆圖片做批處理單張單張地按異步信號(hào)發(fā)散效率太低。我后來(lái)加了一個(gè)隊(duì)列機(jī)制界面層分別調(diào)用infer每次調(diào)用把圖片放進(jìn)QQueueQImage后臺(tái)線程依次取出處理。這樣既保持了UI的響應(yīng)性又能保證多張圖片的推理有序執(zhí)行不會(huì)出現(xiàn)并發(fā)請(qǐng)求導(dǎo)致輸出順序錯(cuò)亂的情況。隊(duì)列實(shí)現(xiàn)起來(lái)不復(fù)雜核心是給QQueue加上QMutex保護(hù)再配合QWaitCondition喚醒工作線程。如果你不想手寫隊(duì)列也可以用QThreadPool加QRunnable的方式接受任務(wù)亂序完成再在界面上按圖片ID對(duì)應(yīng)結(jié)果?？茨愕臉I(yè)務(wù)是否關(guān)心順序。6. 實(shí)測(cè)數(shù)據(jù)、性能瓶頸與部署中的幾個(gè)大坑6.1 端到端延遲與資源占用我拿一個(gè)通用分類模型輸入224x224在普通辦公機(jī)上做了個(gè)粗略測(cè)試配置大致是i5處理器、16GB內(nèi)存、無(wú)獨(dú)立顯卡。單張圖片的端到端耗時(shí)拆解如下階段耗時(shí)毫秒占比QImage讀取與格式轉(zhuǎn)換3-68%縮放 通道轉(zhuǎn)換 歸一化8-1525%ONNX Runtime推理10-2033%后處理與結(jié)果組裝2-46%其他任務(wù)調(diào)度、內(nèi)存拷貝5-1018%總耗電通常在30到55毫秒之間對(duì)交互工具類應(yīng)用來(lái)說(shuō)是完全可接受的。如果你想要更快的速度我實(shí)驗(yàn)過(guò)的有效手段有三個(gè)把圖像縮放到模型輸入尺寸這一步放在推理線程里做避免UI線程做多余工作。用cv::resize替代QImage::scaled。說(shuō)實(shí)話QImage::scaled在縮放效率上一般OpenCV的插值優(yōu)化好得多只是要把數(shù)據(jù)從QImage轉(zhuǎn)到cv::Mat多一道拷貝但整體收益通常是正的。模型量化。將ONNX模型轉(zhuǎn)成INT8量化版本CPU推理速度能提升1.5到2倍代價(jià)是精度損失在分類這種容錯(cuò)度高的場(chǎng)景基本無(wú)感。6.2 踩坑記錄DLL加載失敗與程序直接閃退這是我集成過(guò)程中遇到的第一個(gè)大坑。程序編譯通過(guò)一運(yùn)行直接報(bào)0xc000007b或者提示找不到onnxruntime.dll。排查鏈路是這樣的先確認(rèn)DLL是否放在了可執(zhí)行文件同目錄。放錯(cuò)位置是最常見(jiàn)的原因。再確認(rèn)DLL的架構(gòu)。有個(gè)同事把x86的DLL當(dāng)成x64用了一運(yùn)行就報(bào)錯(cuò)。然后用Dependency Walker或者Visual Studio的調(diào)試輸出看Loader實(shí)際加載了哪個(gè)路徑的DLL。有時(shí)候系統(tǒng)PATH里有舊版本的DLL程序優(yōu)先加載了那個(gè)版本不對(duì)就崩了。最后檢查Qt工具鏈?zhǔn)荕SVC還是MinGW。如果你用MinGW去鏈接MSVC編譯的庫(kù)鏈接階段可能過(guò)但運(yùn)行時(shí)就崩。那次最后定位到的原因是我開(kāi)發(fā)機(jī)器上裝過(guò)另一個(gè)軟件往PATH里塞了一個(gè)舊版DLLQt運(yùn)行時(shí)先找到了這個(gè)舊版直接崩掉。解決辦法是把onnxruntime.dll直接放到可執(zhí)行文件旁邊并保證它和程序在同一個(gè)目錄而不是依賴PATH搜索順序。6.3 踩坑記錄輸入數(shù)據(jù)錯(cuò)位推理結(jié)果完全不對(duì)環(huán)境跑通之后我激動(dòng)地把第一張貓的圖片塞進(jìn)去結(jié)果模型判定為廁所。檢查了半天最后發(fā)現(xiàn)是在預(yù)處理環(huán)節(jié)出了問(wèn)題。第一個(gè)問(wèn)題是通道順序。我一開(kāi)始直接用QImage::Format_RGB32拿到的數(shù)據(jù)它是一個(gè)像素一個(gè)像素排列的ARGB格式并不是連續(xù)的三通道RGB。我把它當(dāng)RGB888直接填進(jìn)張量等于R、G、B三個(gè)通道的順序全亂了模型看到的完全是噪音。改成先convertToFormat(QImage::Format_RGB888)之后問(wèn)題立刻消失。第二個(gè)問(wèn)題是我把圖像的寬高搞反了。模型輸入是(1, 3, 224, 224)也就是高224、寬224但我在縮放圖像時(shí)用了scaled(224, 224)這個(gè)沒(méi)錯(cuò)但在填充inputTensor時(shí)循環(huán)里寫的索引是h * width w其中width用了224而實(shí)際掃描行的長(zhǎng)度是width * 3字節(jié)如果混淆了像素索引和字節(jié)索引就會(huì)出現(xiàn)奇怪的條紋狀污染推理結(jié)果自然全錯(cuò)。這個(gè)坑給的經(jīng)驗(yàn)是寫圖像預(yù)處理時(shí)先打印一小塊數(shù)據(jù)人工核對(duì)一下像素值是否符合預(yù)期再跑完整推理。不要等到模型輸出離譜了才回頭查。6.4 踩坑記錄歸一化被做了兩次另一個(gè)特別隱蔽的問(wèn)題訓(xùn)練代碼里用了transforms.Normalize導(dǎo)出ONNX的時(shí)候把歸一化也導(dǎo)進(jìn)去了或者說(shuō)模型本身就包含前處理層我在C這邊又做了一遍均值方差歸一化。結(jié)果就是模型輸入范圍被打亂分類置信度全部變得很低模型幾乎對(duì)任何輸入都給出均勻概率。這種問(wèn)題怎么排查我建議在集成階段準(zhǔn)備一張標(biāo)準(zhǔn)輸入的調(diào)試圖先用Python加載模型推理一遍記錄下輸出再用C加載同一個(gè)模型輸入同一個(gè)預(yù)處理后的張量對(duì)比輸出。如果兩邊差異超過(guò)1e-4就說(shuō)明前處理邏輯不一致。這個(gè)對(duì)比其實(shí)很值得做成自動(dòng)化把Python端預(yù)處理后的.npy文件保存下來(lái)C端讀取二進(jìn)制數(shù)據(jù)填充張量然后比對(duì)輸出。這一步能消滅大量隱蔽的前后處理不一致問(wèn)題。6.5 踩坑記錄SessionOptions配置不當(dāng)導(dǎo)致的性能劣化還有一個(gè)性能層面的坑ONNX Runtime默認(rèn)會(huì)開(kāi)啟圖形優(yōu)化ORT_ENABLE_ALL這是好事。但SetIntraOpNumThreads如果設(shè)置得過(guò)小比如1單張圖的推理速度就會(huì)明顯變慢設(shè)置得過(guò)大比如32線程切換的開(kāi)銷又會(huì)抵消并行收益。我實(shí)測(cè)下來(lái)在8核處理器上SetIntraOpNumThreads(4)對(duì)224x224輸入的分類模型收益最大。對(duì)于更小的輸入圖比如128x128線程數(shù)太多反而更慢因?yàn)閱未斡?jì)算量太小線程啟動(dòng)和同步的代價(jià)蓋過(guò)了并行收益。這個(gè)參數(shù)最好根據(jù)你的模型大小和用戶機(jī)器情況做基準(zhǔn)測(cè)試不要默認(rèn)不設(shè)置。最后再說(shuō)一個(gè)體積優(yōu)化的小技巧。ONNX Runtime本身只有一份DLL但如果你不需要GPU推理又不需要它自帶的所有優(yōu)化器可以看看官方提供的精簡(jiǎn)版或自定義構(gòu)建選項(xiàng)。我這邊場(chǎng)景只需要CPU就用官方CPU版安裝包里的DLL從二十幾MB壓到了十幾MB對(duì)分發(fā)體驗(yàn)還是有一點(diǎn)幫助的。整個(gè)Qt ONNX Runtime的推理鏈路跑通之后我最深的一個(gè)體會(huì)是神經(jīng)網(wǎng)絡(luò)部署這件事難點(diǎn)從來(lái)不在模型本身而在數(shù)據(jù)格式、線程調(diào)度和運(yùn)行環(huán)境的細(xì)節(jié)。你把訓(xùn)練代碼搬到C、搬到Windows每一步都要重新審視一次數(shù)據(jù)到底走的是什么形狀、什么順序、什么范圍。只要這個(gè)思路清晰剩下的就只是照著接口敲代碼的事了。 Qt與ONNX Runtime：Windows桌面端本地推理集成指南
寫這篇東西的起因是我在做一個(gè)Windows桌面端工具的時(shí)候需要在純離線環(huán)境下跑一個(gè)圖像分類模型。Python那邊訓(xùn)練推理都順得很但一放到用戶桌面上就麻煩總不能要求每個(gè)客戶端都裝Python環(huán)境也不能實(shí)時(shí)把圖片傳服務(wù)器。最后選定用Qt做界面把神經(jīng)網(wǎng)絡(luò)推理直接編譯進(jìn)C程序里。整個(gè)集成過(guò)程不算特別復(fù)雜但坑確實(shí)不少尤其是庫(kù)版本、線程模型和圖像預(yù)處理這幾個(gè)環(huán)節(jié)每一個(gè)都值得單獨(dú)拿出來(lái)說(shuō)。這篇文章就把整個(gè)方案從頭到尾梳理清楚給同樣需要在Windows下用Qt調(diào)用神經(jīng)網(wǎng)絡(luò)的人一份可以直接照抄的參考。1. 桌面端為什么需要Qt神經(jīng)網(wǎng)絡(luò)這個(gè)組合1.1 訓(xùn)練只是開(kāi)始部署才是工程的關(guān)鍵很多做算法的人有個(gè)錯(cuò)覺(jué)模型訓(xùn)完、指標(biāo)達(dá)標(biāo)事情就結(jié)束了。真到了工程集成這一步問(wèn)題才會(huì)暴露出來(lái)。你訓(xùn)練時(shí)用的是Python腳本、GPU服務(wù)器、Jupyter Notebook但目標(biāo)產(chǎn)品是一個(gè)需要分發(fā)給普通用戶的Windows桌面程序。那時(shí)候你會(huì)面臨幾個(gè)很現(xiàn)實(shí)的需求用戶機(jī)器上不一定有Python也不應(yīng)該有Python環(huán)境的要求。推理最好在本地完成圖片、文檔這類數(shù)據(jù)不應(yīng)該上傳到任何外部服務(wù)。離線環(huán)境下也要能跑會(huì)議室斷網(wǎng)、客戶內(nèi)網(wǎng)隔離都是常見(jiàn)場(chǎng)景。程序體積、啟動(dòng)速度、內(nèi)存占用要能被普通用戶接受不能一個(gè)模型跑起來(lái)吃掉2GB內(nèi)存。這幾個(gè)需求疊加C桌面程序 本地推理引擎就變成了最優(yōu)解。而Qt作為跨平臺(tái)UI框架在Windows桌面領(lǐng)域積累深、生態(tài)成熟和推理引擎比如ONNX Runtime這種集成起來(lái)也順自然成了首選。1.2 三種常見(jiàn)集成思路的對(duì)比做本地推理市面上其實(shí)有幾條路線可以走我先把它們的利弊擺出來(lái)方便你做選型判斷。方案原理優(yōu)點(diǎn)缺點(diǎn)Python打包PyInstaller等把Python運(yùn)行時(shí)和依賴一起打包進(jìn)去開(kāi)發(fā)速度快算法代碼不用重寫體積大通常200MB啟動(dòng)慢容易被殺軟誤報(bào)Qt C直接集成推理引擎在Qt應(yīng)用內(nèi)加載ONNX等格式模型并做推理性能好體積可控單EXE能跑適合產(chǎn)品化需要寫C橋接代碼調(diào)試鏈路長(zhǎng)本地服務(wù)橋接HTTP/gRPCQt程序啟動(dòng)一個(gè)本地推理服務(wù)通過(guò)本地端口通信前后端解耦Python側(cè)改動(dòng)小進(jìn)程管理復(fù)雜部署目錄更亂異常處理麻煩我的選擇是第二條路Qt直接集成推理引擎。理由是它最像一個(gè)真正的桌面軟件雙擊打開(kāi)就能用不彈黑窗口崩潰問(wèn)題不會(huì)蔓延到界面層。之前我也試過(guò)PyInstaller打包一次誤報(bào)率高得讓人頭疼幾臺(tái)客戶機(jī)器直接隔離了文件光解決白名單問(wèn)題就折騰了兩天所以這回果斷切到C方案。2. 推理引擎選型跨平臺(tái)通用方案優(yōu)先2.1 推理引擎的作用與差異推理引擎干的事通俗講就是把訓(xùn)練好的模型翻譯成當(dāng)前機(jī)器上能高效執(zhí)行的運(yùn)算。同樣的模型在Python里可以靠PyTorch跑但在C環(huán)境里就不能平白無(wú)故地依賴這些重框架了需要一個(gè)輕量級(jí)的專門運(yùn)行時(shí)。我接觸過(guò)幾種主流選擇ONNX Runtime跨平臺(tái)做得最好CPU、GPU都能跑模型生態(tài)極廣幾乎所有訓(xùn)練框架導(dǎo)出的模型都能轉(zhuǎn)成ONNX格式。OpenVINO在Intel CPU和核顯上優(yōu)化得最狠部署包也不大但是離開(kāi)Intel平臺(tái)優(yōu)勢(shì)就沒(méi)那么明顯。TensorRTGPU推理性能天花板但只支持NVIDIA顯卡Windows下部署門檻高顯卡硬件版本還挑。各家自研引擎通常綁定自家硬件通用性差不太適合作為產(chǎn)品化方案的起點(diǎn)?？紤]到目標(biāo)用戶機(jī)器顯卡型號(hào)五花八門甚至不少是核顯辦公本我基本沒(méi)考慮TensorRT。CPU推理才是這個(gè)場(chǎng)景的基準(zhǔn)線ONNX Runtime在這方面表現(xiàn)均衡文檔也全踩坑資料好找。2.2 為什么我最終選定ONNX Runtime從我實(shí)際集成的體驗(yàn)來(lái)說(shuō)選ONNX Runtime有幾個(gè)非?，F(xiàn)實(shí)的原因模型轉(zhuǎn)換鏈短。訓(xùn)練框架PyTorch、Paddle等都能比較輕松地導(dǎo)出ONNX而它又幾乎不需要寫額外代碼導(dǎo)出完成后用Python快速驗(yàn)證一次算子兼容性就行。部署體積可控。ONNX Runtime的Windows動(dòng)態(tài)庫(kù)在20MB上下加上模型和Qt整個(gè)安裝包能做到60MB以內(nèi)。對(duì)比Python打包動(dòng)輒300MB產(chǎn)品體驗(yàn)差距明顯。API生命周期穩(wěn)定。C接口雖然看著有點(diǎn)笨重Ort::Session、Ort::Value這種命名但迭代多年接口變動(dòng)不算激進(jìn)網(wǎng)上資料也夠用。多線程支持成熟。桌面程序里界面線程要響應(yīng)交互推理必須在后臺(tái)線程做ONNX Runtime的C接口可以多線程并發(fā)調(diào)用同一個(gè)Session或在不同線程使用不同Session實(shí)現(xiàn)起來(lái)都不麻煩。2.3 模型轉(zhuǎn)換與算子檢查模型轉(zhuǎn)換這一步看起來(lái)簡(jiǎn)簡(jiǎn)單單一個(gè)torch.onnx.export實(shí)際坑也不少。我習(xí)慣在導(dǎo)出時(shí)就確認(rèn)這幾件事確認(rèn)輸入輸出的名字后面C代碼里要通過(guò)字符串找到輸入輸出張量。確認(rèn)動(dòng)態(tài)軸設(shè)置。如果不想讓圖像寬高固定死就把寬高設(shè)為動(dòng)態(tài)軸如果確定性推理場(chǎng)景固定形狀反而性能更好。確認(rèn)opset版本。導(dǎo)出時(shí)不用刻意追求最新選擇一個(gè)與你的ONNX Runtime版本兼容的即可。導(dǎo)出后用onnxruntime的Python包跑一次輸入真實(shí)數(shù)據(jù)對(duì)比PyTorch結(jié)果誤差在可接受范圍內(nèi)再往下走。這個(gè)小循環(huán)很重要。我見(jiàn)過(guò)太多人導(dǎo)出ONNX之后不驗(yàn)證C那邊折騰半天最后發(fā)現(xiàn)模型本身在導(dǎo)出時(shí)就出了問(wèn)題。導(dǎo)出的模型文件會(huì)放在部署目錄下的models文件夾里加載時(shí)也要注意路徑。3. 環(huán)境搭建Qt工程與推理引擎庫(kù)的正確配置3.1 開(kāi)發(fā)環(huán)境版本組合我用的組合是Qt 6.xMSVC 2019 64位 ONNX Runtime 1.16.xWindows x64版本編譯器和工具鏈保持MSVC統(tǒng)一。這里要特別強(qiáng)調(diào)一個(gè)坑ONNX Runtime官方發(fā)布的預(yù)編譯庫(kù)通常是用MSVC編譯的如果你的Qt套件用的是MinGW兩者能不能直接混用要看運(yùn)氣。MinGW和MSVC的C運(yùn)行庫(kù)、ABI規(guī)范不完全兼容經(jīng)常出現(xiàn)鏈接報(bào)錯(cuò)或者運(yùn)行崩潰。所以我從頭就選了MSVC套件省掉一堆麻煩。安裝時(shí)還要留意CPU架構(gòu)。別在64位程序里鏈接了x86版本的庫(kù)否則加載時(shí)會(huì)直接報(bào)錯(cuò)。如果你需要支持32位系統(tǒng)得單獨(dú)找對(duì)應(yīng)架構(gòu)的庫(kù)。3.2 工程配置關(guān)鍵點(diǎn)ONNX Runtime解壓后的目錄結(jié)構(gòu)一般是onnxruntime-win-x64/ ├── include/ │ └── onnxruntime/ │ ├── core/session/onnxruntime_cxx_api.h │ └── ... └── lib/ ├── onnxruntime.lib └── onnxruntime.dllQt工程里的.pro文件要加這么幾行INCLUDEPATH $$PWD/3rdparty/onnxruntime-win-x64/include LIBS -L$$PWD/3rdparty/onnxruntime-win-x64/lib -lonnxruntime編譯的時(shí)候要鏈接onnxruntime.lib運(yùn)行時(shí)要把onnxruntime.dll放到可執(zhí)行文件旁邊或者放進(jìn)系統(tǒng)PATH能搜到的位置。我習(xí)慣直接在項(xiàng)目的deploy腳本里把DLL拷貝到輸出目錄這樣開(kāi)發(fā)調(diào)試和發(fā)布打包一套流程走完。Debug和Release的運(yùn)行時(shí)DLL理論上都指向同一個(gè)onnxruntime.dll這點(diǎn)比一些純C庫(kù)省心。但如果你遇到崩潰或者鏈接失敗第一個(gè)排查點(diǎn)就是編譯器是否匹配、架構(gòu)是否正確。3.3 第一個(gè)最小推理Demo環(huán)境配置好之后先別急著寫業(yè)務(wù)代碼寫一個(gè)最小程序把模型加載起來(lái)、打印輸出信息確認(rèn)環(huán)境通了再做大功能。大致流程#include iostream #include onnxruntime/core/session/onnxruntime_cxx_api.h int main() { Ort::Env env(ORT_LOGGING_LEVEL_WARNING, test); Ort::SessionOptions sessionOptions; sessionOptions.SetIntraOpNumThreads(4); sessionOptions.SetGraphOptimizationLevel(GraphOptimizationLevel::ORT_ENABLE_ALL); Ort::Session session(env, L./models/model.onnx, sessionOptions); Ort::AllocatorWithDefaultOptions allocator; size_t inputCount session.GetInputCount(); for (size_t i 0; i inputCount; i) { auto name session.GetInputNameAllocated(i, allocator); auto typeInfo session.GetInputTypeInfo(i); auto tensorInfo typeInfo.GetTensorTypeAndShapeInfo(); auto shape tensorInfo.GetShape(); std::cout input: name.get() , shape: ; for (auto dim : shape) std::cout dim ; std::cout std::endl; } return 0; }這里有個(gè)關(guān)鍵點(diǎn)session.GetInputNameAllocated返回的是智能指針管理的內(nèi)存不需要手動(dòng)釋放。如果你看到程序一跑就崩、或者輸出亂碼大概率是模型路徑、DLL路徑或者編譯字符集的問(wèn)題逐個(gè)排查就好。還有一個(gè)常被忽略的細(xì)節(jié)Windows下模型路徑如果包含中文部分版本的ONNX Runtime會(huì)加載失敗。官方給了寬字符接口傳路徑時(shí)建議用L...這樣的寬字符串Qt里則是QString::toStdWString()。我自己遇到過(guò)一次項(xiàng)目目錄恰好放在用戶名中文的路徑下直接卡了半天。4. 橋接層設(shè)計(jì)把推理封裝成Qt能用的C類4.1 接口設(shè)計(jì)原則環(huán)境通了接下來(lái)是核心工程問(wèn)題怎么把推理能力優(yōu)雅地暴露給Qt界面層。我的做法是單獨(dú)建一個(gè)ModelInferencer類對(duì)外只提供兩個(gè)關(guān)鍵方法class ModelInferencer : public QObject { Q_OBJECT public: explicit ModelInferencer(QObject *parent nullptr); ~ModelInferencer(); bool loadModel(const QString modelPath); // 加載模型 bool isLoaded() const; public slots: void infer(const QImage image); // 異步推理入口 signals: void inferenceFinished(const QVariantMap result); void inferenceFailed(const QString message); };設(shè)計(jì)思路上這個(gè)類自己管理一個(gè)后臺(tái)線程和線程安全的任務(wù)隊(duì)列。界面層只需要調(diào)用infer(image)然后等著inferenceFinished信號(hào)拿結(jié)果。界面代碼不碰任何Ort::Value也不感知模型輸出的具體格式。為什么要這樣隔離因?yàn)橥评肀旧砩婕皟?nèi)部狀態(tài)Session、輸入輸出張量如果讓UI線程直接操作這些對(duì)象一方面會(huì)卡界面另一方面多線程并發(fā)時(shí)的數(shù)據(jù)競(jìng)爭(zhēng)會(huì)讓人崩潰。把這個(gè)復(fù)雜性封裝在類內(nèi)部上層怎么調(diào)用都安全。4.2 圖像數(shù)據(jù)從QImage到模型輸入的轉(zhuǎn)換這是最容易翻車、但也是最好理解的一大步。模型輸入通常是一個(gè)四維張量形狀是(batch, channel, height, width)數(shù)值類型是float。而Qt的QImage只是個(gè)二維像素容器這中間隔著一整套轉(zhuǎn)換。我的轉(zhuǎn)換鏈路是用QImage::convertToFormat(QImage::Format_RGB888)統(tǒng)一像素格式?？s放到模型輸入尺寸。把像素?cái)?shù)據(jù)按HWC內(nèi)存布局讀出來(lái)再轉(zhuǎn)換成CHW。做歸一化把[0, 255]映射到模型訓(xùn)練時(shí)用的范圍。第3步是最常錯(cuò)的地方。我見(jiàn)過(guò)不少人直接把QImage::bits()的內(nèi)存塞給模型結(jié)果要么通道順序不對(duì)要么維序不對(duì)推理結(jié)果一片混亂。正確的C寫法大致是這樣// 假設(shè)模型輸入是 1x3x224x224 const int targetWidth 224; const int targetHeight 224; QImage rgbImage image.convertToFormat(QImage::Format_RGB888); QImage scaledImage rgbImage.scaled(targetWidth, targetHeight, Qt::IgnoreAspectRatio, Qt::SmoothTransformation); std::vectorfloat inputTensor(1 * 3 * targetHeight * targetWidth); for (int h 0; h targetHeight; h) { const uchar *line scaledImage.constScanLine(h); for (int w 0; w targetWidth; w) { int index h * targetWidth w; inputTensor[index] (line[w * 3 0] / 255.0f - 0.485f) / 0.229f; inputTensor[targetHeight * targetWidth index] (line[w * 3 1] / 255.0f - 0.456f) / 0.224f; inputTensor[2 * targetHeight * targetWidth index] (line[w * 3 2] / 255.0f - 0.406f) / 0.225f; } }上面的均值和方差是經(jīng)典的ImageNet統(tǒng)計(jì)值。這里要問(wèn)一個(gè)重要問(wèn)題你的模型訓(xùn)練時(shí)的預(yù)處理和這個(gè)一致嗎如果訓(xùn)練代碼里是直接除以255后再歸一化那你推理代碼也要保持一致不能想當(dāng)然地套一套均值方差。很多人最后推理結(jié)果差得離譜問(wèn)題就在這。另外注意QImage::Format_RGB888的像素排列是R、G、B但如果你用了OpenCV的cv::Mat讀圖那默認(rèn)是BGR順序。如果模型訓(xùn)練時(shí)的輸入是RGB直接用OpenCV的Mat塞給模型通道順序就反了。這個(gè)坑幾乎是C推理必踩務(wù)必在自己的工具層里定義好統(tǒng)一輸入格式。4.3 前處理與后處理的封裝前處理可以抽象成一個(gè)函數(shù)輸入QImage輸出std::vectorfloat張量數(shù)據(jù)。后處理也一樣模型輸出的原始張量要先翻譯成業(yè)務(wù)結(jié)果。以分類模型為例輸出通常是一個(gè)(1, numClasses)的浮點(diǎn)數(shù)向量。我后處理會(huì)做兩件事用softmax把分?jǐn)?shù)歸一化成概率。取top-k把類別索引和置信度封裝成QVariantMap返回給UI。QVariantMap ModelInferencer::postprocess(const std::vectorfloat logits, int topK) { // softmax float maxVal *std::max_element(logits.begin(), logits.end()); std::vectorfloat expLogits(logits.size()); float sumExp 0.0f; for (size_t i 0; i logits.size(); i) { expLogits[i] std::exp(logits[i] - maxVal); sumExp expLogits[i]; } // topK std::vectorstd::pairint, float scores; for (size_t i 0; i expLogits.size(); i) { scores.emplace_back(static_castint(i), expLogits[i] / sumExp); } std::partial_sort(scores.begin(), scores.begin() topK, scores.end(), [](const auto a, const auto b) { return a.second b.second; }); QVariantMap result; QVariantList list; for (int i 0; i topK; i) { QVariantMap item; item[index] scores[i].first; item[score] scores[i].second; list.append(item); } result[topK] list; return result; }如果是檢測(cè)模型輸出結(jié)構(gòu)更復(fù)雜通常包含邊界框坐標(biāo)、目標(biāo)置信度、類別概率。解碼邏輯要根據(jù)訓(xùn)練時(shí)的標(biāo)注方式寫這個(gè)就不細(xì)展開(kāi)了但核心思路一樣把張量數(shù)據(jù)轉(zhuǎn)換成UI能直接理解的業(yè)務(wù)結(jié)構(gòu)。5. 多線程與UI推理放線程池界面才不會(huì)卡死5.1 為什么不能直接在UI線程推理一個(gè)分類模型在CPU上跑快的時(shí)候5到15毫秒可能感覺(jué)不出來(lái)卡。但遇到檢測(cè)模型、分割模型或者較大輸入圖單次推理可能到80到150毫秒。任何超過(guò)100毫秒的同步操作放在UI線程用戶就能明顯感到界面卡頓拖動(dòng)窗口像拖泥帶水點(diǎn)擊按鈕半天沒(méi)反應(yīng)。更麻煩的是Qt的事件循環(huán)如果被阻塞窗口系統(tǒng)消息也沒(méi)法及時(shí)處理極端情況下Windows會(huì)彈出程序未響應(yīng)的提示。所以不管推理多快只要不是毫秒級(jí)就絕不能在UI線程里同步調(diào)Session。5.2 信號(hào)槽驅(qū)動(dòng)下的推理流程我采用的模式是界面線程發(fā)出推理請(qǐng)求后臺(tái)工作線程執(zhí)行推理完成后通過(guò)信號(hào)把結(jié)果傳回界面線程。這樣UI線程永遠(yuǎn)不被阻塞用戶操作始終流暢。具體實(shí)現(xiàn)上我在ModelInferencer類內(nèi)部維護(hù)一個(gè)QThreadPool用QtConcurrent::run啟動(dòng)異步任務(wù)void ModelInferencer::infer(const QImage image) { if (!m_session) { emit inferenceFailed(QStringLiteral(模型尚未加載)); return; } // 深拷貝圖像避免在后臺(tái)線程里訪問(wèn)可能被修改的QImage QImage copy image.copy(); QtConcurrent::run([this, copy]() { try { QVariantMap result doInference(copy); // 真正耗時(shí)的工作 emit inferenceFinished(result); } catch (const std::exception e) { emit inferenceFailed(QString::fromUtf8(e.what())); } }); }這里有個(gè)細(xì)節(jié)值得注意image.copy()不是可選操作。如果直接把外界的QImage引用傳進(jìn)后臺(tái)線程萬(wàn)一用戶在這個(gè)圖像被讀的過(guò)程中做了二次修改比如在界面上裁剪、繪制標(biāo)注后臺(tái)線程讀到的像素?cái)?shù)據(jù)就可能不一致甚至崩潰。深拷貝一張圖像的成本通常不高幾百KB到幾MB的像素拷貝換來(lái)的是確定性的線程安全?；卣{(diào)結(jié)果走信號(hào)槽跨線程傳遞時(shí)Qt會(huì)自動(dòng)使用隊(duì)列連接信號(hào)發(fā)出去后在接收方的線程里執(zhí)行槽函數(shù)天然避開(kāi)了數(shù)據(jù)競(jìng)爭(zhēng)。那Ort::Session線程安全嗎ONNX Runtime的C接口是允許同一個(gè)Session被多個(gè)線程并發(fā)調(diào)用的官方文檔也說(shuō)session線程安全。但實(shí)踐中我更傾向于每個(gè)推理線程共享一個(gè)Session因?yàn)椴l(fā)調(diào)用時(shí)會(huì)內(nèi)部加鎖性能不會(huì)因?yàn)槎嗑€程調(diào)用而惡化太多如果對(duì)性能要求極端苛刻可以每個(gè)工作線程單獨(dú)創(chuàng)建Session代價(jià)是內(nèi)存占用翻倍。我一般用共享Session配合SetIntraOpNumThreads控制單次推理的線程數(shù)。5.3 批量推理與請(qǐng)求排隊(duì)如果你的場(chǎng)景是一次性提交一堆圖片做批處理單張單張地按異步信號(hào)發(fā)散效率太低。我后來(lái)加了一個(gè)隊(duì)列機(jī)制界面層分別調(diào)用infer每次調(diào)用把圖片放進(jìn)QQueueQImage后臺(tái)線程依次取出處理。這樣既保持了UI的響應(yīng)性又能保證多張圖片的推理有序執(zhí)行不會(huì)出現(xiàn)并發(fā)請(qǐng)求導(dǎo)致輸出順序錯(cuò)亂的情況。隊(duì)列實(shí)現(xiàn)起來(lái)不復(fù)雜核心是給QQueue加上QMutex保護(hù)再配合QWaitCondition喚醒工作線程。如果你不想手寫隊(duì)列也可以用QThreadPool加QRunnable的方式接受任務(wù)亂序完成再在界面上按圖片ID對(duì)應(yīng)結(jié)果?？茨愕臉I(yè)務(wù)是否關(guān)心順序。6. 實(shí)測(cè)數(shù)據(jù)、性能瓶頸與部署中的幾個(gè)大坑6.1 端到端延遲與資源占用我拿一個(gè)通用分類模型輸入224x224在普通辦公機(jī)上做了個(gè)粗略測(cè)試配置大致是i5處理器、16GB內(nèi)存、無(wú)獨(dú)立顯卡。單張圖片的端到端耗時(shí)拆解如下階段耗時(shí)毫秒占比QImage讀取與格式轉(zhuǎn)換3-68%縮放 通道轉(zhuǎn)換 歸一化8-1525%ONNX Runtime推理10-2033%后處理與結(jié)果組裝2-46%其他任務(wù)調(diào)度、內(nèi)存拷貝5-1018%總耗電通常在30到55毫秒之間對(duì)交互工具類應(yīng)用來(lái)說(shuō)是完全可接受的。如果你想要更快的速度我實(shí)驗(yàn)過(guò)的有效手段有三個(gè)把圖像縮放到模型輸入尺寸這一步放在推理線程里做避免UI線程做多余工作。用cv::resize替代QImage::scaled。說(shuō)實(shí)話QImage::scaled在縮放效率上一般OpenCV的插值優(yōu)化好得多只是要把數(shù)據(jù)從QImage轉(zhuǎn)到cv::Mat多一道拷貝但整體收益通常是正的。模型量化。將ONNX模型轉(zhuǎn)成INT8量化版本CPU推理速度能提升1.5到2倍代價(jià)是精度損失在分類這種容錯(cuò)度高的場(chǎng)景基本無(wú)感。6.2 踩坑記錄DLL加載失敗與程序直接閃退這是我集成過(guò)程中遇到的第一個(gè)大坑。程序編譯通過(guò)一運(yùn)行直接報(bào)0xc000007b或者提示找不到onnxruntime.dll。排查鏈路是這樣的先確認(rèn)DLL是否放在了可執(zhí)行文件同目錄。放錯(cuò)位置是最常見(jiàn)的原因。再確認(rèn)DLL的架構(gòu)。有個(gè)同事把x86的DLL當(dāng)成x64用了一運(yùn)行就報(bào)錯(cuò)。然后用Dependency Walker或者Visual Studio的調(diào)試輸出看Loader實(shí)際加載了哪個(gè)路徑的DLL。有時(shí)候系統(tǒng)PATH里有舊版本的DLL程序優(yōu)先加載了那個(gè)版本不對(duì)就崩了。最后檢查Qt工具鏈?zhǔn)荕SVC還是MinGW。如果你用MinGW去鏈接MSVC編譯的庫(kù)鏈接階段可能過(guò)但運(yùn)行時(shí)就崩。那次最后定位到的原因是我開(kāi)發(fā)機(jī)器上裝過(guò)另一個(gè)軟件往PATH里塞了一個(gè)舊版DLLQt運(yùn)行時(shí)先找到了這個(gè)舊版直接崩掉。解決辦法是把onnxruntime.dll直接放到可執(zhí)行文件旁邊并保證它和程序在同一個(gè)目錄而不是依賴PATH搜索順序。6.3 踩坑記錄輸入數(shù)據(jù)錯(cuò)位推理結(jié)果完全不對(duì)環(huán)境跑通之后我激動(dòng)地把第一張貓的圖片塞進(jìn)去結(jié)果模型判定為廁所。檢查了半天最后發(fā)現(xiàn)是在預(yù)處理環(huán)節(jié)出了問(wèn)題。第一個(gè)問(wèn)題是通道順序。我一開(kāi)始直接用QImage::Format_RGB32拿到的數(shù)據(jù)它是一個(gè)像素一個(gè)像素排列的ARGB格式并不是連續(xù)的三通道RGB。我把它當(dāng)RGB888直接填進(jìn)張量等于R、G、B三個(gè)通道的順序全亂了模型看到的完全是噪音。改成先convertToFormat(QImage::Format_RGB888)之后問(wèn)題立刻消失。第二個(gè)問(wèn)題是我把圖像的寬高搞反了。模型輸入是(1, 3, 224, 224)也就是高224、寬224但我在縮放圖像時(shí)用了scaled(224, 224)這個(gè)沒(méi)錯(cuò)但在填充inputTensor時(shí)循環(huán)里寫的索引是h * width w其中width用了224而實(shí)際掃描行的長(zhǎng)度是width * 3字節(jié)如果混淆了像素索引和字節(jié)索引就會(huì)出現(xiàn)奇怪的條紋狀污染推理結(jié)果自然全錯(cuò)。這個(gè)坑給的經(jīng)驗(yàn)是寫圖像預(yù)處理時(shí)先打印一小塊數(shù)據(jù)人工核對(duì)一下像素值是否符合預(yù)期再跑完整推理。不要等到模型輸出離譜了才回頭查。6.4 踩坑記錄歸一化被做了兩次另一個(gè)特別隱蔽的問(wèn)題訓(xùn)練代碼里用了transforms.Normalize導(dǎo)出ONNX的時(shí)候把歸一化也導(dǎo)進(jìn)去了或者說(shuō)模型本身就包含前處理層我在C這邊又做了一遍均值方差歸一化。結(jié)果就是模型輸入范圍被打亂分類置信度全部變得很低模型幾乎對(duì)任何輸入都給出均勻概率。這種問(wèn)題怎么排查我建議在集成階段準(zhǔn)備一張標(biāo)準(zhǔn)輸入的調(diào)試圖先用Python加載模型推理一遍記錄下輸出再用C加載同一個(gè)模型輸入同一個(gè)預(yù)處理后的張量對(duì)比輸出。如果兩邊差異超過(guò)1e-4就說(shuō)明前處理邏輯不一致。這個(gè)對(duì)比其實(shí)很值得做成自動(dòng)化把Python端預(yù)處理后的.npy文件保存下來(lái)C端讀取二進(jìn)制數(shù)據(jù)填充張量然后比對(duì)輸出。這一步能消滅大量隱蔽的前后處理不一致問(wèn)題。6.5 踩坑記錄SessionOptions配置不當(dāng)導(dǎo)致的性能劣化還有一個(gè)性能層面的坑ONNX Runtime默認(rèn)會(huì)開(kāi)啟圖形優(yōu)化ORT_ENABLE_ALL這是好事。但SetIntraOpNumThreads如果設(shè)置得過(guò)小比如1單張圖的推理速度就會(huì)明顯變慢設(shè)置得過(guò)大比如32線程切換的開(kāi)銷又會(huì)抵消并行收益。我實(shí)測(cè)下來(lái)在8核處理器上SetIntraOpNumThreads(4)對(duì)224x224輸入的分類模型收益最大。對(duì)于更小的輸入圖比如128x128線程數(shù)太多反而更慢因?yàn)閱未斡?jì)算量太小線程啟動(dòng)和同步的代價(jià)蓋過(guò)了并行收益。這個(gè)參數(shù)最好根據(jù)你的模型大小和用戶機(jī)器情況做基準(zhǔn)測(cè)試不要默認(rèn)不設(shè)置。最后再說(shuō)一個(gè)體積優(yōu)化的小技巧。ONNX Runtime本身只有一份DLL但如果你不需要GPU推理又不需要它自帶的所有優(yōu)化器可以看看官方提供的精簡(jiǎn)版或自定義構(gòu)建選項(xiàng)。我這邊場(chǎng)景只需要CPU就用官方CPU版安裝包里的DLL從二十幾MB壓到了十幾MB對(duì)分發(fā)體驗(yàn)還是有一點(diǎn)幫助的。整個(gè)Qt ONNX Runtime的推理鏈路跑通之后我最深的一個(gè)體會(huì)是神經(jīng)網(wǎng)絡(luò)部署這件事難點(diǎn)從來(lái)不在模型本身而在數(shù)據(jù)格式、線程調(diào)度和運(yùn)行環(huán)境的細(xì)節(jié)。你把訓(xùn)練代碼搬到C、搬到Windows每一步都要重新審視一次數(shù)據(jù)到底走的是什么形狀、什么順序、什么范圍。只要這個(gè)思路清晰剩下的就只是照著接口敲代碼的事了。