Activar la detección RGB de presencia real en Python e InsightFace Server
Añade comprobaciones antes del reconocimiento y recibe estados y puntuaciones por rostro. Configura el reconocimiento condicionado al resultado de vida o el modo de observación para los flujos de detección, comparación, búsqueda y RTSP.
Qué vas a construir
Usa FaceAnalysis para rostros o PersonAnalysis para combinar detección de personas, comparación facial y ReID corporal.
Desactivada de forma predeterminada. Las comprobaciones de registro tienen un ajuste independiente.
Antes de empezar
- El código fuente actualizado de InsightFace 2 con python-package/docs/liveness.md, Python 3.10+ y las dependencias del paquete instaladas. Esta guía se refiere a esa versión del código; un paquete antiguo puede no ofrecer la API del complemento.
- Un archivo local input.jpg con un rostro y suficiente imagen a su alrededor, y acceso para instalar el modelo base y el complemento de liveness. Respete las condiciones de cada modelo.
- Usa el despliegue de la guía Docker y su configuración existente. Los contenedores ya usan root y directorios de modelos y configuración escribibles. La CLI permite activar la función antes del primer inicio.
1. Activar explícitamente la comprobación en Python
Desde la raíz del repositorio actualizado, instale el paquete Python en su entorno virtual activo. Coloque input.jpg en el directorio de trabajo antes de ejecutar el ejemplo. El ejemplo para CPU selecciona detección y reconocimiento; addons=['liveness'] activa el modelo independiente de liveness.
La primera ejecución puede descargar los modelos que falten. El complemento se guarda en ~/.insightface/addons/liveness.onnx y se comprueba su SHA-256 antes de cargarlo. Instalar el archivo no lo activa: especifique addons=['liveness']. Si omite addons, la comprobación permanece desactivada.
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. Interpretar los resultados y elegir la política de reconocimiento
En modo normal, solo se reconoce cuando is_live es True. Los demás rostros permanecen en la lista con sus detecciones, pero sin embedding. En modo observe, el reconocimiento continúa ante una clasificación negativa o una entrada rechazada, conservando el resultado. Los fallos de modelo, alineación o inferencia generan excepciones en ambos modos.
- status='ok': is_live es True o False y live_score es un número en [0, 1]. El umbral predeterminado es 0.8; la igualdad también permite pasar. Valide el umbral con entradas representativas y el proveedor de ejecución de su despliegue.
- status='input_rejected': is_live y live_score son None. Indica que falta área de la imagen original alrededor del rostro alineado, no una clasificación de suplantación. Centre el rostro, aléjese de la cámara o use una imagen menos recortada. reason explica el problema.
- face.liveness es None si no se seleccionó el complemento; si no se detectan rostros, se devuelve []. Use status e is_live en la lógica. El texto reason de Python/API está en inglés y no debe interpretarse como un código de estado estable.
Opcional: activar la detección de vida RGB
Sí. Añade --enable-liveness al instalar el modelo o actívala desde Sistema en la Web UI, y después inicia o reinicia Server. normal controla el reconocimiento; observe registra resultados y lo continúa. Está desactivada por defecto y el registro tiene su propio interruptor.
En una instalación nueva, añade --enable-liveness al comando de instalación del modelo de la guía Docker. Verifica los modelos necesarios y guarda la activación antes del primer inicio.
Para un servicio en ejecución, usa el comando correspondiente de abajo y reinícialo después. La instalación normal y models addons install liveness no activan la función.
También puedes usar Sistema → Detección de vida y descargar con activación tras reiniciar. Web y CLI verifican el modelo y añaden liveness a ambas listas conservando los demás ajustes. Una descarga fallida no activa la función; espera a que la configuración se guarde.
Inicia un despliegue nuevo tras la instalación; reinicia uno existente con el comando CPU/CUDA correspondiente. Confirma enabled=true y restart_required=false. installed describe el archivo verificado y configured_enabled el ajuste guardado. Cambiar montajes requiere recrear el contenedor.
Liveness está desactivado por defecto. La acción web no cambia el registro: liveness_on_registration=false sigue siendo el valor predeterminado. Cámbielo por separado a true para aplicar normal/observe durante el registro. Para desactivar liveness, guarde listas vacías en inference.addons y addons.auto_download y reinicie.
docker compose -f server/deploy/compose.cpu.yml run --rm models install buffalo_l --accept-license --enable-livenessdocker compose -f server/deploy/compose.cuda12.yml run --rm models install buffalo_l --accept-license --enable-livenessdocker compose -f server/deploy/compose.cpu.yml restart serverdocker compose -f server/deploy/compose.cuda12.yml restart server¿Necesitas ayuda con el despliegue en producción?
Contacta con InsightFace para licencias de modelos, optimización de runtime y soporte de despliegue en tu hardware objetivo.
Enviar consulta empresarial