README.md

---
language:
- en
library_name: lvface
pipeline_tag: image-feature-extraction
pretty_name: LVFace ONNX Weights for Python
license: other
tags:
- face-recognition
- face-embedding
- onnx
- lvface
---

# LVFace ONNX Weights for Python

This repository is a preservation mirror of the released LVFace ONNX embedding weights for use
with the [`lvface`](https://github.com/mowshon/lvface) Python
package.

It is not the official LVFace model repository and is not affiliated with or endorsed by
ByteDance. The models were created by the LVFace authors and were obtained from the official
[`bytedance-research/LVFace`](https://huggingface.co/bytedance-research/LVFace) repository at
revision [`b12702ab1f5c721748e054a66dc90e1edd1f0724`](https://huggingface.co/bytedance-research/LVFace/tree/b12702ab1f5c721748e054a66dc90e1edd1f0724).
The files are mirrored without modification.

## Files

| Model | Repository path | Size | SHA-256 |
|---|---|---:|---|
| LVFace-T Glint360K | `LVFace-T_Glint360K.onnx` | 76,653,813 bytes | `bf8da0e1e93c432d9a1d874a9ba0990f5859f970e8864b3990f2f33d11f9cdb3` |
| LVFace-S Glint360K | `LVFace-S_Glint360K.onnx` | 304,196,926 bytes | `cd09f27c82ce0a3633fb8b1966d779a7171b23aa4f14ca0de6edf9677573d119` |
| LVFace-B Glint360K | `LVFace-B_Glint360K.onnx` | 455,533,594 bytes | `9d834ed8e927fd35b9123b2bf97c40aad05785b1f9ecfb1c4c1f6242d38d1382` |
| LVFace-L Glint360K | `LVFace-L_Glint360K.onnx` | 1,022,938,188 bytes | `49389036a4a5b69e0efcddfe34839ac72c7a71ce6b4dc1b6821e2ac368c87063` |

Only the ONNX weights required by the Python package are mirrored here. PyTorch checkpoints,
evaluation outputs, and training code are not part of this repository.

## Use with the Python package

Install LVFace with Hugging Face download support:

```bash
python -m pip install "lvface[hub]"
```

The package resolves a model name to a revision-pinned ONNX file during recognizer construction,
verifies its size and SHA-256, and reuses the local Hugging Face cache on subsequent calls:

```python
from lvface import FaceRecognizer

recognizer = FaceRecognizer("LVFace-T_Glint360K")
embedding = recognizer.embed("portrait.jpg")
```

Users who already have a compatible ONNX file can bypass Hugging Face entirely:

```python
from lvface import FaceRecognizer

recognizer = FaceRecognizer("/path/to/LVFace-T_Glint360K.onnx")
```

The package registry must reference this repository's Hugging Face repository ID and a pinned
commit revision. Do not use `main` as the production revision.

## Direct download

```python
from huggingface_hub import hf_hub_download

path = hf_hub_download(
    repo_id="Mowshon/lvface-weights",
    filename="LVFace-T_Glint360K.onnx",
    revision="83b567cd6a3fc34434667e4415b6125feceb39ea",
)
```

## Provenance and integrity

The checksums in the file table match the Git LFS SHA-256 values published by the official
repository at the source revision. Consumers should pin this mirror to an immutable commit and
validate both file size and SHA-256 before loading a model.

## License

The upstream repository contains conflicting license statements. Its model-card metadata labels
the repository as MIT and it includes an MIT license for code, while the prose states that the
downloaded models are for non-commercial research purposes only.

This mirror does not resolve that conflict and does not grant any additional rights. Users and
redistributors must review the
[official model card](https://huggingface.co/bytedance-research/LVFace/blob/main/README.md#license)
and obtain clarification or permission from the LVFace authors when needed. `LICENSE_CODE.txt`
applies to upstream code and must not be interpreted as a separate license grant for the model
weights.

## Required citation

Use of these weights must include citation of the original LVFace work:

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

Paper: [arXiv:2501.13420](https://arxiv.org/abs/2501.13420)

## Original resources

- [Official LVFace model repository](https://huggingface.co/bytedance-research/LVFace)
- [Official LVFace source repository](https://github.com/bytedance/LVFace)
- [LVFace paper](https://arxiv.org/abs/2501.13420)