Estimate Face Embeddings (AuraFace v1)

How it fits

Typical backends

Caveats

• Hard constraintThe bound weights directory is scanned recursively and must contain exactly one ONNX recognition file; a missing or non-directory binding, zero ONNX files, or more than one all abort startup, so pin a single weights bundle.
• Hard constraintThe five keypoints per face must be ordered left-eye, right-eye, nose, left-mouth, right-mouth; a wrong order does not raise but produces a misaligned crop and a useless embedding. Only the first five keypoints per face are used.
• FallbackA face with fewer than five keypoints passes through as an empty (0,) Embedding in the same output slot rather than being dropped; feeding that into a similarity stage breaks the math, so filter it downstream.
• Parameter interactionThe square alignment size must match the recognition network's training input size; changing it to an untrained size silently degrades match quality.
• FallbackThe device accepts cuda, cuda:N, or cpu; requesting cuda on a node with no visible GPU falls back to CPU at startup rather than failing, so a CPU-only node runs at CPU speeds.
• I/O contractOutput cardinality and order equal the input keypoint-list cardinality; empty input yields an empty output without running the network. Embeddings are unit-normalised so cosine similarity reduces to a dot product.
• State lifetimeAll configuration is captured once at startup; runtime changes have no effect and require a redeploy.