YOLOv5目标检测实战：从环境配置、模型训练到部署导出全流程

只要你在做跟计算机视觉、图像识别相关的事情，大概率绕不开一个名字：YOLOv5。这是一个目标检测框架，核心作用就是让程序告诉你“画面里有什么东西、分别出现在什么位置”，常用于工业质检、安防监控、交通识别、医学影像辅助判断以及各类竞赛Demo。很多人第一次接触它都是被“安装”劝退的，其实YOLOv5本身的安装并不难，难的是你在装的过程里踩到的那一堆版本坑：CUDA对不上、PyTorch装错、依赖冲突、权重下载卡死。这篇记录我按自己多年实操的路径，把从环境准备、快速推理、数据集训练到模型导出的完整流程从头到尾捋一遍，一方面帮你少走弯路，另一方面也把那些“文档里不会写”的坑一并讲清楚。适合刚入门目标检测的开发者、需要快速复现实验的学生，以及准备把模型部署到实际业务里的工程人员。

1. YOLOv5是什么，安装之前先想清楚这几件事

1.1 YOLO系列是怎么走到今天的

YOLO这个名字取自“You Only Look Once”，意思是目标检测只用看一次。早期的检测算法往往要分两步走：先产生候选区域，再对区域做分类，速度慢、流程繁琐。YOLO把检测当成一个回归问题，输入一张图，输出所有目标的类别和坐标，真正做到端到端。第一代YOLO出来的时候，思路很惊艳，但精度和召回都不太行，小目标尤其差。到YOLOv3的时候，引入了多尺度预测和特征金字塔这些结构，检测效果已经很能打，很多项目开始把它当基线用。YOLOv4则是在工程调优上做了大量工作，引入了数据增强、跨阶段局部连接等一系列技巧，把速度和精度又推了一截。

YOLOv5严格来说不是一个纯学术论文驱动的版本，它更偏向工程化实现。它在YOLOv4思路的基础上，把整个训练、推理、部署流程做得极其顺手：源码组织清晰、配置方式简单、预训练权重丰富、导出ONNX和TensorRT也几乎一条命令搞定。这也解释了为什么那么多人选它，而不是选那个“论文指标更高”的版本。你要搞懂的是，YOLOv5不只是一个模型结构，它是一整套目标检测工具箱，里面的模型定义、训练策略、数据增强、推理脚本都是配套好的。

1.2 v5和后续的新版本到底怎么选

每次我写YOLOv5教程，都有人问“官方后面都出YOLOv8了，还学v5有必要吗”。这个问题得分场景看。YOLOv5最大的优势是稳定、资料多、坑基本都被前人踩平了，社区里随便一搜就是现成方案。对于课程设计、竞赛、快速原型验证、中小型项目落地，v5完全够用，而且它的代码结构清晰，很适合用来理解目标检测的训练全流程。后续的v8等版本在结构设计上做了不少更新，训练策略也更现代，但依然保留了YOLO“简单好用”的内核，你如果已经吃透了v5，再切到新版本几乎是无痛迁移。

我给的建议很简单：如果你是第一次接触目标检测，或者急着把模型跑起来交差，直接学YOLOv5；如果你是在做长期项目、准备从零搭一套生产级检测系统，可以先从v5练手，再去看新版本的改进点。版本本身不是重点，检测任务的完整链路才是重点。

1.3 装之前需要建立的基本概念

在正式安装前，有几个名词你要先建立概念，不至于后面看到报错就懵。

• 模型权重（weights）：你可以理解成是模型训练好的“经验记忆”，YOLOv5提供按尺寸分档的预训练权重，下载后直接拿来推理，不用自己从头训练。
• PyTorch：跑YOLOv5的底层深度学习框架，负责张量计算和自动求导，绝大多数安装问题都出在它和CUDA的匹配上。
• CUDA与cuDNN：NVIDIA显卡的并行计算平台和深度神经网络加速库，用来让GPU真正跑起来，没有它，PyTorch就只能用CPU慢慢算。
• 数据集和标签：YOLOv5训练时，每张训练图片都会配一个同名的txt文件，里面写了图中每个目标的位置和类别，这就是YOLO格式的标签。

这几个概念贯穿安装、推理、训练、导出全程。先把它们的关系搞顺，再动手装，效率会高得多。

2. 环境准备与安装：这一步能排掉80%的坑

