ARTICLE DETAIL

建站实战干货

来自一线的建站与推广经验沉淀，每一条都经过真实交付验证。

首页 / 资讯中心 / 正文

YOLOv5从零部署到自定义训练：环境配置、数据标注与模型调优全攻略

2026/8/12 13:20:33 拓冰建站 浏览量
YOLOv5从零部署到自定义训练：环境配置、数据标注与模型调优全攻略

1. 项目概述：为什么YOLOv5依然是目标检测的“硬通货”？

如果你正在计算机视觉领域摸索，或者想快速上手一个能跑起来、效果还不错的检测模型，YOLOv5大概率是你绕不开的一个名字。尽管学术界新模型层出不穷，但在工业界、学生项目乃至个人开发者中，YOLOv5凭借其极致的工程友好性、清晰的文档和活跃的社区，依然是入门和快速部署的“首选”。很多人卡在第一步：安装和配置。网上的教程要么过于零散，要么环境依赖写得不清不楚，导致跟着做一遍，各种报错，最后从入门到放弃。

这篇文章，我就以一个踩过无数坑的过来人身份，带你从头到尾、手把手地走通YOLOv5的安装、配置到基本使用的全流程。我们不只讲“怎么装”，更会深入讲清楚“为什么要这么装”，以及那些官方文档里不会写的、只有实际跑过项目才知道的“坑点”和“骚操作”。无论你是用Windows、macOS还是Linux，无论你的显卡是RTX 4090还是GTX 1060，甚至是只用CPU，这里都有对应的解决方案。我们的目标很简单：让你在30分钟内，拥有一个可以检测图片、视频甚至调用摄像头的YOLOv5环境。

2. 环境准备：构建一个稳定、可复现的Python工作区

在直接pip install之前，花10分钟做好环境规划，能为你后续节省数小时的排错时间。YOLOv5的核心是PyTorch，而PyTorch对CUDA（显卡计算平台）和cuDNN（深度神经网络加速库）的版本有严格匹配要求。乱装一气，最常见的就是遇到“Torch not compiled with CUDA enabled”这种令人崩溃的错误。

2.1 核心依赖解析：PyTorch、CUDA与cuDNN的“铁三角”

首先，你需要理解这三者的关系。PyTorch是深度学习框架，是我们要用的“大脑”。CUDA是NVIDIA推出的通用并行计算架构，让PyTorch可以利用GPU进行高速计算。cuDNN则是NVIDIA针对深度神经网络操作的加速库，是CUDA的“强化补丁”。

它们的版本必须兼容。例如，PyTorch 1.12.1可能只支持CUDA 11.3或11.6，如果你系统里装的是CUDA 12.0，那就会出问题。因此，正确的安装顺序是：先确定你的显卡驱动能支持的最高CUDA版本，然后去PyTorch官网找到对应此CUDA版本的PyTorch安装命令，最后用这个命令安装PyTorch。cuDNN通常会在安装PyTorch时作为依赖自动处理，但了解其存在很重要。

注意：如果你没有NVIDIA显卡，或者暂时不想用GPU，完全可以安装CPU版本的PyTorch，YOLOv5同样可以运行，只是速度会慢很多。这对于验证流程和轻量级学习是完全可行的。

2.2 实操：一步步搭建专属Python环境

我强烈建议使用Conda或**Python虚拟环境（venv）**来管理你的项目环境。这能保证每个项目的依赖库互不干扰，就像给每个项目一个独立的“房间”，避免因为库版本冲突导致的各种诡异问题。

步骤一：检查显卡与驱动打开命令行（Windows的CMD/PowerShell，macOS/Linux的Terminal），输入：

nvidia-smi

如果你看到显卡信息和驱动版本，说明驱动已安装。输出顶部会显示你当前驱动支持的最高CUDA版本（例如“CUDA Version: 12.2”）。记下这个版本号。

如果命令未找到，你需要先去NVIDIA官网下载并安装显卡驱动。对于没有NVIDIA显卡的机器，这一步可以跳过。

