# face-project

**Repository Path**: work_project_item/face-project

## Basic Information

- **Project Name**: face-project
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 人脸识别系统

基于 InsightFace 的人脸识别、特征提取和比对系统，包含完整的前后端实现。

## 功能特性

- **人脸注册**: 上传包含人脸的图片，系统自动提取512维特征向量并存储到数据库
- **人脸识别**: 上传图片，系统在数据库中查找匹配的人脸，返回相似度结果
- **人脸比对**: 上传两张图片，直接比对其中的人脸相似度
- **记录管理**: 查看、删除已注册的人脸记录

## 技术栈

### 后端
- **Python 3.8+**
- **FastAPI**: 现代、快速的 Web 框架
- **InsightFace**: 高精度人脸识别库（ArcFace模型）
- **SQLite**: 轻量级数据库，存储人脸特征向量
- **OpenCV**: 图像处理
- **NumPy**: 数值计算

### 前端
- **React 18**: UI框架
- **TypeScript**: 类型安全
- **Vite**: 快速构建工具
- **Axios**: HTTP客户端

## 项目结构

```
face-project/
├── backend/                 # Python后端
│   ├── run.py              # 简化启动脚本（推荐使用）
│   ├── download_model.py   # 模型下载工具
│   ├── app/
│   │   ├── main.py         # FastAPI应用入口
│   │   ├── config.py        # 统一配置管理
│   │   ├── models/         # 数据模型
│   │   │   ├── database.py # SQLite数据库连接
│   │   │   └── face.py     # 人脸数据模型
│   │   ├── services/       # 业务逻辑
│   │   │   ├── face_service.py    # 人脸识别服务
│   │   │   └── storage_service.py # 存储服务
│   │   ├── api/            # API路由
│   │   │   └── routes.py   # 人脸识别API
│   │   └── utils/          # 工具函数
│   │       └── face_utils.py # 人脸处理工具
│   └── requirements.txt    # Python依赖
├── frontend/               # React前端
│   ├── src/
│   │   ├── components/     # 组件
│   │   │   ├── ImageUpload.tsx    # 图片上传组件
│   │   │   ├── FaceResult.tsx     # 识别结果展示
│   │   │   └── CompareFace.tsx    # 人脸比对组件
│   │   ├── services/       # API服务
│   │   │   └── api.ts      # 后端API调用
│   │   ├── types/          # TypeScript类型
│   │   │   └── face.ts     # 人脸相关类型
│   │   ├── App.tsx         # 主应用组件
│   │   └── main.tsx        # 入口文件
│   ├── package.json
│   └── vite.config.ts
├── storage/               # 统一存储目录（自动创建）
│   ├── database/          # 数据库文件
│   │   └── face_records.db
│   ├── models/            # InsightFace模型文件
│   └── uploads/           # 上传的图片文件
├── database/               # 数据库脚本（参考）
│   └── init.sql           # 初始化SQL
└── README.md              # 项目说明文档
```

## 安装步骤

### 1. 环境要求

- Python 3.8 或更高版本（推荐 3.9+）
- Node.js 16 或更高版本（推荐 18+）
- npm 或 yarn（Node.js 自带 npm）

### 2. 系统要求

#### 最低配置
- **CPU**: 双核及以上（支持 x86_64 或 ARM64）
- **内存**: 4GB RAM
- **存储**: 至少 2GB 可用空间
  - 项目代码: ~50MB
  - Python 依赖: ~500MB
  - Node.js 依赖: ~200MB
  - 模型文件: 100-200MB（首次下载）
  - 运行时数据: 根据使用量增长
- **网络**: 首次运行需要下载模型文件（约 100-200MB），需要稳定的互联网连接
- **端口**: 默认端口 8000（可配置），确保端口未被占用

#### 推荐配置
- **CPU**: 四核及以上
- **内存**: 8GB RAM 或更多
- **存储**: 10GB+ 可用空间
- **GPU**: 可选（支持 CUDA，可加速推理）
- **操作系统**: Windows 10/11、Linux（Ubuntu/Debian/CentOS 等）、macOS（64位系统）

#### 特殊说明
- **Windows 系统**: 支持 PowerShell 和 CMD，可直接使用 `python run.py` 启动
- **Linux/Mac 系统**: 支持 bash shell，可使用 `start.sh` 和 `stop.sh` 脚本管理服务
- **GPU 支持（可选）**: 如需 GPU 加速，需要 NVIDIA GPU（支持 CUDA）、CUDA Toolkit 和 cuDNN，并修改 `face_service.py` 中的执行提供者配置

