在 Python 与 InsightFace Server 中启用可选 RGB 活体检测
在识别前执行检查，并获取逐脸状态与评分。可在检测、比对、搜索和 RTSP 流程中根据活体结果控制是否继续识别，也可选择观察模式。
你将完成什么
使用 Python 进行人脸分析，支持识别前的可选 RGB 活体检测，并返回逐脸结果。
默认关闭。注册时的活体检查单独设置。
开始之前
- 准备包含 python-package/docs/liveness.md 的新版 InsightFace 2 源码目录，并安装 Python 3.10 或更高版本及包依赖。本指南面向该源码版本；旧版已安装包可能没有插件 API。
- 准备本地 input.jpg，保留人脸周围的图像区域，并具备安装基础模型与活体插件所需的访问条件。使用时遵循各模型附带的条款。
- Server：已运行更新后的 Linux 部署并安装基础模型。Web 安装要求 Server 用户（Compose 中为 UID/GID 10001）可写入挂载的 addons 目录及整个配置目录。
1. 在 Python 中明确启用活体检测
从更新后的仓库根目录，将 Python 包安装到已激活的虚拟环境中。运行示例前，将 input.jpg 放在当前工作目录。CPU 示例选择检测与识别，通过 addons=['liveness'] 启用独立的活体模型。
首次运行可能下载缺失的模型。插件保存在 ~/.insightface/addons/liveness.onnx，加载前会校验 SHA-256。仅安装文件不会启用活体检测，仍需明确设置 addons=['liveness']；省略 addons 时保持关闭。
cd python-package
python -m pip install .import cv2
from insightface.app import FaceAnalysis
image_bgr = cv2.imread("input.jpg")
if image_bgr is None:
raise FileNotFoundError("input.jpg")
app = FaceAnalysis(
name="buffalo_l",
allowed_modules=["detection", "recognition"],
addons=["liveness"],
liveness_mode="normal",
liveness_threshold=0.8,
providers=["CPUExecutionProvider"],
)
app.prepare(ctx_id=-1, det_size=(640, 640))
for face in app.get(image_bgr):
print(face.liveness)
if face.liveness is not None:
print(
face.liveness.status,
face.liveness.is_live,
face.liveness.live_score,
)2. 读取结果并选择识别策略
normal 模式仅在 is_live 为 True 时进行识别；其他人脸仍保留在返回列表中，带有检测结果，但没有 embedding。observe 模式保留活体结果，并继续识别判为非活体或输入被拒绝的人脸。两种模式下，模型、对齐或推理故障都会抛出异常。
- status='ok'：is_live 为 True 或 False，live_score 是 [0, 1] 范围内的数值。默认阈值为 0.8，等于阈值时通过。应在实际部署的执行提供程序上，用有代表性的输入验证阈值。
- status='input_rejected'：is_live 与 live_score 均为 None。这表示对齐人脸周围的原始图像区域不足，不是伪造判定。请将人脸移向画面中心、后退或使用裁剪不那么紧的图像；reason 会说明原因。
- 未选择插件时，face.liveness 为 None；未检测到人脸时返回 []。程序判断应使用 status 和 is_live。Python/API 的 reason 文本为英文，不应将其作为固定状态码解析。
3. 在 Server 中安装、重启并确认生效
支持。可通过 Server Web UI 安装并启用可选的 RGB 活体检测插件。常规模式根据活体结果决定是否继续识别；观察模式在返回活体结果的同时继续识别。活体检测默认关闭，注册流程有独立开关。设置与结果解读请参阅活体检测指南。
打开“系统 → 活体检测”，选择“下载并在重启后启用”。操作会下载发布的插件（或复用已验证的缓存），校验 SHA-256，并在 inference.addons 和 addons.auto_download 中保存 ['liveness']。等待安装与配置保存成功后再重启。
从仓库根目录执行重启命令；CUDA 部署使用 compose.cuda12.yml。在系统页确认 enabled 为 true、restart_required 为 false。installed 表示文件已验证，configured_enabled 表示下次启动的保存设置，单独看到其中任一状态都不能确认当前推理已启用。修改挂载需要重建容器。
活体检测默认关闭。Web 操作不会更改注册设置，liveness_on_registration=false 仍为默认值。如需在注册时应用已配置的 normal/observe 策略，应单独将其设为 true。停用时，将 inference.addons 与 addons.auto_download 均保存为空列表，再重启。
docker compose -f server/deploy/compose.cpu.yml restart server