企业官网建设流程全解析

图像识别这块，YOLOv5 算是绕不开的一个实战起点。我从几年前开始把它用在工业质检、安防巡检、零售货架盘点这些场景里，踩过的坑比跑通的模型还多。很多人第一次接触目标检测，看到一堆 anchor、IOU、mAP 就头大，其实把 YOLOv5 拆开来看，它解决的是一件很朴素的事：给一张图，框出里面有什么、在哪、有多大。这件事听起来简单，但真正落地到业务里，数据怎么标、模型怎么选、推理怎么加速、部署怎么稳，每一步都有讲究。这篇内容我打算把 YOLOv5 从环境搭建到训练调参再到部署推理的完整链路讲透，适合刚入门目标检测的开发者，也适合已经跑通过 demo 但卡在效果优化上的朋友。不管你是用笔记本跑着玩，还是要在边缘设备上做实时检测，下面的内容都能直接拿去参考。

1. 项目整体设计与技术选型思路

1.1 为什么是 YOLOv5 而不是别的检测器

目标检测这个领域，模型家族大致分两派：两阶段检测器（以 Faster R-CNN 为代表）和单阶段检测器（以 YOLO 系列、SSD 为代表）。两阶段的做法是先粗筛候选区域，再精细分类回归，精度通常高一些，但速度慢，结构也复杂。单阶段则是把检测当成一个回归问题，一次前向就出结果，速度快、结构简洁，特别适合实时场景。

YOLOv5 属于单阶段里的工程化标杆。它不是我见过精度最高的，但它在精度、速度、易用性三者之间找到了一个很舒服的平衡点。我选它做实战起点，主要基于几个现实考量：

• 工程成熟度高：代码结构清晰，训练脚本、推理脚本、导出脚本一应俱全，改起来不费劲。
• 生态完善：预训练权重齐全，从 n 到 x 五个规模档位，小到嵌入式、大到服务器都能覆盖。
• 部署友好：支持导出 ONNX、TensorRT、OpenVINO 等多种格式，落地路径明确。
• 社区活跃：遇到问题基本都能找到讨论，不用一个人死磕。

注意：YOLOv5 的版本迭代比较快，不同小版本之间 API 有细微差异，建议锁定一个稳定版本再开工，别一边写代码一边升级依赖。

1.2 五个模型档位怎么选

YOLOv5 提供 n、s、m、l、x 五个规模，参数量和计算量依次递增。选型不是越大越好，得看你的硬件和延迟要求。我整理了一张对照表，方便你快速定位：

我个人的经验是：先用 s 档跑通全流程，再根据 mAP 和延迟的短板决定往哪个方向调。如果 s 档精度不够，先别急着换 l，先看看数据质量和标注有没有问题，很多时候瓶颈不在模型容量上。

1.3 整体链路拆解

一个完整的 YOLOv5 实战项目，链路大致是这样的：数据采集与标注 → 数据格式转换与划分 → 配置文件编写 → 训练与验证 → 模型评估与调优 → 导出与部署 → 推理与后处理。这条链路里，训练只占一部分时间，真正耗精力的是数据准备和部署适配。我见过太多人模型训得不错，结果卡在导出格式不兼容或者后处理写错上。

所以这篇内容的编排逻辑是：先把环境和数据这两块地基打牢，再讲训练调参的核心细节，最后落到部署和排错。每一步我都会说明为什么这么做，而不只是给命令。

2. 环境搭建与数据准备的核心细节

2.1 环境搭建的稳妥做法

环境这块，我强烈建议用虚拟环境隔离，别在系统 Python 里直接装。依赖冲突是新手最容易栽的坑，尤其是 PyTorch 和 CUDA 的版本匹配。

# 创建并激活虚拟环境 python -m venv yolov5_env source yolov5_env/bin/activate # Windows 用 yolov5_env\Scripts\activate # 安装 PyTorch（以 CUDA 11.8 为例，具体按你的显卡驱动选） pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 克隆代码并安装依赖 git clone https://github.com/ultralytics/yolov5.git cd yolov5 pip install -r requirements.txt

