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