feat(insightface): add antispoofing (liveness) detection

Makefile

@@ -623,6 +623,11 @@ test-extra-backend-tinygrad-all: \
 FACE_IMAGE_1_URL ?= https://github.com/deepinsight/insightface/raw/master/python-package/insightface/data/images/t1.jpg
 FACE_IMAGE_2_URL ?= https://github.com/deepinsight/insightface/raw/master/python-package/insightface/data/images/t1.jpg
 FACE_IMAGE_3_URL ?= https://github.com/deepinsight/insightface/raw/master/python-package/insightface/data/images/mask_white.jpg
+## Known spoof fixture used by the face_antispoof e2e cap. This is
+## upstream's own `image_F2.jpg` (Silent-Face repo, via yakhyo mirror)
+## — verified to classify as is_real=false with score < 0.05 on the
+## MiniFASNetV2 + MiniFASNetV1SE ensemble.
+FACE_SPOOF_IMAGE_URL ?= https://github.com/yakhyo/face-anti-spoofing/raw/main/assets/image_F2.jpg
 
 ## Host-side cache for the OpenCV Zoo face ONNX files used by the
 ## opencv e2e target. The backend image no longer bakes model weights —
@@ -646,6 +651,15 @@ INSIGHTFACE_BUFFALO_SC_DIR := /tmp/localai-insightface-buffalo-sc-cache
 INSIGHTFACE_BUFFALO_SC_URL := https://github.com/deepinsight/insightface/releases/download/v0.7/buffalo_sc.zip
 INSIGHTFACE_BUFFALO_SC_SHA := 57d31b56b6ffa911c8a73cfc1707c73cab76efe7f13b675a05223bf42de47c72
 
+## Silent-Face antispoofing (MiniFASNetV2 + MiniFASNetV1SE) — shared
+## between the buffalo_sc and opencv e2e targets. Both ONNX files are
+## ~1.7MB, Apache 2.0. URLs + SHAs mirror the gallery entries.
+INSIGHTFACE_ANTISPOOF_DIR := /tmp/localai-insightface-antispoof-cache
+INSIGHTFACE_ANTISPOOF_V2_URL := https://github.com/yakhyo/face-anti-spoofing/releases/download/weights/MiniFASNetV2.onnx
+INSIGHTFACE_ANTISPOOF_V2_SHA := b32929adc2d9c34b9486f8c4c7bc97c1b69bc0ea9befefc380e4faae4e463907
+INSIGHTFACE_ANTISPOOF_V1SE_URL := https://github.com/yakhyo/face-anti-spoofing/releases/download/weights/MiniFASNetV1SE.onnx
+INSIGHTFACE_ANTISPOOF_V1SE_SHA := ebab7f90c7833fbccd46d3a555410e78d969db5438e169b6524be444862b3676
+
 .PHONY: insightface-opencv-models
 insightface-opencv-models:
 	@mkdir -p $(INSIGHTFACE_OPENCV_DIR)
@@ -660,6 +674,20 @@ insightface-opencv-models:
 		echo "$(INSIGHTFACE_OPENCV_SFACE_SHA)  $(INSIGHTFACE_OPENCV_DIR)/sface.onnx" | sha256sum -c; \
 	fi
 
