FaceHub 是一个实时人脸识别 Python 库，提供无 GUI、可独立使用的检测、 特征提取、识别、追踪、摄像头采集能力 —— 并能按人脸整理整个照片集。
特性¶
检测
insightface RetinaFace，自动检测 CUDA / DirectML GPU 并回退 CPU。
特征
ArcFace 512 维 L2 归一化特征向量，可直接用于余弦相似度匹配。
识别
1:N 余弦相似度匹配，带版本号编码缓存，人脸库变更时才重建。
追踪
IoU 多目标追踪 + 多数投票身份平滑。
照片分类
按人脸对照片集自动分组 —— 人脸库匹配或全自动聚类，支持导出为按人分类的文件夹。
可扩展
DetectorProtocol 协议，可接入自定义检测器（YOLO、MediaPipe……）。
60 秒快速开始¶
from face_hub import classify_photos, export_to_folders
# 把一个文件夹的照片按人物自动分组
result = classify_photos(["聚会1.jpg", "聚会2.jpg", "聚会3.jpg"])
for label, group in result.groups.items():
print(label, "→", group.photo_ids)
# person_001 → ['聚会1.jpg', '聚会3.jpg']
# person_002 → ['聚会2.jpg']
# 导出为按人分类的文件夹
export_to_folders(result, "sorted/")
平台支持¶
| 平台 | 检测后端 | 说明 |
|---|---|---|
| Windows | DirectML / CUDA / CPU | 自动探测，优先 GPU |
| Linux | CUDA / CPU | 自动探测，优先 GPU |
| macOS | CPU | 仅 CPU，CoreML 计划中 |