← 가이드로 돌아가기
InsightFace ServerDocker얼굴 인식CUDA셀프 호스팅

Docker로 InsightFace Server 배포

CPU 또는 CUDA에서 InsightFace Server를 셀프 호스팅하고 라이선스 모델 설치·검증, 첫 정확한 1:N 검색, 인증, 영구 데이터 보호까지 진행합니다.

•읽는 시간 10분
서비스, 모델, 데이터베이스와 runtime 상태를 보여 주는 InsightFace Server 대시보드
등록 전에 대시보드와 시스템에서 모든 구성 요소가 준비되었는지 확인합니다.

이 가이드에서 구축할 내용

InsightFace Server는 얼굴 검출, 비교, 등록, 정확한 1:N Person 검색, 다국어 Web UI, REST API, SQLite와 로컬 추론을 하나의 셀프 호스팅 서비스로 제공합니다. 이미지, embedding, 모델과 index를 조직의 인프라 안에 유지할 수 있습니다.

이 빠른 시작은 완전한 InsightFace checkout에서 모델을 설치하고 실제 검색에 성공할 때까지 안내합니다. 운영 전 필요한 모델 권한, 인증, HTTPS, 데이터 영속성, 안전한 종료와 CUDA fail-fast 진단도 다룹니다.

Server는 일반적인 얼굴 인식 흐름을 위한 개인정보 중심의 대안이지 AWS Rekognition 호환 제품이 아닙니다. AWS IAM, SigV4, Region 의미 체계, 내장 TLS, 사용자 계정이나 RBAC를 구현하지 않습니다.

시작하기 전에

  • Docker Engine과 Docker Compose가 설치된 Linux x86_64 호스트의 완전한 InsightFace repository checkout.
  • CUDA 12는 지원 NVIDIA GPU, NVIDIA Driver, NVIDIA Container Toolkit이 필요합니다. 호스트에 CUDA Toolkit, cuDNN, ONNX Runtime, Python, OpenCV를 설치할 필요는 없습니다.
  • 컨테이너를 pull하고 모델을 설치할 때의 네트워크 연결. 설치 이후 일반 Server 시작은 offline으로 유지할 수 있습니다.
  • 생체정보 처리 권한과 동의, 접근, 보존, 삭제, backup, 사고 대응에 관한 문서화된 정책.

1. CPU 또는 CUDA를 선택하고 모델 설치

완전한 InsightFace checkout 루트에서 명령을 실행하고 Compose stack 하나만 선택합니다. CPU는 가장 간단한 평가 경로로 18097 포트를 사용합니다. CUDA는 18098 포트를 사용하며 호환 Driver와 NVIDIA Container Toolkit이 필요하지만 호스트 CUDA나 cuDNN은 필요 없습니다.

아래 명령은 비대화형 --accept-license를 의도적으로 사용하고 buffalo_l을 즉시 검증합니다. 조직이 모델 조건을 검토하고 수락한 경우에만 실행하세요. 설치 도구는 buffalo_m, buffalo_sc, antelopev2도 지원합니다.

  • Turing, Ampere, Ada, Hopper는 Driver R535 이상, Blackwell과 RTX 50 시리즈는 570.26 이상이 필요합니다. 신규 배포는 안정적인 R580 이상을 권장합니다.
  • 공개 image에는 모델, 고객 데이터, API Key, 운영 설정이 포함되지 않습니다.
  • 한 배포에서 CPU와 CUDA Compose를 섞지 마세요. image, port, Provider, named data volume이 서로 다릅니다.
CPU: pull, 모델 license 수락, 설치와 검증
mkdir -p server/.models
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
CUDA 12: pull, 모델 license 수락, 설치와 검증
mkdir -p server/.models
docker compose -f server/deploy/compose.cuda12.yml pull
docker compose -f server/deploy/compose.cuda12.yml \
  run --rm models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cuda12.yml \
  run --rm models verify buffalo_l

2. 모델 라이선스 범위 이해

Server source code와 Python SDK는 MIT license이지만 모델 파일과 weight는 그 MIT license의 적용 대상이 아닙니다. buffalo_l을 포함한 공개 InsightFace 모델 package는 별도 상용 허가가 없으면 일반적으로 비상업 학술 연구용으로 제한되며, 셀프 호스팅이 상용 모델 권한을 부여하지 않습니다.

