【內(nèi)容安全審查】通過YOLO26 模型導(dǎo)出從訓(xùn)練到部署的最后一公里我踩過的坑和最終方案做計算機視覺的同學(xué)應(yīng)該都有這種經(jīng)歷訓(xùn)練時各種指標(biāo)刷得飛起模型在 Colab 上跑得好好的loss 降得賞心悅目mAP 也說得過去。結(jié)果到了要交付的時候?qū)熁蛘呒追揭痪洹鞍涯Ｐ徒o我我這邊要接進系統(tǒng)”你才發(fā)現(xiàn)手里只有一個.pt文件拿去給對方的 C 工程師人家眉頭一皺這玩意兒我們這邊跑不了。這就是模型導(dǎo)出的意義。YOLO26 作為目前 YOLO 系列里熱度一直居高不下的版本網(wǎng)上關(guān)于它訓(xùn)練、改進、結(jié)構(gòu)圖解析的內(nèi)容已經(jīng)很多了但“訓(xùn)練完之后怎么把模型導(dǎo)出成不同平臺能吃的格式”這塊系統(tǒng)性講清楚的內(nèi)容反而不多。不少做計算機視覺大作業(yè)的同學(xué)、做 YOLO26 人員入侵檢測項目的人甚至很多已經(jīng)在跑 YOLO26 訓(xùn)練自己數(shù)據(jù)集的工程師都卡在了導(dǎo)出這一步。這篇東西我想把它徹底講透。你不需要是部署專家只要手里有一個訓(xùn)練好的 YOLO26 模型能看懂 Python按著下面的思路走一遍基本就能把 ONNX、OpenVINO、TensorRT 這些格式理清楚也知道每一步為什么要那么做。1. 導(dǎo)出不只是“換個后綴”模型的運行世界變了很多人第一次接觸導(dǎo)出覺得就是把.pt轉(zhuǎn)成.onnx本質(zhì)上是文件格式轉(zhuǎn)換。這個理解不算錯但太淺了會導(dǎo)致后面遇到問題完全找不到方向。1.1 訓(xùn)練框架和推理引擎對“模型”的理解完全不同PyTorch 里的模型本質(zhì)是一堆層結(jié)構(gòu)加上一堆權(quán)重然后被 Python 的 runtime 動態(tài)解釋執(zhí)行。它靈活、方便調(diào)試但每跑一次前向都要經(jīng)過 Python 層的調(diào)度圖的優(yōu)化也幾乎為零。這在訓(xùn)練階段完全沒問題因為訓(xùn)練本身就要頻繁改權(quán)重、算梯度本來就需要這種靈活性。但推理不一樣。推理的時候模型結(jié)構(gòu)是固定的權(quán)重也是固定的不存在反向傳播也不存在動態(tài)建圖的需求。推理引擎要的是“把計算圖固化下來針對固定 shape 做極致優(yōu)化”。這就是為什么業(yè)界要把訓(xùn)練好的模型從 PyTorch 里“搬”出來搬到一個中立的、描述計算圖的格式里。ONNXOpen Neural Network Exchange就是這個“中立格式”。PyTorch 訓(xùn)練完的模型導(dǎo)出成 ONNX 后相當(dāng)于把整張計算圖固化成了標(biāo)準(zhǔn)化的描述文件。邏輯上它就是一個“計算圖快照”任何支持 ONNX 的推理引擎ONNX Runtime、TensorRT、OpenVINO、Core ML 等都能讀取并執(zhí)行它。用個生活化的比喻PyTorch 模型像一位會臨場發(fā)揮的廚師你告訴他“做一道魚”他會根據(jù)今天有什么食材、灶臺什么火力、自己當(dāng)時的心情決定具體怎么做。而 ONNX 就像一份精確到克數(shù)的菜譜食材、步驟、火候全部寫死。你把這菜譜給任何一個能看懂菜譜的廚房各種推理引擎都能做出一模一樣的菜。1.2 ONNX、TensorRT、OpenVINO 各管哪一段路這是新手最容易懵的地方格式太多了分不清。我把它們按“離硬件有多近”排個序就清楚了ONNX最中立的計算圖描述格式本身不做太多優(yōu)化像一個通用的中間表示IR不太依賴具體硬件。它能跑的地方最廣但優(yōu)化的空間也最大。ONNX RuntimeORT微軟出品的推理引擎直接吃 ONNX 文件。它在 CPU 和 GPU 上都能跑做了不少圖優(yōu)化和算子融合適合做“通用部署”。OpenVINOIntel 出品的推理工具套件針對 Intel CPU、集成顯卡、Movidius 神經(jīng)計算棒做了深度優(yōu)化。如果你部署的目標(biāo)機器是 Intel CPUOpenVINO 往往是性能最好的選擇之一。它可以把 ONNX 進一步轉(zhuǎn)成它自己的 IR 格式.xml.bin也可以直接讀 ONNX。TensorRTNVIDIA 出品的推理優(yōu)化器只在 NVIDIA GPU 上工作。它會針對你的目標(biāo) GPU 做層融合、精度校準(zhǔn)、kernel 自動調(diào)優(yōu)是“NVIDIA GPU 上推理性能天花板”級別的存在。它吃 ONNX轉(zhuǎn)化后再序列化成 TensorRT engine.engine文件。Core MLApple 生態(tài)的模型格式給 iPhone、Mac 上用的。所以整個導(dǎo)出的鏈路一般是PyTorch (.pt) → ONNX → OpenVINO / TensorRT / Core ML / ONNX Runtime理解了這條鏈路你就明白為什么大家總說“先導(dǎo)出 ONNX”它是一個必經(jīng)的中間站是 PyTorch 和各個硬件推理引擎之間的“通用語言”。不只是 YOLO26YOLOv5、v8、v11 這些全是這個套路。1.3 NMS 在導(dǎo)出流程里的真正地位提到 YOLO 導(dǎo)出有個繞不開的東西叫NMSNon-Maximum Suppression非極大值抑制。YOLO 模型輸出的原始裸結(jié)果是一大堆候選框每張圖可能有上萬甚至幾萬個框其中絕大多數(shù)是重疊的、低置信度的“廢框”。NMS 的作用就是把這些框過濾、合并最后留下每個目標(biāo)位置上最合適的那個框。訓(xùn)練和驗證的時候NMS 是在 PyTorch 代碼里用純 Python 或 C 擴展實現(xiàn)的這部分邏輯根本沒進到模型的計算圖里。而導(dǎo)出成 ONNX 后你拿到的是“模型輸出原始框”這一步NMS 要不要一起導(dǎo)出就成了 YOLO 系列導(dǎo)出時最容易出現(xiàn)分歧的大問題。實際工程里主流做法是模型只導(dǎo)出到“原始輸出”為止NMS 后處理放在推理代碼里用目標(biāo)語言C/C#/Java/Go自己寫。原因后面會詳述但你現(xiàn)在先記住導(dǎo)出 YOLO 系列模型基本默認不導(dǎo)出 NMS除非你的部署場景非常特殊比如目標(biāo)檢測的嵌入式端后處理寫起來極其困難才有動力把 NMS 一起塞進模型里。2. 你的 YOLO26 是“哪一款”不同任務(wù)導(dǎo)出的策略不一樣在具體動手前先別急著敲命令。你要回頭看一下自己訓(xùn)練的 YOLO26 到底是“哪一款”模型。YOLO 系列從 v8 開始就不僅僅是目標(biāo)檢測器了它同時支持分類、分割、姿態(tài)估計這些任務(wù)。YOLO26 在這個基礎(chǔ)上還衍生出了 depth深度估計等變體網(wǎng)上搜“yolo26 depth”“yolo26 姿態(tài)模型版本區(qū)別”就能看到很多人都在這塊有疑問。不同任務(wù)類型模型輸出的頭head完全不同導(dǎo)出的注意事項也各不相同。2.1 常規(guī)目標(biāo)檢測模型的導(dǎo)出重點這是最簡單、最常見的情況。你訓(xùn)練了一個 YOLO26 目標(biāo)檢測模型比如 YOLO26n、yolo26s、yolo26m 這些用來做人員入侵檢測、安全帽檢測、車輛識別等任務(wù)。這種情況導(dǎo)出時核心關(guān)注點有三個輸入尺寸訓(xùn)練時用的 imgsz 是多少導(dǎo)出時就盡量保持一致。雖然 ONNX 支持動態(tài)輸入但對推理性能不友好后面細說。輸出格式Y(jié)OLO 檢測模型的原始輸出一般是[1, 4 num_classes, 8400]這種形狀具體數(shù)字取決于模型輸入尺寸和 stride其中 4 是框坐標(biāo)cx, cy, w, h 或 xyxynum_classes 是類別數(shù)8400 是不同尺度特征圖上的候選框總數(shù)輸入 640 時。導(dǎo)出時你會在輸出節(jié)點上看到類似名字。要不要 NMS默認不要。讓下游代碼自己處理。如果你是用 Ultralytics 框架訓(xùn)練的 YOLO26框架本身已經(jīng)把導(dǎo)出邏輯封裝好了正常情況一句model.export()就能搞定。但如果你跑的是別人魔改的 YOLO26網(wǎng)上“yolo26 改進專欄”里這種特別多比如加了注意力機制、換了檢測頭就不能完全依賴框架自動導(dǎo)出要手動檢查改動過的層能不能被 ONNX 算子集支持。這是最讓人頭疼的場景我后面會用一節(jié)專門講怎么排查這類問題。2.2 depth 版本導(dǎo)出時處理額外輸出頭如果你用的是 YOLO26 depth 版本用于單目深度估計它的網(wǎng)絡(luò)結(jié)構(gòu)在檢測頭之外還掛了一個深度頭輸出的是一個和輸入圖像尺寸成一定比例的深度圖。導(dǎo)出這種模型你要額外確認深度頭的輸出名稱和 shape導(dǎo)出的 ONNX 文件中深度輸出是一個獨立的輸出節(jié)點通常像[1, H, W]或[1, H/scale, W/scale]。深度值范圍你訓(xùn)練時的深度標(biāo)簽是相對深度0~1還是絕對深度米模型輸出的原始值范圍是什么這些信息雖然不影響導(dǎo)出但會影響你部署后怎么處理深度圖最好在導(dǎo)出的同時寫進模型說明文檔。后處理差異檢測分支可能需要 NMS深度分支只需要插值縮放回原圖尺寸并做可視化或后續(xù)計算。這決定了你在推理代碼里要同時處理“框后處理”和“深度圖后處理”兩套邏輯導(dǎo)出本身沒區(qū)別但部署代碼要注意。姿態(tài)模型導(dǎo)出與模型版本差異YOLO26 的姿態(tài)模型pose輸出就更特殊了。Ultralytics 框架里的 pose 模型訓(xùn)練好的.pt導(dǎo)出 ONNX 后輸出通常是兩個頭的拼接或分開一個是檢測框分支一個是關(guān)鍵點分支。以 COCO 姿態(tài)任務(wù)為例關(guān)鍵點通常是 17 個每個點有(x, y, confidence)三個值。所以關(guān)鍵點分支的輸出維度一般是 batch 相關(guān)、通道數(shù) 17 * 3。檢測框分支仍然輸出框和類別置信度。這里必須注意“版本差異”。網(wǎng)上搜“yolo26 姿態(tài)模型版本區(qū)別”能看到很多人在問同一個 YOLO26 名字下有不同權(quán)重版本關(guān)鍵點位順序、坐標(biāo)約定是不是和 COCO 一致是否帶了可見性 flagvisible flag這些細節(jié)不同訓(xùn)練腳本導(dǎo)出的結(jié)果形狀就不一樣。我的建議是導(dǎo)出姿態(tài)模型之前先拿一張測試圖用 PyTorch 原始模型推理一遍打印出每個輸出的 shape并人工檢查關(guān)鍵點的坐標(biāo)值是不是符合預(yù)期。只有確認了“PyTorch 階段輸出是正確的”你導(dǎo)出 ONNX 后去對比才有參照物。如果你連 PyTorch 階段的輸出都沒確認過導(dǎo)出后出了 bug 你根本分不清是導(dǎo)出環(huán)節(jié)的問題還是模型本身的問題。2.4 基于 YOLO26 做人員入侵檢測等項目時的導(dǎo)出選型結(jié)合很多做“YOLO26 人員入侵檢測”這類計算機視覺項目的同學(xué)其實是為了交大作業(yè)或者做畢設(shè)。這種項目通常需要部署在一臺普通的電腦上甚至可能是 CPU only 的機器。這種場景下我最推薦導(dǎo)出OpenVINO格式原因有兩點Intel CPU 是個巨大的存量市場OpenVINO 對此的優(yōu)化是出了名的猛經(jīng)常能在不損失精度的情況下比純 PyTorch CPU 推理快 2 到 4 倍。Ultralytics 框架原生支持導(dǎo)出 OpenVINO一條命令就能完成還會幫你生成配套的部署文件。如果項目方指定要用 NVIDIA GPU 跑推理那就直接上 TensorRT。雖然推理速度最快但因為它和具體顯卡綁定注意是“綁定”不是“兼容”換了一張顯卡型號甚至驅(qū)動版本都可能要重新導(dǎo)出在交付時要多留個心眼千萬別只給客戶一個 .engine 文件一定要把 ONNX 文件一起交付不然客戶換臺機器就跑不了。3. 直接抄作業(yè)我驗證過的導(dǎo)出流程和參數(shù)配置理論鋪墊完了現(xiàn)在進入實操。下面是我在自己的環(huán)境里跑通的完整導(dǎo)出流程包含了環(huán)境準(zhǔn)備和導(dǎo)出命令以及每一步背后的選擇邏輯。3.1 環(huán)境準(zhǔn)備與版本對齊先說一個重要教訓(xùn)導(dǎo)出 YOLO26 前先確認你的 ultralytics 包版本和你下載/訓(xùn)練的模型來源一致。YOLO26 相關(guān)的代碼和權(quán)重在社區(qū)里流傳速度很快往往你今天下載的yolo26n.pt需要用某個特定版本的ultralytics包才能正常加載。如果你是在跑“yolo26 環(huán)境配置”時按網(wǎng)上的博客裝了一個版本的包然后又從另一個來源下載了權(quán)重很可能加載時就報錯或者行為異常。我本地的建議環(huán)境組合Python 3.9~3.11PyTorch 2.1 或以上ultralytics 包版本以你模型來源說明為準(zhǔn)一般 8.2.x 之后的版本對 YOLO26 支持比較完整onnxruntime 1.17 以上用于導(dǎo)出后驗證onnx 1.15 以上openvino 2024.x如果用 CPU 部署建議導(dǎo)出 OpenVINO 格式tensorrt 8.6 或以上如果用 NVIDIA GPU建議導(dǎo)出 TensorRT提示Torch、CUDA、TensorRT 三個版本要互相兼容這是老生常談但永遠有人在這上面翻車。TensorRT 對 CUDA 版本很敏感建議統(tǒng)一用 NVIDIA 官方文檔里列的兼容矩陣來配。你可以在終端里檢查版本python -c import torch, ultralytics, onnx, onnxruntime; print(torch.__version__, ultralytics.__version__, onnx.__version__, onnxruntime.__version__)如果輸出里沒有報錯說明基礎(chǔ)環(huán)境沒問題。3.2 標(biāo)準(zhǔn)導(dǎo)出命令與超參選擇如果是用 Ultralytics 框架訓(xùn)練的 YOLO26最笨但也最靠譜的導(dǎo)出代碼長這樣from ultralytics import YOLO # 加載你自己訓(xùn)練的權(quán)重 model YOLO(runs/detect/train/weights/best.pt) # 導(dǎo)出 ONNX model.export( formatonnx, # 導(dǎo)出格式 imgsz640, # 輸入尺寸和訓(xùn)練時保持一致 opset12, # ONNX 算子集版本 dynamicFalse, # 是否允許動態(tài)輸入尺寸 simplifyTrue, # 是否用 onnxsim 簡化計算圖 nmsFalse, # 是否導(dǎo)出 NMS強烈建議 False )這行代碼執(zhí)行完后會在權(quán)重同目錄下生成一個best.onnx。你可能會問參數(shù)為什么這么設(shè)我逐個解釋imgsz640你訓(xùn)練時如果是 640這里就填 640。如果訓(xùn)練時是 1280這里就得填 1280。模型的 backbone 和 head 對輸入特征圖的尺寸有依賴stride 通常是 8、16、32 的組合。輸入尺寸必須是 32 的倍數(shù)或者至少是 stride 最小公倍數(shù)的倍數(shù)否則特征圖會出問題。你導(dǎo)出時如果填了一個訓(xùn)練時完全沒有用過的尺寸精度可能會莫名掉點因為模型從未在這個分辨率上充分適配過。opset12ONNX 的算子集版本。太低的版本不支持一些較新的算子太高的版本對老版本推理引擎不友好。YOLO 系列在這種 CNN 結(jié)構(gòu)里opset 11~13 之間都夠用。我默認選 12兼容性和功能都比較平衡。如果你后續(xù)要轉(zhuǎn) TensorRTTensorRT 8.6 以上的版本對 ONNX opset 的適配已經(jīng)很好不需要額外操心。dynamicFalse這個我強烈建議。設(shè)成 True 雖然能讓模型接受任意尺寸輸入但代價是推理引擎沒法做輸入 shape 相關(guān)的固定優(yōu)化比如 TensorRT 的某些層會根據(jù)固定尺寸做內(nèi)存布局調(diào)優(yōu)性能會有損。部署階段如果你能保證輸入尺寸固定就固定死不要開動態(tài)。但有個例外如果你的業(yè)務(wù)里輸入圖像尺寸不能預(yù)知且變化幅度極大又不想做 letterbox 填充把圖像縮放并填充成固定尺寸那只能開 dynamic。這種情況你要意識到每換一個尺寸推理引擎可能會重新做 shape 推導(dǎo)延遲會高不少。simplifyTrue導(dǎo)出的 ONNX 會經(jīng)過 onnxsim 工具做一遍常量折疊、冗余節(jié)點刪除之類的優(yōu)化。實測下來YOLO26 的模型開 simplify 后文件體積和推理時間都有改善而且不影響精度。但注意如果你的模型里有自定義算子simplify 可能會報錯那就不用 onnxsim后面手動排查。nmsFalse前面講過原因。官方導(dǎo)出選項里有 nms 這個參數(shù)默認是 False。我建議保持默認除非你非常明確自己的部署鏈路為什么需要模型內(nèi)置 NMS。3.3 導(dǎo)出 ONNX 后我用這三種方式驗證它沒問題導(dǎo)出成功不等于導(dǎo)出正確。我見過太多人 export 時沒有報錯以為萬事大吉結(jié)果接入部署代碼后檢測結(jié)果全亂套。以下三步每步都值得做第一步用 onnx.checker 檢查模型結(jié)構(gòu)合法性import onnx onnx_model onnx.load(best.onnx) onnx.checker.check_model(onnx_model) print(ONNX model check passed.)如果你看懂了 checker 的報錯內(nèi)容大多數(shù)結(jié)構(gòu)性問題比如節(jié)點輸入輸出不匹配、維度信息缺失都能在這一步暴露出來。第二步用 onnxruntime 推理一張測試圖和 PyTorch 輸出對比這是最關(guān)鍵的一步。拿同一張測試圖分別用原始.pt模型和導(dǎo)出的.onnx推理打印輸出矩陣的 shape 和數(shù)值看看是否一致。注意不同框架的預(yù)處理方式可能有細微差別比如像素歸一化方式是 0~1 還是 -1~1通道順序是 RGB 還是 BGR。為了驗證 ONNX 本身沒導(dǎo)錯你應(yīng)該把 ONNX 的輸入喂成 PyTorch 模型輸入張量的完全相同的值。這在部署階段做“預(yù)處理對齊”前的一個獨立驗證。import numpy as np import torch import onnxruntime as ort from ultralytics import YOLO # 用 PyTorch 模型推理得到輸入張量 x 和輸出 model YOLO(best.pt) x torch.randn(1, 3, 640, 640) # 這里可以放一張真實圖片預(yù)處理后的張量 with torch.no_grad(): pt_outputs model.model(x) # 這是 PyTorch 原始輸出不是后處理后的結(jié)果 # 用 ONNX Runtime 跑同一個輸入 session ort.InferenceSession(best.onnx, providers[CPUExecutionProvider]) ort_inputs {session.get_inputs()[0].name: x.numpy()} ort_outputs session.run(None, ort_inputs) # 對比每個輸出的 shape 和數(shù)值 for i, pt_out in enumerate(pt_outputs): ort_out ort_outputs[i] print(fPyTorch output {i}: shape{pt_out.shape}) print(fONNX output {i}: shape{ort_out.shape}) print(fMax absolute diff: {np.abs(pt_out.numpy() - ort_out).max():.6f})如果 max diff 在 1e-4 這個量級甚至更小說明導(dǎo)出基本無損。如果 diff 很大比如超過 1e-2那說明計算圖里有算子被錯誤替換了或權(quán)重對齊出了問題要回頭查簡化過程或者逐層對比。第三步可視化模型結(jié)構(gòu)把導(dǎo)出的 ONNX 文件拖進 Netron 網(wǎng)頁端https://netron.app認一遍從輸入到到各分支輸出的形狀變化。這一步特別適合檢查你用的是不是接了正確 head也適合給做 YOLO26 結(jié)構(gòu)圖展示的人用。這個習(xí)慣很值得養(yǎng)成導(dǎo)出不是驗證的終點“導(dǎo)出完更要對齊再收工”省下的全是后面排查自己的時間。我在自己帶團隊做項目時甚至立過規(guī)矩沒做輸出對齊驗證的模型不允許發(fā)給下游。3.4 繼續(xù)導(dǎo)出 OpenVINO 和 TensorRTYOLO26 用 Ultralytics 導(dǎo)出 OpenVINO 很簡單model.export(formatopenvino, imgsz640, halfFalse) # halfFalse 保持 FP32如果推理機器支持且對精度損失做了評估你可以設(shè)置halfTrue轉(zhuǎn)成 FP16。很多 Intel CPU 的核顯對 FP16 也算友好但如果你在普通 CPU 上做純 CPU 推理FP32 其實更穩(wěn)妥。導(dǎo)出 TensorRT 則這樣model.export(formatengine, imgsz640, halfTrue, device0) # device 指定 GPUTensorRT 導(dǎo)出時務(wù)必指定在 NVIDIA GPU 上。halfTrue是 FP16 精度在主流 Ampere 及之后架構(gòu)的卡上YOLO26 用 FP16 推理精度損失通常很小速度提升明顯。如果你的模型是用 FP32 訓(xùn)練的在 NVIDIA 顯卡上直接用 FP16 推理絕大多數(shù)情況下沒有問題但你仍然要在導(dǎo)出完成后對同一批驗證集圖跑一遍 mAP確認精度下降不超過 1 個百分點才比較穩(wěn)。目標(biāo)平臺推薦格式關(guān)鍵特征通用 CPUONNX ONNX Runtime跨平臺安裝簡單Intel CPUOpenVINOCPU 推理優(yōu)化充分易部署NVIDIA GPUTensorRT推理性能天花板綁定顯卡Apple 設(shè)備Core ML生態(tài)私有格式跨平臺原型驗證ONNX先落地再決定正式優(yōu)化4. 導(dǎo)出時最容易翻車的隱蔽環(huán)節(jié)與完整排查鏈路這一節(jié)我想專門講“導(dǎo)出過程中報錯”的處理思路。因為 YOLO26 的源碼和公開資源太多太雜你下載的“YOLO26 源碼下載”很可能是某個博主二次開發(fā)的版本結(jié)構(gòu)圖和官方不完全一樣甚至已經(jīng)加了各種改進模塊。這種模型導(dǎo)出最容易在“自定義算子轉(zhuǎn) ONNX”這一步掛掉。4.1 先復(fù)現(xiàn)再排查處理導(dǎo)出報錯的通用鏈路假設(shè)你在跑 export 時遇到了一個問題比如報錯說某個算子不支持。不要急著搜“YOLO26 導(dǎo)出報錯”這種寬泛的關(guān)鍵詞按照下面的鏈路一步步縮小范圍第一步精確定位到具體的層名和算子Ultralytics 的 export 日志通常會打印到哪個模塊、哪個節(jié)點失敗。如果日志里只給了統(tǒng)一錯誤用 traceback 定位到模型結(jié)構(gòu)定義文件里的具體調(diào)用棧找到出錯的模塊名。第二步檢查這個模塊是不是新加的“改進模塊”如果它來自你下載的“YOLO26 改進專欄”代碼那么它大概率是社區(qū)里有人寫的自定義模塊內(nèi)部可能用了不常規(guī)的 PyTorch 操作比如torch.cumsumscatter的組合有些注意力機制會這么寫、用了可變循環(huán)長度等。這些操作要么 ONNX 算子集里沒有直接對應(yīng)要么對動態(tài) shape 支持不好。第三步把該模塊單獨摳出來構(gòu)造假數(shù)據(jù)導(dǎo)出單測這是非常高效的排查手段。你在一個新文件里單獨定義一個只包含那個模塊的小模型隨機生成相同 shape 的輸入對它單獨做 torch.onnx.export看能不能成功。如果單獨導(dǎo)出成功說明該模塊本身沒有算子問題問題出在和模型中其他模塊的配合上如果單獨導(dǎo)出失敗那問題就鎖定在這個模塊內(nèi)部。然后嘗試把模塊內(nèi)疑似有問題的操作逐個替換成更基礎(chǔ)的算子比如把某些變形操作用 reshape transpose 拆開再重新導(dǎo)出驗證。第四步考慮將“改進模塊”留在 PyTorch 中用前后處理承接如果自定義模塊實在無法轉(zhuǎn) ONNX某些復(fù)雜的注意力機制和檢測頭結(jié)構(gòu)確實會有問題可以考慮導(dǎo)出時屏蔽掉該模塊把它放到部署代碼前后處理階段用別的方式補償。比如注意力模塊輸出可以在 PyTorch 階段預(yù)先計算好部署時把它的結(jié)果作為預(yù)處理的一部分。這聽起來繞但在工程上是常見的妥協(xié)方案。第五步計算圖分段導(dǎo)出再拼接如果模型主體是標(biāo)準(zhǔn)結(jié)構(gòu)、只有個別模塊導(dǎo)不出可以把這個模塊從全圖中拆出來單獨導(dǎo)出成一個小 ONNX然后用 ONNX GraphSurgeon、onnx_graphsurgeon 或者 ONNX 官方工具庫進行圖拼接。這樣做非常接近“模型主體 一系列子圖”的部署方式比較考驗對計算圖結(jié)構(gòu)的理解。一般不建議新手輕易嘗試但它確實是高階方案里最有效的。4.2 圖像縮放方式造成的“精度翻車”是部署階段最常見的坑導(dǎo)出時模型內(nèi)部計算沒問題但推理結(jié)果不對最常見的原因之一是圖像預(yù)處理沒有對齊訓(xùn)練時的邏輯。YOLO 系列訓(xùn)練和驗證時有一套默認的預(yù)處理流程等比縮放 letterbox向邊緣填充灰邊 歸一化 BGR/RGB 通道順序約定。這套邏輯在 PyTorch 階段是框架內(nèi)部自動幫你做掉的但導(dǎo)出到 ONNX 后模型本身只負責(zé)“吃一個張量吐一個張量”預(yù)處理你必須自己在推理代碼里實現(xiàn)。我見過無數(shù)人栽在這件事上直接用了 OpenCV 的cv2.resize(image, (640, 640))把原圖拉變形了喂進模型導(dǎo)致小目標(biāo)檢測效果極差或者圖像尺寸沒做 letterbox 填充直接把非正方形圖塞進去模型輸出的候選框坐標(biāo)在映射回原圖時就全位移了。正確的做法是部署代碼里復(fù)刻 ultralytics 的預(yù)處理函數(shù)。核心邏輯如下計算縮放比例、完成等比縮放、再用灰邊 (114, 114, 114) 填充到目標(biāo)尺寸、最后做歸一化和維度調(diào)整。下采樣映射回原圖時再把 letterbox 填充的偏移量減去。這段代碼不復(fù)雜但如果抄網(wǎng)上零散版本很容易漏掉 BGR/RGB 轉(zhuǎn)換。建議統(tǒng)一從你訓(xùn)練的框架源碼里把預(yù)處理函數(shù)摳出來翻譯成目標(biāo)語言的版本而不是自己重新“發(fā)明”一遍預(yù)處理。4.3 導(dǎo)出 ONNX 后輸出和 PyTorch 輸出差一點但不算離譜這類問題很隱蔽。報錯倒是沒有數(shù)值對比 diff 也在 1e-3 到 1e-2 量級。這種情況通常來源于兩種因素一是 batch norm 層轉(zhuǎn) fold 時的數(shù)值誤差。PyTorch 推理時 batch norm 是按x - running_mean/ sqrt(running_var eps) * weight bias 逐層計算的而導(dǎo)出到 ONNX 時推理引擎會嘗試把 BN 融合到卷積層里變成 y x * scale offset。這個融合理論上精確但浮點運算順序變化會引入微小誤差。這種誤差在 1e-4 量級通常不影響后處理結(jié)果。二是在 FP16 推理下引入的量化誤差。如果你導(dǎo)出時開了 halfTrueFP32 權(quán)重轉(zhuǎn)成 FP16 會損失一點精度輸出 diff 到 1e-2 量級也是正常的。如果 diff 在這個量級而你的后處理結(jié)果比如檢測框沒有明顯變化基本可以繼續(xù)走但如果 diff 到了 1e-1 以上檢測框都飄了就別以為是“正常誤差”大概率是你某個參數(shù)導(dǎo)出時變了比如權(quán)重文件沒正確加載。4.4 dynamicTrue 導(dǎo)出后動態(tài) shape 導(dǎo)致的隱性 bug有的 YOLO26 模型以動態(tài) shape 導(dǎo)出后某些自研模塊在推導(dǎo)輸入尺寸時依賴于“shape 的數(shù)值”做條件分支比如判斷特征圖寬度是否大于某閾值來決定是否執(zhí)行某個操作。PyTorch 是實時執(zhí)行沒問題但 ONNX 導(dǎo)出時這種條件分支會被固化成靜態(tài)的算子路徑換了輸入尺寸可能執(zhí)行了錯誤的計算路徑導(dǎo)致輸出錯亂。規(guī)避方案很直接不要開 dynamic。如果你的業(yè)務(wù)場景確實需要輸入尺寸可變優(yōu)先考慮在你的部署代碼里做“多檔位”策略比如固定支持三種輸入尺寸分別導(dǎo)出三個 engine 或 ONNX 模型推理時按需調(diào)用。這在工程上比一個動態(tài)模型靠譜得多。4.5 CPU 和 GPU 推理的輸出差異注意點同一個 ONNX 文件在 CPU 上用 ONNX Runtime 跑和在 GPU 上用 TensorRT 跑輸出結(jié)果會有很小的差異原因在于浮點運算順序不同、某些算子在不同后端有不同的實現(xiàn)策略。只要差異在正常范圍內(nèi)通常 mAP 差異不超過 1 個百分點都是合理的。如果差異明顯優(yōu)先檢查是不是某個算子如Resize、GridSample在兩種后端上的插值方式實現(xiàn)不同。YOLO 系列里Resize最常出問題因為框架默認的Resize模式不同版本有細微差別。5. 導(dǎo)出完成后模型要怎么接進真實系統(tǒng)導(dǎo)出只是第一步模型接進推理引擎跑起來才是完整閉環(huán)。這里講一講我在實際項目中用的最小可用推理鏈路以 ONNX Runtime 為例方便各位理解部署側(cè)在做什么。5.1 一套簡潔的 ONNX Runtime CPU 推理流程import numpy as np import cv2 import onnxruntime as ort class YOLO26ONNX: def __init__(self, onnx_path, conf_thres0.25, iou_thres0.45): self.session ort.InferenceSession(onnx_path, providers[CPUExecutionProvider]) self.input_name self.session.get_inputs()[0].name self.input_shape self.session.get_inputs()[0].shape # [1, 3, H, W] self.conf_thres conf_thres self.iou_thres iou_thres def preprocess(self, img_bgr): # 這是從 ultralytics 源碼里摳出來的 letterbox 邏輯 h, w img_bgr.shape[:2] target_h, target_w self.input_shape[2], self.input_shape[3] ratio min(target_w / w, target_h / h) new_w, new_h int(round(w * ratio)), int(round(h * ratio)) resized cv2.resize(img_bgr, (new_w, new_h), interpolationcv2.INTER_LINEAR) canvas np.full((target_h, target_w, 3), 114, dtypenp.uint8) dw, dh (target_w - new_w) // 2, (target_h - new_h) // 2 canvas[dh:dh new_h, dw:dw new_w] resized # BGR - RGB, HWC - CHW, 歸一化 blob canvas[:, :, ::-1].transpose(2, 0, 1).astype(np.float32) / 255.0 blob np.expand_dims(blob, axis0) return blob, ratio, dw, dh def postprocess(self, outputs, ratio, dw, dh): # 先做置信度過濾再做 NMS把框坐標(biāo)減掉 letterbox 偏移并除以縮放比 # outputs shape: [1, 4 num_classes, num_anchors] preds outputs[0][0] # preds shape: [4 num_classes, num_anchors] boxes preds[:4].T # [num_anchors, 4] class_scores preds[4:].T # [num_anchors, num_classes] class_ids class_scores.argmax(axis1) confs class_scores.max(axis1) mask confs self.conf_thres boxes, confs, class_ids boxes[mask], confs[mask], class_ids[mask] # 轉(zhuǎn)換為 xyxy x_center, y_center, bw, bh boxes[:, 0], boxes[:, 1], boxes[:, 2], boxes[:, 3] x1, y1 x_center - bw / 2 dw, y_center - bh / 2 dh x2, y2 x_center bw / 2 dw, y_center bh / 2 dh candidates np.stack([x1, y1, x2, y2, confs, class_ids], axis1) # 這里可以接 nms 函數(shù)按 class 分別做 NMS 或者統(tǒng)一做 NMS return candidates上面代碼里 NMS 部分我沒有展開推薦大家直接復(fù)用成熟實現(xiàn)比如 torchvision.ops.nms 的等價邏輯或者自己翻譯成純 NumPy 的矩陣版本。最需要注意的是后處理時要把 letterbox 加的偏移量(dw, dh)減掉、把坐標(biāo)除以ratio才能映射回原始圖像尺寸。這一步是絕大多數(shù)“模型導(dǎo)出后檢測框不準(zhǔn)”的根源。5.2 TensorRT 部署時的 batch 與顯存管理如果你導(dǎo)出了 TensorRT engine推理時用的是 TensorRT Python API 或者通過 ONNX Runtime 的 TensorRT provider。這里提醒三個點batch size導(dǎo)出 engine 時如果固定了 batch1那推理時只能一次一張地跑如果要支持多 batch導(dǎo)出時需要設(shè)置 batch 維度Ultralytics export 里 batchsize 參數(shù)可配。顯存占用TensorRT engine 在推理時會額外申請 workspace如果你的顯存比較緊張在導(dǎo)出時可以通過參數(shù)限制 workspace 大小避免推理時顯存溢出。第一次推理慢TensorRT 第一次加載 engine 和選 kernel 需要預(yù)熱時間生產(chǎn)環(huán)境建議在服務(wù)啟動時就提前加載并 warmup 一次而不是等第一個請求進來才做。5.3 一個被低估的能力判斷導(dǎo)出模型的正確“工作溫度”推理引擎在不同精度模式下的運行速度差距非常大。FP32、FP16、INT8 三種模式下延遲可以差 3 到 10 倍。實際部署中優(yōu)先級順序是先用 FP32 把全鏈路跑通、產(chǎn)出結(jié)果正確再做 FP16 優(yōu)化精度評估通過后再考慮 INT8 量化不要一上來直接上 INT8除非你非常了解量化校準(zhǔn)集的概念我的建議是導(dǎo)出不是一次性的而是按性能需求分階段迭代的。第一次先導(dǎo)入 ONNX 跑通正確性第二次導(dǎo)出 OpenVINO/Engine 追求速度第三次嘗試 INT8 壓縮體積。寫在最后YOLO26 的模型導(dǎo)出本質(zhì)上一句話把 PyTorch 的動態(tài)圖世界搬到靜態(tài)圖推理引擎的確定世界里去中間所有的不確定性都要靠流程和驗證來消滅。我個人在大量導(dǎo)出實踐中有一個心得永遠不要讓“格式轉(zhuǎn)換成功”成為你做導(dǎo)出任務(wù)的終點而是要拿“對下游完全可解釋、可復(fù)現(xiàn)”作為交付標(biāo)準(zhǔn)。你可以順手把驗證腳本、輸出 shape、精度誤差記錄、導(dǎo)出命令都一起放進一個說明文件里和模型一起交付。這樣無論是給自己半年后回頭看還是交給下一位接手的工程師都會省掉大把重復(fù)排雷的時間。如果你現(xiàn)在正好卡在某個導(dǎo)出報錯里不妨回頭按我排查鏈路的順序一步步走大概率會在第五步之前找到問題癥結(jié)。YOLO26 的代碼和社區(qū)迭代速度都很快工具鏈本身也在不斷變化但“導(dǎo)出前先確認結(jié)構(gòu)、導(dǎo)出后立刻對齊驗證、部署時復(fù)刻預(yù)處理”這三條原則是長期有效的。祝各位都能順利把模型送到生產(chǎn)環(huán)境里好好地跑起來。