uniface/docs/concepts/model-cache-offline.md

Model Cache & Offline Use

UniFace automatically downloads and caches models. This page explains how model management works.

---

Automatic Download

Models are downloaded on first use:

from uniface.detection import RetinaFace

# First run: downloads model to cache
detector = RetinaFace()  # ~3.5 MB download

# Subsequent runs: loads from cache
detector = RetinaFace()  # Instant

Weights come from GitHub Releases, with a Hugging Face mirror as an automatic fallback when GitHub is unreachable. There is nothing to configure, and no Hugging Face token is needed.

---

Cache Location

Default cache directory:

~/.uniface/models/

Example structure:

~/.uniface/models/
├── retinaface_mnet_v2.onnx
├── arcface_mnet.onnx
├── 2d_106.onnx
├── gaze_resnet34.onnx
├── parsing_resnet18.onnx
└── ...

---

Custom Cache Directory

Use the programmatic API to change the cache location at runtime:

from uniface.model_store import get_cache_dir, set_cache_dir

# Set a custom cache directory
set_cache_dir('/data/models')

# Verify the current path
print(get_cache_dir())  # /data/models

# All subsequent model loads use the new directory
from uniface.detection import RetinaFace
detector = RetinaFace()  # Downloads to /data/models/

Or set the UNIFACE_CACHE_DIR environment variable (see Environment Variables below).

---

Pre-Download Models

Download models before deployment using the concurrent downloader:

from uniface.model_store import download_models
from uniface.constants import (
    RetinaFaceWeights,
    ArcFaceWeights,
    AgeGenderWeights,
)

# Download multiple models concurrently (defaults to min(CPU count, 8) threads)
paths = download_models([
    RetinaFaceWeights.MNET_V2,
    ArcFaceWeights.MNET,
    AgeGenderWeights.DEFAULT,
])

for model, path in paths.items():
    print(f"{model.value} -> {path}")

Or download one at a time:

from uniface.model_store import verify_model_weights
from uniface.constants import RetinaFaceWeights

path = verify_model_weights(RetinaFaceWeights.MNET_V2)
print(f"Downloaded: {path}")

Or use the CLI tool:

python tools/download_model.py

---

Offline Use

For air-gapped or offline environments:

1. Pre-download models

On a connected machine:

from uniface.model_store import verify_model_weights
from uniface.constants import RetinaFaceWeights

path = verify_model_weights(RetinaFaceWeights.MNET_V2)
print(f"Copy from: {path}")

2. Copy to target machine

# Copy the entire cache directory
scp -r ~/.uniface/models/ user@offline-machine:~/.uniface/models/

3. Point to the cache (if non-default location)

from uniface.model_store import set_cache_dir

# Only needed if the models are not at ~/.uniface/models/
set_cache_dir('/path/to/copied/models')

4. Use normally

# Models load from local cache
from uniface.detection import RetinaFace
detector = RetinaFace()  # No network required

---

Model Verification

Models are verified with SHA-256 checksums:

from uniface.constants import MODEL_REGISTRY, RetinaFaceWeights

# Check expected checksum
expected = MODEL_REGISTRY[RetinaFaceWeights.MNET_V2].sha256
print(f"Expected SHA256: {expected}")

If a model fails verification, it's re-downloaded automatically. The same checksum is enforced whichever source served the file, so a corrupted or stale mirror falls through to the other source instead of being cached.

---

Available Models

Detection Models

Model	Size	Download
RetinaFace MNET_025	1.7 MB	✅
RetinaFace MNET_V2	3.5 MB	✅
RetinaFace RESNET34	56 MB	✅
SCRFD 500M	2.5 MB	✅
SCRFD 10G	17 MB	✅
YOLOv5n-Face	11 MB	✅
YOLOv5s-Face	28 MB	✅
YOLOv5m-Face	82 MB	✅
YOLOv8-Lite-S	7.4 MB	✅
YOLOv8n-Face	12 MB	✅

Recognition Models

Model	Size	Download
ArcFace MNET	8 MB	✅
ArcFace RESNET	166 MB	✅
MobileFace MNET_V2	4 MB	✅
SphereFace SPHERE20	50 MB	✅

Other Models

Model	Size	Download
Landmark106	14 MB	✅
PIPNet WFLW-98	47 MB	✅
PIPNet 300W+CelebA-68	46 MB	✅
AgeGender	8 MB	✅
FairFace	44 MB	✅
Gaze ResNet34	82 MB	✅
BiSeNet ResNet18	51 MB	✅
MiniFASNet V2	1.2 MB	✅

---

Clear Cache

Find and remove cached models:

from uniface.model_store import get_cache_dir
print(get_cache_dir())  # shows the active cache path

# Remove all cached models
rm -rf ~/.uniface/models/

# Remove specific model
rm ~/.uniface/models/retinaface_mnet_v2.onnx

Models will be re-downloaded on next use.

---

Environment Variables

There are three equivalent ways to configure the cache directory:

1. Programmatic API (recommended)

from uniface.model_store import get_cache_dir, set_cache_dir

set_cache_dir('/path/to/custom/cache')
print(get_cache_dir())  # /path/to/custom/cache

2. Direct environment variable (Python)

import os
os.environ['UNIFACE_CACHE_DIR'] = '/path/to/custom/cache'

from uniface.detection import RetinaFace
detector = RetinaFace()  # Uses custom cache

3. Shell environment variable

export UNIFACE_CACHE_DIR=/path/to/custom/cache

All three methods set the same UNIFACE_CACHE_DIR environment variable under the hood. get_cache_dir() always returns the resolved path.

---

Next Steps

• Thresholds & Calibration - Tune model parameters
• Detection Module - Detection model details