基于 SCRFD 的人体检测实战InsightFacescrfd_person模型全流程解析【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface本指南以 InsightFace 仓库中的人体检测示例为主线讲解如何基于 SCRFDSample and Computation Redistribution for Efficient Face DetectionICLR-2022方案构建人体检测应用从安装insightfacePython 库、自动下载scrfd_person_2.5g.onnx模型到单次前向推理同时输出全身检测框full-body bbox与可见区域visible region并完成结果可视化。读完本文你将掌握该示例的完整调用链、关键参数含义以及底层 SCRFD 推理管线的实现原理可直接复用到自己的行人检测、遮挡分析等任务中。一、为什么用 SCRFD 做人体检测InsightFace 是一个覆盖 2D/3D 人脸分析全链路检测、识别、属性、重建等的开源项目其人脸检测部分主要依赖两种方案RetinaFace 与 SCRFD。其中 SCRFD 由项目作者提出是一篇关于高效高精度人脸检测的工作发表于 ICLR-2022其核心思想是通过样本再分配Sample Redistribution与计算再分配Computation Redistribution在有限算力下获得更高的检测精度。完整的训练、评估与模型转换代码位于仓库的 detection/scrfd 目录基于 mmdetection 框架实现。人体检测示例正是将这套 SCRFD 方法直接复用到人这一目标类别上复用 SCRFD 的检测头与后处理逻辑仅将训练类别从人脸替换为人模型命名沿用 SCRFD 的算力分级体系scrfd_person_2.5g.onnx中的2.5g表示约 2.5 GFLOPs 的计算量级别属于轻量级模型适合在普通 CPU/GPU 上实时推理。该示例的核心价值在于在一次前向推理中同时得到全身检测框与对应的可见区域——这对于行人遮挡分析、人体姿态预处理、目标跟踪等场景非常实用。二、快速开始安装与模型加载1. 安装 Python 库示例依赖 InsightFace 的 Python 包需要 0.4 及以上版本scrfd_person.py 中有assert insightface.__version__0.4的显式断言pip install -U insightface2. 加载人体检测模型import insightface detector insightface.model_zoo.get_model(scrfd_person_2.5g.onnx, downloadTrue) detector.prepare(0, nms_thresh0.5)get_model的调用链为model_zoo.get_model→ModelRouter→ 返回SCRFD实例见 model_zoo.py 与 model_zoo/init.py。当传入downloadTrue时模型会自动从官方存储服务器下载到本地模型目录默认~/.insightface/models无需手动准备权重文件。prepare的第一个参数ctx_id控制推理设备ctx_id 0使用 GPU默认按CUDAExecutionProvider→CPUExecutionProvider顺序选择见 get_default_providersctx_id 0强制使用 CPU 执行见 scrfd.py。3. prepare 的常用参数prepare(ctx_id, **kwargs)支持以下关键配置源码见 scrfd.py参数默认值说明nms_thresh0.4NMS 的 IoU 阈值示例中调高到 0.5 以减少重叠框的合并力度det_thresh0.5检测置信度阈值低于该分数的候选框会被直接过滤input_size由模型决定推理输入尺寸多尺度时传[(w1,h1),(w2,h2)]列表三、单次前向全身框 可见区域示例的核心函数是detect_person它体现了一个前向、两种输出的设计完整实现见 scrfd_person.pydef detect_person(img, detector): bboxes, kpss detector.detect(img) bboxes np.round(bboxes[:,:4]).astype(np.int) kpss np.round(kpss).astype(np.int) kpss[:,:,0] np.clip(kpss[:,:,0], 0, img.shape[1]) kpss[:,:,1] np.clip(kpss[:,:,1], 0, img.shape[0]) vbboxes bboxes.copy() vbboxes[:,0] kpss[:, 0, 0] vbboxes[:,1] kpss[:, 0, 1] vbboxes[:,2] kpss[:, 4, 0] vbboxes[:,3] kpss[:, 4, 1] return bboxes, vbboxes拆解其逻辑detector.detect(img)返回两个结果bboxes形状(N, 5)每行[x1, y1, x2, y2, score]即全身检测框与置信度kpss形状(N, 5, 2)即每个人体实例的5 个关键点keypoints坐标use_kpsTrue时才会输出见 scrfd.py。关键点裁剪将关键点坐标clip到图像边界内防止越界导致可视化时切片出错。可见区域推导取每个人体的第 0 个关键点kpss[i, 0]作为可见区域的左上角第 4 个关键点kpss[i, 4]作为右下角构造出vbboxesvisible bounding boxes。这是该示例最精妙的地方——5 个关键点编码了可见区域的对角范围因此无需第二次推理即可获得遮挡情形下人实际露出的部位。关键点不参与坐标四舍五入之外的任何处理kpss直接决定可见区域而bboxes的前 4 列决定全身框。四、结果可视化绿框全身、蓝块可见区域示例在 scrfd_person.py 的main中完成绘制绿色矩形cv2.rectangle颜色(0,255,0)线宽 1表示全身检测框蓝色半透明区域颜色(255,0,0)alpha0.8的加权混合表示可见区域即被遮挡之外实际可见的躯干部分蓝色角点圆圈cv2.circle在可见区域四角绘制标出可见区域的边界。alpha 0.8 color (255, 0, 0) for c in range(3): img[vy1:vy2,vx1:vx2,c] img[vy1:vy2, vx1:vx2, c]*alpha color[c]*(1.0-alpha)这段逐通道的alpha混合是 OpenCV 中半透明蒙版的经典写法用 80% 的原始像素叠加 20% 的蓝色既能突出可见区域又不会完全遮挡画面内容。运行示例脚本# 准备测试图片将图片放入 data/images/ 目录*.jpg # 先创建输出目录 mkdir -p outputs python scrfd_person.py脚本通过glob.glob(data/images/*.jpg)读取输入图片逐张检测并把结果写入./outputs/同名文件。若希望更换输入尺寸可在prepare中显式传入input_size(640, 640)示例作者声明在输入尺寸 640 上完成测试。五、底层原理SCRFD 的 ONNX 推理管线要真正理解detect_person拿到的bboxes与kpss从何而来需要深入 SCRFD 推理实现。1. 模型路由与加载get_model(scrfd_person_2.5g.onnx, downloadTrue)内部会若本地不存在该.onnx文件通过download_onnx(models, ...)自动下载存储目录默认~/.insightface/models用ModelRouter创建 ONNX Runtime 会话并根据模型输出数量路由到对应封装类——输出数 ≥ 5 的模型统一路由为SCRFD见 model_zoo.py。2. 输出结构的自适应解析SCRFD 在_init_vars中根据 ONNX 输出张量数量自适应推断网络结构见 scrfd.py输出数FPN 层数特征步长stride关键点63[8, 16, 32]否93[8, 16, 32]是105[8, 16, 32, 64, 128]否155[8, 16, 32, 64, 128]是scrfd_person_2.5g.onnx属于输出数为 9 的类型3 层 FPN、步长[8,16,32]、带 5 关键点预测因此detect会返回非空的kpss。3. 前向与解码forward见 scrfd.py的执行要点输入预处理cv2.dnn.blobFromImage使用均值127.5、标准差128.0进行归一化与训练配置 base_2.5g.py 中的img_norm_cfg一致并swapRBTrue将 BGR 转为 RGB解码distance2bbox将每个 anchor 中心到四条边的距离预测解码为检测框distance2kps将距离预测解码为关键点坐标见 scrfd.py多尺度候选_detect_candidates会对图像做保持宽高比的 resize 与 paddingletterbox再按det_scale把坐标还原回原图见 scrfd.py多尺度融合默认推理尺寸为[(128, 128), (640, 640)]DEFAULT_DET_SIZES最终将各尺度候选框合并后统一做 NMS见 scrfd.py 与 scrfd.py返回结构detect最终返回bboxes (N,5)与kpss (N,5,2)并支持max_num与metric参数控制最多返回的检测目标数及其排序依据见 scrfd.py。4. 与训练配置的对应人体检测模型与 SCRFD 训练配置 保持一致的超参设定可作为调参依据训练/测试输入尺寸均为(640, 640)base_2.5g.py 与 base_2.5g.pyFPN 步长[8, 16, 32]anchor 比例为[1.0]、尺度为[1, 2]base_2.5g.py推理时的 NMS 阈值对应配置中的iou_threshold0.45base_2.5g.py而示例代码将nms_thresh调整为 0.5 以获得更宽松的合并行为若要自行把 PyTorch 训练权重转换为可部署的 ONNX 模型可参考 scrfd2onnx.py转换后默认支持动态输入也可通过--shape 640 640固定输入尺寸以配合 onnx-simplifier 优化。六、扩展把示例用到自己的数据上在 scrfd_person.py 基础上做最小改造即可适配任意输入源更换图片目录把glob.glob(data/images/*.jpg)替换为你自己的图片路径模式接入摄像头/视频流将cv2.imread替换为cv2.VideoCapture逐帧读取并保持detect_person调用不变调整检测敏感度降低det_thresh例如 0.3可召回更多低置信度的遮挡目标代价是误检增加提高nms_thresh可保留更多相互重叠的检测框约束输出数量调用detector.detect(img, max_num10)只保留排序靠前的目标排序依据由metric控制default兼顾面积与居中程度max只看面积。七、小结InsightFace 的人体检测示例是一个以最小代码量复用 SOTA 检测器的范本通过pip install insightface 两行模型加载代码即可获得基于 SCRFD 的全身检测与可见区域估计能力。其技术要点可总结为模型scrfd_person_2.5g.onnx轻量级 SCRFD 变体支持 5 关键点输出自动下载无需手工准备单次前向双输出全身框来自 bbox 头可见区域由关键点 0/4 推导而来无需二次推理可视化约定绿色矩形为全身框、蓝色半透明蒙版为可见区域底层管线ONNX Runtime 推理 FPN 多尺度 anchor 解码 NMS 后处理全部封装在 SCRFD 类中可平滑迁移到视频流、多尺度检测等场景。该示例完整代码与模型加载逻辑均可在仓库中直接查阅示例脚本、SCRFD 推理实现、SCRFD 训练与评估文档。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 18:17:36 · 阅读 1.2k 基于 SCRFD 的人体检测实战：InsightFace `scrfd_person` 模型全流程解析
基于 SCRFD 的人体检测实战InsightFacescrfd_person模型全流程解析【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface本指南以 InsightFace 仓库中的人体检测示例为主线讲解如何基于 SCRFDSample and Computation Redistribution for Efficient Face DetectionICLR-2022方案构建人体检测应用从安装insightfacePython 库、自动下载scrfd_person_2.5g.onnx模型到单次前向推理同时输出全身检测框full-body bbox与可见区域visible region并完成结果可视化。读完本文你将掌握该示例的完整调用链、关键参数含义以及底层 SCRFD 推理管线的实现原理可直接复用到自己的行人检测、遮挡分析等任务中。一、为什么用 SCRFD 做人体检测InsightFace 是一个覆盖 2D/3D 人脸分析全链路检测、识别、属性、重建等的开源项目其人脸检测部分主要依赖两种方案RetinaFace 与 SCRFD。其中 SCRFD 由项目作者提出是一篇关于高效高精度人脸检测的工作发表于 ICLR-2022其核心思想是通过样本再分配Sample Redistribution与计算再分配Computation Redistribution在有限算力下获得更高的检测精度。完整的训练、评估与模型转换代码位于仓库的 detection/scrfd 目录基于 mmdetection 框架实现。人体检测示例正是将这套 SCRFD 方法直接复用到人这一目标类别上复用 SCRFD 的检测头与后处理逻辑仅将训练类别从人脸替换为人模型命名沿用 SCRFD 的算力分级体系scrfd_person_2.5g.onnx中的2.5g表示约 2.5 GFLOPs 的计算量级别属于轻量级模型适合在普通 CPU/GPU 上实时推理。该示例的核心价值在于在一次前向推理中同时得到全身检测框与对应的可见区域——这对于行人遮挡分析、人体姿态预处理、目标跟踪等场景非常实用。二、快速开始安装与模型加载1. 安装 Python 库示例依赖 InsightFace 的 Python 包需要 0.4 及以上版本scrfd_person.py 中有assert insightface.__version__0.4的显式断言pip install -U insightface2. 加载人体检测模型import insightface detector insightface.model_zoo.get_model(scrfd_person_2.5g.onnx, downloadTrue) detector.prepare(0, nms_thresh0.5)get_model的调用链为model_zoo.get_model→ModelRouter→ 返回SCRFD实例见 model_zoo.py 与 model_zoo/init.py。当传入downloadTrue时模型会自动从官方存储服务器下载到本地模型目录默认~/.insightface/models无需手动准备权重文件。prepare的第一个参数ctx_id控制推理设备ctx_id 0使用 GPU默认按CUDAExecutionProvider→CPUExecutionProvider顺序选择见 get_default_providersctx_id 0强制使用 CPU 执行见 scrfd.py。3. prepare 的常用参数prepare(ctx_id, **kwargs)支持以下关键配置源码见 scrfd.py参数默认值说明nms_thresh0.4NMS 的 IoU 阈值示例中调高到 0.5 以减少重叠框的合并力度det_thresh0.5检测置信度阈值低于该分数的候选框会被直接过滤input_size由模型决定推理输入尺寸多尺度时传[(w1,h1),(w2,h2)]列表三、单次前向全身框 可见区域示例的核心函数是detect_person它体现了一个前向、两种输出的设计完整实现见 scrfd_person.pydef detect_person(img, detector): bboxes, kpss detector.detect(img) bboxes np.round(bboxes[:,:4]).astype(np.int) kpss np.round(kpss).astype(np.int) kpss[:,:,0] np.clip(kpss[:,:,0], 0, img.shape[1]) kpss[:,:,1] np.clip(kpss[:,:,1], 0, img.shape[0]) vbboxes bboxes.copy() vbboxes[:,0] kpss[:, 0, 0] vbboxes[:,1] kpss[:, 0, 1] vbboxes[:,2] kpss[:, 4, 0] vbboxes[:,3] kpss[:, 4, 1] return bboxes, vbboxes拆解其逻辑detector.detect(img)返回两个结果bboxes形状(N, 5)每行[x1, y1, x2, y2, score]即全身检测框与置信度kpss形状(N, 5, 2)即每个人体实例的5 个关键点keypoints坐标use_kpsTrue时才会输出见 scrfd.py。关键点裁剪将关键点坐标clip到图像边界内防止越界导致可视化时切片出错。可见区域推导取每个人体的第 0 个关键点kpss[i, 0]作为可见区域的左上角第 4 个关键点kpss[i, 4]作为右下角构造出vbboxesvisible bounding boxes。这是该示例最精妙的地方——5 个关键点编码了可见区域的对角范围因此无需第二次推理即可获得遮挡情形下人实际露出的部位。关键点不参与坐标四舍五入之外的任何处理kpss直接决定可见区域而bboxes的前 4 列决定全身框。四、结果可视化绿框全身、蓝块可见区域示例在 scrfd_person.py 的main中完成绘制绿色矩形cv2.rectangle颜色(0,255,0)线宽 1表示全身检测框蓝色半透明区域颜色(255,0,0)alpha0.8的加权混合表示可见区域即被遮挡之外实际可见的躯干部分蓝色角点圆圈cv2.circle在可见区域四角绘制标出可见区域的边界。alpha 0.8 color (255, 0, 0) for c in range(3): img[vy1:vy2,vx1:vx2,c] img[vy1:vy2, vx1:vx2, c]*alpha color[c]*(1.0-alpha)这段逐通道的alpha混合是 OpenCV 中半透明蒙版的经典写法用 80% 的原始像素叠加 20% 的蓝色既能突出可见区域又不会完全遮挡画面内容。运行示例脚本# 准备测试图片将图片放入 data/images/ 目录*.jpg # 先创建输出目录 mkdir -p outputs python scrfd_person.py脚本通过glob.glob(data/images/*.jpg)读取输入图片逐张检测并把结果写入./outputs/同名文件。若希望更换输入尺寸可在prepare中显式传入input_size(640, 640)示例作者声明在输入尺寸 640 上完成测试。五、底层原理SCRFD 的 ONNX 推理管线要真正理解detect_person拿到的bboxes与kpss从何而来需要深入 SCRFD 推理实现。1. 模型路由与加载get_model(scrfd_person_2.5g.onnx, downloadTrue)内部会若本地不存在该.onnx文件通过download_onnx(models, ...)自动下载存储目录默认~/.insightface/models用ModelRouter创建 ONNX Runtime 会话并根据模型输出数量路由到对应封装类——输出数 ≥ 5 的模型统一路由为SCRFD见 model_zoo.py。2. 输出结构的自适应解析SCRFD 在_init_vars中根据 ONNX 输出张量数量自适应推断网络结构见 scrfd.py输出数FPN 层数特征步长stride关键点63[8, 16, 32]否93[8, 16, 32]是105[8, 16, 32, 64, 128]否155[8, 16, 32, 64, 128]是scrfd_person_2.5g.onnx属于输出数为 9 的类型3 层 FPN、步长[8,16,32]、带 5 关键点预测因此detect会返回非空的kpss。3. 前向与解码forward见 scrfd.py的执行要点输入预处理cv2.dnn.blobFromImage使用均值127.5、标准差128.0进行归一化与训练配置 base_2.5g.py 中的img_norm_cfg一致并swapRBTrue将 BGR 转为 RGB解码distance2bbox将每个 anchor 中心到四条边的距离预测解码为检测框distance2kps将距离预测解码为关键点坐标见 scrfd.py多尺度候选_detect_candidates会对图像做保持宽高比的 resize 与 paddingletterbox再按det_scale把坐标还原回原图见 scrfd.py多尺度融合默认推理尺寸为[(128, 128), (640, 640)]DEFAULT_DET_SIZES最终将各尺度候选框合并后统一做 NMS见 scrfd.py 与 scrfd.py返回结构detect最终返回bboxes (N,5)与kpss (N,5,2)并支持max_num与metric参数控制最多返回的检测目标数及其排序依据见 scrfd.py。4. 与训练配置的对应人体检测模型与 SCRFD 训练配置 保持一致的超参设定可作为调参依据训练/测试输入尺寸均为(640, 640)base_2.5g.py 与 base_2.5g.pyFPN 步长[8, 16, 32]anchor 比例为[1.0]、尺度为[1, 2]base_2.5g.py推理时的 NMS 阈值对应配置中的iou_threshold0.45base_2.5g.py而示例代码将nms_thresh调整为 0.5 以获得更宽松的合并行为若要自行把 PyTorch 训练权重转换为可部署的 ONNX 模型可参考 scrfd2onnx.py转换后默认支持动态输入也可通过--shape 640 640固定输入尺寸以配合 onnx-simplifier 优化。六、扩展把示例用到自己的数据上在 scrfd_person.py 基础上做最小改造即可适配任意输入源更换图片目录把glob.glob(data/images/*.jpg)替换为你自己的图片路径模式接入摄像头/视频流将cv2.imread替换为cv2.VideoCapture逐帧读取并保持detect_person调用不变调整检测敏感度降低det_thresh例如 0.3可召回更多低置信度的遮挡目标代价是误检增加提高nms_thresh可保留更多相互重叠的检测框约束输出数量调用detector.detect(img, max_num10)只保留排序靠前的目标排序依据由metric控制default兼顾面积与居中程度max只看面积。七、小结InsightFace 的人体检测示例是一个以最小代码量复用 SOTA 检测器的范本通过pip install insightface 两行模型加载代码即可获得基于 SCRFD 的全身检测与可见区域估计能力。其技术要点可总结为模型scrfd_person_2.5g.onnx轻量级 SCRFD 变体支持 5 关键点输出自动下载无需手工准备单次前向双输出全身框来自 bbox 头可见区域由关键点 0/4 推导而来无需二次推理可视化约定绿色矩形为全身框、蓝色半透明蒙版为可见区域底层管线ONNX Runtime 推理 FPN 多尺度 anchor 解码 NMS 后处理全部封装在 SCRFD 类中可平滑迁移到视频流、多尺度检测等场景。该示例完整代码与模型加载逻辑均可在仓库中直接查阅示例脚本、SCRFD 推理实现、SCRFD 训练与评估文档。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考