2.1 先看显卡，把驱动、CUDA和PyTorch的版本关系摸清

我遇到过太多人，一上来就装最新版PyTorch，然后跑YOLOv5报错“CUDA driver version is insufficient”，其实问题就出在版本不匹配。这里有个逻辑链：显卡驱动决定你能用多高版本的CUDA，CUDA决定PyTorch能不能调用GPU。你先在命令行执行 nvidia-smi，看右上角的CUDA Version，比如显示12.3，这说明你的显卡驱动最高支持到CUDA 12.3，你可以安装任意不高于这个版本的CUDA工具包，但实际很多场景下，你不一定需要单独装CUDA Toolkit，因为PyTorch会自带一套它需要的CUDA运行时。

我的日常做法是：先确定PyTorch版本，再让CUDA跟着PyTorch走。比如PyTorch官网提供了cu118、cu121等不同CUDA版本的安装命令，你只需要按自己机器的驱动选一个即可。原则很简单：驱动支持的版本，不能低于PyTorch所对应CUDA版本。大多数近几年的显卡，驱动都支持CUDA 11.8以上，所以我一般推荐直接用 cu118 版本，兼容性最好。

如果你没有NVIDIA显卡，也没关系。YOLOv5支持纯CPU推理，只是训练会比较慢。像我以前在没GPU的笔记本上试过，用yolov5s推理一张图片大概需要几百毫秒，做验证和Debug完全能接受，只是别指望它跑实时视频流。

2.2 用conda创建一个干净的环境，别祸害系统Python

我强烈建议不要直接在系统Python里装YOLOv5依赖，尤其是你机器上还跑着其他项目的时候。深度学习框架之间的版本冲突非常折磨人，明明上一个项目还能跑，装完新的东西再回去就报错了。用conda隔离环境是最省心的方案。安装Anaconda或Miniconda之后，执行：

conda create -n yolov5 python=3.9 -y conda activate yolov5

Python版本我通常选3.9或3.10，这两个版本对YOLOv5的兼容性很好，Python 3.12之前有不少依赖还没完全跟上，容易出幺蛾子。创建完之后，后续所有安装都在这个环境里操作。出了任何问题，直接删掉环境重建就行，完全不影响宿主机，这对反复折腾的人来说是刚需。

2.3 安装PyTorch，CPU版还是GPU版一次说清

激活环境之后，下一步是安装PyTorch。千万别直接 pip install torch 完事，这样默认装的版本不一定带CUDA支持。正确做法是打开PyTorch官网的安装页面，选好你的系统、包管理器、CUDA版本，它会生成对应的安装命令。

一个典型命令长这样：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

如果你没有GPU，就选CPU版本，安装命令会更简单。装完以后一定做一次验证，确保PyTorch真能调用显卡：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

如果输出 True，说明GPU环境已经通了。这一步是整个安装流程成败的关键，很多人后面训练半天发现用的是CPU，白白浪费时间。我在实际项目中，每次装完环境都会先执行这一句，把这个变成肌肉记忆。

2.4 拉取YOLOv5源码并安装依赖

环境好了，接下来就是克隆YOLOv5官方仓库。直接在命令行执行：

git clone [YOLOv5官方仓库地址] cd yolov5 pip install -r requirements.txt

官方仓库地址去项目主页复制即可。requirements.txt里面包含了运行YOLOv5需要的全部Python包：torch、torchvision、opencv-python、matplotlib、numpy、seaborn、pandas等。这里有两个非常常见的问题要注意。

第一，opencv-python不要装太新的版本，某些过新版本会要求更高版本的numpy，而YOLOv5代码对numpy版本又比较敏感，容易报一个与np.int或np.float相关的错误。我的建议是如果遇到兼容性问题，就把numpy固定到1.23.x左右，再重装opencv-python，基本能解决。第二，不要额外安装不必要的包，YOLOv5装依赖已经是按需安装，你多装的大概率不会用到，反而增加冲突概率。装完依赖后，再验证一下：

python -c "import cv2, torch; print(cv2.__version__); print(torch.__version__)"

如果没有报错并且能看到版本号，环境就绪，可以进入下一步了。

3. 五分钟跑通第一张图：用预训练模型做推理

3.1 先准备权重文件，理解四个档位的选择

