# FaceRecognition-server

**Repository Path**: longsanduan/face-recognition-server

## Basic Information

- **Project Name**: FaceRecognition-server
- **Description**: 人脸识别的后台验证服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-06
- **Last Updated**: 2026-02-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 人脸识别系统 - 后端服务

基于 Python + FastAPI 的人脸识别与认证系统后端服务。

## 功能特性

- **人脸检测与对齐**: SCRFD 模型，高精度人脸检测
- **活体检测**: YOLOv11 模型，支持左右摇头、上下点头、张嘴、托下巴等动作验证
- **特征提取**: ArcFace 模型，提取 512 维人脸特征向量
- **向量存储与检索**: PostgreSQL + pgvector，高效向量相似度搜索
- **三大核心功能**: 用户注册、1:1 认证、1:N 识别
- **实时通信**: WebSocket 实时活体检测

## 技术栈

- **语言**: Python 3.9+
- **Web 框架**: FastAPI
- **数据库**: PostgreSQL 14+ with pgvector
- **AI 框架**: 
  - InsightFace (SCRFD, ArcFace)
  - YOLOv11 (活体检测)
  - ONNX Runtime (模型推理)
  - OpenCV (图像处理)
- **ORM**: SQLAlchemy
- **实时通信**: WebSocket

## 项目结构

```
Server-FaceRecognition/
├── main.py                       # 应用入口
├── config.yaml                   # 配置文件
├── requirements.txt              # Python 依赖
├── .env.example                  # 环境变量示例
├── app/
│   ├── api/                      # API 路由
│   │   ├── face.py               # REST API (注册/验证/识别)
│   │   └── websocket.py          # WebSocket API (活体检测)
│   ├── core/                     # 核心模块
│   │   ├── detector.py           # 人脸检测
│   │   ├── aligner.py            # 人脸对齐
│   │   ├── feature_extractor.py  # 特征提取
│   │   ├── pipeline.py           # 处理流程
│   │   └── liveness_session.py   # 活体检测会话管理
│   ├── db/                       # 数据库
│   │   ├── database.py           # 数据库连接
│   │   ├── models.py             # ORM 模型
│   │   └── crud.py               # CRUD 操作
│   ├── schemas/                  # 数据模型
│   │   └── face.py
│   └── utils/                    # 工具函数
│       ├── image.py              # 图片处理
│       └── logger.py             # 日志
├── models/                       # AI 模型文件
│   ├── scrfd_10g_bnkps.onnx      # 人脸检测模型
│   ├── arcface_r100.onnx         # 特征提取模型
│   └── checkface.pt              # YOLOv11 活体检测模型
├── scripts/                      # 工具脚本
│   └── init_db.py                # 数据库初始化
└── logs/                         # 日志文件
```

## 环境要求

- Python 3.9+
- PostgreSQL 14+ with pgvector extension
- 4GB+ RAM
- (可选) NVIDIA GPU with CUDA for faster inference

## 快速开始

### 1. 创建虚拟环境

```bash
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置环境变量

```bash
# Windows
copy .env.example .env

# Linux/Mac
cp .env.example .env
```

编辑 `.env` 文件：
```env
DATABASE_URL=postgresql://postgres:your_password@localhost:5432/check_face
API_HOST=0.0.0.0
API_PORT=8000
MODEL_DIR=models
LOG_LEVEL=INFO
LOG_DIR=logs
```

### 4. 初始化数据库

```bash
# 创建数据库
createdb check_face

# 安装 pgvector 扩展
psql check_face -c "CREATE EXTENSION vector;"

# 运行初始化脚本
python scripts/init_db.py
```

### 5. 下载模型文件

将以下模型文件放置到 `models/` 目录：

- `scrfd_10g_bnkps.onnx` - 人脸检测模型
- `arcface_r100.onnx` - 特征提取模型
- `checkface.pt` - YOLOv11 活体检测模型

### 6. 启动服务

```bash
# 开发模式（自动重载）
python main.py

