259 lines
6.6 KiB
Markdown
259 lines
6.6 KiB
Markdown
# 人脸特征提取API - 项目总结
|
||
|
||
## ✅ 已完成功能
|
||
|
||
### 1. 核心API接口 (已实现)
|
||
|
||
#### 📌 接口1: 人脸特征提取
|
||
- **路径**: `POST /api/extract_feature`
|
||
- **输入**: 人脸图像文件
|
||
- **输出**: 1024维特征向量 + 质量评估
|
||
- **文件**: [app.py:138-197](app.py#L138-L197)
|
||
|
||
#### 📌 接口2: 特征向量对比
|
||
- **路径**: `POST /api/compare_features`
|
||
- **输入**: 两个1024维特征向量
|
||
- **输出**: 相似度分数 + 同一人判断
|
||
- **文件**: [app.py:200-244](app.py#L200-L244)
|
||
|
||
#### 📌 接口3: 图像特征对比 (组合接口)
|
||
- **路径**: `POST /api/compare_image_feature`
|
||
- **输入**: 图像 + 特征向量
|
||
- **输出**: 相似度分数 + 同一人判断
|
||
- **文件**: [app.py:247-315](app.py#L247-L315)
|
||
|
||
---
|
||
|
||
## 📁 项目文件结构
|
||
|
||
```
|
||
FaceFeatureExtractorAPI/
|
||
├── app.py # FastAPI主应用 (新增)
|
||
├── face_feature_extractor.py # 核心特征提取器
|
||
├── requirements.txt # 依赖包 (已更新)
|
||
├── README_API.md # API快速启动指南 (新增)
|
||
├── API_USAGE.md # 详细API使用文档 (新增)
|
||
├── FEATURE_DIMENSION.md # 特征维度说明 (新增)
|
||
├── examples/
|
||
│ ├── api_client_example.py # Python客户端示例 (新增)
|
||
│ └── face_recognition_example.py # 人脸识别示例
|
||
├── models/ # 模型实现
|
||
│ ├── facedetector.py
|
||
│ ├── facerecoger.py # 特征提取 (1024维)
|
||
│ ├── facelandmarks5er.py
|
||
│ ├── facealign.py
|
||
│ └── imgchecker.py
|
||
└── checkpoints/ # ONNX模型文件
|
||
└── face_recognizer.onnx # 特征提取模型 (输出1024维)
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 快速启动
|
||
|
||
### 1. 安装依赖
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
新增依赖:
|
||
- `fastapi>=0.104.0` - Web框架
|
||
- `uvicorn[standard]>=0.24.0` - ASGI服务器
|
||
- `python-multipart>=0.0.6` - 文件上传支持
|
||
|
||
### 2. 启动服务
|
||
```bash
|
||
python app.py
|
||
```
|
||
|
||
或自定义启动:
|
||
```bash
|
||
python app.py --host 0.0.0.0 --port 8000 --reload
|
||
```
|
||
|
||
### 3. 访问文档
|
||
- **交互式文档**: http://localhost:8000/docs
|
||
- **健康检查**: http://localhost:8000/health
|
||
|
||
---
|
||
|
||
## 📊 技术规格
|
||
|
||
### 模型参数
|
||
- **输入尺寸**: 248×248 (人脸对齐后)
|
||
- **特征维度**: 1024维 (固定,由模型决定)
|
||
- **归一化**: L2归一化
|
||
- **相似度算法**: 余弦相似度 (点积)
|
||
|
||
### 质量检查
|
||
- ✅ 亮度检查
|
||
- ✅ 分辨率检查
|
||
- ✅ 清晰度检查
|
||
- ✅ 姿态检查 (正面/侧面/低头/抬头)
|
||
|
||
### 判断阈值
|
||
- **默认阈值**: 0.7
|
||
- **>= 0.7**: 判断为同一人
|
||
- **< 0.7**: 判断为不同人
|
||
|
||
---
|
||
|
||
## 🎯 典型应用场景
|
||
|
||
### 1. 人脸注册系统
|
||
```python
|
||
# 提取特征并存储
|
||
feature = extract_feature(user_image)
|
||
database.save(user_id, feature)
|
||
```
|
||
|
||
### 2. 人脸验证 (1:1)
|
||
```python
|
||
# 使用接口3直接对比
|
||
result = compare_image_feature(live_image, stored_feature)
|
||
if result['is_same_person']:
|
||
grant_access()
|
||
```
|
||
|
||
### 3. 人脸识别 (1:N)
|
||
```python
|
||
# 提取特征后与数据库批量对比
|
||
query_feature = extract_feature(unknown_image)
|
||
for user_id, stored_feature in database.items():
|
||
similarity = compare_features(query_feature, stored_feature)
|
||
if similarity >= threshold:
|
||
return user_id
|
||
```
|
||
|
||
### 4. 人脸去重
|
||
```python
|
||
# 批量对比找出重复
|
||
for i, feat1 in enumerate(features):
|
||
for j, feat2 in enumerate(features[i+1:]):
|
||
if compare_features(feat1, feat2)['similarity'] >= 0.9:
|
||
mark_as_duplicate(i, j)
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 重要说明
|
||
|
||
### 特征维度 (重点)
|
||
**当前模型输出: 1024维 (不可运行时调整)**
|
||
|
||
- ❌ 无法通过配置修改 (由ONNX模型架构决定)
|
||
- ✅ 可以使用PCA等降维技术优化存储
|
||
- ✅ 可以更换其他预训练模型(如512维的ArcFace)
|
||
|
||
详见: [FEATURE_DIMENSION.md](FEATURE_DIMENSION.md)
|
||
|
||
### API设计特点
|
||
1. **接口1 + 接口2**: 灵活组合,适合复杂场景
|
||
2. **接口3**: 便捷封装,适合简单验证场景
|
||
3. **质量过滤**: 自动过滤低质量人脸
|
||
4. **错误处理**: 完善的异常捕获和错误提示
|
||
|
||
---
|
||
|
||
## 📖 文档索引
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [README_API.md](README_API.md) | 快速启动指南 |
|
||
| [API_USAGE.md](API_USAGE.md) | 详细API文档 + 完整示例 |
|
||
| [FEATURE_DIMENSION.md](FEATURE_DIMENSION.md) | 特征维度说明 |
|
||
| [examples/api_client_example.py](examples/api_client_example.py) | Python客户端完整示例 |
|
||
|
||
---
|
||
|
||
## 🧪 测试
|
||
|
||
### 使用交互式文档测试
|
||
访问 http://localhost:8000/docs 可以直接测试所有接口
|
||
|
||
### Python代码测试
|
||
```python
|
||
import requests
|
||
|
||
# 测试健康检查
|
||
resp = requests.get("http://localhost:8000/health")
|
||
print(resp.json())
|
||
|
||
# 测试特征提取
|
||
with open("face.jpg", "rb") as f:
|
||
resp = requests.post(
|
||
"http://localhost:8000/api/extract_feature",
|
||
files={"image": f}
|
||
)
|
||
print(resp.json())
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ 性能优化建议
|
||
|
||
### 后端优化
|
||
1. **GPU加速**: 安装 `onnxruntime-gpu` (如有GPU)
|
||
2. **多实例部署**: 使用Nginx负载均衡
|
||
3. **异步处理**: 大批量请求使用异步队列
|
||
4. **特征缓存**: Redis缓存已提取特征
|
||
|
||
### 存储优化
|
||
1. **降维**: PCA降到512维可节省50%存储
|
||
2. **压缩**: GZIP压缩特征JSON
|
||
3. **量化**: Float32 → Float16 (精度略有损失)
|
||
|
||
---
|
||
|
||
## 🔧 常见问题
|
||
|
||
### Q: 如何修改相似度阈值?
|
||
A: 在 [app.py:216](app.py#L216) 和 [app.py:296](app.py#L296) 修改 `threshold = 0.7`
|
||
|
||
### Q: 如何支持批量特征提取?
|
||
A: 可以添加新接口,循环调用 `extract_features()` 方法
|
||
|
||
### Q: 能否改为512维特征?
|
||
A: 需要更换模型或使用降维技术,详见 [FEATURE_DIMENSION.md](FEATURE_DIMENSION.md)
|
||
|
||
### Q: 如何提高识别准确率?
|
||
A:
|
||
1. 提高阈值 (0.75-0.85)
|
||
2. 确保输入图像质量
|
||
3. 收集更多训练数据重新训练模型
|
||
|
||
---
|
||
|
||
## 📋 下一步建议
|
||
|
||
### 可选增强功能
|
||
- [ ] 批量特征提取接口
|
||
- [ ] 特征降维接口 (PCA)
|
||
- [ ] 活体检测集成
|
||
- [ ] 人脸质量评分接口
|
||
- [ ] Websocket实时识别
|
||
- [ ] 数据库集成 (PostgreSQL/MySQL)
|
||
- [ ] 用户管理接口
|
||
- [ ] API密钥认证
|
||
|
||
### 部署建议
|
||
- [ ] Docker容器化
|
||
- [ ] Kubernetes编排
|
||
- [ ] CI/CD流水线
|
||
- [ ] 监控和日志 (Prometheus + Grafana)
|
||
|
||
---
|
||
|
||
## 📞 支持
|
||
|
||
遇到问题请查看:
|
||
1. 交互式文档: http://localhost:8000/docs
|
||
2. 详细API文档: [API_USAGE.md](API_USAGE.md)
|
||
3. 客户端示例: [examples/api_client_example.py](examples/api_client_example.py)
|
||
|
||
---
|
||
|
||
**项目状态**: ✅ 核心功能已完成,可投入使用
|
||
|
||
**最后更新**: 2025-10-17
|