ArcFace MobileFaceNet en reComputer R Series (CM5 + Hailo-8)

ArcFace con backbone MobileFaceNet extrae embeddings faciales de 512 dimensiones en Hailo-8 mediante HailoRT. El embedding se usa para verificación e identificación facial; la comparación la realiza el cliente con similitud de coseno.

Esta página está dirigida a reComputer R Series (CM5 + Hailo-8) con un acelerador PCIe Hailo-8.

Información del modelo

La precisión es la referencia de Hailo Model Zoo; no es un benchmark medido en CM5.

Hardware y configuración del host

Instala los paquetes de Hailo-8 en el host y confirma que el driver y el dispositivo están listos antes de iniciar el contenedor:

sudo apt update

# Ambos candidatos deben ser 4.23.x antes de la instalación.
apt-cache policy hailort hailort-pcie-driver

sudo apt install hailort=4.23.0 hailort-pcie-driver=4.23.0
sudo reboot

# Después de reiniciar
hailortcli --version
hailortcli fw-control identify
ls -l /dev/hailo0

La versión esperada de HailoRT para esta imagen es 4.23.x. No continúes si apt-cache policy selecciona HailoRT 5.x; ese runtime corresponde a Hailo-10H y no es compatible con este contenedor Hailo-8.

Ejecución con el vídeo de demostración

sudo docker run --rm \
  --name cm5-hailo8-arcface \
  --privileged \
  --net=host \
  -e PYTHONUNBUFFERED=1 \
  --device /dev/hailo0:/dev/hailo0 \
  -v /usr/lib/libhailort.so.4.23.0:/usr/lib/libhailort.so.4.23.0:ro \
  -v /usr/lib/libhailort.so:/usr/lib/libhailort.so:ro \
  ghcr.io/seeed-projects/recomputer-hailo8-cv/arcface_mobilefacenet:latest \
  python web_detection.py --model_path model/arcface_mobilefacenet.hef --video_path video/test.mp4

Abre http://<Board_IP>:8000 para ver la vista previa web. Cada fotograma se anota con la dimensión del embedding y la REST API devuelve el vector completo de 512 dimensiones.

Modo cámara USB

sudo docker run --rm \
  --name cm5-hailo8-arcface \
  --privileged \
  --net=host \
  -e PYTHONUNBUFFERED=1 \
  --device /dev/hailo0:/dev/hailo0 \
  --device /dev/video0:/dev/video0 \
  -v /usr/lib/libhailort.so.4.23.0:/usr/lib/libhailort.so.4.23.0:ro \
  -v /usr/lib/libhailort.so:/usr/lib/libhailort.so:ro \
  ghcr.io/seeed-projects/recomputer-hailo8-cv/arcface_mobilefacenet:latest \
  python web_detection.py --model_path model/arcface_mobilefacenet.hef --camera_id 0

REST API

POST http://<Board_IP>:8000/api/models/arcface_mobilefacenet/predict

curl -X POST "http://<Board_IP>:8000/api/models/arcface_mobilefacenet/predict" \
  -F "file=@face.jpg"

{
  "success": true,
  "source": "uploaded image",
  "embedding": [0.023, -0.156, 0.089, "..."],
  "dimension": 512,
  "image": { "width": 1280, "height": 720 }
}

La verificación facial no se expone como endpoint independiente: compara dos embeddings devueltos con similitud de coseno en el cliente (normaliza ambos vectores con L2 primero).

Notas de implementación

• El HEF incluye su propia capa de normalización, así que la aplicación aplica letterbox a 112x112, convierte BGR a RGB y envía píxeles uint8 sin normalizar.
• El embedding se lee de la salida arcface_mobilefacenet/fc1 cuando el nombre del vstream está disponible; en caso contrario se usa el primer tensor de salida. La primera inferencia registra todos los nombres y shapes de los vstreams para verificar la correspondencia en el hardware.
• Los embeddings vacíos o con valores no finitos se rechazan en lugar de devolverse como resultado válido.

Notas de desarrollo

• Módulo fuente: src/rpi5_hailo8_arcface_mobilefacenet/
• Dockerfile: docker/hailo8/arcface_mobilefacenet.dockerfile
• Contenedor: ghcr.io/seeed-projects/recomputer-hailo8-cv/arcface_mobilefacenet:latest
• HEF: model/arcface_mobilefacenet.hef (4.100.573 bytes)
• El módulo usa la API VStreams de HailoRT 4.23 y un HEF específico para Hailo-8.