从零到一：在RDK X5上部署自定义YOLOv5模型的避坑指南

1. 环境准备：从Windows到WSL2的平滑过渡

如果你和我一样，主要的工作环境是Windows，那么想在RDK X5上玩转YOLOv5，第一步就是搭建一个Linux开发环境。别怕，这听起来复杂，但跟着我的步骤走，绝对能避开我当初踩过的那些坑。最主流、最方便的方法就是使用Windows Subsystem for Linux 2，也就是WSL2。它本质上是在Windows里跑一个完整的Linux内核，让你能无缝使用Linux的命令行工具，同时又不用离开你熟悉的Windows桌面。

安装WSL2，最权威的指南永远是微软官方的文档。你直接在搜索引擎里搜“安装 WSL Microsoft Learn”，第一个结果就是。官方教程步骤清晰，跟着点下一步就行。但这里我要强调一个新手最容易忽略，也最致命的问题：C盘空间。WSL2默认会把所有的Linux系统文件、你后续安装的软件、下载的数据集、训练的模型，统统放在C盘的用户目录下。想象一下，你训练一个YOLOv5模型，动辄几个G的缓存和中间文件，C盘分分钟飘红。所以，在安装Ubuntu之前，甚至在你打开那个安装命令之前，先看看你的C盘还剩多少空间。我个人建议，至少预留50GB的可用空间，否则后续工作会非常掣肘。

安装完WSL2后，我们去Microsoft Store搜索并安装Ubuntu。这里有个小分歧：地平线的OE工具链官方推荐Ubuntu 20.04，但Store里最新的是22.04。实测下来，Ubuntu 22.04完全可以正常运行OE工具链，不必纠结。而且，对于想进一步探索机器人领域的同学来说，22.04是ROS2 Humble的主流支持系统，像鱼香ROS、古月居等很多优质教程都基于此。所以，直接装22.04，一步到位，为以后学习ROS2也铺好了路。装好系统，第一件事不是急着敲命令，而是迁移WSL2的安装位置。这是拯救C盘的关键操作。你需要将Ubuntu的虚拟磁盘文件移动到其他盘符（比如D盘或E盘）。网上有很多教程，核心是使用wsl --export和wsl --import命令。完成这个操作后，你再怎么折腾Linux，也不会影响C盘了。

接下来，我强烈建议你配置VS Code的WSL扩展。这能让你的开发体验提升好几个档次。你可以在Windows的VS Code里直接打开WSL子系统中的文件夹，使用Windows的图形界面来编辑Linux下的代码文件，终端也直接集成了WSL的bash，非常方便。官方同样有详细的“开始通过 WSL 使用 VS Code”教程。完成这些，你的基础战场就搭建好了。这时候，你可以打开Ubuntu终端，先更新一下软件包列表：sudo apt update && sudo apt upgrade -y。然后，我们将进入下一个关键环节：配置深度学习环境。

2. 模型训练基石：YOLOv5环境与数据准备

环境搭好了，我们得把YOLOv5请进来。这里我走了不少弯路，总结下来就是：版本对齐和环境隔离是成功的关键。首先获取YOLOv5的源码。我推荐直接参考地平线RDK的Model Zoo仓库，里面有针对RDK X5优化过的YOLOv5示例。你可以通过GitHub访问D-Robotics的rdk_model_zoo项目。找到demos/detect/YOLOv5目录，里面的README文件就是我们的行动纲领。YOLOv5版本迭代很快，Model Zoo里可能会注明测试通过的版本，比如v7.0。我们就用这个稳定的版本。克隆仓库后，记得用git checkout tags/v7.0切换到指定版本，避免用最新的main分支可能带来的兼容性问题。

拿到源码，先别急着运行。我们需要一个干净的、独立的Python环境来管理依赖。Anaconda或Miniconda是首选。在WSL2的Ubuntu终端里，下载并安装Miniconda（更轻量）。安装完成后，关闭终端重新打开，或者执行source ~/.bashrc，让conda命令生效。这里我遇到一个坑：有时候新开的终端输入conda会提示“command not found”。别慌，这不是安装失败了，只是环境变量没加载。最简单粗暴的解决办法就是把当前终端关掉，重新开一个，百分之九十能解决。如果还不行，就手动执行一下source ~/miniconda3/etc/profile.d/conda.sh。

环境有了，我们创建一个专属于这个项目的conda虚拟环境：conda create -n yolov5_rdk python=3.8。为什么是Python 3.8？因为这是很多深度学习框架和工具链比较兼容的版本，过于新的版本反而容易出幺蛾子。激活环境：conda activate yolov5_rdk。然后，根据YOLOv5源码目录下的requirements.txt文件安装依赖。注意，这里可能因为网络问题导致某些包（比如torch）安装慢或失败。有两个建议：一是使用清华、阿里等国内镜像源；二是对于PyTorch，可以去官网根据你的环境（虽然我们是在WSL2里用CPU训练，但可以先按CPU版本安装）生成安装命令，通常比pip直接装requirements.txt更快更稳。