步骤二：创建并激活虚拟环境这里以Conda为例（如果你没有安装Conda，推荐安装Miniconda，它更轻量）。

# 创建一个名为yolov5的Python3.9环境 conda create -n yolov5 python=3.9 # 激活环境 conda activate yolov5

使用Python 3.8或3.9是最稳妥的选择，对各类库的兼容性最好。Python 3.10及以上版本可能会遇到一些较老库的编译问题。

步骤三：安装匹配的PyTorch前往 PyTorch官网 ，利用它的安装命令生成器。

  1. PyTorch Build: 选择稳定版（Stable）。
  2. Your OS: 选择你的操作系统。
  3. Package: 推荐使用pip（除非你有特殊需求用Conda）。
  4. Language: Python。
  5. Compute Platform: 这里就是关键！根据你nvidia-smi看到的CUDA版本选择。例如，看到“CUDA 12.2”，就选择CUDA 12.2。如果你的驱动支持CUDA 11.8，就选CUDA 11.8。如果没有GPU或想装CPU版，这里就选择CPU。

网站会生成一行命令，比如对于CUDA 12.1的可能是：

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

复制这行命令，在你激活的yolov5环境中执行。

步骤四：验证PyTorch与GPU安装完成后，进入Python交互环境验证：

import torch print(torch.__version__) # 打印PyTorch版本 print(torch.cuda.is_available()) # 打印True说明GPU可用 print(torch.cuda.get_device_name(0)) # 打印你的GPU型号

如果torch.cuda.is_available()返回False，但你有GPU，说明PyTorch的CUDA版本和系统CUDA驱动版本不匹配，需要回到步骤三重新选择。

3. YOLOv5源码获取与依赖安装

环境准备好了，现在可以把YOLOv5的“本体”请下来了。

3.1 克隆仓库与目录结构初窥

YOLOv5的代码托管在GitHub上。我们使用git来克隆，这是最标准的方式。

# 克隆YOLOv5官方仓库 git clone https://github.com/ultralytics/yolov5 # 进入项目目录 cd yolov5

克隆下来的yolov5文件夹里有什么？快速浏览一下：

  • data/: 存放数据集配置文件和脚本（如coco.yaml）。
  • models/: 模型定义文件，包括yolov5s.yaml,yolov5m.yaml等不同大小的模型。
  • utils/: 工具函数库，包括损失计算、指标评估、日志记录等。
  • weights/: 空文件夹，用于存放下载的预训练模型权重。
  • detect.py:用于推理的脚本，对图像、视频、流进行检测。
  • train.py:用于训练的脚本。
  • val.py:用于验证的脚本。
  • export.py:用于模型导出的脚本，可以导出为ONNX、TensorRT等格式。
  • requirements.txt:项目依赖包列表，这是我们下一步要安装的。

3.2 安装项目依赖：解读requirements.txt

在项目根目录下，执行：

pip install -r requirements.txt

这个命令会安装requirements.txt里列出的所有Python包。我们来看看其中几个关键角色：

  • opencv-python： 图像处理核心库，用于读取图片、视频，画检测框。
  • pycocotools： 用于COCO数据集格式的评估，安装这个有时会报错，特别是在Windows上。如果失败，可以尝试pip install pycocotools-windows。
  • torch>=1.8.0： 我们之前已经安装了，这里会检查版本。
  • tensorboard： 训练可视化工具，可以在浏览器中实时查看损失曲线、指标变化。
  • pandas,seaborn： 用于生成训练结果的分析图表。

实操心得：requirements.txt里的版本号有时是“>=”，这意味着可能会安装最新的版本。而最新版有时会引入不兼容的改动。如果安装后运行报错，可以尝试指定稍旧一点的稳定版本。例如，我曾遇到过最新版的matplotlib导致图表显示异常，回退到3.5.3就解决了。记住这个排查思路：当遇到莫名其妙的库错误时，版本冲突是首要怀疑对象。

安装过程可能会持续几分钟，取决于你的网络。如果遇到某个包下载慢或失败，可以考虑使用国内镜像源，例如清华源：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 预训练模型与初步测试：验证安装成功

