메인 콘텐츠로 건너뛰기

개요

얼굴 검색은 팀에서 검색 결과가 Approved 또는 Declined로 반환된 이유를 파악할 수 있도록 몇 가지 경고를 생성합니다. 경고는 POST /v3/face-search/ 응답의 face_search.warnings[] 배열로 반환됩니다(얼굴 검색 보고서 참조). 이곳의 경고는 워크플로 경고에 비해 축소된 형태를 사용합니다. 즉, node_id가 없습니다. 문서화된 응답 명세는 risk, additional_data, log_type, short_description, long_description의 5개 필드를 선언하며, 런타임 payload에는 추가로 feature가 포함되는데 이 endpoint에서는 항상 "LIVENESS"입니다.

생성되는 경고

생성자: FaceSearchAPIView.add_warnings (apis/views/face_search.py:250-330); 상태 도출: get_face_search_status (apis/views/face_search.py:242-248), 이는 두 가지 차단 목록 위험에 대해서만 거부합니다. 알아두어야 할 생성 규칙:
  • 차단 목록이 중복보다 우선합니다. 확인된 차단 목록 일치는 DUPLICATED_FACE를 억제하고, 가능한 차단 목록 일치는 POSSIBLE_DUPLICATED_FACE를 억제합니다. 즉, 동일한 신뢰도 구간에 대해 한 쌍의 두 구성원을 모두 받는 일은 없습니다.
  • additional_data는 일치하는 첫 번째 얼굴만 참조합니다(matches[]에 여러 개가 포함되어 있더라도 마찬가지입니다). 차단 목록 경고에는 {blocklisted_session_id, blocklisted_session_number, api_service}가 포함되고, 중복 경고에는 {duplicated_session_id, duplicated_session_number, api_service}가 포함되며, MULTIPLE_FACES_DETECTED에는 null이 포함됩니다. api_service 값은 대문자(예: PASSIVE_LIVENESS)이거나 워크플로 세션의 경우 null입니다.
  • 허용 목록에 있는 얼굴은 중복 경고를 억제합니다 — 높은 신뢰도의 허용 목록 일치는 DUPLICATED_FACE/POSSIBLE_DUPLICATED_FACE를 제거합니다(차단 목록 경고는 절대 제거하지 않습니다).

정확한 경고 문자열

검색 이미지 게이트

user_image에서 얼굴이 감지되지 않으면 API는 face_search 객체가 생성되기 전에 HTTP 400 및 {"error": "No face detected in the image"}로 요청을 거부합니다. 따라서 성공한 얼굴 검색 응답에는 NO_FACE_DETECTED 경고가 절대 나타나지 않습니다. 이는 warnings[]가 아닌 최상위 error 문자열로 반환됩니다.

구성 가능한 설정

확인된 일치 항목(FACE_IN_BLOCKLIST, DUPLICATED_FACE)과 가능한 일치 항목(POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE)을 구분하는 유사도 구간은 내부적으로 고정되어 있습니다. 애플리케이션별 임계값 조정은 이 endpoint가 아닌 워크플로 라이브니스 확인에 적용됩니다. 요청별로 제어할 수 있는 스위치는 다음과 같습니다.
  • search_type (most_similar, 기본값 | blocklisted_or_approved) — most_similar는 등록된 모든 얼굴을 유사도순으로 순위를 매깁니다. blocklisted_or_approved는 후보를 차단 목록에 등록된 얼굴, 허용 목록에 등록된 얼굴, 승인된 세션의 얼굴, 가져온 사용자 프로필 얼굴로 제한하며 차단 목록 항목의 순위를 먼저 매깁니다.
  • save_api_request (기본값 true) — 호출을 API 유형 세션으로 저장하고 검색된 얼굴을 얼굴 검색 색인에 등록합니다. 얼굴 검색 호출로 등록된 얼굴은 향후 얼굴 검색 결과에서 제외됩니다. 저장하거나 등록하지 않고 조회하려면 false로 설정합니다.
  • rotate_image (기본값 false) — 90도 회전을 시도하고 얼굴 감지가 가장 잘 된 방향을 유지합니다. EXIF 방향 정보가 누락되었을 때 유용합니다.

예시

차단 목록 일치 (Declined로 강제 설정됨)

중복 신호 (상태는 Approved로 유지됨)

관련 항목

경고 유형

마지막 수정일 2026년 11월 7일