lvface

lvface detects faces, aligns them, produces 512-dimensional LVFace embeddings, and compares people across portraits, group photos, or whole albums. The high-level API is small, while the detector and embedder are both replaceable.

This package was inspired by ByteDance's bytedance/lvface repository and was created to make this splendid model easy to install and use through the pip package manager.

from lvface import FaceRecognizer

recognizer = FaceRecognizer("LVFace-T_Glint360K")
result = recognizer.compare("id-photo.jpg", "selfie.jpg")

print(result.is_match)
print(f"cosine={result.cosine:.4f}, display={result.percentage:.1f}%")

Face recognition is biometric processing. Get informed consent, protect stored embeddings, define retention rules, and evaluate accuracy and bias on data representative of your users.

Why lvface?

• One pipeline for paths, image bytes, URLs, and RGB NumPy arrays.
• Every face in an image can be returned, not only the largest one.
• Multi-face search, group-photo matching, and album clustering are built in.
• Released LVFace ONNX models run through ONNX Runtime; PyTorch is not required.
• Custom detectors and embedders plug into the same FaceRecognizer.
• Named weights are revision-pinned and checksum-verified.

Install

Python 3.11, 3.12, or 3.13 is required.

Run exactly one command for your machine:

# CPU, any supported OS
python -m pip install "lvface[all-cpu]"

# NVIDIA CUDA, Linux or Windows
python -m pip install "lvface[all-cuda]"

# DirectML on Windows for DirectX 12-capable AMD, Intel, or NVIDIA GPUs
python -m pip install "lvface[all-directml]"

Use all-cpu if you are unsure. Use all-cuda for NVIDIA GPUs. On Windows without CUDA, use all-directml for DirectML-supported GPUs.

Install exactly one ONNX Runtime backend per virtual environment. Do not install lvface[all-cpu], lvface[all-cuda], and lvface[all-directml] into the same environment. These backends provide the same onnxruntime import name; create a fresh environment when switching backend.

Install variants

The all-* extras above install the complete common feature set: a runtime backend, the default InsightFace detector, automatic model download, guarded http(s) image loading, clustering, and Hungarian assignment.

For smaller installs, combine exactly one backend with only the features you need:

# Local ONNX weights and already aligned 112×112 face crops
python -m pip install "lvface[cpu]"

# Recognition from ordinary photos + automatic weight download
python -m pip install "lvface[cpu,detect,hub]"

# CUDA backend with detection and automatic weight download
python -m pip install "lvface[cuda,detect,hub]"

Available extras are:

Extra	What it adds
cpu	ONNX Runtime CPU backend
cuda	ONNX Runtime GPU backend for NVIDIA CUDA on Linux or Windows
directml	ONNX Runtime DirectML backend on Windows
detect	Default InsightFace detector
hub	Pinned LVFace ONNX weight download by registered model name
http	Guarded http(s) image loading
cluster	Album grouping support through scikit-learn
hungarian	Globally optimal one-to-one matching through SciPy

With [hub], a registered model name downloads its pinned ONNX file on first construction:

recognizer = FaceRecognizer("LVFace-T_Glint360K")

To keep weights under your own control, pass a local file. This path never accesses Hugging Face and does not need [hub]:

recognizer = FaceRecognizer("/models/LVFace-T_Glint360K.onnx")

Choose model weights

All four weights use the same API and produce 512-dimensional embeddings. The difference is the model capacity: larger models generally require more download space, memory, and inference time in exchange for better benchmark accuracy. LVFace-T_Glint360K is the default when no model is specified.

Model name	Download size	When to use it	IJB-C @ 1e-6	IJB-C @ 1e-5	IJB-C @ 1e-4	IJB-B @ 1e-4
LVFace-T_Glint360K	76.7 MB	Default; fastest and smallest choice for local apps, CPU use, and initial evaluation	88.53	95.63	96.67	95.41
LVFace-S_Glint360K	304.2 MB	A balanced upgrade when recognition quality matters more than model size and latency	90.06	96.52	97.31	96.14
LVFace-B_Glint360K	455.5 MB	Best overall accuracy/size tradeoff for accuracy-focused deployments	90.06	97.00	97.70	96.51
LVFace-L_Glint360K	1.02 GB	Largest model; mainly for benchmarking or testing whether its small gains at some operating points justify the cost	89.51	97.02	97.66	96.51

