> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 生物识别认证警告与代码

> Didit 生物识别认证警告处理指南：涵盖 LOW_LIVENESS_SCORE、人脸攻击、黑名单匹配及人脸比对相似度低等警告，支持配置阈值与拒绝操作。

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

## 概述

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

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

警告保持整个平台通用的[警告对象](https://docs.didit.me/zh/reference/data-models.md#警告对象)结构：`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` 一起发出，请参阅[活体检测警告](https://docs.didit.me/zh/core-technology/liveness/warnings-liveness.md#跨会话人脸匹配)。 |

`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`。如果两个会话的身份证件具有相同的签发国家/地区、完全相同的证件号或个人编号，且出生日期无冲突，则即便两端姓名使用不同的文字系统书写，也不会被视为不匹配。请参阅[活体检测警告](https://docs.didit.me/zh/core-technology/liveness/warnings-liveness.md#跨会话人脸匹配)。

## 人脸比对警告

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

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

```json theme={null}
{
  "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
}
```

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

```json theme={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，因为参考图像来源于创建会话时存储的人像照片。

## 警告类型

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

## 相关内容

> [card] [生物识别认证报告](https://docs.didit.me/zh/core-technology/biometric-auth/report-biometric-authentication.md)
>
> `liveness_checks[]` 和 `face_matches[]` 在 V3 决策中的出现位置。

> [card] [活体检测警告](https://docs.didit.me/zh/core-technology/liveness/warnings-liveness.md)
>
> 完整的活体检测警告参考，包含重复人脸匹配。

> [card] [人脸比对警告](https://docs.didit.me/zh/core-technology/face-match/warnings-face-match.md)
>
> 针对 1:1 比对的完整人脸比对警告参考。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.