• 人工智能
• 深度学习
• 计算机视觉
• NLP
• 语音

PP-HumanV2 是飞桨（PaddlePaddle）官方基于 PaddleDetection 打造的行人场景端到端分析工具，覆盖行人检测、多目标跟踪、跨镜跟踪（ReID）、26 种人体属性识别以及摔倒、打架、抽烟、打电话、闯入等异常行为识别。本文以modelcenter/PP-HumanV2/download_cn.md为骨架，完整给出各任务的预训练模型下载清单、解压部署方式、配置文件中模型路径的自动下载机制，并结合仓库内 下载实现 与 推理配置 源码，深入讲解模型从下载、解压到被 Pipeline 加载调用的完整链路，帮助开发者快速上手 PP-HumanV2 的本地化部署。

一、PP-HumanV2 模型体系总览

PP-HumanV2 不是单一模型，而是一套面向不同业务场景的组合式模型 Pipeline。官方为不同任务提供了目标检测、属性识别、行为识别、ReID 四类预训练模型，用户可以按需组合下载使用。根据仓库中 info.yaml 的描述，PP-HumanV2 定位于"飞桨行人场景分析工具"，覆盖计算机视觉中的人体检测、关键点检测、行为识别三个子任务，典型应用包括智慧安防下的摔倒检测、打架识别与进出管理。

从 Pipeline 主程序 的源码结构可以看到，整套系统的运行模式分为四种：

关键点：绝大多数任务都以MOT（多目标跟踪）模型为前置基础——属性识别、摔倒识别、抽烟识别、打电话识别、跨镜跟踪都依赖 MOT 先输出"带 ID 的行人框"，再进入各自的专用模型。因此下载模型时，mot_ppyoloe_l_36e_pipeline.zip或mot_ppyoloe_s_36e_pipeline.zip往往是最先要准备的那个包。

二、全任务模型下载清单（官方预训练权重）

下表为 PP-HumanV2 官方提供的各任务预训练模型，包含端到端速度、模型方案与体积。其中端到端速度的测试环境为 T4 GPU + TensorRT FP16，且包含数据预处理、模型预测、后处理的全流程耗时；模型精度为融合数据集（开源数据集 + 企业数据集）的结果，ReID 模型精度为 Market1501 数据集测试结果。

解读这张表时要注意三点：

1. 一个任务可能由多个模型接力完成：例如摔倒识别 = MOT（跟踪）+ 关键点检测（HRNet）+ STGCN（基于关键点的行为识别）；抽烟识别 = MOT + 基于人体 ID 的局部目标检测。部署时需把方案列中的每个链接都下载。
2. "打架识别"行中的链接指向 MOT 模型包，但其实际模型是视频分类模型（ppTSM），体积为 90M——这也是为什么必须查看配置文件中VIDEO_ACTION.model_dir指向的真实地址（见下文第五节）。
3. 同一模型可复用：mot_ppyoloe_l_36e_pipeline.zip同时承担检测、跟踪、闯入识别乃至属性识别/行为识别的前置检测，下载一次即可服务多个任务。

三、手动下载与解压部署

官方推荐的部署方式是手动下载后统一解压到./output_inference文件夹：

# 以高精度多目标跟踪模型为例 wget https://bj.bcebos.com/v1/paddledet/models/pipeline/mot_ppyoloe_l_36e_pipeline.zip unzip mot_ppyoloe_l_36e_pipeline.zip -d ./output_inference # 若启用属性识别/摔倒识别等，将所需模型同样解压到该目录 unzip PPLCNet_x1_0_person_attribute_945_infer.zip -d ./output_inference unzip dark_hrnet_w32_256x192.zip -d ./output_inference unzip STGCN.zip -d ./output_inference

统一存放output_inference目录的好处是：推理配置（如infer_cfg_pphuman.yml）中的model_dir可以统一改为本地相对路径，例如./output_inference/mot_ppyoloe_l_36e_pipeline，避免推理时重复触发联网下载。开发者也可以将每个模型分别解压到独立目录，只要在配置中把model_dir指向对应的解压目录即可。

四、配置文件中的模型路径与自动下载机制

原文档明确指出：

在配置文件中，模型路径默认为模型的下载路径，如果用户不修改，则在推理时会自动下载对应的模型。

这条规则背后有完整的源码支撑。查看 PP-HumanV2 的核心推理配置 infer_cfg_pphuman.yml，可以看到每个模块的model_dir默认填的就是第二节表格中的下载 URL：

