1. 从零开始为什么YOLOv5依然是目标检测的“敲门砖”如果你刚接触计算机视觉或者想找一个能快速上手、效果又不错的项目来练手那YOLOv5绝对是一个绕不开的名字。我刚开始做目标检测项目时面对Faster R-CNN、SSD、YOLO系列这些名词也是一头雾水直到亲手把YOLOv5跑起来看着摄像头实时框出画面里的物体那种“通了”的感觉才真正到来。它不像一些学术前沿模型那样对硬件和理论要求极高也不像某些“玩具”模型那样功能孱弱。YOLOv5在易用性、速度和精度之间找到了一个非常棒的平衡点官方仓库维护积极社区生态丰富这使得它成为了无数开发者、学生和研究员的第一个“生产级”目标检测工具。尽管YOLOv8、YOLOv9等后续版本已经发布但YOLOv5的江湖地位依然稳固。原因很简单成熟、稳定、资料多。它的代码结构清晰从数据准备、模型训练到模型导出ONNX、TensorRT等的整个流水线都非常完善网上能找到的踩坑经验和解决方案也最多。对于学习目标检测的整个流程——包括环境配置、数据标注、模型训练、性能评估和部署——YOLOv5提供了一个近乎完美的“样板间”。你跟着走一遍就能把深度学习中数据、模型、训练、推理这几个核心环节串起来建立起直观的认识。所以这篇内容的目的不是复读官方文档而是结合我多次在不同平台从个人笔记本到服务器甚至到边缘设备部署YOLOv5的经验带你走通一条最顺畅的路径。我会重点告诉你在那些看似简单的git clone和pip install命令背后有哪些细节决定了成败以及当命令行报出一堆红色错误时你第一步应该检查哪里。2. 环境搭建避开依赖冲突的深坑万事开头难而深度学习的环境配置堪称“开头难”的典范。YOLOv5基于PyTorch这本身是好事因为PyTorch的安装已经比早年友好太多。但Python包管理的“祖传”问题——依赖冲突——依然是我们最大的敌人。你的机器上可能已经为了其他项目安装了不同版本的numpy、opencv-python或torch这些都可能让YOLov5的安装脚本运行失败。2.1 核心武器Conda虚拟环境我强烈建议无论你是新手还是老鸟都使用Conda来管理你的YOLOv5环境。这相当于为这个项目建立一个独立的、干净的“房间”里面的所有家具Python包都是为YOLOv5量身定制的不会和“客厅”系统环境或其他“房间”其他项目环境的家具打架。首先如果你还没有安装Miniconda或Anaconda去官网下载安装就好。之后打开你的终端Windows用Anaconda Prompt或PowerShellLinux/macOS用系统终端我们创建一个新的环境# 创建一个名为yolov5的Python环境指定Python版本为3.8。 # 选择3.8是因为它在PyTorch各版本中兼容性最广最不容易出问题。 conda create -n yolov5 python3.8 -y创建完成后激活这个环境conda activate yolov5你会看到命令行提示符前面变成了(yolov5)这表示你已经进入了这个专属的虚拟环境之后所有pip install的操作都只影响这个环境。2.2 PyTorch的精准安装CUDA版本是关键这是整个安装过程中最需要小心的一步。YOLOv5需要PyTorch而PyTorch能否调用GPU加速完全取决于你安装的PyTorch版本是否匹配你电脑上的CUDA版本。第一步确认你的CUDA版本。如果你有NVIDIA显卡并且希望使用GPU加速训练和推理速度能快几十倍打开终端输入nvidia-smi在输出的右上角你可以看到“CUDA Version: 11.4”之类的信息。记下这个主版本号比如11.4、11.6、12.1等。如果你的命令找不到或者你只有CPU那么后续就安装CPU版本的PyTorch。第二步去PyTorch官网获取安装命令。不要凭记忆输入pip install torch torchvision一定要访问 pytorch.org 。在网站上选择PyTorch Build: StableYour OS: 你的操作系统Package: 建议用pip如果你用Conda环境这里选Conda也可以但pip通常更直接Language: PythonCompute Platform: 根据你刚才查到的CUDA版本选择例如CUDA 11.6。如果只有CPU就选CPU。网站会生成一行类似下面的命令# 例如对于CUDA 11.6 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu116 # 对于CPU版本 pip install torch torchvision torchaudio在你的(yolov5)环境中运行这行命令。这个过程可能会比较慢因为要下载很大的文件。验证安装是否成功安装完成后在Python交互环境中验证import torch print(torch.__version__) # 输出PyTorch版本 print(torch.cuda.is_available()) # 输出True则表示GPU可用如果torch.cuda.is_available()返回False但你的显卡明明支持那99%是CUDA版本和PyTorch版本没对上需要回到PyTorch官网重新选择正确的Compute Platform。2.3 克隆仓库与安装剩余依赖PyTorch这个“地基”打稳了后面的就简单了。首先把YOLOv5的官方代码仓库克隆到本地git clone https://github.com/ultralytics/yolov5.git cd yolov5然后安装项目需要的其他依赖包。YOLOv5很贴心地准备了一个requirements.txt文件pip install -r requirements.txt注意运行这条命令时你可能会遇到各种网络超时ReadTimeoutError或者某个包安装失败的问题。这是非常正常的主要是因为一些依赖比如opencv-python的源在国外。解决方法有两个使用国内镜像源在命令后面加上-i参数指定镜像例如pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple手动安装失败包如果某几个包一直失败可以先跳过requirements.txt等主要包安装完后再单独用镜像源安装它们比如pip install opencv-python -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后你可以运行一个快速的验证脚本检查所有核心组件是否就绪python detect.py --weights yolov5s.pt --source data/images/bus.jpg这条命令会下载一个最小的预训练模型yolov5s.pt并对项目自带的一张公交车图片进行推理。如果一切正常你会在终端看到检测结果识别出了人、公交车等并且在项目根目录的runs/detect/exp文件夹下找到一张画了检测框的输出图片。看到这张图恭喜你环境搭建成功了3. 核心文件结构解析理解YOLOv5的工作流成功运行demo后先别急着训练自己的模型。花十分钟了解一下YOLOv5项目的目录结构能让你在后面操作时心里有张地图知道该去哪里找配置文件结果存在哪里。这比出了问题再满世界搜索要高效得多。打开你克隆下来的yolov5文件夹你会看到很多文件和文件夹。对于初学者重点关注以下几个data/: 这个文件夹是数据配置的核心。data/images/和data/videos/: 存放了一些用于测试的图片和视频。data/coco.yaml和data/coco128.yaml: 这是数据集配置文件的模板。当你训练自己的数据时就需要创建一个类似的.yaml文件告诉模型你的数据在哪里、有哪些类别。coco128是COCO数据集的一个小子集常用来做快速验证。data/hyps/: 里面存放了超参数配置文件如hyp.scratch-low.yaml。超参数控制着训练过程中的学习率、数据增强强度等新手可以先不用改用默认的就好。models/: 这个文件夹是模型定义的核心。models/yolov5s.yaml,models/yolov5m.yaml...: 这些是模型结构配置文件。它们定义了YOLOv5s小、YOLOv5m中、YOLOv5l大、YOLOv5x特大等不同尺寸模型的具体网络层结构。通常我们不需要修改这里。models/common.py,models/experimental.py: 里面定义了各种网络模块如Conv、Bottleneck等和一些实验性功能。runs/: 这是所有实验结果的输出目录非常重要每次你训练train.py或推理detect.py都会在这里生成一个新的子文件夹例如runs/train/exp2、runs/detect/exp3。在train/expX里你能找到训练过程的日志、损失曲线图、模型权重文件best.pt,last.pt以及模型在验证集上的性能指标如精度、召回率。在detect/expX里你能找到推理后生成的图片或视频。utils/: 工具函数集。里面包含了数据加载、指标计算、日志记录、画图等一大堆辅助函数。除非你要深度定制否则一般不用碰。核心入口脚本都在项目根目录train.py:训练脚本。你90%的时间都会和它打交道。detect.py:推理/检测脚本。用训练好的模型对图片、视频、摄像头流进行预测。val.py:验证脚本。在验证集上评估训练好的模型的性能。export.py:模型导出脚本。将PyTorch模型.pt导出为其他格式如ONNX、TensorRT、CoreML等用于移动端或边缘设备部署。理解了这个结构你就明白了YOLOv5的标准工作流在data/下配置你的数据 - 选择models/下的一个模型结构 - 运行train.py进行训练结果存到runs/train/- 用detect.py加载runs/train/exp/weights/best.pt进行测试 - 如果需要部署用export.py转换模型格式。4. 训练自己的数据集从图片标注到模型产出跑通官方demo只是第一步让YOLOv5认识你关心的物体比如车间里的零件、农田里的害虫、交通场景中的特定车辆才是真正的价值所在。这个过程可以分为三步准备数据、配置文件和启动训练。4.1 数据准备与标注YOLO格式详解YOLOv5要求的数据格式是一种简单的文本格式。假设你有一张图片image_001.jpg那么你需要一个同名的标签文件image_001.txt。这个.txt文件的内容可能如下0 0.5 0.5 0.3 0.4 1 0.2 0.8 0.15 0.15每一行代表图片中的一个物体标注包含5个数字用空格分隔class_id: 物体的类别索引从0开始。比如0代表“人”1代表“狗”。x_center: 物体边界框中心点的x坐标除以图片宽度后的归一化值范围0-1。y_center: 物体边界框中心点的y坐标除以图片高度后的归一化值范围0-1。width: 物体边界框的宽度除以图片宽度后的归一化值范围0-1。height: 物体边界框的高度除以图片高度后的归一化值范围0-1。举个例子一张1000x800的图片上有一个物体的中心点在(300, 400)宽高为200x150。那么它的YOLO格式标注就是x_center 300 / 1000 0.3y_center 400 / 800 0.5width 200 / 1000 0.2height 150 / 800 0.1875假设它的类别class_id是2那么这一行就是2 0.3 0.5 0.2 0.1875如何得到这些标注文件手动计算是不可能的。我们需要标注工具。LabelImg是一个经典的选择但这里我更推荐Roboflow或CVAT这类更现代的在线工具或者使用LabelStudio。它们都支持导出YOLO格式。标注时关键是要保证图片和对应的.txt文件放在正确的目录结构里。通常你的数据集文件夹应该像这样my_custom_dataset/ ├── images/ │ ├── train/ # 训练集图片 │ │ ├── img1.jpg │ │ └── ... │ └── val/ # 验证集图片 │ ├── img100.jpg │ └── ... └── labels/ ├── train/ # 训练集标签 (img1.txt, ...) └── val/ # 验证集标签 (img100.txt, ...)4.2 创建数据集配置文件数据准备好了接下来要创建一个YAML文件来告诉YOLOv5你的数据在哪里、叫什么名字。在data/目录下复制一份coco128.yaml改名为my_data.yaml然后编辑它# 数据集根目录路径可以是绝对路径也可以是相对于yolov5根目录的相对路径 path: ../my_custom_dataset # 训练集和验证集的图片目录相对于上面的path train: images/train val: images/val # 类别数量 nc: 2 # 改成你的类别数比如我这里有2类 # 类别名称列表顺序必须和标注文件中的class_id对应 names: [cat, dog] # 改成你的类别名这个文件是连接你的数据和训练脚本的桥梁非常重要。路径一定要写对否则训练时会报“No labels found”的错误。4.3 启动训练与参数解读万事俱备只欠训练。回到项目根目录运行训练命令。一个最基础的训练命令如下python train.py --img 640 --batch 16 --epochs 100 --data data/my_data.yaml --weights yolov5s.pt我们来拆解一下这几个关键参数--img 640: 输入图片会被自动缩放到640x640像素进行训练。这是YOLOv5的默认尺寸更大的尺寸如1280可能提升精度但会显著增加显存消耗和训练时间。--batch 16: 批次大小。一次迭代送入模型多少张图片。这个值越大训练越稳定、越快但对GPU显存要求越高。如果出现“CUDA out of memory”错误首先尝试减小--batch。--epochs 100: 训练轮数。整个训练集被完整遍历一次称为一个epoch。100是一个常见的起始值对于小数据集可能已经过拟合对于大数据集可能还不够。你需要观察验证集指标来决定是否提前停止或继续训练。--data data/my_data.yaml: 指定我们刚刚创建的数据集配置文件。--weights yolov5s.pt: 指定预训练权重。这里用的是yolov5s.pt意思是基于YOLOv5s这个小模型在其基础上用你的数据做微调Fine-tuning。这是训练自己数据集的标准做法能极大加快收敛速度并提升最终性能。如果你想从头开始训练不推荐除非数据量极大可以用--weights 。训练开始后终端会输出每一轮epoch的损失值和评估指标。同时在runs/train/exp每次训练会新建一个如exp2、exp3的文件夹里你会看到实时生成的各种图表results.png: 展示训练损失和验证损失的变化曲线。理想情况下两条曲线都应该稳步下降并最终趋于平缓。如果验证损失在训练后期开始上升说明模型过拟合了。confusion_matrix.png: 混淆矩阵直观展示模型在各个类别上的分类错误情况。val_batchX_labels.jpg和val_batchX_pred.jpg: 验证集批次的真实标签和模型预测结果对比可以直观看到模型检测得好不好。训练完成后最好的模型权重会保存在runs/train/exp/weights/best.pt。这个文件就是你训练成果的结晶。5. 模型推理与使用让模型真正“动”起来训练出模型只是第一步让它能对新的图片、视频甚至摄像头实时画面进行预测才是应用的终点。detect.py脚本就是干这个的它的功能非常强大。5.1 基础推理图片、视频与摄像头使用我们刚刚训练好的模型进行推理# 检测单张图片 python detect.py --weights runs/train/exp/weights/best.pt --source path/to/your/image.jpg # 检测一个文件夹下的所有图片 python detect.py --weights runs/train/exp/weights/best.pt --source path/to/image/folder/ # 检测视频文件 python detect.py --weights runs/train/exp/weights/best.pt --source path/to/video.mp4 # 使用电脑摄像头进行实时检测源为0 python detect.py --weights runs/train/exp/weights/best.pt --source 0检测结果默认会保存在runs/detect/exp同样会自动递增下。对于图片会生成画好检测框的新图片对于视频会生成一个新的带检测框的视频文件。5.2 常用推理参数详解detect.py提供了很多参数来定制推理行为这里介绍几个最实用的--conf-thres 0.25:置信度阈值。模型预测出的每个框都有一个置信度分数表示它有多确信这个框里是某个物体。低于这个阈值的预测框会被过滤掉。提高这个值如0.5可以让结果更“准”但可能会漏掉一些模糊的目标降低这个值则更“敏感”但可能会引入更多误检。你需要根据实际场景调整。--iou-thres 0.45:非极大值抑制NMS的IoU阈值。当多个预测框重叠严重都指向同一个物体时NMS会只保留其中最好的一个。这个参数控制“重叠多严重才算同一个物体”。值越小判定为同一物体的标准越严格留下的框越少。--max-det 300: 每张图片最多保留多少个检测框。防止在非常密集的场景下输出过多结果。--save-txt: 保存检测结果的标签文件YOLO格式。如果你需要用检测结果做进一步分析或作为新数据集的伪标签这个功能就很有用。--save-conf: 在保存的标签文件里同时保存每个检测框的置信度。--name custom_exp: 指定本次推理结果保存的文件夹名而不是默认的exp。一个综合性的命令例子python detect.py --weights best.pt --source test_video.mp4 --conf-thres 0.4 --iou-thres 0.5 --save-txt --save-conf --name road_detection5.3 集成到你的Python代码中除了命令行更多时候我们需要将YOLOv5的检测功能集成到自己的Python应用程序里。YOLOv5的开发者提供了非常简洁的API。在你的项目代码中可以这样调用import torch # 加载模型确保你的环境中已安装YOLOv5所需依赖 model torch.hub.load(ultralytics/yolov5, custom, pathruns/train/exp/weights/best.pt) # 或者使用本地克隆的仓库 # model torch.hub.load(./yolov5, custom, pathbest.pt, sourcelocal) # 使用本地路径 # 设置模型参数可选会覆盖模型本身的设置 model.conf 0.25 # 置信度阈值 model.iou 0.45 # NMS IoU阈值 # 进行推理 img path/to/image.jpg # 也可以是图片路径的list或numpy数组或PIL图像 results model(img) # 查看结果 results.print() # 在终端打印检测到的物体信息类别、坐标、置信度 results.show() # 显示带检测框的图片 results.save() # 保存图片到 runs/detect/exp 目录 # 以Pandas DataFrame格式获取详细结果便于程序化处理 predictions results.pandas().xyxy[0] # 获取第一张图片的预测结果DataFrame print(predictions) # 包含 columns: xmin, ymin, xmax, ymax, confidence, class, name这种方式非常灵活你可以轻松地将检测逻辑嵌入到Web服务、桌面应用或自动化脚本中。6. 模型导出与部署从PyTorch到生产环境训练好的.pt文件在PyTorch环境下使用很方便但如果想部署到移动端Android/iOS、边缘计算设备Jetson系列、树莓派或者希望获得极致的推理速度就需要将其转换为其他格式。export.py脚本就是负责这项工作的。6.1 导出为ONNX格式ONNX是一种开放的模型交换格式被很多推理引擎如OpenVINO, TensorRT, ONNX Runtime支持。导出ONNX是模型部署的第一步。python export.py --weights runs/train/exp/weights/best.pt --include onnx执行后你会在best.pt的同目录下得到一个best.onnx文件。有几个关键点需要注意动态维度默认导出的ONNX模型的输入尺寸是动态的-1这虽然灵活但某些推理引擎可能要求固定尺寸。你可以通过--dynamic参数来控制。如果想固定为训练时的尺寸可以加上--img 640假设你训练时用的是640。简化ONNX导出的ONNX可能包含一些冗余算子。可以使用onnx-simplifier工具进行优化pip install onnx-simplifier python -m onnxsim best.onnx best_sim.onnx验证导出导出后务必用ONNX Runtime或其他工具加载一下确保模型结构正确没有导出错误。6.2 导出为TensorRT引擎如果你在NVIDIA的GPU上追求极限推理速度TensorRT是不二之选。YOLOv5的导出脚本也支持直接导出为TensorRT的.engine文件但这个过程通常需要先导出ONNX再用TensorRT的trtexec工具或Python API进行转换。更简单的方式是使用YOLOv5内置的TensorRT导出需要提前安装好TensorRTpython export.py --weights best.pt --include engine --device 0这个过程会在你的机器上针对特定的GPU--device 0指定第一块GPU进行优化生成一个高度定制化的、序列化后的.engine文件。这个文件只能在你导出时使用的同型号GPU上运行但速度最快。6.3 部署到边缘设备以Jetson Nano为例在资源受限的边缘设备上部署YOLOv5核心思路是在算力强的机器上完成模型训练和格式转换如转为TensorRT再将转换好的模型和精简的推理代码部署到边缘设备。对于Jetson Nano步骤通常是在x86电脑上训练好YOLOv5模型并导出为TensorRT引擎.engine文件或ONNX格式。将模型文件拷贝到Jetson Nano。在Jetson Nano上搭建一个轻量级的Python环境主要安装PyTorch或TensorRT的Python包、OpenCV等。编写或使用一个只包含前向推理加载模型、预处理图像、运行模型、后处理结果的脚本移除所有训练相关的、庞大的依赖。使用这个脚本在Jetson Nano上运行模型。由于Jetson Nano的ARM架构和有限的存储空间直接在上面用pip install -r requirements.txt安装全部依赖可能会遇到很多编译问题。一个更稳妥的方法是使用NVIDIA官方为Jetson提供的PyTorch轮子whl文件进行安装并只安装必要的包。7. 实战避坑指南与性能调优纸上得来终觉浅绝知此事要躬行。下面这些经验都是我在多次部署YOLOv5时踩过的坑希望能帮你节省大量时间。7.1 安装与依赖常见问题ERROR: Could not find a version that satisfies the requirement torch1.7.0这是最典型的问题。请严格按照前文所述先去PyTorch官网获取安装命令。不要用pip install torch。确保你的Python版本建议3.8、CUDA版本与PyTorch命令匹配。ImportError: libGL.so.1: cannot open shared object file(Linux)这是OpenCV的依赖问题。在Ubuntu/Debian上运行sudo apt update sudo apt install libgl1-mesa-glx即可解决。“No module named ‘cv2‘或“No module named ‘PIL‘虽然requirements.txt包含了opencv-python和Pillow但可能因为网络问题安装失败。手动用国内镜像源安装pip install opencv-python pillow -i https://pypi.tuna.tsinghua.edu.cn/simple。训练时出现“CUDA out of memory”这是显存不足。立即降低--batch-size参数如从16降到8、4、2。如果降到1还不够可以考虑使用更小的模型从yolov5m.pt换到yolov5s.pt。减小输入图像尺寸--img如从640降到320。使用梯度累积--accumulate参数模拟更大的批次大小。7.2 训练过程调优与监控损失曲线不下降或震荡剧烈学习率太大这是最常见原因。YOLOv5使用自适应学习率调度但初始学习率--lr0可能不适合你的数据。尝试将其减小一个数量级例如从0.01改为0.001。数据有问题检查你的标注是否正确。可以用train.py自带的可视化功能查看一下数据加载是否正确python train.py --data my_data.yaml --weights yolov5s.pt --epochs 1 --img 640只跑一个epoch它会显示一批训练数据看看框的位置对不对。批次大小太小如果--batch-size只能设为1或2梯度更新会非常不稳定。尝试使用梯度累积例如--accumulate 4它会让每4个批次才更新一次权重相当于模拟批次大小为4的效果。过拟合训练损失很低验证损失很高数据太少这是根本原因。目标检测需要大量数据每个类别至少要有几百张样本。考虑数据增强或收集更多数据。训练轮数太多减少--epochs或使用早停Early Stopping。YOLOv5本身有模型保存策略保存验证集上表现最好的best.pt所以通常直接使用best.pt即可它对应的是验证集性能最好的时刻而非最后一轮。减弱数据增强YOLOv5默认使用了较强的数据增强在data/hyps/hyp.scratch-low.yaml中配置。对于小数据集过强的增强可能有害。你可以尝试修改超参数文件减小hsv_h,hsv_s,hsv_v色彩抖动和degrees旋转等增强参数的值。如何选择预训练权重和模型尺寸--weights yolov5s.pt模型小速度快精度较低。适合移动端、边缘设备或对实时性要求极高的场景。--weights yolov5m.pt平衡之选。在速度和精度间取得较好平衡是许多实际项目的起点。--weights yolov5l.pt或yolov5x.pt模型大速度慢精度高。适合对精度要求极高且拥有强大GPU服务器的场景。通用建议从yolov5m.pt开始。如果速度不达标换s如果精度不达标换l或x。7.3 推理速度优化当你把模型部署到实际应用中时帧率FPS可能是个关键指标。使用半精度FP16推理现代GPU如Volta架构及以后的NVIDIA GPU对半精度浮点数float16有很好的支持能显著提升速度并减少显存占用。在detect.py或你自己的推理脚本中可以在加载模型后添加model.half() # 将模型转换为半精度注意输入数据也需要转换为半精度img img.half()。使用TensorRT导出时也可以直接指定精度为FP16。调整推理尺寸训练时我们用--img 640但推理时不一定非要这个尺寸。通过detect.py的--imgsz参数可以指定不同的推理尺寸。较小的尺寸如320会更快但可能损失精度较大的尺寸如1280更慢但更准。你需要根据场景在速度和精度间做权衡。启用TensorRT如前所述将模型转换为TensorRT引擎.engine是获得终极加速的最有效手段在Jetson等边缘设备上效果尤为明显。最后模型训练和调优是一个需要耐心和反复实验的过程。不要指望一次训练就能得到完美结果。多关注runs/train/exp目录下的图表它们是你了解模型状态最直观的窗口。根据损失曲线和验证指标有方向地调整超参数、检查数据质量你的模型才会越来越“聪明”。