1. 為什么繞不開VS2026和LibTorchCPU版的這個(gè)組合先說(shuō)一個(gè)我實(shí)際遇到的場(chǎng)景。有個(gè)客戶要做一個(gè)離線運(yùn)行的文檔解析工具輸入是一批PDF和掃描圖片輸出是結(jié)構(gòu)化文本。模型我們用PyTorch訓(xùn)練的效果沒(méi)問(wèn)題但到了交付環(huán)節(jié)就卡住了客戶的辦公電腦不允許安裝Python解釋器更不可能裝Anaconda。最初方案是用PyInstaller打包了一個(gè)exe結(jié)果打出來(lái)的目錄300多MB啟動(dòng)還要等好幾秒偶爾還會(huì)被殺毒軟件攔截。最后我決定把推理部分整個(gè)換成C實(shí)現(xiàn)直接用LibTorch來(lái)加載PyTorch導(dǎo)出的模型——這就是VS2026 LibTorchCPU版這套環(huán)境的來(lái)歷。先說(shuō)結(jié)論這套組合解決的核心問(wèn)題就是沒(méi)有Python環(huán)境也能跑PyTorch模型。LibTorch是PyTorch的C發(fā)行版張量運(yùn)算、自動(dòng)求導(dǎo)、TorchScript推理這些能力都有但不需要Python解釋器。而CPU版指的是預(yù)編譯庫(kù)不包含CUDA相關(guān)組件對(duì)顯卡沒(méi)要求在任何一臺(tái)x64 Windows電腦上都能跑體積也比GPU版小不少特別適合做客戶端工具、邊緣設(shè)備推理、或者純CPU服務(wù)器的服務(wù)端部署。如果你屬于下面這幾類人這篇環(huán)境搭建記錄應(yīng)該能幫你少走彎路想把PyTorch模型集成到C/C#桌面程序里的Windows開發(fā)者需要給客戶交付免Python環(huán)境推理程序的工程師做深度學(xué)習(xí)推理部署但手頭機(jī)器沒(méi)有NVIDIA顯卡只能依賴CPU想搞懂LibTorch的include、lib、dll到底怎么配置的初學(xué)者。這篇文章不是官方文檔的翻譯而是我從下載包、建工程、配屬性、寫驗(yàn)證代碼到踩了各種鏈接錯(cuò)誤、運(yùn)行時(shí)DLL缺失這些坑之后整理出來(lái)的完整鏈路包括每一步為什么要這么做的原理以及排查思路。2. 版本匹配是第一道門檻VS組件和LibTorch包對(duì)上了才不折騰2.1 VS2026安裝時(shí)真正需要勾選的東西VS2026在安裝的時(shí)候默認(rèn)的Workloads界面有一堆選項(xiàng)如果只是寫純C業(yè)務(wù)代碼理論上勾一個(gè)使用C的桌面開發(fā)就夠了。但LibTorch這件事上有幾個(gè)點(diǎn)特別容易被忽略。第一C工具集要選最新版MSVC。LibTorch官方預(yù)編譯包是基于MSVC編譯的如果你用較舊的工具鏈版本可能遇到std庫(kù)頭文件不兼容這類問(wèn)題。VS2026安裝器里有一個(gè)單個(gè)組件選項(xiàng)卡建議確認(rèn)一下MSVC v143_x64或更新的和Windows 11 SDK這兩個(gè)組件被勾選上。第二建議把C CMake tools for Windows也勾上雖然我們用VS的新建項(xiàng)目向?qū)б材苁止づ銵ibTorch但后面如果你打算用CMake管理項(xiàng)目這個(gè)組件省去很多麻煩。安裝完VS2026后還有一個(gè)很多人會(huì)忽略的步驟確認(rèn)編譯器是x64版本。LibTorch官方只提供64位預(yù)編譯包沒(méi)有32位版。在VS菜單欄工具→命令行→開發(fā)者命令提示符里輸入cl能看到編譯器版本如果是x86版后續(xù)鏈接階段會(huì)冒出一堆無(wú)法解析的外部符號(hào)錯(cuò)誤原因就在這里。2.2 LibTorch包到底應(yīng)該下載哪個(gè)下載入口是pytorch.org首頁(yè)的Get Started。進(jìn)去之后有幾個(gè)下拉選項(xiàng)PyTorch Build選Stable穩(wěn)定版Package選LibTorchLanguage選C/JavaCompute Platform選CPU。這里注意官方下載頁(yè)上的是libtorch-win-shared-with-deps-版本號(hào)cpu.zip這樣一個(gè)包。shared表示動(dòng)態(tài)鏈接版本里面的torch、torch_cpu這些功能以dll存在后面運(yùn)行程序時(shí)需要這些dll在場(chǎng)with-deps表示把依賴的三方庫(kù)比如protobuf、asmjit、dnnl一起打包了不用額外再找依賴。文件名里帶有cpu的才是CPU版不帶cpu的通常默認(rèn)包含CUDA組件體積大一倍不止而且對(duì)沒(méi)有N卡的環(huán)境并沒(méi)有收益。還有Release和Debug兩個(gè)選擇。官方推薦生產(chǎn)環(huán)境用Release包。我在實(shí)際搭建過(guò)程中發(fā)現(xiàn)Debug包很少被用到因?yàn)槿绻鸙S工程是Debug模式而鏈接的是Release版LibTorch庫(kù)會(huì)報(bào)LNK2038運(yùn)行庫(kù)不匹配反過(guò)來(lái)也一樣。為了避免折騰最省心的策略是VS工程統(tǒng)一用Release模式LibTorch也統(tǒng)一用Release包。這點(diǎn)后面踩坑部分再細(xì)說(shuō)。2.3 解壓之后目錄結(jié)構(gòu)里藏著關(guān)鍵信息下載下來(lái)的是一個(gè)zip包解壓后目錄結(jié)構(gòu)大致是這樣D:\libtorch\ ├── bin\ # 運(yùn)行所需的dll ├── include\ # 頭文件 ├── lib\ # 導(dǎo)入庫(kù) .lib 和 CMake 配置 └── share\ # CMake 查找包所需文件include目錄里藏著一個(gè)容易被忽略的二級(jí)路徑include\torch\csrc\api\include。剛接觸LibTorch的人在VS里配置附加包含目錄時(shí)只填了D:\libtorch\include結(jié)果#include torch/torch.h依然報(bào)找不到文件。原因就是torch/torch.h這個(gè)頭文件實(shí)際放在include\torch\csrc\api\include\torch\torch.h那里需要把D:\libtorch\include\torch\csrc\api\include也加進(jìn)包含路徑編譯器才能逐層找到它。lib目錄下的所有.lib文件都對(duì)應(yīng)了一個(gè)動(dòng)態(tài)庫(kù)。官方推薦的做法是把整個(gè)lib目錄加入鏈接器路徑然后在附加依賴項(xiàng)里把所有.lib寫進(jìn)去。我一開始圖省事只寫了torch.lib和torch_cpu.lib編譯鏈接時(shí)直接報(bào)了一大堆LNK2019 無(wú)法解析的外部符號(hào)最后乖乖把目錄下所有l(wèi)ib全部加進(jìn)去了。這不是玄學(xué)是LibTorch內(nèi)部模塊化之后彼此之間有大量符號(hào)引用缺一個(gè)都不行。3. 項(xiàng)目工程配置的完整鏈路從包含目錄到dll路徑3.1 新建項(xiàng)目時(shí)先把平臺(tái)切到x64打開VS2026新建C控制臺(tái)應(yīng)用項(xiàng)目。項(xiàng)目創(chuàng)建完之后第一件事就是把解決方案平臺(tái)從默認(rèn)的x86改成x64。這一步漏掉后面所有配置都白搭——LibTorch的.lib是x64的你用x86平臺(tái)去鏈接一分鐘內(nèi)會(huì)看到幾百行無(wú)法解析的外部符號(hào)相關(guān)錯(cuò)誤非常勸退。切換位置在VS工具欄的解決方案平臺(tái)下拉框如果沒(méi)看到x64選項(xiàng)通過(guò)配置管理器→活動(dòng)解決方案平臺(tái)→新建→x64添加。這一步建議在配置LibTorch之前就做掉否則后面改了項(xiàng)目屬性一切換平臺(tái)可能又需要重新設(shè)置。3.2 附加包含目錄填兩個(gè)路徑少一個(gè)都不行項(xiàng)目右鍵→屬性→C/C→常規(guī)→附加包含目錄添加D:\libtorch\include D:\libtorch\include\torch\csrc\api\include為什么需要第一個(gè)路徑因?yàn)長(zhǎng)ibTorch內(nèi)部很多頭文件之間是相對(duì)引用的比如ATen/ATen.h、c10/util/ArrayRef.h這些它們都以include作為根目錄來(lái)組織。為什么不只填第二個(gè)路徑因?yàn)榈诙€(gè)路徑是torch C前端API所在的位置torch/torch.h在這里沒(méi)錯(cuò)但它內(nèi)部還會(huì)includeATen、c10、torch/csrc等路徑下的頭文件那些頭文件在第一個(gè)路徑下才能被找到。為了驗(yàn)證配置是否生效可以臨時(shí)在main函數(shù)里寫一行#include torch/torch.h #include iostream如果C項(xiàng)目屬性里這兩個(gè)路徑都填了編譯時(shí)這段代碼能通過(guò)至少說(shuō)明頭文件搜索鏈路是通的。3.3 附加庫(kù)目錄、附加依賴項(xiàng)以及一個(gè)偷懶但安全的方法繼續(xù)在項(xiàng)目屬性里配置鏈接器→常規(guī)→附加庫(kù)目錄D:\libtorch\lib鏈接器→輸入→附加依賴項(xiàng)把D:\libtorch\lib目錄下所有.lib文件名都寫進(jìn)去用分號(hào)隔開。如果不想一個(gè)個(gè)敲可以在lib目錄下按住Shift右鍵打開PowerShell執(zhí)行Get-ChildItem -Name *.lib | ForEach-Object { $_ -join ; }把輸出復(fù)制到附加依賴項(xiàng)里即可。這個(gè)操作看起來(lái)很笨但實(shí)測(cè)是最穩(wěn)的。LibTorch的lib目錄下三四十個(gè).lib文件不是擺設(shè)它們之間互相依賴手寫精簡(jiǎn)列表很容易漏掉某些間接依賴。還有一個(gè)細(xì)節(jié)在鏈接器→命令行里其實(shí)可以通過(guò)-LIBPATH加上通配符實(shí)現(xiàn)類似效果但VS的圖形界面不支持.lib通配符所以老老實(shí)實(shí)全量粘貼是最不容易出錯(cuò)的。3.4 運(yùn)行時(shí)dll問(wèn)題為什么項(xiàng)目編譯通過(guò)卻一運(yùn)行就報(bào)錯(cuò)項(xiàng)目編譯通過(guò)只是第一步。運(yùn)行的時(shí)候如果VS提示由于找不到 torch.dll無(wú)法繼續(xù)執(zhí)行代碼。這說(shuō)明程序運(yùn)行時(shí)找不到LibTorch的動(dòng)態(tài)庫(kù)。解決方案有兩種。第一種把D:\libtorch\bin目錄加入系統(tǒng)環(huán)境變量PATH然后重啟VS2026讓VS進(jìn)程能拿到新的PATH。注意是重啟VS不是重啟電腦VS的進(jìn)程環(huán)境變量在啟動(dòng)時(shí)讀取不重啟它拿不到最新的值。第二種把bin目錄下的所有dll文件復(fù)制到exe輸出目錄也就是與生成的.exe同一個(gè)文件夾。這種方法最適合后面分發(fā)程序因?yàn)椴渴饡r(shí)根本不可能每臺(tái)機(jī)器都配一次PATH。我的建議是開發(fā)階段用第一種方便調(diào)試準(zhǔn)備交付時(shí)用第二種把dll和exe放一起。LibTorch運(yùn)行需要的dll包括torch.dll、torch_cpu.dll、c10.dll、asmjit.dll、fbgemm.dll、dnnl.dll等直接復(fù)制整個(gè)bin目錄下所有dll即可不用刻意挑。3.5 C語(yǔ)言標(biāo)準(zhǔn)和字符集也順手確認(rèn)一下LibTorch 2.x系列需要C17標(biāo)準(zhǔn)支持。在項(xiàng)目屬性→C/C→語(yǔ)言→C語(yǔ)言標(biāo)準(zhǔn)里選擇ISO C17 標(biāo)準(zhǔn) (/std:c17)或更高版本。如果默認(rèn)是C14編譯torch頭文件時(shí)會(huì)出現(xiàn)各種奇怪的模板報(bào)錯(cuò)場(chǎng)面很混亂。字符集建議使用Unicode字符集LibTorch內(nèi)部路徑處理對(duì)寬字符更友好這個(gè)不是必須但能減少一些文件路徑相關(guān)的潛在問(wèn)題。4. 第一個(gè)驗(yàn)證示例讓LibTorch真正跑起來(lái)才算搭完4.1 一段能驗(yàn)證環(huán)境完整性的最小代碼環(huán)境配置完總得寫點(diǎn)代碼驗(yàn)證一下。下面是最小但覆蓋面足夠的驗(yàn)證程序能確認(rèn)頭文件、鏈接庫(kù)、運(yùn)行時(shí)dll三條鏈路全部暢通#include torch/torch.h #include torch/script.h #include iostream int main() { // 1. 基礎(chǔ)張量運(yùn)算 torch::Tensor a torch::tensor({1.0, 2.0, 3.0}); torch::Tensor b torch::tensor({4.0, 5.0, 6.0}); torch::Tensor c a b; std::cout Sum: c std::endl; // 2. 隨機(jī)張量和維度信息 torch::Tensor random_tensor torch::rand({2, 3}); std::cout Random tensor: random_tensor std::endl; std::cout Size: random_tensor.sizes() std::endl; // 3. 輸出LibTorch版本號(hào) std::cout LibTorch version: TORCH_VERSION std::endl; // 4. 確認(rèn)是CPU版CUDA不可用 std::cout CUDA available: torch::cuda::is_available() std::endl; std::cout CPU threads: torch::get_num_threads() std::endl; return 0; }這段代碼里torch/torch.h提供張量和自動(dòng)求導(dǎo)能力torch/script.h提供JIT推理接口雖然驗(yàn)證環(huán)境用不到script.h但為了后面加載模型方便現(xiàn)在就把這兩個(gè)頭文件的編譯路徑驗(yàn)證到位。TORCH_VERSION是一個(gè)宏定義在頭文件里能輸出編譯LibTorch時(shí)對(duì)應(yīng)的PyTorch版本號(hào)。4.2 運(yùn)行之后的預(yù)期輸出編譯運(yùn)行正確輸出大致是Sum: 5 7 9 [ CPUFloatType{3} ] Random tensor: 0.3176 0.2544 0.1354 0.4092 0.7102 0.1017 [ CPUFloatType{2,3} ] Size: [2, 3] LibTorch version: 2.6.0 CUDA available: 0 CPU threads: 8這里注意CUDA available: 0這個(gè)0正是CPU版的正解。如果你下載的是GPU版在沒(méi)有N卡的環(huán)境下打印的也是0但包里帶了一堆用不到的CUDA組件體積大、啟動(dòng)慢所以純CPU場(chǎng)景務(wù)必選CPU版包。如果程序能完整跑出這段結(jié)果說(shuō)明環(huán)境搭建已經(jīng)成功。我自己的習(xí)慣是再把三件事做一遍作為最終確認(rèn)第一把torch/torch.h單獨(dú)放一個(gè)新建空項(xiàng)目里編譯一次確保不是舊項(xiàng)目緩存的假象第二在命令行直接運(yùn)行編譯出的exe而不是在VS里按F5避免VS代理進(jìn)程干擾第三把exe復(fù)制到另一個(gè)目錄確認(rèn)dll是否已經(jīng)放在exe旁如果報(bào)錯(cuò)驗(yàn)證PATH方案或dll復(fù)制方案是否生效。4.3 編譯失敗還是運(yùn)行失敗的排查順序環(huán)境出問(wèn)題時(shí)先別急著重裝LibTorch按這個(gè)順序排查如果編譯階段就報(bào)錯(cuò)100%是包含目錄有問(wèn)題檢查是否兩個(gè)路徑都加了如果編譯通過(guò)、鏈接階段報(bào)錯(cuò)100%是x64平臺(tái)問(wèn)題或者附加依賴項(xiàng)沒(méi)寫全如果鏈接通過(guò)、運(yùn)行時(shí)報(bào)找不到dll100%是PATH沒(méi)生效或dll沒(méi)復(fù)制到exe旁如果運(yùn)行時(shí)報(bào)其他奇怪的崩潰、內(nèi)存訪問(wèn)沖突大概率是Debug/Release混用或者是機(jī)器缺少VC運(yùn)行庫(kù)安裝一下VS2026自帶的對(duì)應(yīng)運(yùn)行庫(kù)即可。這幾類問(wèn)題占到了LibTorch環(huán)境搭建失敗的90%以上。5. 高頻踩坑點(diǎn)鏈接錯(cuò)誤、DLL缺失與頭文件路徑的完整排查5.1 LNK2038運(yùn)行庫(kù)不匹配Debug和Release水火不容我在一個(gè)新的同事們的工作站上復(fù)現(xiàn)過(guò)這個(gè)問(wèn)題。VS工程默認(rèn)是Debug模式LibTorch官方包默認(rèn)選擇Release版然后在鏈接階段報(bào)LNK2038: mismatch detected for RuntimeLibrary: value MD_DynamicRelease doesnt match value MT_StaticRelease這個(gè)錯(cuò)誤的意思是LibTorch的lib文件是用多線程DLL動(dòng)態(tài)鏈接模式編譯的而你的工程配置成了多線程靜態(tài)鏈接模式。MSVC的C運(yùn)行時(shí)庫(kù)有/MD、/MT兩種模式Debug和Release下又有不同名字選錯(cuò)就鏈接不上。解決辦法有兩個(gè)推薦第一個(gè)項(xiàng)目屬性→C/C→代碼生成→運(yùn)行庫(kù)→選擇多線程 DLL (/MD)。如果工程是Debug模式就把LibTorch官方包換成Debug版。但LibTorch Debug包在Windows下用的人少網(wǎng)上資料也少體驗(yàn)不如Release包穩(wěn)定所以最終建議還是項(xiàng)目切Release模式運(yùn)行庫(kù)選/MD。5.2 無(wú)法解析的外部符號(hào)99%是x86/x64不匹配如果報(bào)錯(cuò)信息里有大量LNK2019 無(wú)法解析的外部符號(hào) class c10::TensorTypePtr ...該符號(hào)在函數(shù) ... 中被引用并且你是x64的LibTorch但VS平臺(tái)是x86那這些符號(hào)找不到是必然的。x86的鏈接器只能鏈接x86的libx64的lib對(duì)x86鏈接器來(lái)說(shuō)就是一堆無(wú)法識(shí)別的符號(hào)。這個(gè)坑特別容易在新建項(xiàng)目后忘記切換解決方案平臺(tái)時(shí)出現(xiàn)。尤其是多人協(xié)作倉(cāng)庫(kù)如果項(xiàng)目管理文件里緩存了x86平臺(tái)配置新clone下來(lái)的人一編譯就懵。所以我在配置文檔里會(huì)特意用加粗標(biāo)注先切x64再動(dòng)LibTorch屬性。5.3 運(yùn)行時(shí)報(bào)找不到dllPATH、cwd和UAC的三角關(guān)系鏈接都通過(guò)了運(yùn)行時(shí)報(bào)由于找不到 torch_cpu.dll無(wú)法繼續(xù)執(zhí)行代碼。重新安裝程序可能會(huì)修復(fù)此問(wèn)題。我在幾個(gè)不同環(huán)境里遇到的原因有三種第一種是PATH沒(méi)生效。VS2026是圖形界面程序修改系統(tǒng)環(huán)境變量后VS不會(huì)自動(dòng)刷新必須完全關(guān)閉VS再重新打開。我見(jiàn)過(guò)有人改完P(guān)ATH不重啟VS然后開始懷疑人生。第二種是dll其實(shí)就放在exe旁邊但加載順序問(wèn)題。Windows加載dll的順序是先看exe所在目錄然后看系統(tǒng)目錄再看PATH。理論上exe旁有同名dll時(shí)不會(huì)去PATH找。但如果項(xiàng)目輸出目錄和exe運(yùn)行目錄不是同一個(gè)比如在VS里設(shè)置了自定義輸出路徑就容易出現(xiàn)明明bin里沒(méi)有崩潰換臺(tái)機(jī)器卻崩了的情況。第三種跟用戶賬戶控制UAC有關(guān)。如果程序是以管理員權(quán)限啟動(dòng)的PATH可能會(huì)被系統(tǒng)重置導(dǎo)致原本能搜到的目錄失效。這種情況下更穩(wěn)妥的做法是把dll放到exe同目錄而不是依賴PATH。我自己最終部署時(shí)一律用exe同目錄放全量dll策略沒(méi)有再遇到運(yùn)行時(shí)缺失dll的問(wèn)題。5.4 CPU版LibTorch初始化階段的資源占用問(wèn)題還有一個(gè)不算報(bào)錯(cuò)但很容易讓人誤判的坑LibTorch程序一啟動(dòng)內(nèi)存占用可能直接沖上幾百M(fèi)BCPU占用也會(huì)短暫飆升。第一次跑通驗(yàn)證程序的人看到任務(wù)管理器里這個(gè)現(xiàn)象很容易以為程序卡死了其實(shí)這只是LibTorch在初始化CPU算子庫(kù)包括oneDNN原MKL-DNN的原語(yǔ)緩存、注冊(cè)線程池等資源。如果這個(gè)初始化峰值影響了你的業(yè)務(wù)比如在非常低配的機(jī)器上可以在main函數(shù)最開始設(shè)置#include c10/thread/ThreadPool.h int main() { torch::set_num_threads(4); // 業(yè)務(wù)代碼 }把線程數(shù)限制為業(yè)務(wù)環(huán)境實(shí)際可承受的并發(fā)度。不過(guò)要注意torch::set_num_threads必須在任何張量運(yùn)算之前調(diào)用否則已在運(yùn)行的算子線程池不會(huì)跟著變化。更多細(xì)節(jié)后面會(huì)展開。5.5 不同版本LibTorch的殘留問(wèn)題如果你之前電腦上裝過(guò)舊版LibTorch比如1.13或2.0系列的新項(xiàng)目一定要檢查附加包含目錄和庫(kù)目錄是否指到了舊路徑。VS的屬性是保存在項(xiàng)目文件里的不同機(jī)器上目錄可能不同。我見(jiàn)過(guò)有人新項(xiàng)目配置沒(méi)問(wèn)題但編譯時(shí)頭文件卻被舊版本搶先引用導(dǎo)致模板庫(kù)不兼容的報(bào)錯(cuò)。排查方法很簡(jiǎn)單在源碼里右鍵torch/torch.h→打開文檔看VS實(shí)際打開的是哪個(gè)路徑基本一眼就能定位。6. 環(huán)境搭完后的工程化建議從驗(yàn)證程序走向真實(shí)模型部署6.1 與其在VS屬性面板里折騰不如用CMake手工配置VS屬性面板能跑通環(huán)境但到了真實(shí)項(xiàng)目階段——尤其是多人協(xié)作、跨平臺(tái)、持續(xù)集成——建議盡快切換到CMake。LibTorch官方在share\cmake目錄里提供了完整的CMake配置用起來(lái)非常順滑。一個(gè)最簡(jiǎn)的CMakeLists.txt長(zhǎng)這樣cmake_minimum_required(VERSION 3.18) project(LibTorchDemo) set(CMAKE_CXX_STANDARD 17) # libtorch 根目錄 set(LIBTORCH_DIR D:/libtorch) list(APPEND CMAKE_PREFIX_PATH ${LIBTORCH_DIR}) find_package(Torch REQUIRED) add_executable(demo main.cpp) target_link_libraries(demo ${TORCH_LIBRARIES}) # 確保dll能被復(fù)制到輸出目錄 if(WIN32) add_custom_command(TARGET demo POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different $TARGET_FILE_DIR:${TORCH_LIBRARIES} $TARGET_FILE_DIR:demo) endif()這里find_package(Torch REQUIRED)會(huì)自動(dòng)從share\cmake目錄里找到TorchConfig.cmake設(shè)置好所有頭文件、庫(kù)目錄和宏定義。TORCH_LIBRARIES是CMake提供的變量包含了所有需要鏈接的庫(kù)不用再手動(dòng)枚舉幾十個(gè).lib文件了。對(duì)于團(tuán)隊(duì)里多個(gè)開發(fā)機(jī)環(huán)境不一致的窘?jīng)rCMake版配置直接把LIBTORCH_DIR改成各自機(jī)器上的路徑就行其他邏輯保持一致比手寫VS屬性要可維護(hù)得多。6.2 加載PyTorch模型的正確姿勢(shì)TorchScript環(huán)境搭好之后絕大多數(shù)人的目標(biāo)是加載訓(xùn)練好的PyTorch模型。在Python里用torch.jit.trace或在訓(xùn)練代碼里用torch.jit.script導(dǎo)出TorchScript模型import torch model MyModel() model.load_state_dict(torch.load(model_weights.pth, map_locationcpu)) model.eval() example_input torch.rand(1, 3, 224, 224) traced_model torch.jit.trace(model, example_input) traced_model.save(model_script.pt)然后在C側(cè)加載#include torch/script.h torch::jit::Module module; try { module torch::jit::load(model_script.pt); } catch (const c10::Error e) { std::cerr Failed to load model: e.what() std::endl; return -1; } std::vectortorch::jit::IValue inputs; inputs.push_back(torch::ones({1, 3, 224, 224})); torch::Tensor output module.forward(inputs).toTensor();這里最容易犯的錯(cuò)是在驗(yàn)證代碼里只包含了torch/torch.h沒(méi)包含torch/script.h。雖然torch/torch.h也包含了一些script相關(guān)頭但torch::jit::load的完整聲明在script.h里。環(huán)境驗(yàn)證階段就把script.h包含進(jìn)來(lái)編譯一次后面加載模型時(shí)能省去一輪報(bào)錯(cuò)排查。6.3 CPU版的性能調(diào)優(yōu)方向LibTorch在CPU上跑模型有幾件事值得做第一控制線程數(shù)。默認(rèn)情況下LibTorch會(huì)使用所有物理核心如果程序還開了自己的線程池可能有超額爭(zhēng)搶。前面提到的torch::set_num_threads(N)在初始化時(shí)設(shè)置即可。第二確認(rèn)是否啟用了指令集優(yōu)化。CPU版LibTorch默認(rèn)啟用了AVX/AVX2等指令集運(yùn)行日志里偶爾能看到相關(guān)的初始化信息。如果你的CPU比較老不支持這些指令集程序可能直接崩潰或報(bào)非法指令。這時(shí)候需要換用更早版本的LibTorch或者手動(dòng)編譯一個(gè)沒(méi)有AVX優(yōu)化的版本。這個(gè)情況在嵌入式工控機(jī)上比較常見(jiàn)普通辦公電腦一般不會(huì)遇到。第三對(duì)單次推理耗時(shí)敏感的場(chǎng)景可以用torch::NoGradGuard確保推理時(shí)不創(chuàng)建計(jì)算圖{ torch::NoGradGuard no_grad; auto output module.forward(inputs).toTensor(); }環(huán)境都搭好之后這些優(yōu)化點(diǎn)在真實(shí)部署時(shí)能直觀感受到差別。6.4 交付時(shí)的目錄清單和運(yùn)行庫(kù)注意事項(xiàng)最后說(shuō)一下交付。如果你的程序需要給其他機(jī)器使用最簡(jiǎn)單的目錄組織是C:\MyApp\ ├── MyApp.exe ├── torch.dll ├── torch_cpu.dll ├── c10.dll ├── asmjit.dll ├── fbgemm.dll ├── dnnl.dll └── ... 其他dll如果你的目標(biāo)機(jī)器沒(méi)有安裝較新的Microsoft Visual C Redistributable程序可能啟動(dòng)就報(bào)VCRUNTIME140.dll缺失。解決方法是把VS2026安裝目錄下的VC\Redist\MSVC\...\vc_redist.x64.exe也一起打包進(jìn)安裝程序或者在部署文檔里明確寫上安裝前置運(yùn)行庫(kù)。這一步很多人在開發(fā)機(jī)上意識(shí)不到因?yàn)殚_發(fā)機(jī)裝了VS2026運(yùn)行庫(kù)齊全目標(biāo)機(jī)器上就原形畢露了。我在做交付時(shí)還會(huì)把LibTorch的版本號(hào)、VS編譯的MSVC工具集版本號(hào)寫進(jìn)程序的About窗口或版本信息里方便后續(xù)排查問(wèn)題。別小看這個(gè)半年后你自己回看項(xiàng)目時(shí)省下的時(shí)間不是一點(diǎn)半點(diǎn)。當(dāng)年我第一次把這套環(huán)境跑通前后折騰了大半天大部分時(shí)間花在兩個(gè)地方一是版本選擇沒(méi)弄明白二是被x86/x64平臺(tái)問(wèn)題坑了一遍?，F(xiàn)在回頭看環(huán)境搭建本身并不復(fù)雜核心就三句話選對(duì)CPU版Release包配全頭文件路徑和lib依賴項(xiàng)處理好dll運(yùn)行路徑。把這三件事做對(duì)剩下的就是寫代碼的時(shí)候了。希望這篇記錄能幫你把大半天時(shí)間省成半小時(shí)。