第一篇教程发出来之后有不少朋友留言问板子还没到或者RK3588的开发环境还没配好能不能先在电脑上把YOLOv5的流程跑通我的答案很明确能而且非常建议这么做。这篇教程就是干这件事的——在PC端把YOLOv5从环境搭建到检测出第一张图完整走一遍把代码链路、依赖关系、参数含义都摸清楚后面再上香橙派RK3588真机部署就会顺手太多。先说清楚为什么要把这一步单独拎出来。YOLOv5这玩意本身不复杂但部署到RK3588上会遇到一连串问题NPU驱动、rknn模型转换、交叉编译、内存带宽……这些坑如果不先在PC端把算法本身跑熟叠加在一起排查会让你怀疑人生。在PC仿真环境里把YOLOv5的“纯软件”部分吃透等于先把战场缩小到只处理“硬件适配”一个问题这就是这篇教程最大的价值。这个系列的实验环境是这么设计的PC端采用x86 LinuxUbuntu 22.04作为仿真平台Python环境用Anaconda管理PyTorch走CPU版本起步没有NVIDIA显卡也一样能跑目标检测模型用YOLOv5s官方权重。整个教程覆盖图片检测、视频检测、摄像头实时检测外加训练及验证流程的打通。整个过程不依赖香橙派硬件但每个操作都在为RK3588的后续部署做铺垫。1. 整体思路拆解为什么先PC仿真再上RK3588真机1.1 仿真阶段到底在“仿真”什么很多刚接触嵌入式AI的朋友有一个误区觉得“仿真”就是用软件模拟一个RK3588的芯片然后在里面跑程序。这个理解不完全对。真正做RK3588开发时确实有QEMU这类指令级模拟器可以模拟ARM64环境但用QEMU跑YOLOv5的体验极差——性能损失巨大一张图片推理可能要几十秒摄像头实时检测基本跑不动而且PyTorch对QEMU模拟环境的兼容性也一言难尽。我们这里说的“PC端模拟器仿真”指的是在PC的x86架构上把YOLOv5的完整算法链路跑通数据加载、模型加载、前向推理、NMS后处理、结果可视化。这套逻辑链和RK3588真机上跑的完全一致唯一的区别是底层计算单元不同PC用CPU/GPURK3588用CPU/NPU。在PC上先把这套逻辑吃透后面在RK3588上要做的事情就只剩两件一是把模型转换成RKNN格式二是把NPU推理的API调用接进来。算法层面不会再出问题。从开发策略角度看这也是标准的“先软后硬”流程。软件开发讲究快速迭代PC端的编译和调试速度、打印日志的便利度、第三方库的安装灵活度都远高于嵌入式环境。把YOLOv5的代码结构、检测效果、超参数影响都搞清楚之后再上真机就不会两眼一抹黑。1.2 这套方案避开了哪些实际问题直接拿香橙派RK3588开发板上手跑YOLOv5会碰到一堆和算法本身无关但又不得不解决的破事。拿我自己的经历来说光把PyTorch装到板子上就折腾了半天——系统自带的Python版本不匹配、pip源访问慢、OpenCV依赖冲突每一步都在消耗精力。更别提RK3588的NPU驱动和rknn-toolkit2的版本匹配问题稍不注意就是一堆红色报错。而在PC端仿真这些事情几乎不会发生。x86 Linux环境的软件生态非常成熟PyTorch的安装只需要一条pip命令国外源慢就换国内镜像OpenCV、NumPy这些依赖都有预编译包。整个环境的搭建时间压缩到1小时内非常可控。还有一层好处是成本。很多人可能还在观望要不要买香橙派或者已经买了但不想折腾坏板子。PC仿真阶段零硬件成本、零烧录风险哪怕把系统搞得乱七八糟大不了把conda环境删了重来完全不影响电脑原本的使用。等你确定这套流程能跑通、确实想继续深入的时候再入手板子也不迟。2. 仿真环境准备从零搭建YOLOv5运行环境2.1 Python虚拟环境与基础依赖安装环境搭建的第一步是准备Python环境。我强烈建议用Anaconda或者Miniconda来管理不要直接动系统的Python。原因很朴素YOLOv5对依赖版本有明确要求直接用系统的Python很容易把依赖装乱后面跑起来各种诡异报错。用conda隔离出一个专门的环境怎么折腾都不影响系统其他项目。打开终端依次执行以下命令创建虚拟环境# 创建名为yolov5的Python 3.9环境 conda create -n yolov5 python3.9 -y # 激活环境 conda activate yolov5为什么选Python 3.9而不是最新的3.11或3.12因为YOLOv5官方在README里明确写了Python 3.8但实际测试下来3.9是最好的平衡点——既满足所有依赖的版本要求又不会有太老的问题。PyTorch在3.9上的兼容性也是最好的。后面如果你要在RK3588上用rknn-toolkit2做模型转换它支持的Python版本也是3.8和3.9现在用3.9完全一致。接下来安装PyTorch。这里有个小技巧在没有NVIDIA显卡的情况下不需要装CUDA版本直接装CPU版本就行。CPU版本能跑完整个流程只是推理速度慢一点——一张640x640的图片在CPU上大概几百毫秒到一两秒完全够用来学习验证。# 安装CPU版本的PyTorch使用国内镜像加速 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu不想走默认源的话还可以用清华镜像pip install torch torchvision -i https://pypi.tuna.tsinghua.edu.cn/simple装完验证一下是否成功python -c import torch; print(torch.__version__)2.2 拉取YOLOv5源码与选择正确的分支版本YOLOv5的源码托管在GitHub上直接用git克隆就行。这里要提醒一句YOLOv5版本迭代非常快不同版本之间的接口会有细微差异教程里如果没说明版本很可能照着做就踩坑。建议在克隆时指定一个固定的发布版本——我推荐v7.0这是最稳定的一个版本网上能找到的资料也最多。# 克隆指定版本 git clone -b v7.0 https://github.com/ultralytics/yolov5.git # 进入目录 cd yolov5 # 安装依赖 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simplerequirements.txt里包含的是一整套运行依赖——OpenCV、NumPy、Matplotlib、Pandas、PyYAML、Torch等。这里我踩过一个坑直接无脑执行requirements.txt安装有可能装出依赖冲突。尤其是如果系统里已经有老版本的numpy或opencv-python新装YOLOv5的依赖时会报“Cannot uninstall XXX”之类的错误。解决方式很简单遇到冲突就强制重装# 强制重新安装冲突的包 pip install --force-reinstall opencv-python4.8.1.78 -i https://pypi.tuna.tsinghua.edu.cn/simple2.3 模型权重下载与验证YOLOv5的模型权重文件放在GitHub Releases页面也可以通过源码里自带的下载逻辑自动拉取。第一次运行detect.py时如果本地没有权重文件程序会自动尝试下载。但国内网络直连GitHub Releases经常失败或极慢建议手动先下载好。方法一直接浏览器或者wget下载。YOLOv5s的权重文件在github.com/ultralytics/yolov5/releases/download/v7.0/yolov5s.pt大约14MB。也可以用我前面提到的方式直接把权重文件放到yolov5项目根目录wget https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5s.pt方法二如果GitHub下载超时可以考虑从一些国内的AI模型镜像站找对应的权重文件注意验证文件MD5确保完整。YOLOv5官方权重文件的MD5可以查官方文档。下载完成后放在yolov5目录下运行一次检测验证环境是否正常python detect.py --weights yolov5s.pt --source data/images/bus.jpg如果看到类似“Saved results to runs/detect/exp”的输出说明整个环境已经通了可以去runs/detect/exp目录下查看检测结果图片。这一步完成你的PC仿真环境就基本就绪了。这里插一句关于weights路径的事情。YOLOv5官方权重里yolov5n是最轻量版本约4MByolov5s是通用版本约14MByolov5m、yolov5l、yolov5x依次增大检测精度也逐步提高。第一篇教程里先在PC上跑yolov5s足够了后续真机部署时我们也主要用yolov5s权重来做NPU转换因为它在RK3588上有着最好的精度和速度平衡。3. 实操全流程图片检测、视频检测、摄像头实时识别3.1 用官方权重跑通第一张图片检测环境搭好之后第一次跑通图片检测大概是最有成就感的时刻。先看命令的完整形态python detect.py --weights yolov5s.pt --source data/images/bus.jpg --conf-thres 0.25 --iou-thres 0.45这里面的参数拆开讲一下。“--source”指定输入来源可以是图片、视频、文件夹、摄像头ID或RTSP流。“--conf-thres”是置信度阈值默认0.25表示只有当模型预测某个物体类别的概率大于25%时才认为这是一个有效目标。这个值调得越低检测到的目标越多但误报也越多调得高则相反。“--iou-thres”是NMS的IoU阈值默认0.45决定重叠的预测框保留还是合并这个参数一般不需要动。运行成功后控制台会打印检测到的物体类别、置信度和坐标信息。比如bus: 4 persons, 1 bus, Done. (0.352s)输出结果图片会保存在runs/detect/exp/目录下。你还可以用“--project”和“--name”参数自定义输出目录多跑几次实验时能方便地对比不同参数下的检测效果python detect.py --weights yolov5s.pt --source data/images/bus.jpg --project runs/detect --name test01如果一张测试图不过瘾可以直接指定一个图片文件夹作为输入YOLOv5会批量处理python detect.py --weights yolov5s.pt --source /path/to/your/images --save-txt加上“--save-txt”参数会在输出目录里多存一份检测结果的txt文件格式是“类别 x_center y_center width height”的归一化坐标。你在RK3588上做后处理时也需要用这种坐标格式这里提前接触非常有帮助。3.2 视频检测与摄像头实时检测图片检测只是第一步视频检测才是更接近实际应用的场景。视频检测无非是把“逐帧检测”这个逻辑连续化但会暴露出一个关键性能指标——FPS。以一段测试视频为例python detect.py --weights yolov5s.pt --source test.mp4 --conf-thres 0.4在CPU环境下跑视频你大概率会看到FPS只有个位数这是正常的。CPU跑YOLOv5s推理一张640x640的图大约需要0.3到0.8秒换算下来就是1到3的FPS画面会非常卡顿。如果用NVIDIA显卡跑同样的模型FPS能轻松到60以上。这个性能差距就是后续你在RK3588上要解决的核心问题NPU的效率比CPU高多少决定了你的边缘设备能不能做实时检测。摄像头实时检测的命令也没什么不同把source参数从文件路径改成摄像头ID即可python detect.py --weights yolov5s.pt --source 0“--source 0”表示第一个USB摄像头。执行后程序会打开摄像头窗口实时显示检测框。如果你的电脑没有摄像头也可以用“--source 1”试第二个设备或者回退到视频检测。这里有个容易被忽略的细节视频检测和摄像头检测的口头禅参数“--view-img”。加了这个参数才会弹出可视化窗口不加的话程序只会静默处理后把结果保存下来。在远程SSH连接的环境里跑这个参数要记得去掉因为弹窗会直接报错python detect.py --weights yolov5s.pt --source 0 --view-img3.3 用自己的数据集训练YOLOv5模型在PC仿真阶段光用官方权重检测还不够强烈建议顺手跑一遍“用自己的数据集训练”的流程。因为后续在RK3588上部署自己的业务模型不可能用通用的coco类别必须要自己标注数据、训练模型。YOLOv5的数据集格式是最经典的——每个图像对应一个txt标注文件标注文件每一行是“class_id x_center y_center width height”坐标是归一化后的值0到1之间。推荐的目录结构如下datasets/ mydata/ images/ train/ val/ labels/ train/ val/目录准备好之后新建一个数据的配置文件命名为coco128.yaml之类的文件名内容大致如下# data.yaml path: /path/to/datasets/mydata train: images/train val: images/val nc: 2 names: [class1, class2]这里的“nc”是类别数量“names”是类别名称列表。然后启动训练python train.py --data data.yaml --weights yolov5s.pt --epochs 100 --batch-size 8 --imgsz 640“--epochs”控制训练轮数“--batch-size”控制每批样本数量“--imgsz”是训练图片尺寸。第一次跑训练时建议用小数据集、低轮数先跑通整个流程比如epochs10确认一切正常后再加大训练规模。训练完成后会在runs/train/目录下生成训练日志、权重和图表。这里同步一个经验在自己的数据集上训练YOLOv5时最忌讳的就是从头训练冷启动。我们几乎总是以官方COCO预训练权重为起点做微调finetune这样即使你的数据量不大模型也能很快收敛。这和从随机初始化开始训练是完全不同的概念效果差距巨大。4. YOLOv5核心技术点拆解网络结构、超参数与后处理4.1 网络结构图与代码对应关系把YOLOv5跑通之后建议做一步进阶动作——扒一扒网络结构。很多人调来调去都是瞎试就是因为对网络结构没有概念。YOLOv5的网络分成三大块Backbone、Neck和Head对应到代码就是yolov5s.yaml这个配置文件。Backbone部分用的是CSPDarknet结构用来提取图像特征。你可以把Backbone理解成一套多层“滤波器”——浅层滤波器提取边缘、纹理这些低级特征深层滤波器提取“有没有人”“有没有车”这种高级语义特征。在yolov5s.yaml里对应的是从第0层到第9层。Neck部分用的是PANet结构它的作用是特征融合。YOLOv5同时检测大、中、小目标而不同大小的目标需要不同分辨率的特征图。PANet把浅层的高分辨率特征和深层的高语义特征融合起来让每一层特征图都既“看得清”又“看得懂”。对应yolov5s.yaml的第10层到第23层。Head部分是YOLOv5的检测头标准结构是三个分支分别输出80x80、40x40、20x20的特征图预测结果。80x80的特征图每个格子对应原图8x8像素的区域擅长检测小目标20x20的特征图每个格子对应原图32x32像素的区域擅长检测大目标。这就是为什么同一张图里远处的人和近处的人都能被检测出来。这里有个小白容易忽略的点YOLOv5s.pt并不是模型结构本身而是模型结构与训练好的权重参数的集合体。你现在用detect.py跑的是官方提供的预训练权重。如果你想直观地看网络结构可以这样执行import torch model torch.hub.load(ultralytics/yolov5, yolov5s) print(model)你会在终端里看到每一层的具体信息包括卷积层的in_channels、out_channels、kernel_size等。在PC仿真阶段把网络结构弄清楚后面RK3588转RKNN时调整模型输入输出尺寸会非常方便。4.2 超参数到底怎么调YOLOv5的超参数配置文件是data/hyps/hyp.scratch-low.yaml。你训练时的很多“旋钮”都在这里。官方把超参数分成了增强类、损失类、优化器类这里挑最重要的几个说说。基础学习率lr0默认为0.01。在YOLOv5中模型会使用WarmUp和Cosine Annealing来动态调整学习率。如果数据集比较小建议把lr0降到0.005以下防止前期震荡如果数据集比较大可以维持在0.01。训练过程中可以观察runs/train/exp/results.png这个文件里的learning rate曲线来判断是否合适。Mosaic和MixUp是数据增强参数。mosaicTrue是YOLOv5最核心的数据增强技巧——把4张图片拼接成一张训练样本这能让模型学会在更复杂的背景下检测目标而且在小目标检测上效果提升明显。默认开启不建议关闭。数据增强太猛确实会拖慢收敛速度但能够极大提升模型泛化能力。关于超参数我的个人建议是初学者在一个小数据集上做实验时尽量不要动超参数全部采用默认值把流程跑通。然后每次只修改一个参数比如把lr0从0.01改成0.001对比训练曲线再决定下一步。一次性改多个参数后如果模型效果变差了你根本不知道是哪个参数导致了退化——这是困扰很多新手的大坑。4.3 后处理逻辑从输出张量到目标框很多人在RK3588上做NPU部署时卡住就是因为只熟悉detect.py的封装不清楚最底层的后处理逻辑。这一小节把YOLOv5的后处理彻底讲明白。模型输出的原始张量形状是1, 25200, 85。25200是怎么算出来的三个分支的预测格子数相加80x80 40x40 20x20 6400 1600 400 8400不对常规YOLOv5s输出不是25200这是YOLOv8的格式。YOLOv5s的原始输出展开后是1, 25200, 85其中25200 3 x (80x80 40x40 20x20) 3 x 8400 252003是每个格子的锚框数量85是4个坐标(bx, by, bw, bh) 1个目标置信度 80个类别得分。后处理要做三件事阈值过滤、NMS非极大值抑制、坐标映射。第一步把输出张量里的每个预测框的置信度与类别得分相乘得到一个最终得分。如果最终得分小于conf-thres默认0.25这个预测框直接丢弃。第二步对剩下的预测框执行NMS。因为同一个目标可能被多个格子预测出来它们的框高度重叠。NMS的算法逻辑是按得分从高到低排序取最高得分的框然后计算它和其他框的IoU如果IoU超过iou-thres默认0.45就把那个低得分的框删掉。重复这个过程直到所有框都被保留或删除。第三步坐标映射。模型输出的坐标是相对于特征图的归一化值要还原到原图尺寸需要乘以对应的缩放比例。detect.py里这一段代码在utils/general.py的non_max_suppression函数中高度封装建议自己手动实现一遍并打印中间过程的张量形状这样才能真正掌握。5. PC仿真与香橙派RK3588部署的衔接要点5.1 PC和真机环境的差异对照虽然算法链路一致但PC仿真和RK3588真机部署之间还是存在不少差异。用一张表整理出来后面做迁移时对照着看思路会非常清晰。对比项PC仿真环境RK3588真机部署推理芯片CPU/GPUx86NPU6 TOPS CPUPyTorch直接运行内存受限运行缓慢模型格式.ptPyTorch.rknnRKNN Toolkit转换推理方式torch推理RKNN Runtime API调用摄像头输入USB摄像头USB摄像头/MIPI-CSI接口置信度后处理自动完成需要手动或集成代码最关键的一条是模型格式转换。RK3588的NPU不识PyTorch的.pt模型需要通过rknn-toolkit2先把模型转换为RKNN格式再通过RKNN Runtime的Python或C API在板子上执行推理。转换过程中经常碰到算子不支持的情况比如某些上采样操作、某些激活函数都会成为转换失败的根源。在PC仿真阶段提前把YOLOv5的输入输出尺寸固定好比如640x640转换时会省去不少麻烦。5.2 固定输入尺寸与输出解析如果要为RK3588部署做准备从PC仿真阶段就要养成固定输入尺寸的习惯。YOLOv5默认把输入resize到640x640进行推理但如果你用的是动态输入生成的模型在转RKNN时会遇到很多麻烦。RKNN的NPU特性是静态推理输入尺寸固定这样NPU可以把计算图优化到极致。在detect.py里这个参数就是“--imgsz”python detect.py --weights yolov5s.pt --source data/images/bus.jpg --imgsz 640在训练里是“--imgsz 640”。固定成640后模型推理时的输入张量就是1, 3, 640, 640输出的就是1, 25200, 85这两个数字记住就好——后面在RKNN的预处理和后处理代码里会反复用到。另外在PC仿真阶段就把“模型输出是归一化坐标”这个思维刻进脑子里。detect.py帮你做了坐标映射你在RK3588上往往需要自己来实现因为RKNN的推理结果是原始的模型输出需要手动做后处理。这个后处理就是第4.3节讲的那三步。所以我说前期多下功夫理解原理后期就能少踩坑。5.3 RK3588的硬件资源情况最后说一下香橙派5也就是传说中用RK3588的那款的资源情况。RK3588内置的NPU算力为6 TOPS在可运行的边缘设备里已经算很不错了。它的VPU模块支持硬解H.264/H.265视频流——热词里专门有人搜“rk3588的vpu详解”我在这里做一个简单的补充视频解码这种工作交给VPU去做不要占用NPU资源这样推理才能真正跑满。跑YOLOv5s在RK3588上大概能做到30-60 FPS的推理速度远高于x86 CPU的1-3 FPS。这也解释了为什么边缘设备选择RK3588而不是树莓派——树莓派上用CPU跑YOLOv5s大约就是几FPS的水平实时性完全不够。6. 常见问题排查与避坑经验6.1 环境问题速查表这套流程在实际操作中最常见的问题集中在环境依赖和模型下载两个方面。下面整理成速查表按图索骥能解决90%的运行报错。报错提示原因解决方案No module named torch没安装PyTorchpip install torch torchvision --index-url https://download.pytorch.org/whl/cpuDownloading... to yolov5s.pt 卡住网络原因无法下载权重手动用其他方式下载放到项目根目录CUDA unavailable没装CUDA版本换CPU版本完全不影响跑通逻辑ImportError: libGL.so.1系统缺OpenCV依赖sudo apt install libgl1 -yAssertionError: Label class X exceeds nc数据集标签类别超限检查data.yaml的nc值是否与标注文件类别ID一致RuntimeError: result type Float cant be cast标注坐标非法如负数或超界检查标注txt文件确保坐标在0-1之间其中“Label class X exceeds nc”在自训练时出现频率很高本质是标注文件的class_id超出了配置文件里的类别数。比如配置nc2但标注文件里出现了class_id3就会报这个错。用脚本检查一下标签文件很快能定位。6.2 检测效果调试的几个方向如果检测结果不理想先别急着换模型或者狂调超参数按下面这个顺序排查大概率能找到问题。第一个检查点是置信度阈值。很多时候并不是模型检测能力不够只是阈值设置过高或者过低。业务场景对误报容忍度低的比如安全帽检测把conf-thres调到0.4-0.5业务场景对漏报容忍度低的比如车辆识别把conf-thres降到0.15-0.2。这比重新训练模型快得多。第二个检查点是训练轮数。数据量小的时候100轮可能只训练到了瓶颈期数据量大的时候100轮可能已经过拟合。看runs/train/exp/results.png里的val精度曲线判断模型是否还在上升期。如果val精度还在涨但train精度已经收敛说明欠拟合继续加轮数如果val精度开始下降而train精度继续涨说明过拟合了应该提前停止或者加大数据增强。第三个检查点是数据集质量。标注框有没有明显偏差类别是否均衡遇到“检测不出来”的情况先花时间看几十张训练样本的标注可视化效果往往能直接看出问题所在。6.3 我在实操中积累的几个小技巧在PC仿真阶段多花的那些心思后面都会百分百回馈到你。这里分享几个我自己摸索出来的实用技巧不见得在官方文档里能找到但实测下来非常管用。第一个是提前定义好推理接口。在PC仿真的代码里把模型的推理封装成一个标准的函数接口输入是图像输出是类别、置信度和坐标列表。后面在RK3588上部署时只需要替换函数内部的推理实现从torch推理换成RKNN推理外层逻辑完全不用动。这种“可替换后端”的设计模式能在后续省掉大量重复开发的功夫。第二个是习惯用“--project”和“--name”给每次实验做归档。跑detect.py时如果不指定这两个参数所有结果都会堆在runs/detect/exp、exp2、exp3……里过两天就分不清哪组参数对应哪个结果了。我用的是“--project runs/detect --name bus_01_conf03”这种命名方式看一眼输出目录就知道是什么实验。第三个是留一份环境导出清单。在conda环境里跑完所有依赖之后执行pip freeze requirements_rk3588.txt这份清单保存下来后面在香橙派上配置环境时可以直接对着安装避免版本不一致导致的各种兼容性问题。版本一致是嵌入式部署最容易被忽视也最致命的问题。最后再说一个带点提升的内容。在PC仿真阶段把YOLOv5玩转之后下一步自然是尝试用YOLOv8甚至其他更新的检测模型因为RK3588的NPU算力完全撑得起这些模型。但模型升级的核心难点不是训练而是模型转换。你如果能把YOLOv5从训练到部署的整条链路吃透换模型只是换一个配置文件、换一个权重文件的事情——底层逻辑完全是相通的。这正是我强调在这篇教程里多花时间把原理和流程搞扎实的原因祝你玩得开心。