直接开始写。1. 环境准备装 YOLOv5 之前先把这几件事搞清楚很多人拿到 YOLOv5 教程就开始复制粘贴git clone命令结果装到一半报错才回头一个个排查环境问题。YOLOv5 是个看似简单、实则对环境干净程度要求不低的项目我见过太多新手卡在环境上真正把时间浪费在“安装”而不是“使用”上。所以这篇教程我从环境讲起把最容易被忽略的细节一次说透。先说结论YOLOv5 支持 Python 3.7-3.11官方推荐 PyTorch 1.7 以上版本。但“支持”和“能跑得舒服”是两回事我个人长期用的组合是 Python 3.8 或 3.10 PyTorch 1.10/1.13/2.0这个区间最稳。Python 版本太新比如 3.12、3.13反而容易踩坑因为一些老版本依赖库还没有对应的轮子编译起来会让人崩溃。1.1 Python 版本与虚拟环境为什么不建议直接装到系统环境第一步先确认你的 Python 环境和显卡情况。用 Anaconda 创建独立虚拟环境是 YOLOv5 安装中最值得养成的习惯。原因是 YOLOv5 的依赖项版本比较敏感比如numpy的版本会影响opencv的行为matplotlib版本太新会导致绘图报错。如果你把 YOLOv5 装到系统环境里后面跑其他项目时很容易出现“装 A 包卸 B 包”的恶性循环。创建虚拟环境的命令非常简单conda create -n yolov5 python3.10 conda activate yolov5这里我特意选了 Python 3.10因为它在 PyTorch 生态里兼容性最好既支持老代码也支持新库。如果你用的是 Python 3.8也没问题都是很稳的版本。1.2 GPU 与 CUDA能不能跑显卡决定了你的训练速度差多少倍接下来检查 GPU 环境。YOLOv5 最大优势之一就是训练门槛低但“低”指的是算法层面不是硬件层面。你至少要有一块像样的 NVIDIA 显卡建议显存 4GB 以上。没有独显也能跑但训练速度会惨不忍睹一个几百张图片的小数据集可能都要几小时。确认显卡驱动和 CUDA 是否可用的标准操作nvidia-smi如果命令提示找不到说明驱动没装好先去 NVIDIA 官网装对应驱动。如果显示正常你会看到驱动版本和 CUDA 版本信息。注意nvidia-smi显示的 CUDA 版本是驱动最高支持的版本不代表你一定需要安装对应版本的 CUDA ToolkitPyTorch 自带 CUDA 运行库你只需要合适的驱动。然后是选择 PyTorch 版本。这一点很多人搞混pip install torch默认安装的是 CPU 版本必须在 PyTorch 官网选择对应的 CUDA 版本命令安装。比如pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118这里的cu118对应 CUDA 11.8cu121对应 CUDA 12.1。选哪个取决于你的显卡驱动官方支持稳定版即可不用刻意追求最新。一个排查 GPU 是否生效的小技巧python -c import torch; print(torch.cuda.is_available())输出True说明 GPU 可用。输出False先检查 PyTorch 装的是不是 CPU 版本再看驱动版本够不够新。1.3 目录规划一次把工作区和数据集分开后面能省一半事最后是目录规划。我建议建一个干净的 YOLOv5 工作根目录结构类似下面这样project/ ├── datasets/ # 数据集 ├── yolo_v5/ # 项目代码 ├── runs/ # 训练输出 └── weights/ # 预训练权重为什么要把数据、代码、输出分开因为 YOLOv5 默认会把训练结果保存在runs/目录下数据集放在项目外能避免误删、避免 git 提交时把几千张图片带进去也方便多个项目复用同一份数据集。别嫌这一步啰嗦我见过太多人数据集和代码混在一个目录里最后git clean一执行数据全没了的惨案。2. 依赖安装pip 命令之外这些坑经常劝退新手环境搭好后正式进入安装环节。YOLOv5 官方仓库提供了requirements.txt这是最标准和省事的方式。但“pip install”命令就一行真正让人卡住的往往是网络、权重下载和某些依赖的版本暗坑。2.1 克隆仓库与依赖安装版本锁定的用意先克隆仓库再安装依赖git clone https://github.com/ultralytics/yolov5 cd yolov5 pip install -r requirements.txtrequirements.txt里的依赖项都带有版本号或版本范围这是官方在大量测试后锁定的组合。比如opencv-python4.1.2、matplotlib3.2.2这些并不是随便填的版本过低缺少函数版本过高可能出现 API 变更导致脚本报错。安装时尽量一次性装完不要手动一个个装否则容易出现版本冲突。这里要特别说一个经验如果你在中国大陆网络环境pip install下载大尺寸依赖包如 PyTorch很容易超时中断最好提前设置镜像源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple但注意下载 PyTorch 这种带 CUDA 运行库的包时镜像源不一定有对应版本PyTorch 官方源的稳定性更高。我的习惯是PyTorch 用官方源装其他依赖用镜像源装。2.2 第一次运行自动下载权重文件安装完依赖后很多人直接开始训练结果卡在权重下载这一步。YOLOv5 的模型权重文件托管在国外服务器首次运行时会自动下载网络差的话经常失败。解决办法是手动下载。YOLOv5 官方提供的权重文件包括yolov5s.pt轻量版、yolov5m.pt中等版、yolov5l.pt重量版、yolov5x.pt超大版文件大小从十几 MB 到 100 多 MB 不等。下载后将.pt文件放到项目根目录或你规划的weights/目录即可。一个常见疑问是这几个版本到底选哪个我做了一张表方便你快速决策模型版本参数大小约推理速度相对精度相对适用场景yolov5n1.9MB极快较低移动端/嵌入式yolov5s7.2MB快中等大多数常规场景yolov5m21MB中较高对精度有要求yolov5l47MB慢高离线分析yolov5x89MB很慢最高极致精度追求新手入门一律选yolov5s.pt它平衡了速度和精度显存需求也低跑通整个流程之后再按需换大模型。2.3 常见报错补充显卡驱动、numpy 版本与路径问题安装和使用过程中有几个高频报错我直接列出来你遇到就不用猜了。第一个报错AssertionError: CUDA unavailable, invalid device 0 requested。这是 PyTorch 认为你的环境没有 CUDA前面用torch.cuda.is_available()检查一下大概率是装错包了重装 GPU 版 PyTorch 即可。第二个报错numpy.ndarray size changed, may indicate binary incompatibility。这是典型的 numpy 版本和其他包不兼容通常是 numpy 升级后二进制接口变了降低版本即可pip install numpy1.23.5第三个报错FileNotFoundError: weights/yolov5s.pt。这不是代码问题是权重文件路径不对。检查你启动训练的命令是在哪个目录下执行的YOLOv5 相对路径依赖很强建议统一在yolov5/项目根目录下执行命令。我在实际使用中发现requirements.txt里的依赖一旦装好就不要再动不动pip install --upgrade某个包除非你明确知道自己在做什么。YOLOv5 这套代码对依赖版本很敏感无意间升级了某个库可能就让整个流程跑不通。3. 数据集准备训练前必须搞懂的 YOLO 格式核心逻辑安装只是热身数据集才是 YOLOv5 使用里最核心、也最容易被忽视的一环。很多教程在安装完之后直接让你用官方预训练权重跑图片检测这当然可以但如果你是要训练自己的模型就必须深刻理解 YOLO 格式的数据集结构。3.1 目录结构训练集、验证集怎么摆放才叫规范YOLOv5 推荐的数据集目录结构是这样datasets/ └── mydata/ ├── images/ │ ├── train/ # 训练图片 │ └── val/ # 验证图片 ├── labels/ │ ├── train/ # 训练标签 │ └── val/ # 验证标签 └── data.yaml # 数据配置文件图片和标签的文件名必须一一对应比如img_001.jpg对应img_001.txt。图片格式支持.jpg、.png、.bmp等常见格式但建议统一成.jpg因为 JPEG 压缩更稳定、读取更快。标签文件是.txt纯文本格式。训练集和验证集的比例没有固定标准但我的习惯是 8:2 或 9:1。注意验证集不能和训练集有重复图片否则验证结果没有参考意义。如果你没有现成的划分脚本用train_test_split或者直接按文件名哈希分都行关键是保证随机。3.2 标签格式每行代表一个目标五个数字缺一不可这是 YOLO 格式最核心的部分。每一个.txt标签文件里每一行对应一张图片中的一个目标格式为object-class x_center y_center width height中间四个坐标值全部是归一化后的结果取值在 0 到 1 之间。归一化的意思是x_center表示目标中心点的横坐标占图片宽度的比例y_center是纵坐标占图高的比例width、height同理。举个例子一张 1000x800 的图片里有一个目标其边界框左上角坐标为 (200, 150)右下角坐标为 (500, 650)。那么计算过程是x_center (200 500) / 2 / 1000 0.35 y_center (150 650) / 2 / 800 0.5 width (500 - 200) / 1000 0.3 height (650 - 150) / 800 0.625所以这一行就是0 0.35 0.5 0.3 0.625其中0代表类别 ID。我自己标注数据的时候一般直接用 LabelImg 或 X-AnyLabeling 这类工具。标注工具会自动生成 YOLO 格式的标签避免手算坐标。但无论用什么工具保存之前一定要确认导出格式是 YOLO而不是 VOC 或 COCO。3.3 data.yaml 配置文件把数据集的“说明书”写对数据集文件准备好之后在datasets/mydata/下新建data.yaml文件。这个文件就像一份说明书告诉 YOLOv5 数据在哪里、有几类、类别叫什么。内容如下train: datasets/mydata/images/train val: datasets/mydata/images/val nc: 2 names: [person, car]注意train和val指向的是图片文件夹路径不是标签路径。YOLOv5 会根据同名规则自动去找标签。这个路径是相对于你运行训练命令的目录而言的所以如果你在yolov5/根目录下执行训练命令datasets/要和它同级或者写成绝对路径。nc是类别数量names是类别名称列表。这里有个非常搞笑的坑名字列表的顺序一定要和标注时定义的类别 ID 一致。你在标注软件里把person定义为 0在 names 里就要把person放在第一位否则训练出来的模型会把你所有的标签张冠李戴。3.4 标注时容易犯的几个错误说到标注我把新手最常犯的错集中讲一下。第一个错误一个标注框里包含了太多背景。YOLO 要求标注框尽量贴合目标边缘框得太大模型会把背景特征学进去框得太小目标特征不完整两种情况都会影响检测精度。第二个错误类别不平衡。如果数据集里一类有两千张图另一类只有五十张图模型大概率会把少数类忽略掉。这种情况可以收集更多少数类样本或者用脚本做简单过采样。第三个错误图片里有目标但没标出来。这会产生“漏检”样本模型被隐性地告知“这里没有目标”后续极其容易误判。每次标完一批数据我建议用可视化脚本把标签画到图片上检查一遍YOLOv5 里可以直接用detect.py配合--save-txt反过来检查标注质量也可以用其它开源可视化工具。4. 开始训练参数、监控与结果解读一次跑通的基本功数据集准备好环境没问题就可以进入训练环节了。YOLOv5 的训练命令本身不复杂真正值得讲清楚的是参数的含义以及训练过程中应该看什么、怎么判断模型练得好不好。4.1 训练命令与核心参数解析最基础的训练命令python train.py --img 640 --batch 16 --epochs 100 --data datasets/mydata/data.yaml --weights yolov5s.pt每个参数我都拆开讲一下--img是训练时输入的图片尺寸。YOLOv5 会把所有训练图片统一缩放到这个尺寸默认是 640。它直接决定了模型的输入分辨率和显存占用一般用 640 起步如果你的目标是小物体可以试试 1280但显存需求会成倍增长。--batch是批大小。它表示一次输入多少张图片到 GPU 进行训练。批大小由显存决定显存 8GB 的话 16 比较稳妥显存 4GB 就降到 8 或更低。批大小不宜过小否则梯度更新太频繁收敛不稳定。--epochs是训练轮数。小数据集 100-300 轮足够大规模数据集可以 300-500。不是越多越好后面我会教你判断什么时候该停。--weights指预训练权重。用yolov5s.pt会自动下载并加载官方在 COCO 数据集上训练好的权重这叫做迁移学习。比从零训练收敛更快、精度更高。如果想从头训练改成--weights 即可。另一个很重要的参数是--cache。它表示把数据提前缓存到内存中省去每次迭代都从磁盘读图的 IO 时间训练速度能提升不少。显存够用的话建议加上python train.py --img 640 --batch 16 --epochs 100 --data datasets/mydata/data.yaml --weights yolov5s.pt --cache4.2 训练过程监控怎么判断模型在变好还是过拟合训练启动后终端会不断打印日志同时会在runs/train/exp目录下生成训练结果。你需要看三样东西loss 曲线、PR 曲线和验证集精度。loss 分为三部分box_loss边框回归损失、obj_loss目标置信度损失、cls_loss分类损失。训练初期 loss 会快速下降中后期下降变慢这很正常。真正需要注意的是 val loss也就是验证集上的损失。如果 train loss 一直降、val loss 反而上升说明模型开始过拟合了这时应该停掉训练或增加数据增强。训练结束后重点看results.png里的 PPrecision 精确率、RRecall 召回率、mAP平均精度均值。这里我给大家一个通俗解释精确率是“你检测出来的框里有多少是对的”召回率是“真实目标里你有多少找出来了”mAP 是两者的综合指标。对于绝大多数自定义场景mAP0.5 达到 0.9 以上就算非常好了。如果只有 0.5 左右先别急着调参一般先从数据下手检查标注对不对、样本够不够、是否类别失衡。4.3 断点续训与学习率调整训练是一件很耗时的事哪怕用 GPU几百张图片的几轮训练也可能要几个小时。YOLOv5 支持自动保存最新权重last.pt和最优权重best.pt。如果你中途断了不需要重新跑直接执行python train.py --img 640 --batch 16 --epochs 100 --data datasets/mydata/data.yaml --weights runs/train/exp/weights/last.pt这就是断点续训接着上次的进度继续。这是一个非常实用的功能我自己训练的时候基本都会提前规划好训练轮数但总会因为各种意外中断断点续训省下的时间非常可观。另外新手容易忽略的一个参数是--patience它表示如果验证集精度连续多少轮没有提升就提前终止训练。默认是 100意思是 100 轮没进步就自动停。这个机制很好用能帮你节省大量时间。实际使用中我一般设置成 30-50让它在精度上升乏力时及时止损。5. 推理检测从命令行到 Python 调用把模型用起来训练完模型总算进入“展示成果”的阶段了。YOLOv5 既提供了简单的命令行方式也提供了灵活的 Python 接口。这个环节我会两种都讲因为日常快速验证用命令行但真正嵌入项目时几乎都是写 Python 调用。5.1 命令行推理一行命令搞定图片和视频检测使用训练好的best.pt对图片进行检测python detect.py --weights runs/train/exp/weights/best.pt --source test_images/ --conf-thres 0.25--source可以是单张图片、图片文件夹、视频文件甚至可以是摄像头编号。比如用摄像头实时检测python detect.py --weights runs/train/exp/weights/best.pt --source 0--conf-thres是置信度阈值默认 0.25也就是说模型认为某个框有 25% 以上的概率是目标才会画出来。阈值调高框更少但更准调低框更多但误检也会变多。这个参数没有绝对标准实际部署时你需要根据自己的场景调一版比如宁可漏检不要误检就把阈值调到 0.4 甚至 0.5。运行结束后检测结果会保存在runs/detect/exp目录下图片上已经画好了边界框、类别标签和置信度。命令行方式能满足大部分预览需求但它的问题在于每次都要加载模型、解析参数、跑完整流程。如果你要在一个已有的业务系统里调用检测能力绝对不适合用命令行方式。5.2 Python 接口加载模型、推理与结果解析YOLOv5 官方直接支持通过 Python 方式加载模型非常简单import torch model torch.hub.load(ultralytics/yolov5, custom, pathruns/train/exp/weights/best.pt)这里path指向你自己的权重文件。加载之后就可以对图片进行推理img test_images/001.jpg results model(img)results对象包含很多好东西。我这里给你展示最常用的几个属性# 获取边界框坐标、置信度、类别ID boxes results.xyxy[0] # 每行: x1, y1, x2, y2, conf, class # 显示检测结果 results.show() # 保存检测结果 results.save(output/)如果你要在服务端部署绝对不建议再用model.show()这种带 GUI 的调用方式。更专业的做法是把检测结果转成结构化数据detections results.pandas().xyxy[0] for _, row in detections.iterrows(): x1, y1, x2, y2 int(row[xmin]), int(row[ymin]), int(row[xmax]), int(row[ymax]) conf row[confidence] cls_name row[name] print(f类别: {cls_name}, 置信度: {conf:.2f}, 坐标: ({x1},{y1})-({x2},{y2}))这一段代码基本就是你在实际业务中处理 YOLOv5 输出时的雏形。无论你接的是拍照检测、视频分析还是实时流处理前面加个读取帧/图片后面加个逻辑处理整个链路就通了。5.3 摄像头或视频流检测的显存注意点很多人兴致勃勃跑摄像头实时检测结果发现视频非常卡帧率只有个位数。这是因为业务逻辑没优化。YOLOv5 的默认推理方式是每帧调用一次完整前向传播而视频每秒钟有 20-30 帧对 GPU 的消耗非常大。简单的优化手段是跳帧检测不是每一帧都做检测而是每隔几帧检测一次比如每 3 帧检测一次。这个策略对大部分场景完全够用毕竟目标不会在 100 毫秒内凭空消失。另外检测前把输入图片缩放到更小的尺寸也能显著提速比如从 640 降到 416帧率能提升一半以上精度下降却不太明显。6. 模型导出从 PyTorch 到 ONNX部署前的最后一步模型训练好、验证好真正要落地到生产环境还需要做模型导出。YOLOv5 官方提供了一键导出功能支持导出为 ONNX、TorchScript、TensorRT 等格式。把这一步讲清楚是因为很多人在“跑通检测”之后卡在了部署模型在开发机上运行良好换一台机器换成其他框架就完全跑不起来了。6.1 ONNX 导出跨平台部署的标准动作ONNXOpen Neural Network Exchange是一种跨框架的模型中间表示格式可以理解成“模型界的通用语言”。导出 ONNX 的步骤如下python export.py --weights runs/train/exp/weights/best.pt --include onnx --img 640导出的文件叫best.onnx放在权重同目录下。之后你可以用 ONNX Runtime 加载它在完全不依赖 PyTorch 的环境下运行import onnxruntime as ort import numpy as np import cv2 sess ort.InferenceSession(best.onnx) input_name sess.get_inputs()[0].name img cv2.imread(test.jpg) img cv2.resize(img, (640, 640)) img img[:, :, ::-1].transpose(2, 0, 1) # BGR - RGB, HWC - CHW img np.ascontiguousarray(img, dtypenp.float32) / 255.0 img np.expand_dims(img, axis0) outputs sess.run(None, {input_name: img})ONNX 导出的最大价值在于部署灵活性你的模型现在可以被 C、Java、C# 等任意语言调用可以部署在云服务器也可以部署在边缘设备完全绕开了 Python 和 PyTorch 的依赖。6.2 导出时的常见问题动态尺寸和结果解析差异导出和使用 ONNX 时有两个容易踩的坑。第一个坑是输入尺寸固定问题。默认情况下导出时指定的--img 640会把模型的输入尺寸固定为 640x640。如果你需要用其他尺寸推理可以在导出时加上--dynamic让 ONNX 模型支持动态输入尺寸但要注意动态尺寸的推理速度通常会略慢一些。第二个坑是输出解析差异。PyTorch 推理时results.xyxy已经帮你把预测结果解析成了好理解的左上角右下角坐标。但 ONNX 模型的原始输出是一个高维数组需要你自己解析边界框、置信度和类别。这个过程涉及 NMS非极大值抑制比较复杂。我建议新手不要改动 YOLOv5 的推理仓库直接复用官方提供的models/experimental.py或者用辅助工具库处理可以少掉很多头发。6.3 TensorRT 导出极致推理速度的一条小路如果你的部署环境是 NVIDIA 的 GPU那 TensorRT 是绕不开的加速手段。它可以对模型做层融合和精度校准FP16/INT8推理速度通常能提升两到三倍。导出命令也很简单python export.py --weights runs/train/exp/weights/best.pt --include engine --half--half表示使用半精度 FP16推理速度更快显存占用更少。但要注意TensorRT 导出的.engine文件是与 GPU 型号强相关的在 A 卡上导出的引擎不一定能在 B 卡上运行换机器必须重新导出。7. 训练效果提升数据与超参数的几个实用调整思路安装、训练、检测、导出全流程已经跑通。最后我想分享一些我长期使用 YOLOv5 后总结的提效经验这些不是官方文档里会写的东西但确实能帮你少走弯路。7.1 数据质量比模型参数更重要如果把 YOLOv5 用的时间拉长到几个项目你会发现一个规律数据集质量决定了精度的上限模型参数只是逼近这个上限。同一个模型我用质量差的数据集训练到 mAP 0.6 后无论如何调参都上不去换成清洗过得当的数据后不做任何调整精度直接冲到 0.92。差距不在模型在数据。所以当精度不理想时第一反应不应该是网上找各种魔改模型而是回头检查数据标注框贴合度、误标漏标、类别平衡、场景多样性把这些做扎实之后再考虑参数优化。7.2 数据增强的克制使用YOLOv5 自带了相当丰富的数据增强策略比如随机翻转、缩放、拼接Mosaic等。理解这些增强策略之后有一个常见的错误是为了追求“更强的泛化性”人为把增强参数拉满结果训练出来的模型在验证集上表现极差。增强要适度。训练小数据集时建议保留默认增强策略即可不要做太多自定义改动。真实世界的项目场景优先保证验证集和测试集与部署环境尽量一致而不是指望数据增强能弥补数据分布差异。7.3 迁移学习里的“冻结训练”技巧如果项目里可用的标注数据很少比如几百张可以考虑先冻结主干网络、只训练检测头等 loss 稳定后再解冻全部层训练。YOLOv5 里可以直接通过--freeze参数指定冻结前多少层python train.py --img 640 --batch 16 --epochs 50 --data datasets/mydata/data.yaml --weights yolov5s.pt --freeze 10这种做法在数据量有限时能有效避免过拟合因为预训练主干网络已经学到过通用的视觉特征你只需要让它适配你当前任务的检测逻辑。等第一阶段训练完毕去掉--freeze参数再继续训练完整模型泛化效果通常比直接完整训练好不少。我最近一个项目就是用这个思路在只有 700 多张图片的情况下把一个小目标检测场景的 mAP 从 0.67 拉到了 0.85而且训练时间比从头完整训练还短。如果你的数据集不大这个技巧值得认真试试。8. 写在最后的一点体会YOLOv5 这个东西网上教程多如牛毛动不动号称“超详细”但大部分都停留在 command 复述层面。真正让你成长的是理解每一步操作背后的原因为什么用那个仓库、为什么数据集要这么放、为什么调那个参数以及精度不行时从哪下手排查。我在实际使用中还有一个习惯每次训练完都会在runs/train/目录外另存一份训练配置副本包括data.yaml、训练命令参数和best.pt的 mAP 指标。这样一个月后回头想调模型时不用靠记忆猜当时怎么训的直接翻记录就能完整复现。这个习惯看起来不起眼但对长期维护模型帮助极大。另外如果你打算把 YOLOv5 用到自己的业务里建议严格控制版本不要频繁升级项目仓库。它本身已经非常成熟不会因为新功能频繁变动而给你带来额外收益。用熟一个版本、吃透一套流程比天天追新版本更重要。这是我看过无数人折腾之后最想说的一句话。 
长河君 · 2026/10/20 4:04:59 · 阅读 1.2k YOLOv5从环境配置到模型部署：目标检测全流程实战指南
直接开始写。1. 环境准备装 YOLOv5 之前先把这几件事搞清楚很多人拿到 YOLOv5 教程就开始复制粘贴git clone命令结果装到一半报错才回头一个个排查环境问题。YOLOv5 是个看似简单、实则对环境干净程度要求不低的项目我见过太多新手卡在环境上真正把时间浪费在“安装”而不是“使用”上。所以这篇教程我从环境讲起把最容易被忽略的细节一次说透。先说结论YOLOv5 支持 Python 3.7-3.11官方推荐 PyTorch 1.7 以上版本。但“支持”和“能跑得舒服”是两回事我个人长期用的组合是 Python 3.8 或 3.10 PyTorch 1.10/1.13/2.0这个区间最稳。Python 版本太新比如 3.12、3.13反而容易踩坑因为一些老版本依赖库还没有对应的轮子编译起来会让人崩溃。1.1 Python 版本与虚拟环境为什么不建议直接装到系统环境第一步先确认你的 Python 环境和显卡情况。用 Anaconda 创建独立虚拟环境是 YOLOv5 安装中最值得养成的习惯。原因是 YOLOv5 的依赖项版本比较敏感比如numpy的版本会影响opencv的行为matplotlib版本太新会导致绘图报错。如果你把 YOLOv5 装到系统环境里后面跑其他项目时很容易出现“装 A 包卸 B 包”的恶性循环。创建虚拟环境的命令非常简单conda create -n yolov5 python3.10 conda activate yolov5这里我特意选了 Python 3.10因为它在 PyTorch 生态里兼容性最好既支持老代码也支持新库。如果你用的是 Python 3.8也没问题都是很稳的版本。1.2 GPU 与 CUDA能不能跑显卡决定了你的训练速度差多少倍接下来检查 GPU 环境。YOLOv5 最大优势之一就是训练门槛低但“低”指的是算法层面不是硬件层面。你至少要有一块像样的 NVIDIA 显卡建议显存 4GB 以上。没有独显也能跑但训练速度会惨不忍睹一个几百张图片的小数据集可能都要几小时。确认显卡驱动和 CUDA 是否可用的标准操作nvidia-smi如果命令提示找不到说明驱动没装好先去 NVIDIA 官网装对应驱动。如果显示正常你会看到驱动版本和 CUDA 版本信息。注意nvidia-smi显示的 CUDA 版本是驱动最高支持的版本不代表你一定需要安装对应版本的 CUDA ToolkitPyTorch 自带 CUDA 运行库你只需要合适的驱动。然后是选择 PyTorch 版本。这一点很多人搞混pip install torch默认安装的是 CPU 版本必须在 PyTorch 官网选择对应的 CUDA 版本命令安装。比如pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118这里的cu118对应 CUDA 11.8cu121对应 CUDA 12.1。选哪个取决于你的显卡驱动官方支持稳定版即可不用刻意追求最新。一个排查 GPU 是否生效的小技巧python -c import torch; print(torch.cuda.is_available())输出True说明 GPU 可用。输出False先检查 PyTorch 装的是不是 CPU 版本再看驱动版本够不够新。1.3 目录规划一次把工作区和数据集分开后面能省一半事最后是目录规划。我建议建一个干净的 YOLOv5 工作根目录结构类似下面这样project/ ├── datasets/ # 数据集 ├── yolo_v5/ # 项目代码 ├── runs/ # 训练输出 └── weights/ # 预训练权重为什么要把数据、代码、输出分开因为 YOLOv5 默认会把训练结果保存在runs/目录下数据集放在项目外能避免误删、避免 git 提交时把几千张图片带进去也方便多个项目复用同一份数据集。别嫌这一步啰嗦我见过太多人数据集和代码混在一个目录里最后git clean一执行数据全没了的惨案。2. 依赖安装pip 命令之外这些坑经常劝退新手环境搭好后正式进入安装环节。YOLOv5 官方仓库提供了requirements.txt这是最标准和省事的方式。但“pip install”命令就一行真正让人卡住的往往是网络、权重下载和某些依赖的版本暗坑。2.1 克隆仓库与依赖安装版本锁定的用意先克隆仓库再安装依赖git clone https://github.com/ultralytics/yolov5 cd yolov5 pip install -r requirements.txtrequirements.txt里的依赖项都带有版本号或版本范围这是官方在大量测试后锁定的组合。比如opencv-python4.1.2、matplotlib3.2.2这些并不是随便填的版本过低缺少函数版本过高可能出现 API 变更导致脚本报错。安装时尽量一次性装完不要手动一个个装否则容易出现版本冲突。这里要特别说一个经验如果你在中国大陆网络环境pip install下载大尺寸依赖包如 PyTorch很容易超时中断最好提前设置镜像源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple但注意下载 PyTorch 这种带 CUDA 运行库的包时镜像源不一定有对应版本PyTorch 官方源的稳定性更高。我的习惯是PyTorch 用官方源装其他依赖用镜像源装。2.2 第一次运行自动下载权重文件安装完依赖后很多人直接开始训练结果卡在权重下载这一步。YOLOv5 的模型权重文件托管在国外服务器首次运行时会自动下载网络差的话经常失败。解决办法是手动下载。YOLOv5 官方提供的权重文件包括yolov5s.pt轻量版、yolov5m.pt中等版、yolov5l.pt重量版、yolov5x.pt超大版文件大小从十几 MB 到 100 多 MB 不等。下载后将.pt文件放到项目根目录或你规划的weights/目录即可。一个常见疑问是这几个版本到底选哪个我做了一张表方便你快速决策模型版本参数大小约推理速度相对精度相对适用场景yolov5n1.9MB极快较低移动端/嵌入式yolov5s7.2MB快中等大多数常规场景yolov5m21MB中较高对精度有要求yolov5l47MB慢高离线分析yolov5x89MB很慢最高极致精度追求新手入门一律选yolov5s.pt它平衡了速度和精度显存需求也低跑通整个流程之后再按需换大模型。2.3 常见报错补充显卡驱动、numpy 版本与路径问题安装和使用过程中有几个高频报错我直接列出来你遇到就不用猜了。第一个报错AssertionError: CUDA unavailable, invalid device 0 requested。这是 PyTorch 认为你的环境没有 CUDA前面用torch.cuda.is_available()检查一下大概率是装错包了重装 GPU 版 PyTorch 即可。第二个报错numpy.ndarray size changed, may indicate binary incompatibility。这是典型的 numpy 版本和其他包不兼容通常是 numpy 升级后二进制接口变了降低版本即可pip install numpy1.23.5第三个报错FileNotFoundError: weights/yolov5s.pt。这不是代码问题是权重文件路径不对。检查你启动训练的命令是在哪个目录下执行的YOLOv5 相对路径依赖很强建议统一在yolov5/项目根目录下执行命令。我在实际使用中发现requirements.txt里的依赖一旦装好就不要再动不动pip install --upgrade某个包除非你明确知道自己在做什么。YOLOv5 这套代码对依赖版本很敏感无意间升级了某个库可能就让整个流程跑不通。3. 数据集准备训练前必须搞懂的 YOLO 格式核心逻辑安装只是热身数据集才是 YOLOv5 使用里最核心、也最容易被忽视的一环。很多教程在安装完之后直接让你用官方预训练权重跑图片检测这当然可以但如果你是要训练自己的模型就必须深刻理解 YOLO 格式的数据集结构。3.1 目录结构训练集、验证集怎么摆放才叫规范YOLOv5 推荐的数据集目录结构是这样datasets/ └── mydata/ ├── images/ │ ├── train/ # 训练图片 │ └── val/ # 验证图片 ├── labels/ │ ├── train/ # 训练标签 │ └── val/ # 验证标签 └── data.yaml # 数据配置文件图片和标签的文件名必须一一对应比如img_001.jpg对应img_001.txt。图片格式支持.jpg、.png、.bmp等常见格式但建议统一成.jpg因为 JPEG 压缩更稳定、读取更快。标签文件是.txt纯文本格式。训练集和验证集的比例没有固定标准但我的习惯是 8:2 或 9:1。注意验证集不能和训练集有重复图片否则验证结果没有参考意义。如果你没有现成的划分脚本用train_test_split或者直接按文件名哈希分都行关键是保证随机。3.2 标签格式每行代表一个目标五个数字缺一不可这是 YOLO 格式最核心的部分。每一个.txt标签文件里每一行对应一张图片中的一个目标格式为object-class x_center y_center width height中间四个坐标值全部是归一化后的结果取值在 0 到 1 之间。归一化的意思是x_center表示目标中心点的横坐标占图片宽度的比例y_center是纵坐标占图高的比例width、height同理。举个例子一张 1000x800 的图片里有一个目标其边界框左上角坐标为 (200, 150)右下角坐标为 (500, 650)。那么计算过程是x_center (200 500) / 2 / 1000 0.35 y_center (150 650) / 2 / 800 0.5 width (500 - 200) / 1000 0.3 height (650 - 150) / 800 0.625所以这一行就是0 0.35 0.5 0.3 0.625其中0代表类别 ID。我自己标注数据的时候一般直接用 LabelImg 或 X-AnyLabeling 这类工具。标注工具会自动生成 YOLO 格式的标签避免手算坐标。但无论用什么工具保存之前一定要确认导出格式是 YOLO而不是 VOC 或 COCO。3.3 data.yaml 配置文件把数据集的“说明书”写对数据集文件准备好之后在datasets/mydata/下新建data.yaml文件。这个文件就像一份说明书告诉 YOLOv5 数据在哪里、有几类、类别叫什么。内容如下train: datasets/mydata/images/train val: datasets/mydata/images/val nc: 2 names: [person, car]注意train和val指向的是图片文件夹路径不是标签路径。YOLOv5 会根据同名规则自动去找标签。这个路径是相对于你运行训练命令的目录而言的所以如果你在yolov5/根目录下执行训练命令datasets/要和它同级或者写成绝对路径。nc是类别数量names是类别名称列表。这里有个非常搞笑的坑名字列表的顺序一定要和标注时定义的类别 ID 一致。你在标注软件里把person定义为 0在 names 里就要把person放在第一位否则训练出来的模型会把你所有的标签张冠李戴。3.4 标注时容易犯的几个错误说到标注我把新手最常犯的错集中讲一下。第一个错误一个标注框里包含了太多背景。YOLO 要求标注框尽量贴合目标边缘框得太大模型会把背景特征学进去框得太小目标特征不完整两种情况都会影响检测精度。第二个错误类别不平衡。如果数据集里一类有两千张图另一类只有五十张图模型大概率会把少数类忽略掉。这种情况可以收集更多少数类样本或者用脚本做简单过采样。第三个错误图片里有目标但没标出来。这会产生“漏检”样本模型被隐性地告知“这里没有目标”后续极其容易误判。每次标完一批数据我建议用可视化脚本把标签画到图片上检查一遍YOLOv5 里可以直接用detect.py配合--save-txt反过来检查标注质量也可以用其它开源可视化工具。4. 开始训练参数、监控与结果解读一次跑通的基本功数据集准备好环境没问题就可以进入训练环节了。YOLOv5 的训练命令本身不复杂真正值得讲清楚的是参数的含义以及训练过程中应该看什么、怎么判断模型练得好不好。4.1 训练命令与核心参数解析最基础的训练命令python train.py --img 640 --batch 16 --epochs 100 --data datasets/mydata/data.yaml --weights yolov5s.pt每个参数我都拆开讲一下--img是训练时输入的图片尺寸。YOLOv5 会把所有训练图片统一缩放到这个尺寸默认是 640。它直接决定了模型的输入分辨率和显存占用一般用 640 起步如果你的目标是小物体可以试试 1280但显存需求会成倍增长。--batch是批大小。它表示一次输入多少张图片到 GPU 进行训练。批大小由显存决定显存 8GB 的话 16 比较稳妥显存 4GB 就降到 8 或更低。批大小不宜过小否则梯度更新太频繁收敛不稳定。--epochs是训练轮数。小数据集 100-300 轮足够大规模数据集可以 300-500。不是越多越好后面我会教你判断什么时候该停。--weights指预训练权重。用yolov5s.pt会自动下载并加载官方在 COCO 数据集上训练好的权重这叫做迁移学习。比从零训练收敛更快、精度更高。如果想从头训练改成--weights 即可。另一个很重要的参数是--cache。它表示把数据提前缓存到内存中省去每次迭代都从磁盘读图的 IO 时间训练速度能提升不少。显存够用的话建议加上python train.py --img 640 --batch 16 --epochs 100 --data datasets/mydata/data.yaml --weights yolov5s.pt --cache4.2 训练过程监控怎么判断模型在变好还是过拟合训练启动后终端会不断打印日志同时会在runs/train/exp目录下生成训练结果。你需要看三样东西loss 曲线、PR 曲线和验证集精度。loss 分为三部分box_loss边框回归损失、obj_loss目标置信度损失、cls_loss分类损失。训练初期 loss 会快速下降中后期下降变慢这很正常。真正需要注意的是 val loss也就是验证集上的损失。如果 train loss 一直降、val loss 反而上升说明模型开始过拟合了这时应该停掉训练或增加数据增强。训练结束后重点看results.png里的 PPrecision 精确率、RRecall 召回率、mAP平均精度均值。这里我给大家一个通俗解释精确率是“你检测出来的框里有多少是对的”召回率是“真实目标里你有多少找出来了”mAP 是两者的综合指标。对于绝大多数自定义场景mAP0.5 达到 0.9 以上就算非常好了。如果只有 0.5 左右先别急着调参一般先从数据下手检查标注对不对、样本够不够、是否类别失衡。4.3 断点续训与学习率调整训练是一件很耗时的事哪怕用 GPU几百张图片的几轮训练也可能要几个小时。YOLOv5 支持自动保存最新权重last.pt和最优权重best.pt。如果你中途断了不需要重新跑直接执行python train.py --img 640 --batch 16 --epochs 100 --data datasets/mydata/data.yaml --weights runs/train/exp/weights/last.pt这就是断点续训接着上次的进度继续。这是一个非常实用的功能我自己训练的时候基本都会提前规划好训练轮数但总会因为各种意外中断断点续训省下的时间非常可观。另外新手容易忽略的一个参数是--patience它表示如果验证集精度连续多少轮没有提升就提前终止训练。默认是 100意思是 100 轮没进步就自动停。这个机制很好用能帮你节省大量时间。实际使用中我一般设置成 30-50让它在精度上升乏力时及时止损。5. 推理检测从命令行到 Python 调用把模型用起来训练完模型总算进入“展示成果”的阶段了。YOLOv5 既提供了简单的命令行方式也提供了灵活的 Python 接口。这个环节我会两种都讲因为日常快速验证用命令行但真正嵌入项目时几乎都是写 Python 调用。5.1 命令行推理一行命令搞定图片和视频检测使用训练好的best.pt对图片进行检测python detect.py --weights runs/train/exp/weights/best.pt --source test_images/ --conf-thres 0.25--source可以是单张图片、图片文件夹、视频文件甚至可以是摄像头编号。比如用摄像头实时检测python detect.py --weights runs/train/exp/weights/best.pt --source 0--conf-thres是置信度阈值默认 0.25也就是说模型认为某个框有 25% 以上的概率是目标才会画出来。阈值调高框更少但更准调低框更多但误检也会变多。这个参数没有绝对标准实际部署时你需要根据自己的场景调一版比如宁可漏检不要误检就把阈值调到 0.4 甚至 0.5。运行结束后检测结果会保存在runs/detect/exp目录下图片上已经画好了边界框、类别标签和置信度。命令行方式能满足大部分预览需求但它的问题在于每次都要加载模型、解析参数、跑完整流程。如果你要在一个已有的业务系统里调用检测能力绝对不适合用命令行方式。5.2 Python 接口加载模型、推理与结果解析YOLOv5 官方直接支持通过 Python 方式加载模型非常简单import torch model torch.hub.load(ultralytics/yolov5, custom, pathruns/train/exp/weights/best.pt)这里path指向你自己的权重文件。加载之后就可以对图片进行推理img test_images/001.jpg results model(img)results对象包含很多好东西。我这里给你展示最常用的几个属性# 获取边界框坐标、置信度、类别ID boxes results.xyxy[0] # 每行: x1, y1, x2, y2, conf, class # 显示检测结果 results.show() # 保存检测结果 results.save(output/)如果你要在服务端部署绝对不建议再用model.show()这种带 GUI 的调用方式。更专业的做法是把检测结果转成结构化数据detections results.pandas().xyxy[0] for _, row in detections.iterrows(): x1, y1, x2, y2 int(row[xmin]), int(row[ymin]), int(row[xmax]), int(row[ymax]) conf row[confidence] cls_name row[name] print(f类别: {cls_name}, 置信度: {conf:.2f}, 坐标: ({x1},{y1})-({x2},{y2}))这一段代码基本就是你在实际业务中处理 YOLOv5 输出时的雏形。无论你接的是拍照检测、视频分析还是实时流处理前面加个读取帧/图片后面加个逻辑处理整个链路就通了。5.3 摄像头或视频流检测的显存注意点很多人兴致勃勃跑摄像头实时检测结果发现视频非常卡帧率只有个位数。这是因为业务逻辑没优化。YOLOv5 的默认推理方式是每帧调用一次完整前向传播而视频每秒钟有 20-30 帧对 GPU 的消耗非常大。简单的优化手段是跳帧检测不是每一帧都做检测而是每隔几帧检测一次比如每 3 帧检测一次。这个策略对大部分场景完全够用毕竟目标不会在 100 毫秒内凭空消失。另外检测前把输入图片缩放到更小的尺寸也能显著提速比如从 640 降到 416帧率能提升一半以上精度下降却不太明显。6. 模型导出从 PyTorch 到 ONNX部署前的最后一步模型训练好、验证好真正要落地到生产环境还需要做模型导出。YOLOv5 官方提供了一键导出功能支持导出为 ONNX、TorchScript、TensorRT 等格式。把这一步讲清楚是因为很多人在“跑通检测”之后卡在了部署模型在开发机上运行良好换一台机器换成其他框架就完全跑不起来了。6.1 ONNX 导出跨平台部署的标准动作ONNXOpen Neural Network Exchange是一种跨框架的模型中间表示格式可以理解成“模型界的通用语言”。导出 ONNX 的步骤如下python export.py --weights runs/train/exp/weights/best.pt --include onnx --img 640导出的文件叫best.onnx放在权重同目录下。之后你可以用 ONNX Runtime 加载它在完全不依赖 PyTorch 的环境下运行import onnxruntime as ort import numpy as np import cv2 sess ort.InferenceSession(best.onnx) input_name sess.get_inputs()[0].name img cv2.imread(test.jpg) img cv2.resize(img, (640, 640)) img img[:, :, ::-1].transpose(2, 0, 1) # BGR - RGB, HWC - CHW img np.ascontiguousarray(img, dtypenp.float32) / 255.0 img np.expand_dims(img, axis0) outputs sess.run(None, {input_name: img})ONNX 导出的最大价值在于部署灵活性你的模型现在可以被 C、Java、C# 等任意语言调用可以部署在云服务器也可以部署在边缘设备完全绕开了 Python 和 PyTorch 的依赖。6.2 导出时的常见问题动态尺寸和结果解析差异导出和使用 ONNX 时有两个容易踩的坑。第一个坑是输入尺寸固定问题。默认情况下导出时指定的--img 640会把模型的输入尺寸固定为 640x640。如果你需要用其他尺寸推理可以在导出时加上--dynamic让 ONNX 模型支持动态输入尺寸但要注意动态尺寸的推理速度通常会略慢一些。第二个坑是输出解析差异。PyTorch 推理时results.xyxy已经帮你把预测结果解析成了好理解的左上角右下角坐标。但 ONNX 模型的原始输出是一个高维数组需要你自己解析边界框、置信度和类别。这个过程涉及 NMS非极大值抑制比较复杂。我建议新手不要改动 YOLOv5 的推理仓库直接复用官方提供的models/experimental.py或者用辅助工具库处理可以少掉很多头发。6.3 TensorRT 导出极致推理速度的一条小路如果你的部署环境是 NVIDIA 的 GPU那 TensorRT 是绕不开的加速手段。它可以对模型做层融合和精度校准FP16/INT8推理速度通常能提升两到三倍。导出命令也很简单python export.py --weights runs/train/exp/weights/best.pt --include engine --half--half表示使用半精度 FP16推理速度更快显存占用更少。但要注意TensorRT 导出的.engine文件是与 GPU 型号强相关的在 A 卡上导出的引擎不一定能在 B 卡上运行换机器必须重新导出。7. 训练效果提升数据与超参数的几个实用调整思路安装、训练、检测、导出全流程已经跑通。最后我想分享一些我长期使用 YOLOv5 后总结的提效经验这些不是官方文档里会写的东西但确实能帮你少走弯路。7.1 数据质量比模型参数更重要如果把 YOLOv5 用的时间拉长到几个项目你会发现一个规律数据集质量决定了精度的上限模型参数只是逼近这个上限。同一个模型我用质量差的数据集训练到 mAP 0.6 后无论如何调参都上不去换成清洗过得当的数据后不做任何调整精度直接冲到 0.92。差距不在模型在数据。所以当精度不理想时第一反应不应该是网上找各种魔改模型而是回头检查数据标注框贴合度、误标漏标、类别平衡、场景多样性把这些做扎实之后再考虑参数优化。7.2 数据增强的克制使用YOLOv5 自带了相当丰富的数据增强策略比如随机翻转、缩放、拼接Mosaic等。理解这些增强策略之后有一个常见的错误是为了追求“更强的泛化性”人为把增强参数拉满结果训练出来的模型在验证集上表现极差。增强要适度。训练小数据集时建议保留默认增强策略即可不要做太多自定义改动。真实世界的项目场景优先保证验证集和测试集与部署环境尽量一致而不是指望数据增强能弥补数据分布差异。7.3 迁移学习里的“冻结训练”技巧如果项目里可用的标注数据很少比如几百张可以考虑先冻结主干网络、只训练检测头等 loss 稳定后再解冻全部层训练。YOLOv5 里可以直接通过--freeze参数指定冻结前多少层python train.py --img 640 --batch 16 --epochs 50 --data datasets/mydata/data.yaml --weights yolov5s.pt --freeze 10这种做法在数据量有限时能有效避免过拟合因为预训练主干网络已经学到过通用的视觉特征你只需要让它适配你当前任务的检测逻辑。等第一阶段训练完毕去掉--freeze参数再继续训练完整模型泛化效果通常比直接完整训练好不少。我最近一个项目就是用这个思路在只有 700 多张图片的情况下把一个小目标检测场景的 mAP 从 0.67 拉到了 0.85而且训练时间比从头完整训练还短。如果你的数据集不大这个技巧值得认真试试。8. 写在最后的一点体会YOLOv5 这个东西网上教程多如牛毛动不动号称“超详细”但大部分都停留在 command 复述层面。真正让你成长的是理解每一步操作背后的原因为什么用那个仓库、为什么数据集要这么放、为什么调那个参数以及精度不行时从哪下手排查。我在实际使用中还有一个习惯每次训练完都会在runs/train/目录外另存一份训练配置副本包括data.yaml、训练命令参数和best.pt的 mAP 指标。这样一个月后回头想调模型时不用靠记忆猜当时怎么训的直接翻记录就能完整复现。这个习惯看起来不起眼但对长期维护模型帮助极大。另外如果你打算把 YOLOv5 用到自己的业务里建议严格控制版本不要频繁升级项目仓库。它本身已经非常成熟不会因为新功能频繁变动而给你带来额外收益。用熟一个版本、吃透一套流程比天天追新版本更重要。这是我看过无数人折腾之后最想说的一句话。