版本匹配这件事值得多说两句。PyTorch 版本、CUDA 版本、显卡驱动三者要对得上，否则会出现torch.cuda.is_available()返回 False 的情况。装完之后先跑一句验证：

import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else "CPU only")

如果is_available()是 False，先别怀疑代码，去查驱动和 CUDA 的对应关系。我踩过最冤的一次坑是驱动太老，装了半天白忙活。

提示：requirements.txt 里有些依赖版本会随时间变化，如果安装报错，可以尝试单独降级出问题的包，而不是整体重装。

2.2 数据标注的规范与工具

数据是目标检测的地基，标注质量直接决定模型上限。标注工具我用过几款，LabelImg 适合入门，Labelme 适合需要分割的场景，CVAT 适合团队协作。选哪个不重要，重要的是标注规范要统一。

标注规范我总结了几条硬性要求：

• 框要贴紧目标边缘：留白太多会让模型学到错误的边界，贴太紧又会切掉目标。一般留 1 到 2 个像素的余量比较合适。
• 同类目标命名一致：别一会儿写 "person" 一会儿写 "Person"，类别名大小写敏感，会导致类别混乱。
• 遮挡目标要标可见部分：完全被遮挡的目标不标，部分遮挡的按可见轮廓标。
• 小目标别漏标：小目标是检测难点，漏标会让模型对小目标更不敏感。

标注格式上，YOLOv5 用的是 YOLO 格式，每张图对应一个 txt 文件，每行一个目标，格式是类别索引 中心x 中心y 宽 高，坐标都归一化到 0 到 1 之间。如果你用的是 VOC 的 XML 或者 COCO 的 JSON，需要转换。转换脚本网上很多，但建议自己写一遍，理解坐标变换的逻辑，后面排查问题会轻松很多。

2.3 数据集划分与配置文件

数据集一般按 8:1:1 或 7:2:1 划分训练集、验证集、测试集。小数据集可以适当提高验证集比例，保证评估的可靠性。划分时要注意同一场景的图片不要跨集分布，否则验证集指标会虚高。

YOLOv5 的数据配置文件是一个 yaml，结构如下：

# data/mydata.yaml path: ../datasets/mydata train: images/train val: images/val test: images/test nc: 3 names: ['defect_a', 'defect_b', 'defect_c']

nc是类别数，names是类别名列表，顺序要和标注时的类别索引对应。这里最容易出错的是路径，path是数据集根目录，train、val是相对路径。我建议用绝对路径先跑通，确认没问题再改成相对路径，避免路径解析的坑。

2.4 数据增强的取舍

YOLOv5 默认开启了 Mosaic 增强、随机缩放、色彩抖动等。Mosaic 是把四张图拼成一张，能显著提升小目标检测能力和模型鲁棒性。但增强不是越多越好，得看场景。

我的经验是：如果目标尺寸分布比较集中，可以适当降低缩放增强的幅度；如果场景光照变化大，色彩抖动可以保留；如果目标密集，Mosaic 很有用。对于工业质检这种目标形态固定的场景，过度增强反而会引入噪声，可以关掉部分增强。

配置文件在data/hyps/hyp.scratch-low.yaml里，可以复制一份改。关键参数包括mosaic（拼接概率）、scale（缩放幅度）、hsv_h/s/v（色彩抖动幅度）。调这些参数时一次只改一个，改完看验证集指标变化，别一次全改，否则出了问题都不知道是哪个参数导致的。

3. 训练调参与核心环节实操

3.1 训练命令与关键参数解读

YOLOv5 的训练入口是train.py，一条典型命令长这样：

python train.py \ --img 640 \ --batch 16 \ --epochs 100 \ --data data/mydata.yaml \ --weights yolov5s.pt \ --cfg models/yolov5s.yaml \ --name exp01 \ --cache

逐个说下关键参数的含义和选择逻辑：