crop_thresh: 0.5 attr_thresh: 0.5 kpt_thresh: 0.2 visual: True warmup_frame: 50 DET: model_dir: https://bj.bcebos.com/v1/paddledet/models/pipeline/mot_ppyoloe_l_36e_pipeline.zip batch_size: 1 MOT: model_dir: https://bj.bcebos.com/v1/paddledet/models/pipeline/mot_ppyoloe_l_36e_pipeline.zip tracker_config: pipeline/config/tracker_config.yml batch_size: 1 skip_frame_num: -1 # preferably no more than 3 enable: False KPT: model_dir: https://bj.bcebos.com/v1/paddledet/models/pipeline/dark_hrnet_w32_256x192.zip batch_size: 8 ATTR: model_dir: https://bj.bcebos.com/v1/paddledet/models/pipeline/PPLCNet_x1_0_person_attribute_945_infer.zip batch_size: 8 enable: False VIDEO_ACTION: model_dir: https://videotag.bj.bcebos.com/PaddleVideo-release2.3/ppTSM_fight.zip batch_size: 1 frame_len: 8 sample_freq: 7 short_size: 340 target_size: 320 enable: False SKELETON_ACTION: model_dir: https://bj.bcebos.com/v1/paddledet/models/pipeline/STGCN.zip batch_size: 1 max_frames: 50 display_frames: 80 coord_size: [384, 512] enable: False ID_BASED_DETACTION: model_dir: https://bj.bcebos.com/v1/paddledet/models/pipeline/ppyoloe_crn_s_80e_smoking_visdrone.zip batch_size: 8 threshold: 0.6 display_frames: 80 skip_frame_num: 2 enable: False ID_BASED_CLSACTION: model_dir: https://bj.bcebos.com/v1/paddledet/models/pipeline/PPHGNet_tiny_calling_halfbody.zip batch_size: 8 threshold: 0.8 display_frames: 80 skip_frame_num: 2 enable: False REID: model_dir: https://bj.bcebos.com/v1/paddledet/models/pipeline/reid_model.zip batch_size: 16 enable: False

这份配置同时揭示了几个重要的实操细节：

• enable开关控制模块是否加载：MOT、ATTR、VIDEO_ACTION、SKELETON_ACTION、ID_BASED_DETACTION、ID_BASED_CLSACTION、REID均默认为False，需要在运行时通过avtivity_list参数显式启用对应任务，Pipeline 才会实例化对应模型（见 pipeline.py 中PipePredictor.__init__对各任务的with_*分支判断）。
• VIDEO_ACTION的真实模型是 ppTSM_fight：打架识别实际使用的模型包是ppTSM_fight.zip（90M 视频分类模型），这一点与下载表格中的"视频分类"标注一致。
• 阈值类参数决定识别灵敏度：crop_thresh: 0.5（检测框裁剪阈值）、attr_thresh: 0.5（属性判定阈值）、kpt_thresh: 0.2（关键点阈值）、ID_BASED_DETACTION.threshold: 0.6、ID_BASED_CLSACTION.threshold: 0.8，部署时可按场景精度要求调整。
• SKELETON_ACTION的coord_size: [384, 512]为送入 STGCN 的关键点坐标归一化尺寸，max_frames: 50为判定一次行为所需的关键点帧缓冲数，对应源码中KeyPointBuff(skeleton_action_frames)的帧数缓存逻辑。

自动下载的完整链路

当用户不改动model_dir（保持 URL）时，推理启动阶段会自动完成下载、校验、解压。这条链路定义在 download.py：

1. 入口判断：auto_download_model(model_path)通过is_url()判断model_dir是否为 URL（支持http://、https://、ppdet://三种前缀），若为本地路径则直接返回None、跳过下载。
2. 缓存目录：权重统一缓存到~/.cache/paddle/infer_weights（WEIGHTS_HOME），同名文件已存在且 MD5 校验通过时直接复用，不重复下载。
3. MD5 完整性校验：MODEL_URL_MD5_DICT为每个官方模型包预置了 MD5 值（例如mot_ppyoloe_l_36e_ppvehicle.zip对应3859d1a26e0c498285c2374b1a347013、dark_hrnet_w32_256x192.zip对应a20d5f6ca087bff0e9f2b18df45a36f2），下载后按 4096 字节分块计算 MD5，不匹配则重新下载，最多重试 3 次（DOWNLOAD_RETRY_LIMIT = 3）。
4. 安全解压：zip/tar 包先解压到临时目录tmp，成功后合并移动至目标目录，并删除压缩包，防止解压中断产生残损目录。
5. 目录名归一化：个别包的解压目录名与压缩包名不一致（如ppTSM_fight解压后目录名为ppTSM），decompress_name_map会做映射修正，保证model_dir指向正确路径。
6. Pipeline 联动：get_model_dir_with_list()/get_model_dir()（见 pipeline.py）会在初始化各预测器前遍历配置，对每个model_dir调用auto_download_model，并把下载后的本地路径写回cfg[key]["model_dir"]，因此后续SDE_Detector、AttrDetector、KeyPointDetector等模块拿到的都是可直接加载的本地模型目录。

