Apppublic

Soapppp11/enterprise-access-control-face

sourceHugging Faceupdated 4mo agoView on Hugging Face

1likes

App README

Face Recognition Microservice

A Docker-based Flask microservice for face recognition using InsightFace ArcFace model (buffalo_l).

Features

—✅ Face enrollment (extract and store embeddings)
—✅ Face recognition (match against database)
—✅ REST API with API key authentication
—✅ Persistent face database storage
—✅ Buffalo_l model (high accuracy ~99%)
—✅ GPU support (falls back to CPU)

Quick Start

Health Check

bash

curl https://Soapppp11-enterprise-access-control-face.hf.space/health

Enroll Face

bash

curl -X POST "https://Soapppp11-enterprise-access-control-face.hf.space/enroll" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-face-xyz123" \
  -d '{
    "user_id": 1,
    "image_base64": "base64-encoded-image-data"
  }'

Recognize Face

bash

curl -X POST "https://Soapppp11-enterprise-access-control-face.hf.space/recognize" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-face-xyz123" \
  -d '{
    "image_base64": "base64-encoded-image-data"
  }'

API Endpoints

GET /health

Health check endpoint to verify the service is running.

Response:

json

{
  "status": "ok",
  "model_initialized": true,
  "embeddings_loaded": 5,
  "timestamp": "2026-04-18T17:00:00"
}

POST /enroll

Enroll a face and extract embedding.

Request:

json

{
  "user_id": 1,
  "image_base64": "base64-encoded-face-image"
}

Response:

json

{
  "success": true,
  "data": {
    "user_id": 1,
    "embedding": "base64-encoded-512-dim-vector",
    "message": "Face enrolled successfully"
  }
}

POST /recognize

Recognize face in image and find best match.

Request:

json

{
  "image_base64": "base64-encoded-face-image"
}

Response:

json

{
  "success": true,
  "data": {
    "user_id": 1,
    "similarity": 0.95,
    "is_authorized": true,
    "threshold": 0.6
  }
}

Environment Variables

Configure these in the Space settings:

—FACE_SERVICE_API_KEY: API key for authentication (default: sk-face-xyz123)
—FACE_SERVICE_PORT: Flask port (default: 5000)
—ARCFACE_MODEL: Model to use (default: buffalo_l)
—ARCFACE_DEVICE: Device (0=GPU, -1=CPU; default: 0)
—SIMILARITY_THRESHOLD: Recognition threshold (default: 0.6)
—FACE_DB_PATH: Embedding storage path (default: /data/face_database)

Performance

—First request: ~30-60 seconds (model initialization)
—Subsequent requests: ~0.5-2 seconds
—Memory: ~300MB model + ~10MB per 1000 embeddings

Architecture

Client Request
    ↓
Flask API Endpoint
    ↓
FaceRecognitionModel
    ↓
InsightFace (buffalo_l)
    ↓
Face Embedding (512-dim vector)
    ↓
Store/Compare with Database
    ↓
Response

Troubleshooting

502 Bad Gateway: Service starting or out of memory

—Wait 1-2 minutes for initialization
—Check logs in HF Spaces

401 Unauthorized: Invalid API key

—Verify X-API-Key header is set
—Default key: sk-face-xyz123

License

Apache 2.0

Face Recognition Microservice

Independent Python microservice for face recognition using InsightFace/ArcFace model. Designed to run on a Raspberry Pi or any device with compute resources.

Architecture

Frontend (React Native)
    ↓
Node.js Backend API
    ↓
Face Microservice (Flask) ← Runs on Raspberry Pi or separate host
    └→ InsightFace/ArcFace Model

Features

—✅ Face enrollment (extract & store embeddings)
—✅ Face recognition (identify people in images)
—✅ Embedding retrieval (get stored face vectors)
—✅ Batch operations support
—✅ API key authentication
—✅ Model versioning support (buffalol, buffalom, buffalo_s)

