Face_reg_app/FaceFeatureExtractorAPI/API_USAGE.md

人脸特征提取API使用文档

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 启动服务

# 基础启动
python app.py

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

# 开发模式（支持热重载）
python app.py --reload

服务启动后访问:

• API服务: http://localhost:8000
• 交互式文档: http://localhost:8000/docs
• 健康检查: http://localhost:8000/health

---

API接口说明

接口1: 人脸特征提取

接口地址: POST /api/extract_feature

功能: 上传一张人脸图像,提取并返回1024维特征向量

请求参数:

• image (File): 人脸图像文件 (支持 jpg, png, jpeg 格式)

响应示例:

{
  "success": true,
  "message": "特征提取成功",
  "feature": [0.123, -0.456, 0.789, ...],  // 1024维特征向量
  "feature_dim": 1024,
  "quality_passed": true,
  "processing_time": 0.235
}

Python调用示例:

import requests

url = "http://localhost:8000/api/extract_feature"

with open("face.jpg", "rb") as f:
    files = {"image": f}
    response = requests.post(url, files=files)
    result = response.json()

if result["success"]:
    feature = result["feature"]  # 获取特征向量
    print(f"特征维度: {result['feature_dim']}")
else:
    print(f"失败: {result['message']}")

cURL示例:

curl -X POST "http://localhost:8000/api/extract_feature" \
  -F "image=@face.jpg"

---

接口2: 两个特征值对比

接口地址: POST /api/compare_features

功能: 输入两个特征向量,计算相似度并判断是否为同一人

请求体 (JSON):

{
  "feature1": [0.123, -0.456, ...],  // 1024维特征向量
  "feature2": [0.789, 0.234, ...]    // 1024维特征向量
}

响应示例:

{
  "success": true,
  "message": "对比成功",
  "similarity": 0.8523,
  "is_same_person": true,
  "threshold": 0.7
}

Python调用示例:

import requests
import json

url = "http://localhost:8000/api/compare_features"

data = {
    "feature1": feature_vector_1,  # 从接口1获取的特征
    "feature2": feature_vector_2   # 从接口1获取的特征
}

response = requests.post(url, json=data)
result = response.json()

if result["success"]:
    print(f"相似度: {result['similarity']:.4f}")
    print(f"是否同一人: {result['is_same_person']}")

cURL示例:

curl -X POST "http://localhost:8000/api/compare_features" \
  -H "Content-Type: application/json" \
  -d '{
    "feature1": [0.1, 0.2, ...],
    "feature2": [0.3, 0.4, ...]
  }'

---

接口3: 人脸图像和特征值对比 (组合接口)

接口地址: POST /api/compare_image_feature

功能: 上传一张图像和一个特征向量,自动提取图像特征后进行对比

请求参数:

• image (File): 人脸图像文件
• feature (Form): 特征向量的JSON字符串

响应示例:

{
  "success": true,
  "message": "对比成功",
  "similarity": 0.8234,
  "is_same_person": true,
  "threshold": 0.7,
  "processing_time": 0.245
}

Python调用示例:

import requests
import json

url = "http://localhost:8000/api/compare_image_feature"

# 已有的特征向量
known_feature = [0.123, -0.456, ...]  # 1024维

with open("test_face.jpg", "rb") as f:
    files = {"image": f}
    data = {"feature": json.dumps(known_feature)}
    response = requests.post(url, files=files, data=data)
    result = response.json()

if result["success"]:
    print(f"相似度: {result['similarity']:.4f}")
    print(f"是否同一人: {result['is_same_person']}")
else:
    print(f"失败: {result['message']}")

cURL示例:

curl -X POST "http://localhost:8000/api/compare_image_feature" \
  -F "image=@face.jpg" \
  -F 'feature=[0.1, 0.2, 0.3, ...]'

---

完整工作流程示例

场景: 人脸识别系统

import requests
import json

API_BASE = "http://localhost:8000"