YOLOv5官方在COCO数据集上预训练了四档模型：yolov5s、yolov5m、yolov5l、yolov5x。数字越大，模型参数越多，精度更高，但推理速度更慢。初学者用yolov5s就够了，它体积小，推理快，能跑通流程是你当下的主要目标。

权重文件不需要手动放置，你在执行检测命令时，YOLOv5会自动从官方下载对应权重。但如果网络环境不好，下载容易卡住，我建议你提前把权重文件下载好，放到项目根目录下的 weights 文件夹里（没有就自己创建），这样后面再执行检测或训练就不会因为网络问题中断。权重文件不大，yolov5s.pt大概十几MB，其他几个档位会大一些，但整体都还在可接受范围。

3.2 第一条检测命令，搞清楚这几个核心参数

在源码目录下执行：

python detect.py --weights yolov5s.pt --source data/images/bus.jpg

这条命令会加载YOLOv5s权重，去检测官方示例图片中的公交车和行人，检测结果输出到 runs/detect/exp 目录下。第一次跑出来的那张标注图片，就是你入门目标检测的里程碑。

你后面所有检测操作，基本都是在给这条命令换参数。最常改的七个参数我给你列一下：

• --weights：指定权重文件路径，换成自己训练的best.pt就能检测自定义目标。
• --source：检测来源，可以是图片、视频文件、文件夹路径，填0表示调用摄像头。
• --conf-thres：置信度阈值，默认0.25，只有置信度高于该值的目标才会被显示，调低会漏出更多疑似目标，调高则更严格。
• --iou-thres：NMS交并比阈值，默认0.45，控制重叠框的合并策略，通常情况下不需要动。
• --max-det：单张图片最大检测目标数，默认1000，防止画面里目标过多导致输出爆炸。
• --device：指定运行设备，填0表示用第一块GPU，填cpu表示纯CPU推理。
• --project/--name：指定输出目录和子目录，默认在runs/detect下面按exp、exp2这样递增。

举个例子，我想检测视频文件并限制只输出行人，命令可以这样写：

python detect.py --weights yolov5s.pt --source traffic.mp4 --conf-thres 0.3 --classes 0 --project my_runs --name person_detect

COCO数据集里类别0就是person，--classes参数可以直接限定输出类别，这个功能在工业场景里特别实用，比如只关注车、只关注缺陷品，过滤掉无关目标能大幅减少误报干扰。

3.3 视频、摄像头和批量图片的检测

当你的 --source 换成视频文件路径时，YOLOv5会逐帧推理并合成带标注的输出视频。换成0时，会打开本机摄像头做实时检测。我建议第一次跑摄像头时先测一下设备编号，有些笔记本摄像头编号不是0而是1，直接填0打不开时，改成1或2试一下就好。

批量图片检测也很简单，--source 直接填一个文件夹路径，它会把文件夹内所有图片检测完并统一输出。这个功能在做数据集初筛、批量标注质量检查的时候特别好用。我经常把一批待质检图片丢进去跑一遍，输出框一标，哪些图有问题、哪里有问题一目了然。

4. 训练你自己的数据集：从标注到跑通全流程

4.1 数据标注与YOLO文件格式，新手最容易乱的地方

预训练模型只能检测COCO那80类目标，你想检测自己业务里的东西，比如产品缺陷、工地违规行为、特殊车辆，就必须用自己的数据集训练。数据标注是第一步，业内最常用的工具是LabelImg类的标注GUI，画框后直接导出YOLO格式。

YOLO格式的标签要记住一个关键点：它存的不是像素坐标，而是归一化后的比例值。每张图片对应一个同名txt文件，每一行代表一个目标，格式是：

class_id x_center y_center width height

所有坐标都除以了图片宽高，所以取值范围是0到1。举个例子，一张宽1000、高800的图片，某个目标的中心点像素坐标是(500, 400)，宽高是(200, 100)，那txt里存的就是：

0 0.5 0.5 0.2 0.125

标签文件必须和图片同名，只是扩展名不同，图片是JPG，标签就是同名的txt。目录结构一般这样组织：

datasets/ mydata/ images/ train/ val/ labels/ train/ val/

训练集和验证集大概按8:2或9:1划分，同一张图片的image和label要放在对应的train或val下，不能错位。这个目录结构非常关键，后面很多报错都是因为标签文件和图片不在对应位置。

