1. 为什么选择 PaddleDetection 作为目标检测入门框架目标检测这个方向很多人第一次接触时都会被各种框架和模型绕晕。YOLO 系列、Detectron2、MMDetection、PaddleDetection每个都有自己的生态和上手门槛。我当初选 PaddleDetection 的原因很直接文档是中文的模型库齐全从数据标注到训练到部署有一条完整的链路而且对国内网络环境友好不用折腾各种依赖源的问题。PaddleDetection 是飞桨PaddlePaddle生态下的目标检测开发套件覆盖了目标检测、实例分割、关键点检测等主流任务。它内置了 PP-YOLOE、PP-PicoDet、Faster R-CNN、SOLOv2 等一大批模型支持从移动端到服务端的全场景部署。说白了你想做一个检测任务大概率不需要自己从头写网络结构直接挑一个预训练模型微调就行。这篇文章适合谁看如果你是刚接触深度学习目标检测的新手或者之前用过其他框架但想试试 PaddleDetection 的开发者再或者你需要在本地快速搭一套能跑起来的检测环境做验证那这篇内容就是为你准备的。我会从环境搭建开始一步步走到跑通测试把踩过的坑和关键细节都摊开讲。环境搭建这件事看起来简单实际上是最容易劝退人的环节。CUDA 版本、cuDNN 版本、PaddlePaddle 版本、Python 版本这四个东西只要有一个对不上后面就是无尽的报错。我见过太多人在这一步卡了一整天最后放弃。所以这篇文章的重点不是讲目标检测的原理而是把环境搭建这件事彻底讲透让你一次跑通。2. 环境搭建前的整体规划与版本选型2.1 硬件与操作系统的前置确认在动手装任何东西之前先确认你的硬件条件。PaddleDetection 支持 CPU 和 GPU 两种运行模式但如果你要做训练GPU 是必须的。CPU 模式下跑推理勉强可以训练基本不现实速度会慢到让你怀疑人生。你需要确认的信息包括显卡型号、显存大小、操作系统版本。显存方面跑轻量模型如 PP-PicoDet4GB 显存就够用跑 PP-YOLOE-L 这种较大的模型建议 8GB 以上。操作系统上LinuxUbuntu 20.04/22.04是最省心的选择Windows 也能跑但坑更多macOS 只能用 CPU 模式。我个人的建议是如果你有一台带 NVIDIA 显卡的机器优先用 Ubuntu。如果只有 Windows那就做好心理准备后面会多花一些时间处理路径和编译问题。2.2 版本匹配的核心逻辑版本匹配是环境搭建的灵魂。很多人失败的原因不是操作错了而是一开始版本就没选对。PaddlePaddle 对 CUDA 和 cuDNN 的版本有明确要求而 PaddleDetection 又对 PaddlePaddle 的版本有要求这是一条链式依赖。截至我写这篇内容时比较稳定的组合是这样的组件推荐版本说明操作系统Ubuntu 20.04 / 22.04Windows 也可但坑多Python3.8 / 3.9 / 3.103.11 部分依赖不兼容CUDA11.2 / 11.6 / 11.7根据显卡驱动选择cuDNN8.2 及以上需与 CUDA 对应PaddlePaddle2.5 / 2.6GPU 版本PaddleDetection2.6 / 2.7与 Paddle 版本匹配为什么 Python 不建议用 3.11因为 PaddleDetection 依赖的一些库比如 pycocotools在 3.11 上编译容易出问题。3.8 到 3.10 是最稳的区间我实测 3.9 的兼容性最好。CUDA 版本怎么选先跑nvidia-smi看你的驱动支持到哪个 CUDA 版本。注意nvidia-smi显示的是驱动支持的最高 CUDA 版本不是你当前安装的 CUDA 版本。你安装的 CUDA 版本只要不超过这个上限就行。提示不要盲目追求最新版本。CUDA 12.x 虽然新但 PaddlePaddle 对它的支持还在完善中用 11.x 系列最稳妥。2.3 安装方式的选择pip 还是源码编译PaddlePaddle 有两种安装方式pip 直接安装和源码编译。对于绝大多数人来说pip 安装就够了一条命令搞定。源码编译适合需要自定义算子或者修改底层代码的场景编译一次动辄一两个小时没必要给自己找麻烦。PaddleDetection 本身是通过 git clone 源码来使用的它不是 pip 包。你需要把代码拉下来然后安装它的依赖。这个设计的好处是你可以直接改配置文件、改模型结构灵活性很高。3. 一步步搭建 PaddleDetection 运行环境3.1 创建独立的 Python 虚拟环境第一步永远是创建虚拟环境。不要图省事直接装在系统 Python 里后面依赖冲突会让你痛不欲生。我用 conda 来管理环境如果你没有 conda用 venv 也行。conda create -n paddle_env python3.9 -y conda activate paddle_env创建完之后确认一下 Python 版本python --version应该输出 Python 3.9.x。如果版本不对检查一下 conda 环境是否激活成功。为什么强调虚拟环境因为 PaddleDetection 依赖的 numpy、opencv-python 等库版本比较特定如果你系统里已经装了其他版本很容易冲突。虚拟环境相当于给你一个干净的沙盒怎么折腾都不影响系统。3.2 安装 PaddlePaddle GPU 版本这是最关键的一步。安装命令要根据你的 CUDA 版本和操作系统来定。以 CUDA 11.6 为例python -m pip install paddlepaddle-gpu2.5.2.post116 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html如果你用的是 CUDA 11.2python -m pip install paddlepaddle-gpu2.5.2.post112 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html注意命令里的post116和post112这个后缀对应 CUDA 版本写错了装出来的版本就跑不了 GPU。安装完成后必须验证 GPU 是否可用import paddle print(paddle.__version__) print(paddle.is_compiled_with_cuda()) print(paddle.device.get_device())如果is_compiled_with_cuda()返回 Trueget_device()返回类似gpu:0的结果说明 GPU 版本安装成功。如果返回 False 或者cpu那就要检查 CUDA 和 cuDNN 的配置了。注意如果is_compiled_with_cuda()返回 False先别急着重装。检查一下 LD_LIBRARY_PATH 是否包含了 CUDA 的 lib64 目录很多时候是环境变量没配好。3.3 拉取 PaddleDetection 源码并安装依赖PaddlePaddle 装好之后接下来拉 PaddleDetection 的代码git clone https://github.com/PaddlePaddle/PaddleDetection.git cd PaddleDetection然后切换到与你 PaddlePaddle 版本匹配的分支。比如 PaddlePaddle 2.5 对应 PaddleDetection release/2.6git checkout release/2.6接下来安装依赖pip install -r requirements.txt这一步可能会比较慢因为要装的包不少。如果遇到某个包下载超时可以换源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple依赖装完之后还要编译安装 PaddleDetection 本身pip install -v -e .这个-e是 editable 模式意思是安装之后你修改源码会直接生效不用重新安装。开发调试阶段非常方便。3.4 验证安装是否成功安装完成后跑一个简单的测试来验证python -c import ppdet; print(ppdet.__version__)如果输出了版本号说明 PaddleDetection 安装成功。接下来可以跑一个官方提供的推理测试python tools/infer.py -c configs/ppyolo/ppyolo_r50vd_dcn_1x_coco.yml \ -o weightshttps://paddledet.bj.bcebos.com/models/ppyolo_r50vd_dcn_1x_coco.pdparams \ --infer_imgdemo/000000014439.jpg这条命令会下载预训练权重然后对 demo 图片做推理结果保存在output目录下。如果能看到检测框画在图片上恭喜你环境搭建成功。4. 环境搭建中的常见问题与排查实录4.1 CUDA 与 cuDNN 相关的典型报错环境搭建过程中十有八九的问题都出在 CUDA 和 cuDNN 上。我整理了几个最常见的报错和对应的排查思路。报错一libcudart.so.11.0: cannot open shared object file这个报错的意思是找不到 CUDA 运行时库。原因通常是 CUDA 装了但环境变量没配。解决方法是在~/.bashrc里加上export LD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH export PATH/usr/local/cuda/bin:$PATH然后source ~/.bashrc生效。注意把路径换成你实际的 CUDA 安装路径。报错二CUDA error: no kernel image is available for execution on the device这个报错说明你安装的 PaddlePaddle 版本编译时支持的算力架构和你的显卡不匹配。比如你的显卡是 RTX 30 系列算力 8.6但安装的 PaddlePaddle 只支持到算力 7.5就会报这个错。解决办法是安装支持更高算力的版本或者换一张显卡。报错三cudnn version mismatchcuDNN 版本和 CUDA 版本不匹配。cuDNN 8.2 对应 CUDA 11.xcuDNN 7.x 对应 CUDA 10.x。去 NVIDIA 官网查一下对应关系下载正确的版本。4.2 Python 依赖冲突的处理依赖冲突是另一个高频问题。典型表现是ImportError或者某个函数调用时报AttributeError。最常见的是 numpy 版本问题。PaddleDetection 对 numpy 的版本有要求太新或太旧都可能出问题。如果遇到 numpy 相关的报错先看看当前版本pip show numpy如果版本过新比如 1.24可以降级pip install numpy1.23.5另一个常见的是 opencv-python 的问题。有些环境里同时装了opencv-python和opencv-python-headless两者会冲突。解决方法是只保留一个pip uninstall opencv-python-headless pip install opencv-python4.6.0.664.3 显存不足与性能调优显存不足的报错信息通常是Out of memory或者CUDA out of memory。这个问题在训练阶段特别常见。解决思路有几个方向。第一是减小 batch size这是最直接的方法。在配置文件里把batch_size从 8 改成 4 甚至 2。第二是减小输入图像尺寸比如从 640x640 改成 320x320。第三是使用轻量模型PP-PicoDet 的显存占用比 PP-YOLOE 小很多。如果你显存够但训练速度慢可以检查一下是否开启了 cudnn benchmarkpaddle.set_flags({FLAGS_cudnn_deterministic: False})另外数据加载的 num_workers 也可以适当调大加快数据读取速度。4.4 常见问题速查表问题现象可能原因解决方法GPU 不可用CUDA/cuDNN 未配好检查环境变量和版本匹配导入 ppdet 报错未执行 pip install -e .在 PaddleDetection 目录下重新安装推理结果为空权重未加载或阈值过高检查权重路径和 score_threshold训练 loss 不下降学习率过大或数据有问题调小学习率检查标注格式显存溢出batch size 过大减小 batch size 或输入尺寸依赖冲突版本不匹配用虚拟环境重新安装5. 跑通第一个检测 Demo 的完整流程5.1 准备测试图片和配置文件环境搭好之后第一件事是跑通一个完整的推理流程。PaddleDetection 的demo目录下自带了几张测试图片直接用就行。如果你想用自己的图片放到任意目录推理时指定路径即可。配置文件在configs目录下按模型类型分了很多子目录。比如configs/ppyolo/下面是 PP-YOLO 系列的配置configs/ppyoloe/下面是 PP-YOLOE 系列的配置。每个配置文件里定义了模型结构、数据集、训练参数等信息。以 PP-YOLOE-S 为例配置文件是configs/ppyoloe/ppyoloe_crn_s_300e_coco.yml。这个配置对应的是在 COCO 数据集上训练 300 轮的模型。5.2 执行推理并查看结果推理命令的基本格式是python tools/infer.py -c [配置文件] -o weights[权重路径] --infer_img[图片路径]权重路径可以是本地文件也可以是 URL。PaddleDetection 官方提供了很多预训练权重的下载链接直接用 URL 会自动下载。执行完推理后结果默认保存在output目录下。打开图片可以看到检测框、类别标签和置信度。如果图片里有多个人、车、动物等 COCO 数据集包含的类别应该都能检测出来。我实测下来PP-YOLOE-S 在单张 RTX 3060 上的推理速度大约是 30ms 一张图精度也相当不错。对于快速验证来说完全够用。5.3 用 Python 脚本调用推理接口命令行推理适合快速测试但实际项目中更常见的是在 Python 代码里调用。PaddleDetection 提供了deploy/python/infer.py这个脚本封装了推理接口。一个最简单的调用示例import cv2 from deploy.python.infer import Detector detector Detector( model_diroutput_inference/ppyoloe_crn_s_300e_coco, deviceGPU, threshold0.5 ) image cv2.imread(demo/000000014439.jpg) results detector.predict_image(image) print(results)这段代码的核心是Detector类它封装了预处理、推理、后处理的全流程。model_dir是导出的推理模型目录threshold是置信度阈值低于这个值的检测框会被过滤掉。提示model_dir里的模型需要先通过tools/export_model.py导出。直接用训练时的.pdparams权重是不行的必须先转成推理模型格式。5.4 导出推理模型的关键步骤导出推理模型的命令python tools/export_model.py -c configs/ppyoloe/ppyoloe_crn_s_300e_coco.yml \ -o weightshttps://paddledet.bj.bcebos.com/models/ppyoloe_crn_s_300e_coco.pdparams \ --output_diroutput_inference导出完成后output_inference目录下会有model.pdmodel、model.pdiparams和infer_cfg.yml三个文件。前两个是模型结构和权重第三个是推理配置。为什么需要导出这一步因为训练时的模型包含了优化器状态、学习率调度等信息这些在推理时用不到。导出后的模型更小、加载更快而且可以跨平台部署。6. 从环境搭建到实际使用的经验总结6.1 版本管理的长期策略环境搭建不是一次性的工作。你可能会遇到需要切换不同版本 PaddleDetection 的情况比如项目 A 用 2.5项目 B 用 2.6。这时候如果只有一个环境就会很麻烦。我的做法是给每个项目建一个独立的 conda 环境环境名带上版本号比如paddle25、paddle26。这样切换的时候直接conda activate就行互不干扰。另外把安装命令记录在一个setup.sh脚本里。下次换机器或者重装系统直接跑脚本不用凭记忆一步步操作。这个习惯帮我省了很多时间。6.2 数据准备的前置工作环境跑通之后下一步就是用自己的数据训练。这里有一个容易被忽略的点数据格式。PaddleDetection 默认使用 COCO 格式的标注如果你的数据是 VOC 格式或者 YOLO 格式需要先转换。转换脚本在tools/x2coco.py支持 VOC 和 LabelMe 格式转 COCO。转换的时候注意类别名称和类别 ID 的对应关系搞错了会导致训练时类别混乱。还有一个经验数据量少的时候比如每类只有几十张图不要从头训练直接用预训练模型微调。把学习率调小训练轮数控制在 50 到 100 轮效果通常比从头训练好得多。6.3 配置文件修改的注意事项PaddleDetection 的配置文件是 YAML 格式支持继承和覆盖。基础配置在configs/_base_/目录下具体模型的配置通过_BASE_字段继承基础配置然后覆盖需要修改的部分。修改配置时最容易出错的是字段名拼写。YAML 对缩进和大小写敏感多一个空格或者大小写错了都会导致解析失败。建议用 IDE 打开配置文件开启 YAML 语法检查。另外配置文件里的路径建议用相对路径相对于 PaddleDetection 根目录。用绝对路径的话换机器就要改很麻烦。6.4 日志与调试技巧训练过程中日志是排查问题的第一手资料。PaddleDetection 的日志默认输出到终端也可以重定向到文件python tools/train.py -c configs/ppyoloe/ppyoloe_crn_s_300e_coco.yml 21 | tee train.log日志里重点关注 loss 的变化趋势。正常情况下loss 应该在前几个 epoch 快速下降然后逐渐趋于平稳。如果 loss 一直不降或者震荡剧烈通常是学习率太大或者数据有问题。还有一个调试技巧先用小数据集跑几个 epoch确认流程能跑通再换全量数据。这样能快速发现配置错误不用等几个小时才发现问题。6.5 我踩过的几个坑第一个坑是 CUDA 版本和驱动版本不匹配。我一开始装了 CUDA 11.7但驱动只支持到 11.4结果 PaddlePaddle 死活检测不到 GPU。后来降级到 CUDA 11.2 才解决。教训是装之前先跑nvidia-smi确认驱动支持的 CUDA 上限。第二个坑是 pycocotools 安装失败。这个包需要编译 C 扩展如果系统里没有 gcc 或者 Python 开发头文件就会报错。解决方法是先装build-essential和python3-dev。第三个坑是推理结果为空。排查了半天最后发现是权重文件下载不完整。重新下载之后就好了。所以下载权重之后最好检查一下文件大小和官方标注的大小对比一下。第四个坑是训练时 GPU 利用率很低。原因是数据加载成了瓶颈num_workers 设得太小。调大之后 GPU 利用率从 30% 提升到了 80% 以上。这些坑看起来都是小问题但每一个都可能让你卡半天。希望我的经验能帮你少走一些弯路。环境搭建这件事说到底就是细心加耐心把版本对齐把依赖装全剩下的就是跑通验证。一旦环境跑通了后面的模型训练和调优就是另一个故事了。