+.PHONY: insightface-antispoof-models
+insightface-antispoof-models:
+	@mkdir -p $(INSIGHTFACE_ANTISPOOF_DIR)
+	@if [ "$$(sha256sum $(INSIGHTFACE_ANTISPOOF_DIR)/MiniFASNetV2.onnx 2>/dev/null | awk '{print $$1}')" != "$(INSIGHTFACE_ANTISPOOF_V2_SHA)" ]; then \
+		echo "Fetching MiniFASNetV2..."; \
+		curl -fsSL -o $(INSIGHTFACE_ANTISPOOF_DIR)/MiniFASNetV2.onnx $(INSIGHTFACE_ANTISPOOF_V2_URL); \
+		echo "$(INSIGHTFACE_ANTISPOOF_V2_SHA)  $(INSIGHTFACE_ANTISPOOF_DIR)/MiniFASNetV2.onnx" | sha256sum -c; \
+	fi
+	@if [ "$$(sha256sum $(INSIGHTFACE_ANTISPOOF_DIR)/MiniFASNetV1SE.onnx 2>/dev/null | awk '{print $$1}')" != "$(INSIGHTFACE_ANTISPOOF_V1SE_SHA)" ]; then \
+		echo "Fetching MiniFASNetV1SE..."; \
+		curl -fsSL -o $(INSIGHTFACE_ANTISPOOF_DIR)/MiniFASNetV1SE.onnx $(INSIGHTFACE_ANTISPOOF_V1SE_URL); \
+		echo "$(INSIGHTFACE_ANTISPOOF_V1SE_SHA)  $(INSIGHTFACE_ANTISPOOF_DIR)/MiniFASNetV1SE.onnx" | sha256sum -c; \
+	fi
+
 .PHONY: insightface-buffalo-sc-models
 insightface-buffalo-sc-models:
 	@mkdir -p $(INSIGHTFACE_BUFFALO_SC_DIR)
@@ -682,14 +710,15 @@ insightface-buffalo-sc-models:
 ## the e2e suite drives LoadModel directly without going through
 ## LocalAI's gallery flow (which is what would normally populate
 ## ModelPath and in turn the engine's `_model_dir` option).
-test-extra-backend-insightface-buffalo-sc: docker-build-insightface insightface-buffalo-sc-models
+test-extra-backend-insightface-buffalo-sc: docker-build-insightface insightface-buffalo-sc-models insightface-antispoof-models
 	BACKEND_IMAGE=local-ai-backend:insightface \
 	BACKEND_TEST_MODEL_NAME=insightface-buffalo-sc \
-	BACKEND_TEST_OPTIONS=engine:insightface,model_pack:buffalo_sc,root:$(INSIGHTFACE_BUFFALO_SC_DIR) \
-	BACKEND_TEST_CAPS=health,load,face_detect,face_embed,face_verify \
+	BACKEND_TEST_OPTIONS=engine:insightface,model_pack:buffalo_sc,root:$(INSIGHTFACE_BUFFALO_SC_DIR),antispoof_v2_onnx:$(INSIGHTFACE_ANTISPOOF_DIR)/MiniFASNetV2.onnx,antispoof_v1se_onnx:$(INSIGHTFACE_ANTISPOOF_DIR)/MiniFASNetV1SE.onnx \
+	BACKEND_TEST_CAPS=health,load,face_detect,face_embed,face_verify,face_antispoof \
 	BACKEND_TEST_FACE_IMAGE_1_URL=$(FACE_IMAGE_1_URL) \
 	BACKEND_TEST_FACE_IMAGE_2_URL=$(FACE_IMAGE_2_URL) \
 	BACKEND_TEST_FACE_IMAGE_3_URL=$(FACE_IMAGE_3_URL) \
+	BACKEND_TEST_FACE_SPOOF_IMAGE_URL=$(FACE_SPOOF_IMAGE_URL) \
 	BACKEND_TEST_VERIFY_DISTANCE_CEILING=0.55 \
 	$(MAKE) test-extra-backend
 
@@ -698,14 +727,15 @@ test-extra-backend-insightface-buffalo-sc: docker-build-insightface insightface-
 ## pre-fetched on the host via the insightface-opencv-models target and
 ## passed as absolute paths, since the e2e suite drives LoadModel
 ## directly without going through LocalAI's gallery flow.
-test-extra-backend-insightface-opencv: docker-build-insightface insightface-opencv-models
+test-extra-backend-insightface-opencv: docker-build-insightface insightface-opencv-models insightface-antispoof-models
 	BACKEND_IMAGE=local-ai-backend:insightface \
 	BACKEND_TEST_MODEL_NAME=insightface-opencv \
