sharevent-faces

Self-hosted face detection, recognition & people-grouping microservice for ShareVent. Mirrors the sharevent-nudenet service pattern (its own git repo, GPU container, internal-network-only) but is built on FastAPI + InsightFace (ArcFace buffalo_l) with onnxruntime-gpu and a CPU fallback.

It exposes embedding + clustering endpoints; it stores nothing. The backend (sharevent-be) owns all persistence (faces, persons, links) and all gating. Media is only ever sent here when the gallery_face_grouping module is enabled for an event — see FACE_RECOGNITION_PLAN.md §5 (privacy, non-negotiable).

Biometric embeddings are GDPR Art. 9 special-category data. This service never logs raw embeddings or selfies and persists no media beyond a request lifetime.

Endpoints

Method	Path	Purpose
GET	/healthz	Liveness + model/device report.
POST	/embed	Detect + embed faces in one image (multipart).
POST	/embed/video	Sample + track + one embedding per person-tracklet.
POST	/cluster	HDBSCAN (cosine) over a list of embeddings → labels.
GET	/metrics	Prometheus-style counters (req count, latency, GPU mem).

All non-health endpoints require Authorization: Bearer <FACES_AUTH_TOKEN>.

Full request/response contracts: docs/ARCHITECTURE.md.

Run locally

python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env                            # set FACES_AUTH_TOKEN
uvicorn app.main:app --host 0.0.0.0 --port 5001

Without onnxruntime-gpu + CUDA the service runs on CPU automatically.

Build the container

docker build -t sharevent-faces .
docker run --gpus all -p 5001:5001 --env-file .env sharevent-faces

The InsightFace model is baked into the image at build time (no runtime download).

Status

Service complete (Phases 0–3 of FACE_RECOGNITION_PLAN.md): /embed, /embed/video, /cluster, /metrics and /healthz are all implemented; the buffalo_l model is baked into the image at build time. BE integration (worker, persistence, gating) is Phases 5–9.