Configuration Reference

UFME is configured via a YAML file (default: config/config.yaml) or environment variables. All thresholds are policy values — they are injected at startup as pure function parameters, never embedded in domain logic.

Quality gate

Controls whether a face image is accepted or rejected before extraction.

quality:
  enabled: true
  min_score: 0.5        # 0.0–1.0; images below this are rejected (HTTP 422)
  model: ediffiqa_t     # quality model identifier

Key	Default	Description
quality.enabled	true	Set to false to disable the quality gate entirely
quality.min_score	0.5	Minimum acceptable quality score

Presentation attack detection (PAD)

Rejects spoofed inputs (printed photos, replay attacks, 3D masks).

pad:
  enabled: true
  max_spoof_score: 0.5  # scores above this are rejected (HTTP 451)
  model: minifasnetv2

Key	Default	Description
pad.enabled	true	Set to false to disable PAD
pad.max_spoof_score	0.5	Spoof probability threshold (0–1)

Morphing attack detection (MAD)

Rejects morphed document photos at enrolment.

mad:
  enabled: true
  max_morph_score: 0.5  # scores above this are rejected (HTTP 422)
  model: hrnet_w18

Key	Default	Description
mad.enabled	true	Set to false to disable MAD (not recommended for production)
mad.max_morph_score	0.5	Morphing probability threshold (0–1)

FAISS index

Controls vector search behaviour.

faiss:
  nlist: 4096           # number of IVF Voronoi cells (rule of thumb: sqrt(N))
  nprobe: 64            # cells visited per query (higher = better recall, slower)
  m: 64                 # PQ sub-vectors (64 bytes/vector compressed)
  nbits: 8              # bits per PQ codebook entry
  rerank_k: 100         # candidates fetched before exact reranking
  shards:
    - host: localhost
      port: 50051
    - host: localhost
      port: 50052

Key	Default	Description
faiss.nlist	4096	IVF cell count — tune to sqrt(gallery_size)
faiss.nprobe	64	Search breadth — increase for higher recall at cost of latency
faiss.m	64	PQ sub-vectors — 64 gives 64 bytes/vector (32x compression from 2048)
faiss.rerank_k	100	Candidates retrieved per shard before exact distance reranking

Detection

detection:
  model: scrfd_10g
  confidence_threshold: 0.5
  nms_threshold: 0.4
  input_size: [640, 640]

Recognition

recognition:
  model: arcface-w600k-r50
  embedding_dim: 512
  normalize: true       # L2-normalise embeddings before storage and search

Pipeline

pipeline:
  workers: 4            # concurrent pipeline worker coroutines
  queue_size: 128       # async queue depth between stages

Server

server:
  host: 0.0.0.0
  port: 8080
  log_level: info       # debug | info | warning | error

Environment variable overrides

Any config key can be overridden with an environment variable using the pattern UFME__<SECTION>__<KEY> (double underscore separator, uppercase):

UFME__QUALITY__MIN_SCORE=0.7
UFME__PAD__ENABLED=false
UFME__SERVER__PORT=9090