企业官网建设流程全解析

先别急着pip install -r requirements.txt，我见过太多人在这一步开始翻车了。yolov5 的安装使用，说到底是 PyTorch 生态下的一套完整流程，环境、依赖、权重、推理、训练各有各的坑。这篇文章不和你聊理论推导，就讲实际操作。我会从环境准备、仓库获取、依赖安装，一直讲到第一次推理和训练自己的数据，把那些官方文档里一笔带过、但实际运行中十有八九会遇到的问题，按我自己的实测踩坑记录给你捋一遍。如果你是刚接触目标检测、准备在自己电脑上把 yolov5 跑起来的人，这篇基本能帮你省掉几天的折腾时间。

1. 装之前先把环境底子打对：Python、PyTorch 和显卡驱动的三角组合

1.1 版本矩阵不是玄学，是踩出来的

yolov5 本身对 Python 版本没有太多挑剔的说法，官方仓库里建议的是 Python 3.8 及以上，我个人在实际操作中觉得 3.8 到 3.10 是最稳的区间。太新的 Python 版本有时候会碰到某些依赖还没发布对应 wheel 包的情况，装起来要多费不少功夫。

真正的重头戏是 PyTorch 和显卡驱动的匹配。很多新手在这里犯迷糊：我先装了显卡驱动，为什么程序还是报 CUDA unavailable？因为你装的是驱动，驱动之上还得有 CUDA 工具包或者运行时库，而 PyTorch 又得和这个 CUDA 版本对上才肯用 GPU。

我建议你先在命令行敲一句nvidia-smi，看右上角的 CUDA Version，这是你当前驱动支持的最高 CUDA 版本。比如显示 CUDA 12.1，那你可以放心安装 cu121 版本的 PyTorch；如果显示 CUDA 11.8，那就老老实实找 cu118 的安装命令。强行上高版本的 PyTorch，跑起来会直接报错提示驱动版本太旧。

1.2 显卡情况不同，安装命令也不同

如果你的电脑有 NVIDIA 显卡，并且驱动版本支持 CUDA，那么推荐用官方源安装 GPU 版 PyTorch。实际使用中我用得比较多的是这个组合：

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

这里的 cu121 就是 CUDA 12.1 的意思。如果你的驱动比较老，比如最高只支持 CUDA 11.7，那你可以改成：

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

有一点要提醒你：网上很多教程直接让你pip install torch，这样装上的通常是 CPU 版本。CPU 版也能跑 yolov5，但推理速度和训练速度会慢一个数量级。性能差距有多大？我拿自己的机器试过，同样一张 640x640 的图，GPU 推理不到 0.1 秒，CPU 可能要两三秒，训练的时候差距更夸张。所以只要条件允许，尽量把 GPU 版装好。

1.3 没有 NVIDIA 显卡也没关系，CPU 模式怎么跑

没有独立显卡或者显卡不是 NVIDIA 品牌的，直接用默认的 PyTorch 包就行，装的时候没有 cu121 这种东西，就是最普通的pip install torch torchvision。运行 detect.py 的时候它会自动用 CPU，你不需要做额外配置，只是要接受一个事实：速度会比较慢，而且训练大规模数据集基本不现实。

另外还有个细节，很多人不看好。显卡驱动版本低不代表你完全不能用 GPU，PyTorch 有些版本对老的 CUDA 架构也做了兼容。但我建议不要太纠结这种边缘情况。新手阶段最省心的做法是：把驱动更新到官网提供的最新稳定版，然后再去安装对应较新 CUDA 版次的 PyTorch，这样能避开大多数莫名其妙的坑。

提示：安装完 PyTorch 后，第一件事就是检查 torch 能不能正常调用 GPU。命令很简单：python -c "import torch; print(torch.cuda.is_available())"。如果输出 True，说明环境已经通了一半。

2. 拿下代码仓库之后，先花十分钟看懂目录和依赖脚本

2.1 获取源码的两种方式，以及我推荐的路径

yolov5 的代码托管在开源社区，获取方式最常见的就是git clone：

git clone https://github.com/ultralytics/yolov5.git cd yolov5

