trueface/visionbox

VisionBox Docker镜像文档

概述

VisionBox是一个基于Docker的视觉识别服务镜像，基于Ubuntu 20.04 LTS构建，提供全面的人脸相关智能分析功能。该镜像集成了人脸检测、识别、活体检测、属性分析（眼镜/口罩佩戴）等核心能力，支持多数据库后端存储与动态模型切换，通过丰富的API端点满足各类视觉识别场景需求。

核心功能与特性

人脸检测与识别

• 人脸检测：通过/face-detect端点检测图像中的人脸，支持detect_all标志控制检测全部人脸或仅最大人脸，返回高精度人脸特征（faceprint）
• 人脸识别：/identify端点支持视频输入，识别指定集合中的人脸并返回时间戳；/identify/zipfile端点支持批量识别压缩包中的图像
• 多候选人返回：/identify默认返回Top 3候选人，可通过num_candidates参数自定义数量

属性分析

• 眼镜检测：/v1/detect_glasses端点判断图像中人员是否佩戴眼镜
• 口罩检测：/v1/detect_mask端点判断图像中人员是否佩戴口罩

活体与防欺诈

• 视频活体检测：/liveness端点通过视频输入检测真实人脸（检测眨眼动作）
• 主动防欺诈：/active-spoof端点接收近距离和远距离两张图像进行欺诈检测

数据管理

• 集合管理：/v1/collection/<namespace>/<collection_id>端点列出集合中所有身份；支持命名空间（/namespaces）和集合（/collections）的增删查操作
• 数据库支持：PostgreSQL后端用于集中式集合存储；SQLite用于用户认证数据（替代原MySQL）
• 图像存储：/enroll端点支持store_image标志（opt-in）将注册图像存入数据库，用于UI展示

配置与模型

• 动态模型切换：根据访问的数据库自动切换人脸识别模型（如TFV5/LITE），默认使用高精度TFV5模型
• 配置管理：/config端点查看当前配置；通过./collections卷中的tfsdk_options.json自定义SDK配置（如识别模型、阈值等）
• 系统兼容性：支持无AVX2指令集的CPU，自动利用GPU（若存在）提升性能

安全与认证

• OAUTH2认证：opt-in特性，创建首个用户后启用访问控制
• 用户管理：支持用户注册（/register）、登录（/login）和注销功能，注销后临时令牌失效
• 错误处理：优化错误响应（如/spdetect、/match），增加命名空间存在性检查

使用场景与适用范围

• 身份验证系统：门禁控制、设备登录、用户身份验证
• 安全监控：公共场所人脸检测、异常行为识别、防欺诈验证
• 考勤管理：员工人脸打卡、出勤记录自动化
• 公共卫生管理：口罩佩戴检测、疫情防控场景应用
• 智能分析：人员属性统计、客户行为分析

使用方法与配置说明

基础部署

Docker Run命令

bash
docker run -d \
  -p 8080:8080 \
  -v ./collections:/app/collections \
  -v ./config:/app/config \
  --name visionbox \
  docker.xuanyuan.run/visionbox:latest

• -v ./collections：挂载集合数据卷（存储人脸特征、注册图像等）
• -v ./config：挂载配置卷（存放tfsdk_options.json）
• -p 8080:8080：映射服务端口

Docker Compose配置（PostgreSQL后端）

yaml
version: '3'
services:
  visionbox:
    image: docker.xuanyuan.run/visionbox:latest
    ports:
      - "8080:8080"
    volumes:
      - ./collections:/app/collections
      - ./config:/app/config
    environment:
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_USER=visionbox_user
      - POSTGRES_PASSWORD=secure_password
      - POSTGRES_DB=visionbox_db
      - WORKERS=1  # 避免GPU内存不足，默认1个工作进程
    depends_on:
      - postgres

  postgres:
    image: docker.xuanyuan.run/postgres:13
    environment:
      - POSTGRES_USER=visionbox_user
      - POSTGRES_PASSWORD=secure_password
      - POSTGRES_DB=visionbox_db
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

配置文件说明

tfsdk_options.json

自定义SDK配置文件，存放于./config卷中，示例：

json
{
  "recognition_model": "TFV5",  // 人脸识别模型：TFV5（高精度）或LITE（轻量）
  "face_detection_threshold": 0.8  // 人脸检测阈值
}

• 若文件不存在，系统使用默认配置
• 支持所有SDK配置选项（详见TrueFace SDK文档）

API使用示例

1. 人脸检测

检测图像中所有人脸：

bash
curl -X POST http://localhost:8080/face-detect \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/person.jpg",
    "detect_all": true
  }'

2. 人脸识别（视频）

识别视频中的人脸并返回时间戳：

bash
curl -X POST http://localhost:8080/identify/video \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/surveillance.mp4",
    "collection_id": "employee_collection",
    "namespace": "company"
  }'

3. 口罩检测

检测人员是否佩戴口罩：

bash
curl -X POST http://localhost:8080/v1/detect_mask \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/crowd.jpg"
  }'

4. 查看系统配置

bash
curl http://localhost:8080/config

版本关键特性摘要

• 0.8.4：新增口罩/眼镜检测端点、视频识别时间戳、PostgreSQL集成优化
• 0.8.2：动态模型切换、配置端点、视频活体检测、TFV5默认模型
• 0.8.0：PostgreSQL支持、批量识别（zipfile）、全量SDK配置选项
• 0.7.0：C++ SDK迁移、SQLite集合存储、用户认证系统
• 0.6.x：模型优化、spoof检测增强、数据库连接支持