Installation

Prerequisites

—Python 3.8+
—Flask
—InsightFace
—OpenCV

Setup

1.Clone/Copy files to Raspberry Pi:

bash

cd /path/to/face-microservice

1.Create virtual environment:

bash

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

1.Install dependencies:

bash

pip install -r requirements.txt

1.Configure environment:

bash

cp .env.example .env
# Edit .env with your settings

1.Run the service:

bash

python app.py

The service will start on http://0.0.0.0:5000 by default.

Configuration (.env)

env

# Server
DEBUG=False
FACE_SERVICE_HOST=0.0.0.0
FACE_SERVICE_PORT=5000

# Model (buffalo_l=best accuracy, buffalo_m=balanced, buffalo_s=fastest)
ARCFACE_MODEL=buffalo_l
ARCFACE_DEVICE=-1  # 0=GPU, -1=CPU

# Recognition threshold (higher = stricter)
SIMILARITY_THRESHOLD=0.6

# Database
FACE_DB_PATH=./face_database

# Security
FACE_SERVICE_API_KEY=your-secret-key-change-in-production

API Endpoints

All endpoints require X-API-Key header.

Health Check

bash

GET /health

Enroll Face

bash

POST /enroll
Content-Type: application/json
X-API-Key: your-api-key

{
  "user_id": 1,
  "image_base64": "base64-encoded-image-data"
}

Response:

json

{
  "success": true,
  "data": {
    "user_id": 1,
    "embedding": "base64-encoded-512-dim-vector",
    "message": "Face enrolled successfully"
  }
}

Recognize Face

bash

POST /recognize
Content-Type: application/json
X-API-Key: your-api-key

{
  "image_base64": "base64-encoded-image-data"
}

Response:

json

{
  "success": true,
  "data": {
    "user_id": 1,
    "similarity": 0.85,
    "is_authorized": true,
    "threshold": 0.6
  }
}

Get Embedding

bash

GET /embedding/{user_id}
X-API-Key: your-api-key

Delete Embedding

bash

DELETE /embedding/{user_id}
X-API-Key: your-api-key

Reload Database

bash

POST /db/reload
X-API-Key: your-api-key

Database Stats

bash

GET /db/stats
X-API-Key: your-api-key

Deployment on Raspberry Pi

Using Systemd (Auto-start)

Create /etc/systemd/system/face-microservice.service:

ini

[Unit]
Description=Face Recognition Microservice
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/face-microservice
ExecStart=/home/pi/face-microservice/venv/bin/python app.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Then:

bash

sudo systemctl enable face-microservice
sudo systemctl start face-microservice
sudo systemctl status face-microservice

Using Docker

bash

docker build -t face-microservice .
docker run -p 5000:5000 -v /path/to/face_database:/app/face_database face-microservice

Performance Tips

For Raspberry Pi

—Use buffalo_s model for fastest inference
—Set ARCFACE_DEVICE=-1 for CPU (no CUDA needed)
—Use image compression before sending

For better accuracy (with GPU)

—Use buffalo_l model
—Set ARCFACE_DEVICE=0 (requires CUDA)
—Less compression on images

Troubleshooting

Model download fails

bash

python -c "from insightface.app import FaceAnalysis; app = FaceAnalysis(name='buffalo_l'); app.prepare(ctx_id=-1)"

Out of memory on Raspberry Pi

—Use CPU mode (ARCFACE_DEVICE=-1)
—Use smaller model (buffalo_s)
—Resize images before sending

Slow recognition

—Reduce image quality/resolution
—Use buffalo_s model
—Enable GPU if available

Integration with Main Backend

See backend/controllers/face.controller.js for how to call this service.

The main Node.js backend will:

1.Receive image from frontend
2.Send to this microservice for embedding extraction
3.Store embedding in PostgreSQL
4.Return result to frontend

License

Internal Use Only