# 或使用 uvicorn
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

服务将在 `http://localhost:8000` 启动

## API 文档

启动服务后访问：
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

## 主要 API 端点

### 1. 用户注册
```http
POST /api/v1/face/register
Content-Type: application/json

{
  "phone": "13800138000",
  "face_image": "base64_encoded_image"
}
```

### 2. 1:1 身份认证
```http
POST /api/v1/face/verify
Content-Type: application/json

{
  "phone": "13800138000",
  "face_image": "base64_encoded_image"
}
```

### 3. 1:N 身份识别
```http
POST /api/v1/face/identify
Content-Type: application/json

{
  "face_image": "base64_encoded_image"
}
```

### 4. WebSocket 活体检测
```
WebSocket: ws://localhost:8000/ws/liveness/{phone}
```

## 活体检测系统

### 支持的动作类型

| 动作类型 | 类别名称 | 验证规则 |
|---------|---------|---------|
| 左右摇头 | YAW | 必须检测到 left_shake 和 right_shake 各至少一次 |
| 上下点头 | NOD | 必须检测到 up_head 和 down_head 各至少一次 |
| 张嘴 | MOUTH_OPEN | 检测到 open_mouth 即可通过 |
| 托下巴 | CHIN | 检测到 chin_hold 即可通过 |

### 双向动作验证机制

为提高安全性，YAW 和 NOD 动作采用**双向验证**机制：

**YAW（摇头）验证规则**:
- 必须检测到 `left_shake`（向左摇头）和 `right_shake`（向右摇头）各至少一次
- 只完成单方向摇头无法通过验证
- 两个方向都完成后才标记动作完成

**NOD（点头）验证规则**:
- 必须检测到 `up_head`（向上点头）和 `down_head`（向下点头）各至少一次
- 只完成单方向点头无法通过验证
- 两个方向都完成后才标记动作完成

### 验证流程

1. 客户端连接 WebSocket，服务器随机生成2个动作序列
2. 客户端发送帧数据（包含图片和元数据）
3. 服务器使用 YOLOv11 模型推理，检测动作类型
4. 根据当前要求的动作类型验证是否匹配
5. 对于 YAW 和 NOD，标记对应的子动作完成状态
6. 所有子动作都完成后，标记整个动作完成
7. 发送 `ACTION_COMPLETED` 或 `VERIFICATION_FAILED` 消息
8. 所有动作完成后进行最终人脸识别

### 配置参数

```python
# 模型配置
MODEL_PATH = "models/checkface.pt"  # YOLOv11 模型路径
CONF_THRESHOLD = 0.51  # 置信度阈值

# 会话配置
num_actions = 2  # 随机选择2个动作
timeout = 600  # 会话超时时间（秒）
action_timeout = 10  # 单个动作超时时间（秒）
```

## 配置说明

编辑 `config.yaml` 文件可以调整：
- 数据库连接
- 模型路径
- 相似度阈值
- API速率限制
- 日志级别

## 性能优化

1. **使用GPU加速**: 安装 `onnxruntime-gpu` 替代 `onnxruntime`
2. **数据库优化**: 调整 pgvector 索引参数
3. **缓存**: 使用 Redis 缓存频繁查询的特征向量
4. **负载均衡**: 使用 Nginx + Gunicorn 部署多个worker

## 故障排查

### 模型加载失败
- 检查模型文件是否存在于 `models/` 目录
- 检查模型文件是否完整（未损坏）

### 数据库连接失败
- 检查 PostgreSQL 服务是否运行
- 检查 pgvector 扩展是否安装
- 检查数据库连接字符串是否正确

### 内存不足
- 减少并发请求数
- 使用更小的模型（如 MobileFaceNet）
- 增加系统内存

## 测试

```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_face_detector.py

# 测试活体检测子动作验证
python test_sub_actions.py
```

## 许可证

MIT License