CV / ArcFace

ArcFace MobileFaceNet

ArcFace 人脸识别（2.04M 参数，LFW 99.4%），支持 reComputer R Series 搭配 Hailo-8 或 Hailo-10H。

15 次下载

大小

3.91 MB

内存

4GB+

精度

Hailo HEF / HailoRT

选择你正在使用的设备，设置指南和文档将相应更新。

平台

推理引擎

快速开始

部署

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

REST API

使用 REST API 进行推理。复制以下命令。

Curl

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

Python

import requests
resp = requests.post(
    "http://<Board_IP>:8000/api/models/arcface_mobilefacenet/predict",
    files={"file": open("face.jpg", "rb")},
    timeout=30,
)
print(resp.json())

模型详情

reComputer R Series (CM5 + Hailo-8)

ArcFace MobileFaceNet 在 reComputer R Series（CM5 + Hailo-8）上运行

ArcFace 搭配 MobileFaceNet 骨干网络，通过 HailoRT 在 Hailo-8 上提取 512 维人脸特征向量。特征向量用于人脸验证与识别，比对本身由客户端使用余弦相似度完成。

本页面向搭载 PCIe Hailo-8 加速器的 reComputer R Series（CM5 + Hailo-8）。

模型信息

属性	值
架构	ArcFace（MobileFaceNet 骨干网络）
任务	人脸识别（特征向量提取）
输入	112x112x3 RGB（letterbox，归一化已编译进 HEF）
输出	512 维人脸特征向量
参数量	2.04M
LFW 准确率	99.4%（Hailo Model Zoo 参考值）
HEF	Hailo Model Zoo v2.19.0，Hailo-8

该准确率来自 Hailo Model Zoo 参考值，不是在 CM5 上实测的结果。

硬件与主机设置

项目	值
开发板	reComputer R Series 搭配 Raspberry Pi CM5
加速器	Hailo-8（PCIe 接口），以 `/dev/hailo0` 暴露
运行时	HailoRT 4.23.x
容器内 Python	3.11, aarch64

在主机上安装 Hailo-8 软件包，并在启动容器前确认驱动与设备就绪：

bash

sudo apt update

# 安装前两个候选包都必须是 4.23.x。
apt-cache policy hailort hailort-pcie-driver

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

# 重启后
hailortcli --version
hailortcli fw-control identify
ls -l /dev/hailo0

该镜像要求的 HailoRT 版本为 4.23.x。如果 apt-cache policy 选中的是 5.x，请勿继续——那是 Hailo-10H 的运行时，与本 Hailo-8 容器不匹配。

使用演示视频运行

bash

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

打开 http://<Board_IP>:8000 查看网页预览。每帧会标注特征向量维度，REST API 返回完整的 512 维向量。

USB 摄像头模式

bash

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

text

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

bash

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

json

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

接口	方法	用途
`/`	GET	网页预览界面
`/api/models/arcface_mobilefacenet/predict`	POST	人脸特征向量（JSON）
`/api/video_feed`	GET	MJPEG 预览流
`/api/config`	GET / POST	读取或修改运行时阈值
`/api/video/upload`	POST	上传源视频
`/api/video/analyze`	POST	开始离线视频分析
`/api/video/status`	GET	读取分析进度
`/api/video/download/{filename}`	GET	下载标注结果

人脸验证不单独提供接口：请在客户端对两个返回向量做余弦相似度比较（先做 L2 归一化）。

实现说明

HEF 内含归一化层，因此应用把画面 letterbox 到 112x112、BGR 转 RGB 后直接送入 uint8 像素。
当 vstream 名称可见时，特征向量取自 arcface_mobilefacenet/fc1 输出；否则使用第一个输出张量。首次推理会打印全部 vstream 名称和 shape，便于在实机上核对映射。
空向量或包含非有限值的向量会被拒绝，不会当作有效结果返回。

开发说明

源码模块：src/rpi5_hailo8_arcface_mobilefacenet/
Dockerfile：docker/hailo8/arcface_mobilefacenet.dockerfile
镜像：ghcr.io/seeed-projects/recomputer-hailo8-cv/arcface_mobilefacenet:latest
HEF：model/arcface_mobilefacenet.hef（4,100,573 字节）
模块使用 HailoRT 4.23 VStreams API 与面向 Hailo-8 编译的 HEF。

输入与输出

输入：图像（112x112 RGB）。输出：512 维人脸特征向量；人脸比对由客户端完成。