• --img：输入图像尺寸，默认 640。尺寸越大，小目标越容易检出，但显存占用和计算量也越大。显存不够时优先降这个。
• --batch：批大小。显存允许的情况下越大越好，梯度更稳。一般 8 到 32 之间，显存爆了就减半。
• --epochs：训练轮数。小数据集 100 到 300 轮，大数据集可以少一些。配合早停机制，不用太纠结具体数字。
• --weights：预训练权重。强烈建议从预训练权重开始，收敛快、效果好。从零训练只在数据量极大时才考虑。
• --cache：把图片缓存到内存或磁盘，加速数据加载。数据集不大时建议开。

注意：--img必须是 32 的倍数，因为网络有多次下采样。设成 641 会报错，设成 640 才对。

3.2 学习率与优化器的调法

YOLOv5 默认用 SGD 优化器，配合余弦退火学习率调度。学习率初始值默认 0.01，这个值对大多数场景够用。但如果你的数据集很小（几百张），0.01 可能偏大，容易震荡，可以降到 0.001 到 0.005。

我调学习率的习惯是：先看训练前 10 轮的 loss 曲线。如果 loss 剧烈震荡甚至上升，说明学习率太大；如果 loss 下降极慢，说明学习率太小。正常情况应该是前几轮快速下降，之后平缓收敛。

优化器方面，SGD 泛化性好，Adam 收敛快但容易过拟合。小数据集我倾向 SGD，大数据集可以试试 AdamW。切换优化器时学习率要相应调整，Adam 系列一般用更小的学习率。

3.3 损失函数的三个组成部分

YOLOv5 的损失由三块构成：分类损失、置信度损失、边界框回归损失。理解这三块有助于你判断训练出了什么问题。

• 分类损失：判断框内目标属于哪个类别。如果分类损失降不下去，通常是类别不平衡或者标注有误。
• 置信度损失：判断框内有没有目标。置信度损失高，说明模型对"这里有没有东西"判断不准，可能是背景样本太多。
• 边界框回归损失：调整框的位置和大小。回归损失高，说明框定位不准，可能是标注框质量差或者目标尺度差异大。

训练日志里这三块损失是分开打印的，盯住它们的变化趋势，比只看总 loss 有用得多。我遇到过总 loss 在降但 mAP 不涨的情况，一看是分类损失降了、回归损失没动，最后发现是标注框普遍偏大。

3.4 训练过程监控与早停

训练时用 TensorBoard 看曲线是最直观的：

tensorboard --logdir runs/train

重点看几条曲线：训练 loss、验证 loss、mAP@0.5、mAP@0.5:0.95。理想状态是训练 loss 和验证 loss 同步下降，mAP 稳步上升。如果训练 loss 降但验证 loss 上升，就是过拟合了，需要加正则、减模型容量或者增数据。

YOLOv5 自带早停机制，通过--patience参数控制，默认 100 轮没有提升就停。小数据集建议调小到 30 到 50，避免无效训练浪费时间。

3.5 从训练结果反推问题

训练完看results.png和混淆矩阵，能发现很多问题。混淆矩阵里如果某两类互相误判严重，说明这两类特征太像，要么合并类别，要么补充区分性样本。如果背景被大量误检为目标，说明负样本不足，需要补充纯背景图。

我整理了一张常见现象与对策的对照表：

4. 模型评估、导出与部署落地

4.1 评估指标怎么看

目标检测的核心指标是 mAP（平均精度均值）。mAP@0.5 表示 IOU 阈值为 0.5 时的平均精度，mAP@0.5:0.95 是多个 IOU 阈值下的平均值，后者更严格。

除了 mAP，还要看 Precision（查准率）和 Recall（查全率）。这两个指标往往此消彼长，取决于你的业务更怕误检还是漏检。安防场景通常更怕漏检，宁可多报不可漏报，这时候要调低置信度阈值；质检场景如果误检会导致大量人工复核，就要提高阈值保精度。

置信度阈值和 NMS 的 IOU 阈值是两个关键后处理参数。置信度阈值决定哪些框保留，NMS 的 IOU 阈值决定重叠框怎么合并。这两个参数在推理时调，不用重新训练。

