Getting Started

Prerequisites

Python 3.12+
uv package manager
Rust toolchain (for FAISS bindings): curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
FAISS 1.14+ (macOS: brew install faiss; Linux: see FAISS install guide)
4 GB RAM minimum (8 GB recommended for demo gallery)

Installation

git clone https://github.com/radekdymacz/ufme
cd ufme
make install

This runs uv sync --all-extras, installing all Python dependencies into a managed virtual environment.

Download models

make models

Downloads and exports all models into models/. Required models are always downloaded; optional models are included by default but can be skipped individually.

Required models

Model	File	Size	Role
SCRFD_10G (detection)	`models/det_10g.onnx`	16 MB	Face detection + 5-point landmarks
w600k_r50 ArcFace (recognition)	`models/w600k_r50.onnx`	166 MB	512-dim face embeddings
MiniFASNetV2 (PAD)	`models/MiniFASNetV2.onnx`	1.8 MB	Presentation attack detection
HRNet-W18 (MAD)	`models/mad_selfmad_hrnet_w18.onnx`	73 MB	Morphing attack detection
eDifFIQA(T) (quality)	`models/ediffiqa_tiny.onnx`	6.9 MB	ISO 29794-5 quality scoring

Optional models

These models enable additional pipeline stages. When the file is present, the stage is automatically wired into the pipeline at startup. When absent, the stage is silently omitted.

Model	File	Size	Stage
InsightFace genderage (age)	`models/genderage.onnx`	1.3 MB	Age estimation
InsightFace genderage (attributes)	`models/genderage.onnx`	1.3 MB	Gender classification (same file, two adapters)
Deep-Fake-Detector-v2 (deepfake)	`models/deepfake_vit_q.onnx`	~90 MB	Deepfake detection
yakhyo ResNet-18 (head pose)	`models/head_pose_resnet18.onnx`	~45 MB	Head pose estimation + yaw gate
Real-ESRGAN x4plus (super-resolution)	`models/realesrgan_x4plus.onnx`	~65 MB	4x upscaling pre-detect
w600k_mbf ArcFace MobileFaceNet	`models/w600k_mbf.onnx`	~20 MB	Mask-aware recognition (alternative to w600k_r50)

To use lightweight stubs for development without downloading models:

make models-dummy

Build Rust components

The FAISS shard and compaction binaries are written in Rust. Build them once:

make rust-build

Start the server

make demo

This starts the REST gateway on http://localhost:8080 with an in-memory FAISS index (1 API + 5 shard containers via Docker Compose). Any optional model files present in models/ are automatically loaded.

To load a demo gallery (enrols ~20 LFW subjects):

curl -X POST http://localhost:8080/api/v1/demo/load

Run your first search

All biometric endpoints accept multipart/form-data with an image file part and a metadata JSON part.

Enrol a face:

curl -X POST http://localhost:8080/api/v1/enrol \
  -F image=@photo.jpg \
  -F 'metadata={"subject_id":"person-001","partition":"default"}'

Search for it:

curl -X POST http://localhost:8080/api/v1/search \
  -F image=@photo.jpg \
  -F 'metadata={"partition":"default","top_k":5}'

See the REST API reference for full request and response schemas.

Run tests

make test

Runs 368 tests (unit + integration). All tests use in-memory state — no external services required.

make rust-test   # 75 additional Rust workspace tests (requires FAISS)

Generate PDF documentation

make docs-pdf

Builds the Astro docs-site, starts a local server, and prints each page to a combined PDF at docs/ufme-documentation.pdf. Requires Node.js 18+.