依赖装好了，但模型还是个空壳。我们需要用预训练权重来赋予它“视力”。

4.1 下载预训练权重

YOLOv5提供了从轻量到重量的多个模型：yolov5n(nano),yolov5s(small),yolov5m(medium),yolov5l(large),yolov5x(extra large)。模型越大，精度通常越高，但速度越慢，所需资源也越多。对于初次测试和大多数应用，yolov5s在速度和精度上取得了很好的平衡。

你可以通过detect.py脚本自动下载，但我更推荐手动下载，因为网络问题可能导致自动下载失败。

  1. 访问YOLOv5的 GitHub Releases页面 。
  2. 找到最新的发布版本，在Assets里找到yolov5s.pt（或其他你想要的模型权重文件）。
  3. 下载后，将其放入项目根目录下的weights/文件夹中（如果没有就新建一个）。

4.2 运行第一个检测：让模型“看见”世界

现在，激动人心的时刻到了。我们用官方自带的测试图片来跑一下检测。

python detect.py --source data/images --weights weights/yolov5s.pt --conf 0.25

我们来拆解这条命令：

  • --source data/images: 指定检测源。data/images是项目自带的两个测试图片（bus.jpg和zidane.jpg）所在的文件夹。你也可以指定单张图片路径、视频文件、摄像头编号（如0）或一个包含图片的URL。
  • --weights weights/yolov5s.pt: 指定使用的模型权重路径。
  • --conf 0.25: 置信度阈值。只有检测框的置信度高于0.25的才会被显示出来。调高这个值（如0.5），结果会更严格，漏检可能增加；调低则可能看到更多误检。

执行命令后，你会看到终端开始输出信息：加载模型、处理图片、输出检测结果。处理完成后，结果会保存在runs/detect/exp/目录下（每次运行都会新建一个expn文件夹，n是数字，自动递增）。

打开结果图片，你应该能看到图片中的行人、汽车等被画上了框，并标注了类别和置信度。恭喜你，YOLOv5已经成功运行起来了！

4.3 测试你的自定义图片和视频

把你想检测的图片（比如my_pic.jpg）放到项目根目录，然后运行：

python detect.py --source my_pic.jpg --weights weights/yolov5s.pt

检测视频（比如my_video.mp4）：

python detect.py --source my_video.mp4 --weights weights/yolov5s.pt

使用电脑摄像头（通常编号为0）进行实时检测：

python detect.py --source 0 --weights weights/yolov5s.pt

按q键可以退出实时检测窗口。

5. 训练自己的数据集：从“用模型”到“造模型”

使用预训练模型做检测只是第一步。要让YOLOv5认识你关心的特定物体（比如识别某种零件、某种动物），你需要用自己的数据训练它。这是YOLOv5最核心的价值所在。

5.1 数据准备：YOLO格式详解

YOLOv5要求一种特定的标注格式。你需要为每张图片准备一个同名的.txt标注文件。

  • 图片：可以是.jpg,.png等常见格式。
  • 标注文件：.txt文件，每一行代表图片中的一个物体。
  • 标注行格式：<class_id> <x_center> <y_center> <width> <height>
    • class_id: 物体的类别索引，从0开始。比如“猫”是0，“狗”是1。
    • x_center, y_center: 物体边界框中心的x和y坐标，归一化到图片宽度和高度（即值在0到1之间）。计算公式：x_center = (x_min + x_max) / 2 / image_width
    • width, height: 物体边界框的宽度和高度，同样归一化到图片宽度和高度。计算公式：width = (x_max - x_min) / image_width

例如，一张1000x800的图片上，有一个“猫”（class_id=0）的边界框，其左上角坐标(100, 120)，右下角坐标(300, 400)。那么：

  • x_center = (100 + 300)/2 / 1000 = 0.2
  • y_center = (120 + 400)/2 / 800 = 0.325
  • width = (300 - 100) / 1000 = 0.2
  • height = (400 - 120) / 800 = 0.35对应的标注行就是：0 0.2 0.325 0.2 0.35