环境搞定，接下来是数据的准备。如果你想识别自定义的物体，比如我们项目里的“火苗”，就需要自己标注数据。这里我安利一个比原教程提到的更好用的工具：LabelImg。安装极其简单，在激活的虚拟环境下，pip install labelimg即可。启动它，在终端输入labelimg就会弹出图形界面。使用方法很直观：1. 打开存放图片的目录；2. 设置标注文件（.txt）的输出目录；3. 将标注格式改为YOLO（点击界面上的PascalVOC切换成YOLO）。然后就可以在图片上框选目标，并输入类别标签了。标注是个体力活，但质量直接决定模型上限。标注完成后，你需要按照YOLOv5要求的目录结构来组织数据，通常包含images/train, images/val, labels/train, labels/val这几个文件夹，并且确保图片和标注文件的名字一一对应。最后，创建一个data.yaml配置文件，指明你的类别数量、名称以及上述文件夹的路径。这个文件是后续训练和模型转换的指挥棒，路径一定要写对，否则训练时会报一堆找不到文件的错误。

3. 从训练到转换：产出可用的ONNX模型

数据准备好了，激动人心的训练环节开始。在YOLOv5目录下，训练命令看起来很简单：python train.py --data ./data/my_fire.yaml --cfg ./models/yolov5s.yaml --weights yolov5s.pt --epochs 100 --batch-size 16。这里有几个参数需要你根据实际情况调整：--data指向你刚才创建的data.yaml；--cfg选择模型结构，比如yolov5s.yaml代表小模型，训练快，适合在资源有限的设备上部署；--weights加载预训练权重，能从yolov5s.pt开始训练，这是非常重要的，能极大加速收敛并提升效果；--epochs是训练轮数；--batch-size是批大小，如果你的GPU内存小（或者在WSL2里只用CPU），需要调小这个值，比如设为4或8。

训练过程中，终端会打印损失值、精度等指标。YOLOv5还会自动在runs/train/exp目录下生成可视化结果，包括训练曲线、验证集上的预测样例等。你可以随时查看这些图片来监控训练状态。训练完成后，最好的模型权重会保存在runs/train/exp/weights/best.pt。请注意：训练时如果中断了，你可以通过--resume参数接上上次的权重继续训练，非常人性化。

模型训练好，我们得到了一个.pt文件，但这是PyTorch的格式，RDK X5的OE工具链不认识它。我们需要一个中间桥梁：ONNX。这是将模型从训练框架（如PyTorch）导出到推理引擎（如地平线BPU）的标准格式。导出ONNX，参考Model Zoo的说明是关键。你需要使用YOLOv5项目里的export.py脚本。但直接运行通常不行，因为原始的导出脚本生成的ONNX模型可能包含一些RDK X5不支持的算子。所以，我们需要对export.py或者更常见的，对YOLOv5模型定义文件models/yolo.py进行一些修改。这些修改主要是为了适配地平线芯片的算子支持列表，比如将某些操作替换为等效的、被支持的操作组合。Model Zoo的README里通常会给出需要修改的代码片段，你仔细对照，像做手术一样把代码替换进去即可。

修改完成后，运行导出命令：python export.py --weights ./runs/train/exp/weights/best.pt --include onnx --opset 11。这里--opset指定ONNX算子集版本，一般用11或12比较通用。如果一切顺利，你会在权重文件同级目录下得到一个.onnx文件。强烈建议，在进入下一步之前，用ONNX Runtime或Netron这样的工具简单验证一下这个ONNX模型是否能被正确加载和进行形状推断，确保导出过程没有产生错误。这个.onnx文件，就是我们交给地平线工具链的“原材料”。

4. 地平线工具链实战：模型量化与上板

这是整个流程中最具“地平线特色”，也最容易出错的一步。我们需要在Docker容器里使用地平线的Open Explorer（OE）工具链，把ONNX模型“编译”成RDK X5能直接运行的.bin文件。这个过程叫模型量化。首先，我们需要Docker环境。在Windows上，去Docker官网下载安装Docker Desktop。安装时，务必在设置里找到“Resources” -> “Advanced”，将磁盘镜像的存储位置改到一个非C盘的大容量分区！这是我血泪的教训，编译模型时产生的中间文件巨大，默认C盘路径分分钟撑爆你的系统盘。

安装好Docker Desktop后，确保它在运行，并且设置里勾选了“Use the WSL 2 based engine”。这样，Docker就能和WSL2完美协作了。接下来，我们需要地平线提供的OE工具链Docker镜像。你可以从地平线开发者社区或FTP服务器获取。镜像文件很大（几个GB），建议直接用wget命令在WSL2的终端里下载CPU版本（对于模型转换，CPU版本足够，也更简单）。下载完成后，使用docker load命令加载镜像。然后，运行一个至关重要的命令来启动容器，并将本地目录挂载到容器内，方便文件交换：

