LVFace

src="https://img.shields.io/badge/HuggingFace-Model-yellow?logo=huggingface&logoColor=yellow" alt="Model" /> src="https://img.shields.io/badge/Code-GitHub-orange?logo=github&logoColor=white" alt="Code" /> src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License" />

This is the official PyTorch implementation for the inference of LVFace. Drawing inspiration from the massive data support, multi-stage training paradigm, and Transformer architecture of large-model technology, this method, based on Large Vision Transformer, has carried out progressive optimization of the face clustering space through multiple stages on massive datasets.

News

• 🔥🔥🔥 We have released the training weights of LVFace. Please click here to download it. (August, 2025 UTC)
• 🎉🎉🎉 LVFace has been recommended as ICCV Highlight. (July, 2025 UTC)
• 🎉🎉🎉 LVFace is accepted by ICCV 2025. (July, 2025 UTC)
• 🔥🔥🔥 We have updated the arXiv report of LVFace. Please click here to view it. (March, 2025 UTC)
• 🎉🎉🎉 LVFace secured 1st place in the ICCV 2021 Masked Face Recognition (MFR)-Ongoing Challenge (academic track). (December, 2024 UTC)

Requirements

All required dependencies are listed in requirements.txt:

onnxruntime-gpu==1.19.2
torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
scikit-image
insightface
numpy==1.23

Install all dependencies with a single command: pip install -r requirements.txt

Datasets

Test datasets for inference validation can be downloaded from the following sources:

• IJB-C & IJB-B: Google Drive
• MFR-Ongoing: Challenge Page

LVFace Pretrained Models

Pretrained model weights for inference are available below in both ONNX and PyTorch (.pt) formats:

Step-by-Step Usage Guide

1. Installation & Environment Setup

First, clone the repository and navigate to the project directory:

# Clone the LVFace repository
git clone https://github.com/bytedance/LVFace.git

# Enter the project directory
cd LVFace

Then install all required dependencies using the provided requirements.txt:

# Install dependencies
pip install -r requirements.txt

2. Download Pretrained Models Download the ONNX-format pretrained weights from the LVFace Pretrained Models section, then place them in a directory (e.g., ./LVFace_model/).

3. Run Inference Execute the inference_onnx.py script to perform feature extraction and similarity calculation. A complete workflow example:

## Initialize the inferencer from inference_onnx.py
inferencer = LVFaceONNXInferencer(
   model_path="./models/vit_b_dp005_mask_005.onnx",  # Path to your ONNX model
   use_gpu=True  # Set to False for CPU-only inference
)

## Extract feature from local image
feat1 = inferencer.infer_from_image("path/to/image1.jpg")

## Extract feature from URL
feat2 = inferencer.infer_from_url("https://example.com/image1.jpg")

## Calculate cosine similarity
similarity = inferencer.calculate_similarity(feat1, feat2)
print(f"Similarity score: {similarity:.6f}")  # Output example: 0.892345

Note: The LVFaceONNXInferencer class is defined in inference_onnx.py, which handles ONNX model loading, image preprocessing, feature extraction, and similarity calculation in a unified interface. Ensure the model path and image paths are correctly specified before running.

Model Evaluation

Evaluation Steps

1. Modify the test dataset path (e.g., IJB-C, IJB-B) in the corresponding evaluation script (eval_ijbc.py).
2. Run the evaluation with pretrained model weights using the commands below:

Evaluation Commands

python eval_ijbc.py \
  --model-prefix path/to/LVFace-B_Glint360K.pt \
  --result-dir results \
  --network vit_b_dp005_mask_005 > LVFace-B_Glint360K.log 2>&1 &

License

The code of LVFace is released under the MIT License. There is no limitation for both academic and commercial usage. The models downloaded from our repo follow the above license policy (which is for non-commercial research purposes only).

Citation

If you find this work useful, please cite our paper and give us a star ⭐:

@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}
}

Acknowledgments

We sincerely thank Professor Jiankang Deng for his valuable guidance and insights throug