做目標檢測的朋友應該都清楚YOLO系列在工業(yè)界的地位而YOLOv5在很長一段時間里是絕對的主流。不管是做安防、缺陷檢測還是自動駕駛感知很多項目最后都落在YOLOv5上。這篇文章我不打算復讀官方文檔而是從一個實際用過的角度把YOLOv5的安裝、訓練、調試和部署完整捋一遍包含我踩過的坑和注意事項希望能幫剛接觸的人少走彎路。YOLOv5這個項目用起來其實很簡單但簡單的前提是你得把環(huán)境、數據格式、訓練參數這幾塊搞明白。否則卡在安裝階段就夠你受的。我見過很多人裝了一天依賴最后發(fā)現是Python版本不對或者CUDA沒配好。這篇文章會覆蓋從環(huán)境準備到模型導出部署的全流程適合剛入門的同學也適合已經跑通過但想優(yōu)化訓練細節(jié)的人。1. 項目概覽與環(huán)境準備1.1 YOLOv5是什么解決什么問題YOLOv5是一種基于單階段檢測思路的目標檢測模型它的核心優(yōu)勢是速度快、精度高、部署方便。相比兩階段檢測器YOLOv5只需要一次前向就能同時輸出目標框和類別概率在保持較高精度的同時把推理速度拉到實時級別。對很多業(yè)務場景來說比如生產線上的零件計數、園區(qū)里的車輛行人檢測、工地的安全帽佩戴檢測YOLOv5可以說是第一選擇。它的另一個特點是工程化做得非常好。官方倉庫把訓練、驗證、推理、導出都封裝成了命令行工具幾乎不需要自己寫模型代碼。你只要準備好標注好的數據改一下配置文件就能訓練出一個可用模型。這一點是早期YOLO版本不具備的也是YOLOv5能在社區(qū)里廣泛流行的重要原因。1.2 環(huán)境要求與依賴分析先說結論YOLOv5對硬件的要求不算高但也不低。如果你只用CPU推理那基本是個電腦就能跑但訓練的話強烈建議有NVIDIA顯卡。顯存方面以默認的YOLOv5s模型為例輸入尺寸640x640batch size設為16在8GB顯存上能跑但很緊張。我建議至少12GB顯存如果用YOLOv5l或者更大的模型最好上24GB。操作系統(tǒng)方面Windows、Linux、macOS都可以但我個人推薦Ubuntu系統(tǒng)尤其是用Docker部署的時候。Windows也能跑只是有些編譯依賴需要額外裝比如pycocotools在Windows下要裝預編譯版本否則會編譯報錯。Python版本建議3.8到3.11太老或太新的版本容易出現兼容性問題。PyTorch建議使用1.12以上的穩(wěn)定版我自己用的比較多的是PyTorch 1.13和2.0系列配合CUDA 11.7或12.1整體很穩(wěn)。如果你裝了GPU版PyTorch還需要對應的NVIDIA驅動和CUDA runtime這些裝好后用nvidia-smi確認一下。1.3 獲取代碼與安裝依賴YOLOv5的安裝分三步拉代碼、建虛擬環(huán)境、裝依賴。我一般會先用Anaconda創(chuàng)建獨立的虛擬環(huán)境避免把系統(tǒng)環(huán)境搞亂。conda create -n yolov5 python3.9 conda activate yolov5然后是拉取官方倉庫代碼git clone https://github.com/ultralytics/yolov5 cd yolov5接下來安裝依賴。官方提供了一個requirements.txt你可以直接pip install -r requirements.txt但這里有個小坑默認的requirements.txt會把torch和torchvision也裝進去。如果你已經有可用的PyTorch比如已經在其他環(huán)境里裝好對應CUDA的版本建議把這兩行注釋掉只裝其他依賴。否則pip可能會重新裝一個CPU版或者不匹配的版本白白浪費下載時間。我自己習慣先手動裝PyTorch再裝其余依賴# 先裝PyTorch選擇匹配你CUDA的版本 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 再裝其他依賴 pip install -r requirements.txt裝完后跑一個簡單的檢測命令驗證環(huán)境python detect.py --weights yolov5s.pt --source data/images/bus.jpg如果沒有報錯并且在runs/detect/exp下生成了帶框的圖片說明安裝成功。1.4 驗證安裝以及常見環(huán)境坑第一次跑detect.py會自動下載yolov5s.pt權重如果網絡比較慢可以手動下載放到項目根目錄。另外國內網絡有時候訪問GitHub不穩(wěn)定建議提前配置好代理或者從鏡像站下載。這里不展開你自己想辦法。驗證過程中我最常遇到的問題是torch.cuda.is_available()返回False。遇到這種情況先別急著卸載重裝按順序排查第一NVIDIA驅動是否正常運行nvidia-smi看看能不能輸出第二PyTorch是否裝了CUDA版pip list | grep torch看看版本號里有沒有cu標記第三如果用的是conda環(huán)境確認自己激活的是哪個Python。還有一個小細節(jié)首次運行會下載yolov5s.pt大約14MB但如果你的網絡對下載域名有限制可能會卡很久。我建議下載后把權重文件放在項目根目錄同時確認一下文件的擴展名是.pt不要因為瀏覽器自動改名變成.pt.txt這種低級錯誤真有人遇到過。2. 核心概念與模型結構解讀2.1 從YOLOv5的模型結構看它的設計思路雖然我們只是用工具但了解模型結構能幫你在調參的時候明白每一步在做什么。YOLOv5整體分為三部分Backbone、Neck和Head。Backbone負責提取圖像特征YOLOv5用的是修改過的CSPDarknet簡單說就是通過跨階段部分連接讓梯度流動更高效在減少計算量的同時保持特征提取能力。Neck負責融合不同尺度的特征YOLOv5用的是PANet結構自頂向下和自底向上的路徑都能把語義信息和位置信息揉在一起。Head則輸出三個尺度的預測結果分別對應大目標、中目標和小目標。為什么要分三個尺度因為目標檢測任務里目標大小差異很大。如果只在一個尺度上做預測小目標很容易被下采樣之后的信息丟掉。YOLOv5通過不同步長的特征層讓模型既能檢測大目標也能捕捉小目標。理解了這一點你就知道為什么輸入尺寸不能隨便縮得太小否則小目標就沒了。2.2 模型配置文件的作用與選擇YOLOv5的模型定義不是直接寫在代碼里的而是通過YAML文件配置。在models/目錄下有yolov5s.yaml、yolov5m.yaml、yolov5l.yaml等文件對應不同體量的模型。后綴s、m、l、x分別代表small、medium、large、xlarge遞增的是網絡寬度和深度也就是通道數和骨干層數。為什么官方要提供這么多配置因為在不同場景下你對速度和精度的取舍不一樣。比如嵌入式設備上推理你可能會選yolov5s或者更輕的n模型如果是離線做高精度檢測對速度不敏感就可以上yolov5x。選擇的原則是先跑默認的yolov5s建立baseline再根據自己的設備算力和精度要求逐步嘗試更大的模型。這個YAML文件里幾個關鍵參數值得看一下nc: 80 depth_multiple: 0.33 width_multiple: 0.50 anchors: - [10,13, 16,30, 33,23] - [30,61, 62,45, 59,119] - [116,90, 156,198, 373,326]nc是類別數量一定要改成你自己的類別數。depth_multiple和width_multiple是縮放系數決定了模型的大小。anchors是預設的錨框如果你不想自己計算訓練時代碼會自動使用k-means重新算保持默認也行但改類別數的時候要注意錨框數量是否跟檢測層匹配。2.3 預訓練權重與遷移學習YOLOv5訓練時強烈建議使用預訓練模型。官方提供了COCO數據集上訓練好的權重文件比如yolov5s.pt、yolov5m.pt。這些權重在學習新任務時是很好的起點。因為你自己的數據集通常沒有COCO那么多類別直接用隨機初始化的權重去訓練收斂會很慢而且最終精度往往不如用預訓練權重微調。使用預訓練權重的原理很直觀網絡在COCO上已經學會了通用的邊緣、紋理、形狀等特征遷移到你的數據集時只需要微調高層參數去適配新的類別。這就像你請了一個在通用領域很有經驗的工程師他來做新項目上手速度肯定比一個什么經驗都沒有的新人快。在訓練命令里通過--weights yolov5s.pt指定預訓練權重即可。注意如果你的數據集類別數和COCO不一致代碼會自動處理最后一層輸出你不用手動改權重文件。官方實現里加載權重時會調整類別輸出層的維度。2.4 幾個你必須清楚的訓練參數YOLOv5的訓練參數很多但常用的核心參數就這幾個--epochs訓練輪數一般等于100到300取決于數據量和任務復雜度。--batch-size批大小越大顯存占用越高一般來說batch size越大梯度估計越準確但會受到顯存限制。--img輸入圖像尺寸默認640越大越能檢測小目標但速度越慢。--device指定GPU編號比如--device 0多卡用0,1。--data數據集配置文件路徑后面會詳細說。--hyp超參數配置默認是data/hyps/hyp.scratch-low.yaml里面包含學習率、動量、數據增強的各種設置。還要注意一個參數--cache它可以預先加載數據到內存加速訓練。如果內存夠大比如32GB以上加上這個參數能讓每個epoch的時間明顯縮短。但如果你內存不夠加了反而會因為換頁導致變慢甚至崩潰。3. 數據集準備與標注格式3.1 數據目錄結構規(guī)范YOLOv5使用的數據集目錄結構比較固定你需要按下面的方式組織your_dataset/ ├── images/ │ ├── train/ │ └── val/ └── labels/ ├── train/ └── val/其中images/train放訓練圖片images/val放驗證圖片labels目錄下放對應圖片的標注文件文件名要和圖片名保持一致只是擴展名是.txt。比如一張img001.jpg的圖片對應的標注文件就是labels/train/img001.txt。很多人習慣把數據集直接copy到YOLOv5項目里其實沒必要。你完全可以用絕對路徑或相對路徑指向外部數據集只要在數據配置文件里寫好就行。這樣項目的干凈度和靈活性都更高。3.2 YOLO標注格式詳解YOLO的標簽格式是每一行一個目標每行有五個數字class_id x_center y_center width height注意這里的x_center、y_center、width、height全部是相對于圖片寬高的歸一化值范圍在0到1之間。比如一張寬1000像素、高800像素的圖片某個目標的中心點落在(500, 400)寬為200高為160那么在標簽文件中這行數據是0 0.5 0.5 0.2 0.2這里的class_id從0開始計算對應你數據集yaml中類別列表里的順序。寫標注的時候很容易出錯的是歸一化計算很多人直接把像素坐標寫進去不歸一化或者除以錯誤的值導致模型怎么訓都不收斂。建議寫完標注后先用可視化工具檢查一遍。3.3 自定義數據集的yaml配置在訓練之前你需要創(chuàng)建一個數據配置文件內容大致如下# data.yaml train: /path/to/your_dataset/images/train val: /path/to/your_dataset/images/val nc: 2 names: [person, car]這里train和val指向圖片目錄nc是類別數量names是類別名稱列表。注意類別順序要跟標注文件中的class_id一致。官方代碼還支持把圖片路徑寫成txt文件列表的形式但我比較推薦直接寫目錄路徑簡單明了。配置好之后驗證一下數據路徑是否正確。可以寫個小腳本或者直接跑訓練前的一句話檢查。我通常會用下面這個命令看標注和圖片是否匹配python train.py --data data.yaml --weights yolov5s.pt --epochs 1 --img 640 --batch-size 2跑一個epoch如果沒有報錯再看log里的指標曲線基本就能確認數據沒問題。3.4 數據增強與標注檢查的注意事項YOLOv5內置了不少數據增強策略比如Mosaic、MixUp、隨機裁剪等。在訓練過程中這些增強策略會自動生效你不需要額外配置但要注意一點如果數據增強過強而你的數據集本身已經很小模型可能反而欠擬合或訓練不穩(wěn)定。官方默認的超參數文件是不同的增強檔位初學者直接使用hyp.scratch-low.yaml即可如果你對增強比較熟悉可以再嘗試hyp.scratch-med.yaml或者自定義。另外一個非常關鍵是檢查標注框的完整性。訓練前務必做一次可視化檢查把標注框畫在圖上看看有沒有錯位、漏標、類別標錯的問題。我這里有個簡單的方式用官方提供的一個小腳本思路讀取圖片和對應的txt用OpenCV畫矩形框。批量檢查幾百張圖片能幫你發(fā)現很多隱含問題。標注質量直接決定了模型上限這個環(huán)節(jié)省不得。4. 訓練自己的模型4.1 訓練命令與參數選擇一切就緒后就可以開始訓練了。一個典型的訓練命令是python train.py \ --weights yolov5s.pt \ --data data.yaml \ --epochs 100 \ --batch-size 16 \ --img 640 \ --device 0如果你想從頭訓練不推薦就把--weights換成--weights 。如果你想從某個中間狀態(tài)的權重繼續(xù)訓練可以通過--resume參數指定權重路徑。訓練過程會自動在runs/train/exp下生成日志和模型檢查點默認每10個epoch保存一次同時保存最佳模型best.pt和最后一個模型last.pt。剛開始訓練時建議先把--epochs設小一點比如50跑通整個流程確認沒有問題后再加大輪數。否則一次性設300輪跑了一天發(fā)現數據路徑有誤那就太心痛了。4.2 訓練過程監(jiān)控與指標解讀訓練過程中終端會實時打印P、R、mAP、box loss、obj loss等信息。這幾個指標怎么看PPrecision是查準率表示預測出的目標里有多少是正確目標。RRecall是查全率表示實際目標里有多少被檢測到了。mAP是綜合P和R的評估指標YOLOv5默認用mAP0.5和mAP0.5:0.95。box loss是邊界框損失的均值越低代表框得越準。obj loss是目標置信度損失越低代表分類和定位整體越可靠。訓練時觀察曲線一般前10個epoch loss會快速下降之后變緩。如果box_loss和obj_loss持續(xù)下降但很平緩說明模型還在學習如果loss反彈或者震蕩劇烈可能是學習率太高或batch size太小。mAP曲線在最后階段會趨于平穩(wěn)如果還沒有平穩(wěn)說明epoch數可能不夠。4.3 調優(yōu)技巧分享我自己在實際項目中總結過幾個調優(yōu)方向不一定適合所有場景但可以參考。第一學習率。官方默認學習率是0.01配合warm-up一般來說沒問題。但如果你發(fā)現loss前期下降太慢可以稍微調高到0.02試試如果震蕩降到0.005。調學習率時要把--hyp對應的yaml文件改一下比如修改lr0和lrf。第二輸入尺寸。在顯存允許的情況下把--img從640提高到768甚至896往往能顯著提高小目標檢測能力。代價是訓練時間變長。我當時在檢測小零件的時候把img從640改到768mAP漲了接近3個點。但要注意推理時的圖片尺寸最好和訓練尺寸保持一致不然會有精度損失。第三訓練輪數和早停。YOLOv5自帶早停機制patience默認100輪。如果你觀察到mAP連續(xù)很多輪沒有提升訓練會提前結束這樣省時間。第四類別不平衡。如果你的數據集中某些類別的樣本很少可以考慮調整每個類別在損失中的權重或者在采樣時做類別重加權。YOLOv5沒有直接提供這個參數需要修改代碼但可以在準備數據集時通過過采樣或者數據增強來緩解。4.4 中斷恢復與多卡訓練訓練途中因為電腦重啟或者顯存不夠被kill是再正常不過的事。這時候不要慌用--resume就能接上。比如python train.py --resume runs/train/exp/weights/last.pt注意恢復訓練時要保證數據和參數與之前一致代碼會自己讀取opt.yaml保存的配置。如果你手動改了參數可能會導致結果對不上。多卡訓練也很簡單python train.py --device 0,1,2,3 --batch-size 64這里batch size是總batch代碼會自動分配到各卡上。個人經驗多卡訓練時batch size可以適當調大因為全局梯度平均后相當于更大的batch有時能提升穩(wěn)定性。但要注意學習率也要相應調整可以參考線性縮放規(guī)則batch size翻一倍學習率也翻一倍。5. 模型測試與推理部署5.1 使用測試集評估模型效果訓練完成后要用測試集或者驗證集評估模型而不是只看訓練時的mAP。因為訓練時的mAP是在驗證集上算的可能存在過擬合風險。如果你有單獨的測試集可以這樣跑python val.py --weights runs/train/exp/weights/best.pt --data data.yaml --img 640val.py會輸出各類別的P、R、mAP以及一個混淆矩陣圖同時在runs/val/exp下保存預測結果圖。我一般重點關注難類別的mAP尤其是樣本少的類別如果這些類別的AP明顯偏低說明數據不夠或者特征不明顯需要補充數據。5.2 對圖片、視頻、攝像頭進行推理推理是部署前最常做的事。YOLOv5的detect.py支持多種輸入源例如python detect.py --weights runs/train/exp/weights/best.pt --source ./test_img.jpg python detect.py --weights runs/train/exp/weights/best.pt --source ./test_video.mp4 python detect.py --weights runs/train/exp/weights/best.pt --source 0最后一個0表示調用攝像頭。--source甚至可以傳入一個目錄會批量推理目錄下所有圖片。輸出結果保存在runs/detect/exp下。--conf參數可以調整置信度閾值默認0.25。如果你覺得誤檢太多可以調高到0.5如果漏檢多可以調低到0.1。推理速度方面在GPU上YOLOv5s處理640x640的圖片單張大約只要幾個毫秒到幾十毫秒具體看顯卡型號。CPU上則慢很多可能達到幾百毫秒。5.3 導出為ONNX和TensorRT訓練好的模型要部署到服務或者邊緣設備通常需要導出成中間格式。YOLOv5官方提供了export.py腳本支持多種導出格式python export.py --weights runs/train/exp/weights/best.pt --include onnx engine--include可以傳多個格式比如onnx、engine、torchscript、openvino等。導出ONNX前需要安裝onnx和onnxruntime導出TensorRT engine需要TensorRT庫。這里最大的坑是版本匹配尤其是TensorRT和PyTorch的算子兼容性。如果導出失敗優(yōu)先檢查CUDA、TensorRT、PyTorch三者版本是否匹配網上版本對應表很多對著表檢查一遍基本能解決。導出ONNX后你可以用ONNX Runtime跑推理速度比PyTorch快不少而且不依賴PyTorch環(huán)境。TensorRT又比ONNX Runtime進一步提速適合高端GPU部署。我實測過YOLOv5s在T4上用TensorRT推理單張640x640的延遲能降到5毫秒以內這個性能在很多實時場景已經非常能打了。5.4 部署到邊緣設備與Web服務把導出的engine文件拷到目標設備用TensorRT python API寫推理邏輯或者直接用官方提供的detect.py替換權重路徑也可以把它嵌入更輕量的推理框架。邊緣設備比如Jetson系列同樣是用TensorRT但要注意算力版本。做Web服務的話比較簡單的方式是直接用Flask或FastAPI包裝一個接口接收圖片調用ONNX Runtime推理返回坐標和類別。響應速度主要取決于推理時間和圖片解碼時間把圖片解碼也放在GPU上會更快。還有一個容易被忽略的地方輸入前要把圖片resize到模型輸入尺寸并且做相同的填充方式YOLOv5默認是letterbox也就是保持長寬比填充灰邊。推理代碼里一定要和訓練時的預處理保持一致否則精度會掉。6. 常見問題與排查技巧實錄6.1 安裝階段的問題安裝依賴時最經典的問題是pycocotools在Windows下編譯失敗。解決辦法是不要直接pip install pycocotools而是安裝pycocotools-windows或者先安裝Visual C Build Tools再重新編譯。還有個常見問題是torch和torchvision版本不匹配導致無法導入。這通常是因為分別安裝時版本號沒對應上建議用PyTorch官網的命令一次性裝好避免混裝。另外git clone速度慢甚至中斷可以改用鏡像地址或者直接在瀏覽器下載壓縮包解壓。這個不影響后續(xù)工作只要目錄結構完整就行。6.2 訓練時顯存不足顯存不足是新手最常碰到的攔路虎。報錯通常是CUDA out of memory。處理方法從輕到重有三種減小batch size、減小img尺寸、換更小的模型。比如把batch size從16降到8或者img從640降到480顯存占用立刻下降。如果這些還不夠就把模型從yolov5s換成yolov5n這是最輕量的版本。還有一個技巧是開啟梯度累積。YOLOv5代碼里沒有直接給這個參數但你可以通過--batch-size很小但訓練多步再更新來實現。不過最簡單的還是調低配置。我一般建議在跑通流程時用最小配置等驗證無誤后再逐步放大。6.3 訓練不收斂或精度差如果你發(fā)現loss始終不降先檢查數據標注是否正確這是最常見的原因。把訓練圖片和標注可視化出來看一遍很多問題立刻暴露。比如框坐標歸一化出錯、類別ID跟names對不上、圖片擴展名和標注文件不一致這些都會導致模型學不到規(guī)律。精度低還有可能是key數據太少。如果每個類別只有幾十張圖片數據增強再強也很難學好。我的經驗是每個類別至少幾百張并且要有不同角度、不同光照下的圖像。另外遷移學習時預訓練權重是否選對也很重要不要拿著yolov5x的權重去訓你只有幾百張圖的小數據集那樣容易過擬合反而不如山規(guī)模小一點的模型。最后一點確認訓練和驗證是否使用了同一個數據分布。有時候訓練集是白天圖像驗證集是夜間圖像效果當然好不了。盡量讓訓練集與驗證集分布一致或者通過數據增強模擬多種風格。6.4 推理結果不理想推理結果不理想分兩種情況。第一種是目標檢測出來了但框不準這種情況往往是模型本身精度不夠需要重新訓練或者提高輸入分辨率。第二種是漏檢或誤檢可以先調節(jié)置信度閾值。如果還不行再看是不是測試圖片跟訓練場景差異太大。比如訓練時用的是高空俯拍測試時用低角度仰拍模型沒見過這種視角自然表現不好。另外檢查預處理是否一致。我在實際項目中就遇到過訓練時用letterbox填充推理代碼里卻直接resize導致目標拉伸變形模型精度掉了很多。確保使用同樣的預處理函數這里我推薦直接復用YOLOv5倉庫里的letterbox函數。還有一個容易忽略的細節(jié)類別輸出順序。當你把模型導出成ONNX或TensorRT后得到的結果是按訓練時names的順序排列的。如果你在demo代碼里用另一套順序解析那結果全亂。所以導出前確認類別表部署端跟訓練端保持一致。個人經驗總結一路用下來我的體會是YOLOv5確實是工程落地利器很多細節(jié)官方已經幫你處理好了但真正決定項目成敗的還是數據質量和對訓練機制的理解。你在上面投入的每一分精力最終都會反映在模型精度上。最后分享一個我常用的排查思路每次跑新實驗前先用最小數據集、最小模型、最小epoch數驗證整條鏈路通的再逐步增加數據量和訓練規(guī)模。這樣能避免很多低級錯誤浪費大量時間。如果你準備開始做自己的目標檢測項目不妨先拿YOLOv5s配合公開數據集跑一遍流程把訓練、驗證、導出、推理全走通再替換成自己的數據集。這個過程走下來你基本就入門了。后續(xù)再根據硬件條件和需求探索模型剪枝、量化、知識蒸餾這些進階方向路會越走越寬。