如果你所在的网络环境访问这个地址比较慢，可以直接打开项目主页，下载 zip 压缩包到本地再解压。这个方式在慢速网络下往往比 git clone 更省心，因为浏览器下载可以断点续传，失败了重新点一次就行。我个人建议新手优先用 zip 方式，少折腾 git 本身的网络配置。

下载完以后别急着跑，先把项目根目录看一遍。yolov5 的目录结构并不复杂，但你如果不清楚哪些文件是干什么的，后面改参数的时候很容易改错地方。

2.2 目录结构里，这几个文件才是你真正要关心的

我把关键文件和它们的用途列一下，按使用频率排：

新手最容易犯的错，是跑去把data/coco128.yaml里的内容当成训练自己数据集的配置模板，直接改几行路径就当自己的数据用了。其实这个文件只是官方提供的入门示例，你真的有自己的数据集时，通常要单独建一个 yaml 文件，而不是在它上面改。

2.3 requirements.txt 别无脑全装，但也不能完全不管

requirements.txt里写的是 yolov5 运行所依赖的基础库：opencv-python、matplotlib、pyyaml、numpy、tqdm、torch、torchvision 等。如果你是照着官方流程安装，一行命令全装也有道理：

pip install -r requirements.txt

但如果你已经按第一部分的内容装好了 GPU 版 PyTorch，再跑这条命令的时候，它会检测到 torch 和 torchvision 已满足要求，不会重复安装，这点设计得还算人性化。

不过有一点要注意：requirements.txt里列的版本号是官方在某一个时间点测试过的组合。如果你的环境里已经存在其他项目需要特定版本的 numpy 或 opencv，直接装可能会产生版本冲突。我的处理方式是：先看一遍文件内容，把明确会冲突、我又用不到的一两个库注释掉，只装必要的部分。实际用下来，只要 torch、torchvision、opencv-python、pyyaml、numpy、tqdm 这六个到位，yolov5 的核心功能就能跑起来。

3. 依赖安装最容易翻车的三个环节和自检方法

3.1 这几个坑，我在不同机器上都碰到过

第一个坑是 opencv 相关的问题。有几次我pip install -r requirements.txt装完以后，运行detect.py报错说缺少cv2，细看才发现是安装过程中 opencv-python 的下载源不稳定，安装中断了。这时候不要整包重装，单独执行pip install opencv-python就行。

第二个坑是 numpy 版本问题。yolov5 依赖的 numpy 版本如果和 torch 自带的要求冲突，往往会出现类似A module that was compiled using NumPy 1.x cannot be run in NumPy 2.x这样的提示。解决办法不是去折腾 numpy，而是保持 requirements.txt 里的版本约束，让 pip 自动帮你调整。

第三个坑是 PyTorch 装成了 CPU 版本。很多人用的是国内镜像源装 torch，结果下载的是 CPU 版。检测方法很简单：跑一下python -c "import torch; print(torch.version.cuda)"，输出是None就是 CPU 版，需要按第 1 章的方式重装 GPU 版。这里我不要迷信网上给出的所谓通用命令，一切以你自己的nvidia-smi结果为准。

3.2 装完以后，先跑一条自检命令

依赖装好、torch 能调用 GPU 之后，别急着改代码，先用官方自带的示例数据做过一遍完整流程。这个命令是我每次新环境必跑的：

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

第一次跑的时候大概率会遇到一个卡点：联网下载yolov5s.pt权重文件。这一步和网络环境关系很大，所以我把这个问题的完整解决方案放在下一节单独说。

如果这条命令顺利跑完，你会在runs/detect/exp目录下看到一张画了检测框的bus.jpg，说明整条链路已经通了。到现在为止，你的环境准备阶段算是真正结束。

4. 权重文件下载失败：这个老问题可以这样解决

4.1 为什么会卡在下载权重这一步

yolov5 的模型权重文件和仓库是分离的，需要从项目的 release 页面单独下载。官方命令会在你第一次运行detect.py或者train.py时自动尝试下载权重，但这一过程在部分地区网络环境下经常失败。具体表现就是终端卡在下载进度条上一动不动，或者下载到一半报连接超时。

很多新手在这里反复重跑，结果每次都在同一位置卡死，就以为是自己安装有问题。实际上代码本身没有毛病，单纯就是网络访问不顺。权重文件不像依赖包那样可以通过换镜像源来解决，因为官方只有 release 下载这一条主路径。

