Cerca facial 1:N: advertències i codis d'error

Visió general

La Cerca facial emet un conjunt reduït d’advertències perquè el teu equip pugui saber per què una cerca ha retornat Approved o Declined. Les advertències es retornen a l’array face_search.warnings[] de la resposta de POST /v3/face-search/ (consulta l’informe de Cerca facial). Les advertències d’aquesta secció utilitzen una estructura reduïda en comparació amb les advertències dels fluxos de treball: no hi ha cap node_id. El contracte de resposta documentat declara cinc camps — risk, additional_data, log_type, short_description, long_description —, i el payload en temps d’execució inclou addicionalment feature, que sempre és "LIVENESS" en aquest endpoint.

Advertències generades

Risc	Causa	Gravetat (`log_type`)	Afecta l’estat	Correcció recomanada
`FACE_IN_BLOCKLIST`	La imatge de cerca ha coincidit amb una cara de la llista de bloqueig de cares de la teva aplicació per sobre de la banda de similitud d’alta confiança.	`error`	Força `Declined`.	Rebutja l’usuari. Investiga la sessió vinculada mitjançant `additional_data.blocklisted_session_id`.
`POSSIBLE_FACE_IN_BLOCKLIST`	Una cara de la llista de bloqueig ha coincidit dins de la banda inferior de similitud “possible”, per sota de la banda d’alta confiança.	`error`	Força `Declined` a l’API independent de Cerca facial (més estricta que la comprovació de prova de vida del flux de treball, que envia aquest risc a revisió).	Revisió manual. Confirma la coincidència amb l’evidència original de la llista de bloqueig abans d’actuar.
`MULTIPLE_FACES_DETECTED`	S’ha trobat més d’una cara a la imatge de cerca enviada. La cerca s’executa igualment, utilitzant la cara detectada més gran.	`warning`	Cap — mai rebutja per si sola.	Torna a capturar amb un sol subjecte a l’enquadrament si la cara més gran no és la desitjada.
`DUPLICATED_FACE`	La cara ha coincidit, per sobre de la banda d’alta confiança, amb una cara d’una sessió aprovada o una cara de perfil d’usuari importada. L’endpoint independent no exclou sessions amb el mateix `vendor_data`, de manera que un usuari recurrent coincideix amb les seves pròpies sessions anteriors.	`information`	Cap — els duplicats es mostren com a senyal, no com a rebutjos.	Investiga la sessió vinculada mitjançant `additional_data.duplicated_session_id`. Decideix si vols bloquejar o fusionar comptes pel teu compte.
`POSSIBLE_DUPLICATED_FACE`	El mateix que `DUPLICATED_FACE`, però la similitud se situa a la banda inferior “possible” en lloc de la banda d’alta confiança.	`information`	Cap.	Revisió manual abans de tractar els dos registres com la mateixa persona.

Emissor: FaceSearchAPIView.add_warnings (apis/views/face_search.py:250-330); derivació de l’estat: get_face_search_status (apis/views/face_search.py:242-248), que rebutja únicament pels dos riscos de llista de bloqueig. Regles d’emissió que val la pena conèixer:

La llista de bloqueig té prioritat sobre els duplicats. Una coincidència confirmada a la llista de bloqueig suprimeix DUPLICATED_FACE, i una possible coincidència a la llista de bloqueig suprimeix POSSIBLE_DUPLICATED_FACE; mai s’obtenen tots dos membres d’un parell per a la mateixa banda de confiança.
additional_data fa referència només a la primera cara coincident, fins i tot quan matches[] en conté diverses. Les advertències de llista de bloqueig inclouen {blocklisted_session_id, blocklisted_session_number, api_service}; les advertències de duplicats inclouen {duplicated_session_id, duplicated_session_number, api_service}; MULTIPLE_FACES_DETECTED conté null. El valor de api_service està en majúscules (per exemple, PASSIVE_LIVENESS) o és null per a sessions de flux de treball.
Les cares a la llista de permisos suprimeixen les advertències de duplicats: una coincidència d’alta confiança a la llista de permisos elimina DUPLICATED_FACE/POSSIBLE_DUPLICATED_FACE (mai elimina les advertències de llista de bloqueig).

Cadenes exactes de les advertències

