CV / RetinaFace

RetinaFace

The current service loads the MobileNet-backbone model and exposes confidence filtering through its API.

4 次下载

精度

RKNN

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

平台

尺寸

推理引擎

快速开始

部署

sudo docker run --rm --privileged --net=host -e RKNN_LOG_LEVEL=0 \
  --device /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-retinaface:latest \
  python web_service.py --platform rk3576 --model_dir /app/model --camera_id -1 --host 0.0.0.0 --port 8000

REST API

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

Curl

curl http://localhost:8080/v1/chat/completions -d '{
  "model": "retinaface-rknn",
  "messages": [{"role": "user", "content": "Hello"}]
}'

Python

import requests

resp = requests.post(
    "http://localhost:8080/v1/chat/completions",
    json={"model": "retinaface-rknn", "messages": [{"role": "user", "content": "Hello"}]},
)
print(resp.json())

模型详情

在 reComputer RK3576 和 RK3588 上运行 RetinaFace

本文介绍 reComputer-RK-CV 中的 RetinaFace 服务。它通过 RKNN 加速检测人脸和五个人脸关键点，并提供图像、摄像头、本地视频和上传视频模式。

模型信息

属性	值
当前模型	`model/retinaface_mobile.rknn`
打包的替代模型	`model/retinaface_resnet50.rknn`
输入	`320 x 320` letterbox RGB
输出	人脸框、置信度和五个关键点
NMS	固定 IoU 阈值 `0.5`

运行服务

RK3576

bash

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  --device /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-retinaface:latest \
  python web_service.py --platform rk3576 --model_dir /app/model \
  --camera_id -1 --host 0.0.0.0 --port 8000

RK3588

bash

sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  --device /dev/dri/renderD129:/dev/dri/renderD129 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-retinaface:latest \
  python web_service.py --platform rk3588 --model_dir /app/model \
  --camera_id -1 --host 0.0.0.0 --port 8000

打开 http://<BOARD_IP>:8000 或 /docs。使用摄像头时映射 /dev/videoN 并指定 --camera_id N，使用本地视频时传入 --video video/test.mp4。

启动参数

参数	默认值	说明
`--platform`	必填	`rk3576` 或 `rk3588`。
`--model_dir`	`model`	RetinaFace RKNN 文件和 `test.jpg`。
`--camera_id`	`-1`	摄像头索引；`-1` 禁用采集。
`--video`, `--video_path`	无	循环播放的本地视频；优先级高于摄像头。
`--host` / `--port`	`0.0.0.0` / `8000`	服务地址和端口。

RKNN_LOG_LEVEL=0 会隐藏已确认无害的静态形状初始化消息。诊断 RKNN 启动问题时请移除该设置。

REST API

端点： POST /api/models/retinaface/predict

bash

curl -X POST "http://<BOARD_IP>:8000/api/models/retinaface/predict" \
  -F "file=@test.jpg" -F "threshold=0.5"

每个结果包含 confidence、表示为 [x1,y1,x2,y2] 的 box，以及五个 landmarks。可使用 POST /api/config 和类似 {"threshold":0.5} 的 JSON 更新预览/视频阈值。

响应字段示例：

json

{
  "success": true,
  "model": "retinaface",
  "result": {
    "count": 1,
    "faces": [
      {
        "confidence": 0.96,
        "box": [120, 80, 310, 290],
        "landmarks": [[166, 145], [255, 144], [210, 190], [176, 232], [247, 231]]
      }
    ]
  }
}

通用 topk 配置字段仅为服务兼容性保留，实际不会使用。NMS 使用固定的 0.5 IoU 阈值。

端点	用途
`GET /api/health`	平台、模型名称和就绪状态。
`GET /api/video_feed`	以 MJPEG 提供最新的人脸框和关键点。
`POST /api/video/upload`	上传 MP4。
`POST /api/video/analyze`	分析已上传的 `filename`。
`GET /api/video/status`	进度和错误。
`GET /api/video/list`	已上传和生成的 MP4 文件。
`GET /api/video/download/{filename}`	下载结果。

上游构造函数目前会显式加载 retinaface_mobile.rknn。使用 retinaface_resnet50.rknn 需要修改 task_runtime.py 并验证相同的三输出布局；仅通过 Docker 命令参数无法选择该模型。帧会 letterbox 到 320 x 320，从 BGR 转换为 RGB，结合先验框和五个关键点进行解码，恢复到源图像坐标，按置信度筛选，并使用 NMS 处理。

本地构建

bash

docker build -f docker/rk3576/retinaface.dockerfile \
  -t rk3576-retinaface:local src/rk3576_retinaface

docker build -f docker/rk3588/retinaface.dockerfile \
  -t rk3588-retinaface:local src/rk3588_retinaface

输入与输出

Input: image, video frame, or camera frame. Output: face boxes, confidence scores, and five landmarks.