PPYOLO行人检测实战：从数据准备到部署全流程复盘

行人检测这个方向，这几年被谈得很多，但真正做到能放到现场稳定跑，和demo里看到的效果完全是两码事。我最近用PaddlePaddle框架把PPYOLO行人检测模型从头到尾训练了一遍，从数据整理到配置调参，再到评估和导出部署，整个链路走下来比我预想的曲折不少，也踩了一些比较典型的坑。这篇就把这套流程完整复盘一次：为什么选PPYOLO、数据怎么准备、训练参数怎么调、出问题怎么排查，全部结合我实际跑项目的过程来讲，给准备做目标检测落地的朋友一个能直接照着走的参考。

先说明一下，这个项目针对的是监控摄像头下的行人检测任务，目标就一个：把画面里的行人尽量准确地框出来。任务虽然听起来简单，但真正跑起来会遇到遮挡、小目标、光线变化等各种情况，这也是我坚持把全流程写出来的原因。下面内容适合有一定深度学习基础、想快速上手目标检测工程的读者，也适合那些刚接触PaddlePaddle、想拿一个完整项目练手的人。

1. 项目整体设计与技术选型

1.1 为什么选PPYOLO做行人检测

目标检测的模型选型，基本就是在速度和精度之间做权衡。两阶段检测器精度高，但速度慢，不适合视频流实时处理；传统单阶段检测器速度快，但小目标和遮挡场景下容易漏检。PPYOLO正好是中段偏上的选择：它在单阶段框架下把精度拉高了一大截，同时保持较高的推理速度。

我简单对比过几个方案的实际效果，把当时考虑过的模型放在一起看会更直观：

PPYOLO不是从零设计的模型，它是在YOLOv3基础上做了大量结构改进的产物，包括主干网络替换、多尺度特征融合、更合理的正负样本匹配策略等。这些改进让它在保持单阶段速度的同时，精度和召回率都有了明显提升。对行人检测这种需要实时处理的场景来说，这是一个非常务实的取舍。

另外，PaddlePaddle生态里的PaddleDetection工具把数据加载、训练、评估、导出这些环节封装得很完整，配置文件驱动的方式也让实验管理变得清晰。我不用自己写一堆训练样板代码，这能节省大量精力，把时间花在数据分析和调参上。

1.2 项目完整链路与核心难点

一个完整的行人检测项目，远不只是“跑个训练命令”那么简单。我把整个流程拆成了六个环节：数据整理与标注、环境搭建、模型配置、训练调参、评估分析、导出部署。每个环节都有坑，但最容易翻车的其实集中在数据和配置这两块。

这个项目的技术链路大致是这样的：首先准备一批包含行人标注的图片，转成PaddleDetection支持的格式；然后基于PPYOLO配置文件修改类别数和训练参数；接着在GPU上训练得到模型权重；之后在验证集上评估mAP等指标；最后导出推理模型，部署到目标环境。

从任务角度看，行人检测有几个天然难点。第一是尺度差异大，远景行人可能只有几十个像素，近景行人却占满整幅图。第二是遮挡严重，行人之间、行人与环境之间经常互相遮挡。第三是密集场景，一群人站在一起时，模型很容易把多个人重叠识别成一个人。这些难点会在后面每个环节里反复出现，也是我调参时重点盯的地方。

2. 模型核心原理解读

2.1 PPYOLO相比经典YOLOv3改进了什么

我最初以为PPYOLO只是把YOLOv3换了个实现，训练时才发现它的改进点相当多，尤其体现在特征提取和目标匹配两个层面。简单来说，PPYOLO做了几个很关键的升级。

主干网络方面，它把原本的DarkNet换成了更强的主干结构，配合可变形卷积，让模型能更好地适应行人这种形变较大的目标。可变形卷积听起来高级，本质就是让卷积的采样位置不再固定成方方正正的格子，而是根据输入内容自适应偏移。人站着的姿势千奇百怪，固定网格感受野很难覆盖完整，可变形卷积在一定程度上解决了这个问题。

