企业官网建设流程全解析

很多刚接触目标检测的朋友，第一次听到YOLOv5这个名字，总觉得这是个高深莫测的东西，得先啃一堆论文、理解一堆网络结构才行。其实完全不是这么回事。这篇文章不打算讲复杂的算法推导，也不打算让你手写网络代码，要做的只有一件事：带着你从零开始，把PyTorch环境搭起来，把YOLOv5代码仓库拿下来，再下载好官方训练好的权重，然后复制一行命令，就真的能把目标检测模型跑起来。

这套流程我反复跑过很多次了，踩过不少坑，最后简化成一套“傻瓜式”操作。如果你只是想亲眼看到目标检测是怎么框出人、车、猫、狗的，或者想给手头项目做一个视觉基础能力验证，那这篇就是给你准备的。整个过程中花时间最多的其实不是模型本身，而是环境和版本问题，只要把这一步理顺，后面基本是一路畅通。

1. 先说结论：为什么PyTorch + YOLOv5适合快速上手

1.1 这套组合到底解决了什么问题

目标检测要做的事情，简单说就是“找到图片里有什么物体，以及物体在哪里”。传统做法用滑动窗口加分类器，慢而且效果差。YOLO这类算法思路完全不一样，它把整张图直接喂进网络，一次前向传播就同时输出物体类别和框坐标，所以速度非常快，名字里“You Only Look Once”就是这个意思。

那为什么选择YOLOv5，而不是YOLOv8、DETR、SSD这些？原因很现实：YOLOv5的代码封装得极度友好，项目里有完整的detect.py、train.py、requirements.txt，基本上你只要把环境配好，直接命令就能跑。相比之下，很多新算法的代码依赖更复杂，动不动需要编译或者额外的系统库，对新手来说光是构建环境就能劝退。

PyTorch这边的优势也很明显。它默认动态图机制，调试时随时可以打印中间结果，出了问题报错信息相对容易理解，社区资料铺天盖地。虽然TensorFlow也很强，但遇到环境问题时，PyTorch的解决成本通常更低。对于“先跑起来、再深入理解”的学习路线来说，这个组合是最省心的。

1.2 整体流程就三步，别多想

拎清楚整个流程之后你会发现，所谓的搭建环境无非是三件事：

1. 装好Python环境，最好用虚拟环境隔离。
2. 安装对应你硬件的PyTorch版本。
3. 把YOLOv5代码和权重文件准备好。

这三件事做完，“模型跑起来”就是一条命令的事。后面真正花时间的，反而是在下载大文件和排错上。所以我会把命令一步不落地写出来，也会把容易踩的坑提前标记清楚。

2. 环境搭建：20分钟搞定PyTorch环境，不折腾

2.1 先定Python版本和环境管理工具

我强烈建议你不要直接装在系统自带的Python里，那样装其他包很容易把环境搞乱，甚至把系统工具弄坏。建一个独立的虚拟环境，以后想怎么折腾都行。这一步我用的是conda这类环境管理工具，它同时能把Python版本锁死，避免多个项目互相打架。

操作逻辑是这样的：新建环境、指定Python版本、进入环境。我给Python选的版本是3.9，不是最新的3.12，原因很简单：YOLOv5和PyTorch生态对3.9的兼容性经过大量验证，换新版本很容易遇到某个依赖库还没适配的情况。入门阶段没必要追新，稳定才是第一位的。

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

装完之后，最好确认一下当前环境是不是正确的，终端里输入conda activate yolo后，命令行前面会出现环境名。这一步很多人跳过，结果后面安装的所有包都装到了系统Python里，运行项目时才一脸懵。检查方法很简单：

python --version

看到输出Python 3.9.x，说明环境没进错。

2.2 pip换源：提前解决下载慢的问题

如果直接装依赖，默认源在国外，速度可能很慢，尤其在下载大文件的时候急死人。所以我习惯在装任何东西之前，先把pip默认源换成国内访问更快的镜像源。