#### 运行时资源消耗
- **CPU**: 中等（人脸检测和特征提取时）
- **内存**: 约 500MB-2GB（取决于模型和并发请求）
- **磁盘 I/O**: 低（主要读写图片和数据库）

### 3. 后端安装

```bash
# 进入后端目录
cd backend

# 创建虚拟环境（推荐）
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

### 4. 前端安装

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install
# 或
yarn install
```

## 配置说明

### 后端配置

后端使用环境变量进行配置，可以通过创建 `.env` 文件来设置（参考 `.env.example`）：

```env
# 数据库配置（可选，默认在 storage/database/face_records.db）
DATABASE_PATH=./storage/database/face_records.db

# 图片存储路径（可选，默认在 storage/uploads/）
IMAGE_STORAGE_PATH=./storage/uploads

# InsightFace模型名称 (buffalo_l, buffalo_s, antelopev2等)
FACE_MODEL_NAME=buffalo_l

# 相似度阈值 (0.0-1.0)
SIMILARITY_THRESHOLD=0.6

# 服务器配置
HOST=0.0.0.0
PORT=8000
```

**注意**: 
- `buffalo_l` 模型精度更高但速度较慢，`buffalo_s` 模型速度更快但精度略低
- 首次运行时会自动下载模型文件（约100MB+），请确保网络连接正常
- **存储目录结构**：所有存储文件统一存储在项目根目录下的 `storage/` 文件夹：
  - `storage/database/` - 数据库文件
  - `storage/models/` - 模型文件
  - `storage/uploads/` - 上传的图片文件
- 启动服务时会自动创建所有必需的目录

### 前端配置

前端API地址在 `frontend/src/services/api.ts` 中配置。

**开发环境**：使用相对路径，通过Vite代理转发到后端（配置在 `vite.config.ts` 中）

**生产环境**：使用相对路径（空字符串），因为前后端使用相同的地址和端口

如需修改，可以创建 `.env.production` 文件设置 `VITE_API_BASE_URL`

## 运行项目

### 1. 启动后端

**方式一：Linux启动脚本（推荐，支持自定义端口和前后台运行）**

```bash
cd backend

# 给脚本添加执行权限（首次使用）
chmod +x start.sh

# 交互式启动（会提示输入端口号和运行模式）
./start.sh

# 前台运行在指定端口
./start.sh -p 8080 -f

# 后台运行在指定端口
./start.sh -p 8080 -b

# 停止后台服务
./start.sh --stop

# 查看帮助
./start.sh --help
```

启动脚本功能：
- 支持自定义端口号（交互式输入或命令行参数）
- 支持前台运行（适合开发调试）和后台运行（适合生产环境）
- 自动检查Python环境、虚拟环境和依赖
- 自动检查端口占用情况
- 后台运行时自动生成PID文件和日志文件
- 支持停止后台运行的服务

**停止服务**

使用独立的停止脚本：

```bash
cd backend

# 给脚本添加执行权限（首次使用）
chmod +x stop.sh

# 通过PID文件停止服务（推荐）
./stop.sh

# 通过端口号停止服务
./stop.sh -p 8000

# 查看服务状态
./stop.sh --status

# 强制停止服务
./stop.sh -f

# 查看帮助
./stop.sh --help
```

停止脚本功能：
- 自动查找并停止后台运行的服务
- 支持通过PID文件停止（由start.sh启动的服务）
- 支持通过端口号查找并停止服务
- 优雅停止（先发送SIGTERM，等待进程正常退出）
- 如果优雅停止失败，自动强制终止（SIGKILL）
- 支持查看服务运行状态
- 自动清理PID文件

**方式二：简化启动（推荐）**

```bash
cd backend

# 激活虚拟环境（如果使用）
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 运行服务器（简单命令）
python run.py
```

**方式三：使用 uvicorn 命令**

```bash
cd backend

# 激活虚拟环境（如果使用）
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 运行服务器
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

后端服务将在 `http://localhost:8000` 启动（默认端口）。

API文档可在 `http://localhost:8000/docs` 查看。

### 2. 启动前端

```bash
cd frontend

# 开发模式
npm run dev
# 或
yarn dev
```

前端服务将在 `http://localhost:3000` 启动。