4.2 模型导出与格式选择

训练完的权重是 pt 格式，部署时通常要转成其他格式。常见选择：

• ONNX：通用性最好，跨框架跨平台，适合大多数部署场景。
• TensorRT：NVIDIA GPU 上性能最优，但绑定硬件。
• OpenVINO：Intel CPU 和集成显卡上表现好。
• CoreML：苹果生态专用。

导出 ONNX 的命令：

python export.py --weights runs/train/exp01/weights/best.pt --include onnx --img 640 --batch 1

导出时--img和--batch要和推理时保持一致，动态 batch 需要额外加--dynamic参数。导出后建议用 onnxruntime 跑一遍验证输出是否一致，别等到部署环境才发现问题。

提示：导出 TensorRT 时如果报错，多半是 TensorRT 版本和 CUDA 不匹配，先确认版本对应关系再排查代码。

4.3 推理脚本与后处理

YOLOv5 自带detect.py可以直接推理：

python detect.py --weights best.pt --source data/images --conf-thres 0.25 --iou-thres 0.45

如果要在自己的代码里调用，用torch.hub加载最方便：

import torch model = torch.hub.load('ultralytics/yolov5', 'custom', path='best.pt') results = model('test.jpg') results.print() results.save()

后处理这块，YOLOv5 的输出是三个尺度的特征图，需要做解码和 NMS。自己写后处理时最容易错的是坐标还原，记住输出坐标是相对特征图的，要乘回原图尺度。另外 NMS 要在类别维度上分开做，别把所有类别的框混在一起抑制。

4.4 推理加速的实用手段

推理慢是部署时最常见的抱怨。加速手段按投入产出比排序：

1. 降输入尺寸：从 640 降到 416 或 320，速度提升明显，精度损失可控。
2. 换小模型：从 s 换到 n，速度翻倍，适合对精度要求不极端的场景。
3. 半精度推理：FP16 推理在支持硬件上能提速近一倍，精度损失很小。
4. TensorRT 加速：NVIDIA 平台上收益最大，但转换有成本。
5. 批处理：一次推理多张图，摊薄单张开销，适合离线分析。

我一般先试降尺寸和半精度，这两个改动小、见效快。TensorRT 留到最后，因为转换和调试成本高，不是所有场景都值得。

5. 常见问题排查与避坑实录

5.1 训练阶段的典型故障

显存溢出（OOM）是最常见的。报错信息一般是CUDA out of memory。解决顺序：先降 batch，再降 img 尺寸，最后考虑换小模型。别一上来就换模型，很多时候降 batch 就够了。

loss 出现 NaN通常是学习率太大或者数据里有异常值。先降学习率，再检查标注文件里有没有坐标超出 0 到 1 范围的脏数据。

训练卡在第一个 epoch 不动多半是数据加载的问题。检查图片路径、标注文件是否一一对应，有没有损坏的图片文件。我遇到过一次是某张图片的 EXIF 信息导致读取异常，删掉就好了。

5.2 推理阶段的典型故障

检测框偏移或错位一般是预处理和后处理的尺寸变换不一致。训练时用了 letterbox 填充，推理时也要用同样的方式，否则坐标对不上。

类别索引错乱是数据配置文件的names顺序和标注时的类别索引不一致导致的。这个错误很隐蔽，模型能跑但结果全错，一定要在训练前核对。

推理速度远低于预期先确认是不是在用 GPU。很多人装的是 CPU 版 PyTorch，推理自然慢。用前面那段验证代码确认一下。

5.3 效果不达标的排查路径

效果不好时，按这个顺序排查，能覆盖大部分情况：

1. 看数据：抽样看标注框是否准确，类别是否均衡，有没有漏标。
2. 看训练曲线：判断是欠拟合还是过拟合。
3. 看混淆矩阵：定位是哪几类出了问题。
4. 看误检样本：把误检的图挑出来看，找共性。
5. 调后处理：置信度阈值和 NMS 阈值往往能救回不少指标。

