生物识别认证警告与代码

生物识别认证结合了活体检测与可选的 1:1 人脸比对，比对对象为会话创建时解析的参考人脸（提供的 portrait_image，或通过 vendor_data 检索到的用户已存储人脸）。每个步骤都会在 V3 决策 payload 中发出各自的警告。本页列出了所有代码、出现位置，以及阈值如何转换为最终会话状态。

概述

当生物识别认证会话运行时，Didit 会：

使用 3D Action、Flash 或 Passive Liveness（method：ACTIVE_3D、FLASHING 或 PASSIVE）捕获实时自拍照。
从捕获图像中提取最大的人脸并评估其活体分数。
如果工作流包含人脸比对，则将捕获的人脸与会话的参考人脸（提供的 portrait_image 或用户已存储的人脸）进行比对。
将每个步骤的结果以及任何警告写入会话决策中。

警告保持整个平台通用的警告对象结构：feature、risk、additional_data、log_type、short_description、long_description 和 node_id。

警告出现的位置

决策响应键	警告上的功能标签	触发时机
`liveness_checks[].warnings[]`	`LIVENESS`	活体评分、人脸质量、亮度、多张人脸，以及黑名单/白名单/重复人脸检查。
`face_matches[].warnings[]`	`FACEMATCH`	与会话参考人脸（提供的 `portrait_image` 或用户已存储的人脸）的人脸比对。

在典型的生物识别认证会话中，每个数组各有一个项目。在多实例工作流中，每个警告上的 node_id 可用于区分是由哪个步骤生成的。

自动拒绝条件

以下警告始终会拒绝其步骤（log_type: "error"），无论您如何配置工作流：

风险	功能	自动拒绝的原因
`FACE_IN_BLOCKLIST`	`LIVENESS`	人脸匹配到了您人脸黑名单中的条目。
`NO_FACE_DETECTED`	`LIVENESS`	活体捕获期间未定位到人脸，或用户耗尽了捕获重试次数。
`LIVENESS_FACE_ATTACK`	`LIVENESS`	检测到呈现攻击（面具、屏幕重放、深度伪造类欺骗攻击）。
`NO_REFERENCE_IMAGE`	`FACEMATCH`	没有可用于执行比对的参考图像。触发此项时，`LOW_FACE_MATCH_SIMILARITY` 将被抑制。

当 NO_FACE_DETECTED 触发时，LOW_LIVENESS_SCORE 会被抑制（因为没有人脸可评分）。

可配置阈值与操作

这些警告会先进行评分，然后通过您为每个工作流设置的阈值和操作映射为相应状态：

风险	功能	可配置行为
`LOW_LIVENESS_SCORE`	`LIVENESS`	分数等于或低于审核阈值 → `In Review`；等于或低于拒绝阈值 → `Declined`。
`LOW_FACE_MATCH_SIMILARITY`	`FACEMATCH`	分数等于或低于审核阈值（默认 70）→ `In Review`；等于或低于拒绝阈值（默认 50）→ `Declined`。
`LOW_FACE_QUALITY`	`LIVENESS`	审核阈值（默认 15）→ `In Review`；拒绝阈值（默认 0，即禁用拒绝）→ `Declined`。仅限 Passive Liveness。
`LOW_FACE_LUMINANCE`	`LIVENESS`	低于最小亮度阈值（默认 20）：无操作 / 审核（默认）/ 拒绝。仅限 Passive Liveness。
`HIGH_FACE_LUMINANCE`	`LIVENESS`	高于最大亮度阈值（默认 80）：无操作 / 审核（默认）/ 拒绝。仅限 Passive Liveness。
`MULTIPLE_FACES_DETECTED`	`LIVENESS`	捕获到多张人脸时：无操作（默认）/ 审核 / 拒绝。仅限 Passive Liveness。
`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`	`LIVENESS`	共用一个重复人脸操作：在与其他用户已通过或导入的人脸匹配时，执行无操作（默认）/ 审核 / 拒绝。
`DUPLICATED_FACE_NAME_MISMATCH`	`LIVENESS`	专属操作（`face_liveness_duplicated_face_name_mismatch_action`）：无操作 / 审核（默认）/ 拒绝。当匹配会话的身份与当前会话解析的姓名不一致时，与 `DUPLICATED_FACE` 一起发出，请参阅活体检测警告。