你可以使用标注工具来生成这种格式，最常用的是LabelImg（设置输出格式为YOLO）或Roboflow（在线平台，提供数据增强和格式转换）。

5.2 数据集配置文件：告诉YOLOv5你的数据在哪

数据准备好后，需要创建一个YAML配置文件来告诉训练脚本数据的路径和类别信息。在data/目录下新建一个文件，例如my_custom_data.yaml，内容如下：

# 训练和验证图像的路径（可以是相对路径或绝对路径） train: ../datasets/my_data/images/train/ val: ../datasets/my_data/images/val/ # 类别数量 nc: 2 # 例如，我只有猫和狗两类 # 类别名称列表 names: ['cat', 'dog']
  • train和val: 分别指向训练集和验证集图片所在的文件夹。YOLOv5会读取这些文件夹下所有的图片，并自动在同一目录下寻找同名的.txt标注文件。
  • nc: 类别的总数。
  • names: 类别名称列表，顺序必须与标注文件中的class_id对应。

你需要按照这个结构组织你的数据：

datasets/ └── my_data/ ├── images/ │ ├── train/ # 存放所有训练图片 │ └── val/ # 存放所有验证图片 └── labels/ ├── train/ # 存放所有训练图片对应的.txt标注文件 └── val/ # 存放所有验证图片对应的.txt标注文件

注意，images/train/和labels/train/里的文件必须一一对应，且文件名（不含后缀）相同。

5.3 启动训练：参数解析与监控

准备好数据和配置文件后，就可以开始训练了。基础训练命令如下：

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

这是一个非常强大的命令，我们来详细解读每个参数：

  • --img 640: 输入图像的大小。YOLOv5会将所有图片缩放（保持长宽比并填充）到这个尺寸。更大的尺寸（如1280）可能提升精度，但会显著增加显存消耗和训练时间。640是一个在精度和速度间平衡的常用值。
  • --batch 16: 批处理大小。一次输入多少张图片进行前向和反向传播。越大训练越稳定、越快，但需要更多显存。如果出现“CUDA out of memory”错误，首先尝试减小batch大小。
  • --epochs 100: 训练轮数。整个训练集被完整遍历一次称为一个epoch。通常需要几十到几百个epoch，模型才能收敛。
  • --data data/my_custom_data.yaml: 指向你刚刚创建的数据集配置文件。
  • --weights weights/yolov5s.pt:迁移学习的起点。这里我们使用在COCO数据集上预训练的yolov5s.pt作为初始权重。这是训练自己数据集的关键技巧，能极大加快收敛速度并提升最终性能，远比从零开始训练要好。
  • --device 0: 指定使用的GPU设备编号。如果是多卡，可以用--device 0,1。使用CPU则设为--device cpu。

训练开始后，终端会输出每个epoch的损失值、评估指标（如mAP@0.5）。同时，TensorBoard日志会保存在runs/train/exp/目录下。你可以启动TensorBoard来可视化训练过程：

tensorboard --logdir runs/train

然后在浏览器中打开http://localhost:6006，就可以看到损失曲线、精度曲线、验证样本的检测结果等，非常直观。

5.4 训练中的关键技巧与调参

  1. 学习率（--lr0）：这是最重要的超参数之一。默认是0.01。如果训练过程中损失值剧烈震荡或变成NaN，可以尝试调小学习率（如0.001）。如果损失下降非常缓慢，可以尝试调大。
  2. 数据增强：YOLOv5默认开启了丰富的数据增强（如 mosaic, mixup, 色彩抖动，随机翻转等），这能有效防止过拟合，提升模型泛化能力。除非你的数据非常特殊，否则不建议关闭。
  3. 早停（--patience）：可以设置--patience 50，表示如果连续50个epoch验证集指标没有提升，就自动停止训练，防止过拟合。
  4. 恢复训练：如果训练意外中断，可以使用--resume参数从上次保存的最后一个权重继续训练。例如：--resume runs/train/exp/weights/last.pt。