## 打包和部署

### 前后端统一部署（推荐）

系统支持将前端打包后由后端服务统一提供，前后端使用相同的地址和端口。

#### 1. 打包前端

```bash
cd frontend

# 安装依赖（如果还没有安装）
npm install

# 打包前端（生成dist目录）
npm run build
```

打包完成后，会在 `frontend/dist` 目录下生成前端静态文件。

#### 2. 启动后端服务（自动提供前端）

启动后端服务时，如果检测到 `frontend/dist` 目录存在，会自动提供前端静态文件服务：

```bash
cd backend

# 使用启动脚本（推荐）
./start.sh -p 8000 -f

# 或使用简化启动
python run.py
```

启动后：
- 访问 `http://localhost:8000` 或 `http://你的IP:8000` 即可访问前端页面
- 访问 `http://localhost:8000/api/...` 访问后端API
- 访问 `http://localhost:8000/docs` 查看API文档

**优势**：
- 前后端使用相同的地址和端口，无需配置跨域
- 部署简单，只需启动一个服务
- 适合单机部署和小型项目

**注意事项**：
- 确保先打包前端（`npm run build`），否则后端只会提供API服务
- 前端打包后，所有API请求会自动使用相对路径，无需额外配置
- 如果修改了前端代码，需要重新打包并重启后端服务

## API 文档

### 1. 注册人脸

**POST** `/api/face/register`

上传图片，提取特征，存储到数据库。

**请求参数**:
- `file` (File): 图片文件
- `name` (String, 可选): 人员姓名

**响应示例**:
```json
{
  "success": true,
  "message": "人脸注册成功",
  "data": {
    "id": 1,
    "name": "张三",
    "image_path": "uploads/20231126_103000_abc123.jpg"
  }
}
```

### 2. 识别人脸

**POST** `/api/face/recognize`

上传图片，在数据库中查找匹配的人脸。

**请求参数**:
- `file` (File): 图片文件

**响应示例**:
```json
{
  "success": true,
  "message": "识别完成",
  "data": {
    "faces_detected": 1,
    "matches": [
      {
        "id": 1,
        "name": "张三",
        "image_path": "uploads/20231126_103000_abc123.jpg",
        "similarity": 0.95
      }
    ]
  }
}
```

### 3. 比对人脸

**POST** `/api/face/compare`

比对两张图片中的人脸。

**请求参数**:
- `file1` (File): 第一张图片
- `file2` (File): 第二张图片

**响应示例**:
```json
{
  "success": true,
  "message": "比对完成",
  "data": {
    "similarity": 0.92,
    "is_match": true
  }
}
```

### 4. 查询所有记录

**GET** `/api/face/records`

获取数据库中所有人脸记录。

**响应示例**:
```json
{
  "success": true,
  "message": "查询成功",
  "data": [
    {
      "id": 1,
      "name": "张三",
      "image_path": "uploads/20231126_103000_abc123.jpg",
      "feature_vector": [0.1, 0.2, ...],
      "created_at": "2023-11-26T10:30:00",
      "updated_at": "2023-11-26T10:30:00"
    }
  ]
}
```

### 5. 查询单条记录

**GET** `/api/face/records/{record_id}`

获取指定ID的人脸记录。

### 6. 删除记录

**DELETE** `/api/face/records/{record_id}`

删除指定ID的人脸记录（同时删除关联的图片文件）。

## 使用说明

### 注册人脸

1. 在"注册人脸"标签页
2. 输入人员姓名（可选）
3. 上传包含人脸的图片
4. 系统自动提取特征并存储

### 识别人脸

1. 在"识别人脸"标签页
2. 上传要识别的图片
3. 系统在数据库中查找匹配的人脸
4. 显示匹配结果和相似度

### 人脸比对

1. 在"人脸比对"标签页
2. 上传两张图片
3. 点击"开始比对"
4. 查看相似度结果

### 记录管理

1. 在"记录管理"标签页
2. 查看所有人脸记录
3. 可以删除不需要的记录

## 技术细节

### 人脸识别处理流程

本项目使用 InsightFace 库，内部集成了 RetinaFace 和 ArcFace 模型。完整的人脸识别流程如下：

1. **输入：整张图片**
   - 接收原始图片（支持常见图片格式：JPG、PNG等）