POSSIBLE_FACE_IN_BLOCKLIST（LIVENESS）不可配置：较低置信度的黑名单匹配始终会流转至审核（log_type: "warning"）。

捕获重试

仅由可修正的捕获质量风险（低分、无人脸、质量、亮度、多张人脸，以及人脸比对相似度低）导致的失败会进入重试循环，然后才会确定状态：用户最多可进行 face_liveness_max_attempts / face_match_max_attempts 次尝试（默认为 3 次，每个工作流节点可配置为 2–5 次）。当额度耗尽时，将应用最后一次尝试计算出的状态，并记录 LIVENESS_MAX_ATTEMPTS_EXCEEDED 或 FACE_MATCH_MAX_ATTEMPTS_EXCEEDED 为 information 以作留存。

活体检测警告

API 会返回以下确切的 short_description 和 long_description 字符串：

`risk`	`short_description`	`long_description`
`LOW_LIVENESS_SCORE`	活体检测分数较低	活体检测得分较低，表明可能使用了非活体人脸呈现或生物特征数据质量较差。
`NO_FACE_DETECTED`	活体检测中未检测到人脸	系统在活体检测过程中无法识别到人脸，这可能是由于图像质量差、位置不当或技术问题导致的。
`LIVENESS_FACE_ATTACK`	活体人脸攻击	系统检测到试图绕过活体检测的潜在攻击行为。
`FACE_IN_BLOCKLIST`	人脸位于黑名单中	系统识别出该人脸位于黑名单中，这意味着该人脸不被允许进行验证。
`POSSIBLE_FACE_IN_BLOCKLIST`	人脸疑似位于黑名单中	系统识别出该人脸可能位于黑名单中，这意味着该人脸不被允许进行验证。
`FACE_IN_ALLOWLIST`	人脸位于白名单中	该人脸匹配了应用的白名单，因此针对该信号跳过了重复人脸操作。
`POSSIBLE_FACE_IN_ALLOWLIST`	人脸疑似位于白名单中	该人脸疑似匹配了应用的白名单，因此针对该信号跳过了疑似重复人脸操作。
`DUPLICATED_FACE`	来自其他已通过会话的重复人脸	系统识别出该人脸与另一个已通过的会话重复，需要进一步调查。
`POSSIBLE_DUPLICATED_FACE`	疑似来自其他已通过会话的重复人脸	系统识别出该人脸疑似与另一个已通过的会话重复，需要进一步调查。
`DUPLICATED_FACE_NAME_MISMATCH`	不同姓名下的重复人脸	同一张人脸此前已在另一个会话中通过审核，但登记的姓名不同。重复人脸背后的身份与当前会话申报的身份不符，这是身份欺诈的强烈指标。
`MULTIPLE_FACES_DETECTED` (仅限 Passive)	检测到多张人脸	在活体图像中检测到多张人脸。系统会使用最大的人脸进行活体验证和人脸比对，但多张人脸的存在可能需要额外的人工审核。
`LOW_FACE_QUALITY` (仅限 Passive)	人脸质量较低	人脸图像质量低于可接受阈值，这可能会影响活体检测的可靠性。原因可能包括摄像头分辨率、对焦或压缩失真。
`LOW_FACE_LUMINANCE` (仅限 Passive)	人脸亮度较低	人脸图像过暗，这可能会影响活体检测的准确性。建议在更好的光照条件下操作。
`HIGH_FACE_LUMINANCE` (仅限 Passive)	人脸亮度较高	人脸图像过亮或曝光过度，这可能会影响活体检测的准确性。建议减弱光照或避免强光直射。
`LIVENESS_MAX_ATTEMPTS_EXCEEDED`	超出最大活体检测尝试次数	已达到活体采集的最大尝试次数。已应用最后一次尝试计算得出的状态（已拒绝或审核中）。