6. 模型验证与导出：从训练结果到实际应用

训练完成后，我们需要评估模型的好坏，并把它转换成可以在不同平台上部署的格式。

6.1 模型性能验证

训练脚本在结束时，会自动在验证集上运行一次评估，结果保存在runs/train/exp/results.csv和图片中。你也可以手动运行更详细的验证：

python val.py --weights runs/train/exp/weights/best.pt --data data/my_custom_data.yaml --img 640
  • --weights: 这里指定训练得到的最佳权重best.pt（验证集指标最高的权重）。
  • 运行后会输出一系列指标，其中最关键的是mAP@0.5和mAP@0.5:0.95。
    • mAP@0.5：当交并比（IoU）阈值为0.5时的平均精度均值。这是最常用的一个指标，值越高越好，通常达到0.8以上就算很不错了。
    • mAP@0.5:0.95：在IoU阈值从0.5到0.95（步长0.05）区间内的平均mAP。这是一个更严格的指标。

6.2 模型导出：适配不同部署环境

训练好的.pt文件是PyTorch格式，要在某些边缘设备（如Jetson Nano）或追求极致速度的场景（使用TensorRT）下运行，需要转换成其他格式。export.py脚本就是干这个的。

导出为ONNX格式（一种开放的模型交换格式）：

python export.py --weights runs/train/exp/weights/best.pt --include onnx

导出为TensorRT引擎（NVIDIA GPU上的极致推理加速）：

python export.py --weights runs/train/exp/weights/best.pt --include engine --device 0

导出为CoreML格式（用于iOS/macOS应用）：

python export.py --weights runs/train/exp/weights/best.pt --include coreml

导出的文件会保存在和权重文件相同的目录下。注意，导出TensorRT引擎需要你的环境已正确安装TensorRT。

7. 常见问题与深度排错指南

即使按照步骤操作，也难免会遇到问题。这里我汇总了一些高频问题和解决方法。

7.1 安装与依赖类问题

Q1:pip install -r requirements.txt时，pycocotools安装失败（特别是在Windows上）。A1:这是最常见的问题。pycocotools在Windows上需要Visual C++ Build Tools。最简单的解决方案是安装预编译的Windows版本：

pip install pycocotools-windows

或者，如果你不需要在COCO格式的数据集上做精确评估，可以在requirements.txt中暂时注释掉pycocotools这一行，对基础训练和检测影响不大。

Q2: 运行detect.py或train.py时，报错ModuleNotFoundError: No module named ‘XXX‘。A2:这通常是某个依赖包没有成功安装。首先，请确保你是在激活的虚拟环境（conda activate yolov5）中操作。然后，手动安装缺失的包，例如：pip install XXX。如果问题依旧，尝试升级pip并重新安装所有依赖：pip install --upgrade pip然后pip install -r requirements.txt。

Q3: 使用GPU训练时，报错RuntimeError: CUDA out of memory。A3:显存不足。按以下顺序尝试解决：

  1. 减小批处理大小：这是最有效的方法。将--batch从16降到8、4甚至2。
  2. 减小输入图像尺寸：将--img从640降到416或320。
  3. 使用更小的模型：从yolov5s.pt换到yolov5n.pt作为预训练权重。
  4. 检查是否有其他程序占用显存：在命令行输入nvidia-smi，关闭不必要的GPU进程。
  5. 使用梯度累积：如果显存实在太小，可以设置--accumulate 2（例如），这相当于模拟一个更大的batch size，但会稍微增加训练时间。

7.2 训练与数据类问题

Q4: 训练时损失（loss）不下降，或者下降得非常慢。A4:

  1. 检查数据：这是首要原因。确保你的标注文件（.txt）格式正确，没有空文件，并且class_id在范围内。可以用detect.py快速验证一下标注是否正确：python detect.py --weights yolov5s.pt --source path/to/your/image.jpg，看看预训练模型能否在你图片上检测出东西（至少背景是能处理的）。如果预训练模型都表现异常，可能是图片本身格式有问题。
  2. 调整学习率：默认学习率0.01可能对你的数据太大或太小。尝试使用--lr0 0.001（调小）或--lr0 0.1（调大，需谨慎）。
  3. 关闭数据增强：极少数情况下，默认的数据增强可能干扰了特定数据的训练。可以尝试在训练命令后加上--noaug来关闭所有增强，看看损失是否开始下降。
  4. 检查预训练权重：确保--weights参数指向了正确的、已下载的预训练权重文件（如yolov5s.pt）。