2. **人脸检测（RetinaFace）**
   - 使用 RetinaFace 模型检测图片中的人脸
   - 输出：人脸边界框（bbox）和五个关键点坐标
   - 五个关键点包括：左眼、右眼、鼻尖、左嘴角、右嘴角

3. **人脸对齐**
   - 根据检测到的五个关键点，使用仿射变换将人脸对齐到标准姿态
   - 这一步确保人脸处于正面、居中的标准状态，提高后续特征提取的准确性

4. **裁剪成 112×112**
   - 将对齐后的人脸区域裁剪并缩放到 112×112 像素
   - 这是 ArcFace 模型的标准输入尺寸

5. **特征提取（ArcFace）**
   - 使用 ArcFace 模型从对齐后的人脸图像中提取特征向量
   - 输出：512维归一化的特征向量

**注意**：以上所有步骤都在 InsightFace 的 `FaceAnalysis.get()` 方法内部自动完成，代码中只需要调用 `model.get(image)` 即可获得包含检测结果和特征向量的完整信息。

### 特征向量

- 使用 InsightFace 的 ArcFace 模型提取512维特征向量
- 特征向量已归一化，使用余弦相似度计算相似度
- 相似度阈值建议设置为 0.6-0.7

### 数据库设计

- 使用 SQLite 存储人脸记录
- `face_records` 表结构：
  - `id`: 主键
  - `name`: 人员姓名（可选）
  - `image_path`: 图片存储路径
  - `feature_vector`: 特征向量（JSON格式）
  - `created_at`: 创建时间
  - `updated_at`: 更新时间

### 性能优化

- 特征向量比对在数据量大时性能会下降
- 建议后续使用向量数据库（如 Milvus）提升查询性能
- 当前实现将所有特征向量加载到内存进行比对

## 模型下载

### 自动下载（推荐）

首次运行后端服务时，系统会自动下载 InsightFace 模型文件。模型文件会保存在 `storage/models/` 目录下。

**自动下载触发时机**：
- 首次调用人脸识别相关 API 时
- 模型文件不存在时

### 手动下载

如果自动下载失败或网络不稳定，可以使用提供的下载脚本手动下载：

```bash
cd backend

# 激活虚拟环境（如果使用）
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 运行模型下载脚本
python download_model.py
```

下载脚本会：
- 显示模型名称和存储路径
- 自动下载所需的模型文件
- 显示下载进度和文件大小
- 验证下载是否成功

### 模型文件说明

- **存储位置**：`storage/models/{模型名称}/`
- **默认模型**：`buffalo_l`（精度高，速度较慢）
- **可选模型**：
  - `buffalo_l`：高精度模型（推荐）
  - `buffalo_s`：快速模型（精度略低）
  - `antelopev2`：最新版本模型
- **文件大小**：约 100-200 MB
- **文件格式**：`.onnx` 文件

### 切换模型

如需使用其他模型，可以在 `.env` 文件中设置：

```env
FACE_MODEL_NAME=buffalo_s
```

或在 `backend/app/config.py` 中修改默认值。

## 常见问题

### 1. 模型下载失败

如果模型下载失败，可以尝试以下方法：

**方法一：使用下载脚本**
```bash
cd backend
python download_model.py
```

**方法二：检查网络和代理**
- 确保网络连接正常
- 如果使用代理，确保代理配置正确
- 可以尝试使用 VPN

**方法三：手动下载（高级）**
1. 访问 InsightFace 官方仓库获取模型下载链接
2. 下载模型文件到 `storage/models/{模型名称}/` 目录
3. 确保文件结构正确

**方法四：从其他环境复制**
- 如果其他环境已下载模型，可以直接复制 `storage/models/` 目录

### 2. 识别准确率低

- 确保图片清晰，人脸清晰可见
- 调整相似度阈值（`SIMILARITY_THRESHOLD`）
- 使用更高精度的模型（`buffalo_l`）

### 3. 图片上传失败

- 检查图片格式（支持 JPG、PNG）
- 检查图片大小（建议小于10MB）
- 确保上传目录有写入权限

## 开发计划

- [ ] 支持批量注册人脸
- [ ] 支持人脸库管理（分组、标签）
- [ ] 集成向量数据库提升查询性能
- [ ] 支持视频流实时人脸识别
- [ ] 添加用户认证和权限管理
- [ ] 支持GPU加速（CUDA）

## 许可证

MIT License

## 联系方式

如有问题或建议，欢迎提交 Issue 或 Pull Request。