The benchmark values are verification rates in percent; higher is better. The number after @ is the false-accept-rate operating point, so 1e-6 is stricter than 1e-4. These results are useful for comparing models, but production thresholds must still be calibrated on representative data.

Select another registered model by name:

recognizer = FaceRecognizer("LVFace-B_Glint360K")

Named weights are downloaded once, stored in the local model cache, and SHA-256 verified before use. Later runs reuse the cached file. Do not compare or combine embeddings created by different LVFace model sizes: use the same weight file for enrollment, indexing, and queries.

Model resolution and download happen while FaceRecognizer is constructed. The ONNX Runtime session itself is still created lazily on the first embedding call.

For NVIDIA CUDA installs, verify that ONNX Runtime sees the CUDA provider before benchmarking:

python - <<'PY'
import onnxruntime as ort

if hasattr(ort, "preload_dlls"):
    ort.preload_dlls(directory="")
print(ort.get_available_providers())
PY

Expected CUDA output includes CUDAExecutionProvider. Expected DirectML output on Windows includes DmlExecutionProvider.

A 60-second tour

Compare two photos

from lvface import FaceRecognizer

recognizer = FaceRecognizer(device="auto")
result = recognizer.compare("first.jpg", "second.jpg", select="largest")

if result.is_match:
    print(f"Likely the same person ({result.percentage:.1f}% display score)")

percentage is a readable, threshold-centered display score. It is not a probability or a calibrated confidence value. Use cosine and a threshold calibrated for your own camera, population, and risk tolerance to make decisions.

Get an embedding for every face

faces = recognizer.analyze("team-photo.jpg")

for face in faces:
    vector = face.embedding.vector
    print(face.face_index, face.bbox, vector.shape)  # (512,)

analyze() performs load → detect → align → embed and returns a Face for every alignable face. Each result carries its bounding box, five landmarks, aligned crop, and L2-normalized embedding.

If you only need vectors:

embeddings = recognizer.embed("team-photo.jpg")  # list[Embedding]
one_embedding = recognizer.embed("portrait.jpg", select="largest")

Store face embeddings with FAISS

The FAISS example stores every detected face in a local cosine-similarity index. A small JSON file keeps the image and face index associated with each vector:

python -m pip install faiss-cpu
python examples/embed_and_store.py

Edit the IMAGE constant at the top of the script before running it. The index uses cosine similarity, matching lvface's canonical comparison metric. The script writes faces.index and faces.json. For production, treat both files as biometric data: restrict access, encrypt backups, and delete vectors when their source data must be removed.

To search the saved index, edit QUERY_IMAGE in the companion example:

python examples/search_faiss.py

It embeds the largest face in the query photo, loads faces.index, and prints the nearest stored faces with their cosine similarity. Use the same LVFace model for indexing and searching.

Find someone in a group photo

hits = recognizer.find(
    "person-to-find.jpg",
    "group-photo.jpg",
    top_k=3,
)

for hit in hits:
    print(hit.candidate.face_index, hit.percentage, hit.candidate.bbox)

Match two group photos

result = recognizer.match("group-before.jpg", "group-after.jpg")

for pair in result.pairs:
    print(
        pair.query.face_index,
        "↔",
        pair.candidate.face_index,
        f"{pair.percentage:.1f}%",
    )

The default greedy assignment uses each face at most once. Install lvface[hungarian] and pass assignment="hungarian" for globally optimal one-to-one assignment.

Group an album by identity

identities = recognizer.group(["day-1.jpg", "day-2.jpg", "day-3.jpg"])

for identity in identities:
    print([(face.image_index, face.face_index) for face in identity])

Clustering is conservative: every member must meet the threshold against every other member, and one identity cannot contain two faces from the same image unless one_per_image=False.