설치하면 manifest.json과 서명된 MODEL.LICENSE가 server/.models에 기록됩니다. verify는 package identity, 서명, 유효기간과 현재 권한을 확인합니다. 이 license는 모델과 허용 용도를 나타내는 compliance credential이지 DRM이나 모델 파일 checksum이 아닙니다.

  • --accept-license가 없으면 조건을 표시하고 다운로드하지 않은 채 종료합니다.
  • 모델, manifest, license를 함께 보관하고 일반 운영에서는 /models를 read-only로 mount합니다.
  • 상용 이용 또는 공개 조건의 적용 범위가 불명확하면 사용 전에 InsightFace에 문의하세요.

3. 서비스 시작과 준비 상태 확인

설치한 stack만 시작합니다. CPU는 http://SERVER:18097/, CUDA는 http://SERVER:18098/을 엽니다. health 확인 뒤 데이터를 등록하기 전에 대시보드 또는 시스템에서 서비스, 데이터베이스, 모델, execution provider가 모두 준비되었는지 확인합니다.

CUDA 배포는 CUDAExecutionProvider를 표시해야 합니다. 시작할 때 GPU, Driver, CUDA/cuDNN/ONNX Runtime, 실제 detector와 recognizer Session, Provider placement, warm-up을 검증하며 실패하면 CPU로 조용히 전환하지 않고 종료합니다.

CPU 시작과 health 확인
docker compose -f server/deploy/compose.cpu.yml up -d
curl -fsS http://127.0.0.1:18097/v1/health
CUDA 12 시작과 health 확인
docker compose -f server/deploy/compose.cuda12.yml up -d
curl -fsS http://127.0.0.1:18098/v1/health

4. 첫 Collection → Person → Search 완료

검색 가능한 얼굴 Collection을 생성하고 관리하는 InsightFace Server Collections 화면
Person과 FaceSample을 등록하기 전에 모델에 고정된 Collection을 만듭니다.

Collections에서 employees 같은 안정적인 ID를 만듭니다. System이 제공하는 search profile을 선택하고 memory budget에 맞게 capacity를 정한 뒤 기본 raw cosine threshold 0.4로 시작합니다. Collection은 모델 identity, digest, embedding dimension, preprocessing과 detection profile contract에 고정됩니다.

People에서 Collection을 선택하고 선명한 JPEG, PNG 또는 WebP 한 장 이상으로 Person을 등록합니다. standard review는 사용 가능한 얼굴 하나만 허용하고 크기, confidence, 선명도, 밝기와 pose를 검사하므로 좋은 출발점입니다. batch는 일부만 성공할 수 있으므로 각 거부 이유를 확인하세요.

Search에서 같은 Collection을 선택하고 그 Person의 다른 사진을 업로드합니다. 결과는 raw cosine similarity 내림차순이며 Person score는 FaceSample 중 최고값입니다. similarity는 확률이 아닙니다. 일치하지 않는 경우 빈 목록이 정상 결과입니다.

  • 원본 업로드는 기본적으로 저장하지 않습니다. 선택적 저장은 112×112 bounding-box JPEG crop이며 원본이나 정렬된 인식 입력이 아닙니다.
  • 승인 sample은 SQLite에 commit된 다음 성공 응답 전에 정확 검색 memory index에 추가됩니다. 재시작 시 SQLite에서 재구축합니다.
  • Detect에서 얼굴 없음은 정상 빈 결과입니다. Compare는 한쪽에 사용 가능한 얼굴이 없으면 422 face_not_found를 반환합니다.

5. 네트워크 공개 전에 보안 적용

제공 Compose는 격리 평가를 위해 인증이 꺼져 있습니다. 다른 사용자나 네트워크가 접근하기 전에 인증을 켜고 길고 무작위인 API Key를 배포 secret 환경에 설정한 다음 선택한 stack을 다시 시작합니다. Web UI는 현재 tab의 memory에만 Key를 보관할 수 있습니다.