4.2 写data yaml和模型配置，参数含义一条条讲透

YOLOv5训练前要准备两个配置文件，一个是数据集描述文件，一个是模型结构文件。数据集描述文件是一个yaml，内容类似：

path: datasets/mydata train: images/train val: images/val nc: 2 names: ['cat', 'dog']

path是指数据集根目录，train和val填的是相对path的图片文件夹路径，nc是类别总数，names是类别名称列表，顺序必须和标注时的class_id一一对应。如果names顺序写错，训练出来的模型预测结果就全乱了，这是个非常隐蔽的坑。

模型结构文件用的是源码里的yolov5s.yaml，正常情况下你不需要改它的结构，但要注意里面的nc字段。如果你用的是预训练权重做迁移学习，训练时以下一条命令为准，命令行里传的data文件的nc会覆盖模型yaml里的nc，所以很多教程说只改data yaml就行。但如果你是直接从零训练，最好把模型yaml里的nc也改成自己的类别数，避免某些环节读到错误参数。

4.3 启动训练，学会看懂训练日志

数据准备好了，下一步就是训练。我先给你一个最稳妥的起步命令：

python train.py --data mydata.yaml --weights yolov5s.pt --batch-size 16 --epochs 100 --img 640 --device 0

--weights 填yolov5s.pt表示在预训练权重基础上继续训练，这叫迁移学习，能大幅缩短训练时间、提高收敛精度。--batch-size根据你显存来定，8GB显存用yolov5s和640分辨率，16是个安全值，显存不足就减到8或4。--epochs新手可以先跑50轮看效果，不用一上来就追求几百轮。

训练开始后，你会看到类似这样的日志输出：

Epoch gpu_mem box obj cls labels img_size 1/50 2.31G 0.036 0.018 0.001 7 640 P R mAP50 mAP50-95 0.142 0.115 0.103 0.051

这里面重点看P（精确率）、R（召回率）、mAP50（IOU阈值0.5时的平均精度）、mAP50-95（更严格的综合指标）。P高代表预测得准，R高代表漏得少，mAP是综合指标。训练完成后，模型会保存为best.pt和last.pt两个文件，best是验证集上效果最好的，last是最后一轮的，实际部署用best.pt。

我习惯在训练时把--project指定好，并在不同实验里用不同--name区分，这样每次训练的日志和权重都会单独保存，后期对比实验不会相互覆盖。如果你开启了可视化面板，也能在浏览器里看训练曲线，但实际判断收敛更多还是看日志里的P、R、mAP变化趋势。

4.4 训练翻车现场，这些问题我基本每轮项目都会遇到

第一个问题是显存不足，报错关键词是 OutOfMemoryError。解决办法优先级依次是：降低batch-size、降低--img分辨率、换更小的模型档位（比如从yolov5m降到yolov5s）。把batch从16减到8，显存占用直接减半，这是最立竿见影的操作。

第二个问题是标签没有加载，常见报错是 No labels found 或者训练日志里labels列一直为0。这种基本都是路径或格式问题，先检查标签txt是否和图片同名同目录，再打开txt文件确认内容是归一化坐标，出现负数或大于1的数值肯定不对。还有一种情况是标注工具导出的坐标没归一化，需要自己处理一下。

第三个问题是类别数不一致，报错时提示 nc mismatch。这是因为data yaml里的nc和模型结构文件里的nc不一致，或者names列表长度和nc对不上，仔细检查这两个文件的每个字段。

第四个问题是过拟合，典型特征是训练集P/R都接近1，但验证集mAP很低。这种情况往往是数据集太小、标注噪声大，或者训练轮数过多。我一般先检查标注框有没有明显偏移，再减少训练轮数，也可以加一些数据增强参数缓解。

5. 训练完之后：模型导出与轻量部署路线图

5.1 为什么要导出其他格式

很多人训练完模型，就停在best.pt这一步不走了。其实detect.py只能用来做验证和演示，真正要在生产环境跑，尤其在边缘设备上跑，你得把权重导出成更适配目标平台的格式。YOLOv5支持导出ONNX、TensorRT、OpenVINO、CoreML、TorchScript等多种格式，最重要的是ONNX，它是一种开放的模型交换格式，能被各种推理引擎加载，是你连接训练环境和部署环境的桥梁。

5.2 导出ONNX格式并用ONNX Runtime跑起来

