Python과 InsightFace Server에서 선택적 RGB 라이브니스 검사 활성화
인식 전에 검사하고 얼굴별 상태와 점수를 받으세요. 감지, 비교, 검색, RTSP 작업에서 라이브니스 결과로 인식 여부를 결정하거나 관찰 모드를 사용하도록 설정할 수 있습니다.
이 가이드에서 구축할 내용
얼굴 처리에는 FaceAnalysis를, 사람 감지·얼굴 대조·신체 ReID를 함께 사용하려면 PersonAnalysis를 선택하세요.
기본적으로 비활성화되어 있습니다. 등록 시 검사는 별도로 설정합니다.
시작하기 전에
- python-package/docs/liveness.md가 포함된 업데이트된 InsightFace 2 소스와 Python 3.10 이상, 설치된 패키지 의존성이 필요합니다. 이 가이드는 해당 소스 버전을 대상으로 하며, 이전 설치 패키지에는 애드온 API가 없을 수 있습니다.
- 얼굴 주변 영역이 충분한 로컬 input.jpg와 기본 모델 및 라이브니스 애드온을 설치할 수 있는 환경이 필요합니다. 각 모델에 제공되는 이용 조건을 따르세요.
- Docker 가이드의 배포와 기존 설정을 사용하세요. 컨테이너는 이미 root로 실행되며 모델과 설정 디렉터리는 쓰기 가능합니다. CLI 활성화는 Server의 첫 시작 전에도 가능합니다.
1. Python에서 라이브니스 검사를 명시적으로 실행
업데이트된 저장소 루트에서 활성 가상 환경에 Python 패키지를 설치하세요. 예제를 실행하기 전에 작업 디렉터리에 input.jpg를 두세요. CPU 예제는 감지와 인식을 선택하고, addons=['liveness']로 별도의 라이브니스 모델을 활성화합니다.
처음 실행할 때 없는 모델을 다운로드할 수 있습니다. 애드온은 ~/.insightface/addons/liveness.onnx에 저장되며 로드 전에 SHA-256을 검증합니다. 파일을 설치하는 것만으로는 활성화되지 않습니다. addons=['liveness']를 명시하세요. addons를 생략하면 검사는 꺼진 상태로 유지됩니다.
cd python-package
python -m pip install .import cv2
from insightface.app import FaceAnalysis
image_bgr = cv2.imread("input.jpg")
if image_bgr is None:
raise FileNotFoundError("input.jpg")
app = FaceAnalysis(
name="buffalo_l",
allowed_modules=["detection", "recognition"],
addons=["liveness"],
liveness_mode="normal",
liveness_threshold=0.8,
providers=["CPUExecutionProvider"],
)
app.prepare(ctx_id=-1, det_size=(640, 640))
for face in app.get(image_bgr):
print(face.liveness)
if face.liveness is not None:
print(
face.liveness.status,
face.liveness.is_live,
face.liveness.live_score,
)2. 결과를 읽고 인식 정책 선택
normal 모드는 is_live가 True일 때만 인식을 수행합니다. 다른 얼굴도 감지 결과와 함께 목록에 남지만 embedding은 없습니다. observe 모드는 비라이브 판정이나 입력 거부 시에도 결과를 유지하면서 인식을 계속합니다. 모델, 정렬, 추론 오류는 두 모드 모두에서 예외를 발생시킵니다.
- status='ok': is_live는 True 또는 False이며 live_score는 [0, 1] 범위의 숫자입니다. 기본 임계값은 0.8이고 같은 값도 통과합니다. 배포 환경의 실행 공급자와 대표적인 입력을 사용해 임계값을 검증하세요.
- status='input_rejected': is_live와 live_score는 None입니다. 정렬된 얼굴 주변의 원본 이미지 영역이 부족하다는 뜻이며, 위조 판정이 아닙니다. 얼굴을 중앙으로 옮기거나 카메라에서 물러나거나 덜 잘린 이미지를 사용하세요. reason에 원인이 표시됩니다.
- 애드온을 선택하지 않으면 face.liveness는 None이며, 감지된 얼굴이 없으면 []를 반환합니다. 프로그램에서는 status와 is_live를 사용하세요. Python/API의 reason은 영어 설명이며 고정 상태 코드로 해석하면 안 됩니다.
선택 사항: RGB 라이브니스 검사 활성화
지원합니다. 모델 설치 시 --enable-liveness를 추가하거나 Web UI의 시스템에서 활성화한 뒤 Server를 시작 또는 재시작하세요. normal은 인식 진행을 제어하며 observe는 결과를 기록하고 인식을 계속합니다. 기본적으로 꺼져 있고 등록에는 별도 스위치가 있습니다.
새 배포에서는 Docker 배포 가이드의 모델 설치 명령 끝에 --enable-liveness를 추가하세요. 필요한 모델을 검증하고 첫 시작 전에 활성화 설정을 저장합니다.
실행 중인 서비스는 아래 해당 명령을 실행한 뒤 재시작하세요. 일반 설치와 models addons install liveness는 기능을 활성화하지 않습니다.
시스템 → 라이브니스 검사에서 다운로드 후 재시작 시 활성화하는 방법도 있습니다. Web과 CLI는 모델을 검증하고 다른 설정을 유지하면서 두 목록에 liveness를 추가합니다. 다운로드 실패 시 활성화하지 않으므로 설정 저장 성공을 기다리세요.
새 배포는 설치 후 시작하고 기존 서비스는 아래 CPU/CUDA 명령으로 재시작하세요. enabled=true, restart_required=false를 확인하세요. installed는 검증된 파일, configured_enabled는 저장된 설정을 의미합니다. 마운트 변경 시 컨테이너를 다시 생성해야 합니다.
라이브니스 검사는 기본적으로 꺼져 있습니다. 웹 작업은 등록 설정을 변경하지 않으며 liveness_on_registration=false가 유지됩니다. 등록 시에도 normal/observe 정책을 적용하려면 별도로 true로 설정하세요. 끄려면 inference.addons와 addons.auto_download를 모두 빈 목록으로 저장한 뒤 재시작하세요.
docker compose -f server/deploy/compose.cpu.yml run --rm models install buffalo_l --accept-license --enable-livenessdocker compose -f server/deploy/compose.cuda12.yml run --rm models install buffalo_l --accept-license --enable-livenessdocker compose -f server/deploy/compose.cpu.yml restart serverdocker compose -f server/deploy/compose.cuda12.yml restart server