特征融合方面，PPYOLO使用了类似FPN的多尺度特征融合结构。浅层特征保留细节，适合检测小目标；深层特征语义丰富，适合检测大目标。PPYOLO把这些不同层级的特征结合起来，所以对远距离小行人和近距离大行人都能有所照顾。这个设计对行人检测特别重要，因为一张监控画面里往往同时存在不同大小的行人。

还有一个容易被忽略的改进是训练策略。PPYOLO在anchor匹配和损失计算上做了优化，简单理解就是让模型在学习正样本时更“专注”，减少背景框对梯度的干扰。实际训练中，这会让收敛更稳定，前面几百个迭代的loss曲线不会像传统YOLO那样疯狂震荡。

2.2 行人检测对模型提出的特殊要求

虽然PPYOLO本身的性能不错，但行人检测任务对模型有一些额外的要求，这些要求到了训练阶段就变成具体的超参数设置。

首先是输入分辨率。监控画面里的行人往往较小，如果直接把整张图缩到416×416，小行人可能只有几个像素，谁也检测不出来。我后来把训练和推理的输入尺寸提高到了608甚至640，小目标召回率提升明显。代价是显存占用和推理耗时增加，需要根据实际GPU资源做取舍。

其次是anchor尺寸的设置。PPYOLO需要预设一组anchor box，代表模型默认检测目标的宽高比例。行人通常是细长形状，宽高比接近1:2甚至更大，如果直接用通用模型的anchor，检测框会偏高偏扁。我在配置里专门根据行人数据重新统计了目标框分布，手动调整了anchor，效果立刻好了不少。

最后是NMS阈值。行人密集时，同一个行人可能被预测出多个互相重叠的框。NMS（非极大值抑制）阈值设太高会保留大量重复框，设太低又可能把相邻的两个行人变成一个框。经过几轮测试，我最终把NMS阈值稳定在0.45到0.5之间，这在密集行人场景下是比较合理的区间。

3. 数据准备与标注处理是成败关键

3.1 数据集整理与格式转换

很多初学者一上来就训练，结果模型效果差，第一反应就是调网络结构。其实在行人检测这种任务里，数据质量才是决定模型上限的关键因素。我这次用的数据来自某园区监控画面的脱敏截图，一共近万张图片，原始的标注文件格式比较混乱，有XML也有JSON，整理工作花了不少时间。

最终我统一转成了VOC格式，因为PaddleDetection对VOC格式支持最完善。目录结构如下：

dataset/ ├── JPImages/ # 所有训练图片 ├── Annotations/ # 每张图片对应的XML标注 └── ImageSets/ └── Main/ ├── trainval.txt └── test.txt

标注文件里最关键的信息是每个目标的类别和边界框坐标。一个典型的标注片段长这样：

<annotation> <filename>img_0001.jpg</filename> <size> <width>1280</width> <height>720</height> </size> <object> <name>person</name> <bndbox> <xmin>315</xmin> <ymin>210</ymin> <xmax>470</xmax> <ymax>650</ymax> </bndbox> </object> </annotation>

这里有一个容易忽略的细节：数据集里的trainval.txt内容是图片文件名的绝对路径还是相对路径，必须和配置文件里指定的数据集路径保持一致。我刚开始就因为路径写错，训练日志显示读取了0张图片，白白查了很久。

3.2 数据增强与正负样本平衡

数据准备不只是格式转换，更关键的是怎么让模型在有限的数据里学到更多东西。我用的训练数据量不算特别大，如果直接硬训，过拟合几乎是必然的。因此我在配置里开启了一组数据增强选项。

基本增强包括随机水平翻转、随机裁剪、色彩抖动。行人检测场景下，翻转增强特别有效，因为行人的左右朝向在监控画面里是随机的。随机裁剪则模拟了遮挡和局部可见的情况，帮助模型学会在行人部分身体被挡住时仍然给出正确预测。

稍微进阶一点的是mixup增强，也就是把两张训练图片按一定比例混合，标签也跟着线性混合。一开始我担心这种操作会搅乱行人检测的边界框，实测下来发现它能有效提升模型的泛化能力，尤其是在光照变化很大的监控场景里。

