PaddleDetection环境搭建全攻略：从版本选型到跑通第一个检测Demo

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-PicoDet，4GB 显存就够用；跑 PP-YOLOE-L 这种较大的模型，建议 8GB 以上。操作系统上，Linux（Ubuntu 20.04/22.04）是最省心的选择，Windows 也能跑但坑更多，macOS 只能用 CPU 模式。

我个人的建议是：如果你有一台带 NVIDIA 显卡的机器，优先用 Ubuntu。如果只有 Windows，那就做好心理准备，后面会多花一些时间处理路径和编译问题。

2.2 版本匹配的核心逻辑

版本匹配是环境搭建的灵魂。很多人失败的原因不是操作错了，而是一开始版本就没选对。PaddlePaddle 对 CUDA 和 cuDNN 的版本有明确要求，而 PaddleDetection 又对 PaddlePaddle 的版本有要求，这是一条链式依赖。

截至我写这篇内容时，比较稳定的组合是这样的：

为什么 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 python=3.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-gpu==2.5.2.post116 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html

如果你用的是 CUDA 11.2：

python -m pip install paddlepaddle-gpu==2.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()返回 True，get_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.6：

git 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 weights=https://paddledet.bj.bcebos.com/models/ppyolo_r50vd_dcn_1x_coco.pdparams \ --infer_img=demo/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 mismatch

cuDNN 版本和 CUDA 版本不匹配。cuDNN 8.2 对应 CUDA 11.x，cuDNN 7.x 对应 CUDA 10.x。去 NVIDIA 官网查一下对应关系，下载正确的版本。

4.2 Python 依赖冲突的处理

依赖冲突是另一个高频问题。典型表现是ImportError或者某个函数调用时报AttributeError。

最常见的是 numpy 版本问题。PaddleDetection 对 numpy 的版本有要求，太新或太旧都可能出问题。如果遇到 numpy 相关的报错，先看看当前版本：

pip show numpy

如果版本过新（比如 1.24+），可以降级：

pip install numpy==1.23.5

另一个常见的是 opencv-python 的问题。有些环境里同时装了opencv-python和opencv-python-headless，两者会冲突。解决方法是只保留一个：

pip uninstall opencv-python-headless pip install opencv-python==4.6.0.66

4.3 显存不足与性能调优

显存不足的报错信息通常是Out of memory或者CUDA out of memory。这个问题在训练阶段特别常见。

解决思路有几个方向。第一是减小 batch size，这是最直接的方法。在配置文件里把batch_size从 8 改成 4 甚至 2。第二是减小输入图像尺寸，比如从 640x640 改成 320x320。第三是使用轻量模型，PP-PicoDet 的显存占用比 PP-YOLOE 小很多。

如果你显存够但训练速度慢，可以检查一下是否开启了 cudnn benchmark：

paddle.set_flags({'FLAGS_cudnn_deterministic': False})

另外，数据加载的 num_workers 也可以适当调大，加快数据读取速度。

4.4 常见问题速查表

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_dir='output_inference/ppyoloe_crn_s_300e_coco', device='GPU', threshold=0.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 weights=https://paddledet.bj.bcebos.com/models/ppyoloe_crn_s_300e_coco.pdparams \ --output_dir=output_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 2>&1 | 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% 以上。

这些坑看起来都是小问题，但每一个都可能让你卡半天。希望我的经验能帮你少走一些弯路。环境搭建这件事，说到底就是细心加耐心，把版本对齐，把依赖装全，剩下的就是跑通验证。一旦环境跑通了，后面的模型训练和调优就是另一个故事了。