pip config set global.index-url https://<你所在网络访问更快的镜像源地址>/simple

如果你网络本身很通畅，这一步完全可以跳过。判断标准很简单：先直接执行安装命令，如果发现进度条卡住不动，或者速度长期低于几百KB，再回来换源。别一上来就纠结源，很多坑要实际遇到了才需要处理。

换完之后可以通过pip config list检查一下配置是否生效。这里要特别提醒：别把镜像源写到系统配置里污染全局环境，刚才那条命令已经是写在用户配置里了，对系统其他Python环境影响很小，这点不用担心。

2.3 安装PyTorch：先搞清楚你要CPU版还是GPU版

PyTorch的安装命令不是随便抄的，它和你电脑的显卡强相关。很多人就在这一步翻车，装了CPU版，结果后面跑模型比蜗牛还慢，或者装了GPU版，却因为驱动版本不对，运行时报CUDA错误。

先检查你的机器有没有NVIDIA显卡，打开任务管理器或者设备管理器看一眼就行。如果没有独立NVIDIA显卡，也不需要纠结，直接装CPU版，照样能跑模型，只是速度慢一些，YOLOv5用小模型处理单张图片CPU也是可以接受的。

有NVIDIA显卡的，先确认驱动装没装好。命令行里敲：

nvidia-smi

能看到显卡信息和驱动版本，就说明驱动OK。这时到PyTorch官网的安装选择页面，根据系统、安装方式和CUDA版本生成安装命令。如果你不清楚CUDA版本，我告诉你一个稳妥原则：选最新那个CUDA版本对应的命令，因为新版本PyTorch通常兼容较新的驱动。

以常见的pip安装方式为例，CPU版本这样装：

pip install torch torchvision torchaudio

GPU版本则类似这样：

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

这里的cu118表示CUDA 11.8版本，实际以官方生成命令为准。很多人会纠结“是不是必须提前装完整版CUDA”，其实不需要。PyTorch的GPU版本自带运行时依赖，你只需要保证NVIDIA驱动版本不是太老就够了。

2.4 环境验证：这一步必须做，别省

装完PyTorch之后，我建议你花一分钟做个检测，确认这个环境真的能用。直接执行：

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

如果第二行打印True，说明你的PyTorch已经能用上显卡了。如果打印False，说明装成了CPU版或者驱动有问题。这里有个容易让人误判的情况：torch.__version__显示正常，但torch.cuda.is_available()是False，那可能装的就是CPU版，或者CUDA版本不匹配。先重新确认安装命令里有没有cu118或者cu121这类标识，没有就说明装错了。

这段检测是整个流程的“安全闸门”，我现在每次搭建环境都会先把这行跑了再继续，宁可在这里多花三分钟，也不要到后面跑模型的时候被各种奇怪的报错反复折磨。

3. 把YOLOv5代码和权重拿到手

3.1 获取代码：clone官方仓库是最省心的方式

环境没问题之后，接下来就是准备YOLOv5项目本身。最直接的方式就是从官方代码仓库拉取源码。找个你喜欢的目录执行：

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

如果没有安装git，也可以直接在代码托管平台的网页上把项目下载成zip压缩包，解压到本地。这里有个小细节，下载完会发现项目目录里有一堆文件，新手不用全看懂，核心文件就几个：detect.py是跑检测的入口，train.py是训练入口，requirements.txt记录了所有Python依赖包，data目录里放着测试图片，yolov5s.pt这类权重文件后面才会出现。

如果你决定用git clone，拉取完成后在终端进入项目目录：

cd yolov5

之后的命令都要在这个目录里执行，否则会提示找不到detect.py。这个“当前目录不对”的问题，是新手上路最常见的报错来源。

3.2 安装依赖：requirements.txt直接一把梭

YOLOv5项目把所有需要的依赖都写在了requirements.txt里面，所以安装非常傻瓜式：

pip install -r requirements.txt

