> ## 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 人脸比对 1:1 模块发出的各类警告说明，涵盖相似度过低、缺少参考图像、重试次数耗尽等，包含原因、严重程度与修复建议。

## Overview

人脸比对报告中的警告会标出 Didit 在执行 1:1 人脸比对过程中观察到的每一种情况。它们会出现在 `face_matches[]` 中每个项目的 `warnings[]` 数组中（参见[人脸比对报告](https://docs.didit.me/zh/core-technology/face-match/report-face-match.md)）。每个条目还包含 `feature: "FACEMATCH"` 以及触发该警告的工作流节点的 `node_id`。

每个警告包含三个层面：

1. **`risk` 代码** — 供您在代码中进行匹配的稳定标识符。
2. **`log_type`** — `information`、`warning` 或 `error`，由工作流的相似度分数阈值衍生而来。
3. **决策影响** — 由工作流中针对相似度分数设置的人工审核与拒绝阈值决定。

人脸比对模块设计精简 — 恰好只有五个风险代码，完整列表如下。

## 自动拒绝条件

以下风险始终会强制将人脸比对报告（以及会话）置为 `Declined`：

| 风险 | 触发条件 |
| - | - |
| `NO_REFERENCE_IMAGE` | `source_image`（参考照）或 `target_image`（自拍照）之一缺失，因此无法进行比对。 |

当 `NO_REFERENCE_IMAGE` 触发时，`LOW_FACE_MATCH_SIMILARITY` 将被抑制（因为没有任何内容可供评分）。

存在一种例外情况。
当身份证件验证步骤通过[非证件查询](https://docs.didit.me/zh/core-technology/id-verification/non-doc-lookup.md)完成，且对应登记系统不返回肖像也不核验人脸时，人脸比对在设计上就没有任何参考内容可与实时捕获的图像进行比对。
这种情况会报告为 `FACE_MATCH_NOT_COMPUTED`，分数为 `null`，并由下方的 `face_match_not_computed_action` 决定处理方式，而不是直接自动拒绝。

## 可配置的验证设置

在 Didit 控制台中，人脸比对相似度分数受两个阈值控制（没有通过/审核/拒绝切换开关）：

| 设置 | 默认值 | 行为 |
| - | - | - |
| `face_match_score_review_threshold` | 70 | 当 `score` ≤ 该值时，触发 `LOW_FACE_MATCH_SIMILARITY`，状态变更为 `In Review`。 |
| `face_match_score_decline_threshold` | 50 | 当 `score` ≤ 该值时，同一警告将升级为 `error`，状态变更为 `Declined`。 |

如果您观察到过多误通过，可调高审核阈值；如果您观察到过多误拒绝，可调低拒绝阈值。

另一项独立设置用于控制当相似度分数**完全无法计算**时的情况：两张图像之一未检测到人脸，或者非证件查询未留下任何可供比对的参考照：

| 设置 | 默认值 | 行为 |
| - | - | - |
| `face_match_not_computed_action` | `REVIEW` | 当“无法计算”成为最终结果时执行的操作。`REVIEW` 将报告送入 `In Review`；`DECLINE` 则将其置为 `Declined`。（不存在自动通过选项 — 绝不会静默放行从未计算过分数的验证。） |

该操作控制 `FACE_MATCH_NOT_COMPUTED`（证件肖像中没有人脸，或非证件查询后完全没有参考照）以及用尽重试次数后的 `NO_FACE_IN_SELFIE`（用户重试后自拍照中仍没有人脸）。如果问题出在自拍照上，系统首先会要求用户重新拍摄 — 详见下文 — 只有在尝试次数额度用尽且仍然无法检测到人脸时，该操作才会生效。

低相似度失败在状态最终确定前也会进入重新拍摄重试循环：用户最多可获得 `face_match_max_attempts` 次总尝试机会（默认为 3 次，每个工作流节点可配置 2–5 次）以重新拍摄。`NO_FACE_IN_SELFIE` 失败使用相同的重试循环，因为重新拍摄一张更清晰的自拍照即可解决该问题。`FACE_MATCH_NOT_COMPUTED` 失败**不会**重试 — 在此步骤中无法重新拍摄证件肖像。只有当尝试额度用尽时，最后一次尝试的状态才会生效 — 并记录 `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`。

在独立的[人脸比对 API](https://docs.didit.me/zh/standalone-apis/face-match.md) 上仅存在拒绝阈值（`face_match_score_decline_threshold` 请求选项，默认 30）；触发的任何警告都会拒绝请求，而在完全无法比对人脸时会触发 `NO_REFERENCE_IMAGE`。

## 生成的警告

| 风险 | 原因 | 严重程度 | 是否影响状态？ | 补救措施 |
| - | - | - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | `score` ≤ `face_match_score_review_threshold`。当同时存在 `NO_REFERENCE_IMAGE` 时会被抑制。 | 介于阈值之间为 `warning`；达到或低于拒绝阈值时为 `error` | 介于阈值之间为 `In Review`；达到或低于拒绝阈值时为 `Declined` | 调整阈值，或通过人工审核接受。 |
| `FACE_MATCH_NOT_COMPUTED` | 无法计算相似度分数，原因是在**证件人像照**中未检测到人脸，或者证件步骤属于[无证件查询](https://docs.didit.me/zh/core-technology/id-verification/non-doc-lookup.md)且未留下可用于比对的参考基准（未返回人像照且未核验人脸的登记机构）。当同时存在 `NO_REFERENCE_IMAGE` 时会被抑制。 | 当 `face_match_not_computed_action` 为 `REVIEW` 时为 `warning`；当为 `DECLINE` 时为 `error` | 根据 `face_match_not_computed_action` 的设置，为 `In Review` 或 `Declined` | 在此步骤中无法重新采集证件图像：可通过人工审核解决，或在流程更早阶段重新采集证件。仅数据查询后，可将 `face_match_not_computed_action` 设置为您预期的结果，或者在需要生物识别匹配的国家/地区要求提供证件。 |
| `NO_FACE_IN_SELFIE` | 无法计算相似度分数，原因是在用户的**自拍照**中未检测到人脸。在此结果生效前，系统会提示用户重新拍摄自拍照。 | 当 `face_match_not_computed_action` 为 `REVIEW` 时为 `warning`；当为 `DECLINE` 时为 `error` | 重试次数用尽后，根据 `face_match_not_computed_action` 的设置，为 `In Review` 或 `Declined` | 用户重新采集光线充足、正面且更清晰的自拍照。 |
| `NO_REFERENCE_IMAGE` | 参考图像或目标图像缺失（无证件查询从未生成的参考图像除外，该情况属于 `FACE_MATCH_NOT_COMPUTED`）。 | `error` | **自动拒绝** | 确保同时采集了证件人像照和活体检测自拍照。对于独立 API，请传递两张有效的人脸图像。 |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | 在多次因相似度过低而失败后，用户用尽了采集重试额度（`face_match_max_attempts`）。 | `information` | 否 — 记录已应用最后一次尝试计算得出的状态（拒绝或审核） | 在工作流节点上调高 `face_match_max_attempts`，或通过人工审核解决。 |

## 示例

### In Review — 边缘相似度

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

### In Review — 无法计算人脸比对

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_NOT_COMPUTED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Face match could not be computed",
    "long_description": "A face match score could not be computed because a face could not be detected in the document portrait. Because the document image cannot be recaptured, the result follows the configured action for this case (manual review by default) rather than being treated as a low-similarity mismatch.",
    "node_id": "feature_face_match_1"
  }
]
```

### 自动拒绝 — 缺少参考图像

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "NO_REFERENCE_IMAGE",
    "additional_data": null,
    "log_type": "error",
    "short_description": "No source image found for performing face match",
    "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
    "node_id": "feature_face_match_1"
  }
]
```

### 重试次数已用尽 — 已应用最后一次尝试的状态

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "LOW_FACE_MATCH_SIMILARITY",
    "additional_data": null,
    "log_type": "error",
    "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_1"
  },
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_MAX_ATTEMPTS_EXCEEDED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Maximum face match attempts exceeded",
    "long_description": "The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.",
    "node_id": "feature_face_match_1"
  }
]
```

> [!NOTE]
>
> 独立[人脸比对 API](https://docs.didit.me/zh/standalone-apis/face-match.md)返回相同的警告结构，但没有 `node_id`（该比对未绑定到工作流节点）。

## 警告类型

根据您应用的配置，系统会为每项风险分配一个严重程度。共有三种严重程度：

## 相关内容

* [人脸比对报告](https://docs.didit.me/zh/core-technology/face-match/report-face-match.md) — 完整的报告架构和状态。
* [活体检测警告](https://docs.didit.me/zh/core-technology/liveness/warnings-liveness.md) — 自拍照采集的上游警告。
* [Webhook](https://docs.didit.me/zh/integration/webhooks.md) — 步骤完成后，`session.status.updated` 会立即携带相关警告。
* [数据模型 — 人脸比对](https://docs.didit.me/zh/reference/data-models.md#人脸比对) — 规范架构。
* [数据模型 — 警告对象](https://docs.didit.me/zh/reference/data-models.md#警告对象) — `warnings[]` 中每个条目的结构。


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