Face Embeds Distance

This is the node the whole pack was really built around. The README's own pitch for the entire repo is essentially a use case for this one node: send three reference photos of a real person through it, average them into a baseline, and now every generated image you compare against that baseline gets an actual number instead of you squinting at two thumbnails and going "eh, kinda?" That's Face Embeds Distance.

The mechanism

Whichever library you picked in Face Analysis Models - InsightFace, AuraFace, or Dlib - doesn't just find a face, it turns it into an embedding: a vector that encodes facial geometry, not general appearance. This is the same kind of ArcFace-style embedding that identity-preservation tools like InstantID, PuLID, and IPAdapter FaceID condition their generations on. Face Embeds Distance runs that embedding step on your reference image and your image input, then computes a distance between the two vectors. Small distance, same identity. Large distance, probably a different person, or at least a version generative models got wrong.

It's worth knowing this is exactly the kind of metric research teams use to benchmark identity tools against each other - a "face similarity" score is standard in papers comparing methods like PuLID and InstantID. This node lets you run that same kind of check locally, on your own outputs, instead of trusting a benchmark table that was measured on someone else's dataset.

The inputs that matter

• reference / image (IMAGE) - the known-good face and the face you're checking. reference is your ground truth; image is what you're scoring, and it can be a batch if you want to check a bunch of generations in one pass.
• similarity_metric - L2_norm, cosine, or euclidean. These aren't interchangeable in what "good" looks like: don't assume a threshold you tuned on cosine still means the same thing if you switch to euclidean. Pick one and stay consistent across a project rather than hopping between them.
• filter_thresh (FLOAT, default 100) and filter_best (INT, default 0) - if image is a batch, these let the node do the sorting for you: filter_thresh drops anything past a distance cutoff, filter_best keeps only the closest N matches. This is the feature that turns this node from "a number you read" into "an automatic culling step" - feed it 50 generations, get back the 5 that actually look like your subject.
• generate_image_overlay (BOOLEAN, default true) - when on, the IMAGE output is a side-by-side debug view with the distance number burned in, so you can sanity-check the math against your own eyes instead of trusting a float blindly.

Outputs are IMAGE (the overlay, if you asked for one) and distance (FLOAT) - wire the distance into whatever you're using to log or gate on it.

Installing it

Standard for the pack:

• ComfyUI Manager - search "Face Analysis for ComfyUI", install, restart.
• Manual - cd ComfyUI/custom_nodes && git clone https://github.com/cubiq/ComfyUI_FaceAnalysis, restart.

No extra model downloads for this node specifically - it rides entirely on whatever backend you set up in Face Analysis Models.

Common issues

The single biggest source of misleading numbers isn't the node, it's your reference photo. The README's own advice - average three reference shots rather than trusting one - exists because a single reference taken at a bad angle, weird lighting, or heavy makeup gives you a noisy baseline, and every comparison downstream inherits that noise. If your distances look randomly all over the place, check the reference first before blaming the metric. Second most common issue: comparing an unaligned or heavily cropped image against a clean reference - pass both through Face Align first if you're getting numbers that don't match what your eyes tell you. And remember the license reality underneath all of this: if you're on the InsightFace backend, the embedding model itself is non-commercial-only, so this exact evaluation pipeline isn't something you can build into a paid product without switching to AuraFace or accepting that constraint.