这条命令会装上OpenCV、numpy、matplotlib等一系列依赖。它会检查缺失的包，如果之前已经装了，会自动跳过。刚装完PyTorch后再执行这条，会很贴心地发现torch已经满足要求，不会重复装。

这里有一个值得注意的点：requirements.txt里对torch和torchvision的版本是有最低要求的，如果你Python版本太新或者PyTorch版本太旧，命令行会提示版本不满足。遇到这种情况，千万不要直接手动升级torch，否则可能把之前环境弄坏。更稳的做法是新建环境后，按2.3节的方式装一个比较新的PyTorch版本，再回到这个项目目录安装剩余依赖。

依赖安装过程中，最容易出现的错误就是某个包编译失败。大多数情况下，更新到新版pip可以解决：

pip install --upgrade pip

然后再运行一次pip install -r requirements.txt。

3.3 下载权重文件：yolov5s.pt是首选

模型跑起来必须有权重文件，也就是已经训练好的“大脑”。YOLOv5有多个不同尺寸的预训练模型，最常见的是yolov5s.pt，体积小、速度快、精度也够用，是我的首选推荐。其他还有yolov5n（更小更快）、yolov5m、yolov5l、yolov5x（更大更准），后续可以按需更换。

实际上，你不需要手动去下载权重，因为执行检测命令时，如果当前目录没有权重文件，detect.py会尝试自动下载。但这个自动下载过程经常因为网络原因非常慢或者直接失败。所以稳妥起见，我建议从YOLOv5的官方Release页面手动把yolov5s.pt下载下来，直接放进项目根目录。文件大概十几MB，下载速度通常远好过终端里的自动下载。

放好文件后，执行下面这个命令检查一下：

ls -lh yolov5s.pt

能看到文件且大小正常，权重这一关就算过了。

4. 模型跑起来：一张图快速验证目标检测

4.1 最小命令：一行代码跑通全流程

到了最关键的时刻。在项目目录下，执行：

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

这条命令会加载yolov5s.pt权重，对自带的bus.jpg图片做一次检测。如果一切顺利，终端会打印检测出的物体类别和置信度，比如“2 persons”、“4 buses”之类的信息，然后在项目目录下自动生成一个runs/detect/exp文件夹，里面放着标注了检测框的结果图。

我第一次跑通的时候，说实话有点兴奋，代码没写几行，一张图里的行人和公交车就被框出来了。从环境搭建到这一步，如果中途没有卡壳，基本在半小时内可以完成。这也印证了那件事：目标检测模型跑起来，真的没有想象中那么复杂。

如果你想把结果窗口弹出来亲眼看一下，加一个参数：

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

加了--view-img之后，程序会弹出一个窗口显示检测结果，按任意键关闭。要注意，如果是在远程服务器上执行，没有图形界面，这个窗口是弹不出来的，会报错，那就别加这个参数，直接看保存的结果图片。

4.2 核心参数解读：别只会上传文件

detect.py的可调参数非常多，但你没必要全记，先把这几个搞懂，就已经覆盖90%的日常用法了。

这里重点说一下--conf-thres。如果你检测小目标或者模糊图片，发现框变少了，很可能不是模型失效，而是这个阈值设得太高。初学者经常以为置信度越高越准，于是改成0.7或者0.8，结果什么都检测不出来。我建议先用默认的0.25跑一遍，再根据实际效果适当调整，而不是一开始就调高。

4.3 结果输出在哪里：runs/detect目录

跑完检测后，项目根目录下会出现一个runs文件夹，每次运行都会新生成一个exp、exp2、exp3这样的文件夹，避免覆盖上一次的结果。结构大概是：

runs/detect/ ├── exp/ # 第一次运行的结果 │ └── bus.jpg ├── exp2/ # 第二次运行的结果 │ └── bus.jpg └── exp3/ # 第三次运行的结果

