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