# 步骤1: 注册用户 - 提取并存储特征
def register_user(user_id, image_path):
    """注册用户人脸"""
    url = f"{API_BASE}/api/extract_feature"

    with open(image_path, "rb") as f:
        files = {"image": f}
        response = requests.post(url, files=files)
        result = response.json()

    if result["success"]:
        # 将特征向量存储到数据库
        feature = result["feature"]
        save_to_database(user_id, feature)
        print(f"✓ 用户 {user_id} 注册成功")
        return feature
    else:
        print(f"✗ 注册失败: {result['message']}")
        return None

# 步骤2: 验证用户 - 使用组合接口
def verify_user(user_id, image_path):
    """验证用户身份"""
    # 从数据库获取已存储的特征
    stored_feature = get_from_database(user_id)

    if not stored_feature:
        print(f"✗ 用户 {user_id} 不存在")
        return False

    # 使用组合接口进行对比
    url = f"{API_BASE}/api/compare_image_feature"

    with open(image_path, "rb") as f:
        files = {"image": f}
        data = {"feature": json.dumps(stored_feature)}
        response = requests.post(url, files=files, data=data)
        result = response.json()

    if result["success"]:
        is_verified = result["is_same_person"]
        similarity = result["similarity"]
        print(f"{'✓' if is_verified else '✗'} 验证结果: {similarity:.4f}")
        return is_verified
    else:
        print(f"✗ 验证失败: {result['message']}")
        return False

# 步骤3: 1对N识别 - 在数据库中搜索最相似的人脸
def identify_user(image_path):
    """识别用户（1:N匹配）"""
    # 先提取待识别图像的特征
    url = f"{API_BASE}/api/extract_feature"

    with open(image_path, "rb") as f:
        files = {"image": f}
        response = requests.post(url, files=files)
        result = response.json()

    if not result["success"]:
        print(f"✗ 特征提取失败: {result['message']}")
        return None

    query_feature = result["feature"]

    # 与数据库中所有用户特征进行对比
    all_users = get_all_users_from_database()

    best_match = None
    best_similarity = 0.0

    for user_id, stored_feature in all_users.items():
        # 使用接口2对比特征
        url = f"{API_BASE}/api/compare_features"
        data = {
            "feature1": query_feature,
            "feature2": stored_feature
        }
        response = requests.post(url, json=data)
        result = response.json()

        if result["success"]:
            similarity = result["similarity"]
            if similarity > best_similarity:
                best_similarity = similarity
                best_match = user_id

    # 判断是否超过阈值
    if best_similarity >= 0.7:
        print(f"✓ 识别为: {best_match} (相似度: {best_similarity:.4f})")
        return best_match
    else:
        print(f"✗ 未识别到已注册用户 (最高相似度: {best_similarity:.4f})")
        return None

# 使用示例
if __name__ == "__main__":
    # 注册用户
    register_user("user001", "photos/user001.jpg")
    register_user("user002", "photos/user002.jpg")

    # 验证用户
    verify_user("user001", "photos/user001_verify.jpg")

    # 识别用户
    identify_user("photos/unknown.jpg")

---

错误处理

常见错误码

• 400: 请求参数错误 (图像无法解析、特征维度不匹配等)
• 500: 服务器内部错误 (模型加载失败、处理异常等)
• 503: 服务不可用 (健康检查失败)

错误响应示例

{
  "success": false,
  "message": "未检测到合格的人脸",
  "processing_time": 0.123
}

---

性能优化建议

1. 批量处理: 对于大量图像,建议使用异步并发请求
2. 特征缓存: 已提取的特征应缓存到数据库,避免重复计算
3. 负载均衡: 高并发场景下可部署多个实例
4. GPU加速: 如有GPU,可安装 onnxruntime-gpu 加速推理

---

相似度阈值说明

默认阈值: 0.7

• >= 0.7: 认为是同一人
• < 0.7: 认为不是同一人

可根据实际业务需求调整阈值:

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

---

技术支持

• 查看交互式API文档: http://localhost:8000/docs
• 查看示例代码: examples/api_client_example.py