如果你连续跑了多次，不确定哪一次的结果是最新的，直接看文件夹序号最大的就行。另外，当参数--save-txt打开时，同一个输出目录下还会多出对应图片名的txt文件，里面是每个检测目标的类别id、中心点坐标、宽高，方便做后续统计或训练数据整理。

还有个小坑，如果你不想让结果文件越积越多，可以在下次运行前加--project和--name参数，自定义输出目录。比如：

python detect.py --weights yolov5s.pt --source data/images/bus.jpg --project runs/myresult --name test

这样结果就固定保存在runs/myresult/test里，比每次都找exp5、exp6舒服很多。

4.4 跑视频和摄像头目标检测：玩法一下就打开了

单张图片只是开胃菜，真正有意思的是把模型用到视频和摄像头实时画面上，这也是“目标检测跑起来”最有成就感的场景。

视频文件检测的命令不复杂：

python detect.py --weights yolov5s.pt --source test.mp4 --view-img

程序会把视频逐帧检测，然后一边弹窗播放，一边在runs/detect/expN下保存一份带标注的视频文件。注意点来了：如果视频文件很大，检测速度就可能跟不上视频本身的速度，你会看到画面一卡一卡的，这不是死机，是模型在逐帧计算。解决办法是把--conf-thres调高一些，减少不必要的计算，或者换更小的模型如yolov5n.pt。

摄像头实时检测也是同一套逻辑，把--source改成摄像头设备编号就行：

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

0代表电脑默认摄像头。如果你的电脑有多个摄像头，想用第二个，就把0改成1。跑实时检测时，第一次运行会自动加载权重，需要几秒钟初始化，窗口可能会短暂黑屏，这时候别着急关，稍等一下就出画面了。

这里要提醒一个我踩过的坑：在跑摄像头检测时，如果--view-img弹窗画面卡住不动，同时终端没有打印任何新的检测信息，大概率是摄像头被其他软件占用了，比如正在开视频会议。关掉占用摄像头的应用再跑，就正常了。

5. 模型选择与设备适配：跑起来之后还能怎么折腾

5.1 不同尺寸模型怎么选，别盲目追求大模型

YOLOv5官方提供了多种预训练模型，名字里的n、s、m、l、x代表模型越来越复杂，精度越来越高，但速度和资源消耗也逐渐增大。很多新手一上来就想用最大的模型，结果显卡显存不够，或者速度慢得不可忍受。

给一个直观对比，方便你按机器选择：

我的建议是：入门和日常演示老老实实用yolov5s，你真的把整个流程跑通之后，再根据实际场景去试其他尺寸。换模型只需要改--weights参数，其余逻辑完全不变。比如：

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

5.2 没有显卡，CPU能不能玩

很多人的电脑没有独立NVIDIA显卡，就觉得不能玩目标检测了，这其实是个误解。CPU完全可以跑YOLOv5，只是速度慢一些，但只要不追求实时视频检测，处理单张图片是完全够用的。

跑CPU版时，命令里加上设备指定：

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

实测下来，一张正常分辨率的图片，用yolov5s在主流CPU上大约需要几秒到十几秒的时间，完全可以接受。如果不指定--device cpu，CPU设备上默认也会用CPU，但明确写出来心里更有数，也能避免某些奇怪报错。

如果你的机器是Apple芯片的Mac，可以尝试用MPS加速，PyTorch已经支持了。安装好对应版本后，把--device指定为mps，速度会比纯CPU快不少。不过YOLOv5的某些组件对MPS兼容还不算完美，遇到报错再退回CPU就行。

5.3 用自己的图片和视频，这些细节先处理好

用自带测试图跑通之后，大多数人马上想试自己的图片。这里有几个小坑，提前避开能省很多时间：

第一，路径不要太花哨。我的建议是图片名和路径里不要出现中文或空格，直接叫test1.jpg，放在项目目录或data/images下。YOLOv5对中文路径的支持时好时坏，有人明明模型没问题，结果因为中文路径读不出图片，排查半天才发现是这个原因。