正负样本不平衡也是一个躲不开的问题。一张监控画面里往往只有几个行人，剩下的全是背景，模型很容易学会“什么都检测不到”就能把loss压得很低。PPYOLO本身有正负样本平衡机制，但数据层面我也做了辅助工作：从完全没有人出现的背景图片里挑了一批作为负样本加入训练，让模型见过更多“空场景”。这一步对降低误报率帮助很大。

3.3 标注质量的那些坑

数据清洗阶段踩过的几个坑，我觉得值得单独拎出来说一下。

第一是严重漏标。有些图片里远景行人非常小，标注员可能直接忽略了，这些漏标样本在训练时会被当成难例，模型反而学坏。我后来统一做了一个脚本，把标注框面积小于图片面积千分之一的样本单独筛选出来，逐个人工确认，该删的删，该补的补。

第二是边界框不规范。有的标注把行人从头顶一直框到脚底，有的只框到腰部，还有的把整个人体的外接矩形扩大了一圈。这种不一致会让模型学到一个很模糊的目标概念，预测框时大时小。我重新对全部标注做了一遍校验，统一了“完整包含行人、尽量贴边”的标注标准。

第三是类别标签容易混。行人和骑行的人在外观上有相似性，标注时如果不区分，模型就会把骑车的人误检为行人。这个不是PaddlePaddle的问题，而是标注规范问题。最终我要求标注人员把站立行人和骑行的场景分开处理，并在后续评估时对这两类情况分别观察。

4. 环境搭建与训练实操

4.1 安装PaddlePaddle与PaddleDetection

环境搭建这一步其实不复杂，但版本匹配问题能卡住不少人。我这次用的是一张单卡GPU，显存8G左右，操作系统是常见Linux发行版。安装时先确认了CUDA版本，再安装对应的PaddlePaddle GPU版本。

基本安装命令如下：

python -m pip install paddlepaddle-gpu

装完框架之后，接着安装PaddleDetection。我建议直接从官方仓库拉源码，而不是只装pip包，这样可以方便地查看配置文件结构和源码细节：

git clone https://github.com/PaddlePaddle/PaddleDetection.git cd PaddleDetection pip install -r requirements.txt

这里要特别提醒，安装完成后第一件事不是急着训练，而是跑一个简单的检查命令确认GPU能用。我遇到过很多人安装时报错说找不到CUDA库，最后发现是环境变量没配置好，还有人是系统里存在多个版本的CUDA运行库，导致PaddlePaddle不知道该用哪个。检查方法很简单，在Python里执行导入和版本查看命令，能正确打印出GPU信息就说明环境没问题。

4.2 配置文件关键参数修改

PaddleDetection的训练配置采用YAML文件驱动，PPYOLO的示例配置一般在configs/ppyolo目录下。我这里以实际的PPYOLO主干网络配置文件为例，说明必须改的几个位置。

最核心的改动有两处：数据集配置和类别数配置。如果不改，模型会傻傻地去找COCO数据集的80类，训练时直接报错或者输出一堆无意义结果。类别数这一项我改成了1，代表只有person这一类。

num_classes: 1 TrainReader: batch_size: 8 inputs_def: image_shape: [3, 608, 608] EvalReader: batch_size: 4 epoch: 120 LearningRate: base_lr: 0.001 schedulers: - !PiecewiseDecay gamma: 0.1 milestones: [80, 100]

batch_size和显存的关系需要重点讲一下。8G显存大约能支撑batch_size=8搭配608分辨率训练，再大一点就会报显存溢出错误。如果你显存只有6G，可以换成480分辨率或者把batch_size降到4。

学习率的设置也很有讲究。官方经验是学习率随batch_size线性缩放，batch_size越小学习率应该越低。我用batch_size=8时，base_lr设为0.001是比较稳的；如果batch_size调到16，base_lr可以适当调高到0.0015，否则收敛会偏慢。

4.3 启动训练与日志解读

配置改好后，训练命令很简单：

python tools/train.py -c configs/ppyolo/ppyolo_r50vd_dcn_1x_coco.yml

