Face_reg_app/FaceFeatureExtractorAPI/README_API.md

人脸特征提取API - 快速启动指南

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 启动API服务

python app.py

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

3. 访问API文档

浏览器打开: http://localhost:8000/docs

---

📋 三个核心接口

✅ 接口1: 人脸特征提取

• 路径: POST /api/extract_feature
• 功能: 上传图像,提取1024维人脸特征向量
• 输入: 人脸图像文件
• 输出: 特征向量 + 质量评估结果

✅ 接口2: 特征向量对比

• 路径: POST /api/compare_features
• 功能: 计算两个特征向量的相似度
• 输入: 两个1024维特征向量
• 输出: 相似度分数 + 是否同一人判断

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

• 路径: POST /api/compare_image_feature
• 功能: 上传图像和特征向量,自动提取并对比
• 输入: 人脸图像 + 特征向量
• 输出: 相似度分数 + 是否同一人判断

---

🔧 Python调用示例

import requests

# 接口1: 提取特征
with open("face.jpg", "rb") as f:
    response = requests.post(
        "http://localhost:8000/api/extract_feature",
        files={"image": f}
    )
    result = response.json()
    feature = result["feature"]  # 获取特征向量

# 接口2: 对比特征
response = requests.post(
    "http://localhost:8000/api/compare_features",
    json={
        "feature1": feature1,
        "feature2": feature2
    }
)
result = response.json()
print(f"相似度: {result['similarity']}")

# 接口3: 图像特征对比
import json
with open("test.jpg", "rb") as f:
    response = requests.post(
        "http://localhost:8000/api/compare_image_feature",
        files={"image": f},
        data={"feature": json.dumps(known_feature)}
    )
    result = response.json()
    print(f"是否同一人: {result['is_same_person']}")

---

📚 详细文档

• 完整API文档: API_USAGE.md
• 客户端示例: examples/api_client_example.py
• 交互式文档: http://localhost:8000/docs (启动服务后访问)

---

🎯 应用场景

1. 人脸注册: 使用接口1提取特征并存储到数据库
2. 人脸验证 (1:1): 使用接口3验证用户身份
3. 人脸识别 (1:N): 使用接口1+接口2在数据库中搜索匹配
4. 人脸去重: 使用接口2批量对比特征,找出重复人脸

---

⚙️ 启动参数

# 默认启动
python app.py

# 自定义端口
python app.py --port 8080

# 自定义地址和端口
python app.py --host 0.0.0.0 --port 8000

# 开发模式(热重载)
python app.py --reload

---

📊 相似度阈值

• 默认阈值: 0.7
• >= 0.7: 判断为同一人
• < 0.7: 判断为不同人

根据实际需求调整:

• 安全优先: 提高阈值 (0.75-0.85)
• 体验优先: 降低阈值 (0.6-0.65)

---

🛠️ 技术栈

• Web框架: FastAPI
• 深度学习: ONNX Runtime
• 图像处理: OpenCV
• 特征维度: 1024维 (固定,由模型决定)
• 相似度算法: 余弦相似度

💡 特征维度说明: 查看 FEATURE_DIMENSION.md 了解如何调整特征维度

---

📞 支持

遇到问题? 查看完整文档: API_USAGE.md