4.2 手动下载与放置的完整流程

我的处理逻辑很简单：既然自动下载走不通，就手动把权重文件找下来。具体步骤是：

1. 打开浏览器，访问 yolov5 项目仓库的 release 页面，找到最新版本对应的资产列表。
2. 在资产列表里找到yolov5s.pt，点击下载。如果直接下载失败，就换浏览器或者用支持断点续传的下载工具重试。
3. 下载完成后，把文件放到 yolov5 项目的根目录下。

放好之后，再运行一遍自检命令：

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

这次不会再触发下载流程，直接就能加载本地权重。我实测过，这种方式在某些网络环境下比自动下载稳定得多，基本等几秒到十几秒就能拿到文件。

提示：下载完成后先看一眼文件大小，yolov5s.pt大约 14MB 左右，如果只有几十 KB，多半是下载到了错误页面，加载时会报Bad zip file，这时候删掉重下就行。别因为着急直接跑训练，否则后面报错你都不知道是权重文件的问题。

5. 第一次推理：命令行跑图和 Python 方式调用

5.1 命令行模式下的四个核心参数

yolov5 的推理入口detect.py参数很多，但新手第一阶段只需要掌握四个：

我给一个更完整的操作示例。识别一张图片，并把置信度阈值稍微调高：

python detect.py --weights yolov5s.pt --source data/images/zidane.jpg --conf-thres 0.5

识别一个文件夹里所有图片：

python detect.py --weights yolov5s.pt --source data/images/ --project results --name zidane_test

用摄像头实时检测就是把--source改成0：

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

这里有个经验：如果设备是 CPU 环境，建议显式加上--device cpu，防止某些环境下默认逻辑走了奇怪的路径，反而多出不必要的报错。

5.2 Python 接口：给后续工程化留一条路

命令行跑通了，接下来你会发现实际做项目的时候，更多时候希望在 Python 脚本里调用模型，而不是每次都用--source传参。yolov5 官方支持通过 PyTorch Hub 来调用，这是我很推荐的方式：

import torch # 第一次调用会加载模型结构，同时下载权重文件 model = torch.hub.load('ultralytics/yolov5', 'yolov5s', pretrained=True) # 推理 results = model('data/images/bus.jpg') results.show()

要注意的是，这种方式同样会触发权重下载。如果你之前已经手动下载过yolov5s.pt，建议把它放到项目根目录下，并且检查缓存目录，不然 hub 可能会重复下载。一个更稳妥的做法是，把网络问题绕开，直接用本地文件加载权重：

import torch # 加载本地模型 model = torch.hub.load('ultralytics/yolov5', 'yolov5s', pretrained=False) model.load_state_dict(torch.load('yolov5s.pt', map_location='cpu')['model'].float().state_dict()) model.eval() results = model('data/images/bus.jpg') results.pandas().xyxy[0]

这个写法适合你后续要封装成自己的服务接口时使用，能精确控制权重文件从哪里来，不受网络环境影响。第一次跑通推理以后，建议再用视频源测一次，确认结果能在results里同步输出。至于结果要存成什么格式，是通过results.save()还是直接拿到 numpy 数组，就看你的项目需求了，文档里都有现成说明。

注意：在 Python 里用 torch.hub 加载模型，本质上和命令行方式是一样的，但你需要注意版本一致性。如果你的torch和官方仓库的版本差异过大，hub 加载时可能报兼容性错误，这时把它换成项目内detect.py的方式更省心。

6. 训练自己的数据：从标注结构到参数调整的关键点

6.1 数据集格式是第一个门槛

yolov5 训练自己数据之前，你需要把数据整理成它认识的格式。结构上通常是这样的：

datasets/ ├── mydata/ │ ├── images/ │ │ ├── train/ │ │ └── val/ │ ├── labels/ │ │ ├── train/ │ │ └── val/ │ └── mydata.yaml

图片放在images/train和images/val，对应的标注信息放在labels/train和labels/val。每个标注文件是纯文本，和同名图片放在同一个子集目录里，文件名前缀保持一致，比如000001.jpg对应000001.txt。

标注格式上，每行代表一个目标框：

class_id center_x center_y width height

