YOLOv8 Face Detection 人脸检测与特征框提取节点

使用 Hugging Face 视觉模型前需配置前置环境

请参阅 Hugging Face 集成配置指南，根据指引完成账号配置并在本地环境绑定 Access Token，以确保节点能够在首次运行时顺利下载模型权重。

节点核心功能 (What is it?)

YOLOv8 Face Detection 是一个专用于高精度识别人脸的计算机视觉节点。它基于 🤗 Hugging Face 生态中广受赞誉的单阶段目标检测网络 YOLOv8（You Only Look Once version 8）深度学习架构，并采用专为人脸定位任务精细微调的 arnabdhar/YOLOv8-Face-Detection 权重，能够在毫秒级延迟内精准推导出图像中所有人脸的像素级包围盒坐标（Bounding Box Coordinates）与置信度得分（Confidence Scores）。

典型适用场景 (When would I use it?)

在以下情况下使用该节点：

在人脸识别、身份核验管线中定位并截取面部区域；
配合 CropImage 节点从合影或日常照片中自动批量裁剪头像（Avatar）；
统计和核验监控镜头或聚会照片中的实际人数；
自动化媒体审查与隐私保护（如配合局部高斯模糊实现人脸马赛克脱敏）；
依据人脸在画面的物理坐标动态构图（如自动居中特写）；
构建智能相册的人像自动归类与检索流程。

使用指南 (How to use it)

基础配置流程 (Basic Setup)

添加节点：在工作流画布中添加 "YOLOv8 Face Detection" 节点（首次运行将自动拉取约 6MB 的轻量模型权重）。
连接输入：将源图像（ImageArtifact 或 ImageUrlArtifact）接入 input_image 插槽。
配置参数：
- 设定置信度阈值 confidence_threshold（0.0–1.0），滤除低分误检；
- 设定选区外扩系数 dilation（0–100%），以便在人脸外围包含头发与下巴等边缘上下文。
运行检测：运行节点，即可在 detected_faces 输出引脚处提取所有检测到的人脸坐标列表。

参数输入插槽 (Parameters)

输入插槽 (Input Parameters)

input_image（必填，ImageArtifact 或 ImageUrlArtifact）：待执行人脸检测与分析的源图像。
confidence_threshold（浮点数，0.0–1.0，默认 0.5）：检测置信度截断阈值：
- 调高数值（如 0.8+）：仅保留高把握的目标，误检率极低，适合严肃安防；
- 调低数值（如 0.3）：召回率极高，可识别侧脸、模糊或远距离微小面孔，但可能引入少量假阳性误报。
dilation（浮点数，0.0–100.0，默认 0.0）：包围盒中心向外膨胀百分比：
- 设定 10.0 代表以包围盒几何中心为锚点，向四周等比外扩 10% 物理尺寸，确保完整囊括发际线与耳廓。

输出引脚 (Output Parameters)

detected_faces（列表 list）：检测到的所有人脸目标结构体集合，每个元素包含：
- x：包围盒左上角的水平物理像素绝对坐标；
- y：包围盒左上角的垂直物理像素绝对坐标；
- width：包围盒的物理像素宽度；
- height：包围盒的物理像素高度；
- confidence：该目标的模型预测置信度得分（0.0–1.0）。
logs（字符串）：详细的运行时诊断日志（模型加载时间、显卡利用率、识别到的人脸总数等）。

输出数据规范示例 (Output Format)

每个被检测到的面部以结构化标准字典表达：

{
  "x": 150,
  "y": 200,
  "width": 300,
  "height": 350,
  "confidence": 0.95
}

坐标系原点 $(0, 0)$ 严格锚定在输入图像的左上角。

典型工作流示例 (Example Workflows)

智能人像头像批量裁切流水线

使用 LoadImage 导入一张全身合照。
将其接入 YOLOv8 Face Detection 节点。
将 dilation 设为 15.0，为面部四周留出自然的发型与肩膀轮廓。
将 detected_faces 列表中的首个目标传入 CropImage 节点的坐标插槽。
瞬间从大图中裁切出一张端正的标准个人头像。

高精度严格核验流

将 confidence_threshold 调高至 0.85。
彻底过滤掉背景阴影与复杂纹理导致的潜在误报，确保后续识别 100% 作用于真人面部。

关键技术特性 (Advanced Features)

权重本地持久化：首次自动下载的模型会被安全缓存至本地磁盘，后续调用毫秒级瞬时启动。
中心膨胀防溢出边界夹紧 (Boundary Clamping)：开启 dilation 外扩包围盒时，算法会自动将其硬限制在图像画布边缘内，绝不产生越界负坐标或溢出错误。
超轻量显存开销：模型仅约 6MB，推理时仅占约 50MB 主机内存，在入门级硬件上即可达成亚毫秒级的实时推理帧率。

常见问题与排查 (Common Issues)

缺少 Hugging Face Token：确保已在系统环境变量中注入 HF_TOKEN。
未检测到人脸：若人物面部被大面积口罩遮挡、逆光严重或距离极远，可尝试将 confidence_threshold 降至 0.3。
包围盒贴得太死：调整 dilation（建议设为 10–20%）为面部添加舒适的构图外扩缓冲。