# DeepFace

**Repository Path**: lion_s/deep-face

## Basic Information

- **Project Name**: DeepFace
- **Description**: 人脸比对、人脸查找
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-21
- **Last Updated**: 2025-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

DeepFace 是一个专注于人脸识别与分析的开源 Python 框架，基于深度学习技术，支持人脸验证、识别、属性分析（年龄、性别、情绪等）等功能。它封装了多种经典人脸识别模型（如 VGG-Face、Google FaceNet、DeepID 等），并提供了简洁的 API，适合快速开发人脸识别相关应用。

人脸识别
1 人脸对比
2 人脸查找

### 一、DeepFace 核心功能
- **人脸验证**：判断两张人脸是否属于同一个人（1:1 匹配）。  
- **人脸识别**：从人脸数据库中找到与输入人脸最相似的对象（1:N 匹配）。  
- **属性分析**：预测人脸的年龄、性别、情绪（如开心、愤怒）、种族等属性。  
- **人脸预处理**：自动完成人脸检测、对齐、裁剪等预处理步骤（依赖 MTCNN、dlib 等工具）。  


### 二、安装步骤
DeepFace 的安装依赖于一些图像处理和深度学习库，建议使用虚拟环境（如 Anaconda）安装，避免依赖冲突。

#### 1. 基础安装
通过 pip 直接安装 DeepFace：
```bash
pip install deepface
```

#### 2. 依赖补充
DeepFace 运行可能需要以下依赖（若安装过程中提示缺失，手动安装）：
```bash
# 图像处理库
pip install opencv-python
# 人脸检测/对齐工具（MTCNN 是默认后端）
pip install mtcnn
# 可选：dlib（用于部分人脸对齐模型）
pip install dlib
# 可选：TensorFlow/PyTorch（DeepFace 支持双框架，默认用 TensorFlow）
pip install tensorflow  # 或 pip install torch
```

> 注意：首次运行时，DeepFace 会自动下载预训练模型（如 VGG-Face、FaceNet 等），若下载慢，可手动下载模型文件（官网提供链接），放入 `~/.deepface/weights/` 目录。


### 三、核心功能使用教程
#### 1. 人脸验证（1:1 匹配）
验证两张人脸图像是否属于同一个人，返回匹配概率和判断结果。

**代码示例**：
```python
from deepface import DeepFace

# 定义两张人脸图像路径
img1_path = "person1_1.jpg"  # 同一个人的第一张图
img2_path = "person1_2.jpg"  # 同一个人的第二张图
# img2_path = "person2.jpg"  # 不同人的图（用于测试不匹配情况）

# 调用验证函数
result = DeepFace.verify(
    img1_path=img1_path,
    img2_path=img2_path,
    model_name="VGG-Face",  # 可选模型：VGG-Face, Facenet, OpenFace, DeepFace等
    detector_backend="mtcnn"  # 人脸检测器：mtcnn, opencv, dlib等
)

# 输出结果
print("是否匹配：", result["verified"])  # True/False
print("匹配置信度：", result["distance"])  # 距离越小，越相似（不同模型阈值不同）
print("模型阈值：", result["threshold"])  # 判定匹配的阈值（小于该值则认为匹配）
```

> 关键参数说明：  
> - `model_name`：选择人脸识别模型（默认 VGG-Face，FaceNet 精度较高）。  
> - `detector_backend`：选择人脸检测器（MTCNN 检测精度高，适合复杂场景）。  


#### 2. 人脸识别（1:N 匹配）
从一个人脸数据库中，找到与输入人脸最相似的对象（需先构建数据库）。

**步骤 1：准备人脸数据库**  
创建一个文件夹（如 `database/`），按“人名”分文件夹存放人脸图像（每人至少 1 张）：
```
database/
├── alice/
│   ├── alice1.jpg
│   └── alice2.jpg
├── bob/
│   └── bob1.jpg
└── charlie/
    └── charlie1.jpg
```