训练日志每隔一段时间会打印一行信息，里面包含当前迭代数、总损失、学习率、训练耗时等信息。我会在训练开始后的前几百个迭代重点观察loss曲线。

正常的情况是loss快速下降，然后进入缓慢下降阶段，中间会有正常的起伏，但整体趋势是向下的。如果loss出现断崖式跳变，先别慌，可能是学习率在指定milestone处降低了，这是正常现象。如果loss一直上升或者反复震荡，那就是超参数有问题，需要停下来检查。

训练过程中我还习惯每隔一段时间手动推理几张验证集图片，肉眼看检测效果。Loss曲线只能告诉你模型在收敛，但看不出它学到的到底是不是行人的特征轮廓。有一次loss降得很快，我打开检测结果一看，模型把所有竖直形状的物体都当成行人了，电线杆、路灯、树干全被框住。这就是典型的过拟合倾向，需要赶紧调整数据增强和正则化策略。

5. 训练效果评估与错误样本分析

5.1 评估指标怎么算

训练完成后，第一步不是急着部署，而是用验证集做一次客观评估。PaddleDetection提供了现成的评估命令：

python tools/eval.py \ -c configs/ppyolo/ppyolo_r50vd_dcn_1x_coco.yml \ -o weights=output/ppyolo_r50vd_dcn_1x_coco/best_model.pdparams

评估结果会输出一组指标，最核心的是mAP，也就是所有类别AP的平均值。因为本项目只有一个person类别，mAP就等于person类别的AP。这里的AP是在不同IoU阈值下计算的平均精度，通常默认用IoU=0.5作为判断标准。

只看mAP还不够，我会额外关注两个细分指标：召回率和误检数。行人检测场景里，漏检比误检更让人头疼，宁愿偶尔把非行人框进来，也不要漏掉真正的人。对监控应用来说，假阴性会直接导致计数偏差或者安全事件漏报。

为了拿到更细节的数据，我把验证集按场景分组统计：白天、夜晚、远距离、近距离、遮挡多这五类。最终发现模型在白天和近距离场景下的表现接近完美，但在夜晚和远距离场景下AP下降了超过十个百分点。这说明训练数据里夜晚样本和远距离样本的数量不够，后续需要针对性补充。

5.2 漏检和误检怎么排查

评估完成后，我会把所有错误样本导出到文件夹里，逐个翻看。这个环节最花时间，但也是提升模型效果最有效的途径。

漏检样本有两种典型情况。第一种是行人太小，整个目标只有二三十个像素，模型在浅层特征上根本没提取到有效信息。对这种问题，我把输入分辨率从608进一步提高，同时增强了对小目标样本的过采样，效果有一定改善。第二种是行人被大面积遮挡，只露出一只手或者半个头，这属于Information不足的问题，单纯调参很难根除，只能靠增加这类训练样本慢慢缓解。

误检样本同样分情况。最常见的是行人雕像、海报上的人像被当成真实行人。这类误检的本质是模型学到了“人形轮廓”而没学到“立体人体特征”。处理办法是收集一批包含人形物体但不包含真实行人的图片作为负样本，加入训练集重新训练。另一个误检来源是夜间灯光造成的轮廓错觉，这种通过增加夜晚难负样本也能改善。

整个评估和错误分析过程，我前后做了三轮。每轮先评估、再看错误例、补数据或调参数，然后重新训练。三轮下来mAP提升了大概6个百分点，这个提升幅度主要靠的就是错误样本分析，而不是盲调超参数。

6. 模型导出与工程化部署

6.1 导出推理模型

训练得到的文件是训练权重，里面还包含优化器状态等训练信息，不能直接拿去部署。正式上线前需要把训练权重转换成推理模型。PaddleDetection的导出命令如下：

python tools/export_model.py \ -c configs/ppyolo/ppyolo_r50vd_dcn_1x_coco.yml \ -o weights=output/ppyolo_r50vd_dcn_1x_coco/best_model.pdparams \ --output_dir=deploy/export

