Embed Face (AdaFace)

@minchul1 VersionExtract

Takes an Image plus 5-point [[Landmark]] sets, similarity-aligns each face to a canonical crop, and runs an AdaFace recognizer to emit one Embedding per face — quality-adaptive margins improve accuracy on low-quality or occluded faces versus ArcFace.

How it fits

Typical backends

Face embedding from a still image — detect faces, find their landmarks, embed, and serialize the vectors.

Live face embedding from an HTTP frame source published as JSON.

Caveats

Compatibilitymodel must load through the transformers remote-code AutoModel path; the default CVLFace AdaFace IR-101 emits a 512-d feature, and arbitrary face encoders without that wrapper either fail to load or return the wrong shape.
Hard constraintEach entry of [[Landmark]] must carry the canonical 5 ArcFace points in order (left eye, right eye, nose, left and right mouth corners); a set with fewer than 5 points short-circuits that face to a zero-length Embedding, so filter empty faces upstream.
Parameter interactionalign false skips the similarity warp and resizes the whole frame to image_size square, so disable it only when upstream already supplies aligned chips. normalize L2-normalizes each vector so cosine similarity reduces to a dot product.
State lifetimeThe embedding space, dimension, and norm calibration are tied to the loaded model, so switching it produces incompatible vectors — rebuild any vector index populated with a different checkpoint. All keys are captured once at startup.
Fallbackdevice `cuda` silently falls back to CPU when no CUDA backend is visible.

Versions

b3cf3fcbdefaultlatest
Automated release
6/24/2026