五、模型如何被 Pipeline 调度使用

理解模型下载后如何被使用，有助于按任务裁剪模型、减少不必要的下载。根据 pipeline.py 的初始化与推理逻辑，各模型的调度关系如下：

• 图片输入（单帧）：走predict_image，先DET检测行人框（过滤阈值crop_thresh），再对裁剪框逐个做ATTR属性识别，输出检测框 + 属性标注图。
• 视频输入（多帧）：走predict_video，默认开启MOT多目标跟踪（基于SDE_Detector+tracker_config.yml中的跟踪器参数），随后按启用的任务依次执行：
  • ATTR：对每个跟踪目标框裁剪后送入属性模型；
  • SKELETON_ACTION：对裁剪框做关键点检测（KeyPointDetector，使用 dark_hrnet_w32），关键点经KeyPointBuff按 ID 缓存max_frames帧后送入 STGCN 判定摔倒行为；
  • ID_BASED_DETACTION：基于人体 ID 的目标检测，用于抽烟识别（ppyoloe_crn_s）；
  • ID_BASED_CLSACTION：基于人体 ID 的图像分类，用于打电话识别（PPHGNet_tiny）；
  • VIDEO_ACTION：按frame_len、sample_freq、short_size采集视频片段送入 ppTSM 做打架识别；
  • REID：每 10 帧对目标提取 ReID 特征，供跨镜跟踪（MTMCT）使用。
• 人流计数与轨迹：do_entrance_counting、draw_center_traj属于 MOT 侧增强功能，开启时会调用flow_statistic统计进出客流并绘制中心轨迹，不需要额外模型，只依赖 MOT 结果。

如果你只用"行人检测"功能，实际只需要下载 MOT 模型包并只勾选MOT任务即可，其他模块保持enable: False，Pipeline 不会实例化也不会触发对应 URL 的下载。

六、注意事项与部署提示

沿用原文档的官方注意事项，并结合源码补充如下部署要点：

1. 模型精度口径：模型精度为融合数据集（开源数据集 + 企业数据集）的训练结果；ReID 模型精度为 Market1501 数据集测试结果，跨数据集使用时精度可能波动。
2. 速度口径：预测速度为T4 下开启 TensorRT FP16的效果，且包含数据预处理、模型预测、后处理全流程。若在 CPU 或关闭 TensorRT 的环境下运行，实际耗时会长于表中数值。
3. 自动下载的触发条件：只要配置中的model_dir保持为 URL，且缓存目录~/.cache/paddle/infer_weights中没有校验通过的同名包，推理启动时就会自动下载。离线/内网环境请务必预先手动下载并解压到./output_inference，再将配置改为本地路径。
4. 任务开关与模型裁剪：avtivity_list中的任务名（MOT、ATTR、VIDEO_ACTION、SKELETON_ACTION、ID_BASED_DETACTION、ID_BASED_CLSACTION、REID、do_entrance_counting、draw_center_traj）与配置文件中的enable开关共同决定加载哪些模型；不需要的功能保持关闭可节省显存与启动时间。
5. 跟踪器配置独立：MOT 的跟踪参数（如匹配阈值、轨迹保活时长等）在 tracker_config.yml 中单独维护，MOT.tracker_config指向该文件，调跟踪效果时只需改这份配置，无需重新下载模型。

七、快速上手：从下载到运行的最小流程

结合仓库中的 Gradio 示例应用（app.yml声明的app_file: app.py）与 requirements.txt，最小运行流程为：

# 1. 安装依赖 pip install -r modelcenter/PP-HumanV2/requirements.txt # 2. 启动 APP（首次运行会自动下载激活任务所需模型） python modelcenter/PP-HumanV2/APP/app.py

app.py中，图片 Tab 默认勾选ATTR属性识别，视频 Tab 提供MOT、ATTR、VIDEO_ACTION、SKELETON_ACTION、ID_BASED_DETACTION、ID_BASED_CLSACTION、REID、do_entrance_counting、draw_center_traj多选任务；当勾选do_entrance_counting或draw_center_traj时会自动追加MOT任务（源码中的显式判断），保证计数/轨迹功能有跟踪结果可用。视频输入仅支持.mp4与.avi格式。

更多关于模型整体能力、benchmark 指标与在线体验入口，可继续阅读同目录下的 benchmark_cn.md 与 introduction_cn.ipynb；PP-HumanV2 的完整概览图可参考 pphumanv2.png。

• 人工智能
• 深度学习
• 计算机视觉
• NLP
• 语音