导出成功后会在目录下生成一个文件夹，里面包含推理模型文件、配置文件等。这里有一个容易踩的坑：导出时所用的配置必须和训练时保持一致，包括输入尺寸和预处理方式。我因为改了配置文件里的测试分辨率没有同步改导出配置，导致推理出来的检测框位置整体偏移，看起来就是检测框和行人总是错开一段距离。

6.2 部署到实际环境与速度优化

推理模型生成后，直接在服务器上跑推理脚本就能验证效果：

python tools/infer.py \ -c configs/ppyolo/ppyolo_r50vd_dcn_1x_coco.yml \ -o weights=deploy/export/model.pdmodel \ --infer_img=test.jpg

不过真正部署的时候，我会用服务化推理框架来处理视频流，而不是一张一张图片手动调用。一次请求对应一帧画面，模型输出检测框、类别和置信度，再通过接口转给业务系统。这种模式下，单帧处理时间必须控制住，否则视频流会越积越多。

优化的第一步是调整batch size。尽管推理可以一次性处理多张图，但如果视频流本身是一帧一帧来的，batch太小反倒会增加调度损耗。我把GPU推理的batch设为1，重点优化单帧延迟，最终在目标GPU上单帧时间稳定在30毫秒以内，满足实时需求。

如果还想进一步压缩延迟，可以在部署阶段做半精度推理。半精度本质上就是用更小的数据类型表示模型参数和中间结果，显存占用减半，速度也能提升。但要注意，部分GPU架构对半精度推理支持很好，旧一些的卡反而可能更慢，需要实测对比。我当时在同一组测试数据上比较了单精度和半精度的推理时间和检测结果，确认精度几乎无损失后才启用了半精度。

7. 常见问题排查与避坑实录

7.1 训练时loss不下降或乱跳

训练过程中最容易遇到的就是loss不下降。这种情况我的排查顺序是：先看数据读取是否正常，再看学习率，最后看类别配置。

数据读取异常表现为训练日志里的batch处理时间异常长，或者每个batch的loss都差不多。我大多是因为标注文件和图片没有对应上，某张图片的XML里写的目标框坐标超出了图片尺寸，导致训练加载时不断报错。用脚本检查一遍标注合法性就能解决。

学习率过高的表现是loss曲线剧烈震荡，像锯齿一样上上下下。此时把base_lr降一个数量级往往就见效。学习率过低则表现为loss下降缓慢，几百个迭代后还在同一个量级徘徊，这时适当增大学习率或者采用warmup策略能加快收敛。

7.2 显存不足与OOM报错

训练PPYOLO最现实的限制就是显存。OOM报错通常发生在模型刚开始训练时，或者训练到一半突然出现。刚开始就OOM，说明配置里的batch_size或输入尺寸超出显卡能力，直接调小即可。

训练到一半才OOM的情况更有迷惑性。我遇到过一次，原因是一个batch里的图片分辨率差异很大，数据处理时把所有图都填充到统一尺寸，导致某些batch的实际计算量远超平均值。解决思路是在配置里把输入尺寸固定，不采用原始尺寸训练，这样显存占用会稳定很多。

还有一个容易被忽视的点是GPU显存碎片。模型在训练过程中会占用多块连续显存，如果同一张卡上还跑了其他任务，即使总显存看起来够用也可能分配失败。保持GPU环境干净，或者给训练容器单独锁定一张卡，能有效避免这种问题。

7.3 检测效果不理想时的自检清单

模型训完后效果不好，先别急着改网络结构，我一般按下面这张表逐项排查：

这套自检清单的核心思想是：一个模型的效果是数据、配置、标注三者共同决定的，当你已经确认配置正确、数据质量过关之后，再去考虑更复杂的网络设计才有意义。

最后再分享一个我这次项目里印象最深的小经验。训练期间我在验证集上发现模型对侧身行人的召回特别差，一开始怀疑是标注问题，后来翻开原始图片才发现侧身行人数量在训练集里占比不足。我没有硬调模型，而是专门花时间翻转和收集了一批侧身样本重新训练，效果立竿见影。很多时候，模型效果上不去，不是模型不够强，而是数据和标注没有把该给的信息给足。