**步骤 2：执行人脸识别**  
```python
from deepface import DeepFace

# 输入待识别的人脸图像
img_path = "unknown.jpg"

# 从数据库中匹配
result = DeepFace.find(
    img_path=img_path,
    db_path="database/",  # 数据库路径
    model_name="Facenet",  # 推荐用 Facenet 提升精度
    detector_backend="mtcnn"
)

# 输出匹配结果（按相似度排序，最相似的在前）
print("最相似的匹配：")
print(result[0][["identity", "distance"]])  # identity 是匹配到的图像路径，distance 是距离
```

> 优化建议：  
> - 数据库首次使用时会生成特征向量缓存（`database/representations_*.pkl`），后续调用会加速。  
> - 若数据库更新，需删除缓存文件重新生成。  


#### 3. 人脸属性分析
预测人脸的年龄、性别、情绪、种族等属性。

**代码示例**：
```python
from deepface import DeepFace
import cv2

# 输入人脸图像
img_path = "person.jpg"

# 分析属性
result = DeepFace.analyze(
    img_path=img_path,
    actions=["age", "gender", "emotion", "race"],  # 要分析的属性
    detector_backend="mtcnn"
)

# 输出结果（返回列表，若图像中有多个人脸，每个元素对应一张脸）
for face in result:
    print("年龄：", face["age"])
    print("性别：", face["dominant_gender"])  # 占比最高的性别
    print("情绪：", face["dominant_emotion"])  # 占比最高的情绪
    print("种族：", face["dominant_race"])  # 占比最高的种族
```

> 注意：`analyze` 函数默认会检测图像中所有人脸，若只需单张脸，可配合 `detector_backend` 筛选。


#### 4. 人脸预处理（检测与对齐）
DeepFace 内置了人脸检测和对齐功能，可单独调用获取预处理后的人脸图像。

**代码示例**：
```python
from deepface.commons import functions
import cv2

img_path = "group_photo.jpg"
detector_backend = "mtcnn"

# 检测人脸并返回坐标（x1, y1, x2, y2）和对齐后的人脸
img = cv2.imread(img_path)
faces = functions.extract_faces(
    img_path=img_path,
    detector_backend=detector_backend,
    align=True  # 是否对齐（基于双眼和鼻子坐标校正）
)

# 输出检测到的人脸数量
print(f"检测到 {len(faces)} 张人脸")

# 显示对齐后的人脸
for i, (face_img, _, _) in enumerate(faces):
    cv2.imshow(f"Face {i+1}", face_img)

cv2.waitKey(0)
cv2.destroyAllWindows()
```


### 四、高级配置与优化
1. **模型选择**：不同模型的精度和速度不同，按需选择：  
   - 高精度（适合严格场景）：`Facenet`、`ArcFace`  
   - 高速度（适合实时场景）：`OpenFace`、`DeepID`  

2. **批量处理**：对多张图像批量验证/分析，可使用 `DeepFace.batch_verify` 或循环调用提升效率。  

3. **自定义阈值**：默认阈值由模型决定，可根据业务需求调整（如降低阈值提高严格度）。  

4. **GPU 加速**：若安装了 GPU 版本的 TensorFlow/PyTorch，DeepFace 会自动使用 GPU 加速（大幅提升处理速度）。  


### 五、常见问题解决
1. **模型下载失败**：手动下载模型（从 [DeepFace 官网](https://github.com/serengil/deepface) 找到模型链接），放入 `~/.deepface/weights/`。  
2. **检测不到人脸**：换用更优的检测器（如 `mtcnn` 替代 `opencv`），或确保图像中人脸清晰、光照充足。  
3. **速度慢**：使用轻量模型（如 `OpenFace`）、启用 GPU、减少分析的属性（`actions` 参数）。  


### 六、适用场景
- 身份验证系统（如考勤、门禁）。  
- 人脸属性统计（如商场客流性别/年龄分布）。  
- 社交平台人脸标签推荐。  
- 安防监控中的人脸比对。  


通过上述步骤，你可以快速上手 DeepFace 框架，实现人脸识别与分析功能。如果需要结合实际业务场景（如实时视频流处理），可以进一步结合 OpenCV 读取视频帧，循环调用 DeepFace 的 API 实现连续处理。