insightface backend (LocalAI)

Face recognition backend backed by ONNX Runtime. Provides face verification (1:1), face analysis (age/gender), face detection, face embedding, and — via LocalAI's built-in vector store — 1:N identification.

Engines

This backend ships with two interchangeable engines selected via LoadModel.Options["engine"]:

engine	Implementation	Models	License
`insightface` (default)	`insightface.app.FaceAnalysis`	`buffalo_l`, `buffalo_s`, `antelopev2`	Non-commercial research use only
`onnx_direct`	OpenCV `FaceDetectorYN` + `FaceRecognizerSF`	OpenCV Zoo YuNet + SFace	Apache 2.0 (commercial-safe)

Both engines implement the same FaceEngine protocol in engines.py, so the gRPC servicer in backend.py doesn't need to know which one is active.

LoadModel options

Common:

option	default	description
`engine`	`insightface`	one of `insightface`, `onnx_direct`
`det_size`	`640x640` (insightface), `320x320` (onnx_direct)	detector input size
`det_thresh`	`0.5`	detector confidence threshold
`verify_threshold`	`0.35`	default cosine distance cutoff for FaceVerify

insightface engine:

option	default	description
`model_pack`	`buffalo_l`	which insightface pack to load

onnx_direct engine:

option	default	description
`detector_onnx`	(required)	path to YuNet-compatible ONNX
`recognizer_onnx`	(required)	path to SFace-compatible ONNX

Adding a new model pack

If it's an insightface pack (auto-downloadable or manually extracted into ~/.insightface/models/<name>/), just add a new gallery entry in backend/index.yaml with options: ["engine:insightface", "model_pack:<name>"]. No code change.
If it's an Apache-licensed ONNX pair, add a gallery entry with options: ["engine:onnx_direct", "detector_onnx:...", "recognizer_onnx:..."]. If the detector or recognizer has a different input-tensor shape than YuNet/SFace, you may need a new engine implementation in engines.py; the two-engine seam makes that a self-contained change.

Running tests locally

bash

make -C backend/python/insightface         # install deps + bake models
make -C backend/python/insightface test    # run test.py

The OpenCV Zoo tests skip gracefully when /models/opencv/*.onnx is absent (e.g. on dev boxes where install.sh wasn't run).