：環(huán)境搭建、模型選擇與性能調(diào)優(yōu)全解析)
1. 項目概述與核心價值最近在項目里又用到了YOLOv5雖然現(xiàn)在YOLOv8、YOLOv9甚至YOLOv10都出來了但不得不說YOLOv5依然是很多團隊和個人開發(fā)者的首選。它就像一個“六邊形戰(zhàn)士”在速度、精度、易用性和社區(qū)生態(tài)上取得了非常好的平衡。很多剛接觸目標檢測的朋友或者需要在工業(yè)場景快速落地的工程師第一個想到的往往還是它。今天這篇內(nèi)容我就從一個老手的視角帶大家走一遍YOLOv5從零開始的下載與部署流程。這不僅僅是“照著文檔敲命令”我會把每一步背后的邏輯、可能遇到的坑以及如何根據(jù)你的實際需求做選擇都掰開揉碎了講清楚。無論你是想跑通一個Demo驗證想法還是要為后續(xù)的模型訓練和工程化集成打基礎這套流程都是你必須掌握的“第一課”。2. 環(huán)境準備打造穩(wěn)固的基石部署模型的第一步永遠是把環(huán)境搭建好。一個干凈、版本匹配的環(huán)境能避免90%后續(xù)的玄學問題。YOLOv5對環(huán)境的兼容性已經(jīng)做得相當不錯了但為了追求最佳的穩(wěn)定性和性能我依然推薦大家遵循官方的推薦配置。2.1 核心依賴解析與安裝YOLOv5的核心是PyTorch深度學習框架。你首先需要安裝PyTorch。這里有個關(guān)鍵點不要直接pip install torch。PyTorch的安裝需要根據(jù)你的操作系統(tǒng)、是否使用GPUCUDA版本來選擇合適的命令。去PyTorch官網(wǎng)https://pytorch.org/get-started/locally/看看那里有一個非常直觀的命令生成器。假設你用的是Linux系統(tǒng)有一張NVIDIA顯卡并且安裝了CUDA 11.8那么安裝命令大概是這樣的pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118如果你沒有GPU或者只是想先快速體驗一下可以安裝CPU版本pip install torch torchvision torchaudio安裝完P(guān)yTorch后再安裝YOLOv5所需的其他依賴就簡單了。最規(guī)范的做法是克隆YOLOv5的官方倉庫然后用它的requirements.txt文件來安裝。這能確保所有庫的版本都是經(jīng)過驗證、彼此兼容的。git clone https://github.com/ultralytics/yolov5 # 克隆倉庫 cd yolov5 pip install -r requirements.txt # 安裝所有依賴這個requirements.txt里包含了opencv-python用于圖像處理、matplotlib畫圖、pandas數(shù)據(jù)處理等幾十個庫。用這種方式安裝比你一個個手動pip install要省心得多也安全得多。注意我強烈建議使用Python虛擬環(huán)境如venv或conda來做這件事。這能把你這個項目的依賴和系統(tǒng)其他Python環(huán)境完全隔離開。想象一下你系統(tǒng)里原來有個老項目用的是TensorFlow 1.x而YOLOv5需要一些新版本的庫兩者沖突會導致各種難以排查的錯誤。用虛擬環(huán)境就一勞永逸地解決了這個問題。創(chuàng)建和激活虛擬環(huán)境的命令很簡單python -m venv yolov5_env # 創(chuàng)建名為yolov5_env的虛擬環(huán)境 source yolov5_env/bin/activate # Linux/Mac激活 # 或者 yolov5_env\Scripts\activate # Windows激活激活后你的命令行提示符前面通常會顯示環(huán)境名之后所有pip install操作都只影響這個環(huán)境。2.2 驗證環(huán)境與常見問題安裝完成后怎么知道環(huán)境沒問題呢一個簡單的驗證方法是進入Python交互界面嘗試導入關(guān)鍵庫import torch import cv2 print(torch.__version__) print(torch.cuda.is_available()) # 如果返回True說明GPU可用如果這些導入都沒報錯并且torch.cuda.is_available()返回了True對于GPU用戶那么基礎環(huán)境就算搭建好了。在這個過程中你可能會遇到幾個典型問題網(wǎng)絡超時或下載慢這是因為pip默認的源在國外。解決方法是指定國內(nèi)的鏡像源加速例如使用清華源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple版本沖突某個庫的版本與PyTorch或其他庫不兼容。如果使用requirements.txt安裝后仍報錯可以嘗試單獨升級或降級出問題的包。查看錯誤信息通常它會提示你哪個包需要什么版本。CUDA與PyTorch版本不匹配這是GPU用戶最常踩的坑。表現(xiàn)為torch.cuda.is_available()返回False。請務必核對你的顯卡驅(qū)動支持的CUDA最高版本然后安裝對應版本的PyTorch。你可以通過nvidia-smi命令查看驅(qū)動版本然后去NVIDIA官網(wǎng)查該驅(qū)動支持的CUDA版本。3. 模型獲取選擇合適的“武器”環(huán)境好了接下來就是獲取模型。YOLOv5提供了多種預訓練模型我們稱之為“模型家族”從輕量到重型滿足不同場景。3.1 官方模型家族詳解YOLOv5的官方模型通常按照模型大小和復雜度命名主要有以下幾種以v6.1版本為例YOLOv5n(nano): 最輕量級速度極快精度最低。適合移動端或邊緣設備如Jetson Nano或者對實時性要求極高的場景。YOLOv5s(small): 小型模型在速度和精度間取得了很好的平衡。這是我最推薦初學者和大多數(shù)應用場景首先嘗試的模型它足夠快精度也還不錯。YOLOv5m(medium): 中型模型精度比s有明顯提升速度稍慢。適合對精度有一定要求且算力不是首要瓶頸的場景。YOLOv5l(large): 大型模型精度更高。YOLOv5x(extra large): 超大型模型精度最高速度最慢。通常用于學術(shù)研究刷榜或者在不計成本追求極致精度的場合。如何選擇記住一個核心原則沒有最好的模型只有最適合的模型。如果你的應用是視頻監(jiān)控需要處理30幀的視頻流那n或s可能是唯一選擇。如果你是在處理醫(yī)學圖像每一個漏檢的代價都很大那么即使慢一點也要優(yōu)先考慮l或x。對于大多數(shù)驗證性任務和入門學習從YOLOv5s開始絕對沒錯。3.2 模型下載的兩種方式與原理獲取這些模型有兩種主要方式它們背后的邏輯不同方式一通過代碼自動下載推薦這是最常用、最方便的方式。當你第一次運行YOLOv5的檢測腳本時它會自動檢查并下載你指定的模型。例如運行檢測命令時--weights yolov5s.pt參數(shù)中的yolov5s.pt如果不存在于本地程序會自動從Ultralytics的官方發(fā)布頁面通常是GitHub Release下載。這種方式的好處是省心版本肯定是對的。它的原理是代碼里寫好了模型的URL通過torch.hub.load或類似的機制去獲取。方式二手動下載在某些無法直接訪問外網(wǎng)的環(huán)境如某些企業(yè)內(nèi)網(wǎng)、離線服務器你需要手動下載模型文件。你需要訪問YOLOv5的GitHub倉庫找到Releases頁面在對應的版本比如v6.1的Assets中找到y(tǒng)olov5s.pt、yolov5m.pt等文件手動下載到本地。然后在運行命令時將--weights參數(shù)指向你本地文件的路徑即可例如--weights ./downloads/yolov5s.pt。實操心得對于國內(nèi)用戶自動下載有時會因為網(wǎng)絡問題失敗或極慢。我的習慣是在能順暢訪問外網(wǎng)的環(huán)境比如自己的開發(fā)機上先讓程序自動下載一次把.pt模型文件緩存下來。然后把這個文件拷貝到內(nèi)網(wǎng)或生產(chǎn)環(huán)境中使用。模型文件的位置通常在~/.cache/torch/hub/目錄下Linux/Mac或C:\Users\用戶名\.cache\torch\hub\Windows的對應子目錄中。找到它備份它這是一個好習慣。4. 快速部署與首次推理模型到手環(huán)境就緒是時候讓它“動起來”了。我們將進行第一次圖片推理這是驗證整個流程是否暢通的關(guān)鍵一步。4.1 使用官方腳本進行圖片檢測YOLOv5倉庫根目錄下的detect.py腳本是進行推理的入口。它的設計非常簡潔只需要指定模型權(quán)重、輸入源和輸出目錄即可。一個最基礎的命令如下python detect.py --weights yolov5s.pt --source data/images/bus.jpg --project runs/detect --name exp讓我們拆解這個命令--weights yolov5s.pt: 指定使用的模型權(quán)重。這里會觸發(fā)我們上面說的自動下載如果本地沒有。--source data/images/bus.jpg: 指定輸入源。它可以是單張圖片如.jpg, .png、一個包含多張圖片的文件夾、一個視頻文件.mp4, .avi、甚至是一個RTSP流地址如rtsp://...或攝像頭索引如0表示第一個攝像頭。YOLOv5倉庫自帶了幾張示例圖片在data/images/目錄下bus.jpg就是其中之一。--project runs/detect: 指定所有推理實驗結(jié)果的父目錄。--name exp: 指定本次實驗的子目錄名。輸出結(jié)果會保存在runs/detect/exp/這個路徑下。執(zhí)行這個命令后你會看到終端開始打印信息。首先會加載模型然后顯示模型的結(jié)構(gòu)一層層的卷積、SPPF、Detect頭等接著開始處理圖片。處理完成后它會告訴你結(jié)果保存的路徑例如Results saved to runs/detect/exp 1 image processed, 0.023s pre-process, 0.004s inference, 0.001s NMS per image at shape (1, 3, 640, 640)打開runs/detect/exp文件夾你就能看到處理后的圖片bus.jpg圖片上應該已經(jīng)畫出了檢測到的行人、汽車等物體的邊界框、類別標簽和置信度。4.2 關(guān)鍵參數(shù)解析與調(diào)優(yōu)第一次跑通固然令人興奮但detect.py的強大之處在于它豐富的參數(shù)可以讓你精細控制推理過程。了解這些參數(shù)你才能用活這個工具。--img-size或--imgsz: 輸入圖片的尺寸。默認是640。模型會將輸入圖片縮放到這個尺寸進行處理。這是一個非常重要的參數(shù)。增大尺寸如1280通常會提升檢測小物體的精度但會顯著增加計算量和內(nèi)存占用降低速度。減小尺寸則相反。你需要根據(jù)你的硬件條件和任務需求是更看重速度還是精度來權(quán)衡。通常保持640是一個不錯的起點。--conf-thres: 置信度閾值。默認0.25。模型會輸出很多預測框每個框有一個置信度分數(shù)表示模型有多確信這個框里有所說的物體。低于這個閾值的預測框會被直接過濾掉。調(diào)高這個值如0.5可以讓結(jié)果更“干凈”只留下把握很大的檢測框但可能會漏掉一些模糊的物體。調(diào)低則可能看到更多結(jié)果但雜訊假陽性也會變多。--iou-thres: 非極大值抑制NMS的IoU閾值。默認0.45。當多個預測框指向同一個物體時NMS會保留置信度最高的那個并抑制掉與其重疊度IoU過高的其他框。這個閾值決定了“多高算過高”。調(diào)低它如0.3會讓NMS更嚴格同一個物體最終只留下一個框但若物體密集可能會誤殺調(diào)高它則可能讓一個物體留下多個框。--max-det: 每張圖片最大檢測數(shù)量。默認300。防止一張圖片里出現(xiàn)成百上千個無意義的檢測框。--device: 指定運行設備。默認是空程序會自動選擇。你可以指定--device 0使用第一塊GPU--device cpu強制使用CPU。在服務器上有多卡時這個參數(shù)很有用。--view-img: 一個布爾標志。加上這個參數(shù)會在推理時彈出一個窗口實時顯示檢測結(jié)果。在調(diào)試和演示時非常直觀。--save-txt: 保存檢測結(jié)果為YOLO格式的txt文件。每個txt文件對應一張圖片里面記錄了每個檢測框的類別、中心點坐標、寬高都是歸一化后的值。這個功能對于后續(xù)生成數(shù)據(jù)集標簽、或者與其他系統(tǒng)集成至關(guān)重要。一個更復雜的、調(diào)優(yōu)后的命令可能長這樣python detect.py --weights yolov5m.pt --source ./my_video.mp4 --img-size 1280 --conf-thres 0.4 --iou-thres 0.5 --device 0 --view-img --save-txt這個命令意味著使用精度更高的yolov5m模型處理我自己的視頻my_video.mp4以更高的分辨率1280進行推理只相信置信度高于0.4的預測使用更寬松的NMS0.5來處理可能重疊的物體指定使用第一塊GPU實時顯示畫面并保存檢測框的坐標數(shù)據(jù)。5. 深入部署超越基礎腳本當你熟練使用detect.py后可能會遇到一些更復雜的需求比如將YOLOv5集成到自己的Python項目中或者需要更高的推理性能。這時就需要更深入的部署方式。5.1 使用PyTorch Hub極簡調(diào)用PyTorch Hub是PyTorch提供的一個模型倉庫和加載工具。YOLOv5也支持這種方式它能讓你的代碼變得異常簡潔。在你的Python腳本中只需要幾行import torch # 從PyTorch Hub加載模型 model torch.hub.load(ultralytics/yolov5, yolov5s, pretrainedTrue) # 設置模型為評估模式這對推理是必須的 model.eval() # 進行推理 img https://ultralytics.com/images/zidane.jpg # 可以是圖片路徑、URL、PIL圖像、OpenCV圖像等 results model(img) # 查看結(jié)果 results.print() # 打印檢測到的物體信息 results.show() # 顯示帶標注的圖片 results.save() # 保存圖片到當前目錄這種方式本質(zhì)上和運行detect.py腳本是一樣的但它給了你更大的靈活性。results對象包含了豐富的屬性比如results.pandas().xyxy[0]可以返回一個Pandas DataFrame里面是檢測框的坐標、置信度和類別方便你進行后續(xù)的數(shù)據(jù)處理和分析。5.2 模型導出與優(yōu)化推理在生產(chǎn)環(huán)境中我們很少直接使用原始的PyTorch模型.pt文件。為了追求極致的推理速度和跨平臺部署能力我們需要將模型“導出”成更高效的格式。1. 導出為TorchScriptTorchScript是PyTorch模型的一種中間表示它可以被脫離Python環(huán)境運行例如在C中調(diào)用。使用YOLOv5自帶的export.py腳本可以輕松導出python export.py --weights yolov5s.pt --include torchscript執(zhí)行后你會得到一個yolov5s.torchscript.pt文件。這個文件可以在C中使用LibTorch庫進行加載和推理這對于嵌入式設備或?qū)ython依賴有潔癖的服務端部署非常有用。2. 導出為ONNXONNX是一種開放的模型交換格式得到了眾多推理引擎的支持如TensorRT, OpenVINO, ONNX Runtime等。導出ONNX同樣簡單python export.py --weights yolov5s.pt --include onnx得到y(tǒng)olov5s.onnx文件后你就可以使用ONNX Runtime進行推理了。下面是一個簡單的ONNX Runtime推理示例import onnxruntime import cv2 import numpy as np # 加載ONNX模型和創(chuàng)建會話 ort_session onnxruntime.InferenceSession(yolov5s.onnx) # 準備輸入數(shù)據(jù)需要預處理BGR-RGB, HWC-CHW, 歸一化增加批次維度 img cv2.imread(bus.jpg) img_rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img_resized cv2.resize(img_rgb, (640, 640)) input_data img_resized.transpose(2, 0, 1).astype(np.float32) / 255.0 input_data np.expand_dims(input_data, axis0) # 變成 [1, 3, 640, 640] # 運行推理 ort_inputs {ort_session.get_inputs()[0].name: input_data} ort_outs ort_session.run(None, ort_inputs) # ort_outs 包含了輸出后續(xù)需要做后處理如NMS來解析出檢測框3. 導出為TensorRT或OpenVINO性能飛躍如果你有NVIDIA顯卡強烈建議導出為TensorRT引擎。TensorRT會對模型進行層融合、精度校準FP16/INT8、內(nèi)核自動調(diào)優(yōu)等深度優(yōu)化通常能帶來數(shù)倍甚至十數(shù)倍的推理速度提升。YOLOv5的export.py也支持直接導出為TensorRTpython export.py --weights yolov5s.pt --include engine --device 0類似地對于Intel的CPU或集成顯卡可以導出為OpenVINO的IR格式也能獲得顯著的加速效果。注意事項導出模型不是一勞永逸的。導出的模型只包含了前向推理的計算圖預處理縮放、歸一化和后處理NMS通常需要你自己實現(xiàn)。YOLOv5的導出腳本會嘗試將一些簡單的預處理如/255打包進模型但復雜的后處理一般不包括。所以當你使用導出的模型時需要參考原始倉庫中的代碼確保你的前處理和后處理與訓練時保持一致否則結(jié)果會完全不對。6. 實戰(zhàn)問題排查與性能調(diào)優(yōu)指南在實際部署中你幾乎一定會遇到各種問題。下面我整理了一份從新手到進階常遇到的“坑”及其解決方案。6.1 常見錯誤與解決方案速查表問題現(xiàn)象可能原因解決方案ImportError: No module named ‘xxx‘依賴庫未安裝或版本不對。1. 檢查是否在正確的虛擬環(huán)境中。2. 運行pip install -r requirements.txt重新安裝。3. 根據(jù)錯誤信息單獨安裝缺失的包。torch.cuda.is_available()返回False1. PyTorch版本與CUDA版本不匹配。2. 顯卡驅(qū)動太舊。3. 系統(tǒng)未安裝CUDA工具包。1. 使用nvidia-smi查看驅(qū)動支持的CUDA最高版本安裝對應PyTorch。2. 更新顯卡驅(qū)動。3. 從NVIDIA官網(wǎng)下載并安裝CUDA Toolkit。推理速度非常慢1. 模型在CPU上運行。2. 使用了過大的模型如YOLOv5x。3. 輸入圖片尺寸 (--img-size) 設置過大。1. 確保--device 0或檢查CUDA是否可用。2. 換用更小的模型如YOLOv5s。3. 嘗試減小--img-size(如從1280降到640)。檢測結(jié)果框太多/太雜亂置信度閾值 (--conf-thres) 設置過低。逐步調(diào)高--conf-thres如從0.25調(diào)到0.5或更高直到結(jié)果滿意。同一個物體被重復檢測多個框NMS的IoU閾值 (--iou-thres) 設置過高。逐步調(diào)低--iou-thres如從0.45調(diào)到0.3或更低。檢測不到小物體1. 模型本身能力有限。2. 輸入圖片尺寸太小小物體特征丟失。1. 換用更大的模型如YOLOv5l。2. 增大--img-size(如從640增到1280)。3. 考慮使用專門針對小物體改進的模型或方法。自動下載模型失敗/極慢網(wǎng)絡連接問題。1. 手動下載模型文件用--weights指定本地路徑。2. 配置網(wǎng)絡代理。內(nèi)存不足 (OOM)1. 圖片尺寸太大或批次太大。2. 模型太大。3. GPU顯存太小。1. 減小--img-size。2. 換用小模型。3. 嘗試在CPU上運行 (--device cpu)。6.2 性能調(diào)優(yōu)實戰(zhàn)心得除了解決錯誤讓模型跑得更快、更穩(wěn)才是部署的終極目標。這里分享幾個壓箱底的調(diào)優(yōu)經(jīng)驗1. 圖片尺寸是性能杠桿--img-size是影響速度和精度最直接的參數(shù)。它的值必須是32的倍數(shù)因為YOLOv5網(wǎng)絡中有5次下采樣2^532。一個黃金法則是在滿足精度的前提下使用盡可能小的尺寸。你可以做一個簡單的實驗用同一段視頻分別用--img-size 320和--img-size 640去檢測對比FPS和檢測效果。你會發(fā)現(xiàn)尺寸減半速度可能提升3-4倍但小物體的檢測能力會下降。這個權(quán)衡需要你自己根據(jù)業(yè)務指標來定。2. 批處理 (Batch Inference) 加速detect.py腳本默認是一次處理一張圖片。但在處理大量圖片或視頻流時批處理可以極大提升GPU利用率。雖然detect.py沒有直接提供批處理圖片文件夾的顯式參數(shù)但它的--source參數(shù)支持傳入一個圖片目錄程序內(nèi)部會以批次的形式進行處理。你可以通過修改源碼中的detect.py找到創(chuàng)建DataLoader的部分調(diào)整batch_size參數(shù)來改變批次大小。增大batch_size能提升吞吐量但也會增加延遲和內(nèi)存消耗對于實時視頻流batch_size1通常是延遲最低的選擇。3. 使用TensorRT進行終極加速如果你部署在NVIDIA GPU上并且對性能有極致要求那么TensorRT是必經(jīng)之路。過程大致是PyTorch - ONNX - TensorRT。YOLOv5的export.py提供了--include engine選項可以一鍵完成轉(zhuǎn)換內(nèi)部先轉(zhuǎn)ONNX再轉(zhuǎn)TensorRT。轉(zhuǎn)換時你可以指定精度為FP16甚至INT8。FP16精度幾乎無損速度提升明顯INT8量化需要校準數(shù)據(jù)集精度可能有輕微損失但速度最快內(nèi)存占用最小。轉(zhuǎn)換后的.engine文件推理速度相比原始PyTorch模型常有數(shù)倍提升。4. 預處理與后處理優(yōu)化推理過程不僅僅是模型前向傳播。圖片解碼、縮放、歸一化預處理以及解析輸出、做NMS后處理也占了相當一部分時間。對于高并發(fā)場景可以考慮使用GPU加速的圖片解碼和預處理如NVIDIA的DALI庫。將后處理尤其是NMS也放到GPU上執(zhí)行。YOLOv5的PyTorch模型輸出后其NMS是在CPU上進行的?？梢詫ふ一蜃约簩崿F(xiàn)CUDA版本的NMS內(nèi)核與模型推理在同一個GPU流中完成減少數(shù)據(jù)在CPU和GPU間的傳輸。部署YOLOv5模型從下載到跑通Demo可能只需要10分鐘但要想把它打磨成一個在生產(chǎn)環(huán)境中穩(wěn)定、高效運行的組件需要對這些細節(jié)有深入的理解和不斷的調(diào)試。希望這篇超過5000字的詳細拆解能幫你打下扎實的基礎避開我當年踩過的那些坑。記住動手試一遍遠比看十遍文章要有效。 YOLOv5從零部署實戰(zhàn)：環(huán)境搭建、模型選擇與性能調(diào)優(yōu)全解析
1. 項目概述與核心價值最近在項目里又用到了YOLOv5雖然現(xiàn)在YOLOv8、YOLOv9甚至YOLOv10都出來了但不得不說YOLOv5依然是很多團隊和個人開發(fā)者的首選。它就像一個“六邊形戰(zhàn)士”在速度、精度、易用性和社區(qū)生態(tài)上取得了非常好的平衡。很多剛接觸目標檢測的朋友或者需要在工業(yè)場景快速落地的工程師第一個想到的往往還是它。今天這篇內(nèi)容我就從一個老手的視角帶大家走一遍YOLOv5從零開始的下載與部署流程。這不僅僅是“照著文檔敲命令”我會把每一步背后的邏輯、可能遇到的坑以及如何根據(jù)你的實際需求做選擇都掰開揉碎了講清楚。無論你是想跑通一個Demo驗證想法還是要為后續(xù)的模型訓練和工程化集成打基礎這套流程都是你必須掌握的“第一課”。2. 環(huán)境準備打造穩(wěn)固的基石部署模型的第一步永遠是把環(huán)境搭建好。一個干凈、版本匹配的環(huán)境能避免90%后續(xù)的玄學問題。YOLOv5對環(huán)境的兼容性已經(jīng)做得相當不錯了但為了追求最佳的穩(wěn)定性和性能我依然推薦大家遵循官方的推薦配置。2.1 核心依賴解析與安裝YOLOv5的核心是PyTorch深度學習框架。你首先需要安裝PyTorch。這里有個關(guān)鍵點不要直接pip install torch。PyTorch的安裝需要根據(jù)你的操作系統(tǒng)、是否使用GPUCUDA版本來選擇合適的命令。去PyTorch官網(wǎng)https://pytorch.org/get-started/locally/看看那里有一個非常直觀的命令生成器。假設你用的是Linux系統(tǒng)有一張NVIDIA顯卡并且安裝了CUDA 11.8那么安裝命令大概是這樣的pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118如果你沒有GPU或者只是想先快速體驗一下可以安裝CPU版本pip install torch torchvision torchaudio安裝完P(guān)yTorch后再安裝YOLOv5所需的其他依賴就簡單了。最規(guī)范的做法是克隆YOLOv5的官方倉庫然后用它的requirements.txt文件來安裝。這能確保所有庫的版本都是經(jīng)過驗證、彼此兼容的。git clone https://github.com/ultralytics/yolov5 # 克隆倉庫 cd yolov5 pip install -r requirements.txt # 安裝所有依賴這個requirements.txt里包含了opencv-python用于圖像處理、matplotlib畫圖、pandas數(shù)據(jù)處理等幾十個庫。用這種方式安裝比你一個個手動pip install要省心得多也安全得多。注意我強烈建議使用Python虛擬環(huán)境如venv或conda來做這件事。這能把你這個項目的依賴和系統(tǒng)其他Python環(huán)境完全隔離開。想象一下你系統(tǒng)里原來有個老項目用的是TensorFlow 1.x而YOLOv5需要一些新版本的庫兩者沖突會導致各種難以排查的錯誤。用虛擬環(huán)境就一勞永逸地解決了這個問題。創(chuàng)建和激活虛擬環(huán)境的命令很簡單python -m venv yolov5_env # 創(chuàng)建名為yolov5_env的虛擬環(huán)境 source yolov5_env/bin/activate # Linux/Mac激活 # 或者 yolov5_env\Scripts\activate # Windows激活激活后你的命令行提示符前面通常會顯示環(huán)境名之后所有pip install操作都只影響這個環(huán)境。2.2 驗證環(huán)境與常見問題安裝完成后怎么知道環(huán)境沒問題呢一個簡單的驗證方法是進入Python交互界面嘗試導入關(guān)鍵庫import torch import cv2 print(torch.__version__) print(torch.cuda.is_available()) # 如果返回True說明GPU可用如果這些導入都沒報錯并且torch.cuda.is_available()返回了True對于GPU用戶那么基礎環(huán)境就算搭建好了。在這個過程中你可能會遇到幾個典型問題網(wǎng)絡超時或下載慢這是因為pip默認的源在國外。解決方法是指定國內(nèi)的鏡像源加速例如使用清華源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple版本沖突某個庫的版本與PyTorch或其他庫不兼容。如果使用requirements.txt安裝后仍報錯可以嘗試單獨升級或降級出問題的包。查看錯誤信息通常它會提示你哪個包需要什么版本。CUDA與PyTorch版本不匹配這是GPU用戶最常踩的坑。表現(xiàn)為torch.cuda.is_available()返回False。請務必核對你的顯卡驅(qū)動支持的CUDA最高版本然后安裝對應版本的PyTorch。你可以通過nvidia-smi命令查看驅(qū)動版本然后去NVIDIA官網(wǎng)查該驅(qū)動支持的CUDA版本。3. 模型獲取選擇合適的“武器”環(huán)境好了接下來就是獲取模型。YOLOv5提供了多種預訓練模型我們稱之為“模型家族”從輕量到重型滿足不同場景。3.1 官方模型家族詳解YOLOv5的官方模型通常按照模型大小和復雜度命名主要有以下幾種以v6.1版本為例YOLOv5n(nano): 最輕量級速度極快精度最低。適合移動端或邊緣設備如Jetson Nano或者對實時性要求極高的場景。YOLOv5s(small): 小型模型在速度和精度間取得了很好的平衡。這是我最推薦初學者和大多數(shù)應用場景首先嘗試的模型它足夠快精度也還不錯。YOLOv5m(medium): 中型模型精度比s有明顯提升速度稍慢。適合對精度有一定要求且算力不是首要瓶頸的場景。YOLOv5l(large): 大型模型精度更高。YOLOv5x(extra large): 超大型模型精度最高速度最慢。通常用于學術(shù)研究刷榜或者在不計成本追求極致精度的場合。如何選擇記住一個核心原則沒有最好的模型只有最適合的模型。如果你的應用是視頻監(jiān)控需要處理30幀的視頻流那n或s可能是唯一選擇。如果你是在處理醫(yī)學圖像每一個漏檢的代價都很大那么即使慢一點也要優(yōu)先考慮l或x。對于大多數(shù)驗證性任務和入門學習從YOLOv5s開始絕對沒錯。3.2 模型下載的兩種方式與原理獲取這些模型有兩種主要方式它們背后的邏輯不同方式一通過代碼自動下載推薦這是最常用、最方便的方式。當你第一次運行YOLOv5的檢測腳本時它會自動檢查并下載你指定的模型。例如運行檢測命令時--weights yolov5s.pt參數(shù)中的yolov5s.pt如果不存在于本地程序會自動從Ultralytics的官方發(fā)布頁面通常是GitHub Release下載。這種方式的好處是省心版本肯定是對的。它的原理是代碼里寫好了模型的URL通過torch.hub.load或類似的機制去獲取。方式二手動下載在某些無法直接訪問外網(wǎng)的環(huán)境如某些企業(yè)內(nèi)網(wǎng)、離線服務器你需要手動下載模型文件。你需要訪問YOLOv5的GitHub倉庫找到Releases頁面在對應的版本比如v6.1的Assets中找到y(tǒng)olov5s.pt、yolov5m.pt等文件手動下載到本地。然后在運行命令時將--weights參數(shù)指向你本地文件的路徑即可例如--weights ./downloads/yolov5s.pt。實操心得對于國內(nèi)用戶自動下載有時會因為網(wǎng)絡問題失敗或極慢。我的習慣是在能順暢訪問外網(wǎng)的環(huán)境比如自己的開發(fā)機上先讓程序自動下載一次把.pt模型文件緩存下來。然后把這個文件拷貝到內(nèi)網(wǎng)或生產(chǎn)環(huán)境中使用。模型文件的位置通常在~/.cache/torch/hub/目錄下Linux/Mac或C:\Users\用戶名\.cache\torch\hub\Windows的對應子目錄中。找到它備份它這是一個好習慣。4. 快速部署與首次推理模型到手環(huán)境就緒是時候讓它“動起來”了。我們將進行第一次圖片推理這是驗證整個流程是否暢通的關(guān)鍵一步。4.1 使用官方腳本進行圖片檢測YOLOv5倉庫根目錄下的detect.py腳本是進行推理的入口。它的設計非常簡潔只需要指定模型權(quán)重、輸入源和輸出目錄即可。一個最基礎的命令如下python detect.py --weights yolov5s.pt --source data/images/bus.jpg --project runs/detect --name exp讓我們拆解這個命令--weights yolov5s.pt: 指定使用的模型權(quán)重。這里會觸發(fā)我們上面說的自動下載如果本地沒有。--source data/images/bus.jpg: 指定輸入源。它可以是單張圖片如.jpg, .png、一個包含多張圖片的文件夾、一個視頻文件.mp4, .avi、甚至是一個RTSP流地址如rtsp://...或攝像頭索引如0表示第一個攝像頭。YOLOv5倉庫自帶了幾張示例圖片在data/images/目錄下bus.jpg就是其中之一。--project runs/detect: 指定所有推理實驗結(jié)果的父目錄。--name exp: 指定本次實驗的子目錄名。輸出結(jié)果會保存在runs/detect/exp/這個路徑下。執(zhí)行這個命令后你會看到終端開始打印信息。首先會加載模型然后顯示模型的結(jié)構(gòu)一層層的卷積、SPPF、Detect頭等接著開始處理圖片。處理完成后它會告訴你結(jié)果保存的路徑例如Results saved to runs/detect/exp 1 image processed, 0.023s pre-process, 0.004s inference, 0.001s NMS per image at shape (1, 3, 640, 640)打開runs/detect/exp文件夾你就能看到處理后的圖片bus.jpg圖片上應該已經(jīng)畫出了檢測到的行人、汽車等物體的邊界框、類別標簽和置信度。4.2 關(guān)鍵參數(shù)解析與調(diào)優(yōu)第一次跑通固然令人興奮但detect.py的強大之處在于它豐富的參數(shù)可以讓你精細控制推理過程。了解這些參數(shù)你才能用活這個工具。--img-size或--imgsz: 輸入圖片的尺寸。默認是640。模型會將輸入圖片縮放到這個尺寸進行處理。這是一個非常重要的參數(shù)。增大尺寸如1280通常會提升檢測小物體的精度但會顯著增加計算量和內(nèi)存占用降低速度。減小尺寸則相反。你需要根據(jù)你的硬件條件和任務需求是更看重速度還是精度來權(quán)衡。通常保持640是一個不錯的起點。--conf-thres: 置信度閾值。默認0.25。模型會輸出很多預測框每個框有一個置信度分數(shù)表示模型有多確信這個框里有所說的物體。低于這個閾值的預測框會被直接過濾掉。調(diào)高這個值如0.5可以讓結(jié)果更“干凈”只留下把握很大的檢測框但可能會漏掉一些模糊的物體。調(diào)低則可能看到更多結(jié)果但雜訊假陽性也會變多。--iou-thres: 非極大值抑制NMS的IoU閾值。默認0.45。當多個預測框指向同一個物體時NMS會保留置信度最高的那個并抑制掉與其重疊度IoU過高的其他框。這個閾值決定了“多高算過高”。調(diào)低它如0.3會讓NMS更嚴格同一個物體最終只留下一個框但若物體密集可能會誤殺調(diào)高它則可能讓一個物體留下多個框。--max-det: 每張圖片最大檢測數(shù)量。默認300。防止一張圖片里出現(xiàn)成百上千個無意義的檢測框。--device: 指定運行設備。默認是空程序會自動選擇。你可以指定--device 0使用第一塊GPU--device cpu強制使用CPU。在服務器上有多卡時這個參數(shù)很有用。--view-img: 一個布爾標志。加上這個參數(shù)會在推理時彈出一個窗口實時顯示檢測結(jié)果。在調(diào)試和演示時非常直觀。--save-txt: 保存檢測結(jié)果為YOLO格式的txt文件。每個txt文件對應一張圖片里面記錄了每個檢測框的類別、中心點坐標、寬高都是歸一化后的值。這個功能對于后續(xù)生成數(shù)據(jù)集標簽、或者與其他系統(tǒng)集成至關(guān)重要。一個更復雜的、調(diào)優(yōu)后的命令可能長這樣python detect.py --weights yolov5m.pt --source ./my_video.mp4 --img-size 1280 --conf-thres 0.4 --iou-thres 0.5 --device 0 --view-img --save-txt這個命令意味著使用精度更高的yolov5m模型處理我自己的視頻my_video.mp4以更高的分辨率1280進行推理只相信置信度高于0.4的預測使用更寬松的NMS0.5來處理可能重疊的物體指定使用第一塊GPU實時顯示畫面并保存檢測框的坐標數(shù)據(jù)。5. 深入部署超越基礎腳本當你熟練使用detect.py后可能會遇到一些更復雜的需求比如將YOLOv5集成到自己的Python項目中或者需要更高的推理性能。這時就需要更深入的部署方式。5.1 使用PyTorch Hub極簡調(diào)用PyTorch Hub是PyTorch提供的一個模型倉庫和加載工具。YOLOv5也支持這種方式它能讓你的代碼變得異常簡潔。在你的Python腳本中只需要幾行import torch # 從PyTorch Hub加載模型 model torch.hub.load(ultralytics/yolov5, yolov5s, pretrainedTrue) # 設置模型為評估模式這對推理是必須的 model.eval() # 進行推理 img https://ultralytics.com/images/zidane.jpg # 可以是圖片路徑、URL、PIL圖像、OpenCV圖像等 results model(img) # 查看結(jié)果 results.print() # 打印檢測到的物體信息 results.show() # 顯示帶標注的圖片 results.save() # 保存圖片到當前目錄這種方式本質(zhì)上和運行detect.py腳本是一樣的但它給了你更大的靈活性。results對象包含了豐富的屬性比如results.pandas().xyxy[0]可以返回一個Pandas DataFrame里面是檢測框的坐標、置信度和類別方便你進行后續(xù)的數(shù)據(jù)處理和分析。5.2 模型導出與優(yōu)化推理在生產(chǎn)環(huán)境中我們很少直接使用原始的PyTorch模型.pt文件。為了追求極致的推理速度和跨平臺部署能力我們需要將模型“導出”成更高效的格式。1. 導出為TorchScriptTorchScript是PyTorch模型的一種中間表示它可以被脫離Python環(huán)境運行例如在C中調(diào)用。使用YOLOv5自帶的export.py腳本可以輕松導出python export.py --weights yolov5s.pt --include torchscript執(zhí)行后你會得到一個yolov5s.torchscript.pt文件。這個文件可以在C中使用LibTorch庫進行加載和推理這對于嵌入式設備或?qū)ython依賴有潔癖的服務端部署非常有用。2. 導出為ONNXONNX是一種開放的模型交換格式得到了眾多推理引擎的支持如TensorRT, OpenVINO, ONNX Runtime等。導出ONNX同樣簡單python export.py --weights yolov5s.pt --include onnx得到y(tǒng)olov5s.onnx文件后你就可以使用ONNX Runtime進行推理了。下面是一個簡單的ONNX Runtime推理示例import onnxruntime import cv2 import numpy as np # 加載ONNX模型和創(chuàng)建會話 ort_session onnxruntime.InferenceSession(yolov5s.onnx) # 準備輸入數(shù)據(jù)需要預處理BGR-RGB, HWC-CHW, 歸一化增加批次維度 img cv2.imread(bus.jpg) img_rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img_resized cv2.resize(img_rgb, (640, 640)) input_data img_resized.transpose(2, 0, 1).astype(np.float32) / 255.0 input_data np.expand_dims(input_data, axis0) # 變成 [1, 3, 640, 640] # 運行推理 ort_inputs {ort_session.get_inputs()[0].name: input_data} ort_outs ort_session.run(None, ort_inputs) # ort_outs 包含了輸出后續(xù)需要做后處理如NMS來解析出檢測框3. 導出為TensorRT或OpenVINO性能飛躍如果你有NVIDIA顯卡強烈建議導出為TensorRT引擎。TensorRT會對模型進行層融合、精度校準FP16/INT8、內(nèi)核自動調(diào)優(yōu)等深度優(yōu)化通常能帶來數(shù)倍甚至十數(shù)倍的推理速度提升。YOLOv5的export.py也支持直接導出為TensorRTpython export.py --weights yolov5s.pt --include engine --device 0類似地對于Intel的CPU或集成顯卡可以導出為OpenVINO的IR格式也能獲得顯著的加速效果。注意事項導出模型不是一勞永逸的。導出的模型只包含了前向推理的計算圖預處理縮放、歸一化和后處理NMS通常需要你自己實現(xiàn)。YOLOv5的導出腳本會嘗試將一些簡單的預處理如/255打包進模型但復雜的后處理一般不包括。所以當你使用導出的模型時需要參考原始倉庫中的代碼確保你的前處理和后處理與訓練時保持一致否則結(jié)果會完全不對。6. 實戰(zhàn)問題排查與性能調(diào)優(yōu)指南在實際部署中你幾乎一定會遇到各種問題。下面我整理了一份從新手到進階常遇到的“坑”及其解決方案。6.1 常見錯誤與解決方案速查表問題現(xiàn)象可能原因解決方案ImportError: No module named ‘xxx‘依賴庫未安裝或版本不對。1. 檢查是否在正確的虛擬環(huán)境中。2. 運行pip install -r requirements.txt重新安裝。3. 根據(jù)錯誤信息單獨安裝缺失的包。torch.cuda.is_available()返回False1. PyTorch版本與CUDA版本不匹配。2. 顯卡驅(qū)動太舊。3. 系統(tǒng)未安裝CUDA工具包。1. 使用nvidia-smi查看驅(qū)動支持的CUDA最高版本安裝對應PyTorch。2. 更新顯卡驅(qū)動。3. 從NVIDIA官網(wǎng)下載并安裝CUDA Toolkit。推理速度非常慢1. 模型在CPU上運行。2. 使用了過大的模型如YOLOv5x。3. 輸入圖片尺寸 (--img-size) 設置過大。1. 確保--device 0或檢查CUDA是否可用。2. 換用更小的模型如YOLOv5s。3. 嘗試減小--img-size(如從1280降到640)。檢測結(jié)果框太多/太雜亂置信度閾值 (--conf-thres) 設置過低。逐步調(diào)高--conf-thres如從0.25調(diào)到0.5或更高直到結(jié)果滿意。同一個物體被重復檢測多個框NMS的IoU閾值 (--iou-thres) 設置過高。逐步調(diào)低--iou-thres如從0.45調(diào)到0.3或更低。檢測不到小物體1. 模型本身能力有限。2. 輸入圖片尺寸太小小物體特征丟失。1. 換用更大的模型如YOLOv5l。2. 增大--img-size(如從640增到1280)。3. 考慮使用專門針對小物體改進的模型或方法。自動下載模型失敗/極慢網(wǎng)絡連接問題。1. 手動下載模型文件用--weights指定本地路徑。2. 配置網(wǎng)絡代理。內(nèi)存不足 (OOM)1. 圖片尺寸太大或批次太大。2. 模型太大。3. GPU顯存太小。1. 減小--img-size。2. 換用小模型。3. 嘗試在CPU上運行 (--device cpu)。6.2 性能調(diào)優(yōu)實戰(zhàn)心得除了解決錯誤讓模型跑得更快、更穩(wěn)才是部署的終極目標。這里分享幾個壓箱底的調(diào)優(yōu)經(jīng)驗1. 圖片尺寸是性能杠桿--img-size是影響速度和精度最直接的參數(shù)。它的值必須是32的倍數(shù)因為YOLOv5網(wǎng)絡中有5次下采樣2^532。一個黃金法則是在滿足精度的前提下使用盡可能小的尺寸。你可以做一個簡單的實驗用同一段視頻分別用--img-size 320和--img-size 640去檢測對比FPS和檢測效果。你會發(fā)現(xiàn)尺寸減半速度可能提升3-4倍但小物體的檢測能力會下降。這個權(quán)衡需要你自己根據(jù)業(yè)務指標來定。2. 批處理 (Batch Inference) 加速detect.py腳本默認是一次處理一張圖片。但在處理大量圖片或視頻流時批處理可以極大提升GPU利用率。雖然detect.py沒有直接提供批處理圖片文件夾的顯式參數(shù)但它的--source參數(shù)支持傳入一個圖片目錄程序內(nèi)部會以批次的形式進行處理。你可以通過修改源碼中的detect.py找到創(chuàng)建DataLoader的部分調(diào)整batch_size參數(shù)來改變批次大小。增大batch_size能提升吞吐量但也會增加延遲和內(nèi)存消耗對于實時視頻流batch_size1通常是延遲最低的選擇。3. 使用TensorRT進行終極加速如果你部署在NVIDIA GPU上并且對性能有極致要求那么TensorRT是必經(jīng)之路。過程大致是PyTorch - ONNX - TensorRT。YOLOv5的export.py提供了--include engine選項可以一鍵完成轉(zhuǎn)換內(nèi)部先轉(zhuǎn)ONNX再轉(zhuǎn)TensorRT。轉(zhuǎn)換時你可以指定精度為FP16甚至INT8。FP16精度幾乎無損速度提升明顯INT8量化需要校準數(shù)據(jù)集精度可能有輕微損失但速度最快內(nèi)存占用最小。轉(zhuǎn)換后的.engine文件推理速度相比原始PyTorch模型常有數(shù)倍提升。4. 預處理與后處理優(yōu)化推理過程不僅僅是模型前向傳播。圖片解碼、縮放、歸一化預處理以及解析輸出、做NMS后處理也占了相當一部分時間。對于高并發(fā)場景可以考慮使用GPU加速的圖片解碼和預處理如NVIDIA的DALI庫。將后處理尤其是NMS也放到GPU上執(zhí)行。YOLOv5的PyTorch模型輸出后其NMS是在CPU上進行的?？梢詫ふ一蜃约簩崿F(xiàn)CUDA版本的NMS內(nèi)核與模型推理在同一個GPU流中完成減少數(shù)據(jù)在CPU和GPU間的傳輸。部署YOLOv5模型從下載到跑通Demo可能只需要10分鐘但要想把它打磨成一個在生產(chǎn)環(huán)境中穩(wěn)定、高效運行的組件需要對這些細節(jié)有深入的理解和不斷的調(diào)試。希望這篇超過5000字的詳細拆解能幫你打下扎實的基礎避開我當年踩過的那些坑。記住動手試一遍遠比看十遍文章要有效。