tomas-gajarsky/facetorch

해결하는 문제

얼굴 분석 파이프라인을 구축하는 것은 종종 모델 소스 코드, 종속성, 재현성 문제로 어려움을 겪게 합니다. Facetorch는 오픈소스 얼굴 분석 모델을 엄선하여 휴대 가능한 torch.export 형식(.pt2)으로 패키징하고 통합된 Python 툴킷을 제공함으로써 추론 시 모델 소스 코드 없이도 감지 및 분석을 실행할 수 있게 합니다.

작동 방식

Facetorch는 여러 플러그형 구성 요소를 조정하는 FaceAnalyzer 클래스를 중심으로 합니다. 로컬 경로, 텐서, NumPy 배열, PIL 이미지 또는 바이트에서 이미지를 처리하는 리더, 얼굴을 찾는 감지기(신경망 래퍼), 얼굴 크기와 픽셀 범위를 정규화하는 유니파이어, 일련의 예측기(임베딩, 검증, 표정 등 작업을 위한 신경망 래퍼), 그리고 유틸라이저(예: 경계 상자 그리기)가 포함됩니다. 구성은 Hydra/OmegaConf를 통해 관리되며 CPU 또는 GPU 프로필을 선택하고 설정을 재정의할 수 있습니다. 모델은 torch.export로 직렬화되므로 추론에 원본 코드가 필요하지 않습니다. 라이브러리의 기본 동작은 결정적입니다. 기본적으로 입력을 강제 변환하고 명시적으로 제한된 URLReader를 구성한 경우에만 원격 이미지를 가져옵니다. 모델은 첫 사용 시 지연 로드되고 캐시되며, 라이브러리는 단일 이미지 내에서 감지된 얼굴에 대한 동적 배치를 지원합니다.

대상 사용자

Python에서 유연하고 재현 가능한 방식으로 얼굴 감지 및 분석(예: 신원 확인, 표정 읽기)을 실행해야 하는 개발자와 연구자, 특히 모델 내부를 직접 관리하지 않으려는 사람들을 위한 것입니다. Python 3.11–3.12 및 PyTorch 2.6–2.13이 필요하며 공식 플랫폼은 Linux x86-64입니다(Windows/macOS/ARM은 실험적).

주요 특징

• .pt2 형식의 휴대용 모델—추론 시 모델 소스 코드 불필요; 동적 배치 및 torch.compile 지원
• 관리되는 확장성: 사용자 정의 구성 요소는 불변 매니페스트, 출처, 모델 권리 검토를 포함한 검증을 통과해야 합니다
• 결정적 입력 파이프라인: 로컬 경로, 텐서, NumPy 배열, PIL 이미지 또는 바이트 허용; 원격 입력은 명시적이고 제한된 URLReader를 통해서만 가능
• uv, conda-lock 및 Docker를 통한 재현 가능한 환경; 캐시 디렉터리는 환경 변수로 제어 가능
• 감지기/예측기 모델의 지연 로드 및 캐시; 내장 예측기의 얼굴 배치 크기는 64로 제한