Q5: 训练出的模型在验证集上mAP很低，或者检测时“瞎猜”（乱标框）。A5:

  1. 数据量不足：深度学习是数据驱动的。每个类别的目标至少需要几百甚至上千个样本。如果数据太少，模型无法学习到有效特征。
  2. 类别不平衡：某个类别的样本数量远多于其他类别，导致模型偏向于预测多数类。需要收集更多少数类的数据，或在数据加载时进行采样平衡。
  3. 验证集和训练集分布不一致：确保验证集和训练集来自相同的场景、相同的采集条件。不要把白天数据用于训练，晚上数据用于验证。
  4. 过拟合：模型在训练集上表现很好，在验证集上很差。现象是训练损失持续下降，但验证损失在某个点后开始上升。解决方法：增加数据增强、使用更小的模型、添加正则化（如权重衰减--weight_decay）、减少训练轮数（--epochs）或使用早停（--patience）。

7.3 推理与部署类问题

Q6: 使用detect.py推理时速度很慢。A6:

  1. 确认是否在使用GPU：运行python -c "import torch; print(torch.cuda.is_available())"，确保输出为True。如果为False，你正在使用CPU推理，速度会慢几十倍。请检查PyTorch的CUDA版本是否安装正确。
  2. 使用更小的模型：yolov5n比yolov5s快很多，精度略有牺牲。
  3. 减小推理尺寸：在detect.py中使用--imgsz 320（默认640）。
  4. 使用半精度（FP16）推理：添加参数--half，可以显著提升GPU上的推理速度，并减少显存占用，对精度影响很小。命令如：python detect.py --source ... --weights ... --half。
  5. 导出为TensorRT或ONNX并使用对应推理引擎：这是生产环境下获得极致速度的终极方案。PyTorch的动态图本身有一定开销，转换为静态图（如ONNX）并由专用推理引擎（如TensorRT, ONNX Runtime）执行，速度会有大幅提升。

Q7: 导出的ONNX或TensorRT模型推理结果和PyTorch模型不一致。A7:这是精度转换和算子兼容的常见问题。

  1. 确保导出时输入尺寸固定：有些模型结构对动态尺寸支持不好。在export.py中指定固定的--imgsz，例如--imgsz 640 640。
  2. 检查ONNX opset版本：尝试不同的--opset版本（如12, 13, 17）。
  3. 进行精度对齐测试：在导出后，编写一个简单的脚本，用相同的随机输入分别运行PyTorch模型和导出的模型，比较输出张量的差异。微小的差异（1e-5级别）是正常的，如果差异巨大，则需要排查模型结构中是否有不支持的算子。
  4. 查阅YOLOv5的导出文档：Ultralytics团队会持续更新对不同部署后端的支持情况，可能你遇到的问题在新版本中已经修复。

整个流程走下来，从环境配置到训练出自己的模型，看似步骤不少，但每一步都有其明确的目的。YOLOv5的优秀之处就在于，它把很多复杂的工程细节都封装好了，让我们能更专注于数据、业务和模型调优本身。记住，在深度学习项目中，数据质量决定了模型的上限，而代码和调参只是让我们不断逼近这个上限。多花时间在数据清洗和标注上，往往比盲目调整超参数回报率更高。当你第一次用自己训练的模型准确识别出目标时，那种成就感就是驱动你继续深入这个领域的最好动力。如果在实践中遇到上面没覆盖到的新问题，最好的方法是去YOLOv5的GitHub Issues区搜索，你遇到的大部分问题，很可能已经有前人遇到过并提供了解决方案。