我踩过最深的一个坑是：模型训了很久 mAP 上不去，最后发现是验证集里混进了训练集的图，指标虚高，实际部署效果差。所以数据划分一定要严格，最好用脚本自动划分并记录清单。

5.4 一份速查表

提示：每次改动只动一个变量，改完记录结果。目标检测调参是个系统工程，变量一多就说不清是谁的功劳。

6. 工程化落地的一些实战心得

6.1 数据闭环比模型更重要

做落地项目久了会发现，模型结构带来的提升是有限的，数据质量带来的提升是持续的。我现在的习惯是：上线后持续收集误检和漏检样本，定期回流标注，形成数据闭环。一个能持续迭代数据的流程，比一次训出高分模型有价值得多。

具体做法是：推理时把低置信度的框和人工复核结果都存下来，定期筛选出高价值的难例补充进训练集。这个过程不需要很复杂，一个简单的脚本加人工复核就能跑起来。

6.2 版本管理与可复现性

每次训练都要记录：代码版本、数据版本、超参数配置、随机种子。YOLOv5 每次训练会在runs/train/exp下保存配置和权重，但数据版本它管不了。我建议给数据集打版本号，用 git 或者简单的目录命名管理，保证任何一次训练结果都能复现。

随机种子这块，YOLOv5 默认不固定，同样的配置两次训练结果会有差异。如果要做对比实验，记得固定种子，否则结论不可靠。

6.3 部署环境的差异要提前验证

训练环境和部署环境往往不一样。训练用 GPU 服务器，部署可能是边缘盒子或者 CPU 服务器。这种差异会导致精度和速度都和预期不符。我的做法是：训练完先在目标硬件上跑一遍推理，确认精度损失在可接受范围内，再决定要不要做量化或者格式转换。

量化这块要谨慎，INT8 量化能大幅提速，但精度损失因场景而异。建议先做量化感知训练或者用校准集验证，别直接上训练后量化就上线。

6.4 一个容易被忽视的细节：类别不平衡

实际项目里类别不平衡太常见了。某个类别样本特别少，模型就学不好。解决办法有几个：过采样少数类、在损失里加类别权重、或者用 focal loss 之类的机制。YOLOv5 本身没有直接暴露类别权重参数，但可以通过复制少数类样本的图片和标注来实现过采样，简单有效。

我在一个缺陷检测项目里，某类缺陷只有几十个样本，直接训出来 recall 极低。后来把这类样本复制了五倍，recall 从 0.4 提到了 0.75，代价是这类别的误检略微上升，但业务上可以接受。

6.5 关于模型融合的一点经验

如果单模型效果卡住了，可以试试模型融合。最简单的做法是训几个不同种子或者不同增强配置的模型，推理时对框做加权融合（WBF）或者 NMS 融合。YOLOv5 生态里有现成的融合脚本，效果通常能涨一两个点 mAP。代价是推理成本翻倍，适合对精度要求高、对延迟不敏感的场景。

融合不是万能的，如果几个模型犯的是同样的错误，融合也救不回来。所以融合前先看各模型的误检样本有没有互补性，有互补才值得融。

6.6 长期维护的建议

模型上线不是终点。业务场景会变，数据分布会漂移，模型效果会慢慢衰减。建议建立定期评估机制，比如每月用新采集的数据跑一遍评估，指标下降超过阈值就触发重新训练。这套机制不需要多复杂，关键是有人盯、有流程。

另外，模型文件、配置文件、预处理代码要打包在一起管理，别出现"模型换了但预处理没换"这种低级错误。我见过一次线上事故，就是推理服务用的还是旧版的归一化参数，导致输入分布不对，检测结果全乱。

7. 从实战出发的几点补充

7.1 小目标检测的专项优化

小目标一直是检测的难点。除了提高输入尺寸，还有几个实用手段：一是用切片推理，把大图切成小块分别检测再合并，适合航拍、遥感这类场景；二是在数据增强里增加小目标的复制粘贴；三是调整 anchor 尺寸，让 anchor 更匹配小目标。YOLOv5 的 anchor 是聚类得到的，如果你的数据集目标尺寸分布和 COCO 差异大，可以重新聚类 anchor。

