6.6 KiB

Raw Blame History

人脸特征提取API - 项目总结

✅ 已完成功能

1. 核心API接口 (已实现)

📌 接口1: 人脸特征提取

路径: POST /api/extract_feature
输入: 人脸图像文件
输出: 1024维特征向量 + 质量评估
文件: app.py:138-197

📌 接口2: 特征向量对比

路径: POST /api/compare_features
输入: 两个1024维特征向量
输出: 相似度分数 + 同一人判断
文件: app.py:200-244

📌 接口3: 图像特征对比 (组合接口)

路径: POST /api/compare_image_feature
输入: 图像 + 特征向量
输出: 相似度分数 + 同一人判断
文件: app.py:247-315

📁 项目文件结构

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. 安装依赖

pip install -r requirements.txt

新增依赖:

fastapi>=0.104.0 - Web框架
uvicorn[standard]>=0.24.0 - ASGI服务器
python-multipart>=0.0.6 - 文件上传支持

2. 启动服务

python app.py

或自定义启动:

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. 人脸注册系统

# 提取特征并存储
feature = extract_feature(user_image)
database.save(user_id, feature)

2. 人脸验证 (1:1)

# 使用接口3直接对比
result = compare_image_feature(live_image, stored_feature)
if result['is_same_person']:
    grant_access()

3. 人脸识别 (1:N)

# 提取特征后与数据库批量对比
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. 人脸去重

# 批量对比找出重复
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

API设计特点

接口1 + 接口2: 灵活组合,适合复杂场景
接口3: 便捷封装,适合简单验证场景
质量过滤: 自动过滤低质量人脸
错误处理: 完善的异常捕获和错误提示

📖 文档索引

文档	说明
README_API.md	快速启动指南
API_USAGE.md	详细API文档 + 完整示例
FEATURE_DIMENSION.md	特征维度说明
examples/api_client_example.py	Python客户端完整示例

🧪 测试

使用交互式文档测试

访问 http://localhost:8000/docs 可以直接测试所有接口

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())

⚙️ 性能优化建议

后端优化

GPU加速: 安装 onnxruntime-gpu (如有GPU)
多实例部署: 使用Nginx负载均衡
异步处理: 大批量请求使用异步队列
特征缓存: Redis缓存已提取特征

存储优化

降维: PCA降到512维可节省50%存储
压缩: GZIP压缩特征JSON
量化: Float32 → Float16 (精度略有损失)

🔧 常见问题

Q: 如何修改相似度阈值?

A: 在 app.py:216 和 app.py:296 修改 threshold = 0.7

Q: 如何支持批量特征提取?

A: 可以添加新接口,循环调用 extract_features() 方法

Q: 能否改为512维特征?

A: 需要更换模型或使用降维技术,详见 FEATURE_DIMENSION.md

Q: 如何提高识别准确率?

提高阈值 (0.75-0.85)
确保输入图像质量
收集更多训练数据重新训练模型

📋 下一步建议

可选增强功能

批量特征提取接口
特征降维接口 (PCA)
活体检测集成
人脸质量评分接口
Websocket实时识别
数据库集成 (PostgreSQL/MySQL)
用户管理接口
API密钥认证

部署建议

Docker容器化
Kubernetes编排
CI/CD流水线
监控和日志 (Prometheus + Grafana)

📞 支持

遇到问题请查看:

交互式文档: http://localhost:8000/docs
详细API文档: API_USAGE.md
客户端示例: examples/api_client_example.py

项目状态: ✅ 核心功能已完成,可投入使用

最后更新: 2025-10-17

6.6 KiB Raw Blame History Unescape Escape