> ## 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.

# 人脸搜索 1:N 警告与错误代码

> Didit 人脸搜索 1:N 警告代码详解：涵盖黑名单匹配、重复人脸、检测到多张人脸，以及拒绝未检测到人脸图像的前置拦截机制。

## 概述

人脸搜索会生成一组精简的警告，以便您的团队了解搜索返回 `Approved` 或 `Declined` 的**原因**。警告会在 `POST /v3/face-search/` 响应的 `face_search.warnings[]` 数组中返回（参见[人脸搜索报告](https://docs.didit.me/zh/core-technology/face-search/report-face-search.md)）。

与工作流警告相比，此处的警告采用了**精简结构**：其中不包含 `node_id`。文档中定义的响应规范声明了五个字段：`risk`、`additional_data`、`log_type`、`short_description`、`long_description`，在运行时 payload 中还会额外携带 `feature` 字段，该字段在此 endpoint 上始终为 `"LIVENESS"`。

## 生成的警告

| 风险 | 原因 | 严重程度 (`log_type`) | 影响状态 | 建议处理方式 |
| - | - | - | - | - |
| `FACE_IN_BLOCKLIST` | 搜索图片与您应用人脸黑名单中的某张人脸匹配，相似度高于高置信度区间。 | `error` | 强制设为 `Declined`。 | 拒绝该用户。通过 `additional_data.blocklisted_session_id` 排查关联会话。 |
| `POSSIBLE_FACE_IN_BLOCKLIST` | 命中黑名单人脸，相似度落在较低的“疑似”区间，低于高置信度区间。 | `error` | 在独立人脸搜索 API 上强制设为 `Declined`（比工作流活体检测更严格，工作流会将此风险转入审核）。 | 人工审核。在采取行动前，对照原始黑名单证据核实命中情况。 |
| `MULTIPLE_FACES_DETECTED` | 提交的搜索图片中检测到多张人脸。搜索仍会执行，并使用检测到的最大人脸。 | `warning` | 无：本身绝不会导致拒绝。 | 如果最大的人脸不是目标人脸，请在画面中仅有一名主体的情况下重新采集。 |
| `DUPLICATED_FACE` | 人脸与来自**已通过**会话的人脸或导入的用户画像人脸匹配，相似度高于高置信度区间。独立 endpoint 不会排除相同 `vendor_data` 的会话，因此回流用户会与其自身早期的会话匹配。 | `information` | 无：重复人脸仅作为信号呈现，不会导致拒绝。 | 通过 `additional_data.duplicated_session_id` 排查关联会话。由您自行决定是在自身系统中封禁还是合并账号。 |
| `POSSIBLE_DUPLICATED_FACE` | 与 `DUPLICATED_FACE` 相同，但相似度位于较低的“疑似”区间，而非高置信度区间。 | `information` | 无。 | 在将两条记录视为同一人之前，先进行人工审核。 |

生成来源：`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`（但绝不会清除黑名单警告）。

### 警告文本明细

| 风险 | `short_description` | `long_description` |
| - | - | - |
| `FACE_IN_BLOCKLIST` | 黑名单中的人脸 | 系统在黑名单中识别出该人脸，这意味着该人脸不允许通过验证。 |
| `POSSIBLE_FACE_IN_BLOCKLIST` | 疑似黑名单中的人脸 | 系统在黑名单中识别出疑似人脸，这意味着该人脸不允许通过验证。 |
| `DUPLICATED_FACE` | 来自其他已通过会话的重复人脸 | 系统识别出来自另一个已通过会话的重复人脸，需要进一步调查。 |
| `POSSIBLE_DUPLICATED_FACE` | 来自其他已通过会话的疑似重复人脸 | 系统识别出来自另一个已通过会话的疑似重复人脸，需要进一步调查。 |
| `MULTIPLE_FACES_DETECTED` | 检测到多张人脸 | 在活体图片中检测到多张人脸。系统会使用最大的人脸进行活体检测和人脸比对，但出现多张人脸可能需要额外审核。 |

### 搜索图片校验拦截

当 `user_image` 中未检测到人脸时，API 会在构建 `face_search` 对象**之前**直接拒绝该请求，并返回 HTTP `400` 以及 `{"error": "No face detected in the image"}`，因此成功的人脸搜索响应中绝不会出现 `NO_FACE_DETECTED` 警告。该信息作为顶层 `error` 字符串返回，而非包含在 `warnings[]` 中。

## 可配置项设置

区分确认命中（`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`）

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

### 重复信号（状态保持为 `Approved`）

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

## 相关内容

* [人脸搜索报告](https://docs.didit.me/zh/core-technology/face-search/report-face-search.md) — 完整响应结构
* [人脸搜索 API 参考](https://docs.didit.me/zh/standalone-apis/face-search.md) — 请求参数
* [人脸比对警告](https://docs.didit.me/zh/core-technology/id-verification/warnings-id-verification.md) — 1:1 自拍照与证件比对警告（独立于人脸搜索）
* [数据模型 — 人脸搜索](https://docs.didit.me/zh/reference/data-models.md#人脸搜索) — 权威架构

### 警告类型


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