-	BACKEND_TEST_OPTIONS=engine:onnx_direct,detector_onnx:$(INSIGHTFACE_OPENCV_DIR)/yunet.onnx,recognizer_onnx:$(INSIGHTFACE_OPENCV_DIR)/sface.onnx \
-	BACKEND_TEST_CAPS=health,load,face_detect,face_embed,face_verify \
+	BACKEND_TEST_OPTIONS=engine:onnx_direct,detector_onnx:$(INSIGHTFACE_OPENCV_DIR)/yunet.onnx,recognizer_onnx:$(INSIGHTFACE_OPENCV_DIR)/sface.onnx,antispoof_v2_onnx:$(INSIGHTFACE_ANTISPOOF_DIR)/MiniFASNetV2.onnx,antispoof_v1se_onnx:$(INSIGHTFACE_ANTISPOOF_DIR)/MiniFASNetV1SE.onnx \
+	BACKEND_TEST_CAPS=health,load,face_detect,face_embed,face_verify,face_antispoof \
 	BACKEND_TEST_FACE_IMAGE_1_URL=$(FACE_IMAGE_1_URL) \
 	BACKEND_TEST_FACE_IMAGE_2_URL=$(FACE_IMAGE_2_URL) \
 	BACKEND_TEST_FACE_IMAGE_3_URL=$(FACE_IMAGE_3_URL) \
+	BACKEND_TEST_FACE_SPOOF_IMAGE_URL=$(FACE_SPOOF_IMAGE_URL) \
 	BACKEND_TEST_VERIFY_DISTANCE_CEILING=0.55 \
 	$(MAKE) test-extra-backend
 

backend/backend.proto

