UniFace开发者指南如何扩展自定义ONNX人脸模型继承BaseDetector实战【免费下载链接】unifaceUniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.项目地址: https://gitcode.com/gh_mirrors/un/unifaceUniFace 是一个统一的人脸分析 Python 库支持人脸检测、关键点、识别、属性分析等能力。本文讲解如何继承 BaseDetector 扩展自定义 ONNX 人脸检测模型只需实现三个方法你的模型就能接入 UniFace 的完整分析流水线。为什么需要扩展自定义ONNX人脸模型UniFace 内置了 6 种检测模型SCRFD、YOLOv8-Face、RetinaFace、BlazeFace 等但你的业务场景可能有特殊需求特定领域模型医学影像、监控、车牌场景等专用检测器⚡自研轻量化模型针对边缘设备优化的更小模型替换或对比模型将新架构与内置模型做效果对比好消息是UniFace 的扩展点设计得非常干净所有检测器共享同一个抽象基类BaseDetector你不需要理解整个库只需实现三个方法。快速开始克隆仓库并准备环境git clone https://gitcode.com/gh_mirrors/un/uniface cd uniface pip install -e .[cpu] # CPU 环境Apple Silicon 自动走 CoreML # 或 pip install -e .[gpu] # NVIDIA GPUCUDABaseDetector 抽象接口必须实现什么打开 uniface/detection/base.py接口只有三个抽象方法见抽象方法定义方法职责输入输出preprocess图像预处理BGR 的np.ndarray (H,W,C)归一化后的输入张量postprocess解码模型原始输出模型输出数组边界框、置信度、关键点detect串联完整推理流程BGR 图像list[Face]返回值统一使用 Face 数据类包含bbox[x1, y1, x2, y2]、confidence、landmarks三个必填字段。两个重要的类属性supports_landmarks / supports_alignment这是新手最容易踩坑的地方见属性说明supports_landmarks False # 你的模型是否输出人脸关键点 supports_alignment False # 关键点是否为5点对齐模板supports_landmarks True表示detect会填充Face.landmarkssupports_alignment True表示你的关键点恰好是 5 点对齐模板左眼、右眼、鼻尖、左嘴角、右嘴角如果只输出边界框两个标志都保持False即可FaceAnalyzer会自动跳过依赖关键点的模块若错误地设为True识别、质量评分等下游模块会产出错误结果。实战编写一个自定义检测器以下是完整可运行的骨架参考 docs/recipes/custom-models.mdimport numpy as np from uniface.detection.base import BaseDetector from uniface.onnx_utils import create_onnx_session from uniface.types import Face class MyDetector(BaseDetector): 自定义 ONNX 人脸检测器 supports_landmarks False # 只输出框 supports_alignment False def __init__(self, model_path: str, confidence_threshold: float 0.5): super().__init__(confidence_thresholdconfidence_threshold) # 自动探测硬件加速CoreML CUDA CPU self.session create_onnx_session(model_path) self.threshold confidence_threshold def preprocess(self, image: np.ndarray) - np.ndarray: # 你的预处理缩放到模型输入尺寸、BGR→RGB、归一化 blob image.astype(np.float32) / 255.0 return blob[None].transpose(0, 3, 1, 2) def postprocess(self, outputs, **kwargs) - list[Face]: boxes, scores outputs faces [] for box, score in zip(boxes, scores): if score self.threshold: continue faces.append(Face(bboxbox, confidencefloat(score), landmarksnp.zeros((5, 2), dtypenp.float32))) return faces def detect(self, image: np.ndarray, **kwargs) - list[Face]: tensor self.preprocess(image) outputs self.session.run(None, {input: tensor}) return self.postprocess(outputs)使用方式和内置检测器完全一致detector MyDetector(my_face_model.onnx) faces detector.detect(image) # 或 detector(image) print(len(faces), faces[0].bbox)三个实用技巧硬件加速零配置create_onnx_session会自动选择最优执行提供者Mac 上走 CoreML、N 卡走 CUDA无需手动指定见 onnx_utils.py。复用工具方法基类提供了 _select_top_detections 用于按面积/中心距离筛选人脸_detections_to_faces 用于将检测结果数组批量转成Face对象。参考内置实现BlazeFace 是一个非常完整的范本包含 letterbox 缩放、加权 NMS、anchor 解码等细节扩展自己的模型前建议先通读一遍。验证你的自定义检测器写完之后用三步快速自检接口自检detector.get_info()应返回你的类名、两个标志和配置字典单图测试加载一张测试图确认返回的每个Face的bbox落在图像范围内、confidence在 (0, 1)流水线集成传入FaceAnalyzer确认整体流程无异常from uniface import FaceAnalyzer analyzer FaceAnalyzer(detectorMyDetector(my_face_model.onnx)) faces analyzer.analyze(image) 注意FaceAnalyzer会读取supports_alignment若你的检测器不支持对齐识别模块会被自动禁用并给出警告——这是预期行为不是 bug。更多扩展方向除了检测器UniFace 还提供其他扩展点自定义识别模型继承BaseRecognizer见 recognition/base.py自定义属性预测器继承BaseAttribute通过FaceAnalyzer(predictors[...])逐脸运行更多模式示例docs/recipes/custom-models.md参考资料自定义模型官方文档 — 三种扩展点完整示例检测模块文档 — 内置模型性能对比与 landmarks 约定BaseDetector 源码 — 抽象接口与工具方法Face 数据类 — 统一结果类型定义按这套模式扩展后你的自定义 ONNX 模型就和内置模型享受完全相同的 API 体验——这正是 UniFace 一套接口、任意模型 设计哲学的核心。【免费下载链接】unifaceUniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.项目地址: https://gitcode.com/gh_mirrors/un/uniface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考