신뢰하는 reverse proxy에서 HTTPS를 종료하고 광범위한 CORS 대신 필요한 origin만 허용하며 edge에 rate/body/time limit를 적용합니다. Docker, /data, /models와 backup 접근을 제한하고 이미지, embedding, RTSP credential 또는 API Key를 log에 남기지 마세요.

  • 1단계에는 역할 구분 없는 API Key 하나만 있습니다. multi-tenant 권한 시스템이 아니며 내장 계정이나 RBAC도 없습니다.
  • 같은 data volume을 나중에 다른 INSIGHTFACE_API_KEY로 시작하면 active Key가 의도적으로 교체됩니다.
  • 내장 TLS나 법적 compliance layer가 없으며 합법적 처리와 운영 통제는 운영자 책임입니다.
CPU: 시작 전에 인증 활성화
export INSIGHTFACE_AUTH_ENABLED=true
export INSIGHTFACE_API_KEY='replace-with-a-long-random-secret'
docker compose -f server/deploy/compose.cpu.yml up -d
CUDA 12: 시작 전에 인증 활성화
export INSIGHTFACE_AUTH_ENABLED=true
export INSIGHTFACE_API_KEY='replace-with-a-long-random-secret'
docker compose -f server/deploy/compose.cuda12.yml up -d

6. 데이터 영속화, backup과 안전한 종료

/data의 SQLite가 영속적인 source of truth이고 memory의 정확 검색 index는 재생성할 수 있습니다. Compose는 모델을 read-only로 mount하고 /data를 named volume에 저장합니다. 쓰기를 중지하거나 SQLite-safe snapshot 방식으로 database와 설정된 crop storage를 함께 backup하세요.

시작한 stack에 맞는 전체 down 명령을 사용합니다. 일반 down은 container와 network를 제거해도 named data volume은 보존합니다. 절대로 -v를 붙이지 마세요. docker compose down -v는 해당 data volume을 영구 삭제합니다.

  • upgrade 전에 안전한 snapshot을 만들고 /models와 license를 보존하며 data copy로 새 image를 먼저 시험합니다.
  • 이후 migration, /v1/health, 모델 contract와 알려진 검색을 확인합니다.
  • FaceSample 삭제는 embedding과 선택적 crop을 제거하며 비어 있지 않은 Collection 삭제에는 명시적 force 확인이 필요합니다.
volume을 삭제하지 않고 CPU 중지
docker compose -f server/deploy/compose.cpu.yml down
volume을 삭제하지 않고 CUDA 중지
docker compose -f server/deploy/compose.cuda12.yml down

7. 시작 및 request 실패 진단

health부터 확인하고 System, 선택한 Compose의 container 상태와 log를 봅니다. CUDA는 Driver, GPU, 모델 Session, CUDAExecutionProvider, Provider audit 또는 warm-up이 실패하면 의도적으로 시작을 중단하며 CPU로 silent fallback하지 않습니다.

모든 응답에는 x-request-id가 있고 error body에는 request_id가 있습니다. 문제를 보고할 때 관련 log와 함께 보관하세요. 401 unauthorized는 대개 Key 누락 또는 교체, 409 collection_model_mismatch는 다른 모델 contract, 422 face_not_found는 사용 가능한 얼굴을 선택하지 못했음을 뜻합니다.

  • System의 CPUExecutionProvider 또는 CUDAExecutionProvider가 선택한 Compose와 일치하는지 확인합니다.
  • server/.models의 검증된 package와 서명 license, /models read-only mount를 확인합니다.
  • CUDA에서는 CPU fallback을 기대하지 말고 host Driver, GPU visibility, NVIDIA Container Toolkit을 수정합니다.
CPU health, 상태와 최근 log
curl -fsS http://127.0.0.1:18097/v1/health
docker compose -f server/deploy/compose.cpu.yml ps
docker compose -f server/deploy/compose.cpu.yml logs --tail=200 server
CUDA 12 health, 상태와 최근 log
curl -fsS http://127.0.0.1:18098/v1/health
docker compose -f server/deploy/compose.cuda12.yml ps
docker compose -f server/deploy/compose.cuda12.yml logs --tail=200 server

프로덕션 배포 지원이 필요하신가요?

모델 라이선스, runtime 최적화, 대상 하드웨어 배포 지원은 InsightFace에 문의하세요.

엔터프라이즈 문의 보내기