yakhyo/uniface

UniFace – 얼굴 관련 AI 작업을 위한 통합 Python 라이브러리

개요 – UniFace는 인간의 얼굴에 대해 수행하고자 하는 모든 작업: 탐지, 랜드마크, 3D 메쉬, 파싱/세그멘테이션, 포트레이트 매팅, 시선 및 머리 자세 추정, 인구 통계적 속성(나이, 성별, 인종), 감정, 라이브니스 스푸핑 탐지, 품질 점수, 인식(임베딩), 익명화, 그리고 빠른 유사도 검색을 위한 FAISS 기반 벡터 스토어까지, 최첨단 딥러닝 모델 컬렉션을 하나로 묶었습니다. 모든 모델은 단일하고 일관된 Python API 뒤에 래핑되어 있습니다.

중요성 – 수십 개의 개별 저장소를 하나씩 조합하는 대신, 하나의 패키지(pip install "uniface[cpu]" 또는 "uniface[gpu]")를 설치하여 CPU, Apple Silicon, 또는 NVIDIA CUDA에서 작동하는 프로덕션 레디의 경량 솔루션을 얻을 수 있습니다. 가중치는 처음 사용 시 자동으로 다운로드되며 SHA-256으로 검증되므로, 모델 파일을 직접 관리할 필요가 없습니다.

주요 구성 요소

작업	제공되는 모델
얼굴 탐지	RetinaFace, SCRFD, CenterFace, YOLOv5‑Face, YOLOv8‑Face, BlazeFace
인식	AdaFace, ArcFace, EdgeFace, MobileFace, SphereFace
추적	BYTETracker (지속적 ID)
랜드마크	2d106det (106 pts), PIPNet (98/68), Face‑Mesh (468/478 3D)
파싱 / 세그멘테이션	BiSeNet (19 classes), XSeg
포트레이트 매팅	MODNet (trimap‑free)
시선	MobileGaze (ResNet‑18/34/50, MobileNetV2)
머리 자세	6D 회전 → pitch/yaw/roll
인구 통계	AgeGender, FairFace (나이 그룹, 성별, 인종)
감정	AffectNet‑7 / AffectNet‑8
얼굴 상태	FaceAttribNet (눈, 안경, 마스크, 등)
품질	eDifFIQA (tiny/small/medium/large)
안티 스푸핑	MiniFASNet
익명화	5가지 블러 기반 방법
벡터 스토어	FAISS 기반 임베딩 검색

일반적인 사용법 – 상위 수준의 FaceAnalyzer는 탐지, 정렬 및 (선택적으로) 전달된 모든 속성 예측기를 실행합니다:

import cv2
from uniface import FaceAnalyzer, FairFace

analyzer = FaceAnalyzer(predictors=[FairFace()])
for face in analyzer.analyze(cv2.imread('photo.jpg')):
    print(face.bbox, face.sex, face.age_group, face.embedding.shape)

bbox, confidence, landmarks 및 embedding은 항상 채워집니다; 다른 필드는 해당 예측기를 추가하기 전까지는 None으로 유지됩니다.

설치

# CPU 또는 Apple Silicon
pip install "uniface[cpu]"
# NVIDIA GPU (CUDA)
npip install "uniface[gpu]"
# 최신 프리릴리스 버전
pip install --pre "uniface[cpu]"

패키지는 PyPI에서 시맨틱 버저닝을 따르며, CPU 대 GPU 의존성 패키지를 위한 별도의 extras를 제공합니다.

문서 및 커뮤니티 – 전체 문서, 빠른 시작 가이드, 모델 주, Jupyter 노트북은 https://yakhyo.github.io/uniface/에서 호스팅됩니다. 지원 및 기여를 위해 Discord 서버와 GitHub issue tracker가 제공됩니다.

라이선스 – 코드는 MIT 라이선스입니다. 일부 사전 학습된 가중치는 자체 라이선스를 가지므로, 상업적 배포 전 Model licences 페이지를 확인하십시오.

---

UniFace는 Rocket Software의 상업용 제품 Uniface와 관련이 없습니다.