第二，--source参数可以直接传文件夹路径，批量检测整个目录里的图片。比如：

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

程序会自动处理文件夹内所有图片，输出结果也保存在同一个exp文件夹下。这个功能在处理大量图片时非常省事，不用一张张跑。

第三，检测图片时如果什么都没框出来，先检查图片内容是否清晰，目标是不是特别小或者特别密集。不要第一时间怀疑环境坏了，先跑一遍自带bus.jpg确认环境没问题，再回来调整自己的图片。

6. 常见问题与排查实录：踩坑记录整理

6.1 环境类问题速查表

我接触过很多刚入门的读者，也看过无数报错截图，整理下来发现大部分问题都高度相似。下面这几个问题占了日常报错的八九成，直接对照处理就行。

这里面最坑的是CUDA out of memory，因为它不只是报错那么简单，还会让你怀疑是不是代码有问题。实际上只要换个小模型，或者关掉弹窗，问题立刻消失。我以前跑yolov5x，一张高分辨率图片都能把显存撑爆，后面学乖了，入门阶段用s模型，省心。

6.2 检测效果差：先别怪模型，先检查这三个点

模型跑起来了，但检测结果不理想，这种情况通常不是模型坏了，而是用法问题。我排查这类问题有一个固定顺序：

第一，置信度阈值是不是调太高了。如果图里只有一个非常自信的结果才被保留，漏检就难免了。回到--conf-thres 0.25，甚至调到0.1看看效果。

第二，图片里的目标是不是太小。YOLOv5对小目标检测能力有限，尤其是密集小目标，比如一张远处的人群照片。这时候要么把图片切割成几块分别检测，要么换更大的模型yolov5x，但代价是速度变慢。

第三，预处理问题。图片是不是严重模糊、过暗，或者被拉伸变形。有的用户拿来的图片是从监控视频里截取的，模糊得厉害，模型自然识别困难。这种场景下可以先做简单的清晰化处理再检测。

另外还有一类特殊情况：检测类别里没有你想要的目标。YOLOv5官方权重是80类模型，识别人、车、猫、狗、电视等常见物体没问题，但如果要检测某个特定工业零件或者特殊包装产品，就必须自己训练数据，光靠预训练权重是做不到的。

6.3 三个提高成功率的小技巧，亲测有效

最后一个部分，分享三个我自己积累下来的实操技巧，可以帮你少走很多弯路。

第一个技巧：环境搞坏了不要原地修补，直接新建一个环境。很多人遇到PyTorch版本不对，就在原环境里反复升级降级，最后依赖彻底乱掉。我现在遇到环境问题超过十五分钟解决不了，就会直接conda create新环境，从头再来。反正环境创建成本极低，编译才是浪费时间。

第二个技巧：跑任何检测之前，先检查nvidia-smi能不能看到显卡，再检查torch.cuda.is_available()是不是True。这两个检查加起来不到十秒钟，却能排除大量“看起来像代码问题”的隐患。不要一报错就怀疑YOLOv5的代码，大部分报错都是环境和路径问题。

第三个技巧：保底项目目录干净整洁。YOLOv5项目本身不大，但跑出来的runs结果、下载的权重、你自己的测试图片，都会堆在根目录下。时间长了容易混乱。我习惯是把测试素材单独放data/mytest/文件夹，权重文件统一放weights/子目录，每次运行命令时把--weights weights/yolov5s.pt和--source data/mytest/xxx.jpg写清楚，既好找也不容易搞混。

最后再分享一个体会。这个流程我从第一次摸着石头过河，到后面帮别人搭环境，整体步骤基本没变过，变的只是版本和命令细节。新手最需要的不是一口气吃透所有模型原理，而是先亲眼看到模型在自己的电脑上跑起来，建立信心之后，再回头去啃那些概念，会轻松得多。如果你按照这个流程卡在某个步骤，那就把报错信息原样复制，对照上面的排查表一项项看，绝大多数问题都不需要别人帮忙就能自己解决。