图像人脸占比
更新时间：2026-09-14
简介
图像人脸占比算子，用 Haar 级联检测器检出图像中的人脸，输出最大人脸面积 / 图像面积。算子只产出占比字段，过滤交给 pipeline。
功能描述
- 检测器与
图像人脸数量（ImageFaceCount）共用一套代码：cv2.CascadeClassifier+ OpenCV 自带的haarcascade_frontalface_alt.xml，随 opencv 包安装，不需要纳管权重 - 只取最大一张脸的面积，不是所有脸面积之和；多脸图上小脸不影响结果
- 无人脸时返回 0.0，而不是 None
- 图像面积由 PIL 的
image.width * image.height得到，取值范围 [0, 1] - 纯 CPU，
scale_factor/min_neighbors/min_size/max_size直接透传detectMultiScale，None 的可选项不传 - 面积按
detectMultiScale返回的原始框计算，不额外把框裁剪到图像边界内。Haar 的检测窗口来自图内滑窗，正常图上该裁剪本就是空操作 - 级联 xml 加载失败在初始化阶段抛 FileNotFoundError；单行失败打 exception 日志后该行填 None，不中断整批
算子参数
输入
| 输入 | 含义 |
|---|---|
| images | 图像输入列，内容形式由 image_src_type 决定（路径/URL 字符串、base64 字符串、bytes） |
输出
| 输出 | 含义 |
|---|---|
| face_ratio | float64，最大人脸面积 / 图像面积，取值 [0, 1]；无人脸为 0.0，该行处理失败时为 None |
参数
| 参数名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| image_src_type | str | "image_url" | 输入图像编码形式：image_url / image_base64 / image_binary |
| cv_classifier | str | "" | Haar 级联 xml 路径，空字符串用 OpenCV 自带的 haarcascade_frontalface_alt.xml |
| scale_factor | float | 1.1 | detectMultiScale 的 scaleFactor |
| min_neighbors | int | 3 | detectMultiScale 的 minNeighbors |
| min_size | tuple[int,int] 或 None | None | 最小人脸尺寸，None 表示不限制（不传 minSize） |
| max_size | tuple[int,int] 或 None | None | 最大人脸尺寸，None 表示不限制（不传 maxSize） |
注意事项
- 算子只产出统计字段，不做过滤。常用的保留区间是
face_ratio落在0.0 ~ 0.4（滤掉大头特写），条件要自己在 pipeline 里写。 - 0.0 有两种含义：确实没检出脸，或者脸太小/太侧被 Haar 漏掉。要区分「无脸」与「漏检」得配合
图像人脸数量或更强的检测器。 - Haar 正脸级联对纹理密集区域（布面印花、卡通图案）会误检，误检框往往不小，会把
face_ratio抬高。要更准的人脸框用存量的daft.aihc.functions.image.image_face_detect.ImageFaceDetect（insightface，可用 GPU）。
调用示例
Python
1from __future__ import annotations
2
3import os
4
5import daft
6from daft import col
7
8from daft.aihc.common.udf import aihc_udf
9from daft.aihc.functions.image.image_face_ratio import ImageFaceRatio
10
11if __name__ == "__main__":
12 if os.getenv("DAFT_RUNNER", "native") == "ray":
13 import ray
14 ray.init(dashboard_host="0.0.0.0", ignore_reinit_error=True)
15 daft.set_runner_ray()
16 daft.set_execution_config(actor_udf_ready_timeout=6000, min_cpu_per_task=0)
17
18samples = {"image": ["bos://your-bucket/sample.jpg"]}
19 ds = daft.from_pydict(samples)
20 ds = ds.with_column(
21 "face_ratio",
22 aihc_udf(
23 ImageFaceRatio,
24 construct_args={
25 "image_src_type": "image_url",
26 "scale_factor": 1.1,
27 "min_neighbors": 3,
28 },
29 num_cpus=1,
30 concurrency=4,
31 batch_size=32,
32 )(col("image")),
33 )
34 ds = ds.where(col("face_ratio") <= 0.4)
35 ds.show()评价此篇文章