docker run -it --rm \
  -v /home/你的用户名/OE_workspace:/open_explorer \
  -v /home/你的用户名/model_data:/data/horizon_x5/data \
  openexplorer/ai_toolchain_ubuntu_20_x5_cpu:v1.2.6

请把/home/你的用户名/OE_workspace和/home/你的用户名/model_data替换成你WSL2系统里的真实路径。这个命令的意思是，启动一个交互式容器，将本地的OE_workspace文件夹映射到容器的/open_explorer（工具链工作目录），将model_data映射到容器的/data目录（存放模型和数据）。之前导出的ONNX文件，现在就把它复制到本地的model_data文件夹里，这样在容器里就能访问到了。

进入容器后，首先cd /data，确认你的ONNX文件在里面。第一步，使用hb_mapper checker工具检查模型兼容性：hb_mapper checker --model-type onnx --march bayes-e --model your_model.onnx。这个命令会分析ONNX模型，列出所有算子，并告诉你哪些是支持的，哪些不支持。如果有不支持的算子，你就得返回上一步，修改模型结构或导出方式。如果检查通过，就可以准备量化了。

量化需要一个配置文件（.yaml）。地平线工具链提供了一些样例，在/open_explorer/ddk/samples/ai_toolchain/horizon_model_convert_sample/04_detection/03_yolov5s_onnx这样的路径下可以找到。你需要根据你的模型修改这个yaml文件，核心是以下几项：

• model_name: 你的模型名字。
• onnx_model: ONNX文件的路径。
• output_model_file_prefix: 输出文件前缀。
• input_parameters下的input_name、input_shape：必须和你的模型输入节点名、形状完全一致。
• calibration_data下的cal_data_dir: 指向一个存放校准数据集的目录。这是量化的关键！你需要准备几十到几百张训练集中的图片（不需要标注），放在一个文件夹里，工具链会通过这些图片来计算量化参数。图片格式和预处理方式（如BGR/RGB，归一化）必须在yaml文件里正确配置。

配置文件准备好后，执行量化编译命令：hb_mapper makertbin --model-type onnx --config your_config.yaml。这个过程会消耗一些时间，如果一切正常，最终会生成一个.bin文件，这就是能在RDK X5上加载运行的模型文件！如果报错，最常见的两个原因是：1. yaml配置文件里路径或参数写错了；2. 校准数据没准备好，或者预处理配置不对。你需要仔细核对错误信息，回头检查。

5. 上板部署与效果验证

拿到珍贵的.bin文件，万里长征就走完了九十九步。最后一步是把它放到RDK X5上跑起来。你需要通过SSH或者SCP将.bin文件传输到RDK X5的某个目录下。同时，地平线提供了模型推理的示例代码（C++或Python），通常在RDK的系统镜像里或者开发者社区可以找到。你需要做的是，参照示例代码，编写你自己的推理程序。这个过程主要涉及：

1. 加载模型：使用地平线提供的运行时库（如hobot_dnn）加载.bin文件。
2. 准备输入数据：从摄像头（如USB摄像头或MIPI摄像头）读取一帧图像，按照模型要求进行预处理（缩放、裁剪、颜色空间转换、归一化等），这个预处理必须和之前训练、量化时的预处理方式严格一致。
3. 执行推理：将处理好的图像数据送入模型。
4. 解析输出：模型输出的是一组数据，你需要根据YOLOv5的后处理逻辑（在示例代码中通常有体现），将这些数据解码成边界框坐标、类别置信度和类别索引。
5. 绘制结果：将检测框和标签画在图像上，并通过HDMI或者网络推流显示出来。

这里最大的坑可能是前后处理不对齐。比如训练时图片归一化是/255.0，而推理代码里忘了除；或者训练时输入是640x640，而摄像头来的图像是1920x1080，你却没有正确地resize和padding。这些都会导致检测结果异常甚至崩溃。我的建议是，先用一组静态图片（最好是校准集里的）在RDK X5上测试，确保预处理和模型输出解析正确，再接入实时视频流。

当你在RDK X5的屏幕上看到实时视频里，火焰（或你的目标物体）被准确地框选出来时，那种成就感是无与伦比的。整个过程从零开始，涉及了操作系统、开发环境、深度学习框架、模型转换、嵌入式部署多个层面，确实充满挑战。但只要你耐心地、一步一步地走，严格对照文档和教程，注意我上面提到的每一个坑点，就一定能成功。这套流程不仅适用于YOLOv5和火源识别，你完全可以替换成其他需要识别的物体，比如安全帽、行人、车辆等，方法论是完全相通的。最重要的是动手去做，在解决问题的过程中，你的收获会远远超出一份简单的部署教程。