导出命令非常简单：

python export.py --weights best.pt --include onnx

执行成功后目录下会多出一个best.onnx文件。你可能会看到一些兼容性警告，比如某个算子版本低，不用太担心，大部分部署框架都能处理。接下来用ONNX Runtime做推理验证，最简单的方式是这样：

import onnxruntime as ort import numpy as np import cv2 session = ort.InferenceSession("best.onnx") input_name = session.get_inputs()[0].name image = cv2.imread("test.jpg") image = cv2.resize(image, (640, 640)) image = image[:, :, ::-1].transpose(2, 0, 1)[None].astype(np.float32) / 255.0 outputs = session.run(None, {input_name: image})

ONNX Runtime推理出来的结果需要自己解析，这比直接调用YOLOv5源码要麻烦一点。但好处是不依赖PyTorch环境，部署机器上只需要安装体积很小的onnxruntime，特别适合服务端推理场景。我第一次把模型切到ONNX Runtime后，推理延迟降了不少，部署机器也不需要再装一整套深度学习框架。

5.3 嵌入式设备部署的大方向

如果你的目标是部署到Jetson这类边缘设备，可以走TensorRT路线，它能把模型进一步优化成引擎文件，推理速度能比ONNX再快好几倍。如果是Intel CPU平台，OpenVINO是推荐方向，优化效果同样明显。还有一个轻量级的ncnn，专门为移动端设计。这些工具的详细操作每个都能单独开一篇完整教程，我的建议是先掌握导出ONNX这一环，再按目标平台去学对应的部署框架。导出是共通的，部署框架各有各的路数，先有可交付的模型文件，再研究怎么把它跑得最快。

6. 安装使用高频报错排查速查表

我在多个环境、多台机器上装过YOLOv5，这里把新手最常遇到的报错整理成一张速查表，基本覆盖了八成使用场景，遇到问题先来这里对照一下。

• ModuleNotFoundError: No module named 'torch'：当前conda环境没装PyTorch，或没有激活正确环境。执行conda activate yolov5再检查一遍安装步骤。
• AttributeError: 'Upsample' object has no attribute 'recompute_scale_factor'：PyTorch版本和YOLOv5不兼容，常见于PyTorch版本偏新或偏旧。解决办法是把PyTorch装回2.x早期或1.13版本。
• RuntimeError: CUDA out of memory：显存不足。降低batch-size或imgsize，或换更小的模型档位。
• Downloading yolov5s.pt 卡住不动：网络问题导致权重下载失败。手动下载权重放到weights目录下，再重跑命令。
• No labels found in ...：标签文件缺失或路径不对。检查图片和标签文件是否同名、是否都在正确目录、txt内容是否为空。
• ValueError: Invalid classes ...：data yaml里names列表与标注的类别索引对不上，检查names顺序。
• ImportError: numpy.core.multiarray failed to import：numpy版本与opencv-python不兼容。卸载numpy后安装1.23.x版本，重新装opencv-python。
• 摄像头打开一片黑或报错：--source 0改1或2，或者检查系统摄像头权限是否开启。
• 预测结果全是一个框、框住整张图：置信度阈值太低或模型没训练好，先调高conf-thres，再检查训练数据和参数。
• 训练时loss不下降：学习率或数据集有问题，先用coco128小数据集验证环境是否正常。

这些排查经验里，我想再多说一句：遇到报错先读最后三行，别从第一行开始看。Python报错的核心原因通常在末尾，前面几百行都是调用栈。把末尾的异常类型和提示读明白，再对照上面的表，大部分问题五分钟内能定位。

这套流程我前后在十多台不同配置的机器上跑过，最大的体会是：版本对齐比命令本身更重要。只要PyTorch版本、numpy版本和环境隔离做对了，YOLOv5几乎可以做到克隆源码加装完依赖就能直接跑。至于训练自己的数据集，我更建议你第一条训练命令先别上自己的真实数据，先跑一遍官方自带的coco128小数据集，把流程走通、日志看懂，再换自己的数据和类别。因为路径问题、标签格式问题、参数配置问题，只有在真跑起来之后才会暴露出来，先用小数据集做冒烟测试，代价最小。最后记住一点：目标检测是实操性极强的活计，看一百篇教程不如自己完整跑通一遍，从安装到推理再到训练，能坚持走完这一轮，你基本就入门了。