API at a glance

Call	Result
analyze(image)	Every detected face, aligned crop, and embedding
embed(image)	Embeddings for every face
embed(image, select="largest")	One explicitly selected embedding
embed_aligned(crop)	Embed one pre-aligned 112×112 RGB crop
compare(a, b)	Cosine, Euclidean distance, display score, and decision
verify(a, b)	Boolean match decision
find(query, gallery)	One-to-many ranked face search
match(a, b)	Full many-to-many matrix and assigned pairs
group(images)	Conservative identity clusters across images

Accepted image inputs are a path, http(s) URL with [http], encoded bytes, or an RGB uint8 NumPy array. NumPy arrays are assumed to be RGB, not OpenCV BGR.

Bring your own detector

A detector only needs to subclass FaceDetector and provide lazy load() plus detect(). Each detected Face should contain a bounding box and five ArcFace-order landmarks. The base class supplies the 112×112 alignment implementation.

detector = MyDetector(...)
recognizer = FaceRecognizer(
    embedder="LVFace-T_Glint360K",
    detector=detector,
)
faces = recognizer.analyze("photo.jpg")

examples/custom_detector.py is a complete OpenCV YuNet adapter and shows the important part explicitly: the custom detector instance is passed into FaceRecognizer, so its detections flow through alignment and LVFace embedding.

Change the detector model and image paths at the bottom of the example, then run it:

python examples/custom_detector.py

Custom embedding backends follow the same pattern: subclass FaceEmbedder, lazily initialize the runtime in load(), and implement _forward(batch) to return an (N, 512) floating-point array. The base class validates 112×112 RGB inputs, preprocesses them, batches inference, and returns validated Embedding objects.

Concepts that matter

Embedding. A 512-number representation of an aligned face. Embeddings returned by the public API are L2-normalized.

Cosine similarity. The decision metric. Higher means more similar. The packaged 0.35 default is a provisional starting point, not a domain-general operating threshold.

Euclidean distance. A diagnostic value. For normalized vectors, euclidean² = 2 - 2 × cosine.

Alignment. Five facial landmarks are warped onto the ArcFace 112×112 template before embedding. Good detection and alignment are part of recognition quality, not merely preprocessing details.

Display percentage. A sigmoid mapping centered on the decision threshold. It is for UI display only and must not be presented as probability, certainty, or an estimated false-match rate.

Runnable examples

Each example is intentionally a small, direct Python script. Open one, replace the sample image paths, and run it:

python examples/verify_two_faces.py
python examples/embed_and_store.py
python examples/search_faiss.py
python examples/find_in_group.py
python examples/match_two_group_photos.py
python examples/cluster_album.py
python examples/custom_detector.py

From a source checkout:

python -m pip install -e ".[detect,hub]"

Weights, licenses, and citation

The package code is MIT licensed.

The default InsightFace model packs, including buffalo_l, are separately licensed for non-commercial research use. Applications requiring other terms should supply a detector with appropriate weights or pass pre-aligned crops with detector=None.

LVFace embedding-weight licensing is unresolved. The official repository metadata declares MIT, while its model-card prose restricts downloaded models to non-commercial research. The unofficial Mowshon/lvface-weights preservation mirror grants no additional rights. lvface pins mirror revision 83b567cd6a3fc34434667e4415b6125feceb39ea; the mirror records unchanged files from official bytedance-research/LVFace revision b12702ab1f5c721748e054a66dc90e1edd1f0724. Review the official model card and seek clarification from the authors when necessary.

Use of the weights requires citation of the original work:

@inproceedings{you2025lvface,
  title={{LVFace}: Progressive Cluster Optimization for Large Vision Models in Face Recognition},
  author={You, Jinghan and Li, Shanglin and Sun, Yuanrui and Wei, Jiangchuan and Guo, Mingyu and Feng, Chao and Ran, Jiao},
  booktitle={ICCV},
  year={2025}
}

Development

python -m pip install -e ".[dev]"
ruff check .
ruff format --check .
mypy src
pytest