wehub-resource-sync
68 lines
2.4 KiB
Markdown
68 lines
2.4 KiB
Markdown
# 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
|
|
|
|
1. 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.
|
|
2. 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).
|