黑名单、白名单和重复匹配会携带包含匹配会话的 additional_data（blocklisted_session_id / allowlisted_session_id / duplicated_session_id、匹配的 *_session_number 以及 api_service）。每份报告中仅会出现这六个代码之一。DUPLICATED_FACE_NAME_MISMATCH 是唯一的例外：当匹配会话的身份与当前会话解析出的姓名不符时，它会伴随 DUPLICATED_FACE 一起发出，绝不会取代后者。其 additional_data 会在相同的重复会话字段基础上添加 name_match_score。如果两个会话的身份证件具有相同的签发国家/地区、完全相同的证件号或个人编号，且出生日期无冲突，则即便两端姓名使用不同的文字系统书写，也不会被视为不匹配。请参阅活体检测警告。

人脸比对警告

`risk`	`short_description`	`long_description`
`LOW_FACE_MATCH_SIMILARITY`	人脸比对相似度较低	所提供图像的面部特征与参考图像不够吻合，表明可能存在身份不匹配。
`NO_REFERENCE_IMAGE`	未找到用于进行人脸比对的源图像	缺少用于面部比对的参考图像，导致系统无法完成人脸比对流程。
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	超出最大人脸比对尝试次数	已达到人脸比对采集的最大尝试次数。已应用最后一次尝试计算得出的状态（已拒绝或审核中）。

示例 - 因人脸攻击被拒绝

{
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Declined",
      "method": "ACTIVE_3D",
      "score": 12.40,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LIVENESS_FACE_ATTACK",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Liveness Face Attack",
          "long_description": "The system detected a potential attempt to bypass the liveness check.",
          "node_id": "feature_liveness"
        }
      ]
    }
  ],
  "face_matches": null
}

示例 - 因低相似度处于审核中

{
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "In Review",
      "score": 58.70,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match"
        }
      ]
    }
  ]
}

该分数（58.70）介于拒绝阈值（默认 50）和审核阈值（默认 70）之间，因此该警告带有 log_type: "warning"，且人脸比对状态为 In Review。在此示例中，警告触发于 session_id 为 11111111-2222-3333-4444-555555555555 的会话——source_image_session_id 包含该会话自身的 id，因为参考图像来源于创建会话时存储的人像照片。

警告类型

系统会根据您应用的配置为每项风险分配警告类型。警告分为三个严重等级：

生物识别认证报告

liveness_checks[] 和 face_matches[] 在 V3 决策中的出现位置。

活体检测警告

完整的活体检测警告参考，包含重复人脸匹配。

人脸比对警告

针对 1:1 比对的完整人脸比对警告参考。

身份认证

验证

监控

平台

生物识别认证警告与代码

概述

警告出现的位置

自动拒绝条件

可配置阈值与操作

捕获重试

活体检测警告

人脸比对警告

示例 - 因人脸攻击被拒绝

示例 - 因低相似度处于审核中

警告类型

相关内容

生物识别认证报告

活体检测警告

人脸比对警告

​概述

​警告出现的位置

​自动拒绝条件

​可配置阈值与操作

​捕获重试

​活体检测警告

​人脸比对警告

​示例 - 因人脸攻击被拒绝

​示例 - 因低相似度处于审核中

​警告类型

​相关内容

生物识别认证报告

活体检测警告

人脸比对警告

概述

警告出现的位置

自动拒绝条件

可配置阈值与操作

捕获重试

活体检测警告

人脸比对警告

示例 - 因人脸攻击被拒绝

示例 - 因低相似度处于审核中

警告类型

相关内容