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 the following models into models/:

Model	File	Size
SCRFD_10G (detection)	models/det_10g.onnx	16 MB
w600k_r50 ArcFace (recognition)	models/w600k_r50.onnx	166 MB
MiniFASNetV2 (PAD)	models/MiniFASNetV2.onnx	1.8 MB
eDifFIQA(T) (quality)	models/ediffiqa_t.onnx	88 MB

To download stub/dummy models for development without running inference:

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.

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

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

Run your first search

Enrol a face:

curl -X POST http://localhost:8080/api/v1/enrol \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpeg>",
    "subject_id": "person-001",
    "partition": "default"
  }'

Search for it:

curl -X POST http://localhost:8080/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpeg>",
    "partition": "default",
    "top_k": 5
  }'

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

Run tests

make test

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