얼굴 인식을자체 네트워크에 배포하세요.
하나의 Linux 컨테이너로 완전한 얼굴 인식 백엔드를 구축하세요. Web UI, REST API, Python SDK를 통해 검출, 비교, 등록, 정확한 1:N 검색, RTSP/RTSPS 카메라 모니터링을 제공합니다.
모델 도입 경로 선택
통합을 다시 구축하지 않고 평가에서 프로덕션까지.
모델 권리와 인식 요구 사항이 달라져도 동일한 셀프 호스팅 Server를 계속 사용하세요.
승인된 모델로 프로덕션까지
Server와 Python SDK 코드는 MIT License입니다. 프로덕션에서는 공개 모델 라이선스를 받거나 백만·천만 단위 1:N 갤러리용 고정확도 프라이빗 모델을 평가할 수 있으며, 기존 Server 통합은 그대로 유지됩니다.
사용 허가 신청하나의 셀프 호스팅 서비스
아키텍처로 보호하는 프라이버시, 실용성을 위한 설계.
이미지, embedding, 모델, 인덱스를 직접 관리하는 인프라 안에 유지할 수 있습니다. 다국어 콘솔은 애플리케이션과 동일한 공개 API를 호출하며 CDN, analytics, 원격 font 또는 타사 JavaScript를 사용하지 않습니다.
검출
JPEG, PNG, WebP 이미지에서 bounding box, 5점 landmark, 검출 confidence, 로컬 품질 신호를 반환합니다.
비교
두 이미지에서 선택한 얼굴을 명시적 임계값과 확률이 아닌 원본 cosine similarity로 비교합니다.
등록
Collection, Person, FaceSample로 identity를 구성하고 다중 이미지 등록, 검토 모드, 명확한 거절 사유를 사용합니다.
검색
전체를 스캔하는 정확한 1:N Person 검색을 실행합니다. 각 Person은 Collection 임계값을 넘는 가장 강한 FaceSample 일치로 순위가 정해집니다.
모니터링
영구 RTSP 인식 작업을 실행하고 최근 입장, 퇴장, 오류, 복구 이벤트와 선택적 운영자 미리보기를 확인합니다.
통합
Web UI, 29개 REST operation, 대화형 OpenAPI reference 또는 가벼운 타입 지정 Python client를 사용합니다.
빠른 시작
저장소에서 첫 정확 검색까지.
CPU 또는 CUDA를 선택하고 모델 패키지를 설치한 뒤 준비 상태를 확인하세요. 그런 다음 Python SDK로 Collection을 만들고 한 사람을 등록하여 검색합니다.
git clone https://github.com/deepinsight/insightface.git
cd insightface
mkdir -p server/.models
export INSIGHTFACE_MODELS_UID="$(id -u)"
export INSIGHTFACE_MODELS_GID="$(id -g)"
docker compose -f server/deploy/compose.cpu.yml pull
docker compose -f server/deploy/compose.cpu.yml \
run --rm models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cpu.yml \
run --rm models verify buffalo_l
docker compose -f server/deploy/compose.cpu.yml \
up -d --wait --wait-timeout 180
curl -fsS http://127.0.0.1:18097/v1/health복제 및 설치
InsightFace를 checkout하고 Server 이미지와 별도로 모델 패키지를 설치합니다.
하나의 실행 환경 시작
평가에는 CPU 스택을, GPU 검색과 추론에는 CUDA 12를 사용합니다.
준비 상태 확인
/v1/health를 확인한 후 데이터베이스, 모델, 실행 Provider가 준비되었는지 확인합니다.
첫 검색 실행
Collection을 만들고 한 사람을 등록한 후 Python을 통해 다른 이미지로 검색합니다.
CPU
Docker Engine과 Docker Compose가 설치된 Linux x86_64. 평가와 중간 규모 워크로드에 실용적인 경로입니다.
NVIDIA CUDA 12
지원되는 NVIDIA GPU, driver, NVIDIA Container Toolkit을 추가합니다. 조용히 CPU로 fallback하지 않고 시작에 실패합니다.
배포 경계
인식 파이프라인
이미지에서 순위가 지정된 일치 결과까지.
콘솔, REST API, Python SDK, RTSP Monitor는 모두 동일한 명시적 처리 계약을 따릅니다.
이미지 또는 RTSP frame
JPEG, PNG, WebP 또는 라이브 카메라의 최신 frame.
다중 해상도 SCRFD
얼굴을 검출하고 후보를 병합한 뒤 한 번의 global NMS를 적용합니다.
정렬 및 embedding
5점 정렬, ArcFace embedding, L2 normalization.
모델에 고정된 Collection
모델, 전처리, detector, 임계값, 용량을 고정합니다.
정확한 CPU/GPU 검색
선택한 profile의 모든 유효 FaceSample을 빠짐없이 채점합니다.
Person 일치 결과
원본 cosine score와 request ID가 포함된 순위별 Person을 반환합니다.
SQLite가 영구 원본
영구 database가 원본이며 메모리 정확 인덱스는 재구축 가능한 projection입니다. 승인된 등록은 성공 응답 전에 인덱스에 추가되고, 삭제는 두 저장소 모두에서 제거됩니다.
명시적 identity 계약
Collection으로 모델, 정책, 데이터 경계를 명확하게 유지합니다.
각 Collection은 모델 identity, 전처리 버전, embedding 차원, detector 정책, 검색 profile, 용량, 일치 임계값을 고정합니다. 이 계약은 모델이나 runtime이 바뀔 때 조용히 데이터가 섞이는 일을 방지합니다.
- Person마다 여러 FaceSample을 추가하고 전체 batch를 잃지 않으면서 부분 등록 결과를 검토합니다.
- off, standard, strict 검토를 선택하여 얼굴 수, 크기, 선명도, 밝기, pose, 동일 Person 내 일관성을 확인합니다.
- Collection embedding contract를 통해 신뢰할 수 있는 상위 embedding 파이프라인을 연결합니다. 이미지에는 계속 검출과 검토가 적용됩니다.
- 승인된 얼굴마다 112×112 bounding-box crop을 선택적으로 저장합니다. 원본 업로드와 인식용 정렬 입력은 보관하지 않습니다.
실측 검색 성능
단일 GPU 규모의 정확한 검색.
네이티브 전체 검색 profile을 사용하면 근사 최근접 이웃 인덱스로 바꾸지 않고 벡터 정밀도, 용량, 처리량을 조절할 수 있습니다.
RTX 5090 한 장에서 측정한 512차원 벡터 최대값.
정확히 10M 벡터, 동시 query 1개에서 측정.
10M 벡터에서 측정한 전체 Top-5 검색 처리량.
동일 GPU에서 측정한 INT8 Top-5 처리량 배수.
| GPU 데이터 유형 | 최대 벡터 수 | 10M Top-5 p50 | 10M 직렬 QPS |
|---|---|---|---|
| FP32 | 15.8M | 12.84 ms | 77.85 |
| FP16 | 30.7M | 6.83 ms | 146.32 |
| BF16 | 30.7M | 6.83 ms | 146.33 |
| INT8 | 58.9M | 3.84 ms | 260.81 |
INT8 특징 양자화
공개된 MR-ALL 벤치마크에서 실질적인 정확도 손실이 관찰되지 않았습니다.
NVIDIA GeForce RTX 5090 한 장에서 측정했습니다. 용량은 ONNX 모델과 Server 부하를 제외한 독립 네이티브 인덱스의 한계입니다. 속도는 정확히 10M개의 512차원 이미지 벡터, GPU 상주 전체 Top-5, 동시 query 1개, warm-up 10회, 측정 query 100회 조건입니다. 운영 배포에서는 모델, request, 동시성, 인덱스 재구축, allocator를 위한 VRAM 여유가 필요합니다. 검색은 각 저장 표현 내에서는 정확하지만 저정밀 저장은 FP32 대비 score와 순위를 바꿀 수 있습니다.
프라이빗 모델
대규모 갤러리에는 빠른 인덱스만으로 충분하지 않습니다.
인덱스 용량은 검색 규모를 해결하지만, 엄격한 운영 기준에서의 인식 품질이 대규모 1:N 갤러리의 실용성을 결정합니다. 요건을 충족하는 팀은 라이선스 계약 전에 프라이빗 모델과 공개 모델 기준 성능을 비교할 수 있습니다.
대표성 있고 합법적으로 확보한 검증 데이터를 사용하세요. 평가 제공 여부와 범위는 요건을 충족하는 팀과 협의하여 확정합니다.
더 높은 인식 품질
대표성 있는 데이터로 까다로운 이미지 조건과 엄격한 오인식 목표를 평가합니다.
동일한 Server와 API
REST 또는 Python 통합을 다시 구축하지 않고 승인된 모델 패키지로 교체합니다.
서명된 오프라인 승인
프라이빗 패키지는 동일한 manifest와 서명된 오프라인 라이선스 형식을 사용할 수 있습니다.
상업용 배포 권리
승인된 제품, 환경, 프로덕션 사용 사례에 맞춰 모델 권리를 정합니다.
영구 RTSP Monitor
브라우저 없이 계속 실행되는 카메라 모니터링.
RTSP 또는 RTSPS 소스용 서버 측 Monitor를 만들고 추론 주기와 이벤트 확인을 조정한 뒤 독립적인 client가 현재 상태와 최근 이벤트를 poll하도록 합니다. 콘솔을 닫아도 인식은 중지되지 않고 활성화된 Monitor는 Server 재시작 후 복원됩니다. Frame은 녹화되지 않으며 최근 이벤트는 용량이 제한되고 비영구적이고, 미리보기는 기본적으로 꺼져 있습니다.
인식을 운영자 보조 수단으로 사용하고 영향이 큰 결정의 유일한 통제로 사용하지 마세요. 각 배포에 대한 동의, 보존, 삭제, 검토, 보안 사고 대응 정책을 정의하세요.
운영 및 보안
강화하기 쉬운 명확한 경계.
Server는 프라이빗 배포 운영에 필요한 상태를 제공하면서 secret, 이미지, embedding, 자격증명을 진단 정보에서 제외합니다.
InsightFace Server 기본 제공
준비 상태 및 진단
서비스, database, 모델, provider, 용량, 최근의 안전한 오류 요약을 확인합니다.
CUDA 오류 조기 감지
시작 시 실제 provider, session, library, GPU 호환성, warm-up 추론을 검증합니다.
영구 데이터 경계
모델을 읽기 전용으로 유지하고 /data를 영구 저장하며 SQLite에서 폐기 가능한 정확 인덱스를 재구축합니다.
보호된 자격증명
API Key를 hash하고 /data의 RTSP 자격증명을 암호화하며 응답에서 source를 마스킹합니다.
API 전용 모드
콘솔과 가이드를 비활성화하면서 프라이빗 서비스용 /v1 및 /openapi.json을 유지합니다.
프로덕션 경계 완성
제공되는 Compose 파일은 격리 환경의 평가를 위해 설계되었습니다. 프로덕션 서비스를 외부에 공개하기 전에 네트워크와 거버넌스 모델에 필요한 제어 항목을 추가하세요.
구현 가이드
첫 컨테이너에서 실제 통합까지.
첫 프라이빗 배포에는 핵심에 집중한 빠른 시작을 사용하고, 애플리케이션을 연결할 준비가 되면 API 및 Python SDK 워크플로로 이동하세요.
자주 묻는 질문
배포와 모델 라이선스를 계획하세요.
평가와 프로덕션을 시작하기 전에 팀이 알아야 할 실무 답변입니다.
InsightFace Server는 무료로 사용할 수 있나요?+
Server 소스 코드와 Python SDK는 MIT License입니다. 모델 파일에는 별도 조건이 적용되므로 코드 사용 권한이 모델의 상업적 사용 권리를 부여하지는 않습니다.
인식 모델이 컨테이너에 포함되어 있나요?+
아닙니다. 모델 패키지는 별도로 설치하고 검증하여 모델 ID, 버전, 승인 상태를 명확하게 유지합니다.
InsightFace 공개 사전 학습 모델을 상업적으로 사용할 수 있나요?+
공개 사전 학습 모델 패키지는 InsightFace의 별도 상업용 허가를 받지 않는 한 일반적으로 비상업적 학술 연구 용도로 제한됩니다.
프라이빗 또는 상업용 라이선스 모델에 새로운 통합이 필요한가요?+
아닙니다. 승인된 모델 패키지는 동일한 Server, Web UI, REST API, Python SDK, manifest, 설치 절차를 사용합니다.
InsightFace Server를 오프라인으로 실행할 수 있나요?+
가능합니다. 컨테이너 이미지와 모델 패키지를 설치한 후에는 자체 인프라 안에서 Server의 정상 시작과 운영을 오프라인으로 유지할 수 있습니다.
58.9M 용량은 무엇을 의미하나요?+
RTX 5090 한 장에서 측정한 512차원 INT8 이미지 벡터의 네이티브 인덱스 한계입니다. 사람 수나 API의 End-to-End 용량을 의미하지 않습니다.
1:N 검색은 정확 검색인가요, 근사 검색인가요?+
선택한 저장 표현 안에서 전체를 탐색하는 정확한 Flat 검색이며 근사 최근접 이웃 인덱스를 사용하지 않습니다.
어떤 배포 하드웨어를 지원하나요?+
제공되는 배포 환경은 Linux x86_64를 대상으로 하며 로컬 CPU 추론 또는 CUDA 12 스택을 통한 지원 NVIDIA GPU를 사용할 수 있습니다.
워크플로를 검증한 뒤 적합한 모델을 선택하세요.
로컬에서 첫 정확 검색을 실행하세요. 프로덕션 준비가 되면 통합을 다시 구축하지 않고 공개 모델 사용 허가를 받거나 고정확도 프라이빗 모델을 평가할 수 있습니다.
Server와 SDK 코드는 MIT License입니다. 프로덕션 모델 권리는 별도로 라이선스가 필요합니다.