注意这里的前四个数字都是归一化值，范围在 0 到 1 之间，不是像素坐标。类别 ID 从 0 开始计数。比如我标注了一张包含猫和狗的图片，第一行写0 0.5 0.5 0.25 0.25，表示类别 0 的中心在图片正中间，宽高占图片的 25%。如果你以前用过 VOC 格式的 XML 标注，需要转换一下，这类转换脚本网上有很多现成的，我建议直接用成熟的开源转换工具，比自己写要稳。

6.2 data.yaml 配置文件怎么填

在datasets/mydata/目录下新建一个mydata.yaml，内容大致如下：

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

这里面的train和val路径要注意，是相对于你运行train.py时所在目录的路径。如果你把 yaml 和数据集都放在项目内，直接用相对路径最省心；如果用绝对路径，换台机器就得改一遍，不推荐。

最后执行训练命令，我用的是下面这行：

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

6.3 参数调整的核心逻辑：显存和时间的权衡

训练参数里边，batch-size是最容易爆显存的。显存不够时会直接报CUDA out of memory。我的建议是，8GB 显存从--batch-size 16开始试，如果爆了就降到 8 或者 4。--img默认 640，如果显存压力大可以降到 416，速度会快一些，但精度通常会有轻微下降。

--epochs是训练轮数。100 轮对小型自定义数据集基本够用。训练过程中你会发现，后面的 loss 曲线波动会慢慢变小，如果 100 轮跑完了 loss 还在明显下降，可以继续加轮数。判断训练效果好不好，直接看runs/train/exp/weights/best.pt，这是验证集上表现最好的权重，推理和部署都用它，而不是用last.pt。

关于--weights参数，有两个选择输入：一个是官方预训练模型，比如yolov5s.pt，这叫做迁移学习，能明显加速收敛；另一个是--weights ''，意味着从头训练，新手我不建议。除非你的数据分布和 COCO 差别非常大，否则从预训练权重开始训练永远是最省时间的路径。

提示：训练时默认是开启半精度（AMP）的，显存比较小的时候可以手动加上--amp保持开启，或者显存充足时用--no-amp关闭。我在 6GB 显存的机器上训练时，发现开启 AMP 后显存占用明显减少，没有观察到精度明显下降。

7. 从实测看 yolov5 使用中值得注意的细节

7.1 常见报错速查表

安装和运行过程中，你会遇到各种报错信息。我把频率最高的几个整理成一张表，方便你对照排查：

7.2 我的两个习惯：先搞定数据子集，再做完整实验

训练自定义数据的时候，我最常犯的错是直接拿全部数据开跑，结果跑了一晚上发现 loss 不降，或者指标特别差，最后才排查出是数据集路径配错了几十张图。后来养成了一个习惯：先拿很小一部分数据，比如 20 张训练图片和 5 张验证图片，把训练流程完整跑通一次，确认可以正常生成best.pt，再上全量数据。这能帮你把大多数低级错误挡在正式训练之前。

另一个习惯是尽量保持 yolov5 仓库代码不变动，不自己改源码。如果实在要改，比如想修改detect.py的输出格式，我建议另存新文件，不去动原本的入口。因为官方仓库更新频率不低，一旦拉了新版本代码或者切换分支，改动很容易被覆盖或者出现莫名的冲突。保持源码干净，后续排查问题会省力很多。

7.3 一次完整的“安装使用”闭环复盘

我拿一台干净环境的机器，把整个流程完整走了一遍，大致是这样：先确认显卡驱动和 CUDA 版本，装 GPU 版 PyTorch；获取项目源码后手动下载yolov5s.pt放到根目录；跑通detect.py自检；搭建一个小规模数据集，执行训练命令；训练完成后用best.pt重新跑推理。从零开始到拿到自己数据集的检测结果，大约花了一个多小时，其中大头花在环境安装和权重下载上，真正训练因为数据集很小，只花了十几分钟。

这个流程最大的启发是：yolov5 的安装使用并不复杂，坑大多集中在环境匹配、依赖冲突和网络下载这三件事上。你只要把这三件事处理妥了，后面就是按部就班的操作。等你有了一次完整闭环的经验，再往深了去调参、做模型压缩、转 ONNX，都会顺很多。我自己在后续接触其他目标检测框架时，也还经常拿这套环境排查思路去做参照，迁移起来相当顺手。