重新聚类 anchor 的脚本 YOLOv5 里有提供，跑一下就能得到适配你数据的 anchor 尺寸，替换到配置文件里即可。这个改动成本低，有时候能带来意外的小目标提升。

7.2 标注质量的自动化检查

人工标注难免出错，我习惯写个脚本做自动化检查：检查坐标是否越界、框的宽高是否过小、类别索引是否超出范围、图片和标注是否一一对应。这些检查能在训练前拦下大部分脏数据问题，省去很多排查时间。

脚本不复杂，遍历标注文件做几项断言就行。我把它做成了训练前的必跑步骤，养成习惯后能避免很多莫名其妙的训练异常。

7.3 推理服务的工程细节

如果要把模型做成服务，几个细节要注意：模型加载只做一次，别每次请求都加载；预处理和后处理要和多线程配合好，别让 CPU 成为瓶颈；批量推理要设超时，避免请求堆积。这些是工程层面的东西，和模型本身无关，但直接影响线上体验。

我一般用简单的 HTTP 服务封装，配合连接池和请求队列。如果并发高，考虑用异步框架或者专门的推理服务框架。这块展开能写很多，核心原则是：模型推理是计算密集型，服务封装要考虑资源隔离和背压控制。

7.4 关于预训练权重的使用建议

预训练权重能显著加速收敛，但不是所有场景都适用。如果你的数据集和 COCO 差异极大（比如医学影像、工业缺陷），预训练权重的收益会打折扣，甚至可能带来负迁移。这种情况下可以试试冻结 backbone 先训 head，再解冻全量微调，或者干脆从零训练。

判断标准是：先跑一版用预训练权重的，再跑一版从零训练的，对比收敛速度和最终指标。大多数自然图像场景预训练权重都有明显优势，特殊领域则要实测。

7.5 训练日志的阅读技巧

训练日志信息量很大，新手容易看花眼。我的建议是重点关注几个关键行：每个 epoch 结束时的 mAP 汇总、各类别的 precision 和 recall、以及 loss 的三个分量。其他的细节可以忽略。

如果发现某个 epoch 指标突然暴跌，先别慌，看看是不是学习率调度到了某个节点，或者数据加载出了问题。偶发的波动很正常，连续多个 epoch 下降才需要干预。

7.6 一个实用的调试技巧

调试检测模型时，把中间结果可视化出来非常有用。比如把数据增强后的图片和标注框画出来看，确认增强没有把目标裁掉或者变形过度；把模型预测的原始框画出来看，确认解码逻辑正确。这些可视化能帮你快速定位问题出在数据、模型还是后处理。

YOLOv5 自带可视化工具，也可以自己用 OpenCV 画。我习惯在训练前先可视化一批增强后的样本，确认没问题再开训，这个习惯帮我避免过好几次数据增强配置错误的问题。

7.7 硬件选型的现实考量

最后说下硬件。训练和推理的硬件需求差别很大。训练看重显存和算力，推理看重延迟和功耗。如果只是学习练手，一张中端显卡足够；如果要落地到边缘设备，选型时要考虑功耗、散热、接口这些工程因素，不能只看算力参数。

我见过不少项目在服务器上训得好好的，换到边缘盒子上精度掉一截、速度也不达标，最后不得不重新选型。所以硬件选型要趁早，最好在数据准备阶段就把目标硬件定下来，训练时就用对应的输入尺寸和精度做验证。

图像识别这条路上，YOLOv5 是个很好的起点，但真正把项目做扎实，靠的是对数据、训练、部署每个环节的细致打磨。我个人的体会是，模型本身能带来的提升有限，把数据闭环和工程细节做好，才是效果稳定的关键。上面这些内容都是我在实际项目里反复验证过的，你可以直接拿去对照自己的场景调整，遇到具体问题再针对性排查，比盲目调参高效得多。