人脸识别服务 API

该服务提供一个用于人脸向量化的小型 REST API。

基础 URL

• 默认地址：http://<host>:9000

• Docker 容器监听 9000 端口。

  • 开发环境（docker-compose.yml）：启动 uvicorn，默认 1 个 worker（1 个进程），并启用访问日志。

  • 生产环境（docker-compose.prod.yml）：启动 uvicorn，配置 --workers 2（两个进程）和 --no-access-log。

    • 每个 worker 加载自己的模型副本。

接口端点

GET /health

健康检查/就绪状态检查。

响应

{"status":"ok"}

未就绪状态 (503)

当 worker 仍在加载模型时返回此状态。

{"status":"not_ready"}

POST /faces/vectorize

上传人脸图像（multipart/form-data 格式）并获取其特征向量。

请求

• Content-Type：multipart/form-data
• 文件字段名：image（推荐）或 file

示例 (curl)

curl -F "image=@/path/to/face.jpg" http://localhost:9000/faces/vectorize

成功响应 (200)

{
  "status": "success",
  "embedding": [0.0123, -0.0456, 0.0789]
}

错误响应

• 400 {"status":"missing_image"}：未上传文件
• 400 {"status":"invalid_image"}：图像无法读取或无效
• 422 {"status":"no_face"}：未检测到人脸
• 422 {"status":"multiple_faces","face_count":2}：检测到多张人脸
• 500 {"status":"error"}：内部错误

日志记录

该服务会对每个请求记录以下结果之一：

• 成功：检测到 1 张人脸。
• 失败：未检测到人脸。
• 失败：检测到多张人脸。
• 失败：图像无效或服务器错误。