Python과 InsightFace Server에서 선택적 RGB 라이브니스 검사 활성화
인식 전에 검사하고 얼굴별 상태와 점수를 받으세요. 감지, 비교, 검색, RTSP 작업에서 라이브니스 결과로 인식 여부를 결정하거나 관찰 모드를 사용하도록 설정할 수 있습니다.
이 가이드에서 구축할 내용
Python에서 얼굴을 분석하세요. 인식 전 선택적 RGB 라이브니스 검사와 얼굴별 결과를 지원합니다.
기본적으로 비활성화되어 있습니다. 등록 시 검사는 별도로 설정합니다.
시작하기 전에
- python-package/docs/liveness.md가 포함된 업데이트된 InsightFace 2 소스와 Python 3.10 이상, 설치된 패키지 의존성이 필요합니다. 이 가이드는 해당 소스 버전을 대상으로 하며, 이전 설치 패키지에는 애드온 API가 없을 수 있습니다.
- 얼굴 주변 영역이 충분한 로컬 input.jpg와 기본 모델 및 라이브니스 애드온을 설치할 수 있는 환경이 필요합니다. 각 모델에 제공되는 이용 조건을 따르세요.
- Server: 기본 모델이 설치된 업데이트된 Linux 배포가 실행 중이어야 합니다. 웹 설치에는 Server 사용자(Compose의 UID/GID 10001)가 마운트된 addons 디렉터리와 전체 설정 디렉터리에 쓸 수 있어야 합니다.
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은 영어 설명이며 고정 상태 코드로 해석하면 안 됩니다.
3. Server에서 설치, 재시작, 상태 확인
네. Server Web UI에서 선택적 RGB 라이브니스 애드온을 설치하고 활성화할 수 있습니다. 일반 모드는 라이브니스 결과에 따라 인식 여부를 결정하고, 관찰 모드는 결과를 보고하면서 인식을 계속합니다. 기본적으로 비활성화되어 있으며, 등록에는 별도 스위치가 있습니다. 설정 및 결과 해석은 라이브니스 검사 가이드를 참조하세요.
System → Liveness에서 Download and enable after restart를 선택하세요. 게시된 애드온을 다운로드하거나 검증된 캐시를 재사용하고, SHA-256을 검증한 다음 inference.addons와 addons.auto_download에 ['liveness']를 저장합니다. 설치와 설정 저장이 성공한 뒤 재시작하세요.
저장소 루트에서 재시작 명령을 실행하세요. CUDA에는 compose.cuda12.yml을 사용합니다. System에서 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 restart server