Risc	`short_description`	`long_description`
`FACE_IN_BLOCKLIST`	Cara a la llista de bloqueig	El sistema ha identificat una cara a la llista de bloqueig, la qual cosa significa que no es permet verificar la cara.
`POSSIBLE_FACE_IN_BLOCKLIST`	Possible cara a la llista de bloqueig	El sistema ha identificat una possible cara a la llista de bloqueig, la qual cosa significa que no es permet verificar la cara.
`DUPLICATED_FACE`	Cara duplicada d’una altra sessió aprovada	El sistema ha identificat una cara duplicada d’una altra sessió aprovada, la qual cosa requereix una investigació addicional.
`POSSIBLE_DUPLICATED_FACE`	Possible cara duplicada d’una altra sessió aprovada	El sistema ha identificat una possible cara duplicada d’una altra sessió aprovada, la qual cosa requereix una investigació addicional.
`MULTIPLE_FACES_DETECTED`	S’han detectat múltiples cares	S’han detectat múltiples cares a la imatge de prova de vida. El sistema utilitza la cara més gran per a la verificació de la prova de vida i la comparació facial, però la presència de múltiples cares pot requerir una revisió addicional.

Control de la imatge de cerca

Quan no es detecta cap cara a user_image, l’API rebutja la sol·licitud amb HTTP 400 i {"error": "No face detected in the image"} abans que es construeixi un objecte face_search, de manera que mai apareix una advertència NO_FACE_DETECTED en una resposta satisfactòria de Cerca facial. Això es retorna com una cadena error de primer nivell, no a warnings[].

Opcions de configuració

Les bandes de similitud que separen les coincidències confirmades (FACE_IN_BLOCKLIST, DUPLICATED_FACE) de les possibles coincidències (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) estan fixades internament; l’ajust de llindars per aplicació s’aplica a la comprovació de prova de vida del flux de treball, no a aquest endpoint. Els paràmetres que controles per sol·licitud són:

search_type (most_similar, per defecte | blocklisted_or_approved) — most_similar classifica cada cara registrada per similitud; blocklisted_or_approved restringeix els candidats a cares a la llista de bloqueig, cares a la llista de permisos, cares de sessions aprovades i cares importades de perfils d’usuari, classificant en primer lloc les entrades de la llista de bloqueig.
save_api_request (per defecte true) — desa la crida com una sessió de tipus API i incorpora la cara cercada al teu índex de cerca facial. Les cares incorporades mitjançant crides de Cerca facial s’exclouen dels futurs resultats de Cerca facial. Estableix-ho a false per consultar sense desar ni incorporar.
rotate_image (per defecte false) — prova rotacions de 90 graus i manté l’orientació amb la millor detecció facial; és útil quan falta l’orientació EXIF.

Exemples

Coincidència amb la llista de bloqueig (força `Declined`)

{
  "warnings": [
    {
      "risk": "FACE_IN_BLOCKLIST",
      "feature": "LIVENESS",
      "additional_data": {
        "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "blocklisted_session_number": 323442,
        "api_service": "PASSIVE_LIVENESS"
      },
      "log_type": "error",
      "short_description": "Face in blocklist",
      "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
    }
  ]
}

Senyal de duplicat (l’estat es manté `Approved`)

{
  "warnings": [
    {
      "risk": "MULTIPLE_FACES_DETECTED",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Multiple faces detected",
      "long_description": "Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review."
    },
    {
      "risk": "DUPLICATED_FACE",
      "feature": "LIVENESS",
      "additional_data": {
        "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "duplicated_session_number": 1024,
        "api_service": null
      },
      "log_type": "information",
      "short_description": "Duplicated face from other approved session",
      "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
    }
  ]
}

Relacionat

Informe de Cerca facial — estructura completa de la resposta
Referència de l’API de Cerca facial — paràmetres de la sol·licitud
Advertències de Coincidència facial — advertències 1:1 de selfie a document (separades de Cerca facial)
Models de dades — Cerca facial — esquema canònic

Autenticació

Verificació

Monitoratge

Plataforma

Cerca facial 1:N: advertències i codis d'error

Visió general

Advertències generades

Cadenes exactes de les advertències

Control de la imatge de cerca

Opcions de configuració

Exemples

Coincidència amb la llista de bloqueig (força `Declined`)

Senyal de duplicat (l’estat es manté `Approved`)

Relacionat

Tipus d’advertències

​Visió general

​Advertències generades

​Cadenes exactes de les advertències

​Control de la imatge de cerca

​Opcions de configuració

​Exemples

​Coincidència amb la llista de bloqueig (força Declined)

​Senyal de duplicat (l’estat es manté Approved)

​Relacionat

​Tipus d’advertències

Visió general

Advertències generades

Cadenes exactes de les advertències

Control de la imatge de cerca

Opcions de configuració

Exemples

Coincidència amb la llista de bloqueig (força `Declined`)

Senyal de duplicat (l’estat es manté `Approved`)

Relacionat

Tipus d’advertències