Download backend/core/models.py from StillWorking/sentinel-face-recognition: direct link, hf CLI and curl.
- Browser
- Download file 17.1 kB
-
https://huggingface.co/StillWorking/sentinel-face-recognition/resolve/main/backend/core/models.py
- Command line
-
hf download hf://StillWorking/sentinel-face-recognition/backend/core/models.py
-
curl -L -o models.py https://huggingface.co/StillWorking/sentinel-face-recognition/resolve/main/backend/core/models.py
17.1 kB
| """ | |
| core/models.py β Sentinel-AI | |
| =============================== | |
| Singleton loaders for the local PyTorch models: | |
| * MTCNN β face detection + 5-point alignment (vendored with AdaFace) | |
| * AdaFace IR-50 β face embedding (512-D output, FP16 on CUDA) | |
| RF-DETR is kept as an optional, explicitly opt-in detector for backwards | |
| compatibility. It is *not* used by default: ``RFDETRSmall`` is a COCO object | |
| detector (90 everyday classes, no "face" class) and was being asked to do face | |
| detection, which produced labels such as "bicycle" and "boat" for human faces. | |
| The AdaFace repository in ``models_cache/adaface`` already ships the MTCNN | |
| weights, so no extra download is required. | |
| Both heavy models are module-level singletons: loaded once at startup and | |
| reused across every request. | |
| """ | |
| from __future__ import annotations | |
| import os | |
| import sys | |
| from pathlib import Path | |
| from typing import Optional | |
| import numpy as np | |
| import torch | |
| import torch.nn as nn | |
| from core.paths import env_float, env_int, resolve_path | |
| # ββ Lazy import guard for RF-DETR (optional) βββββββββββββββββββββββββββββββββ | |
| try: | |
| from rfdetr import RFDETRSmall # type: ignore | |
| _RFDETR_AVAILABLE = True | |
| except ImportError: | |
| _RFDETR_AVAILABLE = False | |
| # ββ AdaFace + MTCNN live in the vendored repository ββββββββββββββββββββββββββ | |
| # models.py is at backend/core/models.py, so parent.parent == backend/ | |
| _ADAFACE_REPO = Path(__file__).resolve().parent.parent / "models_cache" / "adaface" | |
| if _ADAFACE_REPO.exists() and str(_ADAFACE_REPO) not in sys.path: | |
| sys.path.insert(0, str(_ADAFACE_REPO)) | |
| try: | |
| import net as adaface_net # type: ignore | |
| _ADAFACE_AVAILABLE = True | |
| except ImportError: | |
| _ADAFACE_AVAILABLE = False | |
| try: | |
| from face_alignment import mtcnn as _mtcnn # type: ignore | |
| _MTCNN_AVAILABLE = True | |
| except Exception: # pragma: no cover | |
| _MTCNN_AVAILABLE = False | |
| DEVICE = os.getenv("TORCH_DEVICE", "cuda") if torch.cuda.is_available() else "cpu" | |
| if os.getenv("TORCH_DEVICE", "cuda").lower() == "cpu": | |
| DEVICE = "cpu" | |
| ADAFACE_WEIGHTS = resolve_path( | |
| os.getenv("ADAFACE_WEIGHTS"), | |
| "./models_cache/adaface_ir50_ms1mv2.ckpt", | |
| ) | |
| # A face crop must include some hair / shoulder context so that it resembles | |
| # the CelebA framing the FAISS index was built from. 1.5 was measured on the | |
| # bundled dataset (see SENTINEL_FIX_LOG.md). | |
| FACE_CROP_MARGIN = env_float("FACE_CROP_MARGIN", 1.5) | |
| # MTCNN missed ~1% of CelebA samples at the default settings. If the first | |
| # pass finds nothing, retry once with a smaller minimum size and lower | |
| # detection thresholds. Downstream identity matching (cosine similarity) | |
| # still rejects the extra low-confidence detections that are not real matches. | |
| MTCNN_RETRY_MIN_FACE_SIZE = env_int("MTCNN_RETRY_MIN_FACE_SIZE", 12) | |
| MTCNN_RETRY_CONFIDENCE = env_float("MTCNN_RETRY_CONFIDENCE", 0.45) | |
| # ββ Module-level singletons βββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| _detector: Optional[nn.Module] = None | |
| _embedder: Optional[nn.Module] = None | |
| _face_detector = None | |
| def detector_ready() -> bool: | |
| """True once the MTCNN detector has been loaded.""" | |
| return _face_detector is not None | |
| def embedder_ready() -> bool: | |
| """True once the AdaFace embedder has been loaded.""" | |
| return _embedder is not None | |
| # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| # MTCNN face detection (default) | |
| # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| def load_face_detector(device: str = DEVICE): | |
| """Return the MTCNN face detector singleton.""" | |
| global _face_detector | |
| if _face_detector is not None: | |
| return _face_detector | |
| if not _MTCNN_AVAILABLE: | |
| raise RuntimeError( | |
| "MTCNN face detector is not available. " | |
| "Expected the vendored AdaFace repository at " | |
| f"{_ADAFACE_REPO}." | |
| ) | |
| mtcnn_device = "cuda:0" if str(device).startswith("cuda") and torch.cuda.is_available() else "cpu" | |
| _face_detector = _mtcnn.MTCNN(device=mtcnn_device, crop_size=(112, 112)) | |
| # Conservative defaults; exposed through env for ops tuning. | |
| _face_detector.min_face_size = env_int("MTCNN_MIN_FACE_SIZE", 20) | |
| print(f"[Sentinel-AI] MTCNN face detector loaded on {mtcnn_device}") | |
| return _face_detector | |
| def _detect_pass( | |
| detector, | |
| image, | |
| min_face_size: int, | |
| confidence_threshold: float, | |
| thresholds, | |
| ) -> list[dict]: | |
| """Run one MTCNN pass and return score-sorted face dictionaries.""" | |
| boxes, landmarks = detector.detect_faces( | |
| image, | |
| min_face_size, | |
| thresholds, | |
| detector.nms_thresholds, | |
| detector.factor, | |
| ) | |
| faces: list[dict] = [] | |
| for box, points in zip(boxes, landmarks): | |
| score = float(box[4]) if len(box) > 4 else 1.0 | |
| if score < confidence_threshold: | |
| continue | |
| faces.append({ | |
| "box": [int(round(v)) for v in box[:4]], | |
| "score": round(score, 4), | |
| "landmarks": [float(v) for v in points[:10]], | |
| }) | |
| faces.sort(key=lambda item: item["score"], reverse=True) | |
| return faces | |
| def detect_faces(image, confidence_threshold: float = 0.6) -> list[dict]: | |
| """ | |
| Detect faces with MTCNN, retrying once with relaxed thresholds. | |
| The first pass uses the detector's normal settings. If it finds no face, | |
| a second pass lowers the minimum face size and the P/R/O thresholds | |
| (``MTCNN_RETRY_MIN_FACE_SIZE`` / ``MTCNN_RETRY_CONFIDENCE``). The caller | |
| still compares the resulting embedding against ``MATCH_SIMILARITY_THRESHOLD``, | |
| so a relaxed detection cannot by itself produce a false identity match. | |
| Parameters | |
| ---------- | |
| image : PIL.Image.Image RGB image | |
| confidence_threshold : minimum MTCNN probability to keep a face | |
| Returns | |
| ------- | |
| List of ``{"box": [x1, y1, x2, y2], "score": float, | |
| "landmarks": [x0, β¦, x4, y0, β¦, y4]}`` sorted by score. | |
| """ | |
| detector = load_face_detector() | |
| rgb_image = image.convert("RGB") | |
| faces = _detect_pass( | |
| detector, | |
| rgb_image, | |
| detector.min_face_size, | |
| confidence_threshold, | |
| detector.thresholds, | |
| ) | |
| if faces: | |
| return faces | |
| retry_min_size = min(int(detector.min_face_size), int(MTCNN_RETRY_MIN_FACE_SIZE)) | |
| retry_confidence = min(float(confidence_threshold), float(MTCNN_RETRY_CONFIDENCE)) | |
| # Lower each P/R/O stage threshold to the configured retry confidence. | |
| # Using ``retry_confidence`` here would wrongly lower the later stages when | |
| # the retry confidence is *higher* than the caller's threshold. | |
| retry_stage_threshold = float(MTCNN_RETRY_CONFIDENCE) | |
| retry_thresholds = [ | |
| min(float(threshold), retry_stage_threshold) | |
| for threshold in detector.thresholds | |
| ] | |
| # Skip a pointless second pass when the retry settings are not actually | |
| # more permissive than the first pass. | |
| if ( | |
| retry_min_size >= int(detector.min_face_size) | |
| and retry_confidence >= float(confidence_threshold) | |
| and retry_thresholds == list(detector.thresholds) | |
| ): | |
| return faces | |
| return _detect_pass( | |
| detector, | |
| rgb_image, | |
| retry_min_size, | |
| retry_confidence, | |
| retry_thresholds, | |
| ) | |
| def align_face(image, landmarks: list[float], detector=None): | |
| """ | |
| Warp a face to the canonical 112x112 template using MTCNN's 5 landmarks. | |
| This is the standard AdaFace preprocessing. It removes pose, scale, and | |
| framing variance, so embeddings are comparable regardless of how the | |
| source image was cropped. ``landmarks`` is the flat 10-value list | |
| returned by :func:`detect_faces`. | |
| Falls back to a plain context crop if the warp fails. | |
| """ | |
| from PIL import Image as _Image | |
| from mtcnn_pytorch.src.align_trans import warp_and_crop_face # type: ignore | |
| if not landmarks or len(landmarks) < 10: | |
| raise ValueError("MTCNN landmarks are required for alignment.") | |
| detector = detector or load_face_detector() | |
| points = [[landmarks[j], landmarks[j + 5]] for j in range(5)] | |
| warped = warp_and_crop_face( | |
| np.array(image.convert("RGB")), | |
| points, | |
| detector.refrence, | |
| crop_size=detector.crop_size, | |
| ) | |
| return _Image.fromarray(warped).convert("RGB") | |
| def square_context_crop(image, box: list[int], margin: float = FACE_CROP_MARGIN): | |
| """ | |
| Crop a square region around a face box, including hair/shoulder context. | |
| CelebA images (used to build the index) are tightly framed portraits. A | |
| raw MTCNN box crops only the inner face and loses that context, which | |
| measurably degrades identity matching. Expanding the box by ``margin`` | |
| and forcing a square aspect reproduces the index framing. | |
| PIL pads out-of-bounds crop areas with black, so faces near an image edge | |
| are handled without special-casing. | |
| """ | |
| x1, y1, x2, y2 = (float(v) for v in box[:4]) | |
| cx, cy = (x1 + x2) / 2.0, (y1 + y2) / 2.0 | |
| side = max(x2 - x1, y2 - y1) * max(margin, 1.0) | |
| half = side / 2.0 | |
| left = int(round(cx - half)) | |
| top = int(round(cy - half)) | |
| right = int(round(cx + half)) | |
| bottom = int(round(cy + half)) | |
| if right <= left or bottom <= top: # degenerate box | |
| return image.convert("RGB") | |
| return image.crop((left, top, right, bottom)).convert("RGB") | |
| # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| # Optional RF-DETR detector (kept for backwards compatibility) | |
| # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| def load_rfdetr(device: str = DEVICE): | |
| """ | |
| Return the RF-DETR detector singleton, if the optional dependency is | |
| installed. RF-DETR is a general COCO object detector and is *not* used by | |
| the default inference path. | |
| """ | |
| global _detector | |
| if _detector is not None: | |
| return _detector | |
| if not _RFDETR_AVAILABLE: | |
| raise RuntimeError( | |
| "RF-DETR is not installed. " | |
| "Install it with: pip install 'rfdetr>=1.11'" | |
| ) | |
| print("[Sentinel-AI] Loading optional RF-DETR Small weights...") | |
| wrapper = RFDETRSmall() | |
| # rfdetr >= 1.11 exposes .inference(); older releases used | |
| # .optimize_for_inference(). Support both rather than crashing at startup. | |
| try: | |
| if hasattr(wrapper, "inference"): | |
| wrapper.inference(compile=False, inplace=True, dtype=torch.float16) | |
| elif hasattr(wrapper, "optimize_for_inference"): | |
| wrapper.optimize_for_inference(compile=False, inplace=True, dtype="float16") | |
| except Exception as exc: # pragma: no cover | |
| print(f"[Sentinel-AI] RF-DETR FP16 optimisation skipped: {exc}") | |
| _detector = wrapper | |
| print("[Sentinel-AI] RF-DETR Small loaded") | |
| return _detector | |
| def _safe_parse_detr_output( | |
| outputs: dict, | |
| image_h: int, | |
| image_w: int, | |
| confidence_threshold: float, | |
| ) -> list[dict]: | |
| """ | |
| Parse raw DETR forward-pass output into detection dicts. | |
| Raises KeyError if RF-DETR changes its output format (fail-fast). | |
| """ | |
| logits = outputs["pred_logits"][0].softmax(-1) # (queries, classes+1) | |
| boxes = outputs["pred_boxes"][0] # (queries, 4) | |
| scores, labels = logits[..., :-1].max(-1) | |
| detections: list[dict] = [] | |
| for score, label, box in zip(scores, labels, boxes): | |
| s = float(score) | |
| if s < confidence_threshold: | |
| continue | |
| cx, cy, w, h = box.float().tolist() | |
| x1 = int(max(0, (cx - w / 2) * image_w)) | |
| y1 = int(max(0, (cy - h / 2) * image_h)) | |
| x2 = int(min(image_w, (cx + w / 2) * image_w)) | |
| y2 = int(min(image_h, (cy + h / 2) * image_h)) | |
| detections.append({ | |
| "box": [x1, y1, x2, y2], | |
| "score": round(s, 4), | |
| "label": int(label.item()), | |
| }) | |
| return detections | |
| def rfdetr_detect( | |
| image_tensor: torch.Tensor, | |
| model, | |
| confidence_threshold: float = 0.6, | |
| ) -> list[dict]: | |
| """Run the optional RF-DETR detector on a CHW tensor in [0, 1].""" | |
| from PIL import Image | |
| image_np = (image_tensor.detach().permute(1, 2, 0).cpu().numpy() * 255).clip(0, 255).astype(np.uint8) | |
| pil_image = Image.fromarray(image_np) | |
| detections_sv = model.predict(pil_image, confidence=confidence_threshold) | |
| detections = [] | |
| for i in range(len(detections_sv.xyxy)): | |
| x1, y1, x2, y2 = detections_sv.xyxy[i].astype(int).tolist() | |
| score = float(detections_sv.confidence[i]) | |
| label = int(detections_sv.class_id[i]) if detections_sv.class_id is not None else 0 | |
| detections.append({ | |
| "box": [x1, y1, x2, y2], | |
| "score": round(score, 4), | |
| "label": label, | |
| }) | |
| detections.sort(key=lambda d: d["score"], reverse=True) | |
| return detections | |
| # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| # AdaFace embedding | |
| # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| def load_adaface( | |
| architecture: str = "ir_50", | |
| weights_path: Path = ADAFACE_WEIGHTS, | |
| device: str = DEVICE, | |
| ) -> nn.Module: | |
| """ | |
| Return the AdaFace face-embedding model singleton. | |
| Raises RuntimeError if the checkpoint is missing or if the checkpoint does | |
| not cover the model (the previous ``strict=False`` silently produced | |
| random embeddings in that case). | |
| """ | |
| global _embedder | |
| if _embedder is not None: | |
| return _embedder | |
| if not _ADAFACE_AVAILABLE: | |
| raise RuntimeError( | |
| "AdaFace is not available. " | |
| "Clone https://github.com/mk-minchul/AdaFace into models_cache/adaface " | |
| "and download adaface_ir50_ms1mv2.ckpt." | |
| ) | |
| weights_path = Path(weights_path) | |
| if not weights_path.exists(): | |
| raise RuntimeError( | |
| f"AdaFace weights not found at {weights_path}. " | |
| "Download adaface_ir50_ms1mv2.ckpt before starting the server." | |
| ) | |
| model = adaface_net.build_model(architecture) | |
| checkpoint = torch.load(str(weights_path), map_location="cpu", weights_only=False) | |
| state_dict = checkpoint.get("state_dict", checkpoint) | |
| # Strip the Lightning "model." prefix used by the official checkpoint. | |
| state_dict = {k.replace("model.", "", 1): v for k, v in state_dict.items()} | |
| result = model.load_state_dict(state_dict, strict=False) | |
| missing = [k for k in result.missing_keys if "head." not in k] | |
| if missing: | |
| raise RuntimeError( | |
| "AdaFace checkpoint does not match the model architecture; " | |
| f"{len(missing)} required tensors are missing (e.g. {missing[:3]}). " | |
| "Refusing to run with partially random weights." | |
| ) | |
| model = model.to(device) | |
| if str(device).startswith("cuda"): | |
| model = model.half() # FP16 | |
| model.eval() | |
| _embedder = model | |
| return _embedder | |
| def adaface_embed( | |
| face_tensor: torch.Tensor, | |
| model: nn.Module, | |
| ) -> torch.Tensor: | |
| """ | |
| Embed a single 112x112 face crop. | |
| Parameters | |
| ---------- | |
| face_tensor : torch.Tensor shape (3, 112, 112), normalised to [-1, 1] | |
| model : AdaFace model from load_adaface() | |
| Returns | |
| ------- | |
| torch.Tensor shape (512,), L2-normalised float32 on CPU | |
| """ | |
| device = next(model.parameters()).device | |
| x = face_tensor.unsqueeze(0).to(device) | |
| if device.type == "cuda": | |
| x = x.half() | |
| with torch.no_grad(): | |
| with torch.amp.autocast(device_type=device.type, enabled=(device.type == "cuda")): | |
| # AdaFace always returns (embeddings, norms) | |
| embeddings, _ = model(x) | |
| embedding = embeddings[0].float().cpu() | |
| embedding = embedding / embedding.norm().clamp(min=1e-12) | |
| return embedding | |