@@ -493,7 +493,7 @@ message FaceVerifyRequest {
   string img1 = 1;              // base64-encoded image
   string img2 = 2;              // base64-encoded image
   float  threshold = 3;         // cosine-distance threshold; 0 = use backend default
-  bool   anti_spoofing = 4;     // reserved for future MiniFASNet bolt-on
+  bool   anti_spoofing = 4;     // run MiniFASNet liveness on each image; failed liveness forces verified=false
 }
 
 message FaceVerifyResponse {
@@ -505,6 +505,10 @@ message FaceVerifyResponse {
   FacialArea img1_area = 6;
   FacialArea img2_area = 7;
   float      processing_time_ms = 8;
+  bool       img1_is_real = 9;          // anti-spoofing result when enabled
+  float      img1_antispoof_score = 10;
+  bool       img2_is_real = 11;
+  float      img2_antispoof_score = 12;
 }
 
 message FaceAnalyzeRequest {

backend/python/insightface/Makefile

@@ -11,3 +11,6 @@ protogen-clean:
 .PHONY: clean
 clean: protogen-clean
 	rm -rf venv __pycache__
+
+test: install
+	bash test.sh

backend/python/insightface/backend.py

@@ -180,23 +180,57 @@ def FaceVerify(self, request, context):
         verified = distance < threshold
         confidence = max(0.0, min(100.0, (1.0 - distance / threshold) * 100.0)) if threshold > 0 else 0.0
 
-        def _region(img) -> backend_pb2.FacialArea:
+        # Detect once per image — region is needed for the response and
+        # potentially for the antispoof crop. Returns the highest-score face.
+        def _best_detection(img):
             dets = self.engine.detect(img)
             if not dets:
+                return None
+            return max(dets, key=lambda d: d.score)
+
+        def _region(det) -> backend_pb2.FacialArea:
+            if det is None:
                 return backend_pb2.FacialArea()
-            best = max(dets, key=lambda d: d.score)
-            x1, y1, x2, y2 = best.bbox
+            x1, y1, x2, y2 = det.bbox
             return backend_pb2.FacialArea(x=x1, y=y1, w=x2 - x1, h=y2 - y1)
 
+        det1 = _best_detection(img1)
+        det2 = _best_detection(img2)
+
+        img1_is_real = False
+        img1_score = 0.0
+        img2_is_real = False
+        img2_score = 0.0
+        if request.anti_spoofing:
+            spoof1 = self.engine.antispoof(img1, det1.bbox) if det1 is not None else None
+            spoof2 = self.engine.antispoof(img2, det2.bbox) if det2 is not None else None
+            if spoof1 is None or spoof2 is None:
+                context.set_code(grpc.StatusCode.FAILED_PRECONDITION)
+                context.set_details(
+                    "anti_spoofing requested but no antispoof model is loaded — "
+                    "install `silent-face-antispoofing` or pick a gallery entry "
+                    "that bundles MiniFASNet weights"
+                )
+                return backend_pb2.FaceVerifyResponse()
+            img1_is_real, img1_score = spoof1.is_real, spoof1.score
+            img2_is_real, img2_score = spoof2.is_real, spoof2.score
+            # Failed liveness vetoes verification regardless of similarity.
+            if not (img1_is_real and img2_is_real):
+                verified = False
+
         return backend_pb2.FaceVerifyResponse(
             verified=verified,
             distance=float(distance),
             threshold=float(threshold),
             confidence=float(confidence),
             model=self.model_name or self.engine_name,
-            img1_area=_region(img1),
-            img2_area=_region(img2),
+            img1_area=_region(det1),
+            img2_area=_region(det2),
             processing_time_ms=float((time.time() - start) * 1000.0),
+            img1_is_real=img1_is_real,
+            img1_antispoof_score=float(img1_score),
+            img2_is_real=img2_is_real,
+            img2_antispoof_score=float(img2_score),
         )
 
     def FaceAnalyze(self, request, context):
@@ -223,6 +257,19 @@ def FaceAnalyze(self, request, context):
                 fa.dominant_gender = attrs.dominant_gender
             for k, v in attrs.gender.items():
                 fa.gender[k] = float(v)
+            if request.anti_spoofing:
+                bbox = (float(x), float(y), float(x + w), float(y + h))
+                spoof = self.engine.antispoof(img, bbox)
+                if spoof is None:
+                    context.set_code(grpc.StatusCode.FAILED_PRECONDITION)
+                    context.set_details(
+                        "anti_spoofing requested but no antispoof model is loaded — "
+                        "install `silent-face-antispoofing` or pick a gallery entry "
+                        "that bundles MiniFASNet weights"
+                    )
+                    return backend_pb2.FaceAnalyzeResponse()
+                fa.is_real = spoof.is_real
+                fa.antispoof_score = float(spoof.score)
             faces.append(fa)
         return backend_pb2.FaceAnalyzeResponse(faces=faces)
 

backend/python/insightface/engines.py

@@ -41,13 +41,134 @@ class FaceAttributes:
     gender: dict[str, float] = field(default_factory=dict)
 
 
+@dataclass
+class SpoofResult:
+    is_real: bool
+    score: float  # averaged probability of the "real" class, 0.0-1.0
+
+
 class FaceEngine(Protocol):
     """Minimal interface every engine must implement."""
 
     def prepare(self, options: dict[str, str]) -> None: ...
     def detect(self, img: np.ndarray) -> list[FaceDetection]: ...
     def embed(self, img: np.ndarray) -> np.ndarray | None: ...
     def analyze(self, img: np.ndarray) -> list[FaceAttributes]: ...
+    # Optional: returns None when no antispoof model is loaded.
+    def antispoof(self, img: np.ndarray, bbox: tuple[float, float, float, float]) -> SpoofResult | None: ...
+
+
+# ─── Antispoofer (Silent-Face MiniFASNet) ──────────────────────────────
+
+class Antispoofer:
+    """Liveness detector using the Silent-Face MiniFASNet ensemble.
+
+    Loads up to two ONNX exports (MiniFASNetV2 at scale 2.7 and
+    MiniFASNetV1SE at scale 4.0). Both are 80x80 BGR-float32-input
+    classifiers with 3 output logits where index 1 = "real". When both
+    are loaded, softmax outputs are averaged before argmax — the same
+    ensembling the upstream `test.py` does.
+
+    Preprocessing matches yakhyo/face-anti-spoofing's reference impl:
+    each model gets its own scale-expanded crop centered on the face
+    bbox, resized to 80x80, fed straight as float32 BGR (no /255, no
+    mean/std). See `_crop_face` for the bbox math.
+
+    A single model also works (the missing one is simply skipped).
+    """
+
+    INPUT_SIZE = (80, 80)  # h, w
+    REAL_CLASS_IDX = 1
+
+    def __init__(self) -> None:
+        self._sessions: list[tuple[Any, float, str, str]] = []  # (session, scale, input_name, output_name)
+        self.threshold: float = 0.5
+
+    def load(self, model_paths: list[tuple[str, float]], threshold: float = 0.5) -> None:
+        """Load one or more (path, scale) pairs."""
+        import onnxruntime as ort
+
+        providers = ["CUDAExecutionProvider", "CPUExecutionProvider"]
+        for path, scale in model_paths:
+            session = ort.InferenceSession(path, providers=providers)
+            input_name = session.get_inputs()[0].name
+            output_name = session.get_outputs()[0].name
+            self._sessions.append((session, float(scale), input_name, output_name))
+        self.threshold = float(threshold)
+
+    @property
+    def loaded(self) -> bool:
+        return bool(self._sessions)
+
+    def _crop_face(self, img: np.ndarray, bbox: tuple[float, float, float, float], scale: float) -> np.ndarray:
+        # bbox is (x1, y1, x2, y2) in source-image coordinates.
+        src_h, src_w = img.shape[:2]
+        x1, y1, x2, y2 = bbox
+        box_w = max(1.0, x2 - x1)
+        box_h = max(1.0, y2 - y1)
+
+        # Clamp scale so the expanded crop fits inside the source image.
+        scale = min((src_h - 1) / box_h, (src_w - 1) / box_w, scale)
+        new_w = box_w * scale
+        new_h = box_h * scale
+
+        cx = x1 + box_w / 2.0
+        cy = y1 + box_h / 2.0
+
+        cx1 = max(0, int(cx - new_w / 2.0))
+        cy1 = max(0, int(cy - new_h / 2.0))
+        cx2 = min(src_w - 1, int(cx + new_w / 2.0))
+        cy2 = min(src_h - 1, int(cy + new_h / 2.0))
+
+        cropped = img[cy1 : cy2 + 1, cx1 : cx2 + 1]
+        if cropped.size == 0:
+            cropped = img
+        out_h, out_w = self.INPUT_SIZE
+        return cv2.resize(cropped, (out_w, out_h))
+
+    @staticmethod
+    def _softmax(x: np.ndarray) -> np.ndarray:
+        e = np.exp(x - np.max(x, axis=1, keepdims=True))
+        return e / e.sum(axis=1, keepdims=True)
+
+    def predict(self, img: np.ndarray, bbox: tuple[float, float, float, float]) -> SpoofResult:
+        if not self._sessions:
+            raise RuntimeError("Antispoofer.predict called with no models loaded")
+        accum = np.zeros((1, 3), dtype=np.float32)
+        for session, scale, input_name, output_name in self._sessions:
+            face = self._crop_face(img, bbox, scale).astype(np.float32)
+            tensor = np.transpose(face, (2, 0, 1))[np.newaxis, ...]
+            logits = session.run([output_name], {input_name: tensor})[0]
+            accum += self._softmax(logits)
+        accum /= float(len(self._sessions))
+        real_prob = float(accum[0, self.REAL_CLASS_IDX])
+        is_real = int(np.argmax(accum)) == self.REAL_CLASS_IDX and real_prob >= self.threshold
+        return SpoofResult(is_real=is_real, score=real_prob)
+
+
+def _build_antispoofer(options: dict[str, str], model_dir: str | None) -> Antispoofer | None:
+    """Instantiate an Antispoofer from option keys, or return None.
+
+    Recognised options:
+        antispoof_v2_onnx     — path/filename of MiniFASNetV2 (scale 2.7)
+        antispoof_v1se_onnx   — path/filename of MiniFASNetV1SE (scale 4.0)
+        antispoof_threshold   — real-class probability threshold, default 0.5
+
+    Either or both can be provided. Returns None when neither is set.
+    """
+    pairs: list[tuple[str, float]] = []
+    v2 = options.get("antispoof_v2_onnx", "")
+    if v2:
+        pairs.append((_resolve_model_path(v2, model_dir=model_dir), 2.7))
+    v1se = options.get("antispoof_v1se_onnx", "")
+    if v1se:
+        pairs.append((_resolve_model_path(v1se, model_dir=model_dir), 4.0))
+    if not pairs:
+        return None
+    threshold = float(options.get("antispoof_threshold", "0.5"))
+    spoofer = Antispoofer()
+    spoofer.load(pairs, threshold=threshold)
+    return spoofer
 
 
 # ─── InsightFaceEngine ────────────────────────────────────────────────
@@ -80,6 +201,7 @@ def __init__(self) -> None:
         self.det_size: tuple[int, int] = (640, 640)
         self.det_thresh: float = 0.5
         self._providers: list[str] = ["CPUExecutionProvider"]
+        self._antispoofer: Antispoofer | None = None
 
     def prepare(self, options: dict[str, str]) -> None:
         import glob
@@ -90,6 +212,7 @@ def prepare(self, options: dict[str, str]) -> None:
         self.model_pack = options.get("model_pack", "buffalo_l")
         self.det_size = _parse_det_size(options.get("det_size", "640x640"))
         self.det_thresh = float(options.get("det_thresh", "0.5"))
+        self._antispoofer = _build_antispoofer(options, options.get("_model_dir"))
 
         pack_dir = _locate_insightface_pack(options, self.model_pack)
         if pack_dir is None:
@@ -187,6 +310,11 @@ def analyze(self, img: np.ndarray) -> list[FaceAttributes]:
             out.append(attrs)
         return out
 
+    def antispoof(self, img: np.ndarray, bbox: tuple[float, float, float, float]) -> SpoofResult | None:
+        if self._antispoofer is None or not self._antispoofer.loaded:
+            return None
+        return self._antispoofer.predict(img, bbox)
+
 
 # ─── OnnxDirectEngine ─────────────────────────────────────────────────
 
@@ -206,6 +334,7 @@ def __init__(self) -> None:
         self.det_thresh: float = 0.5
         self._detector: Any = None
         self._recognizer: Any = None
+        self._antispoofer: Antispoofer | None = None
 
     def prepare(self, options: dict[str, str]) -> None:
         raw_det = options.get("detector_onnx", "")
@@ -219,6 +348,7 @@ def prepare(self, options: dict[str, str]) -> None:
         self.recognizer_path = _resolve_model_path(raw_rec, model_dir=model_dir)
         self.input_size = _parse_det_size(options.get("det_size", "320x320"))
         self.det_thresh = float(options.get("det_thresh", "0.5"))
+        self._antispoofer = _build_antispoofer(options, model_dir)
 
         # YuNet is a fixed-size detector; size is reset per detect() call to
         # match the input frame.
@@ -286,6 +416,11 @@ def analyze(self, img: np.ndarray) -> list[FaceAttributes]:
             for d in self.detect(img)
         ]
 
+    def antispoof(self, img: np.ndarray, bbox: tuple[float, float, float, float]) -> SpoofResult | None:
+        if self._antispoofer is None or not self._antispoofer.loaded:
+            return None
+        return self._antispoofer.predict(img, bbox)
+
 
 # ─── helpers ──────────────────────────────────────────────────────────