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

概述

人脸搜索会生成一组精简的警告，以便您的团队了解搜索返回 Approved 或 Declined 的原因。警告会在 POST /v3/face-search/ 响应的 face_search.warnings[] 数组中返回（参见人脸搜索报告）。与工作流警告相比，此处的警告采用了精简结构：其中不包含 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`）

{
  "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`）

{
  "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."
    }
  ]
}

身份认证

验证

监控

平台

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

概述

生成的警告

警告文本明细

搜索图片校验拦截

可配置项设置

示例

黑名单命中（强制为 `Declined`）

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

相关内容

警告类型

​概述

​生成的警告

​警告文本明细

​搜索图片校验拦截

​可配置项设置

​示例

​黑名单命中（强制为 Declined）

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

​相关内容

​警告类型

概述

生成的警告

警告文本明细

搜索图片校验拦截

可配置项设置

示例

黑名单命中（强制为 `Declined`）

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

相关内容

警告类型